Forge Community Wiki - User contributions [en-gb]

Codecs

2024-01-10T18:20:14Z

TheSilkMiner: Keep the only change made by Blabliblubpaul that made sense

Codecs are a serialization tool from mojang's DataFixerUpper library. Codecs are used alongside [[DynamicOps|DynamicOps]] to allow objects to be serialized to different formats and back, such as JSON or [[Using_NBT|NBT]]. While the DynamicOps describes the format the object is to be serialized to, the Codec describes the manner in which the object is to be serialized; a single Codec can be used to serialize an object to any format for which a DynamicOps exists. Codecs and DynamicOps jointly form an abstraction layer over data serialization, simplifying the effort needed to serialize or deserialize data.

= Using Codecs =

== Serialization and Deserialization ==

The primary use for Codecs is to serialize java objects to some serialized type, such as a JsonElement or a Tag, and to deserialize a serialized object back to its proper java type. This is accomplished with <code>Codec#encodeStart</code> and <code>Codec#parse</code>, respectively. Given a Codec<SomeJavaType> and a DynamicOps<SomeSerializedType>, we can convert instances of SomeJavaType to instances of SomeSerializedType and back.

Each of these methods take a [[DynamicOps]] instance and an instance of the object we are serializing or deserializing, and returns a DataResult:

<syntaxhighlight lang="java">
// let someCodec be a Codec<SomeJavaType>
// let someJavaObject be an instance of SomeJavaType
// let someTag and someJsonElement be instances of Tag and JsonElement, respectively

// serialize some java object to Tag
DataResult<Tag> result = someCodec.encodeStart(NBTOps.INSTANCE, someJavaObject);

// deserialize some Tag instance back to a proper java object
DataResult<SomeJavaType> result = someCodec.parse(NBTOps.INSTANCE, someTag);

// serialize some java object to a JsonElement
DataResult<JsonElement> result = someCodec.encodeStart(JsonOps.INSTANCE, someJavaObject);

// deserialize a JsonElement back to a proper java object
DataResult<SomeJavaType> result = someCodec.parse(JsonOps.INSTANCE, someJsonElement);
</syntaxhighlight>

A DataResult either holds the converted instance, or it holds some error data, depending on whether the conversion was successful or not, respectively. There are several things we can do with this DataResult; <code>DataResult#result</code> simply returns an Optional containing the converted object if the conversion was successful, while <code>DataResult#resultOrPartial</code> also runs a given function if the conversion was unsuccessful (in addition to returning the Optional). #resultOrPartial is particularly useful for logging errors during datapack deserialization:

<syntaxhighlight lang="java">
// deserialize something from json
someCodec.parse(JsonOps.INSTANCE, someJsonElement)
.resultOrPartial(errorMessage -> doSomethingIfBadData(errorMessage))
.ifPresent(someJavaObject -> doSomethingIfGoodData(someJavaObject))
</syntaxhighlight>

== Builtin Codecs ==
=== Primitive Codecs ===
The Codec class itself contains static instances of codecs for all supported primitive types, e.g. <code>Codec.STRING</code> is the canonical <code>Codec<String></code> implementation. Primitive codecs include:
* BOOL, which serializes to a boolean value
* BYTE, SHORT, INT, LONG, FLOAT, and DOUBLE, which serialize to numeric values
* STRING, which serializes to a string
* BYTE_BUFFER, INT_STREAM, and LONG_STREAM, which serialize to lists of numbers
* EMPTY, which represents null objects

=== Other Builtin Codecs ===
Vanilla minecraft has many builtin codecs for objects that it frequently serializes. These codecs are typically static instances in the class the codec is serializing; e.g. <code>ResourceLocation.CODEC</code> is the canonical <code>Codec<ResourceLocation></code>, while <code>BlockPos.CODEC</code> is the codec used for serializing a BlockPos.

Each vanilla <code>Registry</code> acts as the Codec for the type of object the registry contains; e.g. <code>Registry.BLOCK</code> is itself a <code>Codec<Block></code>. Forge Registries, however, do not currently implement Codec and cannot yet be used in this way; custom codecs must be created for forge-specific registries that are not tied to specific vanilla registries.

Of particular note here is the CompoundTag.CODEC, which can be used to e.g. serialize a CompoundTag into a json file. This has a notable limitation in that CompoundTag.CODEC *cannot* safely deserialize lists of numbers from json, due to the strong typing of ListTag and the way that the NBTOps deserializer reads numeric values.

= Creating Codecs =

Suppose we have the following class, and we want to deserialize json files to instances of this class:
<syntaxhighlight lang="java">
public class ExampleCodecClass {

private final int someInt;
private final Item item;
private final List<BlockPos> blockPositions;

public ExampleCodecClass(int someInt, Item item, List<BlockPos> blockPositions) {...}

public int getSomeInt() { return this.someInt; }
public Item getItem() { return this.item; }
public List<BlockPos> getBlockPositions() { return this.blockPositions; }
}
</syntaxhighlight>

Where a json file for an instance of this class might look like:

<syntaxhighlight lang="json">
{
"some_int": 42,
"item": "minecraft:gold_ingot",
"block_positions":
[
[0,0,0],
[10,20,-100]
]
}
</syntaxhighlight>

We can assemble a codec for this class by building a new codec out of smaller codecs. We'll need a codec for each of these fields:
* a <code>Codec<Integer></code>
* a <code>Codec<Item></code>
* a <code>Codec<List<BlockPos>></code>
And then we'll need to assemble these into a <code>Codec<ExampleCodecClass></code>.

As previously mentioned, we can use <code>Codec.INT</code> for the integer codec, and <code>Registry.ITEM</code> for the Item codec. We don't have a builtin codec for list-of-blockpos, but we can use BlockPos.CODEC to create one.

== Lists ==
The <code>Codec#listOf</code> instance method can be used to generate a codec for a List from an existing codec:

<syntaxhighlight lang="java">
// BlockPos.CODEC is a Codec<BlockPos>
Codec<List<BlockPos>> = BlockPos.CODEC.listOf();
</syntaxhighlight>

Codecs created via listOf() serialize things to listlike objects, such as [] json arrays or ListTags.

