Forge Community Wiki - User contributions [en-gb]

Block Entity Renderer

2022-10-08T08:30:58Z

Nexus-Dino: /* Parameters */

A <code>BlockEntityRenderer</code> or <code>BER</code> is used to render blocks in a way that cannot be represented with a static baked model (JSON, OBJ, B3D, etc.). A block entity renderer requires the block to have a <code>BlockEntity</code>.

== Creating a BER ==
To create a BER, create a class that inherits from <code>BlockEntityRenderer</code>. It takes a generic argument specifying the block's <code>BlockEntity</code> class. The generic argument is used in the BER's <code>render</code> method.

Only one BER exists for a given <code>BlockEntityType</code>. Therefore, values that are specific to a single instance in the world should be stored in the block entity being passed to the renderer rather than in the BER itself. For example, an integer that increments every frame, if stored in the BER, will increment every frame for every block entity of this type in the world.

=== <code> render </code> ===

This method is called every frame in order to render the block entity.

=== Parameters ===
* <code>blockEntity</code>: This is the instance of the block entity being rendered.
* <code>partialTick</code>: The amount of time, in fractions of a tick, that has passed since the last full tick.
* <code>poseStack</code>: A stack holding four-dimensional matrix entries offset to the current position of the block entity.
* <code>bufferSource</code>: A rendering buffer able to access a vertex consumer.
* <code>combinedLight</code>: An integer of the current light value on the block entity.
* <code>combinedOverlay</code>: An integer set to the current overlay of the block entity, usually <code>OverlayTexture#NO_OVERLAY</code> or 655,360.

==Registering a BER==
In order to register a BER, you must subscribe to the <code>EntityRenderersEvent$RegisterRenderers</code> event on the mod event bus and call <code>#registerBlockEntityRenderer</code>.

Making Entities

2022-10-06T06:02:19Z

Nexus-Dino: Fix Attributes Section

{{Under construction}}

Entities are core to the Minecraft world and make up all movable objects that do not fall under [[Making Blocks|Blocks]] or [[Block Entities]]. Entities can tick and be controlled by AI or player input. This article serves as a guide for setting up a basic entity. It does not involve setting up the rendering for an entity, which is a required step to be able to see an entity in-game without crashing. See [[Entity Renderer]] for more information on entity rendering and setup.

== Entity Type ==
Much of the identity of an entity is determined by its '''entity type'''. This contains information universal to an entity. An entity type must exist and be [[Registration|registered]] for the corresponding entity to be summonable.

