Forge Community Wiki - User contributions [en-gb]

Capabilities

2023-07-02T16:08:25Z

SizableShrimp:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Working with Capabilities ==

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

=== Obtaining a Capability ===

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

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

{{Tabs/Code Snippets
|java=
public static Capability<IItemHandler> ITEM_HANDLER = CapabilityManager.get(new CapabilityToken<>(){});
}}

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

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

=== Exposing a Capability ===

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

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

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

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

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

{{Tabs/Code Snippets
|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 == ForgeCapabilities.ITEM_HANDLER
&& (direction == null {{!}}{{!}} direction == Direction.UP {{!}}{{!}} direction == Direction.DOWN)) {
return this.inventoryOptional.cast();
}
return super.getCapability(capability, direction); // See note after snippet
}

@Override
protected void invalidateCaps() {
super.invalidateCaps();
this.inventoryOptional.invalidate();
}
}}

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

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

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

=== Attaching a Capability ===

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

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

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

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

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

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

{{Tabs/Code Snippets
|java=
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

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

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

event.addCapability(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
}}

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

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

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

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

{{Tabs/Code Snippets
|java=
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

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

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

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

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

event.addCapabilities(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
}}

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

=== Accessing a Capability ===

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

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

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

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

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

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

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

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

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

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

== Creating Custom Capabilities ==

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

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

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

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

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

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

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

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

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

{{Tabs/Code Snippets
|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;
}
}
}}

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

=== The Capability Provider ===

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

=== Registering Capabilities ===

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 only requires the Capability Interface.
After registering, the created Capability will be automatically injected into all relevant fields and methods, see [[#Obtaining a Capability|Obtaining a Capability]] for more information.
As of Forge 1.19.2-43.1.1, there are two ways to register capabilities.

==== AutoRegisterCapability annotation ====
On Forge 1.19.2-43.1.1 or higher, a quick and easy way to register a capability is by annotating the Capability Interface with <code>@AutoRegisterCapability</code>. This would look like so:

{{Tabs/Code Snippets
|java=
@AutoRegisterCapability
public interface MyCapability {
...
}
}}

==== RegisterCapabilitiesEvent ====
An alternative way to register capabilities is by calling the <code>register</code> method within the <code>RegisterCapabilitiesEvent</code>. This event is fired on the <code>MOD</code> event bus. For example:

{{Tabs/Code Snippets
|java=
@SubscribeEvent
public void registerCaps(RegisterCapabilitiesEvent event) {
event.register(MyCapability.class);
}
}}

=== Class Diagram ===

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

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

== Custom Capability Providers ==

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

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

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

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

== Code Examples ==

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

[[Category:Data Storage]]

Block Entity Renderer

2022-10-08T14:01:35Z

SizableShrimp:

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

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

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

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

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

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

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

Capabilities

2022-09-25T02:31:43Z

SizableShrimp: Change back to ForgeCapabilities for cap references since the others are deprecated

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Working with Capabilities ==

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

=== Obtaining a Capability ===

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

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

{{Tabs/Code Snippets
|java=
public static Capability<IItemHandler> ITEM_HANDLER = CapabilityManager.get(new CapabilityToken<>(){});
}}

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

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

=== Exposing a Capability ===

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

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

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

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

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

{{Tabs/Code Snippets
|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 == ForgeCapabilities.ITEM_HANDLER
&& (direction == null || direction == Direction.UP || direction == Direction.DOWN)) {
return this.inventoryOptional.cast();
}
return super.getCapability(capability, direction); // See note after snippet
}

@Override
protected void invalidateCaps() {
super.invalidateCaps();
this.inventoryOptional.invalidate();
}
}}

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

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

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

=== Attaching a Capability ===

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

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

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

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

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

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

{{Tabs/Code Snippets
|java=
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

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

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

event.addCapability(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
}}

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

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

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

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

{{Tabs/Code Snippets
|java=
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

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

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

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

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

event.addCapabilities(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
}}

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

=== Accessing a Capability ===

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

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

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

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

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

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

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

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

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

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

== Creating Custom Capabilities ==

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

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

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

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

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

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

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

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

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

{{Tabs/Code Snippets
|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;
}
}
}}

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

=== The Capability Provider ===

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

=== Registering Capabilities ===

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 only requires the Capability Interface.
After registering, the created Capability will be automatically injected into all relevant fields and methods, see [[#Obtaining a Capability|Obtaining a Capability]] for more information.
As of Forge 1.19.2-43.1.1, there are two ways to register capabilities.

==== AutoRegisterCapability annotation ====
On Forge 1.19.2-43.1.1 or higher, a quick and easy way to register a capability is by annotating the Capability Interface with <code>@AutoRegisterCapability</code>. This would look like so:

{{Tabs/Code Snippets
|java=
@AutoRegisterCapability
public interface MyCapability {
...
}
}}

==== RegisterCapabilitiesEvent ====
An alternative way to register capabilities is by calling the <code>register</code> method within the <code>RegisterCapabilitiesEvent</code>. This event is fired on the <code>MOD</code> event bus. For example:

{{Tabs/Code Snippets
|java=
@SubscribeEvent
public void registerCaps(RegisterCapabilitiesEvent event) {
event.register(MyCapability.class);
}
}}

=== Class Diagram ===

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

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

== Custom Capability Providers ==

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

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

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

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

== Code Examples ==

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

[[Category:Data Storage]]

Capabilities

2022-09-25T02:24:52Z

SizableShrimp: Clean up information about registering cap classes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Working with Capabilities ==

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

=== Obtaining a Capability ===

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

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

{{Tabs/Code Snippets
|java=
public static Capability<IItemHandler> ITEM_HANDLER_CAPABILITY = CapabilityManager.get(new CapabilityToken<>(){});
}}

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

This is, for obvious reasons, redundant, since that capability is also available through
<code>CapabilityItemHandler</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:

{{Tabs/Code Snippets
|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();
}
}}

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

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

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

=== Attaching a Capability ===

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

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

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

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

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

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

{{Tabs/Code Snippets
|java=
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

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

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

event.addCapability(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
}}

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

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

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

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

{{Tabs/Code Snippets
|java=
@SubscribeEvent
public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
if (!(event.getObject() instanceof EnergyBasedBlockEntity)) return;

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

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

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

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

event.addCapabilities(new ResourceLocation("examplemod", "fe_compatibility"), provider);
}
}}

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

=== Accessing a Capability ===

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

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

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

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

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

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

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

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

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

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

== Creating Custom Capabilities ==

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

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

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

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

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

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

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

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

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

{{Tabs/Code Snippets
|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;
}
}
}}

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

=== The Capability Provider ===

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

=== Registering Capabilities ===

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 only requires the Capability Interface.
After registering, the created Capability will be automatically injected into all relevant fields and methods, see [[#Obtaining a Capability|Obtaining a Capability]] for more information.
As of Forge 1.19.2-43.1.1, there are two ways to register capabilities.

==== <code>AutoRegisterCapability</code> annotation ====
On Forge 1.19.2-43.1.1 or higher, a quick and easy way to register a capability is by annotating the Capability Interface with <code>@AutoRegisterCapability</code>. This would look like so:

{{Tabs/Code Snippets
|java=
@AutoRegisterCapability
public interface MyCapability {
...
}
}}

==== RegisterCapabilitiesEvent ====
An alternative way to register capabilities is by calling the <code>register</code> method within the <code>RegisterCapabilitiesEvent</code>. This event is fired on the <code>MOD</code> event bus. For example:

{{Tabs/Code Snippets
|java=
@SubscribeEvent
public void registerCaps(RegisterCapabilitiesEvent event) {
event.register(MyCapability.class);
}
}}

=== Class Diagram ===

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

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

== Custom Capability Providers ==

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

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

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

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

== Code Examples ==

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

[[Category:Data Storage]]

Main Page

2022-09-12T04:56:32Z

SizableShrimp: Add entities category

__NOTOC__
<templatestyles src=":Main_Page/styles.css" />

<div class="center title">Forge Community Wiki</div>

The Forge Community Wiki exists so that the community can:

* collectively keep track of major changes and updates to Forge and Vanilla code;
* create and edit articles with in-depth explanations about a variety of Forge-related subjects; and
* contribute example code and tutorials for both simple and difficult concepts.

This wiki is editable by any registered user with an account. This is to allow tracking of harmful edits, but isn't imposing any annoying limits. We welcome any edit, however small. Join the [https://discord.gg/Nn42eAh Discord] to discuss changes and edits to the wiki with others and the staff.

{{Supported versions}}

<div class="center round_warning">
Please read the [[FCWMeta:Wiki Policy|wiki policy]] before editing!
</div>

<div class="center" style="margin-bottom: 2em">
{{Supported versions|text=1}}
</div>

<div class="box_container center">

<div class="box">
<h3>Beginner Topics</h3>
* [[Getting Started]]
* [[Proper Mod Structuring]]
* [[Mods.toml file]]
* [[Debug Profiler|The Debug Profiler]]
* [[Version Checker]]
</div>

<div class="box">
<h3>Advanced Topics</h3>
* [[Jar-in-jar]]
</div>

<div class="box">
<h3>Common Concepts</h3>
* [[Sides|Understanding Sides]]
* [[Events|Understanding Events]]
* [[Registration]]
* [[Internationalization]]
* [[Configs]]
</div>

<div class="box">
<h3>Forge Conventions</h3>
* [[Semantic Versioning]]
* [[Stages of Modloading]]
</div>

<div class="box">
<h3>Resources and Data</h3>
* [[Using Resources|Introduction]]
* [[Recipes]]
* [[Tags]]
* [[Holders]]
</div>

<div class="box">
<h3>Blocks</h3>
* [[Making Blocks|Creating Blocks]]
* [[Understanding Blockstates]]
* [[Interacting With Blocks|Block Interactions]]
</div>

<div class="box">
<h3>Items</h3>
* [[Making Items]]
* [[Making Tools]]
* [[BlockEntityWithoutLevelRenderer|<tt>BlockEntityWithoutLevelRenderer</tt>]]
* [[Custom Item Animations]]
</div>

<div class="box">
<h3>Entities</h3>
* [[Making Entities]]
</div>

<div class="box">
<h3>Data Generation</h3>
* [[Datageneration|Introduction]]
* [[Datageneration/Recipes|Recipes]]
* [[Datageneration/Tags|Tags]]
* [[Datageneration/Loot_Tables|Loot Tables]]
* [[Datageneration/I18n|Localization]]
* [[Datageneration/States and Models|<tt>BlockState</tt>s and Models]]
</div>

<div class="box">
<h3>Block Entities</h3>
* [[Block Entities|Introduction]]
* [[Block Entity Renderer|<tt>BlockEntityRenderer</tt>]]
</div>

<div class="box">
<h3>Models</h3>
* [[Introduction to Models|Introduction]]
* [[Model JSONs]]
* [[BlockState JSONs]]
* [[Coloring textures dynamically|Dynamically Colored Textures]]
* [[Item Properties]]
</div>

<div class="box">
<h3>Handling Information</h3>
* [[Understanding Networking|Introduction]]
* [[Using NBT|Named Binary Tag (NBT)]]
* [[Using FriendlyByteBuf|Using <tt>FriendlyByteBuf</tt>]]
* [[Sending Packets|Sending and Receiving Packets]]
* [[Using SimpleChannel|Using <tt>SimpleChannel</tt>]]
* [[Networking with Entities]]
* [[DynamicOps|Using DynamicOps]]
* [[Codecs|Using Codecs]]
</div>

<div class="box">
<h3>Data Storage</h3>
* [[Capabilities|Understanding Capabilities]]
* [[Capabilities/Attaching|Attaching Capabilities]]
* [[Saved Data]]
</div>

<div class="box">
<h3>Game Effects</h3>
* [[Mob Effects]]
* [[Potions]]
* [[Particles]]
* [[Sounds]]
</div>

<div class="box">
<h3>Events</h3>
* [[Events|Understanding Events]]
* [[Entity Events]]
</div>

<div class="box">
<h3>Others</h3>
* [[Dependencies]]
* [[Dynamic Loot Modification]]
* [[Components|Components and Translation Keys]]
* [[Key Mappings]]
* [[Access Transformers]]
* [[Toolchain]]
* [[Game_Tests|Game Tests]]
* [[Biome_Modifiers|Biome Modifiers]]
* [[Datapack_Registries|Datapack Registries]]
</div>

<div class="box">
<h3>Recipes</h3>
* [[Recipes]]
* [[Custom Recipes|Custom Recipe Types]]
* [[Datageneration/Recipes|Datageneration]]
</div>

</div>

Making Entities

2022-09-12T04:53:49Z

SizableShrimp: boop

{{Under construction}}

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

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

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

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

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

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

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

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

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

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

Making Entities

2022-09-12T04:53:31Z

SizableShrimp: Basic information about entities, entity types, and spawning

{{Under construction}}

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

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

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

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

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

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

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

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

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

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

Biome Modifier

2022-09-12T04:45:35Z

SizableShrimp: Redirected page to Biome Modifiers

#REDIRECT [[Biome Modifiers]]

Registration

2022-09-08T17:06:38Z

SizableShrimp: Some improvements of changes in 1.19; skimmed

Registration is the process of making an object (such as an item or block) known to the game during runtime with an attached <code>ResourceLocation</code> name. Unregistered objects are a likely cause of game loading crashes or bugs, so it is important to register objects correctly.

Most objects that are known within the game are handled by a Vanilla <code>Registry</code> or a Forge <code>IForgeRegistry</code>. Each registry uniquely defines each of its own objects through a "registry name" via a [[Using Resources#ResourceLocation|ResourceLocation]].
Registries themselves have a name and are registered to the Vanilla root registry or <code>RegistryManager</code>.
It is important to keep these distinct; although both are called registry names.

{{Tip|In a global context, each object is universally unique through its <code>ResourceKey</code>: a concatenation of its registry's id and the object's registry name.}}

Forge expands Vanilla's registries to add important features for modded environments, such as world saving of integer ids and network syncing of integer ids, to ensure consistency when different mods and entries are present.

Forge registries preserves the same loading order of Vanilla registries, with all modded registries fired after Vanilla in alphabetical order by string comparing namespace then path. This loading order determines what order registries have their entries registered. All registries wrapped by Forge can be found within the <code>ForgeRegistries</code> class.

{{Tip|All registries have their own set of names and objects, so the same name (e.g. <code>examplemod:object</code>) can be reused in multiple registries, like blocks and items.}}

{{Tip/Warning|If two registry objects within the '''same''' registry have the same name, the second object will override the first.}}

== Methods for Registering ==

There are two proper ways to register objects to a Forge registry or Vanilla registry: the <code>DeferredRegister</code> class, and the <code>RegisterEvent</code> lifecycle event.

=== DeferredRegister ===

<code>DeferredRegister</code> is an abstraction layer over the registry event used to register objects. It maintains a map of "registry name" to their associated suppliers and resolves those suppliers during <code>RegisterEvent</code> for the associated registry. This method is the currently recommended, and documented, way to handle these objects as it provides convenience and safety for those who want to statically initialize objects while avoiding some issues associated with it.

{{Tip/Important|When using <code>DeferredRegister</code>s with non-vanilla registries, the registry key or the registry name should be supplied to the <code>create</code> method. These include the custom Forge registries for entity data serializers, global loot modifier serializers, world presets, and biome modifier serializers. Calling <code>Supplier#get</code> on a <code>Supplier<IForgeRegistry<?>></code> when making a DeferredRegister will return null because the registry does not exist yet.}}

An example of a mod registering a custom block:

{{Template:Tabs/Code_Snippets
|java=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

public ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().getModEventBus());
}
|kotlin=private val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

val EXAMPLE_BLOCK: RegistryObject<Block> = BLOCKS.register("example_block") { Block(BlockBehaviour.Properties.of(Material.ROCK)) }

internal class ExampleMod {
init {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus)
}
}
|scala=object ExampleMod {
private final val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

final val EXAMPLE_BLOCK = registerBlock("example_block", () => new Block(BlockBehaviour.Properties.of(Material.ROCK)))
}
class ExampleMod {
BLOCKS.register(FMLJavaModLoadingContext.get.getModEventBus)
}
|groovy=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus);
}
|}}

{{Tip|When using a <code>DeferredRegister</code> to register any object, the name inputted will be automatically prefixed with the mod id passed in, giving the above object a "registry name" of <code>examplemod:example_block</code>.}}

=== RegisterEvent ===

The <code>RegisterEvent</code> is the second way register objects. This [[Events|event]] is fired for each registry synchronously in vanilla registry order after <code>FMLConstructModEvent</code> and before the configs are loaded. Objects are registered using <code>#register</code> by passing in the registry key, the name of the registry object, and the object itself. There is an additional <code>#register</code> overload which takes in a consumed helper to register an object with a given name. It is recommended to use this method to avoid unnecessary object creation.

Here is an example: (the event handler is registered on the '''mod event bus''')

{{Template:Tabs/Code_Snippets
|java=@SubscribeEvent
public void register(RegisterEvent event) {
event.register(ForgeRegistries.Keys.BLOCKS,
helper -> helper.register(new ResourceLocation(MODID, "example_block"), new Block(...))
);
}
|kotlin=@JvmStatic
@SubscribeEvent
private fun register(event: RegisterEvent) =
event.register(ForgeRegistries.Keys.BLOCKS) {
helper -> helper.register(ResourceLocation(MODID, "example_block"), Block(...))
}
|scala=@SubscribeEvent
def register(event: RegisterEvent): Unit =
event.register(ForgeRegistries.Keys.BLOCKS,
helper => helper.register(new ResourceLocation(MODID, "example_block"), new Block(...))
)
|}}

{{Tip/Important|Since all objects registered must be singleton, some classes cannot by themselves be registered. Instead, <code>*Type</code> classes are registered and used in the formers' constructors to wrap the flyweight objects. For example, a [[Basics_of_Block_Entities|<code>BlockEntity</code>]] is wrapped via <code>BlockEntityType</code>, and <code>Entity</code> is wrapped via <code>EntityType</code>. These <code>*Type</code> classes hold factories that simply create the containing type on demand.

These factory holders are created through the use of their <code>*Type$Builder</code> classes. An example: (<code>REGISTER</code> here refers to a <code>DeferredRegister<BlockEntityType<?>></code>)

{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<BlockEntityType<ExampleBlockEntity>> EXAMPLE_BLOCK_ENTITY = REGISTER.register(
"example_block_entity", () -> BlockEntityType.Builder.of(ExampleBlockEntity::new, EXAMPLE_BLOCK.get()).build(null)
);
|kotlin=val EXAMPLE_BLOCK_ENTITY: RegistryObject<BlockEntityType<ExampleBlockEntity>> = REGISTER.register("example_block_entity") { BlockEntityType.Builder.of(::ExampleBlockEntity, EXAMPLE_BLOCK.get()).build(null)) }
|scala=final val EXAMPLE_BLOCK_ENTITY = REGISTER.register("example_block_entity", () => BlockEntityType.Builder.of(() => new ExampleBlockEntity(), GeneralRegistrar.EXAMPLE_BLOCK.get).build(null))
|}}
}}

=== Non-Forge Registries ===

Not all vanilla registries are wrapped as a Forge registry. To register objects to any one of these registries, create a <code>DeferredRegister</code> via the <code>#create</code> overload which takes in a resource key of the registry and the mod id to register the entries for. Then simply call <code>#register</code> like any other <code>DeferredRegister</code>.

{{Template:Tabs/Code_Snippets
|java=private static final DeferredRegister<LootItemConditionType> REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID);

public static final RegistryObject<LootItemConditionType> EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () -> new LootItemConditionType(...));
|kotlin=private val REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID)

val EXAMPLE_LOOT_ITEM_CONDITION_TYPE : RegistryObject<LootItemConditionType> = REGISTER.register("example_loot_item_condition_type") {
LootItemConditionType(...)
}
|scala=private final val REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID)

final val EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () => new LootItemConditionType(...))
|groovy=private static final DeferredRegister<LootItemConditionType> REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID);

public static final RegistryObject<LootItemConditionType> EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () -> new LootItemConditionType(...));
|}}

If you attempt to make one of these instances require an instance of another registry object, you should use the lazy initialization method mentioned above to register the object in the correct order.

=== Data Driven Entries ===

Registries are considered to be data driven if they are located within <code>RegistryAccess</code> with the exception of <code>LevelStem</code> and <code>Level</code>.

These registry objects only need to be registered within code if they are to be used within a pre-existing registry object (e.g. a <code>PlacedFeature</code> for ore generation within an overworld <code>Biome</code>). Otherwise, their instance can be purely registered using a JSON file.

If a data driven registry object has to be registered within code, a dummy object should be supplied to hold a "registry name" and then constructed within a JSON file.

== Referencing Registered Objects ==

Each forge registered object should not be statically initialized nor reference another instance being registered. They must always be a new, singleton instance that is resolved during when <code>RegisterEvent</code> is called for their registry. This is to maintain a sane loading order for registries and their objects along with dynamic loading/unloading of mods.

Forge registered objects must always be referenced through a <code>RegistryObject</code> or a field with <code>@ObjectHolder</code>.

===Using RegistryObjects===
<code>RegistryObject</code>s can be used to retrieve references to registered objects once they become available. Their references are updated along with all <code>@ObjectHolder</code> annotations after the registry that <code>RegisterEvent</code> is called for is dispatched and frozen.

A <code>RegistryObject</code> can be retrieved as a result of using <code>DeferredRegister</code> or calling the static factory <code>RegistryObject#create</code>. Each static factory takes in the "registry name" of the object being referenced and one of the following: a <code>IForgeRegistry</code>, a registry name of the type <code>ResourceLocation</code>, or a registry key of the type <code>ResourceKey<? extends Registry<?>></code>. The <code>RegistryObject</code> can be stored within some field and retrieve the registered object using <code>#get</code>.