Deserializing a list in this manner produces an ''immutable'' list. If a mutable list is needed, [[Codecs#Equivalent_Types_and_xmap|xmap]] can be used to convert the list after deserializing.

== Records ==
RecordCodecBuilder is used to generate codecs that serialize instances of classes with explicitly named fields, like our example above. Codecs created via RecordCodecBuilder serialize things to maplike objects, such as {} json objects or CompoundTags.

RecordCodecBuilder can be used in several ways, but the simplest form is as follows:

<syntaxhighlight lang="java">
public static final Codec<SomeJavaClass> = RecordCodecBuilder.create(instance -> instance.group(
someFieldCodecA.fieldOf("field_name_a").forGetter(SomeJavaClass::getFieldA),
someFieldCodecB.fieldOf("field_name_b").forGetter(SomeJavaClass::getFieldB),
someFieldCodecC.fieldOf("field_name_c").forGetter(SomeJavaClass::getFieldC),
// up to 16 fields can be declared here
).apply(instance, SomeJavaClass::new));
</syntaxhighlight>

Where each line in the group specifies a codec instance for the type of that field, the field name in the serialized object, and the corresponding getter function in the java class. The builder is concluded by specifying a constructor or factory for the java class whose arguments are the previously defined fields in the same order.

For example, using RecordCodecBuilder to create a codec for our example class above:
<syntaxhighlight lang="java">
public static final Codec<ExampleCodecClass> = RecordCodecBuilder.create(instance -> instance.group(
Codec.INT.fieldOf("some_int").forGetter(ExampleCodecClass::getSomeInt),
Registry.ITEM.fieldOf("item").forGetter(ExampleCodecClass::getItem),
BlockPos.CODEC.listOf().fieldOf("block_positions").forGetter(ExampleCodecClass::getBlockPositions)
).apply(instance, ExampleCodecClass::new));
</syntaxhighlight>

===Optional and Default Values in Record Fields===
When RecordCodecBuilder is used as shown above, all of the fields are *required* to be in the serialized object (the JsonObject/CompoundTag/etc), or the entire thing will fail to parse when the codec tries to deserialize it. If we wish to have optional or default values, we have several alternatives of fieldOf() we can use.

* <code>someCodec.optionalFieldOf("field_name")</code> creates a field for an Optional. If the field in the json/nbt is not present or invalid, it will deserialize as an empty optional. Empty optionals will not be serialized; the field will be omitted from the json or nbt.
* <code>someCodec.optionalFieldOf("field_name", someDefaultValue)</code> creates an optional field that deserializes as the given default value if the field is not present in the json/nbt. When serializing, if the field in the java object equals the default value, the value will not be serialized and the field will be omitted from the json or nbt.

When using optional fields, be wary that if the field contains bad data or otherwise fails to serialize, the error will be silently caught, and the field will serialize as the default value instead!

===Boxing values as objects===
In some situations, we may need to serialize a single value as a single-field object. We can use fieldOf to box a single value in this way without needing the entire RecordCodecBuilder process:

<syntaxhighlight lang="java">
public static final Codec<Integer> BOXED_INT_CODEC = Codec.INT.fieldOf("value").codec();

JsonElement value = BOXED_INT_CODEC.encodeStart(JsonOps.INSTANCE, 5).result().get();
</syntaxhighlight>

Which serializes the following output:

<syntaxhighlight lang="json">
{"value":5}
</syntaxhighlight>

==Unit==
The <code>Codec.unit(defaultValue)</code> codec creates a Codec that always deserializes a specified default value, regardless of input. When serializing, it serializes nothing.

==Pair==
The <code>Codec.pair(codecA, codecB)</code> static method takes two codecs and generates a Codec<Pair<A,B>> from them.

The only valid arguments for this method are codecs that serialize to objects with explicit fields, such as codecs created using [[Codecs#Records|RecordCodecBuilder]] or [[Codecs#Boxing_values_as_objects|fieldOf]]. Codecs that serialize nothing (such as [[Codecs#Unit|unit codecs]]) are also valid as they act as objects-with-no-fields.

The resulting Pair codec will serialize a single object that has all of the fields of the two original codecs. For example:
<syntaxhighlight lang="java">
public static final Codec<Pair<Integer,String>> PAIR_CODEC = Codec.pair(
Codec.INT.fieldOf("value").codec(),
Codec.STRING.fieldOf("name").codec());

JsonElement encodedPair = PAIR_CODEC.encodeStart(JsonOps.INSTANCE, Pair.of(5, "cheese").result().get();
</syntaxhighlight>
This codec serializes the above value to:
<syntaxhighlight lang="json">
{
"value": 5,
"name": "cheese"
}
</syntaxhighlight>

Codecs that serialize to objects with undefined fields such as [[Codecs#Maps|unboundedMap]] may cause strange and unpredictable behaviour when used here; these objects should be boxed via fieldOf when used in a pair codec.

==Either==
The <code>Codec.either(codecA, codecB)</code> static method takes two codecs and generates a Codec<Either<A,B>> from them.

When this codec is used to de/serialize an object, it first attempts to use the first codec; if and only if that conversion fails, it then attempts to use the second codec. If that conversion also fails, then the returned DataResult will contain the error data from the *second* codec's conversion attempt.

==Numeric Ranges==
The <code>Codec.intRange(min,max)</code>, <code>Codec.floatRange(min,max)</code>, and <code>Codec.doubleRange(min,max)</code> static methods generate Codecs for Integers, Floats, or Doubles, respectively, for which only a specified inclusive range is valid, and values outside that range will fail to de/serialize.

==Maps==
Suppose we want to serialize a HashMap or other Map type, where we could have indefinitely many key-value pairs and we don't know what the keys are ahead of time.

We can create a <code>Codec<Map<KEY,VALUE>></code> using the <code>Codec.unboundedMap</code> static method, which takes a key codec and a value codec and creates a codec for a map type:

<syntaxhighlight lang="java">
public static final Codec<Map<String, BlockPos>> = Codec.unboundedMap(Codec.STRING, BlockPos.CODEC);
</syntaxhighlight>

The serialized form of maps serialized by this codec will be a JsonObject or CompoundTag, whose fields are the key-value pairs in the map; the map's keys will be used as the field names, and the map's values will be the values of those fields

A limitation of using unboundedMap is that it only supports key codecs that serialize to Strings (including codecs for things like ResourceLocation that aren't Strings themselves but still serialize to strings). To create a codec for a Map whose keys are not fundamentally strings, the Map must be serialized as a list of key-value pairs instead of using unboundedMap.

==Equivalent Types and xmap==
Suppose we have two java classes, Amalgam and Box; any Amalgam instance can be converted to a Box, and vice-versa. Now suppose we have a Codec<Amalgam>, but we'd also like to have a Codec<Box>. Rather than creating an entirely new codec for Box from scratch, we can simply xmap our Amalgam codec instead.

The <code>Codec#xmap</code> instance method is used to generate a second codec for a fundamentally equivalent type to the first codec's type. The method takes two function objects as arguments, which are used to convert the first type to the second when deserializing, and converting the second type to the first when serializing:

<syntaxhighlight lang="java">
public static final Codec<Box> = Amalgam.CODEC.xmap(Amalgam::toBox, Box::toAmalgam);
</syntaxhighlight>

Codecs created in this manner will serialize objects in the same format as the starting codec.

==Partially Equivalent Types, flatComapMap, comapFlatMap, and flatXMap==
Consider the ResourceLocation: Any ResourceLocation can be converted to a String, but not all Strings can be converted to a ResourceLocation; ResourceLocations have strict limits on their format and allowed characters.

While we *could* use xmap to convert the Codec.STRING to a codec for ResourceLocations, this would cause attempts to parse an invalid string like <code>SHOUTY:MOD:Invalid$Characters</code> to throw a runtime exception, when we really should be returning a failed DataResult to the parser instead -- which indeed is what the vanilla ResourceLocation codec does.

Codecs have three additional instance methods for creating equivalent codecs for when we can *potentially* convert one type to another, but are not guaranteed to be able to do so. These take conversion function arguments that return DataResults, allowing validation to be performed during serialization and deserialization.

{| class="wikitable"
|+ Codec Conversion Methods
|-
! Can A always be converted to B? !! Can B always be converted to A? !! Which method of codecA should be used to create codecB?
|-
| yes || yes || codecA.xmap
|-
| yes || no || codecA.flatComapMap
|-
| no || yes || codecA.comapFlatMap
|-
| no || no || codecA.flatXmap
|}

== Registry Dispatch ==
Registry Dispatch Codecs allow us to define a registry of codecs and delegate to a specific codec to deserialize a particular json based on a type field in that json. Dispatch codecs are used extensively when deserializing worldgen data.

To create a dispatch codec for a Thing class, the following steps can be performed:
# Create a Thing abstract class class and ThingType interface. The ThingType interface should have a method that supplies a Codec<Thing>, while Thing subclasses must define a method that supplies a ThingType.
# Create a map or registry of ThingTypes, and register a ThingType for each sub-codec we want to have.
# Create a Codec<ThingType>, or have the ThingType registry implement Codec.
# Create our Codec<Thing> master codec by invoking <code>Codec#dispatch</code> on our ThingType codec. This method's arguments are:
## A field name for the ID of the sub-codec (the example json below is using "type")
## A function to retrieve a ThingType from a Thing
## A function to retrieve a Codec<Thing> from a ThingType

We can then use our Codec<Thing> to create Thing fields in other codecs whose serialized format depends on the specific sub-codec used by a Thing instance.

As an example of this, consider the ExampleCodecClass earlier. Suppose we make this class extend Thing and register our codec for it to a codec dispatch registry with the id "ourmod:exampleclass". If we were to define an instance of this class in a Thing field in some json, it would look like

<syntaxhighlight lang="json">
"some_thing":
{
"type": "ourmod:exampleclass",
"some_int": 42,
"item": "minecraft:gold_ingot",
"block_positions":
[
[0,0,0],
[10,20,-100]
]
}
</syntaxhighlight>

Other ThingTypes we register would have different fields in this json object, but would still be valid for the "some_thing" field.

Several examples of vanilla classes that use dispatch codecs:
* RuleTest and RuleTestType
* BlockPlacer and BlockPlacerType
* ConfiguredDecorator and FeatureDecorator

=== Registering MapCodecCodecs for Dispatch Subcodecs ===

When registering a subcodec to any dispatch codec registry, the registered subcodec should be an instance of MapCodecCodec, or the subcodec will be nested in its own object when serialized.

For example, suppose we register a single-field subcodec, where we use fieldOf-and-xmap to convert an int to our int-holding Thing:

<syntaxhighlight lang="java">
public record Thing(int n){}
public static Codec<Thing> CODEC = Codec.INT.fieldOf("n").codec().xmap(Thing::new, Thing::n);
</syntaxhighlight>

This results in this json when serialized:

<syntaxhighlight lang="json">
"some_thing":
{
"type": "ourmod:thing",
"value": {
"n": 5
}
}
</syntaxhighlight>

This occurs because xmap does not produce a MapCodecCodec, and if this nested object is not desired, then our registered subcodec must be a MapCodecCodec.

However, fieldOf() produces a MapCodec, which has a codec() method, which does produce a MapCodecCodec. We can rearrange our codec builder, which then produces a cleaner json:

<syntaxhighlight lang="java">
public static Codec<Thing> CODEC = Codec.INT // Primitive codec
.fieldOf("n") // MapCodec
.xmap(Thing::new, Thing::n) // MapCodec
.codec(); // MapCodecCodec! That's what we want.
</syntaxhighlight>

<syntaxhighlight lang="json">
"some_thing":
{
"type": "ourmod:thing",
"n": 5
}
</syntaxhighlight>

RecordCodecBuilder also produces MapCodecCodecs.

=External Links=
* [https://github.com/Mojang/DataFixerUpper/blob/master/src/main/java/com/mojang/serialization/Codec.java Codecs in Mojang's official public DataFixerUpper repository]
* [https://kvverti.github.io/Documented-DataFixerUpper/snapshot/com/mojang/serialization/Codec.html#flatXmap-java.util.function.Function-java.util.function.Function- Unofficial Codec Javadocs]

Datagen

2023-03-30T13:57:26Z

TheSilkMiner: Create redirect to Datageneration page

#REDIRECT [[Datageneration]]

User:TheSilkMiner/Capabilities

2021-05-06T08:28:58Z

TheSilkMiner: Redirect to actual page; we don't want to break links that are already bookmarked or shared around

#REDIRECT [[Capabilities]]

Capabilities

2021-05-06T08:27:10Z

TheSilkMiner: Rewrite Capability documentation to be better in documenting stuff

'''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; one of the various implementations may also be considered the '''default capability implementation'''.
; Capability Storage
: the manager that handles loading and storing persistent capabilities data from and to disk, guaranteeing preservation of information; in-code this is represented by an implementation of the <code>Capability.IStorage</code> interface.

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>TileEntity</code>, <code>Entity</code>,
<code>ItemStack</code>, <code>World</code>, and <code>Chunk</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>, <code>IEnergyStorage</code>, and
<code>IAnimationStateMachine</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>IInventory</code> and <code>ISidedInventory</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>LockableLootTileEntity</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 referes 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>.

=== <tt>IAnimationStateMachine</tt> ===

The <code>IAnimationStateMachine</code> capability refers to the ability for any capability provider to leverage the
Forge Animation State Machine API for animations.

== 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. Since these objects are created by Forge and there is only '''one''' unique instance for each capability that
may exist, this instance cannot be obtained by "common" means. Forge provides two different methods of obtaining such
instances: '''injecting''' into a field, or a '''callback method'''.

==== Injecting into a Field ====

A <code>Capability</code> can be injected automatically into a field as soon as it gets created by Forge, following the
principle commonly known as '''dependency injection'''. This provides less flexibility, since it doesn't notify the user
that the capability has been injected nor runs arbitrary code. Nevertheless, it is '''suggested''' to use this method
instead of the callback approach.

To inject the <code>Capability</code> into a field, all that's needed is to declare a <code>static</code> field of type
<code>Capability<T></code>, where <code>T</code> represents the capability interface, and annotate it with
<code>@CapabilityInject(T.class)</code>.

For a more practical example, consider the following snippet:

<syntaxhighlight lang="java">
@CapabilityInject(IItemHandler.class)
public static Capability<IItemHandler> ITEM_HANDLER_CAPABILITY = null;
</syntaxhighlight>

The above code will let Forge know that the field <code>ITEM_HANDLER_CAPABILITY</code> should be injected with the
unique instance of the <code>IItemHandler</code> capability. Assigning the field to <code>null</code> allows us to
provide a reasonable fallback in case the capability we want hasn't been registered yet.

This injection is, for obvious reasons, redundant, since that capability is also available through
<code>CapabilityItemHandler</code>.

==== Declaring a Callback ====

Another option is to declare a callback method, meaning a method that will be called with the value of the desired
<code>Capability</code> once the instance is available. This gives more flexibility since the method may perform a
number of arbitrary actions with the received instance prior to storing it in a field, or may even discard the
capability entirely if wanted. Nevertheless, the usage of a field instead of a method is encouraged as a matter of
style.

To use a method as a callback, the method must be declared as <code>static</code> and accepting a single parameter of
type <code>Capability<T></code>, where <code>T</code> represents the capability interface. The method should also
be annotated with <code>@CapabilityInject(T.class)</code>.

For a more practical example, consider the following snippet:

<syntaxhighlight lang="java">
public static Capability<IEnergyStorage> ENERGY = null;

@CapabilityInject(IEnergyStorage.class)
private static void onEnergyStorageInit(Capability<IEnergyStorage> capability) {
LOGGER.info("Received IEnergyStorage capability '{}': enabling Forge Energy support", capability);
ENERGY = capability;
}
</syntaxhighlight>

The above code declares a callback method that will be invoked when a <code>Capability</code> instance for
<code>IEnergyStorage</code> is available. The callback then prints a log message and stores the capability into a
<code>public</code> field for accessibility. The field is initialized to <code>null</code> to provide a reasonable
fallback in case the capability does not exist.

This callback is, for obvious reasons, redundant, since that capability is also available through
<code>CapabilityEnergy</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 final LazyOptional<IItemhandler> inventoryOptional = LazyOptional.of(() -> this.inventory);

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

@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>TileEntity</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>TileEntity</code>, this usually happens when the block gets removed from the world 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>MyTileEntity</code>,
which extends <code>TileEntity</code>, you'll have to listen to <code>AttachCapabilitiesEvent<TileEntity></code>,
'''NOT''' to <code>AttachCapabilitiesEvent<MyTileEntity></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<TileEntity> event) {
if (!(event.getObject() instanceof EnergyBasedTileEntity)) return;

EnergyStorage backend = new EnergyStorage(((EnergyBasedTileEntity) 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 == CapabilityEnergy.ENERGY) {
return optionalStorage.cast();
}
return LazyOptional.empty();
}
};

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

This example implementation of an attaching agent attaches a <code>IEnergyStorage</code> capability to all
<code>TileEntity</code> instance that are a subclass of <code>EnergyBasedTileEntity</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<TileEntity> event) {
if (!(event.getObject() instanceof EnergyBasedTileEntity)) return;

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

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

@Override
public IntNBT serializeNBT() {
return capability.getStorage().writeNbt(capability, backend, null);
}

@Override
public void deserializeNBT(IntNBT nbt) {
capability.getStorage().readNBT(capability, backend, null, nbt);
}
};

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

=== 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">
private final Map<Direction, LazyOptional<IEnergyStorage>> cache = new HashMap<>();

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

if (targetCapability == null) {
ICapabilityProvider provider = world.getTileEntity(pos.offset(direction));
targetCapability = provider.getCapability(CapabilityEnergy.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>TileEntity</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 three main components: the Capability Interface, at least one
Capability Implementation, and the Capability Storage. Optionally, a 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, but no less than one.

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>).

One of the various Capability Implementation should also act as the default implementation. Other mods can ask the
capability to create an instance of the default implementation without ever referring to such an implementation
themselves. This guarantees separation of API code from implementation code, which is also one of the goals of the
capability system.

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, which will also act as the default implementation for
the <code>MyCapability</code> capability.

=== The Capability Storage ===

The Capability Storage is that component of the Capability System that is responsible for serializing and deserializing
a capability. All capabilities must provide one, since certain providers may or may not require that their capabilities
are serializable.

The Capability Storage implements the <code>Capability.IStorage<T></code> interface, where <code>T</code> is the
generic type of the Capability Interface the storage refers to. Each capability must have '''one and exactly one'''
Capability Storage.

The Storage is usually called by the Capability Provider when serialization or deserialization needs to happen. The
Storage is then responsible of reading the data from the given capability instance and convert that into an NBT-based
structure that can be serialized. A Storage may also return <code>null</code> to indicate that no serialization is
necessary, although some providers may require an empty tag to be supplied instead. At the same time, the Storage is
also responsible for restoring the original state of the capability when deserialization happens. In this case, the
given NBT structure is guaranteed not to be <code>null</code>.

In all cases, a <code>Direction</code> is provided for context, if available.

Although discouraged as a matter of code cleanliness, it is legal for a Capability Storage to require a specific
Capability Implementation for the serialization and deserialization to be successful. If this is the case, this
requirement '''must''' be documented, though the code should be refactored wherever possible to remove this requirement.

Given the above information, an example of an implementation of a Capability Storage may be the following:

<syntaxhighlight lang="java">
public class MyCapabilityStorage implements Capability.IStorage<MyCapability> {
@Override
@Nullable
INBT writeNBT(Capability<MyCapability> capability, MyCapability instance, Direction direction) {
return StringNBT.valueOf(instance.getValue());
}

@Override
public void readNBT(Capability<MyCapability> capability, MyCapability instance, Direction direction, INBT nbtData) {
if (!(nbtData instanceof StringNBT)) {
throw new IllegalArgumentException("Unable to deserialize 'MyCapability' from a non-String NBT structure");
}
instance.setValue(((StringNBT) nbtData).getString());
}
}
</syntaxhighlight>

Note the <code>instanceof</code> check needed to ensure that the given <code>INBT</code> instance is valid for
deserialization. A Capability Storage should always perform this check prior to the cast in order to provide a
meaningful error message, rather than a cryptic <code>ClassCastException</code>.

=== 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 the Capability Interface, the Capability Storage, and a
factory for the default capability implementation.

The registration can be performed by calling the <code>register</code> method on the <code>CapabilityManager</code>.
This '''needs''' to happen when the <code>FMLCommonSetupEvent</code> 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">
public void onCommonSetup(FMLCommonSetupEvent event) {
CapabilityManager.INSTANCE.register(MyCapability.class, new MyCapabilityStorage(), MyCapabilityImplementation::new);
}
</syntaxhighlight>

== 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>TileEntity</code> or <code>Chunk</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/TheSilkMiner/5cc92ba573e7bdd871dfdbffdd5c2806 A Gist showing a quick and dirty example on how to implement a Capability effectively]

User:TheSilkMiner/Capabilities

2021-05-06T08:26:12Z

TheSilkMiner: client -> user

User:TheSilkMiner/Capabilities

2021-05-01T20:40:47Z

TheSilkMiner: Finish Capability docs

'''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; one of the various implementations may also be considered the '''default capability implementation'''.
; Capability Storage
: the manager that handles loading and storing persistent capabilities data from and to disk, guaranteeing preservation of information; in-code this is represented by an implementation of the <code>Capability.IStorage</code> interface.

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>TileEntity</code>, <code>Entity</code>,
<code>ItemStack</code>, <code>World</code>, and <code>Chunk</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>, <code>IEnergyStorage</code>, and
<code>IAnimationStateMachine</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>IInventory</code> and <code>ISidedInventory</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>LockableLootTileEntity</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 referes 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>.

=== <tt>IAnimationStateMachine</tt> ===

The <code>IAnimationStateMachine</code> capability refers to the ability for any capability provider to leverage the
Forge Animation State Machine API for animations.

== 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''',
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. Since these objects are created by Forge and there is only '''one''' unique instance for each capability that
may exist, this instance cannot be obtained by "common" means. Forge provides two different methods of obtaining such
instances: '''injecting''' into a field, or a '''callback method'''.

==== Injecting into a Field ====

A <code>Capability</code> can be injected automatically into a field as soon as it gets created by Forge, following the
principle commonly known as '''dependency injection'''. This provides less flexibility, since it doesn't notify the user
that the capability has been injected nor runs arbitrary code. Nevertheless, it is '''suggested''' to use this method
instead of the callback approach.

To inject the <code>Capability</code> into a field, all that's needed is to declare a <code>static</code> field of type
<code>Capability<T></code>, where <code>T</code> represents the capability interface, and annotate it with
<code>@CapabilityInject(T.class)</code>.

For a more practical example, consider the following snippet:

<syntaxhighlight lang="java">
@CapabilityInject(IItemHandler.class)
public static Capability<IItemHandler> ITEM_HANDLER_CAPABILITY = null;
</syntaxhighlight>

The above code will let Forge know that the field <code>ITEM_HANDLER_CAPABILITY</code> should be injected with the
unique instance of the <code>IItemHandler</code> capability. Assigning the field to <code>null</code> allows us to
provide a reasonable fallback in case the capability we want hasn't been registered yet.

This injection is, for obvious reasons, redundant, since that capability is also available through
<code>CapabilityItemHandler</code>.

==== Declaring a Callback ====

Another option is to declare a callback method, meaning a method that will be called with the value of the desired
<code>Capability</code> once the instance is available. This gives more flexibility since the method may perform a
number of arbitrary actions with the received instance prior to storing it in a field, or may even discard the
capability entirely if wanted. Nevertheless, the usage of a field instead of a method is encouraged as a matter of
style.

To use a method as a callback, the method must be declared as <code>static</code> and accepting a single parameter of
type <code>Capability<T></code>, where <code>T</code> represents the capability interface. The method should also
be annotated with <code>@CapabilityInject(T.class)</code>.

For a more practical example, consider the following snippet:

<syntaxhighlight lang="java">
public static Capability<IEnergyStorage> ENERGY = null;

@CapabilityInject(IEnergyStorage.class)
private static void onEnergyStorageInit(Capability<IEnergyStorage> capability) {
LOGGER.info("Received IEnergyStorage capability '{}': enabling Forge Energy support", capability);
ENERGY = capability;
}
</syntaxhighlight>

The above code declares a callback method that will be invoked when a <code>Capability</code> instance for
<code>IEnergyStorage</code> is available. The callback then prints a log message and stores the capability into a
<code>public</code> field for accessibility. The field is initialized to <code>null</code> to provide a reasonable
fallback in case the capability does not exist.

This callback is, for obvious reasons, redundant, since that capability is also available through
<code>CapabilityEnergy</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 clients.

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 final LazyOptional<IItemhandler> inventoryOptional = LazyOptional.of(() -> this.inventory);

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

@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>TileEntity</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>TileEntity</code>, this usually happens when the block gets removed from the world 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>MyTileEntity</code>,
which extends <code>TileEntity</code>, you'll have to listen to <code>AttachCapabilitiesEvent<TileEntity></code>,
'''NOT''' to <code>AttachCapabilitiesEvent<MyTileEntity></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.

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<TileEntity> event) {
if (!(event.getObject() instanceof EnergyBasedTileEntity)) return;

EnergyStorage backend = new EnergyStorage(((EnergyBasedTileEntity) 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 == CapabilityEnergy.ENERGY) {
return optionalStorage.cast();
}
return LazyOptional.empty();
}
};

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

This example implementation of an attaching agent attaches a <code>IEnergyStorage</code> capability to all
<code>TileEntity</code> instance that are a subclass of <code>EnergyBasedTileEntity</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<TileEntity> event) {
if (!(event.getObject() instanceof EnergyBasedTileEntity)) return;

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

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

@Override
public IntNBT serializeNBT() {
return capability.getStorage().writeNbt(capability, backend, null);
}

@Override
public void deserializeNBT(IntNBT nbt) {
capability.getStorage().readNBT(capability, backend, null, nbt);
}
};

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

=== Accessing a Capability ===

Accessing a Capability is the process by which a client 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 client 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 client 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 client should thus register itself to the invalidation listener via the
<code>addListener</code> method. This ensures that the client 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 a client may be similar to the following snippet of code:

<syntaxhighlight lang="java">
private final Map<Direction, LazyOptional<IEnergyStorage>> cache = new HashMap<>();

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

if (targetCapability == null) {
ICapabilityProvider provider = world.getTileEntity(pos.offset(direction));
targetCapability = provider.getCapability(CapabilityEnergy.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 a client is querying via a <code>TileEntity</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 three main components: the Capability Interface, at least one
Capability Implementation, and the Capability Storage. Optionally, a 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, but no less than one.

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>).

One of the various Capability Implementation should also act as the default implementation. Other mods can ask the
capability to create an instance of the default implementation without ever referring to such an implementation
themselves. This guarantees separation of API code from implementation code, which is also one of the goals of the
capability system.

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, which will also act as the default implementation for
the <code>MyCapability</code> capability.

=== The Capability Storage ===

The Capability Storage is that component of the Capability System that is responsible for serializing and deserializing
a capability. All capabilities must provide one, since certain providers may or may not require that their capabilities
are serializable.

The Capability Storage implements the <code>Capability.IStorage<T></code> interface, where <code>T</code> is the
generic type of the Capability Interface the storage refers to. Each capability must have '''one and exactly one'''
Capability Storage.

The Storage is usually called by the Capability Provider when serialization or deserialization needs to happen. The
Storage is then responsible of reading the data from the given capability instance and convert that into an NBT-based
structure that can be serialized. A Storage may also return <code>null</code> to indicate that no serialization is
necessary, although some providers may require an empty tag to be supplied instead. At the same time, the Storage is
also responsible for restoring the original state of the capability when deserialization happens. In this case, the
given NBT structure is guaranteed not to be <code>null</code>.

In all cases, a <code>Direction</code> is provided for context, if available.

Although discouraged as a matter of code cleanliness, it is legal for a Capability Storage to require a specific
Capability Implementation for the serialization and deserialization to be successful. If this is the case, this
requirement '''must''' be documented, though the code should be refactored wherever possible to remove this requirement.

Given the above information, an example of an implementation of a Capability Storage may be the following:

<syntaxhighlight lang="java">
public class MyCapabilityStorage implements Capability.IStorage<MyCapability> {
@Override
@Nullable
INBT writeNBT(Capability<MyCapability> capability, MyCapability instance, Direction direction) {
return StringNBT.valueOf(instance.getValue());
}

@Override
public void readNBT(Capability<MyCapability> capability, MyCapability instance, Direction direction, INBT nbtData) {
if (!(nbtData instanceof StringNBT)) {
throw new IllegalArgumentException("Unable to deserialize 'MyCapability' from a non-String NBT structure");
}
instance.setValue(((StringNBT) nbtData).getString());
}
}
</syntaxhighlight>

Note the <code>instanceof</code> check needed to ensure that the given <code>INBT</code> instance is valid for
deserialization. A Capability Storage should always perform this check prior to the cast in order to provide a
meaningful error message, rather than a cryptic <code>ClassCastException</code>.

=== 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 the Capability Interface, the Capability Storage, and a
factory for the default capability implementation.

The registration can be performed by calling the <code>register</code> method on the <code>CapabilityManager</code>.
This '''needs''' to happen when the <code>FMLCommonSetupEvent</code> 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">
public void onCommonSetup(FMLCommonSetupEvent event) {
CapabilityManager.INSTANCE.register(MyCapability.class, new MyCapabilityStorage(), MyCapabilityImplementation::new);
}
</syntaxhighlight>

== 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 clients 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>TileEntity</code> or <code>Chunk</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/TheSilkMiner/5cc92ba573e7bdd871dfdbffdd5c2806 A Gist showing a quick and dirty example on how to implement a Capability effectively]

User:TheSilkMiner/Capabilities

2021-02-15T14:56:13Z

TheSilkMiner: Add description on how to attach a capability

'''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; one of the various implementations may also be considered the '''default capability implementation'''.
* '''Capability Storage''': the manager that handles loading and storing persistent capabilities data from and to disk, guaranteeing preservation of information; in-code this is represented by an implementation of the <code>Capability.IStorage</code> interface.

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>TileEntity</code>, <code>Entity</code>, <code>ItemStack</code>, <code>World</code>, and <code>Chunk</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>, <code>IEnergyStorage</code>, and <code>IAnimationStateMachine</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>IInventory</code> and <code>ISidedInventory</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>LockableLootTileEntity</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 referes 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>.

=== <tt>IAnimationStateMachine</tt> ===

The <code>IAnimationStateMachine</code> capability refers to the ability for any capability provider to leverage the Forge Animation State Machine API for animations.

== 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''', 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. Since these objects are created by Forge and there is only '''one''' unique instance for each capability that may exist, this instance cannot be obtained by "common" means. Forge provides two different methods of obtaining such instances: '''injecting''' into a field, or a '''callback method'''.

==== Injecting into a Field ====

<code>Capability</code> can be injected automatically into a field as soon as they get created by Forge, following the principle commonly known as '''dependency injection'''. This provides less flexibility, since it doesn't notify the user that the capability has been injected nor runs arbitrary code. Nevertheless, it is '''suggested''' to use this method instead of the callback approach.

To inject the <code>Capability</code> into a field, all that's needed is to declare a <code>static</code> field of type <code>Capability<T></code>, where <code>T</code> represents the capability interface, and annotate it with <code>@CapabilityInject(T.class)</code>.

For a more practical example, consider the following snippet:

<syntaxhighlight lang="java">
@CapabilityInject(IItemHandler.class)
public static Capability<IItemHandler> ITEM_HANDLER_CAPABILITY = null;
</syntaxhighlight>

The above code will let Forge know that the field <code>ITEM_HANDLER_CAPABILITY</code> should be injected with the unique instance of the <code>IItemHandler</code> capability. Assigning the field to <code>null</code> allows us to provide a reasonable fallback in case the capability we want hasn't been registered yet.

This injection is, for obvious reasons, redundant, since that capability is also available through <code>CapabilityItemHandler</code>.

==== Declaring a Callback ====

Another option is to declare a callback method, meaning a method that will be called with the value of the
desired <code>Capability</code> once the instance is available. This gives more flexibility since the method may perform a number of arbitrary actions with the received instance prior to storing it in a field, or may even discard the capability entirely if wanted. Nevertheless, the usage of a field instead of a method is encouraged as a matter of style.

To use a method as a callback, the method must be declared as <code>static</code> and accepting a single parameter of type <code>Capability<T></code>, where <code>T</code> represents the capability interface. The method should also be annotated with <code>@CapabilityInject(T.class)</code>.

For a more practical example, consider the following snippet:

<syntaxhighlight lang="java">
public static Capability<IEnergyStorage> ENERGY = null;

@CapabilityInject(IEnergyStorage.class)
private static void onEnergyStorageInit(Capability<IEnergyStorage> capability) {
LOGGER.info("Received IEnergyStorage capability '{}': enabling Forge Energy support", capability);
ENERGY = capability;
}
</syntaxhighlight>

The above code declares a callback method that will be invoked when a <code>Capability</code> instance for <code>IEnergyStorage</code> is available. The callback then prints a log message and stores the capability into a <code>public</code> field for accessibility. The field is initialized to <code>null</code> to provide a reasonable fallback in case the capability does not exist.

This callback is, for obvious reasons, redundant, since that capability is also available through <code>CapabilityEnergy</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 clients.

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'' 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 final LazyOptional<IItemhandler> inventoryOptional = LazyOptional.of(() -> this.inventory);

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

@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>TileEntity</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>TileEntity</code>, this usually happens when the block gets removed from the world, either because it's too far away or it simply got broken.

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. For more information on when and why this is needed refer to '''The Capability Provider''' section.

=== 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>MyTileEntity</code>, which extends <code>TileEntity</code>, you'll have to listen to <code>AttachCapabilitiesEvent<TileEntity></code>, '''NOT''' to <code>AttachCapabilitiesEvent<MyTileEntity></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.

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''' 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<TileEntity> event) {
if (!(event.getObject() instanceof EnergyBasedTileEntity)) return;

EnergyStorage backend = new EnergyStorage(((EnergyBasedTileEntity) 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 == CapabilityEnergy.ENERGY) {
return optionalStorage.cast();
}
return LazyOptional.empty();
}
};

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

This example implementation of an attaching agent attaches a <code>IEnergyStorage</code> capability to all <code>TileEntity</code> instance that are a subclass of <code>EnergyBasedTileEntity</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.

=== Accessing a Capability ===

== Creating Custom Capabilities ==

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

=== The Capability Storage ===

=== The Capability Provider ===

=== Tying it All Together ===

== Code Examples ==

= OLD SHIT FOLLOWS =

Capabilities allow exposing features in a dynamic and flexible way, without having to resort to directly implementing many interfaces.

In general terms, each capability provides a feature in the form of an interface, alongside with a default implementation which can be requested, and a storage handler for at least this default implementation. The storage handler can support other implementations, but this is up to the capability implementor, so look it up in their documentation before trying to use the default storage with non-default implementations.

Forge adds capability support to <code>TileEntities</code>, <code>Entities</code>, <code>ItemStack</code>s, <code>World</code>s and <code>Chunk</code>s, which can be exposed either by attaching them through an event or by overriding the capability methods in your own implementations of the objects. This will be explained in more detail in the following sections.

== Forge-provided Capabilities ==
Forge provides three capabilities: <code>IItemHandler</code>, <code>IFluidHandler</code> and <code>IEnergyStorage</code>.

<code>IItemHandler</code> exposes an interface for handling inventory slots. It can be applied to <code>TileEntities</code> (chests, machines, etc.), <code>Entities</code> (extra player slots, mob/creature inventories/bags), or <code>ItemStacks</code> (portable backpacks and such). It replaces the old <code>IInventory</code> and <code>ISidedInventory</code> with an automation-friendly system.

<code>IFluidHandler</code> exposes an interface for handling fluid inventories. It can also be applied to <code>TileEntities</code> <code>Entities</code>, or <code>ItemStacks</code>. It replaces the old <code>IFluidHandler</code> with a more consistent and automation-friendly system.

<code>IEnergyStorage</code> exposes an interface for handling energy containers. It can be applied to <code>TileEntities</code>, <code>Entities</code> or <code>ItemStacks</code>. It is based on the RedstoneFlux API by TeamCoFH.

== Using an Existing Capability ==
As mentioned earlier, <code>TileEntities</code>, <code>Entities</code>, and <code>ItemStacks</code> implement the capability provider feature, through the <code>ICapabilityProvider</code> interface. This interface adds the method <code>getCapability</code>, which can be used to query the capabilities present in the objects.

In order to obtain a capability, you will need to refer it by its unique instance. In the case of the <code>IItemHandler</code>, this capability is primarily stored in <code><nowiki>CapabilityItemHandler#ITEM_HANDLER_CAPABILITY</nowiki></code>, but it is possible to get other instance references by using the <code>@CapabilityInject</code> annotation.
<syntaxhighlight lang="java">
@CapabilityInject(IItemHandler.class)
static Capability<IItemHandler> ITEM_HANDLER_CAPABILITY = null;
</syntaxhighlight>
This annotation can be applied to fields and methods. When applied to a field, it will assign the instance of the capability (the same one gets assigned to all fields) upon registration of the capability, and left to the existing value (<code>null</code>), if the capability was never registered. Because local static field accesses are fast, it is a good idea to keep your own local copy of the reference for objects that work with capabilities. This annotation can also be used on a method, in order to get notified when a capability is registered, so that certain features can be enabled conditionally.

Both the <code>getCapability</code> methods have a second parameter, of type <code>Direction</code>, which can be used in the to request the specific instance for that one face. If passed <code>null</code>, it can be assumed that the request comes either from within the block, or from some place where the side has no meaning, such as a different dimension. In this case a general capability instance that does not care about sides will be requested instead. The return type of <code>getCapability</code> will correspond to the type declared in the capability passed to the method. For the item handler capability, this is indeed <code>IItemHandler</code>.

==Exposing a Capability==
In order to expose a capability, you will first need an instance of the underlying capability type. Note that you should assign a separate instance to each object that keeps the capability, since the capability will most probably be tied to the containing object.

There’s two ways to obtain such an instance, through the <code>Capability</code> itself, or by explicitly instantiating an implementation of it. The first method is designed to use a default implementation via <code>Capability#getDefaultInstance</code>, if those default values are useful for you. In the case of the item handler capability, the default implementation will expose a single slot inventory, which is most probably not what you want.

The second method can be used to provide custom implementations. In the case of <code>IItemHandler</code>, the default implementation uses the <code>ItemStackHandler</code> class, which has an optional argument in the constructor, to specify a number of slots. However, relying on the existence of these default implementations should be avoided, as the purpose of the capability system is to prevent loading errors in contexts where the capability is not present, so instantiation should be protected behind a check testing if the capability has been registered (see the remarks about <code>@CapabilityInject</code> in the previous section).

Once you have your own instance of the capability interface, you will want to notify users of the capability system that you expose this capability and provide a holder of the instance. This is done by overriding the <code>getCapability</code> method, and comparing the instance with the capability you are exposing. If your machine has different slots based on which side is being queried, you can test this with the <code>side</code> parameter. For <code>Entities</code> and <code>ItemStack</code>s, this parameter can be ignored, but it is still possible to have side as a context, such as different armor slots on a player (top side => head slot?), or about the surrounding blocks in the inventory (west => slot on the left?). Don’t forget to fall back to <code>super</code>, otherwise the attached capabilities will stop working. Make sure to invalidate the holder of the instance at the end of the provider's lifecycle.

<syntaxhighlight lang="java">
// Somewhere in your TileEntity subclass
LazyOptional<IItemHandler> inventoryHandlerLazyOptional;

// After initializing inventoryHandler
inventoryHandlerLazyOptional = LazyOptional.of(() -> inventoryHandler);

public <T> LazyOptional<T> getCapability(Capability<T> cap, Direction side) {
if (cap == CapabilityItemHandler.ITEM_HANDLER_CAPABILITY) {
return inventoryHandlerLazyOptional.cast();
}
return super.getCapability(cap, side);
}

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

<code>Item</code>s are a special case since their capability providers are stored on an <code>ItemStack</code>. Instead, a provider should be attached through <code>Item#initCapabilities</code> when applicable. This should hold your capabilities for the lifecycle of the stack.

It is strongly suggested that direct checks in code are used to test for capabilities instead of attempting to rely on maps or other data structures, since capability tests can be done by many objects every tick, and they need to be as fast as possible in order to avoid slowing down the game.

User:TheSilkMiner/Capabilities

2021-01-10T15:28:44Z

TheSilkMiner: Finish Capability Exposure documentation

'''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; one of the various implementations may also be considered the '''default capability implementation'''.
* '''Capability Storage''': the manager that handles loading and storing persistent capabilities data from and to disk, guaranteeing preservation of information; in-code this is represented by an implementation of the <code>Capability.IStorage</code> interface.

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>TileEntity</code>, <code>Entity</code>, <code>ItemStack</code>, <code>World</code>, and <code>Chunk</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>, <code>IEnergyStorage</code>, and <code>IAnimationStateMachine</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>IInventory</code> and <code>ISidedInventory</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>LockableLootTileEntity</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 referes 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>.

=== <tt>IAnimationStateMachine</tt> ===

The <code>IAnimationStateMachine</code> capability refers to the ability for any capability provider to leverage the Forge Animation State Machine API for animations.

== 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''', 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. Since these objects are created by Forge and there is only '''one''' unique instance for each capability that may exist, this instance cannot be obtained by "common" means. Forge provides two different methods of obtaining such instances: '''injecting''' into a field, or a '''callback method'''.

==== Injecting into a Field ====

<code>Capability</code> can be injected automatically into a field as soon as they get created by Forge, following the principle commonly known as '''dependency injection'''. This provides less flexibility, since it doesn't notify the user that the capability has been injected nor runs arbitrary code. Nevertheless, it is '''suggested''' to use this method instead of the callback approach.

To inject the <code>Capability</code> into a field, all that's needed is to declare a <code>static</code> field of type <code>Capability<T></code>, where <code>T</code> represents the capability interface, and annotate it with <code>@CapabilityInject(T.class)</code>.

For a more practical example, consider the following snippet:

<syntaxhighlight lang="java">
@CapabilityInject(IItemHandler.class)
public static Capability<IItemHandler> ITEM_HANDLER_CAPABILITY = null;
</syntaxhighlight>

The above code will let Forge know that the field <code>ITEM_HANDLER_CAPABILITY</code> should be injected with the unique instance of the <code>IItemHandler</code> capability. Assigning the field to <code>null</code> allows us to provide a reasonable fallback in case the capability we want hasn't been registered yet.

This injection is, for obvious reasons, redundant, since that capability is also available through <code>CapabilityItemHandler</code>.

==== Declaring a Callback ====

Another option is to declare a callback method, meaning a method that will be called with the value of the
desired <code>Capability</code> once the instance is available. This gives more flexibility since the method may perform a number of arbitrary actions with the received instance prior to storing it in a field, or may even discard the capability entirely if wanted. Nevertheless, the usage of a field instead of a method is encouraged as a matter of style.

To use a method as a callback, the method must be declared as <code>static</code> and accepting a single parameter of type <code>Capability<T></code>, where <code>T</code> represents the capability interface. The method should also be annotated with <code>@CapabilityInject(T.class)</code>.

For a more practical example, consider the following snippet:

<syntaxhighlight lang="java">
public static Capability<IEnergyStorage> ENERGY = null;

@CapabilityInject(IEnergyStorage.class)
private static void onEnergyStorageInit(Capability<IEnergyStorage> capability) {
LOGGER.info("Received IEnergyStorage capability '{}': enabling Forge Energy support", capability);
ENERGY = capability;
}
</syntaxhighlight>

The above code declares a callback method that will be invoked when a <code>Capability</code> instance for <code>IEnergyStorage</code> is available. The callback then prints a log message and stores the capability into a <code>public</code> field for accessibility. The field is initialized to <code>null</code> to provide a reasonable fallback in case the capability does not exist.

This callback is, for obvious reasons, redundant, since that capability is also available through <code>CapabilityEnergy</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 clients.

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'' 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 static final LazyOptional<IItemhandler> INVENTORY_OPTIONAL = LazyOptional.of(() -> inventory);

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

@Override
protected void invalidateCaps() {
super.invalidateCaps();
INVENTORY_OPTIONAL.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>TileEntity</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>TileEntity</code>, this usually happens when the block gets removed from the world, either because it's too far away or it simply got broken.

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. For more information on when and why this is needed refer to '''The Capability Provider''' section.

=== Attaching a Capability ===

=== Accessing a Capability ===

== Creating Custom Capabilities ==

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

=== The Capability Storage ===

=== The Capability Provider ===

=== Tying it All Together ===

== Code Examples ==

= OLD SHIT FOLLOWS =

Capabilities allow exposing features in a dynamic and flexible way, without having to resort to directly implementing many interfaces.

In general terms, each capability provides a feature in the form of an interface, alongside with a default implementation which can be requested, and a storage handler for at least this default implementation. The storage handler can support other implementations, but this is up to the capability implementor, so look it up in their documentation before trying to use the default storage with non-default implementations.

Forge adds capability support to <code>TileEntities</code>, <code>Entities</code>, <code>ItemStack</code>s, <code>World</code>s and <code>Chunk</code>s, which can be exposed either by attaching them through an event or by overriding the capability methods in your own implementations of the objects. This will be explained in more detail in the following sections.

== Forge-provided Capabilities ==
Forge provides three capabilities: <code>IItemHandler</code>, <code>IFluidHandler</code> and <code>IEnergyStorage</code>.

<code>IItemHandler</code> exposes an interface for handling inventory slots. It can be applied to <code>TileEntities</code> (chests, machines, etc.), <code>Entities</code> (extra player slots, mob/creature inventories/bags), or <code>ItemStacks</code> (portable backpacks and such). It replaces the old <code>IInventory</code> and <code>ISidedInventory</code> with an automation-friendly system.

<code>IFluidHandler</code> exposes an interface for handling fluid inventories. It can also be applied to <code>TileEntities</code> <code>Entities</code>, or <code>ItemStacks</code>. It replaces the old <code>IFluidHandler</code> with a more consistent and automation-friendly system.

<code>IEnergyStorage</code> exposes an interface for handling energy containers. It can be applied to <code>TileEntities</code>, <code>Entities</code> or <code>ItemStacks</code>. It is based on the RedstoneFlux API by TeamCoFH.

== Using an Existing Capability ==
As mentioned earlier, <code>TileEntities</code>, <code>Entities</code>, and <code>ItemStacks</code> implement the capability provider feature, through the <code>ICapabilityProvider</code> interface. This interface adds the method <code>getCapability</code>, which can be used to query the capabilities present in the objects.

In order to obtain a capability, you will need to refer it by its unique instance. In the case of the <code>IItemHandler</code>, this capability is primarily stored in <code><nowiki>CapabilityItemHandler#ITEM_HANDLER_CAPABILITY</nowiki></code>, but it is possible to get other instance references by using the <code>@CapabilityInject</code> annotation.
<syntaxhighlight lang="java">
@CapabilityInject(IItemHandler.class)
static Capability<IItemHandler> ITEM_HANDLER_CAPABILITY = null;
</syntaxhighlight>
This annotation can be applied to fields and methods. When applied to a field, it will assign the instance of the capability (the same one gets assigned to all fields) upon registration of the capability, and left to the existing value (<code>null</code>), if the capability was never registered. Because local static field accesses are fast, it is a good idea to keep your own local copy of the reference for objects that work with capabilities. This annotation can also be used on a method, in order to get notified when a capability is registered, so that certain features can be enabled conditionally.

Both the <code>getCapability</code> methods have a second parameter, of type <code>Direction</code>, which can be used in the to request the specific instance for that one face. If passed <code>null</code>, it can be assumed that the request comes either from within the block, or from some place where the side has no meaning, such as a different dimension. In this case a general capability instance that does not care about sides will be requested instead. The return type of <code>getCapability</code> will correspond to the type declared in the capability passed to the method. For the item handler capability, this is indeed <code>IItemHandler</code>.

==Exposing a Capability==
In order to expose a capability, you will first need an instance of the underlying capability type. Note that you should assign a separate instance to each object that keeps the capability, since the capability will most probably be tied to the containing object.

There’s two ways to obtain such an instance, through the <code>Capability</code> itself, or by explicitly instantiating an implementation of it. The first method is designed to use a default implementation via <code>Capability#getDefaultInstance</code>, if those default values are useful for you. In the case of the item handler capability, the default implementation will expose a single slot inventory, which is most probably not what you want.

The second method can be used to provide custom implementations. In the case of <code>IItemHandler</code>, the default implementation uses the <code>ItemStackHandler</code> class, which has an optional argument in the constructor, to specify a number of slots. However, relying on the existence of these default implementations should be avoided, as the purpose of the capability system is to prevent loading errors in contexts where the capability is not present, so instantiation should be protected behind a check testing if the capability has been registered (see the remarks about <code>@CapabilityInject</code> in the previous section).

Once you have your own instance of the capability interface, you will want to notify users of the capability system that you expose this capability and provide a holder of the instance. This is done by overriding the <code>getCapability</code> method, and comparing the instance with the capability you are exposing. If your machine has different slots based on which side is being queried, you can test this with the <code>side</code> parameter. For <code>Entities</code> and <code>ItemStack</code>s, this parameter can be ignored, but it is still possible to have side as a context, such as different armor slots on a player (top side => head slot?), or about the surrounding blocks in the inventory (west => slot on the left?). Don’t forget to fall back to <code>super</code>, otherwise the attached capabilities will stop working. Make sure to invalidate the holder of the instance at the end of the provider's lifecycle.

<syntaxhighlight lang="java">
// Somewhere in your TileEntity subclass
LazyOptional<IItemHandler> inventoryHandlerLazyOptional;

// After initializing inventoryHandler
inventoryHandlerLazyOptional = LazyOptional.of(() -> inventoryHandler);

public <T> LazyOptional<T> getCapability(Capability<T> cap, Direction side) {
if (cap == CapabilityItemHandler.ITEM_HANDLER_CAPABILITY) {
return inventoryHandlerLazyOptional.cast();
}
return super.getCapability(cap, side);
}

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

<code>Item</code>s are a special case since their capability providers are stored on an <code>ItemStack</code>. Instead, a provider should be attached through <code>Item#initCapabilities</code> when applicable. This should hold your capabilities for the lifecycle of the stack.

It is strongly suggested that direct checks in code are used to test for capabilities instead of attempting to rely on maps or other data structures, since capability tests can be done by many objects every tick, and they need to be as fast as possible in order to avoid slowing down the game.

User:TheSilkMiner/Capabilities

2021-01-10T14:52:29Z

TheSilkMiner: Additional edits

User:TheSilkMiner/Capabilities

2021-01-10T13:24:40Z

TheSilkMiner: Add descriptions for the various Forge provided capabilities

User:TheSilkMiner/Capabilities

2021-01-08T13:24:28Z

TheSilkMiner: Reword Terminology section and titles to make more sense

User:TheSilkMiner/Capabilities

2021-01-08T13:15:28Z

TheSilkMiner: Set up structure for the page

User:TheSilkMiner/Capabilities

2021-01-08T11:34:07Z

TheSilkMiner: Start rewrite of Capability page

User:TheSilkMiner/Capabilities

2021-01-04T19:36:54Z

TheSilkMiner: Let's get started with the rewrite, shall we?

Capabilities allow exposing features in a dynamic and flexible way, without having to resort to directly implementing many interfaces.

In general terms, each capability provides a feature in the form of an interface, alongside with a default implementation which can be requested, and a storage handler for at least this default implementation. The storage handler can support other implementations, but this is up to the capability implementor, so look it up in their documentation before trying to use the default storage with non-default implementations.

Forge adds capability support to <code>TileEntities</code>, <code>Entities</code>, <code>ItemStack</code>s, <code>World</code>s and <code>Chunk</code>s, which can be exposed either by attaching them through an event or by overriding the capability methods in your own implementations of the objects. This will be explained in more detail in the following sections.

== Forge-provided Capabilities ==
Forge provides three capabilities: <code>IItemHandler</code>, <code>IFluidHandler</code> and <code>IEnergyStorage</code>.

<code>IItemHandler</code> exposes an interface for handling inventory slots. It can be applied to <code>TileEntities</code> (chests, machines, etc.), <code>Entities</code> (extra player slots, mob/creature inventories/bags), or <code>ItemStacks</code> (portable backpacks and such). It replaces the old <code>IInventory</code> and <code>ISidedInventory</code> with an automation-friendly system.

<code>IFluidHandler</code> exposes an interface for handling fluid inventories. It can also be applied to <code>TileEntities</code> <code>Entities</code>, or <code>ItemStacks</code>. It replaces the old <code>IFluidHandler</code> with a more consistent and automation-friendly system.

<code>IEnergyStorage</code> exposes an interface for handling energy containers. It can be applied to <code>TileEntities</code>, <code>Entities</code> or <code>ItemStacks</code>. It is based on the RedstoneFlux API by TeamCoFH.

== Using an Existing Capability ==
As mentioned earlier, <code>TileEntities</code>, <code>Entities</code>, and <code>ItemStacks</code> implement the capability provider feature, through the <code>ICapabilityProvider</code> interface. This interface adds the method <code>getCapability</code>, which can be used to query the capabilities present in the objects.

In order to obtain a capability, you will need to refer it by its unique instance. In the case of the <code>IItemHandler</code>, this capability is primarily stored in <code><nowiki>CapabilityItemHandler#ITEM_HANDLER_CAPABILITY</nowiki></code>, but it is possible to get other instance references by using the <code>@CapabilityInject</code> annotation.
<syntaxhighlight lang="java">
@CapabilityInject(IItemHandler.class)
static Capability<IItemHandler> ITEM_HANDLER_CAPABILITY = null;
</syntaxhighlight>
This annotation can be applied to fields and methods. When applied to a field, it will assign the instance of the capability (the same one gets assigned to all fields) upon registration of the capability, and left to the existing value (<code>null</code>), if the capability was never registered. Because local static field accesses are fast, it is a good idea to keep your own local copy of the reference for objects that work with capabilities. This annotation can also be used on a method, in order to get notified when a capability is registered, so that certain features can be enabled conditionally.

Both the <code>getCapability</code> methods have a second parameter, of type <code>Direction</code>, which can be used in the to request the specific instance for that one face. If passed <code>null</code>, it can be assumed that the request comes either from within the block, or from some place where the side has no meaning, such as a different dimension. In this case a general capability instance that does not care about sides will be requested instead. The return type of <code>getCapability</code> will correspond to the type declared in the capability passed to the method. For the item handler capability, this is indeed <code>IItemHandler</code>.

==Exposing a Capability==
In order to expose a capability, you will first need an instance of the underlying capability type. Note that you should assign a separate instance to each object that keeps the capability, since the capability will most probably be tied to the containing object.

There’s two ways to obtain such an instance, through the <code>Capability</code> itself, or by explicitly instantiating an implementation of it. The first method is designed to use a default implementation via <code>Capability#getDefaultInstance</code>, if those default values are useful for you. In the case of the item handler capability, the default implementation will expose a single slot inventory, which is most probably not what you want.

The second method can be used to provide custom implementations. In the case of <code>IItemHandler</code>, the default implementation uses the <code>ItemStackHandler</code> class, which has an optional argument in the constructor, to specify a number of slots. However, relying on the existence of these default implementations should be avoided, as the purpose of the capability system is to prevent loading errors in contexts where the capability is not present, so instantiation should be protected behind a check testing if the capability has been registered (see the remarks about <code>@CapabilityInject</code> in the previous section).

Once you have your own instance of the capability interface, you will want to notify users of the capability system that you expose this capability and provide a holder of the instance. This is done by overriding the <code>getCapability</code> method, and comparing the instance with the capability you are exposing. If your machine has different slots based on which side is being queried, you can test this with the <code>side</code> parameter. For <code>Entities</code> and <code>ItemStack</code>s, this parameter can be ignored, but it is still possible to have side as a context, such as different armor slots on a player (top side => head slot?), or about the surrounding blocks in the inventory (west => slot on the left?). Don’t forget to fall back to <code>super</code>, otherwise the attached capabilities will stop working. Make sure to invalidate the holder of the instance at the end of the provider's lifecycle.

<syntaxhighlight lang="java">
// Somewhere in your TileEntity subclass
LazyOptional<IItemHandler> inventoryHandlerLazyOptional;

// After initializing inventoryHandler
inventoryHandlerLazyOptional = LazyOptional.of(() -> inventoryHandler);

public <T> LazyOptional<T> getCapability(Capability<T> cap, Direction side) {
if (cap == CapabilityItemHandler.ITEM_HANDLER_CAPABILITY) {
return inventoryHandlerLazyOptional.cast();
}
return super.getCapability(cap, side);
}

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

<code>Item</code>s are a special case since their capability providers are stored on an <code>ItemStack</code>. Instead, a provider should be attached through <code>Item#initCapabilities</code> when applicable. This should hold your capabilities for the lifecycle of the stack.

It is strongly suggested that direct checks in code are used to test for capabilities instead of attempting to rely on maps or other data structures, since capability tests can be done by many objects every tick, and they need to be as fast as possible in order to avoid slowing down the game.