=== Creating the Builder ===
The primary way to make an <code>EntityType</code> is to create and configure an <code>EntityType$Builder</code>. Creating an entity type builder is done using the static factory <code>EntityType.Builder#of</code>. It requires two parameters: an <code>EntityType.EntityFactory</code> and a <code>MobCategory</code>.
The entity factory is usually an entity class with a constructor taking its own <code>EntityType</code> and <code>Level</code> of the form <code>MyEntity::new</code>. This requires a class of the name <code>MyEntity</code> to actually exist (see [[#Entity Class|the entity class section]] for more info).
The mob category is an enum describing mostly spawning properties about a category of mobs. This includes:
<ul>
<li>How many entities in a given mob category can spawn per chunk</li>
<li>Whether the entity is friendly (and therefore will spawn in peaceful difficulty)</li>
<li>Whether the entity is persistent (and therefore will save to disk and be reloaded)</li>
<li>How many blocks away a player must be for an entity in a given mob category to despawn</li>
</ul>

=== Configuring the Builder ===
An entity type builder by itself is not very useful. It must be configured to match the desired properties of the entity.
The possible properties that can be configured are listed below:
{| class="wikitable" border=1
! Method !! Default Value !! Description
|-
| <code><nowiki>sized</nowiki></code> || 0.6 meters wide by 1.8 meters tall (player dimensions) || Sets the default pose dimensions of the entity in order of square base width then height in meters/blocks. A value of 1.0 would be equivalent to the length of 1 full block. The base cannot be configured with a separate width and length.
|-
| <code><nowiki>noSummon</nowiki></code> || Can summon || Calling this prevents spawning the entity through <code>/summon</code>; intended for internal entities that a user should not be able to create. This also prevents summoning through natural spawning in biomes, if it is configured.
|-
| <code><nowiki>noSave</nowiki></code> || Can save || Calling this prevents the entity from ever saving to disk. Unloading a chunk with a <code>noSave</code> entity will effectively delete the entity.
|-
| <code><nowiki>fireImmune</nowiki></code> || Vulnerable to fire || Calling this prevents the entity from taking any fire/lava damage.
|-
| <code><nowiki>clientTrackingRange</nowiki></code> || 5 chunks || Sets the maximum range in chunks in which players should be sent update packet information about the entity. Sending update information about an entity to a player is known as the player ''tracking'' that entity. If the player is outside this chunk range, they will not know of the entity's existence.
|-
| <code><nowiki>immuneTo</nowiki></code> || Empty set of blocks || Effectively useless for modding purposes.
|-
| <code><nowiki>canSpawnFarFromPlayer</nowiki></code> || True for <code>MobCategory.CREATURE</code> and <code>MobCategory.MISC</code>, false otherwise. || Calling this allows an entity to spawn outside of the despawn distance of its mob category.
|-
| <code><nowiki>updateInterval</nowiki></code> || 3 ticks || How often, in ticks, update packets should be sent to all client players tracking this entity (see <code>clientTrackingRange</code>). The update packets contain information like position, rotation, and velocity. They may be sent more quickly than this interval during specific actions.
|-
| <code><nowiki>setShouldReceiveVelocityUpdates</nowiki></code> || true || Sets whether tracking client players should receive velocity information in update interval packets. If false, velocity information will not be sent to clients unless necessary.
|}

=== Building the Builder ===
After creating and configuring the entity type builder, it must be built. This requires the modid and name of the entity type. For an entity type with the name "example_monster" in the mod "examplemod", this would look like <code>builder.build("examplemod:example_monster")</code>.

=== Tying It Together ===
Given the above information, a basic EntityType might look like the following:
{{Tabs/Code Snippets
|java=EntityType.Builder.of(ExampleMonsterEntity::new, MobCategory.MONSTER)
.sized(1.0F, 2.0F)
.fireImmune()
.updateInterval(1)
.build("examplemod:example_monster")
}}
To function, this example requires that an entity class of the name <code>ExampleMonsterEntity</code> exist along with the entity type being [[Registration|registered]].

== Entity Class ==
Alongside an entity type, an entity requires a class outlining its behavior and any information that may change from one instance to another. All entities must extend from the base class <code>Entity</code>. However, some entities should extend from specific subclasses instead. For a completely generic entity, use <code>Entity</code>. For a living entity with health, potion effects, and an inventory, use <code>LivingEntity</code>. For a living entity with movement AI and AI goals, use <code>Mob</code>. There are also many other entity subclasses which can be found through your IDE and picked depending on the scenario.

Once picking a target superclass to extend, an entity class should be created and the constructor should be setup. It should look something like this:
{{Tabs/Code Snippets|
java=public class ExampleMonsterEntity extends Mob {
public ExampleMonsterEntity(EntityType<? extends Mob> entityType, Level level) {
super(entityType, level);
}
}
}}

To define custom behavior, methods must be overriden. Your IDE should have a feature to list all possible methods to override, although some common ones might be: <code>customServerAiStep</code> for server AI, <code>tick</code> for code to execute each tick on client/server, and <code>registerGoals</code> to setup AI goals.

== Entity Attributes ==
Since 1.17 and later versions, you **MUST** define attributes if your entity class extends <code>LivingEntity</code> or any other class that inherits from it. In Attributes, you can define:

* Max Health
* Movement Speed
* Attack Damage

and more...

In your Entity class, create a static method that creates your attributes:
<syntaxhighlight lang="java">
public static AttributeSupplier.Builder createAttributes()
{
return createHostileAttributes().add(Attributes.MAX_HEALTH, 40.0F).add(Attributes.ATTACK_DAMAGE, 10.0F);
}
</syntaxhighlight>

== Natural Spawning ==
To make entities naturally spawn, they must be added to the spawn list for each biome that the entity should spawn in. This can be achieved with a [[Biome Modifiers#Add Spawns|<code>forge:add_spawns</code> biome modifier]].

Making Entities

2022-10-06T05:58:11Z

Nexus-Dino: Add Entity Attributes Section

{{Under construction}}

Entities are core to the Minecraft world and make up all movable objects that do not fall under [[Making Blocks|Blocks]] or [[Block Entities]]. Entities can tick and be controlled by AI or player input. This article serves as a guide for setting up a basic entity. It does not involve setting up the rendering for an entity, which is a required step to be able to see an entity in-game without crashing. See [[Entity Renderer]] for more information on entity rendering and setup.

== Entity Type ==
Much of the identity of an entity is determined by its '''entity type'''. This contains information universal to an entity. An entity type must exist and be [[Registration|registered]] for the corresponding entity to be summonable.

=== Creating the Builder ===
The primary way to make an <code>EntityType</code> is to create and configure an <code>EntityType$Builder</code>. Creating an entity type builder is done using the static factory <code>EntityType.Builder#of</code>. It requires two parameters: an <code>EntityType.EntityFactory</code> and a <code>MobCategory</code>.
The entity factory is usually an entity class with a constructor taking its own <code>EntityType</code> and <code>Level</code> of the form <code>MyEntity::new</code>. This requires a class of the name <code>MyEntity</code> to actually exist (see [[#Entity Class|the entity class section]] for more info).
The mob category is an enum describing mostly spawning properties about a category of mobs. This includes:
<ul>
<li>How many entities in a given mob category can spawn per chunk</li>
<li>Whether the entity is friendly (and therefore will spawn in peaceful difficulty)</li>
<li>Whether the entity is persistent (and therefore will save to disk and be reloaded)</li>
<li>How many blocks away a player must be for an entity in a given mob category to despawn</li>
</ul>

=== Configuring the Builder ===
An entity type builder by itself is not very useful. It must be configured to match the desired properties of the entity.
The possible properties that can be configured are listed below:
{| class="wikitable" border=1
! Method !! Default Value !! Description
|-
| <code><nowiki>sized</nowiki></code> || 0.6 meters wide by 1.8 meters tall (player dimensions) || Sets the default pose dimensions of the entity in order of square base width then height in meters/blocks. A value of 1.0 would be equivalent to the length of 1 full block. The base cannot be configured with a separate width and length.
|-
| <code><nowiki>noSummon</nowiki></code> || Can summon || Calling this prevents spawning the entity through <code>/summon</code>; intended for internal entities that a user should not be able to create. This also prevents summoning through natural spawning in biomes, if it is configured.
|-
| <code><nowiki>noSave</nowiki></code> || Can save || Calling this prevents the entity from ever saving to disk. Unloading a chunk with a <code>noSave</code> entity will effectively delete the entity.
|-
| <code><nowiki>fireImmune</nowiki></code> || Vulnerable to fire || Calling this prevents the entity from taking any fire/lava damage.
|-
| <code><nowiki>clientTrackingRange</nowiki></code> || 5 chunks || Sets the maximum range in chunks in which players should be sent update packet information about the entity. Sending update information about an entity to a player is known as the player ''tracking'' that entity. If the player is outside this chunk range, they will not know of the entity's existence.
|-
| <code><nowiki>immuneTo</nowiki></code> || Empty set of blocks || Effectively useless for modding purposes.
|-
| <code><nowiki>canSpawnFarFromPlayer</nowiki></code> || True for <code>MobCategory.CREATURE</code> and <code>MobCategory.MISC</code>, false otherwise. || Calling this allows an entity to spawn outside of the despawn distance of its mob category.
|-
| <code><nowiki>updateInterval</nowiki></code> || 3 ticks || How often, in ticks, update packets should be sent to all client players tracking this entity (see <code>clientTrackingRange</code>). The update packets contain information like position, rotation, and velocity. They may be sent more quickly than this interval during specific actions.
|-
| <code><nowiki>setShouldReceiveVelocityUpdates</nowiki></code> || true || Sets whether tracking client players should receive velocity information in update interval packets. If false, velocity information will not be sent to clients unless necessary.
|}

=== Building the Builder ===
After creating and configuring the entity type builder, it must be built. This requires the modid and name of the entity type. For an entity type with the name "example_monster" in the mod "examplemod", this would look like <code>builder.build("examplemod:example_monster")</code>.

=== Tying It Together ===
Given the above information, a basic EntityType might look like the following:
{{Tabs/Code Snippets
|java=EntityType.Builder.of(ExampleMonsterEntity::new, MobCategory.MONSTER)
.sized(1.0F, 2.0F)
.fireImmune()
.updateInterval(1)
.build("examplemod:example_monster")
}}
To function, this example requires that an entity class of the name <code>ExampleMonsterEntity</code> exist along with the entity type being [[Registration|registered]].

== Entity Class ==
Alongside an entity type, an entity requires a class outlining its behavior and any information that may change from one instance to another. All entities must extend from the base class <code>Entity</code>. However, some entities should extend from specific subclasses instead. For a completely generic entity, use <code>Entity</code>. For a living entity with health, potion effects, and an inventory, use <code>LivingEntity</code>. For a living entity with movement AI and AI goals, use <code>Mob</code>. There are also many other entity subclasses which can be found through your IDE and picked depending on the scenario.

Once picking a target superclass to extend, an entity class should be created and the constructor should be setup. It should look something like this:
{{Tabs/Code Snippets|
java=public class ExampleMonsterEntity extends Mob {
public ExampleMonsterEntity(EntityType<? extends Mob> entityType, Level level) {
super(entityType, level);
}
}
}}

To define custom behavior, methods must be overriden. Your IDE should have a feature to list all possible methods to override, although some common ones might be: <code>customServerAiStep</code> for server AI, <code>tick</code> for code to execute each tick on client/server, and <code>registerGoals</code> to setup AI goals.

== Entity Attributes ==
Since 1.17 and later versions, you **MUST** define attributes if your entity class extends <code>LivingEntity</code> or any other class that inherits from it. In Attributes, you can define:

* Max Health
* Movement Speed
* Attack Damage

and more...

In your Entity class, create a static method that creates your attributes:
<code>
// In your Entity class...

public static AttributeSupplier.Builder setAttributes()
{
return createHostileAttributes().add(Attributes.MAX_HEALTH);
}
</code>

== Natural Spawning ==
To make entities naturally spawn, they must be added to the spawn list for each biome that the entity should spawn in. This can be achieved with a [[Biome Modifiers#Add Spawns|<code>forge:add_spawns</code> biome modifier]].

Making Entities

2022-10-06T05:40:38Z

Nexus-Dino: /* Tying It Together */

{{Under construction}}

Entities are core to the Minecraft world and make up all movable objects that do not fall under [[Making Blocks|Blocks]] or [[Block Entities]]. Entities can tick and be controlled by AI or player input. This article serves as a guide for setting up a basic entity. It does not involve setting up the rendering for an entity, which is a required step to be able to see an entity in-game without crashing. See [[Entity Renderer]] for more information on entity rendering and setup.

== Entity Type ==
Much of the identity of an entity is determined by its '''entity type'''. This contains information universal to an entity. An entity type must exist and be [[Registration|registered]] for the corresponding entity to be summonable.

=== Creating the Builder ===
The primary way to make an <code>EntityType</code> is to create and configure an <code>EntityType$Builder</code>. Creating an entity type builder is done using the static factory <code>EntityType.Builder#of</code>. It requires two parameters: an <code>EntityType.EntityFactory</code> and a <code>MobCategory</code>.
The entity factory is usually an entity class with a constructor taking its own <code>EntityType</code> and <code>Level</code> of the form <code>MyEntity::new</code>. This requires a class of the name <code>MyEntity</code> to actually exist (see [[#Entity Class|the entity class section]] for more info).
The mob category is an enum describing mostly spawning properties about a category of mobs. This includes:
<ul>
<li>How many entities in a given mob category can spawn per chunk</li>
<li>Whether the entity is friendly (and therefore will spawn in peaceful difficulty)</li>
<li>Whether the entity is persistent (and therefore will save to disk and be reloaded)</li>
<li>How many blocks away a player must be for an entity in a given mob category to despawn</li>
</ul>

=== Configuring the Builder ===
An entity type builder by itself is not very useful. It must be configured to match the desired properties of the entity.
The possible properties that can be configured are listed below:
{| class="wikitable" border=1
! Method !! Default Value !! Description
|-
| <code><nowiki>sized</nowiki></code> || 0.6 meters wide by 1.8 meters tall (player dimensions) || Sets the default pose dimensions of the entity in order of square base width then height in meters/blocks. A value of 1.0 would be equivalent to the length of 1 full block. The base cannot be configured with a separate width and length.
|-
| <code><nowiki>noSummon</nowiki></code> || Can summon || Calling this prevents spawning the entity through <code>/summon</code>; intended for internal entities that a user should not be able to create. This also prevents summoning through natural spawning in biomes, if it is configured.
|-
| <code><nowiki>noSave</nowiki></code> || Can save || Calling this prevents the entity from ever saving to disk. Unloading a chunk with a <code>noSave</code> entity will effectively delete the entity.
|-
| <code><nowiki>fireImmune</nowiki></code> || Vulnerable to fire || Calling this prevents the entity from taking any fire/lava damage.
|-
| <code><nowiki>clientTrackingRange</nowiki></code> || 5 chunks || Sets the maximum range in chunks in which players should be sent update packet information about the entity. Sending update information about an entity to a player is known as the player ''tracking'' that entity. If the player is outside this chunk range, they will not know of the entity's existence.
|-
| <code><nowiki>immuneTo</nowiki></code> || Empty set of blocks || Effectively useless for modding purposes.
|-
| <code><nowiki>canSpawnFarFromPlayer</nowiki></code> || True for <code>MobCategory.CREATURE</code> and <code>MobCategory.MISC</code>, false otherwise. || Calling this allows an entity to spawn outside of the despawn distance of its mob category.
|-
| <code><nowiki>updateInterval</nowiki></code> || 3 ticks || How often, in ticks, update packets should be sent to all client players tracking this entity (see <code>clientTrackingRange</code>). The update packets contain information like position, rotation, and velocity. They may be sent more quickly than this interval during specific actions.
|-
| <code><nowiki>setShouldReceiveVelocityUpdates</nowiki></code> || true || Sets whether tracking client players should receive velocity information in update interval packets. If false, velocity information will not be sent to clients unless necessary.
|}

=== Building the Builder ===
After creating and configuring the entity type builder, it must be built. This requires the modid and name of the entity type. For an entity type with the name "example_monster" in the mod "examplemod", this would look like <code>builder.build("examplemod:example_monster")</code>.

===Tying It Together===
Given the above information, a basic EntityType might look like the following:{{Tabs/Code Snippets
|java=EntityType.Builder.of(ExampleMonsterEntity::new, MobCategory.MONSTER)
.sized(1.0F, 2.0F)
.fireImmune()
.updateInterval(1)
.build("examplemod:example_monster")
}}To function, this example requires that an entity class of the name <code>ExampleMonsterEntity</code> exist along with the entity type being [[Registration|registered]].

== Entity Class ==
Alongside an entity type, an entity requires a class outlining its behavior and any information that may change from one instance to another. All entities must extend from the base class <code>Entity</code>. However, some entities should extend from specific subclasses instead. For a completely generic entity, use <code>Entity</code>. For a living entity with health, potion effects, and an inventory, use <code>LivingEntity</code>. For a living entity with movement AI and AI goals, use <code>Mob</code>. There are also many other entity subclasses which can be found through your IDE and picked depending on the scenario.

Once picking a target superclass to extend, an entity class should be created and the constructor should be setup. It should look something like this:
{{Tabs/Code Snippets|
java=public class ExampleMonsterEntity extends Mob {
public ExampleMonsterEntity(EntityType<? extends Mob> entityType, Level level) {
super(entityType, level);
}
}
}}

To define custom behavior, methods must be overriden. Your IDE should have a feature to list all possible methods to override, although some common ones might be: <code>customServerAiStep</code> for server AI, <code>tick</code> for code to execute each tick on client/server, and <code>registerGoals</code> to setup AI goals.

== Natural Spawning ==
To make entities naturally spawn, they must be added to the spawn list for each biome that the entity should spawn in. This can be achieved with a [[Biome Modifiers#Add Spawns|<code>forge:add_spawns</code> biome modifier]].

Model JSONs

2022-09-24T18:20:45Z

Nexus-Dino: Update Wiki according to recent client refactors

A “model” is simply a shape. It can be a simple cube, it can be several cubes, it can be a truncated icosidodecahedron, or anything in between. Most models you’ll see will be in the vanilla JSON format. Models in other formats are loaded into an <code>IUnbakedGeometry</code> by an <code>IGeometryLoader</code> at runtime. Forge provides default implementations for WaveFront OBJ files, buckets, composite models, models in different render layers, and a reimplementation of Vanilla's <code>builtin/generated</code> item model. Most things do not care about what loaded the model or what format it’s in as they all "bake" into an <code>BakedModel</code>.

When <code>ResourceLocation</code> refers to a model, the path is normally relative to <code>models</code> (e.g. <code><nowiki>examplemod:block/block</nowiki></code> → <code><nowiki>assets/examplemod/models/block/block</nowiki></code>).

Block and item models differ in a few ways, the major one being [[Item Overrides|item property overrides]].

== Textures ==
Textures, like models, are contained within resource packs and are referred to with <code>ResourceLocation</code>s. When <code>ResourceLocation</code>s refer to textures in models, the paths are taken to be relative to <code><nowiki>textures/</nowiki></code> (e.g. <code><nowiki>examplemod:blocks/test</nowiki></code> → <code><nowiki>assets/examplemod/textures/blocks/test.png</nowiki></code>). Additionally, in Minecraft, the [https://en.wikipedia.org/wiki/UV_mapping UV coordinates] (0,0) are taken to mean the ''<code>top-left</code>'' corner. UVs are <code>always</code> from 0 to 16. If a texture is larger or smaller, the coordinates are scaled to fit. A texture should also be square, and the side length of a texture should be a power of two, as doing otherwise breaks mipmapping. (E.g. 1x1, 2x2, 8x8, 16x16, and 128x128 are good. 5x5 and 30x30 are not recommended because they are not powers of 2. 5x10 and 4x8 are completely broken as they are not square.) If there is an <code>mcmeta</code> file associated with the texture, and an animation is defined, the image can be rectangular and is interpreted as a vertical sequence of square regions from top to bottom, where each square is a frame of the animation.

== JSON Models ==
Vanilla Minecraft’s JSON model format is rather simple. It defines cuboid (cube/rectangular prism) elements, and assigns textures to their faces. On the [https://minecraft.fandom.com/wiki/Model#Block_models wiki], there is a definition of its format.

{{Colored box|title=Tip|content=JSON models only support cuboid elements; there is no way to express a triangular wedge or anything like it. To have more complicated models, another format must be used.}}

When a <code>ResourceLocation</code> refers to the location of a JSON model, it is not suffixed with <code><nowiki>.json</nowiki></code>, unlike OBJ (e.g. <code><nowiki>minecraft:block/cube_all</nowiki></code>, not <code><nowiki>minecraft:block/cube_all.json</nowiki></code>).

== WaveFront OBJ Models ==
Forge adds a loader for the <code>.obj</code> file format. To use these models, the JSON must reference the <code>forge:obj</code> loader. This loader accepts any model location that is in a registered namespace and whose path ends in <code>.obj</code>. The <code>.mtl</code> file should be placed in the same location with the same name as the <code>.obj</code> to be used automatically. The <code>.mtl</code> file will probably have to be manually edited to change the paths pointing to textures defined within the JSON. Additionally, the V axis for textures may be flipped depending on the external program that created the model (i.e. V = 0 may be the bottom edge, not the top). This may be rectified in the modelling program itself or done in the model JSON like so:

<syntaxhighlight lang="json">
{
"__comment": "Add the following line on the same level as a 'model' declaration.",
"loader": "forge:obj",
"flip-v": true,
"model": "examplemod:models/block/model.obj",
"textures": {
"_comment": "Can refer to in .mtl using #texture0",
"texture0": "minecraft:block/dirt",
"particle": "minecraft:block/dirt"
}
}
</syntaxhighlight>

[[Category:Models]]

Capabilities

2022-09-24T18:07:56Z

Nexus-Dino:

'''Capabilities''' are a Forge system that allows cross-mod interactions by allowing capability ''providers'' to
dynamically respect contracts and provide specialized behavior without requiring the implementation of many interfaces
or hard dependencies on mods.

== History ==
In an ideal world, all that would be needed for a mod to provide the equivalent of a capability would be implementing an
interface. This is in fact how cross-mod interaction used to work prior to the introduction of capabilities.

The real world, though, is often much more complicated: users wanted to be free to combine mods the way they wanted and
saw fit, and developers wanted to be able to declare ''soft'' dependencies on other mods, thus reducing the need of
having a huge mod pack just for testing.

The first approach used by Forge was conditional stripping of interfaces and methods, but this proved to be problematic.
While the idea works well in theory, in practice the ASM editing of classes relied on complex mechanics and could lead
to hard to spot bugs.

For this reason, the entire system was redesigned and the concept of '''capabilities''' was born.

== The Concept ==
A capability allows any capability provider to conditionally expose a certain ability to do something, e.g. accepting
power or handling items. A capability provider, moreover, can decide to expose a capability only on certain sides,
allowing for easy interactions with hoppers, cables, etc.

Capabilities may also be added and removed dynamically both from the "owner" of the capability provider and other mods,
allowing even easier cross-mod interaction. For example, a mod that isn't compatible with Forge Energy could be
converted into one by dynamically attaching the Forge Energy capability and handling the conversion to a third-party
energy system without having to alter the original mod.

== Terminology ==
The high flexibility of the system comes with a cost, though, which is terminology. The following section wants to be a
dictionary of sorts, defining all the terms that you may come across when dealing with capabilities.

In the rest of this article, we will refer to these terms frequently, so make sure you are familiar with them.

; Capability
: the ability to perform something. In-code this is represented by the <code>Capability</code> class.
; Capability Provider
: something that is able to support capabilities and provides a mean of accessing them. In-code they are represented by implementations of <code>ICapabilityProvider</code>. There are multiple kinds of capability providers:
:; Volatile Provider
:: a provider that doesn't persist data to disk; once the provider ceases to exist for any number of reasons, all capability data gets deleted.
:; Persistent Provider
:: a provider that requires all capabilities to serialize data to disk, in order to persist data even across game restarts. They implement the <code>INBTSerializable</code> interface.
:; Agnostic Provider
:: a provider that isn't neither volatile nor persistent, rather delegates the decision either to the capability directly or to sub-implementations. They also implement the <code>INBTSerializable</code> interface.
; Capability Interface
: the interface that defines the contract of the capability, so what operations the capability exposes.
; Capability Implementation
: one of the possibly many implementations of the capability interface, that actually carries out the work.

The wary reader may note that both ''persistent'' and ''agnostic'' providers are represented the same way in code. In
fact, the only difference between them comes from pure semantics in how their serialization methods are designed. This
will be further discussed in their respective sections.

Moreover, it is also common to refer to the capability interface as simply the ''capability''. While not strictly
correct, due to common usage we will also use this convention. So, to refer to the capability interface
<code>MyCapability</code>, we will usually talk about the "<code>MyCapability</code> capability".

== Forge-provided Capabilities and Providers ==
In order to ensure mods can work together seamlessly, Forge provides a set of default capabilities and capability
providers.

The default capability providers in a Forge environment are: <code>BlockEntity</code>, <code>Entity</code>,
<code>ItemStack</code>, <code>Level</code>, and <code>LevelChunk</code>. These are all agnostic providers, since they don't
mandate any sort of capability persistency requirements. Rather, it is the job of whoever subclasses these providers to
deal with either volatile or non-volatile capabilities.

The default capabilities that forge provides are represented by the interfaces <code>IItemHandler</code>,
<code>IFluidHandler</code>, <code>IFluidHandlerItem</code>, and <code>IEnergyStorage</code>. Each one of these capabilities will be discussed in the corresponding section.

=== <tt>IItemHandler</tt> ===

The <code>IItemHandler</code> capability refers to the ability for any capability provider to have some sort of internal
'''inventory''' with a certain number of slots, from which items can be inserted and extracted. It is also possible,
though, to expose this capability even if no such inventory is present as long as the capability provider can emulate
its presence (e.g. tools that allow accessing remote inventories).

This effectively '''replaces''' the vanilla interfaces <code>Container</code> and <code>WorldlyContainer</code>. These
interfaces are in fact retained only to allow vanilla code to compile and should not be used in mod code. This extends
to anything that implements those vanilla interfaces, such as <code>RandomizableContainerBlockEntity</code>.

A default reference implementation for this capability interface is provided in <code>ItemStackHandler</code>.

=== <tt>IFluidHandler</tt> ===

The <code>IFluidHandler</code> capability refers to the ability for any capability provider to handle and store fluids
in one or multiple fluid tanks. It is effectively the equivalent in terms of fluids of the <code>IItemHandler</code>
capability.

A default reference implementation for this capability interface is provided in <code>TileFluidHandler</code>.

=== <tt>IFluidHandlerItem</tt> ===

The <code>IFluidHandlerItem</code> capability refers to the ability for an <code>ItemStack</code> capability provider
to handle and store fluids in one or multiple fluid tanks. It is basically a specialized version of the
<code>IFluidHandler</code> capability that allows <code>ItemStack</code>s to define a custom container.

=== <tt>IEnergyStorage</tt> ===

The <code>IEnergyStorage</code> capability refers to the ability for any capability provider to store, consume, and
produce energy. This capability is the base capability for what's commonly known in the modded world as Forge Energy (or
FE), i.e. the energy system most mods use. Its internal design is heavily based on the (now defunct) Redstone Flux
Energy API, supporting both a push and pull system.

A default reference implementation for this capability interface is provided in <code>EnergyStorage</code>.

== Working with Capabilities ==

Both capability providers and users need to be able to provide and access capabilities through a common framework,
otherwise the ideal of dynamic and mod-agnostic would not really exist. For this reason, both capability providers and
capability ''accessors'' (which we define as everything that wants to access a capability), also known as '''clients''' or '''users''',
need to work together and with Forge to ensure that the common interface is used sensibly and correctly by all parties.

=== Obtaining a Capability ===

Before being able to work with a capability, it is necessary to obtain an instance of the <code>Capability</code> object itself.

A <code>Capability</code> can obtained at any time using <code>CapabilityManager#get</code>. This takes in an anonymous <code>CapabilityToken</code> to still allow for a soft dependency system while also keeping hold of any generic information needed. As such, you can always obtain a non-null capability.

<syntaxhighlight lang="java">
public static Capability<IItemHandler> ITEM_HANDLER = CapabilityManager.get(new CapabilityToken<>(){});
</syntaxhighlight>

The above code will let Forge know that the field <code>ITEM_HANDLER</code> should be analogous with the <code>IItemHandler</code> capability. Note that this does not mean the capability is accessible or registered. To check if it is, call <code>Capability#isRegistered</code>.

This is, for obvious reasons, redundant, since all capabilities are available through
<code>ForgeCapabilities</code>.

=== Exposing a Capability ===

Exposing a capability is a voluntary act by a capability provider that allows the capability to be discovered and
accessed by users.

To do so, a capability provider needs to juggle a couple more moving pieces to ensure that the capability state remains
consistent and that the lookup remains fast. It is in fact possible for a capability provider to be asked to provide
many capabilities many times in the same tick. For this reason, a provider is asked to do the following:

* the <code>LazyOptional</code>s that get returned '''must be cached''';
* if a capability changes exposure state (more on this later), all listeners '''must be notified''';
* if a capability gets invalidated (more on this later), all listeners '''must be notified'''
* the lookup inside <code>getCapability</code> must be performed with '''an <code>if</code>-<code>else</code> chain''';
* all unexposed but still present capabilities '''should be available''' if the provider is queried with a <code>null</code> direction (see ''Accessing a Capability'' for more information);
* if no capability of a given type is available or accessible, the provider '''must call <code>super</code> as long as it is possible to do so'''.

Capability providers must also reflect changes in the ''exposure state'' of a capability, meaning that if the
accessibility of a capability from a certain <code>Direction</code> changes (refer to
[[#Accessing a Capability|Accessing a Capability]] for more information), it is the provider's responsibility to trigger
a state response by invalidating the returned <code>LazyOptional</code> and caching a new one. This should also be
performed when a capability gets ''invalidated'', such as when a capability provider gets removed.

With all of the above in mind, part of a capability provider implementation may be similar to the following snippet:

<syntaxhighlight lang="java">
// suppose the presence of a field 'inventory' of type 'IItemHandler'

private LazyOptional<IItemhandler> inventoryOptional = LazyOptional.empty();

@Override
public <T> LazyOptional<T> getCapability(Capability<T> capability, @Nullable Direction direction) {
if (capability == ForgeCapabilities.ITEM_HANDLER
&& (direction == null || direction == Direction.UP || direction == Direction.DOWN)) {
return this.inventoryOptional.cast();
}
return super.getCapability(capability, direction); // See note after snippet
}

@Override
public void invalidateCaps()
{
this.inventoryOptional = LazyOptional.of(() -> this.inventory);
}

@Override
protected void invalidateCaps() {
super.invalidateCaps();
this.inventoryOptional.invalidate();
}
</syntaxhighlight>

This possible implementation of a capability provider exposes an <code>IItemHandler</code> capability and restricts
access only to the <code>UP</code> and <code>DOWN</code> directions. If we assume this capability provider is a
<code>BlockEntity</code>, then we may also say that the inventory is only accessible from the top and the bottom of the
block.

Moreover, the capability gets automatically invalidated when the provider gets invalidated. Assuming this is a
<code>BlockEntity</code>, this usually happens when the block gets removed from the level or unloaded due to distance.

The <code>super</code> call at the end of the <code>getCapability</code> method is extremely important, since it's what
allows Attaching external Capabilities to capability providers. Nevertheless, it is not always possible to invoke
<code>super</code>: in those cases, an empty <code>LazyOptional</code> should be returned.

=== Attaching a Capability ===

Attaching a Capability is a process by which external agents "modify" a Capability Provider, making it expose additional
capabilities other than the already available ones.

To do so, the '''attaching agent''' (which means the thing that wants to attach a capability to another provider) must
listen to the <code>AttachCapabilitiesEvent<T></code>. The <code>T</code> in this case represents the capability
provider you want to attach the capability to. Note that the type of <code>T</code> '''must''' be the base type of the
capability provider, not a subclass. As an example, if you want to attach a capability to a <code>MyBlockEntity</code>,
which extends <code>BlockEntity</code>, you'll have to listen to <code>AttachCapabilitiesEvent<BlockEntity></code>,
'''NOT''' to <code>AttachCapabilitiesEvent<MyBlockEntity></code>, since the latter will never fire.

The attaching agent can use the provided methods <code>getObject</code>, <code>addCapability</code>, and
<code>addListener</code> to check whether the capability should be attached to the current object and perform the
desired action.

When attaching a capability, the attaching agent should also provide a name in the form of a
<code>ResourceLocation</code>. The name '''must''' be under the attaching agent's namespace, but no restrictions are
placed on the actual name, as long as it is unique inside the given namespace.

Maybe a little counter-intuitively, the process of attaching does not attach a capability nor a capability interface
directly. Rather, the attaching agent should create its own implementation of a '''Capability Provider''' and attach it
via the event. This is done so that the attaching agent can have control over when, how, and where its capabilities are
exposed, instead of relying on the game itself deciding these parameters. For this reason, all considerations given in
the [[#Exposing a Capability|Exposing a Capability]] section on how to correctly create a Capability Provider.

With the above in mind, part of an attaching agent may be similar to the following snippet of code:

<syntaxhighlight lang="java">
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

EnergyStorage backend = new EnergyStorage(((EnergyBasedBlockEntity) event.getObject()).capacity);
LazyOptional<IEnergyStorage> optionalStorage = LazyOptional.of(() -> backend);

ICapabilityProvider provider = new ICapabilityProvider() {
@Override
public <T> LazyOptional<T> getCapability(Capability<T> cap, @Nullable Direction direction) {
if (cap == ForgeCapabilities.ENERGY) {
return optionalStorage.cast();
}
return LazyOptional.empty();
}
};

event.addCapability(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
</syntaxhighlight>

This example implementation of an attaching agent attaches a <code>IEnergyStorage</code> capability to all
<code>BlockEntity</code> instance that are a subclass of <code>EnergyBasedBlockEntity</code>. It also sets up the
<code>LazyOptional</code> for invalidation if the parent capability provider gets invalidated.

Note also the call of <code>LazyOptional.empty()</code> rather than a <code>super</code>. This is needed because when
attaching a capability, the parent capability provider isn't known. For this reason, it is necessary to return an empty
<code>LazyOptional</code>. The game will then handle automatic merging of the various different providers into a single
one.

The above example is one of a '''Volatile''' Capability Provider. On the other hand, mods may want to persist their
data across sessions. In this case, they should attach a '''Persistent''' Capability Provider: this can be done either
by implementing the <code>INBTSerializable</code> interface along with <code>ICapabilityProvider</code> or by
implementing the <code>ICapabilitySerializable</code> interface.

The previous example reworked to use a Persistent Capability Provider may be similar to the following snippet:

<syntaxhighlight lang="java">
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

EnergyStorage backend = new EnergyStorage(((EnergyBasedBlockEntity) event.getObject()).capacity);
LazyOptional<IEnergyStorage> optionalStorage = LazyOptional.of(() -> backend);
Capability<IEnergyStorage> capability = ForgeCapabilities.ENERGY;

ICapabilityProvider provider = new ICapabilitySerializable<IntTag>() {
@Override
public <T> LazyOptional<T> getCapability(Capability<T> cap, @Nullable Direction direction) {
if (cap == capability) {
return optionalStorage.cast();
}
return LazyOptional.empty();
}

@Override
public IntTag serializeNBT() {
return backend.serializeNBT();
}

@Override
public void deserializeNBT(IntTag tag) {
backend.deserializeNBT(tag);
}
};

event.addCapabilities(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
</syntaxhighlight>

Note that when using capabilities on entities, you should manually invalidate the capability via <code>invalidateCaps()</code>, via etc. <code>PlayerEvent.Clone</code>. This is due to the fact that players are recreated & copied when moving across dimensions, not simply moved.

=== Accessing a Capability ===

Accessing a Capability is the process by which a user is able to '''query''' a Capability Provider for a specific
instance of a capability.

This is perhaps the second most important part of the entire capability system, since it is what allows cross-mod
interaction. To obtain an instance of a Capability, the user must first get a hold of the Capability Provider that
should be queried. This can be done in a variety of ways and is outside the scope of this article. The user should
then invoke the <code>getCapability</code> method passing the unique instance of the capability that should be queried
(see [[#Obtaining a Capability|Obtaining a Capability]] for more information) and the querying <code>Direction</code>,
if applicable.

The returned object is a <code>LazyOptional</code> wrapping the queried Capability, if the capability provider exposes
it, otherwise it will be empty. The <code>LazyOptional</code> can be either unwrapped via an <code>orElse</code> or
used directly via <code>ifPresent</code>.

It is '''highly suggested''' to cache the returned <code>LazyOptional</code> to avoid querying the same provider every
time, in order to improve performance. The user should thus register itself to the invalidation listener via the
<code>addListener</code> method. This ensures that the user will be able to react to the invalidation of the
<code>LazyOptional</code> and remove it from the cache.

With the above in mind, part of an user may be similar to the following snippet of code:

<syntaxhighlight lang="java">
// note the use of EnumMap, which is much more performant than HashMap for enum keys
private final Map<Direction, LazyOptional<IEnergyStorage>> cache = new EnumMap<>(Direction.class);

private void sendPowerTo(int power, Direction direction) {
LazyOptional<IEnergyStorage> targetCapability = cache.get(direction);

if (targetCapability == null) {
ICapabilityProvider provider = level.getBlockEntity(pos.relative(direction));
targetCapability = provider.getCapability(ForgeCapabilities.ENERGY, direction.getOpposite());
cache.put(direction, targetCapability);
targetCapability.addListener(self -> cache.put(direction, null));
}

targetCapability.ifPresent(storage -> storage.receiveEnergy(power, false));
}
</syntaxhighlight>

This example implementation of an user is querying via a <code>BlockEntity</code> the neighboring capability provider
for an <code>IEnergyStorage</code> capability. Before obtaining the provider, the code performs a cache lookup for the
targeted capability. If the check succeeds, then no lookup is performed; if the check fails, the targeted Capability
Provider is obtained and queried for the Capability. The obtained <code>LazyOptional</code> is then cached and a
listener is attached to it so that the cache would be emptied on invalidation. The code then continues with the
interaction with the capability, which is outside the scope of this article.

== Creating Custom Capabilities ==

While the various capabilities provided by Forge may satisfy the most common use cases, there is always the chance that
a mod may require a custom solution. For this reason, Forge provides a way to define a custom Capability.

Defining a custom Capability requires the user to provide one main component: the Capability Interface. Optionally, a
Capability Implementation and Capability Provider can also be created. In this
case, the provider will be used as described in [[#Attaching a Capability|Attaching a Capability]]. The various details
for all these components are described in the respective sections of this article.

In this section, we will refer to the implementation of a <code>MyCapability</code> capability, that can be used to
store a single mutable <code>String</code>.

Refer also to [[#Code Examples|Code Examples]] for an example on how the various components may be implemented in a
real-world scenario.

=== The Capability Interface and the Capability Implementation ===

The Capability Interface is one of the most important parts of a Capability: without it, the Capability effectively does
not exist. Designing a Capability Interface is exactly like designing any Java interface, so the particular details will
be glossed over in this section.

The Capability Implementation, on the other hand, is the implementation of the previously defined Capability Interface.
Usual rules for interface implementations follow. There can be more than one Capability Implementation for each
capability.

Note that a '''well-formed''' capability implementation should '''not store''' the Capability Provider inside of it: we
call the capability implementation ''provider-agnostic''. This is not a hard-requirement, though, rather it should act
more as a guideline. There are in fact certain situations where this cannot be avoided (e.g. attaching a client-synced
capability to an <code>ItemStack</code>).

Given all of the above information, this may be an example implementation of both a Capability Interface and a
Capability Implementation:

<syntaxhighlight lang="java">
@AutoRegisterCapability // This annotation registers the capability for you automatically!
public interface MyCapability {
String getValue();
void setValue(String value);
}

public class MyCapabilityImplementation implements MyCapability {
private String value;

@Override
public String getValue() {
return this.value;
}

@Override
public void setValue(String value) {
this.value = value;
}
}
</syntaxhighlight>

Note that in this case, only a single implementation is provided.

=== The Capability Provider ===

The Capability Provider is an optional component of the capability that allows the Capability to be attached to a
component. The details on how a Capability Provider should behave have already been discussed in the two previous
sections [[#Exposing a Capability|Exposing a Capability]] and [[#Attaching a Capability|Attaching a Capability]]: refer
to those for more information.

=== Class Diagram ===

[[File:Custom Capability Class Diagram.svg|800px|thumb|center|Custom Capability Class Diagram]]

In the above diagram the green and red marked areas are classes from Minecraft and Forge respectively. The classes inside the purple area are only needed if you want to [[#Attaching a Capability|Attach a Capability]]. Furthermore this diagram models a persistent provider and its most basic form, for more information on how to create a more complex provider see [[#Custom Capability Providers|Custom Capability Providers]]. To create a volatile provider instead just do not implement <code>INBTSerializable</code>.

== Custom Capability Providers ==

Much like custom Capabilities, Forge also allows the creation of custom Capability Providers. The main advantage of this
is allowing mods to create custom providers for their custom objects, in order to promote not only cross-mod
compatibility, but also uniformity in the way users may interact with different mod APIs.

This section will only give the basic outline of what is necessary to implement a custom Capability Provider: for more
in-depth explanation, people are referred to the game code.

By definition, a custom Capability Provider is everything that implements the <code>ICapabilityProvider</code>
interface. In this section, though, we will only cover people that may want to replicate the functionality of one of
the default providers, such as <code>BlockEntity</code> or <code>LevelChunk</code>.

The easiest way of doing this is extending the <code>CapabilityProvider</code> class provided by Forge. This will
automatically set up an ''agnostic'' Capability Provider. To fully initialize the capability provider, the subclass
should then invoke the <code>gatherCapabilities</code> method as the last instruction in its constructor, to ensure that
the game is able to recollect and attach all capabilities that other mods may want to attach to the capability provider.

== Code Examples ==

* [https://gist.github.com/TheCurle/6db954d680f6f067dcdc791355c32c89 A Gist showing a quick and dirty example on how to implement a Capability effectively]

[[Category:Data Storage]]

Capabilities

2022-09-24T18:06:20Z

Nexus-Dino: /* The Capability Interface and the Capability Implementation */

'''Capabilities''' are a Forge system that allows cross-mod interactions by allowing capability ''providers'' to
dynamically respect contracts and provide specialized behavior without requiring the implementation of many interfaces
or hard dependencies on mods.

== History ==
In an ideal world, all that would be needed for a mod to provide the equivalent of a capability would be implementing an
interface. This is in fact how cross-mod interaction used to work prior to the introduction of capabilities.

The real world, though, is often much more complicated: users wanted to be free to combine mods the way they wanted and
saw fit, and developers wanted to be able to declare ''soft'' dependencies on other mods, thus reducing the need of
having a huge mod pack just for testing.

The first approach used by Forge was conditional stripping of interfaces and methods, but this proved to be problematic.
While the idea works well in theory, in practice the ASM editing of classes relied on complex mechanics and could lead
to hard to spot bugs.

For this reason, the entire system was redesigned and the concept of '''capabilities''' was born.

== The Concept ==
A capability allows any capability provider to conditionally expose a certain ability to do something, e.g. accepting
power or handling items. A capability provider, moreover, can decide to expose a capability only on certain sides,
allowing for easy interactions with hoppers, cables, etc.

Capabilities may also be added and removed dynamically both from the "owner" of the capability provider and other mods,
allowing even easier cross-mod interaction. For example, a mod that isn't compatible with Forge Energy could be
converted into one by dynamically attaching the Forge Energy capability and handling the conversion to a third-party
energy system without having to alter the original mod.

== Terminology ==
The high flexibility of the system comes with a cost, though, which is terminology. The following section wants to be a
dictionary of sorts, defining all the terms that you may come across when dealing with capabilities.

In the rest of this article, we will refer to these terms frequently, so make sure you are familiar with them.

; Capability
: the ability to perform something. In-code this is represented by the <code>Capability</code> class.
; Capability Provider
: something that is able to support capabilities and provides a mean of accessing them. In-code they are represented by implementations of <code>ICapabilityProvider</code>. There are multiple kinds of capability providers:
:; Volatile Provider
:: a provider that doesn't persist data to disk; once the provider ceases to exist for any number of reasons, all capability data gets deleted.
:; Persistent Provider
:: a provider that requires all capabilities to serialize data to disk, in order to persist data even across game restarts. They implement the <code>INBTSerializable</code> interface.
:; Agnostic Provider
:: a provider that isn't neither volatile nor persistent, rather delegates the decision either to the capability directly or to sub-implementations. They also implement the <code>INBTSerializable</code> interface.
; Capability Interface
: the interface that defines the contract of the capability, so what operations the capability exposes.
; Capability Implementation
: one of the possibly many implementations of the capability interface, that actually carries out the work.

The wary reader may note that both ''persistent'' and ''agnostic'' providers are represented the same way in code. In
fact, the only difference between them comes from pure semantics in how their serialization methods are designed. This
will be further discussed in their respective sections.

Moreover, it is also common to refer to the capability interface as simply the ''capability''. While not strictly
correct, due to common usage we will also use this convention. So, to refer to the capability interface
<code>MyCapability</code>, we will usually talk about the "<code>MyCapability</code> capability".

== Forge-provided Capabilities and Providers ==
In order to ensure mods can work together seamlessly, Forge provides a set of default capabilities and capability
providers.

The default capability providers in a Forge environment are: <code>BlockEntity</code>, <code>Entity</code>,
<code>ItemStack</code>, <code>Level</code>, and <code>LevelChunk</code>. These are all agnostic providers, since they don't
mandate any sort of capability persistency requirements. Rather, it is the job of whoever subclasses these providers to
deal with either volatile or non-volatile capabilities.

The default capabilities that forge provides are represented by the interfaces <code>IItemHandler</code>,
<code>IFluidHandler</code>, <code>IFluidHandlerItem</code>, and <code>IEnergyStorage</code>. Each one of these capabilities will be discussed in the corresponding section.

=== <tt>IItemHandler</tt> ===

The <code>IItemHandler</code> capability refers to the ability for any capability provider to have some sort of internal
'''inventory''' with a certain number of slots, from which items can be inserted and extracted. It is also possible,
though, to expose this capability even if no such inventory is present as long as the capability provider can emulate
its presence (e.g. tools that allow accessing remote inventories).

This effectively '''replaces''' the vanilla interfaces <code>Container</code> and <code>WorldlyContainer</code>. These
interfaces are in fact retained only to allow vanilla code to compile and should not be used in mod code. This extends
to anything that implements those vanilla interfaces, such as <code>RandomizableContainerBlockEntity</code>.

A default reference implementation for this capability interface is provided in <code>ItemStackHandler</code>.

=== <tt>IFluidHandler</tt> ===

The <code>IFluidHandler</code> capability refers to the ability for any capability provider to handle and store fluids
in one or multiple fluid tanks. It is effectively the equivalent in terms of fluids of the <code>IItemHandler</code>
capability.

A default reference implementation for this capability interface is provided in <code>TileFluidHandler</code>.

=== <tt>IFluidHandlerItem</tt> ===

The <code>IFluidHandlerItem</code> capability refers to the ability for an <code>ItemStack</code> capability provider
to handle and store fluids in one or multiple fluid tanks. It is basically a specialized version of the
<code>IFluidHandler</code> capability that allows <code>ItemStack</code>s to define a custom container.

=== <tt>IEnergyStorage</tt> ===

The <code>IEnergyStorage</code> capability refers to the ability for any capability provider to store, consume, and
produce energy. This capability is the base capability for what's commonly known in the modded world as Forge Energy (or
FE), i.e. the energy system most mods use. Its internal design is heavily based on the (now defunct) Redstone Flux
Energy API, supporting both a push and pull system.

A default reference implementation for this capability interface is provided in <code>EnergyStorage</code>.

== Working with Capabilities ==

Both capability providers and users need to be able to provide and access capabilities through a common framework,
otherwise the ideal of dynamic and mod-agnostic would not really exist. For this reason, both capability providers and
capability ''accessors'' (which we define as everything that wants to access a capability), also known as '''clients''' or '''users''',
need to work together and with Forge to ensure that the common interface is used sensibly and correctly by all parties.

=== Obtaining a Capability ===

Before being able to work with a capability, it is necessary to obtain an instance of the <code>Capability</code> object itself.

A <code>Capability</code> can obtained at any time using <code>CapabilityManager#get</code>. This takes in an anonymous <code>CapabilityToken</code> to still allow for a soft dependency system while also keeping hold of any generic information needed. As such, you can always obtain a non-null capability.

<syntaxhighlight lang="java">
public static Capability<IItemHandler> ITEM_HANDLER = CapabilityManager.get(new CapabilityToken<>(){});
</syntaxhighlight>

The above code will let Forge know that the field <code>ITEM_HANDLER</code> should be analogous with the <code>IItemHandler</code> capability. Note that this does not mean the capability is accessible or registered. To check if it is, call <code>Capability#isRegistered</code>.

This is, for obvious reasons, redundant, since all capabilities are available through
<code>ForgeCapabilities</code>.

=== Exposing a Capability ===

Exposing a capability is a voluntary act by a capability provider that allows the capability to be discovered and
accessed by users.

To do so, a capability provider needs to juggle a couple more moving pieces to ensure that the capability state remains
consistent and that the lookup remains fast. It is in fact possible for a capability provider to be asked to provide
many capabilities many times in the same tick. For this reason, a provider is asked to do the following:

* the <code>LazyOptional</code>s that get returned '''must be cached''';
* if a capability changes exposure state (more on this later), all listeners '''must be notified''';
* if a capability gets invalidated (more on this later), all listeners '''must be notified'''
* the lookup inside <code>getCapability</code> must be performed with '''an <code>if</code>-<code>else</code> chain''';
* all unexposed but still present capabilities '''should be available''' if the provider is queried with a <code>null</code> direction (see ''Accessing a Capability'' for more information);
* if no capability of a given type is available or accessible, the provider '''must call <code>super</code> as long as it is possible to do so'''.

Capability providers must also reflect changes in the ''exposure state'' of a capability, meaning that if the
accessibility of a capability from a certain <code>Direction</code> changes (refer to
[[#Accessing a Capability|Accessing a Capability]] for more information), it is the provider's responsibility to trigger
a state response by invalidating the returned <code>LazyOptional</code> and caching a new one. This should also be
performed when a capability gets ''invalidated'', such as when a capability provider gets removed.

With all of the above in mind, part of a capability provider implementation may be similar to the following snippet:

<syntaxhighlight lang="java">
// suppose the presence of a field 'inventory' of type 'IItemHandler'

private LazyOptional<IItemhandler> inventoryOptional = LazyOptional.empty();

@Override
public <T> LazyOptional<T> getCapability(Capability<T> capability, @Nullable Direction direction) {
if (capability == ForgeCapabilities.ITEM_HANDLER
&& (direction == null || direction == Direction.UP || direction == Direction.DOWN)) {
return this.inventoryOptional.cast();
}
return super.getCapability(capability, direction); // See note after snippet
}

@Override
public void invalidateCaps()
{
this.inventoryOptional = LazyOptional.of(() -> this.inventory);
}

@Override
protected void invalidateCaps() {
super.invalidateCaps();
this.inventoryOptional.invalidate();
}
</syntaxhighlight>

This possible implementation of a capability provider exposes an <code>IItemHandler</code> capability and restricts
access only to the <code>UP</code> and <code>DOWN</code> directions. If we assume this capability provider is a
<code>BlockEntity</code>, then we may also say that the inventory is only accessible from the top and the bottom of the
block.

Moreover, the capability gets automatically invalidated when the provider gets invalidated. Assuming this is a
<code>BlockEntity</code>, this usually happens when the block gets removed from the level or unloaded due to distance.

The <code>super</code> call at the end of the <code>getCapability</code> method is extremely important, since it's what
allows Attaching external Capabilities to capability providers. Nevertheless, it is not always possible to invoke
<code>super</code>: in those cases, an empty <code>LazyOptional</code> should be returned.

=== Attaching a Capability ===

Attaching a Capability is a process by which external agents "modify" a Capability Provider, making it expose additional
capabilities other than the already available ones.

To do so, the '''attaching agent''' (which means the thing that wants to attach a capability to another provider) must
listen to the <code>AttachCapabilitiesEvent<T></code>. The <code>T</code> in this case represents the capability
provider you want to attach the capability to. Note that the type of <code>T</code> '''must''' be the base type of the
capability provider, not a subclass. As an example, if you want to attach a capability to a <code>MyBlockEntity</code>,
which extends <code>BlockEntity</code>, you'll have to listen to <code>AttachCapabilitiesEvent<BlockEntity></code>,
'''NOT''' to <code>AttachCapabilitiesEvent<MyBlockEntity></code>, since the latter will never fire.

The attaching agent can use the provided methods <code>getObject</code>, <code>addCapability</code>, and
<code>addListener</code> to check whether the capability should be attached to the current object and perform the
desired action.

When attaching a capability, the attaching agent should also provide a name in the form of a
<code>ResourceLocation</code>. The name '''must''' be under the attaching agent's namespace, but no restrictions are
placed on the actual name, as long as it is unique inside the given namespace.

Maybe a little counter-intuitively, the process of attaching does not attach a capability nor a capability interface
directly. Rather, the attaching agent should create its own implementation of a '''Capability Provider''' and attach it
via the event. This is done so that the attaching agent can have control over when, how, and where its capabilities are
exposed, instead of relying on the game itself deciding these parameters. For this reason, all considerations given in
the [[#Exposing a Capability|Exposing a Capability]] section on how to correctly create a Capability Provider.

With the above in mind, part of an attaching agent may be similar to the following snippet of code:

<syntaxhighlight lang="java">
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

EnergyStorage backend = new EnergyStorage(((EnergyBasedBlockEntity) event.getObject()).capacity);
LazyOptional<IEnergyStorage> optionalStorage = LazyOptional.of(() -> backend);

ICapabilityProvider provider = new ICapabilityProvider() {
@Override
public <T> LazyOptional<T> getCapability(Capability<T> cap, @Nullable Direction direction) {
if (cap == ForgeCapabilities.ENERGY) {
return optionalStorage.cast();
}
return LazyOptional.empty();
}
};

event.addCapability(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
</syntaxhighlight>

This example implementation of an attaching agent attaches a <code>IEnergyStorage</code> capability to all
<code>BlockEntity</code> instance that are a subclass of <code>EnergyBasedBlockEntity</code>. It also sets up the
<code>LazyOptional</code> for invalidation if the parent capability provider gets invalidated.

Note also the call of <code>LazyOptional.empty()</code> rather than a <code>super</code>. This is needed because when
attaching a capability, the parent capability provider isn't known. For this reason, it is necessary to return an empty
<code>LazyOptional</code>. The game will then handle automatic merging of the various different providers into a single
one.

The above example is one of a '''Volatile''' Capability Provider. On the other hand, mods may want to persist their
data across sessions. In this case, they should attach a '''Persistent''' Capability Provider: this can be done either
by implementing the <code>INBTSerializable</code> interface along with <code>ICapabilityProvider</code> or by
implementing the <code>ICapabilitySerializable</code> interface.

The previous example reworked to use a Persistent Capability Provider may be similar to the following snippet:

<syntaxhighlight lang="java">
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

EnergyStorage backend = new EnergyStorage(((EnergyBasedBlockEntity) event.getObject()).capacity);
LazyOptional<IEnergyStorage> optionalStorage = LazyOptional.of(() -> backend);
Capability<IEnergyStorage> capability = ForgeCapabilities.ENERGY;

ICapabilityProvider provider = new ICapabilitySerializable<IntTag>() {
@Override
public <T> LazyOptional<T> getCapability(Capability<T> cap, @Nullable Direction direction) {
if (cap == capability) {
return optionalStorage.cast();
}
return LazyOptional.empty();
}

@Override
public IntTag serializeNBT() {
return backend.serializeNBT();
}

@Override
public void deserializeNBT(IntTag tag) {
backend.deserializeNBT(tag);
}
};

event.addCapabilities(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
</syntaxhighlight>

Note that when using capabilities on entities, you should manually invalidate the capability via <code>invalidateCaps()</code>, via etc. <code>PlayerEvent.Clone</code>. This is due to the fact that players are recreated & copied when moving across dimensions, not simply moved.

=== Accessing a Capability ===

Accessing a Capability is the process by which a user is able to '''query''' a Capability Provider for a specific
instance of a capability.

This is perhaps the second most important part of the entire capability system, since it is what allows cross-mod
interaction. To obtain an instance of a Capability, the user must first get a hold of the Capability Provider that
should be queried. This can be done in a variety of ways and is outside the scope of this article. The user should
then invoke the <code>getCapability</code> method passing the unique instance of the capability that should be queried
(see [[#Obtaining a Capability|Obtaining a Capability]] for more information) and the querying <code>Direction</code>,
if applicable.

The returned object is a <code>LazyOptional</code> wrapping the queried Capability, if the capability provider exposes
it, otherwise it will be empty. The <code>LazyOptional</code> can be either unwrapped via an <code>orElse</code> or
used directly via <code>ifPresent</code>.

It is '''highly suggested''' to cache the returned <code>LazyOptional</code> to avoid querying the same provider every
time, in order to improve performance. The user should thus register itself to the invalidation listener via the
<code>addListener</code> method. This ensures that the user will be able to react to the invalidation of the
<code>LazyOptional</code> and remove it from the cache.

With the above in mind, part of an user may be similar to the following snippet of code:

<syntaxhighlight lang="java">
// note the use of EnumMap, which is much more performant than HashMap for enum keys
private final Map<Direction, LazyOptional<IEnergyStorage>> cache = new EnumMap<>(Direction.class);

private void sendPowerTo(int power, Direction direction) {
LazyOptional<IEnergyStorage> targetCapability = cache.get(direction);

if (targetCapability == null) {
ICapabilityProvider provider = level.getBlockEntity(pos.relative(direction));
targetCapability = provider.getCapability(ForgeCapabilities.ENERGY, direction.getOpposite());
cache.put(direction, targetCapability);
targetCapability.addListener(self -> cache.put(direction, null));
}

targetCapability.ifPresent(storage -> storage.receiveEnergy(power, false));
}
</syntaxhighlight>

This example implementation of an user is querying via a <code>BlockEntity</code> the neighboring capability provider
for an <code>IEnergyStorage</code> capability. Before obtaining the provider, the code performs a cache lookup for the
targeted capability. If the check succeeds, then no lookup is performed; if the check fails, the targeted Capability
Provider is obtained and queried for the Capability. The obtained <code>LazyOptional</code> is then cached and a
listener is attached to it so that the cache would be emptied on invalidation. The code then continues with the
interaction with the capability, which is outside the scope of this article.

== Creating Custom Capabilities ==

While the various capabilities provided by Forge may satisfy the most common use cases, there is always the chance that
a mod may require a custom solution. For this reason, Forge provides a way to define a custom Capability.

Defining a custom Capability requires the user to provide one main component: the Capability Interface. Optionally, a
Capability Implementation and Capability Provider can also be created. In this
case, the provider will be used as described in [[#Attaching a Capability|Attaching a Capability]]. The various details
for all these components are described in the respective sections of this article.

In this section, we will refer to the implementation of a <code>MyCapability</code> capability, that can be used to
store a single mutable <code>String</code>.

Refer also to [[#Code Examples|Code Examples]] for an example on how the various components may be implemented in a
real-world scenario.

=== The Capability Interface and the Capability Implementation ===

The Capability Interface is one of the most important parts of a Capability: without it, the Capability effectively does
not exist. Designing a Capability Interface is exactly like designing any Java interface, so the particular details will
be glossed over in this section.

The Capability Implementation, on the other hand, is the implementation of the previously defined Capability Interface.
Usual rules for interface implementations follow. There can be more than one Capability Implementation for each
capability.

Note that a '''well-formed''' capability implementation should '''not store''' the Capability Provider inside of it: we
call the capability implementation ''provider-agnostic''. This is not a hard-requirement, though, rather it should act
more as a guideline. There are in fact certain situations where this cannot be avoided (e.g. attaching a client-synced
capability to an <code>ItemStack</code>).

Given all of the above information, this may be an example implementation of both a Capability Interface and a
Capability Implementation:

<syntaxhighlight lang="java">
@AutoRegisterCapability
public interface MyCapability {
String getValue();
void setValue(String value);
}

public class MyCapabilityImplementation implements MyCapability {
private String value;

@Override
public String getValue() {
return this.value;
}

@Override
public void setValue(String value) {
this.value = value;
}
}
</syntaxhighlight>

Note that in this case, only a single implementation is provided.

=== The Capability Provider ===

The Capability Provider is an optional component of the capability that allows the Capability to be attached to a
component. The details on how a Capability Provider should behave have already been discussed in the two previous
sections [[#Exposing a Capability|Exposing a Capability]] and [[#Attaching a Capability|Attaching a Capability]]: refer
to those for more information.

=== Tying it All Together ===

Once all components of a Capability have been created, they must be registered so that the game is aware of the
capability's presence. The registration requires specifying only the Capability Interface.

The registration can be performed by calling the <code>register</code> method within the <code>RegisterCapabilitiesEvent</code> which is fired on the <code>MOD</code> event bus. The
registration will also automatically inject the created Capability into all relevant fields and methods: refer to
[[#Obtaining a Capability|Obtaining a Capability]] for more information.

An example of registration can be found in the snippet that follows:

<syntaxhighlight lang="java">
@SubscribeEvent
public void registerCaps(RegisterCapabilitiesEvent event) {
event.register(MyCapability.class);
}
</syntaxhighlight>

=== Class Diagram ===

[[File:Custom Capability Class Diagram.svg|800px|thumb|center|Custom Capability Class Diagram]]

In the above diagram the green and red marked areas are classes from Minecraft and Forge respectively. The classes inside the purple area are only needed if you want to [[#Attaching a Capability|Attach a Capability]]. Furthermore this diagram models a persistent provider and its most basic form, for more information on how to create a more complex provider see [[#Custom Capability Providers|Custom Capability Providers]]. To create a volatile provider instead just do not implement <code>INBTSerializable</code>.

== Custom Capability Providers ==

Much like custom Capabilities, Forge also allows the creation of custom Capability Providers. The main advantage of this
is allowing mods to create custom providers for their custom objects, in order to promote not only cross-mod
compatibility, but also uniformity in the way users may interact with different mod APIs.

This section will only give the basic outline of what is necessary to implement a custom Capability Provider: for more
in-depth explanation, people are referred to the game code.

By definition, a custom Capability Provider is everything that implements the <code>ICapabilityProvider</code>
interface. In this section, though, we will only cover people that may want to replicate the functionality of one of
the default providers, such as <code>BlockEntity</code> or <code>LevelChunk</code>.

The easiest way of doing this is extending the <code>CapabilityProvider</code> class provided by Forge. This will
automatically set up an ''agnostic'' Capability Provider. To fully initialize the capability provider, the subclass
should then invoke the <code>gatherCapabilities</code> method as the last instruction in its constructor, to ensure that
the game is able to recollect and attach all capabilities that other mods may want to attach to the capability provider.

== Code Examples ==

* [https://gist.github.com/TheCurle/6db954d680f6f067dcdc791355c32c89 A Gist showing a quick and dirty example on how to implement a Capability effectively]

[[Category:Data Storage]]

Capabilities

2022-09-24T18:05:16Z

Nexus-Dino: Update Wiki to recent MinecraftForge PRs

'''Capabilities''' are a Forge system that allows cross-mod interactions by allowing capability ''providers'' to
dynamically respect contracts and provide specialized behavior without requiring the implementation of many interfaces
or hard dependencies on mods.

== History ==
In an ideal world, all that would be needed for a mod to provide the equivalent of a capability would be implementing an
interface. This is in fact how cross-mod interaction used to work prior to the introduction of capabilities.

The real world, though, is often much more complicated: users wanted to be free to combine mods the way they wanted and
saw fit, and developers wanted to be able to declare ''soft'' dependencies on other mods, thus reducing the need of
having a huge mod pack just for testing.

The first approach used by Forge was conditional stripping of interfaces and methods, but this proved to be problematic.
While the idea works well in theory, in practice the ASM editing of classes relied on complex mechanics and could lead
to hard to spot bugs.

For this reason, the entire system was redesigned and the concept of '''capabilities''' was born.

== The Concept ==
A capability allows any capability provider to conditionally expose a certain ability to do something, e.g. accepting
power or handling items. A capability provider, moreover, can decide to expose a capability only on certain sides,
allowing for easy interactions with hoppers, cables, etc.

Capabilities may also be added and removed dynamically both from the "owner" of the capability provider and other mods,
allowing even easier cross-mod interaction. For example, a mod that isn't compatible with Forge Energy could be
converted into one by dynamically attaching the Forge Energy capability and handling the conversion to a third-party
energy system without having to alter the original mod.

== Terminology ==
The high flexibility of the system comes with a cost, though, which is terminology. The following section wants to be a
dictionary of sorts, defining all the terms that you may come across when dealing with capabilities.

In the rest of this article, we will refer to these terms frequently, so make sure you are familiar with them.

; Capability
: the ability to perform something. In-code this is represented by the <code>Capability</code> class.
; Capability Provider
: something that is able to support capabilities and provides a mean of accessing them. In-code they are represented by implementations of <code>ICapabilityProvider</code>. There are multiple kinds of capability providers:
:; Volatile Provider
:: a provider that doesn't persist data to disk; once the provider ceases to exist for any number of reasons, all capability data gets deleted.
:; Persistent Provider
:: a provider that requires all capabilities to serialize data to disk, in order to persist data even across game restarts. They implement the <code>INBTSerializable</code> interface.
:; Agnostic Provider
:: a provider that isn't neither volatile nor persistent, rather delegates the decision either to the capability directly or to sub-implementations. They also implement the <code>INBTSerializable</code> interface.
; Capability Interface
: the interface that defines the contract of the capability, so what operations the capability exposes.
; Capability Implementation
: one of the possibly many implementations of the capability interface, that actually carries out the work.

The wary reader may note that both ''persistent'' and ''agnostic'' providers are represented the same way in code. In
fact, the only difference between them comes from pure semantics in how their serialization methods are designed. This
will be further discussed in their respective sections.

Moreover, it is also common to refer to the capability interface as simply the ''capability''. While not strictly
correct, due to common usage we will also use this convention. So, to refer to the capability interface
<code>MyCapability</code>, we will usually talk about the "<code>MyCapability</code> capability".

== Forge-provided Capabilities and Providers ==
In order to ensure mods can work together seamlessly, Forge provides a set of default capabilities and capability
providers.

The default capability providers in a Forge environment are: <code>BlockEntity</code>, <code>Entity</code>,
<code>ItemStack</code>, <code>Level</code>, and <code>LevelChunk</code>. These are all agnostic providers, since they don't
mandate any sort of capability persistency requirements. Rather, it is the job of whoever subclasses these providers to
deal with either volatile or non-volatile capabilities.

The default capabilities that forge provides are represented by the interfaces <code>IItemHandler</code>,
<code>IFluidHandler</code>, <code>IFluidHandlerItem</code>, and <code>IEnergyStorage</code>. Each one of these capabilities will be discussed in the corresponding section.

=== <tt>IItemHandler</tt> ===

The <code>IItemHandler</code> capability refers to the ability for any capability provider to have some sort of internal
'''inventory''' with a certain number of slots, from which items can be inserted and extracted. It is also possible,
though, to expose this capability even if no such inventory is present as long as the capability provider can emulate
its presence (e.g. tools that allow accessing remote inventories).

This effectively '''replaces''' the vanilla interfaces <code>Container</code> and <code>WorldlyContainer</code>. These
interfaces are in fact retained only to allow vanilla code to compile and should not be used in mod code. This extends
to anything that implements those vanilla interfaces, such as <code>RandomizableContainerBlockEntity</code>.

A default reference implementation for this capability interface is provided in <code>ItemStackHandler</code>.

=== <tt>IFluidHandler</tt> ===

The <code>IFluidHandler</code> capability refers to the ability for any capability provider to handle and store fluids
in one or multiple fluid tanks. It is effectively the equivalent in terms of fluids of the <code>IItemHandler</code>
capability.

A default reference implementation for this capability interface is provided in <code>TileFluidHandler</code>.

=== <tt>IFluidHandlerItem</tt> ===

The <code>IFluidHandlerItem</code> capability refers to the ability for an <code>ItemStack</code> capability provider
to handle and store fluids in one or multiple fluid tanks. It is basically a specialized version of the
<code>IFluidHandler</code> capability that allows <code>ItemStack</code>s to define a custom container.

=== <tt>IEnergyStorage</tt> ===

The <code>IEnergyStorage</code> capability refers to the ability for any capability provider to store, consume, and
produce energy. This capability is the base capability for what's commonly known in the modded world as Forge Energy (or
FE), i.e. the energy system most mods use. Its internal design is heavily based on the (now defunct) Redstone Flux
Energy API, supporting both a push and pull system.

A default reference implementation for this capability interface is provided in <code>EnergyStorage</code>.

== Working with Capabilities ==

Both capability providers and users need to be able to provide and access capabilities through a common framework,
otherwise the ideal of dynamic and mod-agnostic would not really exist. For this reason, both capability providers and
capability ''accessors'' (which we define as everything that wants to access a capability), also known as '''clients''' or '''users''',
need to work together and with Forge to ensure that the common interface is used sensibly and correctly by all parties.

=== Obtaining a Capability ===

Before being able to work with a capability, it is necessary to obtain an instance of the <code>Capability</code> object itself.

A <code>Capability</code> can obtained at any time using <code>CapabilityManager#get</code>. This takes in an anonymous <code>CapabilityToken</code> to still allow for a soft dependency system while also keeping hold of any generic information needed. As such, you can always obtain a non-null capability.

<syntaxhighlight lang="java">
public static Capability<IItemHandler> ITEM_HANDLER = CapabilityManager.get(new CapabilityToken<>(){});
</syntaxhighlight>

The above code will let Forge know that the field <code>ITEM_HANDLER</code> should be analogous with the <code>IItemHandler</code> capability. Note that this does not mean the capability is accessible or registered. To check if it is, call <code>Capability#isRegistered</code>.

This is, for obvious reasons, redundant, since all capabilities are available through
<code>ForgeCapabilities</code>.

=== Exposing a Capability ===

Exposing a capability is a voluntary act by a capability provider that allows the capability to be discovered and
accessed by users.

To do so, a capability provider needs to juggle a couple more moving pieces to ensure that the capability state remains
consistent and that the lookup remains fast. It is in fact possible for a capability provider to be asked to provide
many capabilities many times in the same tick. For this reason, a provider is asked to do the following:

* the <code>LazyOptional</code>s that get returned '''must be cached''';
* if a capability changes exposure state (more on this later), all listeners '''must be notified''';
* if a capability gets invalidated (more on this later), all listeners '''must be notified'''
* the lookup inside <code>getCapability</code> must be performed with '''an <code>if</code>-<code>else</code> chain''';
* all unexposed but still present capabilities '''should be available''' if the provider is queried with a <code>null</code> direction (see ''Accessing a Capability'' for more information);
* if no capability of a given type is available or accessible, the provider '''must call <code>super</code> as long as it is possible to do so'''.

Capability providers must also reflect changes in the ''exposure state'' of a capability, meaning that if the
accessibility of a capability from a certain <code>Direction</code> changes (refer to
[[#Accessing a Capability|Accessing a Capability]] for more information), it is the provider's responsibility to trigger
a state response by invalidating the returned <code>LazyOptional</code> and caching a new one. This should also be
performed when a capability gets ''invalidated'', such as when a capability provider gets removed.

With all of the above in mind, part of a capability provider implementation may be similar to the following snippet:

<syntaxhighlight lang="java">
// suppose the presence of a field 'inventory' of type 'IItemHandler'

private LazyOptional<IItemhandler> inventoryOptional = LazyOptional.empty();

@Override
public <T> LazyOptional<T> getCapability(Capability<T> capability, @Nullable Direction direction) {
if (capability == ForgeCapabilities.ITEM_HANDLER
&& (direction == null || direction == Direction.UP || direction == Direction.DOWN)) {
return this.inventoryOptional.cast();
}
return super.getCapability(capability, direction); // See note after snippet
}

@Override
public void invalidateCaps()
{
this.inventoryOptional = LazyOptional.of(() -> this.inventory);
}

@Override
protected void invalidateCaps() {
super.invalidateCaps();
this.inventoryOptional.invalidate();
}
</syntaxhighlight>

This possible implementation of a capability provider exposes an <code>IItemHandler</code> capability and restricts
access only to the <code>UP</code> and <code>DOWN</code> directions. If we assume this capability provider is a
<code>BlockEntity</code>, then we may also say that the inventory is only accessible from the top and the bottom of the
block.

Moreover, the capability gets automatically invalidated when the provider gets invalidated. Assuming this is a
<code>BlockEntity</code>, this usually happens when the block gets removed from the level or unloaded due to distance.

The <code>super</code> call at the end of the <code>getCapability</code> method is extremely important, since it's what
allows Attaching external Capabilities to capability providers. Nevertheless, it is not always possible to invoke
<code>super</code>: in those cases, an empty <code>LazyOptional</code> should be returned.

=== Attaching a Capability ===

Attaching a Capability is a process by which external agents "modify" a Capability Provider, making it expose additional
capabilities other than the already available ones.

To do so, the '''attaching agent''' (which means the thing that wants to attach a capability to another provider) must
listen to the <code>AttachCapabilitiesEvent<T></code>. The <code>T</code> in this case represents the capability
provider you want to attach the capability to. Note that the type of <code>T</code> '''must''' be the base type of the
capability provider, not a subclass. As an example, if you want to attach a capability to a <code>MyBlockEntity</code>,
which extends <code>BlockEntity</code>, you'll have to listen to <code>AttachCapabilitiesEvent<BlockEntity></code>,
'''NOT''' to <code>AttachCapabilitiesEvent<MyBlockEntity></code>, since the latter will never fire.

The attaching agent can use the provided methods <code>getObject</code>, <code>addCapability</code>, and
<code>addListener</code> to check whether the capability should be attached to the current object and perform the
desired action.

When attaching a capability, the attaching agent should also provide a name in the form of a
<code>ResourceLocation</code>. The name '''must''' be under the attaching agent's namespace, but no restrictions are
placed on the actual name, as long as it is unique inside the given namespace.

Maybe a little counter-intuitively, the process of attaching does not attach a capability nor a capability interface
directly. Rather, the attaching agent should create its own implementation of a '''Capability Provider''' and attach it
via the event. This is done so that the attaching agent can have control over when, how, and where its capabilities are
exposed, instead of relying on the game itself deciding these parameters. For this reason, all considerations given in
the [[#Exposing a Capability|Exposing a Capability]] section on how to correctly create a Capability Provider.

With the above in mind, part of an attaching agent may be similar to the following snippet of code:

<syntaxhighlight lang="java">
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

EnergyStorage backend = new EnergyStorage(((EnergyBasedBlockEntity) event.getObject()).capacity);
LazyOptional<IEnergyStorage> optionalStorage = LazyOptional.of(() -> backend);

ICapabilityProvider provider = new ICapabilityProvider() {
@Override
public <T> LazyOptional<T> getCapability(Capability<T> cap, @Nullable Direction direction) {
if (cap == ForgeCapabilities.ENERGY) {
return optionalStorage.cast();
}
return LazyOptional.empty();
}
};

event.addCapability(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
</syntaxhighlight>

This example implementation of an attaching agent attaches a <code>IEnergyStorage</code> capability to all
<code>BlockEntity</code> instance that are a subclass of <code>EnergyBasedBlockEntity</code>. It also sets up the
<code>LazyOptional</code> for invalidation if the parent capability provider gets invalidated.

Note also the call of <code>LazyOptional.empty()</code> rather than a <code>super</code>. This is needed because when
attaching a capability, the parent capability provider isn't known. For this reason, it is necessary to return an empty
<code>LazyOptional</code>. The game will then handle automatic merging of the various different providers into a single
one.

The above example is one of a '''Volatile''' Capability Provider. On the other hand, mods may want to persist their
data across sessions. In this case, they should attach a '''Persistent''' Capability Provider: this can be done either
by implementing the <code>INBTSerializable</code> interface along with <code>ICapabilityProvider</code> or by
implementing the <code>ICapabilitySerializable</code> interface.

The previous example reworked to use a Persistent Capability Provider may be similar to the following snippet:

<syntaxhighlight lang="java">
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

EnergyStorage backend = new EnergyStorage(((EnergyBasedBlockEntity) event.getObject()).capacity);
LazyOptional<IEnergyStorage> optionalStorage = LazyOptional.of(() -> backend);
Capability<IEnergyStorage> capability = ForgeCapabilities.ENERGY;

ICapabilityProvider provider = new ICapabilitySerializable<IntTag>() {
@Override
public <T> LazyOptional<T> getCapability(Capability<T> cap, @Nullable Direction direction) {
if (cap == capability) {
return optionalStorage.cast();
}
return LazyOptional.empty();
}

@Override
public IntTag serializeNBT() {
return backend.serializeNBT();
}

@Override
public void deserializeNBT(IntTag tag) {
backend.deserializeNBT(tag);
}
};

event.addCapabilities(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
</syntaxhighlight>

Note that when using capabilities on entities, you should manually invalidate the capability via <code>invalidateCaps()</code>, via etc. <code>PlayerEvent.Clone</code>. This is due to the fact that players are recreated & copied when moving across dimensions, not simply moved.

=== Accessing a Capability ===

Accessing a Capability is the process by which a user is able to '''query''' a Capability Provider for a specific
instance of a capability.

This is perhaps the second most important part of the entire capability system, since it is what allows cross-mod
interaction. To obtain an instance of a Capability, the user must first get a hold of the Capability Provider that
should be queried. This can be done in a variety of ways and is outside the scope of this article. The user should
then invoke the <code>getCapability</code> method passing the unique instance of the capability that should be queried
(see [[#Obtaining a Capability|Obtaining a Capability]] for more information) and the querying <code>Direction</code>,
if applicable.

The returned object is a <code>LazyOptional</code> wrapping the queried Capability, if the capability provider exposes
it, otherwise it will be empty. The <code>LazyOptional</code> can be either unwrapped via an <code>orElse</code> or
used directly via <code>ifPresent</code>.

It is '''highly suggested''' to cache the returned <code>LazyOptional</code> to avoid querying the same provider every
time, in order to improve performance. The user should thus register itself to the invalidation listener via the
<code>addListener</code> method. This ensures that the user will be able to react to the invalidation of the
<code>LazyOptional</code> and remove it from the cache.

With the above in mind, part of an user may be similar to the following snippet of code:

<syntaxhighlight lang="java">
// note the use of EnumMap, which is much more performant than HashMap for enum keys
private final Map<Direction, LazyOptional<IEnergyStorage>> cache = new EnumMap<>(Direction.class);

private void sendPowerTo(int power, Direction direction) {
LazyOptional<IEnergyStorage> targetCapability = cache.get(direction);

if (targetCapability == null) {
ICapabilityProvider provider = level.getBlockEntity(pos.relative(direction));
targetCapability = provider.getCapability(ForgeCapabilities.ENERGY, direction.getOpposite());
cache.put(direction, targetCapability);
targetCapability.addListener(self -> cache.put(direction, null));
}

targetCapability.ifPresent(storage -> storage.receiveEnergy(power, false));
}
</syntaxhighlight>

This example implementation of an user is querying via a <code>BlockEntity</code> the neighboring capability provider
for an <code>IEnergyStorage</code> capability. Before obtaining the provider, the code performs a cache lookup for the
targeted capability. If the check succeeds, then no lookup is performed; if the check fails, the targeted Capability
Provider is obtained and queried for the Capability. The obtained <code>LazyOptional</code> is then cached and a
listener is attached to it so that the cache would be emptied on invalidation. The code then continues with the
interaction with the capability, which is outside the scope of this article.

== Creating Custom Capabilities ==

While the various capabilities provided by Forge may satisfy the most common use cases, there is always the chance that
a mod may require a custom solution. For this reason, Forge provides a way to define a custom Capability.

Defining a custom Capability requires the user to provide one main component: the Capability Interface. Optionally, a
Capability Implementation and Capability Provider can also be created. In this
case, the provider will be used as described in [[#Attaching a Capability|Attaching a Capability]]. The various details
for all these components are described in the respective sections of this article.

In this section, we will refer to the implementation of a <code>MyCapability</code> capability, that can be used to
store a single mutable <code>String</code>.

Refer also to [[#Code Examples|Code Examples]] for an example on how the various components may be implemented in a
real-world scenario.

=== The Capability Interface and the Capability Implementation ===

The Capability Interface is one of the most important parts of a Capability: without it, the Capability effectively does
not exist. Designing a Capability Interface is exactly like designing any Java interface, so the particular details will
be glossed over in this section.

The Capability Implementation, on the other hand, is the implementation of the previously defined Capability Interface.
Usual rules for interface implementations follow. There can be more than one Capability Implementation for each
capability.

Note that a '''well-formed''' capability implementation should '''not store''' the Capability Provider inside of it: we
call the capability implementation ''provider-agnostic''. This is not a hard-requirement, though, rather it should act
more as a guideline. There are in fact certain situations where this cannot be avoided (e.g. attaching a client-synced
capability to an <code>ItemStack</code>).

Given all of the above information, this may be an example implementation of both a Capability Interface and a
Capability Implementation:

<syntaxhighlight lang="java">
public interface MyCapability {
String getValue();
void setValue(String value);
}

public class MyCapabilityImplementation implements MyCapability {
private String value;

@Override
public String getValue() {
return this.value;
}

@Override
public void setValue(String value) {
this.value = value;
}
}
</syntaxhighlight>

Note that in this case, only a single implementation is provided.

=== The Capability Provider ===

The Capability Provider is an optional component of the capability that allows the Capability to be attached to a
component. The details on how a Capability Provider should behave have already been discussed in the two previous
sections [[#Exposing a Capability|Exposing a Capability]] and [[#Attaching a Capability|Attaching a Capability]]: refer
to those for more information.

=== Tying it All Together ===

Once all components of a Capability have been created, they must be registered so that the game is aware of the
capability's presence. The registration requires specifying only the Capability Interface.

The registration can be performed by calling the <code>register</code> method within the <code>RegisterCapabilitiesEvent</code> which is fired on the <code>MOD</code> event bus. The
registration will also automatically inject the created Capability into all relevant fields and methods: refer to
[[#Obtaining a Capability|Obtaining a Capability]] for more information.

An example of registration can be found in the snippet that follows:

<syntaxhighlight lang="java">
@SubscribeEvent
public void registerCaps(RegisterCapabilitiesEvent event) {
event.register(MyCapability.class);
}
</syntaxhighlight>

=== Class Diagram ===

[[File:Custom Capability Class Diagram.svg|800px|thumb|center|Custom Capability Class Diagram]]

In the above diagram the green and red marked areas are classes from Minecraft and Forge respectively. The classes inside the purple area are only needed if you want to [[#Attaching a Capability|Attach a Capability]]. Furthermore this diagram models a persistent provider and its most basic form, for more information on how to create a more complex provider see [[#Custom Capability Providers|Custom Capability Providers]]. To create a volatile provider instead just do not implement <code>INBTSerializable</code>.

== Custom Capability Providers ==

Much like custom Capabilities, Forge also allows the creation of custom Capability Providers. The main advantage of this
is allowing mods to create custom providers for their custom objects, in order to promote not only cross-mod
compatibility, but also uniformity in the way users may interact with different mod APIs.

This section will only give the basic outline of what is necessary to implement a custom Capability Provider: for more
in-depth explanation, people are referred to the game code.

By definition, a custom Capability Provider is everything that implements the <code>ICapabilityProvider</code>
interface. In this section, though, we will only cover people that may want to replicate the functionality of one of
the default providers, such as <code>BlockEntity</code> or <code>LevelChunk</code>.

The easiest way of doing this is extending the <code>CapabilityProvider</code> class provided by Forge. This will
automatically set up an ''agnostic'' Capability Provider. To fully initialize the capability provider, the subclass
should then invoke the <code>gatherCapabilities</code> method as the last instruction in its constructor, to ensure that
the game is able to recollect and attach all capabilities that other mods may want to attach to the capability provider.

== Code Examples ==

* [https://gist.github.com/TheCurle/6db954d680f6f067dcdc791355c32c89 A Gist showing a quick and dirty example on how to implement a Capability effectively]

[[Category:Data Storage]]

Block Entities

2022-09-20T18:01:23Z

Nexus-Dino:

Block entities are like simplified entities that are bound to a <code>Block</code>. They are used to store dynamic data, execute tick based tasks and for dynamic rendering. Some examples from vanilla Minecraft would be: handling of inventories (chests), smelting logic on furnaces, or area effects for beacons. More advanced examples exist in mods, such as quarries, sorting machines, pipes, and displays.

{{Colored box|title=Tip|content=A <code>BlockEntity</code> isn’t a solution for everything, and they can cause lag when used wrongly. When possible, try to avoid them.}}

== Creating a <code>BlockEntity</code> ==
You can also use a <code>DeferredRegister</code> instead.
<syntaxhighlight lang="java">
public static final DeferredRegister<BlockEntityType<?>> BLOCK_ENTITIES = DeferredRegister.create(ForgeRegistries.BLOCK_ENTITIES, "examplemod");

public static final RegistryObject<BlockEntityType<?>> MY_BE = BLOCK_ENTITIES.register("mybe", () -> BlockEntityType.Builder.of(supplier, validBlocks).build(null));
</syntaxhighlight>

In this example, <code>supplier</code> is a <code>BlockEntityType$BlockEntitySupplier</code> that creates a new instance of your <code>BlockEntity</code>. A method reference or a lambda is commonly used. The variable <code>validBlocks</code> is one or more blocks (<code><nowiki>BlockEntityType$Builder::of</nowiki></code> is varargs) that the block entity can exist for.

== Attaching a <code>BlockEntity</code> to a <code>Block</code> ==
To attach your new <code>BlockEntity</code> to a <code>Block</code>, the <code>EntityBlock</code> interface must be implemented on your <code>Block</code> subclass. The method <code>EntityBlock#newBlockEntity(BlockPos, BlockState)</code> must be implemented and return a new instance of your <code>BlockEntity</code>.

== Storing Data within your <code>BlockEntity</code> ==
In order to save data, override the following two methods
<syntaxhighlight lang="java">
BlockEntity#saveAdditional(CompoundTag tag)

BlockEntity#load(CompoundTag tag)
</syntaxhighlight>
These methods are called whenever the <code>LevelChunk</code> containing the <code>BlockEntity</code> gets loaded from/saved to a tag. Use them to read and write to the fields in your block entity class.

{{Colored box|title=Tip|content=Whenever your data changes you need to call <code><nowiki>BlockEntity#setChanged()</nowiki></code>, otherwise the <code>LevelChunk</code> containing your <code>BlockEntity</code> might be skipped while the level is saved.}}

{{Tip/Important|It is important that you call the super methods!

The tag names <code>id</code>, <code>x</code>, <code>y</code>, <code>z</code>, <code>ForgeData</code> and <code>ForgeCaps</code> are reserved by the super methods.}}

== Ticking <code>BlockEntity</code> ==
If you need a ticking <code>BlockEntity</code>, for example to keep track of the progress during a smelting process, another method must be implemented and overridden within <code>EntityBlock</code>: <code>EntityBlock#getTicker(Level, BlockState, BlockEntityType)</code>. This can implement different tickers depending on which logical side the user is on, or just implement one general ticker. In either case, a <code>BlockEntityTicker</code> must be returned. Since this is a functional interface, it can just take in a method representing the ticker instead:
<syntaxhighlight lang="java">
// Inside some Block subclass
@Nullable
@Override
public <T extends BlockEntity> BlockEntityTicker<T> getTicker(Level level, BlockState state, BlockEntityType<T> type) {
return type == MyBlockEntityTypes.MY_BE.get() ? MyBlockEntity::tick : null;
}

// Inside MyBlockEntity
public static void tick(Level level, BlockPos pos, BlockState state, T blockEntity) {
// Do stuff
}
</syntaxhighlight>

{{Colored box|title=Tip|content=This method is called each tick. Therefore, you should avoid having complicated calculations in here. If possible, you should make more complex calculations just every X ticks. (The amount of ticks in a second may be lower than 20 (twenty) but won’t be higher)}}

== Synchronizing the Data to the Client ==
There are 3 (three) ways of syncing data to the client. Synchronizing on chunk load, synchronizing on block updates and synchronizing with a custom network message.
=== Synchronizing on LevelChunk load ===
For this you need to override
<syntaxhighlight lang="java">
BlockEntity#getUpdateTag()

IForgeBlockEntity#handleUpdateTag(CompoundTag tag)
</syntaxhighlight>
Again, this is pretty simple, the first method collects the data that should be send to the client, while the second one processes that data. If your <code>BlockEntity</code> doesn’t contain much data you might be able to use the methods out of the [[#storing_data|Storing Data]] section.

{{Tip/Important|Synchronizing excessive/useless data for block entities can lead to network congestion. You should optimize your network usage by sending only the information the client needs when the client needs it. For instance, it is more often than not unnecessary to send the inventory of a block entity in the update tag, as this can be synchronized via its <code>AbstractContainerMenu</code>.)}}

=== Synchronizing on block update ===
This method is a bit more complicated, but again you just need to override 2 or 3 methods. Here is a tiny example implementation of it:
<syntaxhighlight lang="java">
@Override
public CompoundTag getUpdateTag() {
CompoundTag tag = new CompoundTag();
//Write your data into the tag
return tag;
}

@Override
public Packet<ClientGamePacketListener> getUpdatePacket() {
// Will get tag from #getUpdateTag
return ClientboundBlockEntityDataPacket.create(this);
}

// Can override IForgeBlockEntity#onDataPacket. By default, this will defer to the #load.
</syntaxhighlight>
The static constructors <code>ClientboundBlockEntityDataPacket#create</code> takes:
* The <code>BlockEntity</code>.
* An optional function to get the <code>CompoundTag</code> from the <code>BlockEntity</code>. By default, this uses <code>BlockEntity#getUpdateTag</code>.

Now, to send the packet, an update notification must be given on the server.
<code>
Level#sendBlockUpdated(BlockPos pos, BlockState oldState, BlockState newState, int flags)
</code>
The <code>pos</code> should be your <code>BlockEntity</code>’s position. For <code>oldState</code> and <code>newState</code> you can pass the current <code>BlockState</code> at that position. The <code>flags</code> are a bitmask and should contain <code>2</code>, which will sync the changes to the client. See <code>Block</code> for more info as well as the rest of the flags. The flag <code>2</code> is equivalent to <code><nowiki>Block#UPDATE_CLIENTS</nowiki></code>.

=== Synchronizing using a custom network message ===

This way of synchronizing is probably the most complicated one, but is usually also the most optimized one, as you can make sure that only the data you need to be synchronized is actually synchronized. You should first check out the <code>[[Understanding Networking|Networking]]</code> section and especially <code>[[Using SimpleChannel|SimpleImpl]]</code> before attempting this. Once you’ve created your custom network message, you can send it to all users that have the <code>BlockEntity</code> loaded with:
<syntaxhighlight lang="java">
SimpleChannel#send(PacketDistributor.TRACKING_CHUNK.with(() -> chunk), MSG);
</syntaxhighlight>
{{Colored box|title=Alert|content=It is important that you do safety checks, the <code>BlockEntity</code> might already be destroyed/replaced when the message arrives at the player! You should also check if the area is loaded using (<code><nowiki>Level#hasChunkAt(BlockPos)</nowiki></code>)}}

Datageneration/Loot Tables

2022-09-20T17:57:56Z

Nexus-Dino:

==The LootTableProvider class==
First you would need a new class that extends <code>LootTableProvider</code>. In this class you will override the <code>getTables</code> and <code>validate</code> methods.
You can optionally override <code>getName</code> to return a name for the logs, if you have multiple providers and don't want to simply show up as "LootTables".

None of the methods you will be overriding (either here or, where applicable, on the subproviders) should call the superclass methods - these superclass methods implement the vanilla data generation.

The <code>getTables</code> method will return a list of subproviders (explained further in the next section), the function signature looks a bit overwhelming but the actual method body is simple. Each subprovider will typically be a class, and you can simply use their constructors here. For more advanced scenarios (e.g. if you want to organize subproviders for multiple parameter sets into a single class), you can use a lambda that returns another lambda or a method reference.
<syntaxhighlight lang="java">
@Override
protected List<Pair<Supplier<Consumer<BiConsumer<ResourceLocation, LootTable.Builder>>>, LootContextParamSet>> getTables() {
return List.of(
Pair.of(MyBlockLoot::new, LootContextParamSets.BLOCK),
Pair.of(MyEntityLoot::new, LootContextParamSets.ENTITY),
Pair.of(MyChestLoot::new, LootContextParamSets.CHEST));
}
</syntaxhighlight>

The <code>validate</code> method needs to be overriden to eliminate the part of the vanilla code that verifies that the vanilla special loot tables have all been defined. If you have special loot tables (i.e. any loot table other than the main loot table for a block or entity), you may wish to add similar verification code here. The remaining code ensures that each table is consistent with the associated parameter set (e.g. that you're not trying to access a block state in an entity loot table).
<syntaxhighlight lang="java">
@Override
protected void validate(Map<ResourceLocation, LootTable> map, ValidationContext validationtracker) {
map.forEach((location, lootTable) -> LootTables.validate(validationtracker, location, lootTable);
}
</syntaxhighlight>

==Subproviders==
Each subprovider is a <code>Consumer<BiConsumer<ResourceLocation, LootTable.Builder>></code>. This is a fancy name that means that it has an accept function that is called with an argument containing another function that it can call with each loot table it wants to create.

Each vanilla subprovider is a class. BlockLoot and EntityLoot contain helper methods to ensure that every block or entity has a primary loot table and to help generate certain types of loot tables. BlockLoot in particular has a large collection of helper functions that are extremely useful for implementing standard forms of loot tables for block types such as ores, doors, slabs, crops, or any block that simply always drops itself as an item.

===Extending BlockLoot or EntityLoot===
If you are extending BlockLoot or EntityLoot, you will need to override the <code>addTables</code> and <code>getKnownBlocks</code> or <code>getKnownEntities</code> methods. From the <code>addTables</code> methods you will call the <code>add</code> method for each of the tables you wish to create (a handful of the helper functions in BlockLoot including <code>dropSelf</code> automatically add the tables they create).

<syntaxhighlight lang="java">
@Override
protected void addTables() {
dropSelf(ModBlocks.BLOCK1.get());
add(ModBlocks.BLOCK2.get(), ...);
}
</syntaxhighlight>

The second parameter to <code>BlockLoot.add</code> may be a function that accepts the Block and returns a LootTable.Builder, or the LootTable.Builder itself. Many of the helper functions in BlockLoot work this way. For <code>EntityLoot.add</code>, it must simply be the LootTable.Builder, but the first argument may be a ResourceLocation to create a special loot table rather than the primary loot table for the entity (this is used by vanilla for sheep colors).

You must override <code>getKnownBlocks</code> or <code>getKnownEntities</code>, respectively, to return only the blocks or entity types registered by your mod.
<syntaxhighlight lang="java">
@Override
protected Iterable<Block> getKnownBlocks() {
return ModBlocks.BLOCKS.getEntries().stream().map(RegistryObject::get).toList();
}
</syntaxhighlight>

===Implementing a simple subprovider===
The other vanilla subproviders don't have much worth extending for, so you can simply directly implement <code>Consumer<BiConsumer<ResourceLocation, LootTable.Builder>></code>.
<syntaxhighlight lang="java">
public void accept(BiConsumer<ResourceLocation, LootTable.Builder> consumer) {
consumer.accept({ResourceLocation}, {LootTable.Builder});
}
</syntaxhighlight>

===The LootTable Builder===
This is where you actually make a loot table. You start with an empty <code>LootPool.Builder</code> and add the necessary attributes to it.
* <code>.name</code> is used for the pool name.
* <code>.setRolls</code> is used for the amount.
* <code>.add</code> is used to add an <code>LootPoolEntryContainer$Builder</code>. You can have multiple entries.

A <code>LootPoolEntryContainer$Builder</code> defines what entry container is returned, and which functions and/or conditions are applied (see [https://minecraft.fandom.com/wiki/Loot_table Loot table] for the vanilla functions and conditions).
* <code>.when</code> is used to apply a condition. These themselves can have multiple operations.

After all attributes have been added the <code>LootPool.Builder</code> can be used to make a <code>LootTable.Builder</code>. This builder can then be used in the subproviders as discussed above.

The <code>LootContextParamSet</code> is automatically applied by the vanilla <code>LootTableProvider.run</code> method.
<syntaxhighlight lang="java">
LootPool.Builder poolBuilder = LootPool.lootPool()
.name(...)
.setRolls(...)
.add(LootItem.lootTableItem(...)
.apply(function1)
.apply(function2)
.when(condition1)
.when(condition2))
);
LootTable.Builder tableBuilder = LootTable.lootTable().withPool(poolBuilder);
</syntaxhighlight>[[Category:Data Generation]]

Dynamic Loot Modification

2022-09-20T17:52:56Z

Nexus-Dino: Update to 1.19 Codec GLMs

Global Loot Modifiers are a data-driven method of handling modification of harvested drops without the need to overwrite dozens to hundreds of vanilla loot tables or to handle effects that would require interactions with another mod's loot tables without knowing what mods may be loaded. Global Loot Modifiers are also stacking, rather than last-load-wins as modifications to loot tables would be.

== Registering a Global Loot Modifier ==

You will need 3 things:
# Create a <code>global_loot_modifiers.json</code> file at <code><nowiki>/data/forge/loot_modifiers/</nowiki></code>
#* This will tell Forge about your modifiers and works similar to [[Tags|tags]].
# A serialized json representing your modifier at <code><nowiki>/data/<modID>/loot_modifiers/</nowiki></code>
#* This will contain all of the data about your modification and allows data packs to tweak your effect.
# A class that extends <code>LootModifier</code>
#* The operational code that makes your modifier work and associated serializer.

Finally, the serializer for your operational class is [[Registration|registered]] as any other registry object.

==The global_loot_modifiers.json==
All you need to add here are the file names of your loot modifiers.
These are the names of the json files you have made in the loot_modifiers folder, in ResourceLocation format.

<syntaxhighlight lang="json">
{
"replace": false,
"entries": [
"global_loot_test:silk_touch_bamboo",
"global_loot_test:smelting",
"global_loot_test:wheat_harvest"
]
}
</syntaxhighlight>

<code>replace</code> causes the cache of modifiers to be cleared fully when this asset loads (mods are loaded in an order that may be specified by a data pack). For modders you will want to use <code>false</code> while data pack makers may want to specify their overrides with <code>true</code>.

<code>entries</code> is an ''ordered list'' of the modifiers that will be loaded. Any modifier that is not listed will not be loaded and the ones listed are called in the order listed. This is primarily relevant to data pack makers for resolving conflicts between modifiers from separate mods.

== The serialized json ==

This file contains all of the potential variables related to your modifier, including the conditions that must be met prior to modifying any loot as well as any other parameters your modifier might have. Avoid hard-coded values where ever possible so that data pack makers can adjust balance if they wish to.
<syntaxhighlight lang="json">
{
"conditions": [
{
"condition": "minecraft:match_tool",
"predicate": {
"item": "minecraft:shears"
}
},
{
"condition": "minecraft:block_state_property",
"block": "minecraft:wheat"
}
],
"seedItem": "minecraft:wheat_seeds",
"numSeeds": 3,
"replacement": "minecraft:wheat"
}
</syntaxhighlight>

In the above example, the modification only happens if the player harvests wheat when using shears (specified by the two <code>conditions</code> which are automatically <code>AND</code>ed together). The <code>seedsItem</code> and <code>numSeeds</code> values are then used to count how many seeds were generated by the vanilla loot table, and if matched, are substituted for an additional <code>replacement</code> item instead. The operation code will be shown below.

{{Tip|<code>conditions</code> is the only object needed by the system specification, everything else is the mod maker's data.

<code>seedItem</code>, <code>numSeeds</code> and <code>replacement</code> are NOT standard elements of Global Loot Modifiers.

They are deserialized manually in the next section.}}

== The LootModifier Subclass ==

You will also need a static child class that extends <code>GlobalLootModifierSerializer<T></code> where <code>T</code> is your LootModifier subclass in order to deserialize your json data file into operational code.

<syntaxhighlight lang="java">
/**
* When harvesting wheat with shears, this modifier is invoked via the wheat_harvest loot_modifier json<br/>
* This modifier checks how many seeds were harvested and turns X seeds into Y wheat (3:1)
*
*/
private static class WheatSeedsConverterModifier extends LootModifier
{
public static final Supplier<Codec<WheatSeedsConverterModifier>> CODEC = Suppliers.memoize(() ->
RecordCodecBuilder.create(inst -> codecStart(inst).and(
inst.group(
Codec.INT.fieldOf("numSeeds").forGetter(m -> m.numSeedsToConvert),
ForgeRegistries.ITEMS.getCodec().fieldOf("seedItem").forGetter(m -> m.itemToCheck),
ForgeRegistries.ITEMS.getCodec().fieldOf("replacement").forGetter(m -> m.itemReward)
)).apply(inst, WheatSeedsConverterModifier::new)
));

private final int numSeedsToConvert;
private final Item itemToCheck;
private final Item itemReward;
public WheatSeedsConverterModifier(LootItemCondition[] conditionsIn, int numSeeds, Item itemCheck,
Item reward)
{
super(conditionsIn);
numSeedsToConvert = numSeeds;
itemToCheck = itemCheck;
itemReward = reward;
}

@NotNull
@Override
public ObjectArrayList<ItemStack> doApply(ObjectArrayList<ItemStack> generatedLoot, LootContext context) {
//
// Additional conditions can be checked, though as much as possible should be parameterized via JSON data.
// It is better to write a new ILootCondition implementation than to do things here.
//
int numSeeds = 0;
generatedLoot.stream().filter(stack -> stack.getItem() == itemToCheck)
.forEach(stack -> numSeeds+=stack.getCount())
if(numSeeds >= numSeedsToConvert) {
generatedLoot.removeIf(x -> x.getItem() == itemToCheck);
generatedLoot.add(new ItemStack(itemReward, (numSeeds/numSeedsToConvert)));
numSeeds = numSeeds%numSeedsToConvert;
if(numSeeds > 0)
generatedLoot.add(new ItemStack(itemToCheck, numSeeds));
}
return generatedLoot;
}

@Override
public Codec<? extends IGlobalLootModifier> codec() {
return CODEC.get();
}
}
</syntaxhighlight>

The critical portion is the <code>doApply</code> method.

This method is only called if the <code>conditions</code> specified return <code>true</code> and the modder is now able to make the modifications they desire. In this case we can see that the number of <code>itemToCheck</code> meets or exceeds the <code>numSeedsToConvert</code> before modifying the list by adding an <code>itemReward</code> and removing any excess <code>itemToCheck</code> stacks, matching the previously mentioned effects: ''When a wheat block is harvested with shears, if enough seeds are generated as loot, they are converted to additional wheat instead''.

Utilize <code>GlobalLootModifierProvider</code> for [[datageneration|data generation]].

Additional [https://github.com/MinecraftForge/MinecraftForge/blob/1.19.x/src/test/java/net/minecraftforge/debug/gameplay/loot/GlobalLootModifiersTest.java examples] can be found on the Forge Git repository, including silk touch and smelting effects.