An example using <code>RegistryObject</code>:
{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<Item> EXAMPLE_ITEM = RegistryObject.create(new ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS);

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
public static final RegistryObject<ExampleRegistry> EXAMPLE_OBJECT = RegistryObject.create(new ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod");
|kotlin=val EXAMPLE_ITEM: RegistryObject<Item> = RegistryObject.create(ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS)

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
val EXAMPLE_OBJECT: RegistryObject<ExampleRegistry> = RegistryObject.create(ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod")
|scala=final val EXAMPLE_ITEM = RegistryObject.create(new ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS)

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
final val EXAMPLE_OBJECT = RegistryObject.create(new ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod");
|}}

{{Tip/Important|All vanilla objects are bootstrapped and registered before mods are loaded. As such, they can be referenced as is without any issues.}}

=== Using @ObjectHolder ===

Forge registry objects can also be injected into <code>public static final</code> fields by annotating each field with <code>@ObjectHolder</code>. Note that using <code>RegistryObject</code>s is the preferred strategy as ObjectHolders are verbose, clunky, and easy to mess up.

ObjectHolders can only be applied to fields and require 2 pieces of information: the registry name of your target registry and the name of your object entry inside the registry.

The registry name can be found inside of <code>ForgeRegistries.Keys</code> or <code>Registry</code>.
For blocks, this would be <code>"minecraft:block"</code>.
For items, this would be <code>"minecraft:item"</code>, etc.

The name of your entry is dependent on what you called it and requires your modid to be prefixed.
When using <code>@ObjectHolder</code> inside of your main mod class annotated with <code>@Mod</code>, the modid namespace can be omitted.

The rules for <code>@ObjectHolder</code> are as follows:

* If the class is annotated with <code>@Mod</code>, the modid will be the default namespace for all annotated fields within if not explicitly defined
* A field is considered for injection if:
** it has at least the modifiers <code>public static</code> and optionally <code>final</code>, and
** the '''field''' is annotated with <code>@ObjectHolder</code>, and:
*** the entry name value is explicitly defined, and
*** the registry name value is explicitly defined
* ''An exception is thrown if the resulting <code>ResourceLocation</code> is incomplete or invalid (non-valid characters in path)''
* If no other errors or exceptions occur, the field will be injected
* If all of the above rules do not apply, no action will be taken (and a message may be logged)

<code>@ObjectHolder</code> annotated fields are injected with their associated object values after <code>RegisterEvent</code> is fired for their registry, the same time that <code>RegistryObject</code>s are filled. ObjectHolders will remain empty if the associated registry does not exist.

{{Tip/Warning|If the object does not exist in the registry when it is to be injected, a debug message will be logged, and no value will be injected. If the object is found, but the field cannot be set, a warning message will be logged instead.}}

As these rules are rather complicated, here are some examples:
<div class="mw-collapsible mw-collapsed" style="border: solid 2px; padding: 2px 5px; margin-top: 3px">
<div style="font-weight:bold;line-height:1.6;">Example uses of <code>@ObjectHolder</code></div>
<div class="mw-collapsible-content" style="overflow: auto; white-space: nowrap;">
<syntaxhighlight lang="java">
class Holder {
@ObjectHolder(registryName = "minecraft:enchantment", value = "minecraft:flame")
public static final Enchantment flame = null; // Annotation present. [public static] is required. [final] is optional.
// Registry name is explicitly defined: "minecraft:enchantment"
// Resource location is explicitly defined: "minecraft:flame"
// To inject: "minecraft:flame" from the [Enchantment] registry

public static final Biome ice_flat = null; // No annotation on the field.
// Therefore, the field is ignored.

@ObjectHolder("minecraft:creeper")
public static final Entity creeper = null; // Annotation present. [public static] is required. [final] is optional.
// The registry name has not been specified on the field.
// Therefore, this will not compile.

@ObjectHolder(registryName = "minecraft:potion")
public static final Potion levitation = null; // Annotation present. [public static] is required. [final] is optional.
// Registry name is explicitly defined: "minecraft:potion"
// The entry's name value has not been specified on the field.
// Therefore, this will not compile.
}
</syntaxhighlight>
</div>
</div>

== Creating Custom Registries ==

Creating custom registries for your mod might be useful if you want other mods to add new things to your system. For example, you might have magic spells and want to allow other mods to add new spells. For this you will want to make a registry (eg. "mymagicmod:spells"). This way, other mods will be able to register things to that list, and you won't have to do anything else.

Just like with registering a new item or block you have two ways of making a new registry. Each method takes in a <code>RegistryBuilder</code> which is used to build an <code>IForgeRegistry</code>. Each builder should have its name set via <code>#setName</code> before being created.

=== With DeferredRegister ===

The first method involves the second static constructor: <code>DeferredRegister#create(ResourceLocation, String)</code>. From there, we can construct the registry using <code>#makeRegistry</code>. This will already populate <code>#setName</code> for us. This method also returns a supplier of the registry which we can use after the <code>NewRegistryEvent</code> is called.

Here is an example:

{{Template:Tabs/Code_Snippets
|java=public static final DeferredRegister<ExampleRegistry> EXAMPLE = DeferredRegister.create(new ResourceLocation(MODID, "example_registry"), MODID);

public static final Supplier<IForgeRegistry<ExampleRegistry>> REGISTRY = EXAMPLE.makeRegistry(RegistryBuilder::new);
|kotlin=val EXAMPLE: DeferredRegister<ExampleRegistry> = DeferredRegister.create(ResourceLocation(MODID, "example_registry"), MODID)

val REGISTRY: IForgeRegistry<ExampleRegistry> by EXAMPLE.makeRegistry(::RegistryBuilder).let {
lazy {
it.get()
}
}
|scala=final val EXAMPLE = DeferredRegister.create(new ResourceLocation(MODID, "example_registry"), MODID)

private final val PRIVATE_REGISTRY = EXAMPLE.makeRegistry(() => new RegistryBuilder)
final lazy val REGISTRY = PRIVATE_REGISTRY.get
|}}

=== Using <code>NewRegistryEvent</code> ===

The second method can be done during the <code>NewRegistryEvent</code> event. Using <code>NewRegistryEvent#create</code>, you can pass in a <code>RegistryBuilder</code> directly. This method will return a <code>Supplier<IForgeRegistry<V>></code> that can be stored and queried after the event is fired to gain access to your <code>IForgeRegistry</code> instance.

Here is an example: (the event handler is registered on the '''mod event bus''')

<syntaxhighlight lang="Java">
public static Supplier<IForgeRegistry<ExampleRegistry>> registrySupplier = null;

@SubscribeEvent
public void onNewRegistry(NewRegistryEvent event){
RegistryBuilder<ExampleRegistry> registryBuilder = new RegistryBuilder<>();
registryBuilder.setName(new ResourceLocation(MODID, "example_registry");
registrySupplier = event.create(registryBuilder);
}
</syntaxhighlight>

== Handling Missing Entries ==

When loading a pre-existing world after removing mods or updating versions, there are cases where certain registry objects will cease to exist. In these cases, it is possible to specify actions to remove a mapping, prevent the world from loading, or remap the name as needed. This can be done through the third of the registry events: <code>MissingMappingsEvent</code>. Within the event, you can grab an immutable list of missing mappings associated with a mod id for a given registry via <code>#getMappings</code> or a list of all mappings via <code>#getAllMappings</code>.

For each <code>Mapping</code>, you can either execute one of the following methods:
* <code>#ignore</code> which abandons the entry when loading
* <code>#warn</code> which warns the user about the missing entry but continues loading
* <code>#fail</code> which prevents the world from loading
* <code>#remap</code> which remaps the entry to the specified non-null object in the same registry

If none of the above are specified, then the default action of notifying the user about the missing mappings occur.

Here is an example: (the event handler is registered on the '''forge event bus''')

{{Template:Tabs/Code_Snippets
|java=// This will ignore any missing test items from the specified world
@SubscribeEvent
public void onMissing(final MissingMappingsEvent event) {
event.getMappings(ForgeRegistries.Keys.ITEMS, MODID).stream()
.filter(mapping -> mapping.key.getPath().contains("test"))
.forEach(Mapping::ignore);
}
|groovy=// This will ignore any missing test items from the specified world
@SubscribeEvent
void onMissing(final MissingMappingsEvent event) {
event.getMappings(ForgeRegistries.Keys.ITEMS, MODID).stream()
.filter(mapping -> mapping.key.path.contains("test"))
.forEach(Mapping::ignore);
}
|}}

[[Category:Common Concepts]]

Biome Modifiers

2022-08-16T02:16:58Z

SizableShrimp:

Biome Modifiers are a data-driven system for modifying biomes. They have the ability to modify biomes in several ways:

* Adding or removing worldgen features and carvers
* Adding or removing mob spawns and mob spawn costs
* Modifying the climate of a biome
* Modifying a biome's client effects, such as water color

Creating and using biome modifiers involves up to three steps:

# Creating a [[#Biome_Modifier_Type|biome modifier type]], which defines how to modify a biome.
# Registering a [[#Biome_Modifier_Serializers|biome modifier codec]], which defines how to parse a json into your biome modifier type.
# Creating [[#Biome_Modifier_JSONs|biome modifier JSONs]] to define individual biome modifier instances; each json file provides a glob of data to your serializer to produce an instance of a biome modifier type. These can be [[#Datageneration|datagenerated]] if desired.

Forge provides several [[#Builtin_Biome_Modifier_Types|builtin biome modifier types]], so some basic use cases such as adding features or mob spawns to biomes can be done without registering additional serializers.

=Biome Modifier Types=
To define a new type of biome modifier, begin by implementing a new class that extends <code>BiomeModifier</code>. BiomeModifiers can usually be implemented as records, to reduce boilerplate.

<syntaxhighlight lang="java">
public record ExampleBiomeModifier() implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// This allows modifications to the given biome via the provided Builder.
}

public Codec<? extends BiomeModifier> codec()
{
// This must return a registered Codec, see Biome Modifier Serializers below.
}
}
</syntaxhighlight>

Beware! The modify method is called once per each phase per biome per biome modifier, so it's important to check which phase you're in and only make your changes in one phase.

<syntaxhighlight lang="java">
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
if (phase == Phase.ADD)
{
// add things to biomes
}
}
</syntaxhighlight>

Typically we also want to restrict biome modifiers to only apply to certain biomes. We can do that by accepting a HolderSet<biome> in our constructor:

<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
if (phase == Phase.ADD && biomes.contains(biome))
{
// add things to biomes
}
}
</syntaxhighlight>

We can also accept [[Holders]] or [[HolderSets|HolderSets]] for other [[Registration#Data_Driven_Entries|datapack registry elements]], such as PlacedFeatures, which allows our BiomeModifier to refer to those elements, which can then be defined in their own JSON files.

<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes, Holder<PlacedFeature> feature) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// add a feature to all specified biomes
if (phase == Phase.ADD && biomes.contains(biome))
{
builder.getGenerationSettings().addFeature(Decoration.UNDERGROUND_ORES, feature);
}
}
</syntaxhighlight></biome>

= Biome Modifier Serializers =

Each type of biome modifier must have a [[Codecs|Codec]] registered for it; [[Registration#DeferredRegister|Deferred Registers]] are the recommended way to register biome modifier codecs.

<syntaxhighlight lang="java">
public class YourMod
{
static DeferredRegister<Codec<? extends BiomeModifier>> BIOME_MODIFIER_SERIALIZERS =
DeferredRegister.create(ForgeRegistries.Keys.BIOME_MODIFIER_SERIALIZERS, "yourmodid");

static RegistryObject<Codec<ExampleBiomeModifier>> EXAMPLE_CODEC = BIOME_MODIFIER_SERIALIZERS.register("example", () ->
RecordCodecBuilder.create(builder -> builder.group(
// declare fields
Biome.LIST_CODEC.fieldOf("biomes").forGetter(ExampleBiomeModifier::biomes),
PlacedFeature.CODEC.fieldOf("feature").forGetter(ExampleBiomeModifier::feature)
// declare constructor
).apply(builder, ExampleBiomeModifier::new)));
}
</syntaxhighlight>

We can now implement the codec() method in our biome modifier class:

<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes, Holder<PlacedFeature> feature) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// add a feature to all specified biomes
if (phase == Phase.ADD && biomes.contains(biome))
{
builder.getGenerationSettings().addFeature(Decoration.UNDERGROUND_ORES, feature);
}
}

public Codec<? extends BiomeModifier> codec()
{
return YourMod.EXAMPLE_CODEC.get();
}
}
</syntaxhighlight>

= Biome Modifier JSONs =

Once we've registered a codec for our biome modifier type, we can define jsons for it. Biome modifier jsons must be defined in the directory <code>data/modid/forge/biome_modifier/</code>; a biome modifier at <code>data/modid/forge/biome_modifier/your_biome_modifier.json</code> has the namespaced id <code>modid:your_biome_modifier</code>.

Our codec above defines the json format:

* "biomes" is a special HolderSet field that accepts a single biome id, [list of biome ids], or #biome_tag.
* "feature" accepts a single placed feature id. [https://minecraft.fandom.com/wiki/Placed_feature These can be defined in jsons as well].
* We must also specify "type": "yourmodid:example" to tell the data loader to use our registered codec to read our json.

A json instance of our biome modifier that adds some feature to badlands biomes might look like this:

<syntaxhighlight lang="json">
{
"type": "yourmodid:example",
"biomes": "#minecraft:is_badlands",
"feature": "yourmod:some_feature"
}
</syntaxhighlight>

= Datageneration =

Biome Modifier jsons can be [[Datageneration|datagenerated via GatherDataEvent]]. As biome modifiers are datapack registry objects, this can be done by using JsonCodecProvider#forDatapackRegistry as the data provider. Refer to [[Datageneration/Datapack_Registries]] for additional information on datagenerating datapack registry elements.

= Builtin Biome Modifier Types =

Forge provides the following builtin biome modifier types:

== None ==

A no-op biome modifier type, whose jsons have the following format:

<syntaxhighlight lang="json">
{
"type": "forge:none"
}
</syntaxhighlight>

This allows pack devs or server operators to disable mods' biome modifiers by overriding their biome modifier jsons with the above.

== Add Features ==

This biome modifier type adds placed features to biomes.

<syntaxhighlight lang="json">
{
"type": "forge:add_features", // required
"biomes": "#namespace:your_biome_tag", // accepts a biome id, [list of biome ids], or #namespace:biome_tag
"features": "namespace:your_feature", // accepts a placed feature id, [list of placed feature ids], or #namespace:feature_tag
"step": "underground_ores" // accepts a Decoration enum name
}
</syntaxhighlight>

Decoration steps in order of generation are:
* raw_generation
* lakes
* local_modifications
* underground_structures
* surface_structures
* underground_ores
* underground_decoration
* fluid_springs
* vegetal_decoration
* top_layer_modification

== Remove Features ==

This biome modifier type removes features from biomes.

<syntaxhighlight lang="json">
{
"type": "forge:remove_features", // required
"biomes": "#namespace:your_biome_tag", // accepts a biome id, [list of biome ids], or #namespace:biome_tag
"features": "namespace:your_feature", // accepts a placed feature id, [list of placed feature ids], or #namespace:feature_tag
"steps": "underground_ores" // optional field specifying a Decoration or list of Decorations to remove features from, defaults to all if not specified
}
</syntaxhighlight>

== Add Spawns ==

This biome modifier type adds mob spawns to biomes.

<syntaxhighlight lang="json">
{
"type": "forge:add_spawns", // Required
"biomes": "#namespace:biome_tag", // Accepts a biome id, [list of biome ids], or #namespace:biome_tag
"spawners":
{
"type": "namespace:entity_type", // Type of mob to spawn
"weight": 100, // int, spawn weighting
"minCount": 1, // int, minimum pack size
"maxCount": 4 // int, maximum pack size
}
}
</syntaxhighlight>

== Remove Spawns ==

This biome modifier type removes mob spawns from biomes.

<syntaxhighlight lang="json">
{
"type": "forge:remove_spawns", // Required
"biomes": "#namespace:biome_tag", // Accepts a biome id, [list of biome ids], or #namespace:biome_tag
"entity_types": "#namespace:entitytype_tag" // Accepts an entity type, list, or tag of entitytypes whose spawns are to be removed from the biomes
}
</syntaxhighlight>

= Best Practices =

* Avoid using biome modifiers to add vanilla placed features to biomes, as this may cause a feature cycle violation (the game will crash if two biomes have the same two features in their feature lists but in different orders). Placed features can be referenced in biome jsons or added via biome modifiers, but should not be used in both.

Biome Modifiers

2022-08-13T20:40:08Z

SizableShrimp: /* Biome Modifier Types */

Biome Modifiers are a data-driven system for modifying biomes. They have the ability to modify biomes in several ways:

* Adding or removing worldgen features and carvers
* Adding or removing mob spawns and mob spawn costs
* Modifying the climate of a biome
* Modifying a biome's client effects, such as water color

Creating and using biome modifiers involves up to three steps:

# Creating a [[#Biome_Modifier_Type|biome modifier type]], which defines how to modify a biome.
# Registering a [[#Biome_Modifier_Serializers|biome modifier codec]], which defines how to parse a json into your biome modifier type.
# Creating [[#Biome_Modifier_JSONs|biome modifier JSONs]] to define individual biome modifier instances; each json file provides a glob of data to your serializer to produce an instance of a biome modifier type. These can be [[#Datageneration|datagenerated]] if desired.

Forge provides several [[#Builtin_Biome_Modifier_Types|builtin biome modifier types]], so some basic use cases such as adding features or mob spawns to biomes can be done without registering additional serializers.

=Biome Modifier Types=
To define a new type of biome modifier, begin by implementing a new class that extends <code>BiomeModifier</code>. BiomeModifiers can usually be implemented as records, to reduce boilerplate.

<syntaxhighlight lang="java">
public record ExampleBiomeModifier() implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// This allows modifications to the given biome via the provided Builder.
}

public Codec<? extends BiomeModifier> codec()
{
// This must return a registered Codec, see Biome Modifier Serializers below.
}
}
</syntaxhighlight>

Beware! The modify method is called once per each phase per biome per biome modifier, so it's important to check which phase you're in and only make your changes in one phase.

<syntaxhighlight lang="java">
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
if (phase == Phase.ADD)
{
// add things to biomes
}
}
</syntaxhighlight>

Typically we also want to restrict biome modifiers to only apply to certain biomes. We can do that by accepting a HolderSet<biome> in our constructor:

<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
if (phase == Phase.ADD && biomes.contains(biome))
{
// add things to biomes
}
}
</syntaxhighlight>

We can also accept [[Holders]] or [[HolderSets]] for other [[Registration#Data_Driven_Entries|datapack registry elements]], such as PlacedFeatures, which allows our BiomeModifier to refer to those elements, which can then be defined in their own JSON files.

<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes, Holder<PlacedFeature> feature) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// add a feature to all specified biomes
if (phase == Phase.ADD && biomes.contains(biome))
{
builder.getGenerationSettings().addFeature(Decoration.UNDERGROUND_ORES, feature);
}
}
</syntaxhighlight></biome>

= Biome Modifier Serializers =

Each type of biome modifier must have a [[Codecs|Codec]] registered for it; [[Registration#DeferredRegister|Deferred Registers]] are the recommended way to register biome modifier codecs.

<syntaxhighlight lang="java">
public class YourMod
{
static DeferredRegister<Codec<? extends BiomeModifier>> BIOME_MODIFIER_SERIALIZERS =
DeferredRegister.create(ForgeRegistries.Keys.BIOME_MODIFIER_SERIALIZERS, "yourmodid");

static RegistryObject<Codec<ExampleBiomeModifier>> EXAMPLE_CODEC = BIOME_MODIFIER_SERIALIZERS.register("example", () ->
RecordCodecBuilder.create(builder -> builder.group(
// declare fields
Biome.LIST_CODEC.fieldOf("biomes").forGetter(ExampleBiomeModifier::biomes),
PlacedFeature.CODEC.fieldOf("feature").forGetter(ExampleBiomeModifier::feature)
// declare constructor
).apply(builder, ExampleBiomeModifier::new)));
}
</syntaxhighlight>

We can now implement the codec() method in our biome modifier class:

<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes, Holder<PlacedFeature> feature) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// add a feature to all specified biomes
if (phase == Phase.ADD && biomes.contains(biome))
{
builder.getGenerationSettings().addFeature(Decoration.UNDERGROUND_ORES, feature);
}
}

public Codec<? extends BiomeModifier> codec()
{
return YourMod.EXAMPLE_CODEC.get();
}
}
</syntaxhighlight>

= Biome Modifier JSONs =

Once we've registered a codec for our biome modifier type, we can define jsons for it. Biome modifier jsons must be defined in the directory <code>data/modid/forge/biome_modifier/</code>; a biome modifier at <code>data/modid/forge/biome_modifier/your_biome_modifier.json</code> has the namespaced id <code>modid:your_biome_modifier</code>.

Our codec above defines the json format:

* "biomes" is a special HolderSet field that accepts a single biome id, [list of biome ids], or #biome_tag.
* "feature" accepts a single placed feature id. [https://minecraft.fandom.com/wiki/Placed_feature These can be defined in jsons as well].
* We must also specify "type": "yourmodid:example" to tell the data loader to use our registered codec to read our json.

A json instance of our biome modifier that adds some feature to badlands biomes might look like this:

<syntaxhighlight lang="json">
{
"type": "yourmodid:example",
"biomes": "#minecraft:is_badlands",
"feature": "yourmod:some_feature"
}
</syntaxhighlight>

== Side Note on HolderSets ==

HolderSets are a vanilla feature that, when defined in JSON, can be specified as a single id, list of ids, or tag. Our example above uses a holderset of biomes, so all three of these are valid biome fields:

<syntaxhighlight lang="json">
{
"biomes": "forest",
"biomes": ["forest", "birch_forest"],
"biomes": "#is_forest"
}
</syntaxhighlight>

= Datageneration =

Biome Modifier jsons can be [[Datageneration|datagenerated via GatherDataEvent]]. As biome modifiers are datapack registry objects, this can be done by using JsonCodecProvider#forDatapackRegistry as the data provider. Refer to [[Datageneration/Datapack_Registries]] for additional information on datagenerating datapack registry elements.

= Builtin Biome Modifier Types =

Forge provides the following builtin biome modifier types:

== None ==

A no-op biome modifier type, whose jsons have the following format:

<syntaxhighlight lang="json">
{
"type": "forge:none"
}
</syntaxhighlight>

This allows pack devs or server operators to disable mods' biome modifiers by overriding their biome modifier jsons with the above.

== Add Features ==

This biome modifier type adds placed features to biomes.

<syntaxhighlight lang="json">
{
"type": "forge:add_features", // required
"biomes": "#namespace:your_biome_tag", // accepts a biome id, [list of biome ids], or #namespace:biome_tag
"features": "namespace:your_feature", // accepts a placed feature id, [list of placed feature ids], or #namespace:feature_tag
"step": "underground_ores" // accepts a Decoration enum name
}
</syntaxhighlight>

Decoration steps in order of generation are:
* raw_generation
* lakes
* local_modifications
* underground_structures
* surface_structures
* underground_ores
* underground_decoration
* fluid_springs
* vegetal_decoration
* top_layer_modification

== Remove Features ==

This biome modifier type removes features from biomes.

<syntaxhighlight lang="json">
{
"type": "forge:remove_features", // required
"biomes": "#namespace:your_biome_tag", // accepts a biome id, [list of biome ids], or #namespace:biome_tag
"features": "namespace:your_feature", // accepts a placed feature id, [list of placed feature ids], or #namespace:feature_tag
"steps": "underground_ores" // optional field specifying a Decoration or list of Decorations to remove features from, defaults to all if not specified
}
</syntaxhighlight>

== Add Spawns ==

This biome modifier type adds mob spawns to biomes.

<syntaxhighlight lang="json">
{
"type": "forge:add_spawns", // Required
"biomes": "#namespace:biome_tag", // Accepts a biome id, [list of biome ids], or #namespace:biome_tag
"spawners":
{
"type": "namespace:entity_type", // Type of mob to spawn
"weight": 100, // int, spawn weighting
"minCount": 1, // int, minimum pack size
"maxCount": 4 // int, maximum pack size
}
}
</syntaxhighlight>

== Remove Spawns ==

This biome modifier type removes mob spawns from biomes.

<syntaxhighlight lang="json">
{
"type": "forge:remove_spawns", // Required
"biomes": "#namespace:biome_tag", // Accepts a biome id, [list of biome ids], or #namespace:biome_tag
"entity_types": "#namespace:entitytype_tag" // Accepts an entity type, list, or tag of entitytypes whose spawns are to be removed from the biomes
}
</syntaxhighlight>

= Best Practices =

* Avoid using biome modifiers to add vanilla placed features to biomes, as this may cause a feature cycle violation (the game will crash if two biomes have the same two features in their feature lists but in different orders). Placed features can be referenced in biome jsons or added via biome modifiers, but should not be used in both.

Holder

2022-08-13T20:31:14Z

SizableShrimp: Redirect to Holders

#REDIRECT [[Holders]]

HolderSet

2022-08-13T20:30:15Z

SizableShrimp: Redirect to Holders#HolderSets

#REDIRECT [[Holders#HolderSets]]

HolderSets

2022-08-13T20:29:28Z

SizableShrimp: Redirect to Holders#HolderSets

#REDIRECT [[Holders#HolderSets]]

Holders

2022-08-13T16:36:28Z

SizableShrimp: /* Builtin Custom HolderSet Types */

Holders are a component of vanilla registries representing a registrable value and/or the identifier of that value; they vaguely resemble a vanilla implementation of RegistryObjects, but with substantial semantic and implementation differences. They are used extensively by [[Tags|tags]] and [[Registration#Data_Driven_Entries|datapack registries]]; modders that use these systems should be aware of their functions and caveats.

Datapack registry elements can have reference to HolderSets, which can use tag references to define sets of registry elements.

== Holders ==

=== Properties of Holders ===

Holders in general have the following properties:
* A holder may or may not have a key (a ResourceLocation/ResourceKey identifying the holder/value by name)
* A holder may or may not have a value (e.g. a block or a biome)
* A holder may or may not belong to a specific registry instance
* A holder may or may not be a mutable object
* A holder is associated with zero or more tags

=== Types of Holder ===

There are three categories of holders: direct holders, standalone reference holders, and intrusive reference holders.

==== Direct Holders ====

Direct holders always hold an unregistered value, and never hold a key. Direct holders are generally created when a datapack registry json inline-defines a value in a holder field instead of declaring a reference to another json. Direct holders are immutable records, and never have tags bound to them.

A vanilla example of direct holders being used is in density functions; density functions are often composed of holders of other density functions, but the child functions themselves don't need to be registered, and so many vanilla density functions are created with inline/direct child functions.

Direct holders should not be created for values that must always exist in the registry, or for values whose registry names must be determined at some point.

==== Reference Holders ====

Reference holders refer to registered values; they are created with either a key or a value, with the other property being bound to them later in the registration process. Reference holders belong to a specific registry instance and are aware of which registry they belong to (if multiple copies of a registry exist, as is the case for datapack registries, a reference holder is only valid for a single instance of that registry).

Reference holders are mutable and may have tags bound to them.

===== Standalone Reference Holders =====

Most holders encountered will be standalone reference holders; they are created with a key, and have a value bound to them later. Each registry has at most one standalone reference holder per key; parsing a reference holder in a datapack registry json computes a holder in the relevant registry if it doesn't already exist.

Standalone reference holders are the means by which datapack registry jsons can refer to each other. They have the following lifecycle:

* A datapack registry json is loaded that refers to another registrable by id, e.g. "minecraft:desert"
* A standalone reference holder is retrieved from the relevant registry via a get-or-create operation
* When a datapack registry json is loaded and fully parsed, a holder for that json is get-or-created *and* the parsed value is bound to it
* When registries freeze, the get-or-create operation can no longer create new holders. If any reference holders in the registry are not fully bound at this time (with both a key and a value), an error is raised. This will occur if a datapack registry json refers by id to another datapack registry json that does not exist, and is how these references-by-id are validated.
* Whenever tags load, each tag file's TagKey is bound to all reference holders referred to in that tag (this modifiers the holders in-place).

When datagenerating datapack registry jsons with reference holders, any reference holders *must* be created by the specific registry instances used by the RegistryOps/RegistryAccess used to datagen the jsons, or they will fail to serialize.

===== Intrusive Reference Holders =====

Intrusive reference holders are created with a value and have a key bound to them later. Several static registrable types (blocks, items, fluids, entitytypes, and gameevents) create intrusive holders of themselves when constructed, which have a value bound to them once the value is registered.

Intrusive holders and the means of creating them are deprecated by mojang; this seems to be a hack to allow blocks and friends to quickly look up their registry name. Intrusive holders may be removed in future minecraft releases, and should not be used by mods (value->key lookups can be done via a method in the relevant registry, or by creating standalone holders or RegistryObjects to create name-value pairs).

== HolderSets ==

A HolderSet is an indexable set of holders, and is the preferred means by which datapack registrables can refer to other datapack registrables. Vanilla frequently uses holdersets to wire worldgen jsons together, e.g. a structure json has a holderset field for which biomes the structure can spawn in.

Vanilla has two types of holdersets and three json formats; forge expands the holderset serializer to allow additional types of holdersets. A holderset field in a json can accept a single element, a list of elements, a tag ID, or one of forge's special formats, making datapack creation very flexible when holderset fields are used.

<syntaxhighlight lang="json">
{
"a_biome": "desert", // single element holderset
"some_biomes": ["plains", "forest"], // list holderset
"biome_tag": "#is_plains", // tag holderset
"expanded_forge_format": // more on these later
{
"type": "modid:custom_holderset_type",
// additional fields as specified by the type
}
}
</syntaxhighlight>

[[Codecs]] can be created for holdersets to allow holdersets to be read from jsons; however, a holderset codec must be created for each registry holdersets can be made for, e.g. Biome.LIST_OF_LISTS_CODEC is the codec for HolderSet<Biome>.

HolderSets should generally only be serialized when used as components of unsynced (server-only) datapack registry jsons, such as in worldgen features. HolderSets that are serialized without RegistryOps for registry context (including when synced to clients in synced datapack registries, which do not serialize with registry context) will be deserialized as lists of unregistered objects.

=== Types of HolderSets ===

==== Direct HolderSets ====

Direct HolderSets represent an immutable list of holders. They can be defined in json as single elements or lists of elements (the single element format simply parses as a list holderset with one element in it).

<syntaxhighlight lang="json">
{
"a_biome": "desert", // single element holderset
"some_biomes": ["plains", "forest"], // list holderset
}
</syntaxhighlight>

==== Named HolderSets ====

Named HolderSets represent a tag. Named HolderSets are mutable; they cache a list and a set of holders, and this cache is reset each time tags reload.

<syntaxhighlight lang="json">
{
"biome_tag": "#is_plains", // tag holderset
}
</syntaxhighlight>

==== Custom HolderSet Types ====

Forge expands the holderset codecs to allow additional json formats. Custom holderset serializers can be registered by creating a deferred register for ForgeRegistries.Keys.HOLDER_SET_TYPES, though the builtin types provided by forge should be sufficient for most use cases.

====Builtin Custom HolderSet Types====
Forge provides four builtin holderset types, allowing for additional set operations and representations in datapack registry jsons. The <code>and</code>, <code>or</code>,
and <code>not</code> types are composed of other holdersets, and are therefore potentially mutable as they may be composed of mutable tag holdersets whose values are recalculated after tags reload.
=====Any=====
The <code>forge:any</code> holderset type represents the set of all elements of the relevant registry.

<syntaxhighlight lang="json">
{
"biomes":
{
"type": "forge:any"
}
}
</syntaxhighlight>

=====And=====
The <code>forge:and</code> type represents an intersection of other holdersets.

<syntaxhighlight lang="json">
{
"biomes":
{
"type": "forge:and",
"values":
[
// list of holdersets of any format, different formats (string, list, object) can be mixed here
"#is_plains",
"#is_overworld"
]
}
}
</syntaxhighlight>
=====Or=====
The <code>forge:or</code> type represents a union of other holdersets.

<syntaxhighlight lang="json">
{
"biomes":
{
"type": "forge:or",
"values":
[
// list of holdersets of any format, different formats (string, list, object) can be mixed here
"#is_plains",
["swamp", "mangrove_swamp"]
]
}
}
</syntaxhighlight>
=====Not=====
The <code>forge:not</code> type represents the set of all elements in the registry that do not belong to the specified holderset.

<syntaxhighlight lang="json">
{
"biomes":
{
"type": "forge:not",
"value": "#is_plains" // holderset of any format (string, list, or object)
}
}
</syntaxhighlight>

Item Overrides/1.18

2022-06-16T01:26:42Z

SizableShrimp: Redirect to Item Properties/1.18

#REDIRECT [[Item Properties/1.18]]

Item Overrides

2022-06-16T01:26:17Z

SizableShrimp: Redirect to Item Properties

#REDIRECT [[Item Properties]]

Registration

2022-06-13T00:50:13Z

SizableShrimp: Clarify non-vanilla registries tip

Registration is the process of making an object (such as an item or block) known to the game during runtime. If some objects are not registered, this could cause crashes even before the game is fully loaded or arbitrary behaviors such as bottlenecking mod compatibility for world generation.

Most objects that are known within the game are handled by a <code>Registry</code>. Each registry uniquely defines each object through a "registry name" via a [[Using Resources#ResourceLocation|ResourceLocation]].

{{Tip|In a global context, each object is universally unique through its <code>ResourceKey</code>: a concatenation of its registry's id and the object's registry name.}}

Due to the inconsistent ordering and registration process vanilla uses, Forge wraps most vanilla registries using <code>IForgeRegistry</code>. This guarantees that the loading order for these wrapped registries will be <code>Block</code>, <code>Item</code>, and then the rest of the wrapped registries in alphabetical order. All registries supported by Forge can be found within the <code>ForgeRegistries</code> class. Since all registry names are unique to a specific registry, different registry objects within different registries can have the same name (e.g. a <code>Block</code> and an <code>Item</code> each hold a registry object named <code>examplemod:object</code>.

{{Tip/Warning|If two registry objects within the same registry have the same name, the second object will override the first. The only registry that will throw an <code>IllegalArgumentException</code> is the <code>DataSerializerEntry</code> registry.}}

== Methods for Registering ==

There are two proper ways to register objects within an associated wrapped Forge registry: the <code>DeferredRegister</code> class, and the <code>RegisterEvent</code> lifecycle event.

=== DeferredRegister ===

<code>DeferredRegister</code> is an abstraction layer over the registry event used to register objects. It maintains a map of "registry name" to their associated suppliers and resolves those suppliers during <code>RegisterEvent</code> for the associated registry. This method is the currently recommended, and documented, way to handle these objects as it provides convenience and safety for those who want to statically initialize objects while avoiding some issues associated with it.

{{Tip/Important|When using <code>DeferredRegister</code>s with non-vanilla registries, the registry key or the registry name should be supplied to the <code>create</code> method. These include the custom Forge registries for entity data serializers, global loot modifier serializers, world presets, and biome modifier serializers. Calling <code>Supplier#get</code> on a <code>Supplier<IForgeRegistry<?>></code> when making a DeferredRegister will return null because the registry does not exist yet.}}

An example of a mod registering a custom block:

{{Template:Tabs/Code_Snippets
|java=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

public ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().getModEventBus());
}
|kotlin=private val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

val EXAMPLE_BLOCK: RegistryObject<Block> = BLOCKS.register("example_block") { Block(BlockBehaviour.Properties.of(Material.ROCK)) }

internal class ExampleMod {
init {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus)
}
}
|scala=object ExampleMod {
private final val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

final val EXAMPLE_BLOCK = registerBlock("example_block", () => new Block(BlockBehaviour.Properties.of(Material.ROCK)))
}
class ExampleMod {
BLOCKS.register(FMLJavaModLoadingContext.get.getModEventBus)
}
|groovy=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus);
}
|}}

{{Tip|When using a <code>DeferredRegister</code> to register any object, the name inputted will be automatically prefixed with the mod id passed in, giving the above object a "registry name" of <code>examplemod:example_block</code>.}}

=== RegisterEvent ===

The <code>RegisterEvent</code> is the second way register objects. This [[Events|event]] is fired for each registry synchronously in vanilla registry order after <code>FMLConstructModEvent</code> and before the configs are loaded. Objects are registered using <code>#register</code> by passing in the registry key, the name of the registry object, and the object itself. There is an additional <code>#register</code> overload which takes in a consumed helper to register an object with a given name. It is recommended to use this method to avoid unnecessary object creation.

Here is an example: (the event handler is registered on the '''mod event bus''')

{{Template:Tabs/Code_Snippets
|java=@SubscribeEvent
public void register(RegisterEvent event) {
event.register(ForgeRegistries.Keys.BLOCKS,
helper -> helper.register(new ResourceLocation(MODID, "example_block"), new Block(...))
);
}
|kotlin=@JvmStatic
@SubscribeEvent
private fun register(event: RegisterEvent) =
event.register(ForgeRegistries.Keys.BLOCKS) {
helper -> helper.register(ResourceLocation(MODID, "example_block"), Block(...))
}
|scala=@SubscribeEvent
def register(event: RegisterEvent): Unit =
event.register(ForgeRegistries.Keys.BLOCKS,
helper => helper.register(new ResourceLocation(MODID, "example_block"), new Block(...))
)
|}}

{{Tip/Important|Since all objects registered must be singleton, some classes cannot by themselves be registered. Instead, <code>*Type</code> classes are registered and used in the formers' constructors to wrap the flyweight objects. For example, a [[Basics_of_Block_Entities|<code>BlockEntity</code>]] is wrapped via <code>BlockEntityType</code>, and <code>Entity</code> is wrapped via <code>EntityType</code>. These <code>*Type</code> classes hold factories that simply create the containing type on demand.

These factory holders are created through the use of their <code>*Type$Builder</code> classes. An example: (<code>REGISTER</code> here refers to a <code>DeferredRegister<BlockEntityType<?>></code>)

{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<BlockEntityType<ExampleBlockEntity>> EXAMPLE_BLOCK_ENTITY = REGISTER.register(
"example_block_entity", () -> BlockEntityType.Builder.of(ExampleBlockEntity::new, EXAMPLE_BLOCK.get()).build(null)
);
|kotlin=val EXAMPLE_BLOCK_ENTITY: RegistryObject<BlockEntityType<ExampleBlockEntity>> = REGISTER.register("example_block_entity") { BlockEntityType.Builder.of(::ExampleBlockEntity, EXAMPLE_BLOCK.get()).build(null)) }
|scala=final val EXAMPLE_BLOCK_ENTITY = REGISTER.register("example_block_entity", () => BlockEntityType.Builder.of(() => new ExampleBlockEntity(), GeneralRegistrar.EXAMPLE_BLOCK.get).build(null))
|}}
}}

=== Non-Forge Registries ===

Not all vanilla registries are wrapped as a Forge registry. To register objects to any one of these registries, create a <code>DeferredRegister</code> via the <code>#create</code> overload which takes in a resource key of the registry and the mod id to register the entries for. Then simply call <code>#register</code> like any other <code>DeferredRegister</code>.

{{Template:Tabs/Code_Snippets
|java=private static final DeferredRegister<LootItemConditionType> REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID);

public static final RegistryObject<LootItemConditionType> EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () -> new LootItemConditionType(...));
|kotlin=private val REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID)

val EXAMPLE_LOOT_ITEM_CONDITION_TYPE : RegistryObject<LootItemConditionType> = REGISTER.register("example_loot_item_condition_type") {
LootItemConditionType(...)
}
|scala=private final val REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID)

final val EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () => new LootItemConditionType(...))
|groovy=private static final DeferredRegister<LootItemConditionType> REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID);

public static final RegistryObject<LootItemConditionType> EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () -> new LootItemConditionType(...));
|}}

If you attempt to make one of these instances require an instance of another registry object, you should use the lazy initialization method mentioned above to register the object in the correct order.

=== Data Driven Entries ===

Registries are considered to be data driven if they are located within <code>RegistryAccess</code> with the exception of <code>LevelStem</code> and <code>Level</code>.

These registry objects only need to be registered within code if they are to be used within a pre-existing registry object (e.g. a <code>PlacedFeature</code> for ore generation within an overworld <code>Biome</code>). Otherwise, their instance can be purely registered using a JSON file.

If a data driven registry object has to be registered within code, a dummy object should be supplied to hold a "registry name" and then constructed within a JSON file.

== Referencing Registered Objects ==

Each forge registered object should not be statically initialized nor reference another instance being registered. They must always be a new, singleton instance that is resolved during when <code>RegisterEvent</code> is called for their registry. This is to maintain a sane loading order for registries and their objects along with dynamic loading/unloading of mods.

Forge registered objects must always be referenced through a <code>RegistryObject</code> or a field with <code>@ObjectHolder</code>.

===Using RegistryObjects===
<code>RegistryObject</code>s can be used to retrieve references to registered objects once they become available. Their references are updated along with all <code>@ObjectHolder</code> annotations after the registry that <code>RegisterEvent</code> is called for is dispatched and frozen.

A <code>RegistryObject</code> can be retrieved as a result of using <code>DeferredRegister</code> or calling the static factory <code>RegistryObject#create</code>. Each static factory takes in the "registry name" of the object being referenced and one of the following: a <code>IForgeRegistry</code>, a registry name of the type <code>ResourceLocation</code>, or a registry key of the type <code>ResourceKey<? extends Registry<?>></code>. The <code>RegistryObject</code> can be stored within some field and retrieve the registered object using <code>#get</code>.

An example using <code>RegistryObject</code>:
{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<Item> EXAMPLE_ITEM = RegistryObject.create(new ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS);

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
public static final RegistryObject<ExampleRegistry> EXAMPLE_OBJECT = RegistryObject.create(new ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod");
|kotlin=val EXAMPLE_ITEM: RegistryObject<Item> = RegistryObject.create(ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS)

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
val EXAMPLE_OBJECT: RegistryObject<ExampleRegistry> = RegistryObject.create(ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod")
|scala=final val EXAMPLE_ITEM = RegistryObject.create(new ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS)

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
final val EXAMPLE_OBJECT = RegistryObject.create(new ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod");
|}}

{{Tip/Important|All vanilla objects are bootstrapped and registered before mods are loaded. As such, they can be referenced as is without any issues.}}

=== Using @ObjectHolder ===

Forge registry objects can also be injected into <code>public static</code> fields with either their class or that field annotated with <code>@ObjectHolder</code>. There must be enough information to construct a <code>ResourceLocation</code> to identify a single object within a specific registry.

The rules for <code>@ObjectHolder</code> are as follows:

* If the class is annotated with <code>@ObjectHolder</code>, its value will be the default namespace for all fields within if not explicitly defined
* If the class is annotated with <code>@Mod</code>, the modid will be the default namespace for all annotated fields within if not explicitly defined
* A field is considered for injection if:
** it has at least the modifiers <code>public static</code>; and
** one of the following conditions are true:
*** the '''enclosing class''' has an <code>@ObjectHolder</code> annotation, and the field is <code>final</code>, and:
**** the name value is the field's name; and
**** the namespace value is the enclosing class's namespace
**** ''An exception is thrown if the namespace value cannot be found and inherited''
*** the '''field''' is annotated with <code>@ObjectHolder</code>, and:
**** the name value is explicitly defined; and
**** the namespace value is either explicitly defined or the enclosing class's namespace
** the field type or one of its supertypes corresponds to a valid registry (e.g. <code>Item</code> or <code>ArrowItem</code> for the <code>Item</code> registry)
** ''An exception is thrown if a field does not have a corresponding registry.''
* ''An exception is thrown if the resulting <code>ResourceLocation</code> is incomplete or invalid (non-valid characters in path)''
* If no other errors or exceptions occur, the field will be injected
* If all of the above rules do not apply, no action will be taken (and a message may be logged)

<code>@ObjectHolder</code> annotated fields are injected with their associated object values after <code>RegisterEvent</code> is fired for their registry, along with <code>RegistryObject</code>s.

{{Tip/Warning|If the object does not exist in the registry when it is to be injected, a debug message will be logged, and no value will be injected. If the object is found, but the field cannot be set, a warning message will be logged instead.}}

As these rules are rather complicated, here are some examples:
<div class="mw-collapsible mw-collapsed" style="border: solid 2px; padding: 2px 5px; margin-top: 3px">
<div style="font-weight:bold;line-height:1.6;">Example uses of <code>@ObjectHolder</code></div>
<div class="mw-collapsible-content" style="overflow: auto; white-space: nowrap;">
<syntaxhighlight lang="java">
@ObjectHolder("minecraft") // Inheritable resource namespace: "minecraft"
class AnnotatedHolder {
public static final Block diamond_block = null; // No annotation. [public static final] is required.
// Block has a corresponding registry: [Block]
// Name path is the name of the field: "diamond_block"
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:diamond_block" from the [Block] registry

@ObjectHolder("ambient.cave")
public static SoundEvent ambient_sound = null; // Annotation present. [public static] is required.
// SoundEvent has a corresponding registry: [SoundEvent]
// Name path is the value of the annotation: "ambient.cave"
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:ambient.cave" from the [SoundEvent] registry

// Assume for the next entry that [ManaType] is a valid registry.
@ObjectHolder("neomagicae:coffeinum")
public static final ManaType coffeinum = null; // Annotation present. [public static] is required. [final] is optional.
// ManaType has a corresponding registry: [ManaType] (custom registry)
// Resource location is explicitly defined: "neomagicae:coffeinum"
// To inject: "neomagicae:coffeinum" from the [ManaType] registry

public static final Item ENDER_PEARL = null; // No annotation. [public static final] is required.
// Item has a corresponding registry: [Item].
// Name path is the name of the field: "ENDER_PEARL" -> "ender_pearl"
// !! ^ Field name is valid, because they are
// converted to lowercase automatically.
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:ender_pearl" from the [Item] registry

@ObjectHolder("minecraft:arrow")
public static final ArrowItem arrow = null; // Annotation present. [public static] is required. [final] is optional.
// ArrowItem does not have a corresponding registry.
// ArrowItem's supertype of Item has a corresponding registry: [Item]
// Resource location is explicitly defined: "minecraft:arrow"
// To inject: "minecraft:arrow" from the [Item] registry

public static Block bedrock = null; // No annotation, so [public static final] is required.
// Therefore, the field is ignored.

public static final CreativeModeTab group = null; // No annotation. [public static final] is required.
// CreativeModeTab does not have a corresponding registry.
// No supertypes of CreativeModeTab has a corresponding registry.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}

class UnannotatedHolder { // Note the lack of an @ObjectHolder annotation on this class.
@ObjectHolder("minecraft:flame")
public static final Enchantment flame = null; // Annotation present. [public static] is required. [final] is optional.
// Enchantment has corresponding registry: [Enchantment].
// Resource location is explicitly defined: "minecraft:flame"
// To inject: "minecraft:flame" from the [Enchantment] registry

public static final Biome ice_flat = null; // No annotation on the enclosing class.
// Therefore, the field is ignored.

@ObjectHolder("minecraft:creeper")
public static Entity creeper = null; // Annotation present. [public static] is required.
// Entity does not have a corresponding registry.
// No supertypes of Entity has a corresponding registry.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.

@ObjectHolder("levitation")
public static final Potion levitation = null; // Annotation present. [public static] is required. [final] is optional.
// Potion has a corresponding registry: [Potion].
// Name path is the value of the annotation: "levitation"
// Namespace is not explicitly defined.
// No annotation in enclosing class.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}
</syntaxhighlight>
</div>
</div>

== Creating Custom Registries ==

Creating custom registries for your mod might be useful if you want other mods to add new things to your system. For example, you might have magic spells and want to allow other mods to add new spells. For this you will want to make a registry (eg. "mymagicmod:spells"). This way, other mods will be able to register things to that list, and you won't have to do anything else.

Just like with registering a new item or block you have two ways of making a new registry. Each method takes in a <code>RegistryBuilder</code> which is used to build an <code>IForgeRegistry</code>. Each builder should have its name set via <code>#setName</code> before being created.

=== With DeferredRegister ===

The first method involves the second static constructor: <code>DeferredRegister#create(ResourceLocation, String)</code>. From there, we can construct the registry using <code>#makeRegistry</code>. This will already populate <code>#setName</code> for us. This method also returns a supplier of the registry which we can use after the <code>NewRegistryEvent</code> is called.

Here is an example:

{{Template:Tabs/Code_Snippets
|java=public static final DeferredRegister<ExampleRegistry> EXAMPLE = DeferredRegister.create(new ResourceLocation(MODID, "example_registry"), MODID);

public static final Supplier<IForgeRegistry<ExampleRegistry>> REGISTRY = EXAMPLE.makeRegistry(RegistryBuilder::new);
|kotlin=val EXAMPLE: DeferredRegister<ExampleRegistry> = DeferredRegister.create(ResourceLocation(MODID, "example_registry"), MODID)

val REGISTRY: IForgeRegistry<ExampleRegistry> by lazy {
EXAMPLE.makeRegistry(::RegistryBuilder).get()
}
|scala=final val EXAMPLE = DeferredRegister.create(new ResourceLocation(MODID, "example_registry"), MODID)

final lazy val REGISTRY = EXAMPLE.makeRegistry(() => new RegistryBuilder).get
|}}

=== Using <code>NewRegistryEvent</code> ===

The second method can be done during the <code>NewRegistryEvent</code> event. Using <code>NewRegistryEvent#create</code>, you can pass in a <code>RegistryBuilder</code> directly. This method will return a <code>Supplier<IForgeRegistry<V>></code> that can be stored and queried after the event is fired to gain access to your <code>IForgeRegistry</code> instance.

Here is an example: (the event handler is registered on the '''mod event bus''')

<syntaxhighlight lang="Java">
public static Supplier<IForgeRegistry<ExampleRegistry>> registrySupplier = null;

@SubscribeEvent
public void onNewRegistry(NewRegistryEvent event){
RegistryBuilder<ExampleRegistry> registryBuilder = new RegistryBuilder<>();
registryBuilder.setName(new ResourceLocation(MODID, "example_registry");
registrySupplier = event.create(registryBuilder);
}
</syntaxhighlight>

== Handling Missing Entries ==

When loading a pre-existing world after removing mods or updating versions, there are cases where certain registry objects will cease to exist. In these cases, it is possible to specify actions to remove a mapping, prevent the world from loading, or remap the name as needed. This can be done through the third of the registry events: <code>MissingMappingsEvent</code>. Within the event, you can grab an immutable list of missing mappings associated with a mod id for a given registry via <code>#getMappings</code> or a list of all mappings via <code>#getAllMappings</code>.

For each <code>Mapping</code>, you can either execute one of the following methods:
* <code>#ignore</code> which abandons the entry when loading
* <code>#warn</code> which warns the user about the missing entry but continues loading
* <code>#fail</code> which prevents the world from loading
* <code>#remap</code> which remaps the entry to the specified non-null object in the same registry

If none of the above are specified, then the default action of notifying the user about the missing mappings occur.

Here is an example: (the event handler is registered on the '''forge event bus''')

{{Template:Tabs/Code_Snippets
|java=// This will ignore any missing test items from the specified world
@SubscribeEvent
public void onMissing(final MissingMappingsEvent event) {
event.getMappings(ForgeRegistries.Keys.ITEMS, MODID).stream()
.filter(mapping -> mapping.key.getPath().contains("test"))
.forEach(Mapping::ignore);
}
|groovy=// This will ignore any missing test items from the specified world
@SubscribeEvent
void onMissing(final MissingMappingsEvent event) {
event.getMappings(ForgeRegistries.Keys.ITEMS, MODID).stream()
.filter(mapping -> mapping.key.path.contains("test"))
.forEach(Mapping::ignore);
}
|}}

[[Category:Common Concepts]]

Registration

2022-06-12T06:23:41Z

SizableShrimp: /* Using `NewRegistryEvent` */ Fix header

Registration is the process of making an object (such as an item or block) known to the game during runtime. If some objects are not registered, this could cause crashes even before the game is fully loaded or arbitrary behaviors such as bottlenecking mod compatibility for world generation.

Most objects that are known within the game are handled by a <code>Registry</code>. Each registry uniquely defines each object through a "registry name" via a [[Using Resources#ResourceLocation|ResourceLocation]].

{{Tip|In a global context, each object is universally unique through its <code>ResourceKey</code>: a concatenation of its registry's id and the object's registry name.}}

Due to the inconsistent ordering and registration process vanilla uses, Forge wraps most vanilla registries using <code>IForgeRegistry</code>. This guarantees that the loading order for these wrapped registries will be <code>Block</code>, <code>Item</code>, and then the rest of the wrapped registries in alphabetical order. All registries supported by Forge can be found within the <code>ForgeRegistries</code> class. Since all registry names are unique to a specific registry, different registry objects within different registries can have the same name (e.g. a <code>Block</code> and an <code>Item</code> each hold a registry object named <code>examplemod:object</code>.

{{Tip/Warning|If two registry objects within the same registry have the same name, the second object will override the first. The only registry that will throw an <code>IllegalArgumentException</code> is the <code>DataSerializerEntry</code> registry.}}

== Methods for Registering ==

There are two proper ways to register objects within an associated wrapped Forge registry: the <code>DeferredRegister</code> class, and the <code>RegisterEvent</code> lifecycle event.

=== DeferredRegister ===

<code>DeferredRegister</code> is an abstraction layer over the registry event used to register objects. It maintains a map of "registry name" to their associated suppliers and resolves those suppliers during <code>RegisterEvent</code> for the associated registry. This method is the currently recommended, and documented, way to handle these objects as it provides convenience and safety for those who want to statically initialize objects while avoiding some issues associated with it.

An example of a mod registering a custom block:

{{Template:Tabs/Code_Snippets
|java=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

public ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().getModEventBus());
}
|kotlin=private val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

val EXAMPLE_BLOCK: RegistryObject<Block> = BLOCKS.register("example_block") { Block(BlockBehaviour.Properties.of(Material.ROCK)) }

internal class ExampleMod {
init {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus)
}
}
|scala=object ExampleMod {
private final val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

final val EXAMPLE_BLOCK = registerBlock("example_block", () => new Block(BlockBehaviour.Properties.of(Material.ROCK)))
}
class ExampleMod {
BLOCKS.register(FMLJavaModLoadingContext.get.getModEventBus)
}
|groovy=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus);
}
|}}

{{Tip|When using a <code>DeferredRegister</code> to register any object, the name inputted will be automatically prefixed with the mod id passed in, giving the above object a "registry name" of <code>examplemod:example_block</code>.}}

=== RegisterEvent ===

The <code>RegisterEvent</code> is the second way register objects. This [[Events|event]] is fired for each registry synchronously in vanilla registry order after <code>FMLConstructModEvent</code> and before the configs are loaded. Objects are registered using <code>#register</code> by passing in the registry key, the name of the registry object, and the object itself. There is an additional <code>#register</code> overload which takes in a consumed helper to register an object with a given name. It is recommended to use this method to avoid unnecessary object creation.

Here is an example: (the event handler is registered on the '''mod event bus''')

{{Template:Tabs/Code_Snippets
|java=@SubscribeEvent
public void register(RegisterEvent event) {
event.register(ForgeRegistries.Keys.BLOCKS,
helper -> helper.register(new ResourceLocation(MODID, "example_block"), new Block(...))
);
}
|kotlin=@JvmStatic
@SubscribeEvent
private fun register(event: RegisterEvent) =
event.register(ForgeRegistries.Keys.BLOCKS) {
helper -> helper.register(ResourceLocation(MODID, "example_block"), Block(...))
}
|scala=@SubscribeEvent
def register(event: RegisterEvent): Unit =
event.register(ForgeRegistries.Keys.BLOCKS,
helper => helper.register(new ResourceLocation(MODID, "example_block"), new Block(...))
)
|}}

{{Tip/Important|Since all objects registered must be singleton, some classes cannot by themselves be registered. Instead, <code>*Type</code> classes are registered and used in the formers' constructors to wrap the flyweight objects. For example, a [[Basics_of_Block_Entities|<code>BlockEntity</code>]] is wrapped via <code>BlockEntityType</code>, and <code>Entity</code> is wrapped via <code>EntityType</code>. These <code>*Type</code> classes hold factories that simply create the containing type on demand.

These factory holders are created through the use of their <code>*Type$Builder</code> classes. An example: (<code>REGISTER</code> here refers to a <code>DeferredRegister<BlockEntityType<?>></code>)

{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<BlockEntityType<ExampleBlockEntity>> EXAMPLE_BLOCK_ENTITY = REGISTER.register(
"example_block_entity", () -> BlockEntityType.Builder.of(ExampleBlockEntity::new, EXAMPLE_BLOCK.get()).build(null)
);
|kotlin=val EXAMPLE_BLOCK_ENTITY: RegistryObject<BlockEntityType<ExampleBlockEntity>> = REGISTER.register("example_block_entity") { BlockEntityType.Builder.of(::ExampleBlockEntity, EXAMPLE_BLOCK.get()).build(null)) }
|scala=final val EXAMPLE_BLOCK_ENTITY = REGISTER.register("example_block_entity", () => BlockEntityType.Builder.of(() => new ExampleBlockEntity(), GeneralRegistrar.EXAMPLE_BLOCK.get).build(null))
|}}
}}

=== Non-Forge Registries ===

Not all vanilla registries are wrapped as a Forge registry. To register objects to any one of these registries, create a <code>DeferredRegister</code> via the <code>#create</code> overload which takes in a resource key of the registry and the mod id to register the entries for. Then simply call <code>#register</code> like any other <code>DeferredRegister</code>.

{{Template:Tabs/Code_Snippets
|java=private static final DeferredRegister<LootItemConditionType> REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID);

public static final RegistryObject<LootItemConditionType> EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () -> new LootItemConditionType(...));
|kotlin=private val REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID)

val EXAMPLE_LOOT_ITEM_CONDITION_TYPE : RegistryObject<LootItemConditionType> = REGISTER.register("example_loot_item_condition_type") {
LootItemConditionType(...)
}
|scala=private final val REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID)

final val EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () => new LootItemConditionType(...))
|groovy=private static final DeferredRegister<LootItemConditionType> REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID);

public static final RegistryObject<LootItemConditionType> EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () -> new LootItemConditionType(...));
|}}

If you attempt to make one of these instances require an instance of another registry object, you should use the lazy initialization method mentioned above to register the object in the correct order.

=== Data Driven Entries ===

Registries are considered to be data driven if they are located within <code>RegistryAccess</code> with the exception of <code>LevelStem</code> and <code>Level</code>.

These registry objects only need to be registered within code if they are to be used within a pre-existing registry object (e.g. a <code>PlacedFeature</code> for ore generation within an overworld <code>Biome</code>). Otherwise, their instance can be purely registered using a JSON file.

If a data driven registry object has to be registered within code, a dummy object should be supplied to hold a "registry name" and then constructed within a JSON file.

== Referencing Registered Objects ==

Each forge registered object should not be statically initialized nor reference another instance being registered. They must always be a new, singleton instance that is resolved during when <code>RegisterEvent</code> is called for their registry. This is to maintain a sane loading order for registries and their objects along with dynamic loading/unloading of mods.

Forge registered objects must always be referenced through a <code>RegistryObject</code> or a field with <code>@ObjectHolder</code>.

===Using RegistryObjects===
<code>RegistryObject</code>s can be used to retrieve references to registered objects once they become available. Their references are updated along with all <code>@ObjectHolder</code> annotations after the registry that <code>RegisterEvent</code> is called for is dispatched and frozen.

A <code>RegistryObject</code> can be retrieved as a result of using <code>DeferredRegister</code> or calling the static factory <code>RegistryObject#create</code>. Each static factory takes in the "registry name" of the object being referenced and one of the following: a <code>IForgeRegistry</code>, a registry name of the type <code>ResourceLocation</code>, or a registry key of the type <code>ResourceKey<? extends Registry<?>></code>. The <code>RegistryObject</code> can be stored within some field and retrieve the registered object using <code>#get</code>.

An example using <code>RegistryObject</code>:
{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<Item> EXAMPLE_ITEM = RegistryObject.create(new ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS);

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
public static final RegistryObject<ExampleRegistry> EXAMPLE_OBJECT = RegistryObject.create(new ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod");
|kotlin=val EXAMPLE_ITEM: RegistryObject<Item> = RegistryObject.create(ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS)

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
val EXAMPLE_OBJECT: RegistryObject<ExampleRegistry> = RegistryObject.create(ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod")
|scala=final val EXAMPLE_ITEM = RegistryObject.create(new ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS)

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
final val EXAMPLE_OBJECT = RegistryObject.create(new ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod");
|}}

{{Tip/Important|All vanilla objects are bootstrapped and registered before mods are loaded. As such, they can be referenced as is without any issues.}}

=== Using @ObjectHolder ===

Forge registry objects can also be injected into <code>public static</code> fields with either their class or that field annotated with <code>@ObjectHolder</code>. There must be enough information to construct a <code>ResourceLocation</code> to identify a single object within a specific registry.

The rules for <code>@ObjectHolder</code> are as follows:

* If the class is annotated with <code>@ObjectHolder</code>, its value will be the default namespace for all fields within if not explicitly defined
* If the class is annotated with <code>@Mod</code>, the modid will be the default namespace for all annotated fields within if not explicitly defined
* A field is considered for injection if:
** it has at least the modifiers <code>public static</code>; and
** one of the following conditions are true:
*** the '''enclosing class''' has an <code>@ObjectHolder</code> annotation, and the field is <code>final</code>, and:
**** the name value is the field's name; and
**** the namespace value is the enclosing class's namespace
**** ''An exception is thrown if the namespace value cannot be found and inherited''
*** the '''field''' is annotated with <code>@ObjectHolder</code>, and:
**** the name value is explicitly defined; and
**** the namespace value is either explicitly defined or the enclosing class's namespace
** the field type or one of its supertypes corresponds to a valid registry (e.g. <code>Item</code> or <code>ArrowItem</code> for the <code>Item</code> registry)
** ''An exception is thrown if a field does not have a corresponding registry.''
* ''An exception is thrown if the resulting <code>ResourceLocation</code> is incomplete or invalid (non-valid characters in path)''
* If no other errors or exceptions occur, the field will be injected
* If all of the above rules do not apply, no action will be taken (and a message may be logged)

<code>@ObjectHolder</code> annotated fields are injected with their associated object values after <code>RegisterEvent</code> is fired for their registry, along with <code>RegistryObject</code>s.

{{Tip/Warning|If the object does not exist in the registry when it is to be injected, a debug message will be logged, and no value will be injected. If the object is found, but the field cannot be set, a warning message will be logged instead.}}

As these rules are rather complicated, here are some examples:
<div class="mw-collapsible mw-collapsed" style="border: solid 2px; padding: 2px 5px; margin-top: 3px">
<div style="font-weight:bold;line-height:1.6;">Example uses of <code>@ObjectHolder</code></div>
<div class="mw-collapsible-content" style="overflow: auto; white-space: nowrap;">
<syntaxhighlight lang="java">
@ObjectHolder("minecraft") // Inheritable resource namespace: "minecraft"
class AnnotatedHolder {
public static final Block diamond_block = null; // No annotation. [public static final] is required.
// Block has a corresponding registry: [Block]
// Name path is the name of the field: "diamond_block"
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:diamond_block" from the [Block] registry

@ObjectHolder("ambient.cave")
public static SoundEvent ambient_sound = null; // Annotation present. [public static] is required.
// SoundEvent has a corresponding registry: [SoundEvent]
// Name path is the value of the annotation: "ambient.cave"
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:ambient.cave" from the [SoundEvent] registry

// Assume for the next entry that [ManaType] is a valid registry.
@ObjectHolder("neomagicae:coffeinum")
public static final ManaType coffeinum = null; // Annotation present. [public static] is required. [final] is optional.
// ManaType has a corresponding registry: [ManaType] (custom registry)
// Resource location is explicitly defined: "neomagicae:coffeinum"
// To inject: "neomagicae:coffeinum" from the [ManaType] registry

public static final Item ENDER_PEARL = null; // No annotation. [public static final] is required.
// Item has a corresponding registry: [Item].
// Name path is the name of the field: "ENDER_PEARL" -> "ender_pearl"
// !! ^ Field name is valid, because they are
// converted to lowercase automatically.
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:ender_pearl" from the [Item] registry

@ObjectHolder("minecraft:arrow")
public static final ArrowItem arrow = null; // Annotation present. [public static] is required. [final] is optional.
// ArrowItem does not have a corresponding registry.
// ArrowItem's supertype of Item has a corresponding registry: [Item]
// Resource location is explicitly defined: "minecraft:arrow"
// To inject: "minecraft:arrow" from the [Item] registry

public static Block bedrock = null; // No annotation, so [public static final] is required.
// Therefore, the field is ignored.

public static final CreativeModeTab group = null; // No annotation. [public static final] is required.
// CreativeModeTab does not have a corresponding registry.
// No supertypes of CreativeModeTab has a corresponding registry.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}

class UnannotatedHolder { // Note the lack of an @ObjectHolder annotation on this class.
@ObjectHolder("minecraft:flame")
public static final Enchantment flame = null; // Annotation present. [public static] is required. [final] is optional.
// Enchantment has corresponding registry: [Enchantment].
// Resource location is explicitly defined: "minecraft:flame"
// To inject: "minecraft:flame" from the [Enchantment] registry

public static final Biome ice_flat = null; // No annotation on the enclosing class.
// Therefore, the field is ignored.

@ObjectHolder("minecraft:creeper")
public static Entity creeper = null; // Annotation present. [public static] is required.
// Entity does not have a corresponding registry.
// No supertypes of Entity has a corresponding registry.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.

@ObjectHolder("levitation")
public static final Potion levitation = null; // Annotation present. [public static] is required. [final] is optional.
// Potion has a corresponding registry: [Potion].
// Name path is the value of the annotation: "levitation"
// Namespace is not explicitly defined.
// No annotation in enclosing class.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}
</syntaxhighlight>
</div>
</div>

== Creating Custom Registries ==

Creating custom registries for your mod might be useful if you want other mods to add new things to your system. For example, you might have magic spells and want to allow other mods to add new spells. For this you will want to make a registry (eg. "mymagicmod:spells"). This way, other mods will be able to register things to that list, and you won't have to do anything else.

Just like with registering a new item or block you have two ways of making a new registry. Each method takes in a <code>RegistryBuilder</code> which is used to build an <code>IForgeRegistry</code>. Each builder should have its name set via <code>#setName</code> before being created.

=== With DeferredRegister ===

The first method involves the second static constructor: <code>DeferredRegister#create(ResourceLocation, String)</code>. From there, we can construct the registry using <code>#makeRegistry</code>. This will already populate <code>#setName</code> for us. This method also returns a supplier of the registry which we can use after the <code>NewRegistryEvent</code> is called.

Here is an example:

{{Template:Tabs/Code_Snippets
|java=public static final DeferredRegister<ExampleRegistry> EXAMPLE = DeferredRegister.create(new ResourceLocation(MODID, "example_registry"), MODID);

public static final Supplier<IForgeRegistry<ExampleRegistry>> REGISTRY = EXAMPLE.makeRegistry(RegistryBuilder::new);
|kotlin=val EXAMPLE: DeferredRegister<ExampleRegistry> = DeferredRegister.create(ResourceLocation(MODID, "example_registry"), MODID)

val REGISTRY: IForgeRegistry<ExampleRegistry> by lazy {
EXAMPLE.makeRegistry(::RegistryBuilder).get()
}
|scala=final val EXAMPLE = DeferredRegister.create(new ResourceLocation(MODID, "example_registry"), MODID)

final lazy val REGISTRY = EXAMPLE.makeRegistry(() => new RegistryBuilder).get
|}}

=== Using <code>NewRegistryEvent</code> ===

The second method can be done during the <code>NewRegistryEvent</code> event. Using <code>NewRegistryEvent#create</code>, you can pass in a <code>RegistryBuilder</code> directly. This method will return a <code>Supplier<IForgeRegistry<V>></code> that can be stored and queried after the event is fired to gain access to your <code>IForgeRegistry</code> instance.

Here is an example: (the event handler is registered on the '''mod event bus''')

<syntaxhighlight lang="Java">
public static Supplier<IForgeRegistry<ExampleRegistry>> registrySupplier = null;

@SubscribeEvent
public void onNewRegistry(NewRegistryEvent event){
RegistryBuilder<ExampleRegistry> registryBuilder = new RegistryBuilder<>();
registryBuilder.setName(new ResourceLocation(MODID, "example_registry");
registrySupplier = event.create(registryBuilder);
}
</syntaxhighlight>

== Handling Missing Entries ==

When loading a pre-existing world after removing mods or updating versions, there are cases where certain registry objects will cease to exist. In these cases, it is possible to specify actions to remove a mapping, prevent the world from loading, or remap the name as needed. This can be done through the third of the registry events: <code>MissingMappingsEvent</code>. Within the event, you can grab an immutable list of missing mappings associated with a mod id for a given registry via <code>#getMappings</code> or a list of all mappings via <code>#getAllMappings</code>.

For each <code>Mapping</code>, you can either execute one of the following methods:
* <code>#ignore</code> which abandons the entry when loading
* <code>#warn</code> which warns the user about the missing entry but continues loading
* <code>#fail</code> which prevents the world from loading
* <code>#remap</code> which remaps the entry to the specified non-null object in the same registry

If none of the above are specified, then the default action of notifying the user about the missing mappings occur.

Here is an example: (the event handler is registered on the '''forge event bus''')

{{Template:Tabs/Code_Snippets
|java=// This will ignore any missing test items from the specified world
@SubscribeEvent
public void onMissing(final MissingMappingsEvent event) {
event.getMappings(ForgeRegistries.Keys.ITEMS, MODID).stream()
.filter(mapping -> mapping.key.getPath().contains("test"))
.forEach(Mapping::ignore);
}
|groovy=// This will ignore any missing test items from the specified world
@SubscribeEvent
void onMissing(final MissingMappingsEvent event) {
event.getMappings(ForgeRegistries.Keys.ITEMS, MODID).stream()
.filter(mapping -> mapping.key.path.contains("test"))
.forEach(Mapping::ignore);
}
|}}

[[Category:Common Concepts]]

Registration

2022-06-12T06:20:06Z

SizableShrimp: I don't think this page is under construction anymore

Registration is the process of making an object (such as an item or block) known to the game during runtime. If some objects are not registered, this could cause crashes even before the game is fully loaded or arbitrary behaviors such as bottlenecking mod compatibility for world generation.

Most objects that are known within the game are handled by a <code>Registry</code>. Each registry uniquely defines each object through a "registry name" via a [[Using Resources#ResourceLocation|ResourceLocation]].

{{Tip|In a global context, each object is universally unique through its <code>ResourceKey</code>: a concatenation of its registry's id and the object's registry name.}}

Due to the inconsistent ordering and registration process vanilla uses, Forge wraps most vanilla registries using <code>IForgeRegistry</code>. This guarantees that the loading order for these wrapped registries will be <code>Block</code>, <code>Item</code>, and then the rest of the wrapped registries in alphabetical order. All registries supported by Forge can be found within the <code>ForgeRegistries</code> class. Since all registry names are unique to a specific registry, different registry objects within different registries can have the same name (e.g. a <code>Block</code> and an <code>Item</code> each hold a registry object named <code>examplemod:object</code>.

{{Tip/Warning|If two registry objects within the same registry have the same name, the second object will override the first. The only registry that will throw an <code>IllegalArgumentException</code> is the <code>DataSerializerEntry</code> registry.}}

== Methods for Registering ==

There are two proper ways to register objects within an associated wrapped Forge registry: the <code>DeferredRegister</code> class, and the <code>RegisterEvent</code> lifecycle event.

=== DeferredRegister ===

<code>DeferredRegister</code> is an abstraction layer over the registry event used to register objects. It maintains a map of "registry name" to their associated suppliers and resolves those suppliers during <code>RegisterEvent</code> for the associated registry. This method is the currently recommended, and documented, way to handle these objects as it provides convenience and safety for those who want to statically initialize objects while avoiding some issues associated with it.

An example of a mod registering a custom block:

{{Template:Tabs/Code_Snippets
|java=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

public ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().getModEventBus());
}
|kotlin=private val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

val EXAMPLE_BLOCK: RegistryObject<Block> = BLOCKS.register("example_block") { Block(BlockBehaviour.Properties.of(Material.ROCK)) }

internal class ExampleMod {
init {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus)
}
}
|scala=object ExampleMod {
private final val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

final val EXAMPLE_BLOCK = registerBlock("example_block", () => new Block(BlockBehaviour.Properties.of(Material.ROCK)))
}
class ExampleMod {
BLOCKS.register(FMLJavaModLoadingContext.get.getModEventBus)
}
|groovy=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus);
}
|}}

{{Tip|When using a <code>DeferredRegister</code> to register any object, the name inputted will be automatically prefixed with the mod id passed in, giving the above object a "registry name" of <code>examplemod:example_block</code>.}}

=== RegisterEvent ===

The <code>RegisterEvent</code> is the second way register objects. This [[Events|event]] is fired for each registry synchronously in vanilla registry order after <code>FMLConstructModEvent</code> and before the configs are loaded. Objects are registered using <code>#register</code> by passing in the registry key, the name of the registry object, and the object itself. There is an additional <code>#register</code> overload which takes in a consumed helper to register an object with a given name. It is recommended to use this method to avoid unnecessary object creation.

Here is an example: (the event handler is registered on the '''mod event bus''')

{{Template:Tabs/Code_Snippets
|java=@SubscribeEvent
public void register(RegisterEvent event) {
event.register(ForgeRegistries.Keys.BLOCKS,
helper -> helper.register(new ResourceLocation(MODID, "example_block"), new Block(...))
);
}
|kotlin=@JvmStatic
@SubscribeEvent
private fun register(event: RegisterEvent) =
event.register(ForgeRegistries.Keys.BLOCKS) {
helper -> helper.register(ResourceLocation(MODID, "example_block"), Block(...))
}
|scala=@SubscribeEvent
def register(event: RegisterEvent): Unit =
event.register(ForgeRegistries.Keys.BLOCKS,
helper => helper.register(new ResourceLocation(MODID, "example_block"), new Block(...))
)
|}}

{{Tip/Important|Since all objects registered must be singleton, some classes cannot by themselves be registered. Instead, <code>*Type</code> classes are registered and used in the formers' constructors to wrap the flyweight objects. For example, a [[Basics_of_Block_Entities|<code>BlockEntity</code>]] is wrapped via <code>BlockEntityType</code>, and <code>Entity</code> is wrapped via <code>EntityType</code>. These <code>*Type</code> classes hold factories that simply create the containing type on demand.

These factory holders are created through the use of their <code>*Type$Builder</code> classes. An example: (<code>REGISTER</code> here refers to a <code>DeferredRegister<BlockEntityType<?>></code>)

{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<BlockEntityType<ExampleBlockEntity>> EXAMPLE_BLOCK_ENTITY = REGISTER.register(
"example_block_entity", () -> BlockEntityType.Builder.of(ExampleBlockEntity::new, EXAMPLE_BLOCK.get()).build(null)
);
|kotlin=val EXAMPLE_BLOCK_ENTITY: RegistryObject<BlockEntityType<ExampleBlockEntity>> = REGISTER.register("example_block_entity") { BlockEntityType.Builder.of(::ExampleBlockEntity, EXAMPLE_BLOCK.get()).build(null)) }
|scala=final val EXAMPLE_BLOCK_ENTITY = REGISTER.register("example_block_entity", () => BlockEntityType.Builder.of(() => new ExampleBlockEntity(), GeneralRegistrar.EXAMPLE_BLOCK.get).build(null))
|}}
}}

=== Non-Forge Registries ===

Not all vanilla registries are wrapped as a Forge registry. To register objects to any one of these registries, create a <code>DeferredRegister</code> via the <code>#create</code> overload which takes in a resource key of the registry and the mod id to register the entries for. Then simply call <code>#register</code> like any other <code>DeferredRegister</code>.

{{Template:Tabs/Code_Snippets
|java=private static final DeferredRegister<LootItemConditionType> REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID);

public static final RegistryObject<LootItemConditionType> EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () -> new LootItemConditionType(...));
|kotlin=private val REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID)

val EXAMPLE_LOOT_ITEM_CONDITION_TYPE : RegistryObject<LootItemConditionType> = REGISTER.register("example_loot_item_condition_type") {
LootItemConditionType(...)
}
|scala=private final val REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID)

final val EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () => new LootItemConditionType(...))
|groovy=private static final DeferredRegister<LootItemConditionType> REGISTER = DeferredRegister.create(Registry.LOOT_ITEM_REGISTRY, MODID);

public static final RegistryObject<LootItemConditionType> EXAMPLE_LOOT_ITEM_CONDITION_TYPE = REGISTER.register("example_loot_item_condition_type", () -> new LootItemConditionType(...));
|}}

If you attempt to make one of these instances require an instance of another registry object, you should use the lazy initialization method mentioned above to register the object in the correct order.

=== Data Driven Entries ===

Registries are considered to be data driven if they are located within <code>RegistryAccess</code> with the exception of <code>LevelStem</code> and <code>Level</code>.

These registry objects only need to be registered within code if they are to be used within a pre-existing registry object (e.g. a <code>PlacedFeature</code> for ore generation within an overworld <code>Biome</code>). Otherwise, their instance can be purely registered using a JSON file.

If a data driven registry object has to be registered within code, a dummy object should be supplied to hold a "registry name" and then constructed within a JSON file.

== Referencing Registered Objects ==

Each forge registered object should not be statically initialized nor reference another instance being registered. They must always be a new, singleton instance that is resolved during when <code>RegisterEvent</code> is called for their registry. This is to maintain a sane loading order for registries and their objects along with dynamic loading/unloading of mods.

Forge registered objects must always be referenced through a <code>RegistryObject</code> or a field with <code>@ObjectHolder</code>.

===Using RegistryObjects===
<code>RegistryObject</code>s can be used to retrieve references to registered objects once they become available. Their references are updated along with all <code>@ObjectHolder</code> annotations after the registry that <code>RegisterEvent</code> is called for is dispatched and frozen.

A <code>RegistryObject</code> can be retrieved as a result of using <code>DeferredRegister</code> or calling the static factory <code>RegistryObject#create</code>. Each static factory takes in the "registry name" of the object being referenced and one of the following: a <code>IForgeRegistry</code>, a registry name of the type <code>ResourceLocation</code>, or a registry key of the type <code>ResourceKey<? extends Registry<?>></code>. The <code>RegistryObject</code> can be stored within some field and retrieve the registered object using <code>#get</code>.

An example using <code>RegistryObject</code>:
{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<Item> EXAMPLE_ITEM = RegistryObject.create(new ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS);

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
public static final RegistryObject<ExampleRegistry> EXAMPLE_OBJECT = RegistryObject.create(new ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod");
|kotlin=val EXAMPLE_ITEM: RegistryObject<Item> = RegistryObject.create(ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS)

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
val EXAMPLE_OBJECT: RegistryObject<ExampleRegistry> = RegistryObject.create(ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod")
|scala=final val EXAMPLE_ITEM = RegistryObject.create(new ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS)

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
final val EXAMPLE_OBJECT = RegistryObject.create(new ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod");
|}}

{{Tip/Important|All vanilla objects are bootstrapped and registered before mods are loaded. As such, they can be referenced as is without any issues.}}

=== Using @ObjectHolder ===

Forge registry objects can also be injected into <code>public static</code> fields with either their class or that field annotated with <code>@ObjectHolder</code>. There must be enough information to construct a <code>ResourceLocation</code> to identify a single object within a specific registry.

The rules for <code>@ObjectHolder</code> are as follows:

* If the class is annotated with <code>@ObjectHolder</code>, its value will be the default namespace for all fields within if not explicitly defined
* If the class is annotated with <code>@Mod</code>, the modid will be the default namespace for all annotated fields within if not explicitly defined
* A field is considered for injection if:
** it has at least the modifiers <code>public static</code>; and
** one of the following conditions are true:
*** the '''enclosing class''' has an <code>@ObjectHolder</code> annotation, and the field is <code>final</code>, and:
**** the name value is the field's name; and
**** the namespace value is the enclosing class's namespace
**** ''An exception is thrown if the namespace value cannot be found and inherited''
*** the '''field''' is annotated with <code>@ObjectHolder</code>, and:
**** the name value is explicitly defined; and
**** the namespace value is either explicitly defined or the enclosing class's namespace
** the field type or one of its supertypes corresponds to a valid registry (e.g. <code>Item</code> or <code>ArrowItem</code> for the <code>Item</code> registry)
** ''An exception is thrown if a field does not have a corresponding registry.''
* ''An exception is thrown if the resulting <code>ResourceLocation</code> is incomplete or invalid (non-valid characters in path)''
* If no other errors or exceptions occur, the field will be injected
* If all of the above rules do not apply, no action will be taken (and a message may be logged)

<code>@ObjectHolder</code> annotated fields are injected with their associated object values after <code>RegisterEvent</code> is fired for their registry, along with <code>RegistryObject</code>s.

{{Tip/Warning|If the object does not exist in the registry when it is to be injected, a debug message will be logged, and no value will be injected. If the object is found, but the field cannot be set, a warning message will be logged instead.}}

As these rules are rather complicated, here are some examples:
<div class="mw-collapsible mw-collapsed" style="border: solid 2px; padding: 2px 5px; margin-top: 3px">
<div style="font-weight:bold;line-height:1.6;">Example uses of <code>@ObjectHolder</code></div>
<div class="mw-collapsible-content" style="overflow: auto; white-space: nowrap;">
<syntaxhighlight lang="java">
@ObjectHolder("minecraft") // Inheritable resource namespace: "minecraft"
class AnnotatedHolder {
public static final Block diamond_block = null; // No annotation. [public static final] is required.
// Block has a corresponding registry: [Block]
// Name path is the name of the field: "diamond_block"
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:diamond_block" from the [Block] registry

@ObjectHolder("ambient.cave")
public static SoundEvent ambient_sound = null; // Annotation present. [public static] is required.
// SoundEvent has a corresponding registry: [SoundEvent]
// Name path is the value of the annotation: "ambient.cave"
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:ambient.cave" from the [SoundEvent] registry

// Assume for the next entry that [ManaType] is a valid registry.
@ObjectHolder("neomagicae:coffeinum")
public static final ManaType coffeinum = null; // Annotation present. [public static] is required. [final] is optional.
// ManaType has a corresponding registry: [ManaType] (custom registry)
// Resource location is explicitly defined: "neomagicae:coffeinum"
// To inject: "neomagicae:coffeinum" from the [ManaType] registry

public static final Item ENDER_PEARL = null; // No annotation. [public static final] is required.
// Item has a corresponding registry: [Item].
// Name path is the name of the field: "ENDER_PEARL" -> "ender_pearl"
// !! ^ Field name is valid, because they are
// converted to lowercase automatically.
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:ender_pearl" from the [Item] registry

@ObjectHolder("minecraft:arrow")
public static final ArrowItem arrow = null; // Annotation present. [public static] is required. [final] is optional.
// ArrowItem does not have a corresponding registry.
// ArrowItem's supertype of Item has a corresponding registry: [Item]
// Resource location is explicitly defined: "minecraft:arrow"
// To inject: "minecraft:arrow" from the [Item] registry

public static Block bedrock = null; // No annotation, so [public static final] is required.
// Therefore, the field is ignored.

public static final CreativeModeTab group = null; // No annotation. [public static final] is required.
// CreativeModeTab does not have a corresponding registry.
// No supertypes of CreativeModeTab has a corresponding registry.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}

class UnannotatedHolder { // Note the lack of an @ObjectHolder annotation on this class.
@ObjectHolder("minecraft:flame")
public static final Enchantment flame = null; // Annotation present. [public static] is required. [final] is optional.
// Enchantment has corresponding registry: [Enchantment].
// Resource location is explicitly defined: "minecraft:flame"
// To inject: "minecraft:flame" from the [Enchantment] registry

public static final Biome ice_flat = null; // No annotation on the enclosing class.
// Therefore, the field is ignored.

@ObjectHolder("minecraft:creeper")
public static Entity creeper = null; // Annotation present. [public static] is required.
// Entity does not have a corresponding registry.
// No supertypes of Entity has a corresponding registry.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.

@ObjectHolder("levitation")
public static final Potion levitation = null; // Annotation present. [public static] is required. [final] is optional.
// Potion has a corresponding registry: [Potion].
// Name path is the value of the annotation: "levitation"
// Namespace is not explicitly defined.
// No annotation in enclosing class.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}
</syntaxhighlight>
</div>
</div>

== Creating Custom Registries ==

Creating custom registries for your mod might be useful if you want other mods to add new things to your system. For example, you might have magic spells and want to allow other mods to add new spells. For this you will want to make a registry (eg. "mymagicmod:spells"). This way, other mods will be able to register things to that list, and you won't have to do anything else.

Just like with registering a new item or block you have two ways of making a new registry. Each method takes in a <code>RegistryBuilder</code> which is used to build an <code>IForgeRegistry</code>. Each builder should have its name set via <code>#setName</code> before being created.

=== With DeferredRegister ===

The first method involves the second static constructor: <code>DeferredRegister#create(ResourceLocation, String)</code>. From there, we can construct the registry using <code>#makeRegistry</code>. This will already populate <code>#setName</code> for us. This method also returns a supplier of the registry which we can use after the <code>NewRegistryEvent</code> is called.

Here is an example:

{{Template:Tabs/Code_Snippets
|java=public static final DeferredRegister<ExampleRegistry> EXAMPLE = DeferredRegister.create(new ResourceLocation(MODID, "example_registry"), MODID);

public static final Supplier<IForgeRegistry<ExampleRegistry>> REGISTRY = EXAMPLE.makeRegistry(RegistryBuilder::new);
|kotlin=val EXAMPLE: DeferredRegister<ExampleRegistry> = DeferredRegister.create(ResourceLocation(MODID, "example_registry"), MODID)

val REGISTRY: IForgeRegistry<ExampleRegistry> by lazy {
EXAMPLE.makeRegistry(::RegistryBuilder).get()
}
|scala=final val EXAMPLE = DeferredRegister.create(new ResourceLocation(MODID, "example_registry"), MODID)

final lazy val REGISTRY = EXAMPLE.makeRegistry(() => new RegistryBuilder).get
|}}

=== Using `NewRegistryEvent` ===

The second method can be done during the <code>NewRegistryEvent</code> event. Using <code>NewRegistryEvent#create</code>, you can pass in a <code>RegistryBuilder</code> directly. This method will return a <code>Supplier<IForgeRegistry<V>></code> that can be stored and queried after the event is fired to gain access to your <code>IForgeRegistry</code> instance.

Here is an example: (the event handler is registered on the '''mod event bus''')

<syntaxhighlight lang="Java">
public static Supplier<IForgeRegistry<ExampleRegistry>> registrySupplier = null;

@SubscribeEvent
public void onNewRegistry(NewRegistryEvent event){
RegistryBuilder<ExampleRegistry> registryBuilder = new RegistryBuilder<>();
registryBuilder.setName(new ResourceLocation(MODID, "example_registry");
registrySupplier = event.create(registryBuilder);
}
</syntaxhighlight>

== Handling Missing Entries ==

When loading a pre-existing world after removing mods or updating versions, there are cases where certain registry objects will cease to exist. In these cases, it is possible to specify actions to remove a mapping, prevent the world from loading, or remap the name as needed. This can be done through the third of the registry events: <code>MissingMappingsEvent</code>. Within the event, you can grab an immutable list of missing mappings associated with a mod id for a given registry via <code>#getMappings</code> or a list of all mappings via <code>#getAllMappings</code>.

For each <code>Mapping</code>, you can either execute one of the following methods:
* <code>#ignore</code> which abandons the entry when loading
* <code>#warn</code> which warns the user about the missing entry but continues loading
* <code>#fail</code> which prevents the world from loading
* <code>#remap</code> which remaps the entry to the specified non-null object in the same registry

If none of the above are specified, then the default action of notifying the user about the missing mappings occur.

Here is an example: (the event handler is registered on the '''forge event bus''')

{{Template:Tabs/Code_Snippets
|java=// This will ignore any missing test items from the specified world
@SubscribeEvent
public void onMissing(final MissingMappingsEvent event) {
event.getMappings(ForgeRegistries.Keys.ITEMS, MODID).stream()
.filter(mapping -> mapping.key.getPath().contains("test"))
.forEach(Mapping::ignore);
}
|groovy=// This will ignore any missing test items from the specified world
@SubscribeEvent
void onMissing(final MissingMappingsEvent event) {
event.getMappings(ForgeRegistries.Keys.ITEMS, MODID).stream()
.filter(mapping -> mapping.key.path.contains("test"))
.forEach(Mapping::ignore);
}
|}}

[[Category:Common Concepts]]

Main Page/1.18

2022-06-10T08:03:34Z

SizableShrimp: Biome modifiers do not exist on 1.18

__NOTOC__
<templatestyles src=":Main_Page/styles.css" />

<div class="center title">Forge Community Wiki</div>

The Forge Community Wiki exists so that the community can:

* collectively keep track of major changes and updates to Forge and Vanilla code;
* create and edit articles with in-depth explanations about a variety of Forge-related subjects; and
* contribute example code and tutorials for both simple and difficult concepts.

This wiki is editable by any registered user with an account. This is to allow tracking of harmful edits, but isn't imposing any annoying limits. We welcome any edit, however small. Join the [https://discord.gg/Nn42eAh Discord] to discuss changes and edits to the wiki with others and the staff.

{{Supported versions}}

<div class="center round_warning">
Please read the [[FCWMeta:Wiki Policy/1.18|wiki policy]] before editing!
</div>

<div class="center" style="margin-bottom: 2em">
{{Supported versions|text=1}}
</div>

<div class="box_container center">

<div class="box">
<h3>Beginner Topics</h3>
* [[Getting Started/1.18|Getting Started]]
* [[Proper Mod Structuring/1.18|Proper Mod Structuring]]
* [[Mods.toml file/1.18|Mods.toml file]]
* [[Debug Profiler/1.18|The Debug Profiler]]
* [[Version Checker/1.18|Version Checker]]
</div>

<div class="box">
<h3>Common Concepts</h3>
* [[Sides/1.18|Understanding Sides]]
* [[Events/1.18|Understanding Events]]
* [[Registration/1.18|Registration]]
* [[Internationalization/1.18|Internationalization]]
* [[Configs/1.18|Configs]]
</div>

<div class="box">
<h3>Forge Conventions</h3>
* [[Semantic Versioning/1.18|Semantic Versioning]]
* [[Stages of Modloading/1.18|Stages of Modloading]]
</div>

<div class="box">
<h3>Resources and Data</h3>
* [[Using Resources/1.18|Introduction]]
* [[Recipes/1.18|Recipes]]
* [[Tags/1.18|Tags]]
</div>

<div class="box">
<h3>Blocks</h3>
* [[Making Blocks/1.18|Creating Blocks]]
* [[Understanding Blockstates/1.18|Understanding Blockstates]]
* [[Interacting With Blocks/1.18|Block Interactions]]
</div>

<div class="box">
<h3>Items</h3>
* [[Making Items/1.18|Making Items]]
* [[Making Tools/1.18|Making Tools]]
* [[BlockEntityWithoutLevelRenderer/1.18|<tt>BlockEntityWithoutLevelRenderer</tt>]]
</div>

<div class="box">
<h3>Data Generation</h3>
* [[Datageneration/1.18|Introduction]]
* [[Datageneration/Recipes/1.18|Recipes]]
* [[Datageneration/Tags/1.18|Tags]]
* [[Datageneration/Loot Tables/1.18|Loot Tables]]
* [[Datageneration/I18n/1.18|Localization]]
* [[Datageneration/States and Models/1.18|<tt>BlockState</tt>s and Models]]
</div>

<div class="box">
<h3>Block Entities</h3>
* [[Block Entities/1.18|Introduction]]
* [[Block Entity Renderer/1.18|<tt>BlockEntityRenderer</tt>]]
</div>

<div class="box">
<h3>Models</h3>
* [[Introduction to Models/1.18|Introduction]]
* [[Model JSONs/1.18|Model JSONs]]
* [[BlockState JSONs/1.18|BlockState JSONs]]
* [[Coloring textures dynamically/1.18|Dynamically Colored Textures]]
* [[Item Properties/1.18|Item Properties]]
</div>

<div class="box">
<h3>Handling Information</h3>
* [[Understanding Networking/1.18|Introduction]]
* [[Using NBT/1.18|Named Binary Tag (NBT)]]
* [[Using FriendlyByteBuf/1.18|Using <tt>FriendlyByteBuf</tt>]]
* [[Sending Packets/1.18|Sending and Receiving Packets]]
* [[Using SimpleChannel/1.18|Using <tt>SimpleChannel</tt>]]
* [[Networking with Entities/1.18|Networking with Entities]]
* [[DynamicOps/1.18|Using DynamicOps]]
* [[Codecs/1.18|Using Codecs]]
</div>

<div class="box">
<h3>Data Storage</h3>
* [[Capabilities/1.18|Understanding Capabilities]]
* [[Capabilities/Attaching/1.18|Attaching Capabilities]]
* [[Saved Data/1.18|Saved Data]]
</div>

<div class="box">
<h3>Game Effects</h3>
* [[Mob Effects/1.18|Mob Effects]]
* [[Potions/1.18|Potions]]
* [[Particles/1.18|Particles]]
* [[Sounds/1.18|Sounds]]
</div>

<div class="box">
<h3>Events</h3>
* [[Events/1.18|Understanding Events]]
* [[Entity Events/1.18|Entity Events]]
</div>

<div class="box">
<h3>Others</h3>
* [[Dependencies/1.18|Dependencies]]
* [[Dynamic Loot Modification/1.18|Dynamic Loot Modification]]
* [[Components/1.18|Components and Translation Keys]]
* [[Key Mappings/1.18|Key Mappings]]
* [[Access Transformers/1.18|Access Transformers]]
* [[Toolchain/1.18|Toolchain]]
* [[Game Tests/1.18|Game Tests]]
</div>

<div class="box">
<h3>Recipes</h3>
* [[Recipes/1.18|Recipes]]
* [[Custom Recipes/1.18|Custom Recipe Types]]
* [[Datageneration/Recipes/1.18|Datageneration]]
</div>

</div>

Template:Supported versions

2022-06-10T08:02:08Z

SizableShrimp: Add 1.19 to support box

{{#if:{{{text|}}}
|The current ''Latest'' version is '''1.19'''. The current ''Long Term Support (LTS)'' version is '''1.18.2'''.
|{{#vardefine: page | Main Page }}
{{Colored box
|border-color=#3498db
|title={{{title|This wiki hosts information for the following Minecraft versions:}}}
|{{{1|* [[{{#var:page}}|1.19]]
* [[{{#var:page}}/1.18|1.18]]
* [[{{#var:page}}/1.17|1.17]]
* [[{{#var:page}}/1.16|1.16]]}}}
}}}}

Template:Supported versions

2022-06-10T01:09:32Z

SizableShrimp: 1.19, still need to copy all pages

{{#if:{{{text|}}}
|The current ''Latest'' version is '''1.19'''. The current ''Long Term Support (LTS)'' version is '''1.18.2'''.
|{{#vardefine: page | Main Page }}
{{Colored box
|border-color=#3498db
|title={{{title|This wiki hosts information for the following Minecraft versions:}}}
|{{{1|* [[{{#var:page}}|1.18]]
* [[{{#var:page}}/1.17|1.17]]
* [[{{#var:page}}/1.16|1.16]]}}}
}}}}

Registration

2022-04-03T18:26:44Z

SizableShrimp: Some cleanup based on #8527 vanilla Deferred Registers

{{Under construction}}

Registration is the process of making an object (such as an item or block) known to the game during runtime. If some objects are not registered, this could cause crashes even before the game is fully loaded or arbitrary behaviors such as bottlenecking mod compatibility for world generation.

Most objects that are known within the game are handled by a <code>Registry</code>. Each registry uniquely defines each object through a "registry name" via a [[Using Resources#ResourceLocation|ResourceLocation]]. This "registry name" can be accessed with its respective getter and setter: <code>#getRegistryName</code> and <code>#setRegistryName</code>. You can only set the "registry name" of a given object once; otherwise, an exception will be thrown.

{{Tip|In a global context, each object is universally unique through its <code>ResourceKey</code>: a concatenation of its registry's id and the object's registry name.}}

Due to the inconsistent ordering and registration process vanilla uses, Forge wraps most vanilla registries using <code>IForgeRegistry</code>. This guarantees that the loading order for these wrapped registries will be <code>Block</code>, <code>Item</code>, and then the rest of the wrapped registries in alphabetical order. All registries supported by Forge can be found within the <code>ForgeRegistries</code> class. Since all registry names are unique to a specific registry, different registry objects within different registries can have the same name (e.g. a <code>Block</code> and an <code>Item</code> each hold a registry object named <code>examplemod:object</code>.

{{Tip/Warning|If two registry objects within the same registry have the same name, the second object will override the first. The only registry that will throw an <code>IllegalArgumentException</code> is the <code>DataSerializerEntry</code> registry.}}

== Methods for Registering ==

There are two proper ways to register objects within an associated wrapped Forge registry: the <code>DeferredRegister</code> class, and the <code>RegistryEvent$Register</code> lifecycle event.

For objects with '''no''' associated Forge registry, you can register the associated entry during the <code>FMLCommonSetupEvent</code> lifecycle event. In some cases, although not recommended, you may also statically initialize and register these entries.

=== DeferredRegister ===

<code>DeferredRegister</code> is an abstraction layer over the registry event used to register objects. It maintains a map of "registry name" to their associated suppliers and resolves those suppliers during the proper <code>RegistryEvent$Register</code> event. This method is the currently recommended, and documented, way to handle these objects as it provides convenience and safety for those who want to statically initialize objects while avoiding some issues associated with it.

An example of a mod registering a custom block:

{{Template:Tabs/Code_Snippets
|java=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

public ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().getModEventBus());
}
|kotlin=private val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

val EXAMPLE_BLOCK: RegistryObject<Block> = BLOCKS.register("example_block") { Block(BlockBehaviour.Properties.of(Material.ROCK)) }

internal class ExampleMod {
init {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus)
}
}
|scala=object ExampleMod {
private final val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

final val EXAMPLE_BLOCK = registerBlock("example_block", () => new Block(BlockBehaviour.Properties.of(Material.ROCK)))
}
class ExampleMod {
BLOCKS.register(FMLJavaModLoadingContext.get.getModEventBus)
}
|groovy=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus);
}
|}}

{{Tip|When using a <code>DeferredRegister</code> to register any object, the name inputted will be automatically prefixed with the mod id passed in, giving the above object a "registry name" of <code>examplemod:example_block</code>.}}

=== RegistryEvent.Register ===

The <code>RegistryEvent</code>s are another, more slightly flexible way to register objects. These [[Events|events]] are fired synchronously after <code>FMLConstructModEvent</code> and before the configs are loaded.

The event used to register objects is <code>RegistryEvent.Register<T></code>, where the type parameter <code>T</code> is the object type being registered. You can grab the associated registry using <code>#getRegistry</code> and register the objects within using either <code>#register</code> (pass in a single object) or <code>#registerAll</code> (pass in ''varargs'' or an array of objects). The latter is useful for minimizing calls to <code>#register</code>, although it provides no benefit time-complexity wise.

{{Tip/Important|The type parameter specified must be the exact class used within the Forge registry, not its superclass nor its subclass. If the class specified is not referenced as a type parameter within the associated Forge registries, then the event will not be called.}}

Here is an example: (the event handler is registered on the '''mod event bus''')

{{Template:Tabs/Code_Snippets
|java=@SubscribeEvent
public void registerBlocks(RegistryEvent.Register<Block> event) {
event.getRegistry().registerAll(new Block(...).setRegistryName(new ResourceLocation(MODID, "example_block1")), new Block(...).setRegistryName(new ResourceLocation(MODID, "example_block2")), ...);
}
|kotlin=@JvmStatic
@SubscribeEvent
private fun registerBlocks(event: RegistryEvent.Register<Block>) =
event.registry.registerAll(Block(...).setRegistryName(new ResourceLocation(MODID, "example_block1")), Block(...).setRegistryName(new ResourceLocation(MODID, "example_block2")), ...)
|scala=@SubscribeEvent
def registerBlocks(event: RegistryEvent.Register[Block]): Unit =
event.getRegistry.registerAll(new Block(...).setRegistryName(new ResourceLocation(MODID, "example_block1")), new Block(...).setRegistryName(new ResourceLocation(MODID, "example_block2")), ...)
|}}

{{Tip/Important|Since all objects registered must be singleton, some classes cannot by themselves be registered. Instead, <code>*Type</code> classes are registered and used in the formers' constructors to wrap the flyweight objects. For example, a [[Basics_of_Block_Entities|<code>BlockEntity</code>]] is wrapped via <code>BlockEntityType</code>, and <code>Entity</code> is wrapped via <code>EntityType</code>. These <code>*Type</code> classes hold factories that simply create the containing type on demand.

These factory holders are created through the use of their <code>*Type$Builder</code> classes. An example: (<code>REGISTER</code> here refers to a <code>DeferredRegister<BlockEntityType<?>></code>)

{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<BlockEntityType<ExampleBlockEntity>> EXAMPLE_BLOCK_ENTITY = REGISTER.register(
"example_block_entity", () -> BlockEntityType.Builder.of(ExampleBlockEntity::new, EXAMPLE_BLOCK.get()).build(null)
);
|kotlin=val EXAMPLE_BLOCK_ENTITY: RegistryObject<BlockEntityType<ExampleBlockEntity>> = REGISTER.register("example_block_entity") { BlockEntityType.Builder.of(::ExampleBlockEntity, EXAMPLE_BLOCK.get()).build(null)) }
|scala=final val EXAMPLE_BLOCK_ENTITY = REGISTER.register("example_block_entity", () => BlockEntityType.Builder.of(() => new ExampleBlockEntity(), GeneralRegistrar.EXAMPLE_BLOCK.get).build(null))
|}}
}}

=== Non-Forge Registries ===

Not all vanilla registries are wrapped as a Forge registry. This is because the registry is fully independent from any other registry, completely data driven, or just has not been wrapped yet.

These registries include:
* Custom Stats (a <code>ResourceLocation</code> registry)
* <code>RuleTestType</code>
* <code>PosRuleTestType</code>
* <code>RecipeType</code>
* <code>GameEvent</code>
* <code>PositionSourceType</code>
* <code>VillagerType</code>
* <code>LootPoolEntryType</code>
* <code>LootItemFunctionType</code>
* <code>LootItemConditionType</code>
* <code>LootNumberProviderType</code>
* <code>LootNbtProviderType</code>
* <code>LootScoreProviderType</code>
* <code>FloatProviderType</code>
* <code>IntProviderType</code>
* <code>HeightProviderType</code>
* <code>StructurePieceType</code>
* <code>TrunkPlacerType</code>
* <code>FeatureSizeType</code>
* A <code>Codec</code> of <code>BiomeSource</code>
* A <code>Codec</code> of <code>ChunkGenerator</code>
* <code>StructureProcessorType</code>
* <code>StructurePoolElementType</code>
* All registries within <code>BuiltinRegistries</code> excluding <code>Biome</code>

To register objects to any one of these registries, create a <code>DeferredRegister</code> via the <code>#create</code> overload which takes in a resource key of the registry and the mod id to register the entries for. Then simply call <code>#register</code> like any other <code>DeferredRegister</code>.

{{Template:Tabs/Code_Snippets
|java=private static final DeferredRegister<RecipeType<?>> RECIPE_TYPES = DeferredRegister.create(Registry.RECIPE_TYPE_REGISTRY, MODID);

public static final RegistryObject<RecipeType<ExampleRecipe>> EXAMPLE_RECIPE = RECIPE_TYPES.register("example_recipe", () -> new RecipeType<>() {});
|kotlin=private val RECIPE_TYPES = DeferredRegister.create(Registry.RECIPE_TYPE_REGISTRY, MODID)

val EXAMPLE_RECIPE: RegistryObject<RecipeType<ExampleRecipe>> = RECIPE_TYPES.register("example_recipe") {
RecipeType<>() {}
}
|scala=private final val RECIPE_TYPES = DeferredRegister.create(Registry.RECIPE_TYPE_REGISTRY, MODID)

final val EXAMPLE_RECIPE = RECIPE_TYPES.register("example_recipe", () => new RecipeType<>() {})
|groovy=private static final DeferredRegister<RecipeType<?>> RECIPE_TYPES = DeferredRegister.create(Registry.RECIPE_TYPE_REGISTRY, MODID);

public static final RegistryObject<RecipeType<ExampleRecipe>> EXAMPLE_RECIPE = RECIPE_TYPES.register("example_recipe", () -> new RecipeType<>() {});
|}}

If you attempt to make one of these instances require an instance of another registry object, you must use the lazy initialization method mentioned above to register the object in the correct order.

=== Data Driven Entries ===

Registries are considered to be data driven if they are located within <code>RegistryAccess</code> with the exception of <code>LevelStem</code> and <code>Level</code>.

The following registries are data driven:
* <code>ConfiguredSurfaceBuilder</code>
* <code>ConfiguredWorldCarver</code>
* <code>ConfiguredFeature</code>
* <code>ConfiguredStructureFeature</code>
* <code>StructureProcessorList</code>
* <code>StructureTemplatePool</code>
* <code>Biome</code>
* <code>NoiseGeneratorSettings</code>
* <code>DimensionType</code>
* <code>LevelStem</code>
* <code>Level</code>

These registry objects only need to be registered within code if they are to be used within a pre-existing registry object (e.g. a <code>ConfiguredFeature</code> for ore generation within an overworld <code>Biome</code>). Otherwise, their instance can be purely registered using a JSON file.

If a data driven registry object has to be registered within code, a dummy object should be supplied to hold a "registry name" and then constructed within a JSON file.

== Referencing Registered Objects ==

Each forge registered object should not be statically initialized nor reference another instance being registered. They must always be a new, singleton instance that is resolved during their respective <code>RegistryEvent$Register</code> event. This is to maintain a sane loading order for registries and their objects along with dynamic loading/unloading of mods.

Forge registered objects must always be referenced through a <code>RegistryObject</code> or a field with <code>@ObjectHolder</code>.

===Using RegistryObjects===
<code>RegistryObject</code>s can be used to retrieve references to registered objects once they become available. Their references are updated along with all <code>@ObjectHolder</code> annotations after the associated <code>RegistryEvent$Register</code> has been dispatched and frozen.

A <code>RegistryObject</code> can be retrieved as a result of using <code>DeferredRegister</code> or calling the static factory <code>RegistryObject#create</code>. Each static factory takes in the "registry name" of the object being referenced and one of the following: a <code>IForgeRegistry</code>, a registry name of the type <code>ResourceLocation</code>, or a registry key of the type <code>ResourceKey<? extends Registry<?>></code>. The <code>RegistryObject</code> can be stored within some field and retrieve the registered object using <code>#get</code>.

An example using <code>RegistryObject</code>:
{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<Item> EXAMPLE_ITEM = RegistryObject.create(new ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS);

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
public static final RegistryObject<ExampleRegistry> EXAMPLE_OBJECT = RegistryObject.create(new ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod");
|kotlin=val EXAMPLE_ITEM: RegistryObject<Item> = RegistryObject.create(ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS)

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
val EXAMPLE_OBJECT: RegistryObject<ExampleRegistry> = RegistryObject.create(ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod")
|scala=final val EXAMPLE_ITEM = RegistryObject.create(new ResourceLocation("examplemod", "example_item"), ForgeRegistries.ITEMS)

// Assume that 'examplemod:example_registry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
final val EXAMPLE_OBJECT = RegistryObject.create(new ResourceLocation("examplemod", "example_object"), new ResourceLocation("examplemod", "example_registry"), "examplemod");
|}}

{{Tip/Important|All vanilla objects are bootstrapped and registered before mods are loaded. As such, they can be referenced as is without any issues.}}

=== Using @ObjectHolder ===

Forge registry objects can also be injected into <code>public static</code> fields with either their class or that field annotated with <code>@ObjectHolder</code>. There must be enough information to construct a <code>ResourceLocation</code> to identify a single object within a specific registry.

The rules for <code>@ObjectHolder</code> are as follows:

* If the class is annotated with <code>@ObjectHolder</code>, its value will be the default namespace for all fields within if not explicitly defined
* If the class is annotated with <code>@Mod</code>, the modid will be the default namespace for all annotated fields within if not explicitly defined
* A field is considered for injection if:
** it has at least the modifiers <code>public static</code>; and
** one of the following conditions are true:
*** the '''enclosing class''' has an <code>@ObjectHolder</code> annotation, and the field is <code>final</code>, and:
**** the name value is the field's name; and
**** the namespace value is the enclosing class's namespace
**** ''An exception is thrown if the namespace value cannot be found and inherited''
*** the '''field''' is annotated with <code>@ObjectHolder</code>, and:
**** the name value is explicitly defined; and
**** the namespace value is either explicitly defined or the enclosing class's namespace
** the field type or one of its supertypes corresponds to a valid registry (e.g. <code>Item</code> or <code>ArrowItem</code> for the <code>Item</code> registry)
** ''An exception is thrown if a field does not have a corresponding registry.''
* ''An exception is thrown if the resulting <code>ResourceLocation</code> is incomplete or invalid (non-valid characters in path)''
* If no other errors or exceptions occur, the field will be injected
* If all of the above rules do not apply, no action will be taken (and a message may be logged)

<code>@ObjectHolder</code> annotated fields are injected with their associated object values after their corresponding registry's <code>RegistryEvent$Register</code> event is fired, along with <code>RegistryObject</code>s.

{{Tip/Warning|If the object does not exist in the registry when it is to be injected, a debug message will be logged, and no value will be injected. If the object is found, but the field cannot be set, a warning message will be logged instead.}}

As these rules are rather complicated, here are some examples:
<div class="mw-collapsible mw-collapsed" style="border: solid 2px; padding: 2px 5px; margin-top: 3px">
<div style="font-weight:bold;line-height:1.6;">Example uses of <code>@ObjectHolder</code></div>
<div class="mw-collapsible-content" style="overflow: auto; white-space: nowrap;">
<syntaxhighlight lang="java">
@ObjectHolder("minecraft") // Inheritable resource namespace: "minecraft"
class AnnotatedHolder {
public static final Block diamond_block = null; // No annotation. [public static final] is required.
// Block has a corresponding registry: [Block]
// Name path is the name of the field: "diamond_block"
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:diamond_block" from the [Block] registry

@ObjectHolder("ambient.cave")
public static SoundEvent ambient_sound = null; // Annotation present. [public static] is required.
// SoundEvent has a corresponding registry: [SoundEvent]
// Name path is the value of the annotation: "ambient.cave"
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:ambient.cave" from the [SoundEvent] registry

// Assume for the next entry that [ManaType] is a valid registry.
@ObjectHolder("neomagicae:coffeinum")
public static final ManaType coffeinum = null; // Annotation present. [public static] is required. [final] is optional.
// ManaType has a corresponding registry: [ManaType] (custom registry)
// Resource location is explicitly defined: "neomagicae:coffeinum"
// To inject: "neomagicae:coffeinum" from the [ManaType] registry

public static final Item ENDER_PEARL = null; // No annotation. [public static final] is required.
// Item has a corresponding registry: [Item].
// Name path is the name of the field: "ENDER_PEARL" -> "ender_pearl"
// !! ^ Field name is valid, because they are
// converted to lowercase automatically.
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:ender_pearl" from the [Item] registry

@ObjectHolder("minecraft:arrow")
public static final ArrowItem arrow = null; // Annotation present. [public static] is required. [final] is optional.
// ArrowItem does not have a corresponding registry.
// ArrowItem's supertype of Item has a corresponding registry: [Item]
// Resource location is explicitly defined: "minecraft:arrow"
// To inject: "minecraft:arrow" from the [Item] registry

public static Block bedrock = null; // No annotation, so [public static final] is required.
// Therefore, the field is ignored.

public static final CreativeModeTab group = null; // No annotation. [public static final] is required.
// CreativeModeTab does not have a corresponding registry.
// No supertypes of CreativeModeTab has a corresponding registry.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}

class UnannotatedHolder { // Note the lack of an @ObjectHolder annotation on this class.
@ObjectHolder("minecraft:flame")
public static final Enchantment flame = null; // Annotation present. [public static] is required. [final] is optional.
// Enchantment has corresponding registry: [Enchantment].
// Resource location is explicitly defined: "minecraft:flame"
// To inject: "minecraft:flame" from the [Enchantment] registry

public static final Biome ice_flat = null; // No annotation on the enclosing class.
// Therefore, the field is ignored.

@ObjectHolder("minecraft:creeper")
public static Entity creeper = null; // Annotation present. [public static] is required.
// Entity does not have a corresponding registry.
// No supertypes of Entity has a corresponding registry.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.

@ObjectHolder("levitation")
public static final Potion levitation = null; // Annotation present. [public static] is required. [final] is optional.
// Potion has a corresponding registry: [Potion].
// Name path is the value of the annotation: "levitation"
// Namespace is not explicitly defined.
// No annotation in enclosing class.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}
</syntaxhighlight>
</div>
</div>

== Creating Custom Registries ==

Creating custom registries for your mod might be useful if you want other mods to add new things to your system. For example, you might have magic spells and want to allow other mods to add new spells. For this you will want to make a registry (eg. "mymagicmod:spells"). This way, other mods will be able to register things to that list, and you won't have to do anything else.

Just like with registering a new item or block you have two ways of making a new registry. Each method takes in a <code>RegistryBuilder</code> which is used to build an <code>IForgeRegistry</code> for an object class that implements <code>IForgeRegistryEntry</code>. Each builder should have its name and type set via <code>#setName</code> and <code>#setType</code> respectively before being created.

For the class that implements <code>IForgeRegistryEntry</code>, it is recommended in most cases to extend the default implementation of <code>ForgeRegistryEntry</code>. For interfaces, it should extend <code>IForgeRegistryEntry</code> with its implementations extending <code>ForgeRegistryEntry</code>.

=== With DeferredRegister ===

The first method involves the second static constructor: <code>DeferredRegister#create(ResourceLocation, String)</code>. From there, we can construct the registry using <code>#makeRegistry</code>. This will already populate <code>#setName</code> and <code>#setType</code> for us. This method also returns a supplier of the registry which we can use after the <code>NewRegistryEvent</code> is called.

Here is an example:

{{Template:Tabs/Code_Snippets
|java=public static final DeferredRegister<ExampleRegistry> EXAMPLE = DeferredRegister.create(new ResourceLocation(MODID, "example_registry"), MODID);

public static final Supplier<IForgeRegistry<ExampleRegistry>> REGISTRY = EXAMPLE.makeRegistry(ExampleRegistry.class, RegistryBuilder::new);
|kotlin=val EXAMPLE: DeferredRegister<ExampleRegistry> = DeferredRegister.create(ResourceLocation(MODID, "example_registry"), MODID)

val REGISTRY: IForgeRegistry<ExampleRegistry> by lazy {
EXAMPLE.makeRegistry(ExampleRegistry::class.java, ::RegistryBuilder).get()
}
|scala=final val EXAMPLE = DeferredRegister.create(new ResourceLocation(MODID, "example_registry"), MODID)

final lazy val REGISTRY = EXAMPLE.makeRegistry(classOf[ExampleRegistry], () => new RegistryBuilder).get
|}}

=== Using `NewRegistryEvent` ===

The second method can be done during the <code>NewRegistryEvent</code> event. Using <code>NewRegistryEvent#create</code>, you can pass in a <code>RegistryBuilder</code> directly. This method will return a <code>Supplier<IForgeRegistry<V>></code> that can be stored and queried after the event is fired to gain access to your <code>IForgeRegistry</code> instance.

Here is an example: (the event handler is registered on the '''mod event bus''')

<syntaxhighlight lang="Java">
public static Supplier<IForgeRegistry<ExampleRegistry>> registrySupplier = null;

@SubscribeEvent
public void onNewRegistry(NewRegistryEvent event){
RegistryBuilder<ExampleRegistry> registryBuilder = new RegistryBuilder<>();
registryBuilder.setName(new ResourceLocation(MODID, "example_registry");
registryBuilder.setType(ExampleRegistry.class);
registrySupplier = event.create(registryBuilder);
}
</syntaxhighlight>

== Handling Missing Entries ==

When loading a pre-existing world after removing mods or updating versions, there are cases where certain registry objects will cease to exist. In these cases, it is possible to specify actions to remove a mapping, prevent the world from loading, or remap the name as needed. This can be done through the third of the registry events: <code>RegistryEvent$MissingMappings<T></code>, where the type parameter <code>T</code> is the object type being registered. Within the event, you can grab an immutable list of missing mappings associated with a mod id via <code>#getMappings</code> or a list of all mappings via <code>#getAllMappings</code>.

For each <code>Mapping</code>, you can either execute one of the following methods:
* <code>#ignore</code> which abandons the entry when loading
* <code>#warn</code> which warns the user about the missing entry but continues loading
* <code>#fail</code> which prevents the world from loading
* <code>#remap</code> which remaps the entry to the specified non-null object in the same registry

If none of the above are specified, then the default action of notifying the user about the missing mappings occur.

Here is an example: (the event handler is registered on the '''mod event bus''')

{{Template:Tabs/Code_Snippets
|java=// This will ignore any missing test items from the specified world
@SubscribeEvent
public void onMissingItems(final RegistryEvent.MissingMappings<Item> event) {
event.getMappings(MODID).stream()
.filter(mapping -> mapping.key.getPath().contains("test"))
.forEach(Mapping::ignore);
}
|groovy=// This will ignore any missing test items from the specified world
@SubscribeEvent
void onMissingItems(final RegistryEvent.MissingMappings<Item> event) {
event.getMappings(MODID).stream()
.filter(mapping -> mapping.key.path.contains("test"))
.forEach(Mapping::ignore);
}
|}}

[[Category:Common Concepts]]

ISTER

2022-02-02T02:19:18Z

SizableShrimp: Redirect to ItemStack_TileEntityRenderer/1.16

#REDIRECT [[ItemStack_TileEntityRenderer/1.16]]

BEWLR

2022-02-02T02:17:44Z

SizableShrimp: Redirect to BlockEntityWithoutLevelRenderer

#REDIRECT [[BlockEntityWithoutLevelRenderer]]

Saved Data/1.16

2022-01-30T01:30:54Z

SizableShrimp: Redirect to World Saved Data/1.16

#REDIRECT [[World Saved Data/1.16]]

Components/1.16

2022-01-19T21:04:46Z

SizableShrimp: Redirect to Text Components/1.16

#REDIRECT [[Text Components/1.16]]

Capabilities

2022-01-12T15:41:07Z

SizableShrimp: /* Forge-provided Capabilities and Providers */ Remove ref to IAnimationStateMachine

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Working with Capabilities ==

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

=== Obtaining a Capability ===

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

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

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

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

This is, for obvious reasons, redundant, since that capability is also available through
<code>CapabilityItemHandler</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>BlockEntity</code>, then we may also say that the inventory is only accessible from the top and the bottom of the
block.

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

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

=== Attaching a Capability ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Accessing a Capability ===

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

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

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

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

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

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

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

if (targetCapability == null) {
ICapabilityProvider provider = level.getBlockEntity(pos.relative(direction));
targetCapability = provider.getCapability(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>BlockEntity</code> the neighboring capability provider
for an <code>IEnergyStorage</code> capability. Before obtaining the provider, the code performs a cache lookup for the
targeted capability. If the check succeeds, then no lookup is performed; if the check fails, the targeted Capability
Provider is obtained and queried for the Capability. The obtained <code>LazyOptional</code> is then cached and a
listener is attached to it so that the cache would be emptied on invalidation. The code then continues with the
interaction with the capability, which is outside the scope of this article.

== Creating Custom Capabilities ==

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

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

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

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

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

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

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

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

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

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

public class MyCapabilityImplementation implements MyCapability {
private String value;

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

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

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

=== The Capability Provider ===

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

=== Tying it All Together ===

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

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

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

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

=== Class Diagram ===

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

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

== Custom Capability Providers ==

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

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

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

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

== Code Examples ==

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

[[Category:Data Storage]]

Template:Supported versions

2022-01-08T19:21:45Z

SizableShrimp: Update Latest version to 1.18.1

{{#if:{{{text|}}}
|The current ''Latest'' version is '''1.18.1'''. The current ''Long Term Support (LTS)'' version is '''1.16.5'''.
|{{#vardefine: page | Main Page }}
{{Colored box
|border-color=#3498db
|title={{{title|This wiki hosts information for the following Minecraft versions:}}}
|{{{1|* [[{{#var:page}}|1.18]]
* [[{{#var:page}}/1.17|1.17]]
* [[{{#var:page}}/1.16|1.16]]}}}
}}}}

Config

2022-01-08T19:20:56Z

SizableShrimp: Redirect to Configs

#REDIRECT [[Configs]]

Template:Supported versions

2021-12-07T14:48:13Z

SizableShrimp: Use Main Page for now

{{#if:{{{text|}}}
|The current ''Latest'' version is '''1.18'''. The current ''Long Term Support (LTS)'' version is '''1.16.5'''.
|{{#vardefine: page | Main Page }}
{{Colored box
|border-color=#3498db
|title={{{title|This wiki hosts information for the following Minecraft versions:}}}
|{{{1|* [[{{#var:page}}|1.18]]
* [[{{#var:page}}/1.17|1.17]]
* [[{{#var:page}}/1.16|1.16]]}}}
}}}}

Template:Supported versions

2021-12-07T14:09:06Z

SizableShrimp: Try {{BASEPAGENAME}}

{{#if:{{{text|}}}|The current ''Latest'' version is '''1.18'''. The current ''Long Term Support (LTS)'' version is '''1.16.5'''.|{{Colored box
|border-color=#3498db
|title={{{title|This wiki hosts information for the following Minecraft versions:}}}
|{{{1|* [[{{{page|{{NAMESPACE}}:{{BASEPAGENAME}}}}}|1.18]]
* [[{{{page|{{NAMESPACE}}:{{BASEPAGENAME}}}}}/1.17|1.17]]
* [[{{{page|{{NAMESPACE}}:{{BASEPAGENAME}}}}}/1.16|1.16]]}}}
}}}}

Template:Supported versions

2021-12-07T14:01:16Z

SizableShrimp: Allow specifying linked page

{{#if:{{{text|}}}|The current ''Latest'' version is '''1.18'''. The current ''Long Term Support (LTS)'' version is '''1.16.5'''.|{{Colored box
|border-color=#3498db
|title={{{title|This wiki hosts information for the following Minecraft versions:}}}
|{{{1|* [[{{{page|{{NAMESPACE}}:{{ROOTPAGENAME}}}}}|1.18]]
* [[{{{page|{{NAMESPACE}}:{{ROOTPAGENAME}}}}}/1.17|1.17]]
* [[{{{page|{{NAMESPACE}}:{{ROOTPAGENAME}}}}}/1.16|1.16]]}}}
}}}}

Main Page/1.16

2021-12-07T13:59:15Z

SizableShrimp: Use Template:Supported versions with text=1

__NOTOC__
<templatestyles src=":Main_Page/styles.css" />

<div class="center title">Forge Community Wiki</div>

The Forge Community Wiki exists so that the community can:

* collectively keep track of major changes and updates to Forge and Vanilla code;
* create and edit articles with in-depth explanations about a variety of Forge-related subjects; and
* contribute example code and tutorials for both simple and difficult concepts.

This wiki is editable by any registered user with an account. This is to allow tracking of harmful edits, but isn't imposing any annoying limits. We welcome any edit, however small. Join the [https://discord.gg/Nn42eAh Discord] to discuss changes and edits to the wiki with others and the staff.

{{Supported versions}}

<div class="center round_warning">
Please read the [[FCWMeta:Wiki Policy|wiki policy]] before editing!
</div>

<div class="center" style="margin-bottom: 2em">
{{Supported versions|text=1}}
</div>

<div class="box_container center">

<div class="box">
<h3>Beginner Topics</h3>
* [[Getting Started/1.16|Getting Started]]
* [[Proper Mod Structuring/1.16|Proper Mod Structuring]]
* [[Debug Profiler/1.16|The Debug Profiler]]
* [[Version Checker/1.16|Version Checker]]
</div>

<div class="box">
<h3>Common Concepts</h3>
* [[Sides/1.16|Understanding Sides]]
* [[Events/1.16|Understanding Events]]
* [[Registration/1.16|Registration]]
* [[Internationalization/1.16|Internationalization]]
</div>

<div class="box">
<h3>Forge Conventions</h3>
* [[Semantic Versioning/1.16|Semantic Versioning]]
* [[Stages of Modloading/1.16|Stages of Modloading]]
</div>

<div class="box">
<h3>Resources and Data</h3>
* [[Using Resources/1.16|Introduction]]
* [[Recipes/1.16|Recipes]]
* [[Tags/1.16|Tags]]
</div>

<div class="box">
<h3>Blocks</h3>
* [[Making Blocks/1.16|Creating Blocks]]
* [[Understanding Blockstates/1.16|Understanding Blockstates]]
* [[Interacting With Blocks/1.16|Block Interactions]]
</div>

<div class="box">
<h3>Items</h3>
* [[Making Items/1.16|Making Items]]
* [[Making Tools/1.16|Making Tools]]
* [[ItemStack TileEntityRenderer/1.16|<tt>ItemStackTileEntityRenderer</tt>]]
</div>

<div class="box">
<h3>Data Generation</h3>
* [[Datageneration/1.16|Introduction]]
* [[Datageneration/Recipes/1.16|Recipes]]
* [[Datageneration/Tags/1.16|Tags]]
* [[Datageneration/Loot Tables/1.16|Loot Tables]]
* [[Datageneration/I18n/1.16|Localization]]
* [[Datageneration/States and Models/1.16|<tt>BlockState</tt>s and Models]]
</div>

<div class="box">
<h3>Tile Entities</h3>
* [[Basics of Tile Entities/1.16|Introduction]]
* [[Using Tile Entity Renderers/1.16|Using Tile Entity Renderers]]
</div>

<div class="box">
<h3>Models</h3>
* [[Introduction to Models/1.16|Introduction]]
* [[Model JSONs/1.16|Model JSONs]]
* [[BlockState JSONs/1.16|BlockState JSONs]]
* [[Coloring textures dynamically/1.16|Dynamically Colored Textures]]
* [[Item Overrides/1.16|Item Overrides]]
</div>

<div class="box">
<h3>Handling Information</h3>
* [[Understanding Networking/1.16|Introduction]]
* [[Using NBT/1.16|Named Binary Tag (NBT)]]
* [[Using PacketBuffer/1.16|Using <tt>PacketBuffer</tt>]]
* [[Sending Packets/1.16|Sending and Receiving Packets]]
* [[Using SimpleChannel/1.16|Using <tt>SimpleChannel</tt>]]
* [[Networking with Entities/1.16|Networking with Entities]]
* [[DynamicOps/1.16|Using DynamicOps]]
* [[Codecs/1.16|Using Codecs]]
</div>

<div class="box">
<h3>Data Storage</h3>
* [[Capabilities/1.16|Understanding Capabilities]]
* [[Capabilities/Attaching/1.16|Attaching Capabilities]]
* [[World Saved Data/1.16|World Saved Data]]
</div>

<div class="box">
<h3>Game Effects</h3>
* [[Effects/1.16|Effects]]
* [[Potions/1.16|Potions]]
* [[Particles/1.16|Particles]]
* [[Sounds/1.16|Sounds]]
</div>

<div class="box">
<h3>Events</h3>
* [[Events/1.16|Understanding Events]]
* [[Entity Events/1.16|Entity Events]]
</div>

<div class="box">
<h3>Others</h3>
* [[Dependencies/1.16|Dependencies]]
* [[Dynamic Loot Modification/1.16|Dynamic Loot Modification]]
* [[Text Components/1.16|Text Components and Translation Keys]]
* [[Key Bindings/1.16|Key Bindings]]
* [[Access Transformers/1.16|Access Transformers]]
* [[Toolchain/1.16|Toolchain]]
</div>

<div class="box">
<h3>Recipes</h3>
* [[Recipes/1.16|Recipes]]
* [[Custom Recipes/1.16|Custom Recipe Types]]
* [[Datageneration/Recipes/1.16|Datageneration]]
</div>

</div>

Main Page/1.17

2021-12-07T13:58:29Z

SizableShrimp: Use Template:Supported versions with text=1

__NOTOC__
<templatestyles src=":Main_Page/styles.css" />

<div class="center title">Forge Community Wiki</div>

The Forge Community Wiki exists so that the community can:

* collectively keep track of major changes and updates to Forge and Vanilla code;
* create and edit articles with in-depth explanations about a variety of Forge-related subjects; and
* contribute example code and tutorials for both simple and difficult concepts.

This wiki is editable by any registered user with an account. This is to allow tracking of harmful edits, but isn't imposing any annoying limits. We welcome any edit, however small. Join the [https://discord.gg/Nn42eAh Discord] to discuss changes and edits to the wiki with others and the staff.

{{Supported versions}}

<div class="center round_warning">
Please read the [[FCWMeta:Wiki Policy|wiki policy]] before editing!
</div>

<div class="center" style="margin-bottom: 2em">
{{Supported versions|text=1}}
</div>

<div class="box_container center">

<div class="box">
<h3>Beginner Topics</h3>
* [[Getting Started/1.17|Getting Started]]
* [[Proper Mod Structuring/1.17|Proper Mod Structuring]]
* [[Mods.toml file/1.17|Mods.toml file]]
* [[Debug Profiler/1.17|The Debug Profiler]]
* [[Version Checker/1.17|Version Checker]]
</div>

<div class="box">
<h3>Common Concepts</h3>
* [[Sides/1.17|Understanding Sides]]
* [[Events/1.17|Understanding Events]]
* [[Registration/1.17|Registration]]
* [[Internationalization/1.17|Internationalization]]
* [[Configs/1.17|Configs]]
</div>

<div class="box">
<h3>Forge Conventions</h3>
* [[Semantic Versioning/1.17|Semantic Versioning]]
* [[Stages of Modloading/1.17|Stages of Modloading]]
</div>

<div class="box">
<h3>Resources and Data</h3>
* [[Using Resources/1.17|Introduction]]
* [[Recipes/1.17|Recipes]]
* [[Tags/1.17|Tags]]
</div>

<div class="box">
<h3>Blocks</h3>
* [[Making Blocks/1.17|Creating Blocks]]
* [[Understanding Blockstates/1.17|Understanding Blockstates]]
* [[Interacting With Blocks/1.17|Block Interactions]]
</div>

<div class="box">
<h3>Items</h3>
* [[Making Items/1.17|Making Items]]
* [[Making Tools/1.17|Making Tools]]
* [[BlockEntityWithoutLevelRenderer/1.17|<tt>BlockEntityWithoutLevelRenderer</tt>]]
</div>

<div class="box">
<h3>Data Generation</h3>
* [[Datageneration/1.17|Introduction]]
* [[Datageneration/Recipes/1.17|Recipes]]
* [[Datageneration/Tags/1.17|Tags]]
* [[Datageneration/Loot Tables/1.17|Loot Tables]]
* [[Datageneration/I18n/1.17|Localization]]
* [[Datageneration/States and Models/1.17|<tt>BlockState</tt>s and Models]]
</div>

<div class="box">
<h3>Block Entities</h3>
* [[Block Entities/1.17|Introduction]]
* [[Block Entity Renderer/1.17|<tt>BlockEntityRenderer</tt>]]
</div>

<div class="box">
<h3>Models</h3>
* [[Introduction to Models/1.17|Introduction]]
* [[Model JSONs/1.17|Model JSONs]]
* [[BlockState JSONs/1.17|BlockState JSONs]]
* [[Coloring textures dynamically/1.17|Dynamically Colored Textures]]
* [[Item Properties/1.17|Item Properties]]
</div>

<div class="box">
<h3>Handling Information</h3>
* [[Understanding Networking/1.17|Introduction]]
* [[Using NBT/1.17|Named Binary Tag (NBT)]]
* [[Using FriendlyByteBuf/1.17|Using <tt>FriendlyByteBuf</tt>]]
* [[Sending Packets/1.17|Sending and Receiving Packets]]
* [[Using SimpleChannel/1.17|Using <tt>SimpleChannel</tt>]]
* [[Networking with Entities/1.17|Networking with Entities]]
* [[DynamicOps/1.17|Using DynamicOps]]
* [[Codecs/1.17|Using Codecs]]
</div>

<div class="box">
<h3>Data Storage</h3>
* [[Capabilities/1.17|Understanding Capabilities]]
* [[Capabilities/Attaching/1.17|Attaching Capabilities]]
* [[Saved Data/1.17|Saved Data]]
</div>

<div class="box">
<h3>Game Effects</h3>
* [[Mob Effects/1.17|Mob Effects]]
* [[Potions/1.17|Potions]]
* [[Particles/1.17|Particles]]
* [[Sounds/1.17|Sounds]]
</div>

<div class="box">
<h3>Events</h3>
* [[Events/1.17|Understanding Events]]
* [[Entity Events/1.17|Entity Events]]
</div>

<div class="box">
<h3>Others</h3>
* [[Dependencies/1.17|Dependencies]]
* [[Dynamic Loot Modification/1.17|Dynamic Loot Modification]]
* [[Components/1.17|Components and Translation Keys]]
* [[Key Mappings/1.17|Key Mappings]]
* [[Access Transformers/1.17|Access Transformers]]
* [[Toolchain/1.17|Toolchain]]
</div>

<div class="box">
<h3>Recipes</h3>
* [[Recipes/1.17|Recipes]]
* [[Custom Recipes/1.17|Custom Recipe Types]]
* [[Datageneration/Recipes/1.17|Datageneration]]
</div>

</div>

Main Page

2021-12-07T13:57:51Z

SizableShrimp: Use Template:Supported versions with text=1

__NOTOC__
<templatestyles src=":Main_Page/styles.css" />

<div class="center title">Forge Community Wiki</div>

The Forge Community Wiki exists so that the community can:

* collectively keep track of major changes and updates to Forge and Vanilla code;
* create and edit articles with in-depth explanations about a variety of Forge-related subjects; and
* contribute example code and tutorials for both simple and difficult concepts.

This wiki is editable by any registered user with an account. This is to allow tracking of harmful edits, but isn't imposing any annoying limits. We welcome any edit, however small. Join the [https://discord.gg/Nn42eAh Discord] to discuss changes and edits to the wiki with others and the staff.

{{Supported versions}}

<div class="center round_warning">
Please read the [[FCWMeta:Wiki Policy|wiki policy]] before editing!
</div>

<div class="center" style="margin-bottom: 2em">
{{Supported versions|text=1}}
</div>

<div class="box_container center">

<div class="box">
<h3>Beginner Topics</h3>
* [[Getting Started]]
* [[Proper Mod Structuring]]
* [[Mods.toml file]]
* [[Debug Profiler|The Debug Profiler]]
* [[Version Checker]]
</div>

<div class="box">
<h3>Common Concepts</h3>
* [[Sides|Understanding Sides]]
* [[Events|Understanding Events]]
* [[Registration]]
* [[Internationalization]]
* [[Configs]]
</div>

<div class="box">
<h3>Forge Conventions</h3>
* [[Semantic Versioning]]
* [[Stages of Modloading]]
</div>

<div class="box">
<h3>Resources and Data</h3>
* [[Using Resources|Introduction]]
* [[Recipes]]
* [[Tags]]
</div>

<div class="box">
<h3>Blocks</h3>
* [[Making Blocks|Creating Blocks]]
* [[Understanding Blockstates]]
* [[Interacting With Blocks|Block Interactions]]
</div>

<div class="box">
<h3>Items</h3>
* [[Making Items]]
* [[Making Tools]]
* [[BlockEntityWithoutLevelRenderer|<tt>BlockEntityWithoutLevelRenderer</tt>]]
</div>

<div class="box">
<h3>Data Generation</h3>
* [[Datageneration|Introduction]]
* [[Datageneration/Recipes|Recipes]]
* [[Datageneration/Tags|Tags]]
* [[Datageneration/Loot_Tables|Loot Tables]]
* [[Datageneration/I18n|Localization]]
* [[Datageneration/States and Models|<tt>BlockState</tt>s and Models]]
</div>

<div class="box">
<h3>Block Entities</h3>
* [[Block Entities|Introduction]]
* [[Block Entity Renderer|<tt>BlockEntityRenderer</tt>]]
</div>

<div class="box">
<h3>Models</h3>
* [[Introduction to Models|Introduction]]
* [[Model JSONs]]
* [[BlockState JSONs]]
* [[Coloring textures dynamically|Dynamically Colored Textures]]
* [[Item Properties]]
</div>

<div class="box">
<h3>Handling Information</h3>
* [[Understanding Networking|Introduction]]
* [[Using NBT|Named Binary Tag (NBT)]]
* [[Using FriendlyByteBuf|Using <tt>FriendlyByteBuf</tt>]]
* [[Sending Packets|Sending and Receiving Packets]]
* [[Using SimpleChannel|Using <tt>SimpleChannel</tt>]]
* [[Networking with Entities]]
* [[DynamicOps|Using DynamicOps]]
* [[Codecs|Using Codecs]]
</div>

<div class="box">
<h3>Data Storage</h3>
* [[Capabilities|Understanding Capabilities]]
* [[Capabilities/Attaching|Attaching Capabilities]]
* [[Saved Data]]
</div>

<div class="box">
<h3>Game Effects</h3>
* [[Mob Effects]]
* [[Potions]]
* [[Particles]]
* [[Sounds]]
</div>

<div class="box">
<h3>Events</h3>
* [[Events|Understanding Events]]
* [[Entity Events]]
</div>

<div class="box">
<h3>Others</h3>
* [[Dependencies]]
* [[Dynamic Loot Modification]]
* [[Components|Components and Translation Keys]]
* [[Key Mappings]]
* [[Access Transformers]]
* [[Toolchain]]
</div>

<div class="box">
<h3>Recipes</h3>
* [[Recipes]]
* [[Custom Recipes|Custom Recipe Types]]
* [[Datageneration/Recipes|Datageneration]]
</div>

</div>

Template:Supported versions

2021-12-07T13:57:07Z

SizableShrimp: Add text=1 to show different info

{{#if:{{{text|}}}|The current ''Latest'' version is '''1.18'''. The current ''Long Term Support (LTS)'' version is '''1.16.5'''.|{{Colored box
|border-color=#3498db
|title={{{title|This wiki hosts information for the following Minecraft versions:}}}
|{{{1|* [[Main Page|1.18]]
* [[Main Page/1.17|1.17]]
* [[Main Page/1.16|1.16]]}}}
}}}}

Template:Supported versions

2021-12-06T05:54:24Z

SizableShrimp: Update info for Forge 1.18

{{Colored box
|border-color=#3498db
|title={{{title|This wiki hosts information for the following Minecraft versions:}}}
|{{{1|* [[Main Page|1.18]]
* [[Main Page/1.17|1.17]]
* [[Main Page/1.16|1.16]]}}}
}}

Main Page

2021-12-06T05:53:38Z

SizableShrimp: Update info for Forge 1.18

__NOTOC__
<templatestyles src=":Main_Page/styles.css" />

<div class="center title">Forge Community Wiki</div>

The Forge Community Wiki exists so that the community can:

* collectively keep track of major changes and updates to Forge and Vanilla code;
* create and edit articles with in-depth explanations about a variety of Forge-related subjects; and
* contribute example code and tutorials for both simple and difficult concepts.

This wiki is editable by any registered user with an account. This is to allow tracking of harmful edits, but isn't imposing any annoying limits. We welcome any edit, however small. Join the [https://discord.gg/Nn42eAh Discord] to discuss changes and edits to the wiki with others and the staff.

{{Supported versions}}

<div class="center round_warning">
Please read the [[FCWMeta:Wiki Policy|wiki policy]] before editing!
</div>

<div class="center" style="margin-bottom: 2em">
The current ''Latest'' version is '''1.18'''. The current ''Long Term Support (LTS)'' version is '''1.16.5'''.
</div>

<div class="box_container center">

<div class="box">
<h3>Beginner Topics</h3>
* [[Getting Started]]
* [[Proper Mod Structuring]]
* [[Mods.toml file]]
* [[Debug Profiler|The Debug Profiler]]
* [[Version Checker]]
</div>

<div class="box">
<h3>Common Concepts</h3>
* [[Sides|Understanding Sides]]
* [[Events|Understanding Events]]
* [[Registration]]
* [[Internationalization]]
* [[Configs]]
</div>

<div class="box">
<h3>Forge Conventions</h3>
* [[Semantic Versioning]]
* [[Stages of Modloading]]
</div>

<div class="box">
<h3>Resources and Data</h3>
* [[Using Resources|Introduction]]
* [[Recipes]]
* [[Tags]]
</div>

<div class="box">
<h3>Blocks</h3>
* [[Making Blocks|Creating Blocks]]
* [[Understanding Blockstates]]
* [[Interacting With Blocks|Block Interactions]]
</div>

<div class="box">
<h3>Items</h3>
* [[Making Items]]
* [[Making Tools]]
* [[BlockEntityWithoutLevelRenderer|<tt>BlockEntityWithoutLevelRenderer</tt>]]
</div>

<div class="box">
<h3>Data Generation</h3>
* [[Datageneration|Introduction]]
* [[Datageneration/Recipes|Recipes]]
* [[Datageneration/Tags|Tags]]
* [[Datageneration/Loot_Tables|Loot Tables]]
* [[Datageneration/I18n|Localization]]
* [[Datageneration/States and Models|<tt>BlockState</tt>s and Models]]
</div>

<div class="box">
<h3>Block Entities</h3>
* [[Block Entities|Introduction]]
* [[Block Entity Renderer|<tt>BlockEntityRenderer</tt>]]
</div>

<div class="box">
<h3>Models</h3>
* [[Introduction to Models|Introduction]]
* [[Model JSONs]]
* [[BlockState JSONs]]
* [[Coloring textures dynamically|Dynamically Colored Textures]]
* [[Item Properties]]
</div>

<div class="box">
<h3>Handling Information</h3>
* [[Understanding Networking|Introduction]]
* [[Using NBT|Named Binary Tag (NBT)]]
* [[Using FriendlyByteBuf|Using <tt>FriendlyByteBuf</tt>]]
* [[Sending Packets|Sending and Receiving Packets]]
* [[Using SimpleChannel|Using <tt>SimpleChannel</tt>]]
* [[Networking with Entities]]
* [[DynamicOps|Using DynamicOps]]
* [[Codecs|Using Codecs]]
</div>

<div class="box">
<h3>Data Storage</h3>
* [[Capabilities|Understanding Capabilities]]
* [[Capabilities/Attaching|Attaching Capabilities]]
* [[Saved Data]]
</div>

<div class="box">
<h3>Game Effects</h3>
* [[Mob Effects]]
* [[Potions]]
* [[Particles]]
* [[Sounds]]
</div>

<div class="box">
<h3>Events</h3>
* [[Events|Understanding Events]]
* [[Entity Events]]
</div>

<div class="box">
<h3>Others</h3>
* [[Dependencies]]
* [[Dynamic Loot Modification]]
* [[Components|Components and Translation Keys]]
* [[Key Mappings]]
* [[Access Transformers]]
* [[Toolchain]]
</div>

<div class="box">
<h3>Recipes</h3>
* [[Recipes]]
* [[Custom Recipes|Custom Recipe Types]]
* [[Datageneration/Recipes|Datageneration]]
</div>

</div>

Codec

2021-11-27T05:36:25Z

SizableShrimp: Redirect to Codecs

#REDIRECT [[Codecs]]

Main Page/1.16

2021-07-28T02:11:16Z

SizableShrimp: Update info for Forge 1.17.1

__NOTOC__
<templatestyles src=":Main_Page/styles.css" />

<div class="center title">Forge Community Wiki</div>

The Forge Community Wiki exists so that the community can:

* collectively keep track of major changes and updates to Forge and Vanilla code;
* create and edit articles with in-depth explanations about a variety of Forge-related subjects; and
* contribute example code and tutorials for both simple and difficult concepts.

This wiki is editable by any registered user with an account. This is to allow tracking of harmful edits, but isn't imposing any annoying limits. We welcome any edit, however small. Join the [https://discord.gg/Nn42eAh Discord] to discuss changes and edits to the wiki with others and the staff.

{{Supported versions}}

<div class="center round_warning">
Please read the [[FCWMeta:Wiki Policy|wiki policy]] before editing!
</div>

<div class="center" style="margin-bottom: 2em">
The current ''Latest'' version is '''1.17.1'''. The current ''Long Term Support (LTS)'' version is '''1.16.5'''. '''1.15.2''' is currently in ''grace/LTS''.
</div>

<div class="box_container center">

<div class="box">
<h3>Beginner Topics</h3>
* [[Getting Started/1.16|Getting Started]]
* [[Proper Mod Structuring/1.16|Proper Mod Structuring]]
* [[Debug Profiler/1.16|The Debug Profiler]]
* [[Version Checker/1.16|Version Checker]]
</div>

<div class="box">
<h3>Common Concepts</h3>
* [[Sides/1.16|Understanding Sides]]
* [[Events/1.16|Understanding Events]]
* [[Registration/1.16|Registration]]
* [[Internationalization/1.16|Internationalization]]
</div>

<div class="box">
<h3>Forge Conventions</h3>
* [[Semantic Versioning/1.16|Semantic Versioning]]
* [[Stages of Modloading/1.16|Stages of Modloading]]
</div>

<div class="box">
<h3>Resources and Data</h3>
* [[Using Resources/1.16|Introduction]]
* [[Recipes/1.16|Recipes]]
* [[Tags/1.16|Tags]]
</div>

<div class="box">
<h3>Blocks</h3>
* [[Making Blocks/1.16|Creating Blocks]]
* [[Understanding Blockstates/1.16|Understanding Blockstates]]
* [[Interacting With Blocks/1.16|Block Interactions]]
</div>

<div class="box">
<h3>Items</h3>
* [[Making Items/1.16|Making Items]]
* [[Making Tools/1.16|Making Tools]]
* [[ItemStack TileEntityRenderer/1.16|<tt>ItemStackTileEntityRenderer</tt>]]
</div>

<div class="box">
<h3>Data Generation</h3>
* [[Datageneration/1.16|Introduction]]
* [[Datageneration/Recipes/1.16|Recipes]]
* [[Datageneration/Tags/1.16|Tags]]
* [[Datageneration/Loot Tables/1.16|Loot Tables]]
* [[Datageneration/I18n/1.16|Localization]]
* [[Datageneration/States and Models/1.16|<tt>BlockState</tt>s and Models]]
</div>

<div class="box">
<h3>Tile Entities</h3>
* [[Basics of Tile Entities/1.16|Introduction]]
* [[Using Tile Entity Renderers/1.16|Using Tile Entity Renderers]]
</div>

<div class="box">
<h3>Models</h3>
* [[Introduction to Models/1.16|Introduction]]
* [[Model JSONs/1.16|Model JSONs]]
* [[BlockState JSONs/1.16|BlockState JSONs]]
* [[Coloring textures dynamically/1.16|Dynamically Colored Textures]]
* [[Item Overrides/1.16|Item Overrides]]
</div>

<div class="box">
<h3>Handling Information</h3>
* [[Understanding Networking/1.16|Introduction]]
* [[Using NBT/1.16|Named Binary Tag (NBT)]]
* [[Using PacketBuffer/1.16|Using <tt>PacketBuffer</tt>]]
* [[Sending Packets/1.16|Sending and Receiving Packets]]
* [[Using SimpleChannel/1.16|Using <tt>SimpleChannel</tt>]]
* [[Networking with Entities/1.16|Networking with Entities]]
* [[DynamicOps/1.16|Using DynamicOps]]
* [[Codecs/1.16|Using Codecs]]
</div>

<div class="box">
<h3>Data Storage</h3>
* [[Capabilities/1.16|Understanding Capabilities]]
* [[Capabilities/Attaching/1.16|Attaching Capabilities]]
* [[World Saved Data/1.16|World Saved Data]]
</div>

<div class="box">
<h3>Game Effects</h3>
* [[Effects/1.16|Effects]]
* [[Potions/1.16|Potions]]
* [[Particles/1.16|Particles]]
* [[Sounds/1.16|Sounds]]
</div>

<div class="box">
<h3>Events</h3>
* [[Events/1.16|Understanding Events]]
* [[Entity Events/1.16|Entity Events]]
</div>

<div class="box">
<h3>Others</h3>
* [[Dependencies/1.16|Dependencies]]
* [[Dynamic Loot Modification/1.16|Dynamic Loot Modification]]
* [[Text Components/1.16|Text Components and Translation Keys]]
* [[Key Bindings/1.16|Key Bindings]]
* [[Access Transformers/1.16|Access Transformers]]
* [[Toolchain/1.16|Toolchain]]
</div>

<div class="box">
<h3>Recipes</h3>
* [[Recipes/1.16|Recipes]]
* [[Custom Recipes/1.16|Custom Recipe Types]]
* [[Datageneration/Recipes/1.16|Datageneration]]
</div>

</div>

Main Page

2021-07-28T02:10:14Z

SizableShrimp: Update info for Forge 1.17.1

__NOTOC__
<templatestyles src=":Main_Page/styles.css" />

<div class="center title">Forge Community Wiki</div>

The Forge Community Wiki exists so that the community can:

* collectively keep track of major changes and updates to Forge and Vanilla code;
* create and edit articles with in-depth explanations about a variety of Forge-related subjects; and
* contribute example code and tutorials for both simple and difficult concepts.

This wiki is editable by any registered user with an account. This is to allow tracking of harmful edits, but isn't imposing any annoying limits. We welcome any edit, however small. Join the [https://discord.gg/Nn42eAh Discord] to discuss changes and edits to the wiki with others and the staff.

{{Supported versions}}

<div class="center round_warning">
Please read the [[FCWMeta:Wiki Policy|wiki policy]] before editing!
</div>

<div class="center" style="margin-bottom: 2em">
The current ''Latest'' version is '''1.17.1'''. The current ''Long Term Support (LTS)'' version is '''1.16.5'''. '''1.15.2''' is currently in ''grace/LTS''.
</div>

<div class="box_container center">

<div class="box">
<h3>Beginner Topics</h3>
* [[Getting Started]]
* [[Proper Mod Structuring]]
* [[Debug Profiler|The Debug Profiler]]
* [[Version Checker]]
</div>

<div class="box">
<h3>Common Concepts</h3>
* [[Sides|Understanding Sides]]
* [[Events|Understanding Events]]
* [[Registration]]
* [[Internationalization]]
</div>

<div class="box">
<h3>Forge Conventions</h3>
* [[Semantic Versioning]]
* [[Stages of Modloading]]
</div>

<div class="box">
<h3>Resources and Data</h3>
* [[Using Resources|Introduction]]
* [[Recipes]]
* [[Tags]]
</div>

<div class="box">
<h3>Blocks</h3>
* [[Making Blocks|Creating Blocks]]
* [[Understanding Blockstates]]
* [[Interacting With Blocks|Block Interactions]]
</div>

<div class="box">
<h3>Items</h3>
* [[Making Items]]
* [[Making Tools]]
* [[ItemStack TileEntityRenderer|<tt>ItemStackTileEntityRenderer</tt>]]
</div>

<div class="box">
<h3>Data Generation</h3>
* [[Datageneration|Introduction]]
* [[Datageneration/Recipes|Recipes]]
* [[Datageneration/Tags|Tags]]
* [[Datageneration/Loot_Tables|Loot Tables]]
* [[Datageneration/I18n|Localization]]
* [[Datageneration/States and Models|<tt>BlockState</tt>s and Models]]
</div>

<div class="box">
<h3>Tile Entities</h3>
* [[Basics of Tile Entities|Introduction]]
* [[Using Tile Entity Renderers]]
</div>

<div class="box">
<h3>Models</h3>
* [[Introduction to Models|Introduction]]
* [[Model JSONs]]
* [[BlockState JSONs]]
* [[Coloring textures dynamically|Dynamically Colored Textures]]
* [[Item Overrides]]
</div>

<div class="box">
<h3>Handling Information</h3>
* [[Understanding Networking|Introduction]]
* [[Using NBT|Named Binary Tag (NBT)]]
* [[Using PacketBuffer|Using <tt>PacketBuffer</tt>]]
* [[Sending Packets|Sending and Receiving Packets]]
* [[Using SimpleChannel|Using <tt>SimpleChannel</tt>]]
* [[Networking with Entities]]
* [[DynamicOps|Using DynamicOps]]
* [[Codecs|Using Codecs]]
</div>

<div class="box">
<h3>Data Storage</h3>
* [[Capabilities|Understanding Capabilities]]
* [[Capabilities/Attaching|Attaching Capabilities]]
* [[World Saved Data]]
</div>

<div class="box">
<h3>Game Effects</h3>
* [[Effects]]
* [[Potions]]
* [[Particles]]
* [[Sounds]]
</div>

<div class="box">
<h3>Events</h3>
* [[Events|Understanding Events]]
* [[Entity Events]]
</div>

<div class="box">
<h3>Others</h3>
* [[Dependencies]]
* [[Dynamic Loot Modification]]
* [[Text Components|Text Components and Translation Keys]]
* [[Key Bindings]]
* [[Access Transformers]]
* [[Toolchain]]
</div>

<div class="box">
<h3>Recipes</h3>
* [[Recipes]]
* [[Custom Recipes|Custom Recipe Types]]
* [[Datageneration/Recipes|Datageneration]]
</div>

</div>

Template:Supported versions

2021-07-28T02:09:29Z

SizableShrimp: grammar change

{{Colored box
|border-color=#3498db
|title={{{title|This wiki hosts information for the following Minecraft versions:}}}
|{{{1|* [[Main Page|1.17]]
* [[Main Page/1.16|1.16]]}}}
}}

Template:Supported versions

2021-07-28T02:07:02Z

SizableShrimp: Create initial template

{{Colored box
|border-color=#3498db
|title={{{title|This wiki supports the following Minecraft versions:}}}
|{{{1|* [[Main Page|1.17]]
* [[Main Page/1.16|1.16]]}}}
}}

Main Page/1.16

2021-07-27T04:21:04Z

SizableShrimp: Small fix

__NOTOC__
<templatestyles src=":Main_Page/styles.css" />

<div class="center title">Forge Community Wiki</div>

The Forge Community Wiki exists so that the community can:

* collectively keep track of major changes and updates to Forge and Vanilla code;
* create and edit articles with in-depth explanations about a variety of Forge-related subjects; and
* contribute example code and tutorials for both simple and difficult concepts.

This wiki is editable by any registered user with an account. This is to allow tracking of harmful edits, but isn't imposing any annoying limits. We welcome any edit, however small. Join the [https://discord.gg/Nn42eAh Discord] to discuss changes and edits to the wiki with others and the staff.

''The wiki is still under heavy construction. Pages may move around, so if you bookmark a page, beware when the page is moved and your bookmarked link dies.''

Please note that we only maintain wiki entries for the Latest and Long Term Support (LTS) releases. Once a documented release is no longer under LTS, it will be removed.

<div class="center round_warning">
Please read the [[FCWMeta:Wiki Policy|wiki policy]] before editing!
</div>

<div class="center" style="margin-bottom: 2em">
The current ''Latest'' version is '''1.16.5'''. The current ''Long Term Support (LTS)'' version is '''1.15.2'''.
</div>

<div class="box_container center">

<div class="box">
<h3>Beginner Topics</h3>
* [[Getting Started/1.16|Getting Started]]
* [[Proper Mod Structuring/1.16|Proper Mod Structuring]]
* [[Debug Profiler/1.16|The Debug Profiler]]
* [[Version Checker/1.16|Version Checker]]
</div>

<div class="box">
<h3>Common Concepts</h3>
* [[Sides/1.16|Understanding Sides]]
* [[Events/1.16|Understanding Events]]
* [[Registration/1.16|Registration]]
* [[Internationalization/1.16|Internationalization]]
</div>

<div class="box">
<h3>Forge Conventions</h3>
* [[Semantic Versioning/1.16|Semantic Versioning]]
* [[Stages of Modloading/1.16|Stages of Modloading]]
</div>

<div class="box">
<h3>Resources and Data</h3>
* [[Using Resources/1.16|Introduction]]
* [[Recipes/1.16|Recipes]]
* [[Tags/1.16|Tags]]
</div>

<div class="box">
<h3>Blocks</h3>
* [[Making Blocks/1.16|Creating Blocks]]
* [[Understanding Blockstates/1.16|Understanding Blockstates]]
* [[Interacting With Blocks/1.16|Block Interactions]]
</div>

<div class="box">
<h3>Items</h3>
* [[Making Items/1.16|Making Items]]
* [[Making Tools/1.16|Making Tools]]
* [[ItemStack TileEntityRenderer/1.16|<tt>ItemStackTileEntityRenderer</tt>]]
</div>

<div class="box">
<h3>Data Generation</h3>
* [[Datageneration/1.16|Introduction]]
* [[Datageneration/Recipes/1.16|Recipes]]
* [[Datageneration/Tags/1.16|Tags]]
* [[Datageneration/Loot Tables/1.16|Loot Tables]]
* [[Datageneration/I18n/1.16|Localization]]
* [[Datageneration/States and Models/1.16|<tt>BlockState</tt>s and Models]]
</div>

<div class="box">
<h3>Tile Entities</h3>
* [[Basics of Tile Entities/1.16|Introduction]]
* [[Using Tile Entity Renderers/1.16|Using Tile Entity Renderers]]
</div>

<div class="box">
<h3>Models</h3>
* [[Introduction to Models/1.16|Introduction]]
* [[Model JSONs/1.16|Model JSONs]]
* [[BlockState JSONs/1.16|BlockState JSONs]]
* [[Coloring textures dynamically/1.16|Dynamically Colored Textures]]
* [[Item Overrides/1.16|Item Overrides]]
</div>

<div class="box">
<h3>Handling Information</h3>
* [[Understanding Networking/1.16|Introduction]]
* [[Using NBT/1.16|Named Binary Tag (NBT)]]
* [[Using PacketBuffer/1.16|Using <tt>PacketBuffer</tt>]]
* [[Sending Packets/1.16|Sending and Receiving Packets]]
* [[Using SimpleChannel/1.16|Using <tt>SimpleChannel</tt>]]
* [[Networking with Entities/1.16|Networking with Entities]]
* [[DynamicOps/1.16|Using DynamicOps]]
* [[Codecs/1.16|Using Codecs]]
</div>

<div class="box">
<h3>Data Storage</h3>
* [[Capabilities/1.16|Understanding Capabilities]]
* [[Capabilities/Attaching/1.16|Attaching Capabilities]]
* [[World Saved Data/1.16|World Saved Data]]
</div>

<div class="box">
<h3>Game Effects</h3>
* [[Effects/1.16|Effects]]
* [[Potions/1.16|Potions]]
* [[Particles/1.16|Particles]]
* [[Sounds/1.16|Sounds]]
</div>

<div class="box">
<h3>Events</h3>
* [[Events/1.16|Understanding Events]]
* [[Entity Events/1.16|Entity Events]]
</div>

<div class="box">
<h3>Others</h3>
* [[Dependencies/1.16|Dependencies]]
* [[Dynamic Loot Modification/1.16|Dynamic Loot Modification]]
* [[Text Components/1.16|Text Components and Translation Keys]]
* [[Key Bindings/1.16|Key Bindings]]
* [[Access Transformers/1.16|Access Transformers]]
* [[Toolchain/1.16|Toolchain]]
</div>

<div class="box">
<h3>Recipes</h3>
* [[Recipes/1.16|Recipes]]
* [[Custom Recipes/1.16|Custom Recipe Types]]
* [[Datageneration/Recipes/1.16|Datageneration]]
</div>

</div>

Components

2021-05-30T00:27:38Z

SizableShrimp: Wording changes and updates

'''Text components''' (base interface <code>ITextComponent</code>) are forms of text used by Minecraft and Forge to concisely hold data relating to text. They form the basis of the chat system used in Minecraft. They are used for serializing and sending text data over network to players, displaying on clients, and styling for how the text appears with modifiers like bold and coloration.

There are two main types of text components: <code>StringTextComponent</code>s and <code>TranslationTextComponent</code>s. Both serve different purposes, although you should prefer the latter one for most general mod development. Both of these also extend from a base class of <code>TextComponent</code>, which has some important properties.

== TextComponent ==
Text components at their most basic level hold a <code>Style</code> object and a list of "sibling" text components named <code>siblings</code>. In reality, these "siblings" are actually children of the main text component, and are treated as such when formatting with the <code>Style</code> object. A style can be applied to a text component by calling <code>withStyle</code> and <code>setStyle</code>. <code>withStyle</code> modifies the existing <code>Style</code> object with the given property, while <code>setStyle</code> replaces the current <code>Style</code> object. By default, text components use a style of <code>Style.EMPTY</code>, with an empty color representing white and empty properties meaning no special text formatting. To add a light blue color for example, one could simple call <code>theTextComponent.withStyle(TextFormatting.BLUE)</code>. This will merge the <code>BLUE</code> color with the existing <code>Style</code> object. When applying a parent text component's <code>Style</code> to its children text components, a non-null property of a child <code>Style</code> will take precedence over its parent <code>Style</code>. This means that if the color is set for both a child and parent text component, the child's color will be displayed. Otherwise, non-null properties from a parent text component's <code>Style</code> override properties from the child <code>Style</code> if they are null.

=== Appending siblings ===
Siblings can be appended to text components similar to the plus (+) operator with Strings. Either <code>TextComponent#append(ITextComponent)</code> or <code>TextComponent#append(String)</code> can be called. The latter is an overload for the first function, and simply creates a new <code>StringTextComponent</code> with the provided String.

== StringTextComponent ==
String text components are the most basic form of text components. They are raw text components that contain a single String object. These are not preferred for general mod development as they cannot be translated into other languages. All properties of the base <code>TextComponent</code> apply to string text components.

=== Creating ===
String text components are instantiated in the form <code>new StringTextComponent("Hello, world!")</code>. In practice, when sent to a player, this would simply be displayed as declared: <code>Hello, world!</code>.

=== Usage ===
String text components are most commonly used to create empty or space-filling text components, which can then link multiple text components together using <code>appendSibling</code>.

== TranslationTextComponent ==
Translation text components are a more advanced form of text components that support String formatting and translation into multiple languages. Translation text components hold a '''translation key''', which is integral to translation into other languages. Translation keys are then mapped with a language file (commonly know as a lang file) to their appropriate entry for each translated language. It is important to note that the translation key is translated by the client, not the server. The server sends the translation key to the player, and the player's client converts the translation key into its fully expanded form when rendering depending on the player's selected language. If a player selects a specific language for which a translation key is not mapped, it will default to English.

=== Format modifiers ===
Translation text components also support format modifiers like used in <code>String#format</code>. These format modifiers are declared by using the string <code>%s</code> when creating a translation entry for a given translation key. This format modifier will then be expanded and replaced with the provided object when rendered by the client. Any other format modifiers like <code>%d</code> or <code>%n</code> are ''not supported'' and will throw a formatting error. To get a normal percentage, a double percentage sign must be used (<code>%%</code>). A number can also be inserted, and it will be used as a 1-based index to select the argument. This is useful for choosing a specific argument out of order, or using the same argument twice. This looks like <code>%1$s</code>. The list of arguments to expand these format modifiers are passed to the constructor of the <code>TranslationTextComponent</code> using an Object varargs parameter, similar to <code>String#format</code>. The arguments passed in the constructor of a <code>TranslationTextComponent</code> can be either an Object or another <code>ITextComponent</code>. Any <code>ITextComponent</code>s will be expanded and have any declared <code>Style</code>s properties preserved in the final output. Any objects that are not an instance of <code>ITextComponent</code> will have <code>Object#toString</code> called during expansion.

=== Creating ===
Translation text components are instantiated in the form <code>new TranslationTextComponent("your.translation_key.here", new StringTextComponent("thing1").withStyle(TextFormatting.RED), new StringTextComponent("thing1").withStyle(TextFormatting.BLUE))</code>. In your lang file, the entry would look something like: <syntaxhighlight lang="json">{
"your.translation_key.here": "I like using %1$s and %2$s!"
}</syntaxhighlight>
In practice, when sent to a player, this would be displayed as <code>I like using thing1 and thing2!</code>, where <code>thing1</code> would be colored as red and <code>thing2</code> would be colored as blue. Normal <code>String</code>s can also be passed in, and they will inherit the <code>Style</code> object of the main text component. Note that any more values in the language file must be declared as comma-separated key-value pairs as required by the JSON specification, with the last key-value pair not ending with a comment.

=== Usage ===
Translation text components are used for sending anything visual to the player. Using them provides a benefit of format modifiers and the ability to be translated into different languages. This means that, given a translator, one could translate the English translation file (by default, <code>en_us.json</code>) into another language for a given mod. This system is also used by Minecraft itself and has been used to translate the game into hundreds of langauges. Translation keys are also required for declaring the names of items, blocks, and entities in the game.

[[Category:Translations]]

Template:See also

2021-05-29T03:02:12Z

SizableShrimp: Adds template data

See also: [[{{{1}}}]]{{#if:{{{2|}}}|{{#if:{{{3|}}}|, | and }}[[{{{2}}}]]{{#if:{{{3|}}}|{{#if:{{{4|}}}|, | and }}[[{{{3}}}]]{{#if:{{{4|}}}|{{#if:{{{5|}}}|, | and }}[[{{{4}}}]]{{#if:{{{5|}}}|{{#if:{{{6|}}}|, | and }}[[{{{5}}}]]{{#if:{{{6|}}}|{{#if:{{{7|}}}|, | and }}[[{{{6}}}]]{{#if:{{{7|}}}|{{#if:{{{8|}}}|, | and }}[[{{{7}}}]]{{#if:{{{8|}}}|{{#if:{{{9|}}}|, | and }}[[{{{8}}}]]{{#if:{{{9|}}}| and [[{{{9}}}]]}} |}} |}} |}} |}} |}} |}} |}}''
<noinclude>
<templatedata>
{
"params": {
"1": {
"description": "The first article to see also",
"required": true,
"suggested": true
},
"2": {},
"3": {},
"4": {},
"5": {},
"6": {},
"7": {},
"8": {},
"9": {}
},
"description": "Adds a hatnote linking to similar or related articles. Used on section headers",
"format": "inline"
}
</templatedata>
</noinclude>

Template:See also

2021-05-29T02:59:20Z

SizableShrimp: Create template

Template:About

2021-05-19T01:36:48Z

SizableShrimp: Create {{About}} template

:''This page is about {{{1}}}. For {{{2|other uses}}}, see <span class="about-dis-link">[[{{{3|{{PAGENAME}} (Disambiguation)}}}]]</span>''.<noinclude>

<templatedata>
{
"params": {
"1": {
"description": "The use of the page",
"example": "This page is about forge modloading.",
"type": "string",
"required": true
},
"2": {
"description": "The use of the similar page",
"example": "For minecraft loading, see Minecraft Loading.",
"type": "string",
"default": "other uses",
"autovalue": "other uses"
},
"3": {
"description": "The disambiguation page or other page. Automatically converted into a wikilink.",
"example": "Minecraft Loading",
"type": "string",
"default": "{{PAGENAME}} (Disambiguation)",
"autovalue": "{{subst:PAGENAME}} (Disambiguation)"
}
},
"description": "Used to inform readers about the content on a page and provide them with similarly named pages.",
"format": "inline"
}
</templatedata>
</noinclude>