Forge Community Wiki - User contributions [en-gb]

Capabilities

2022-09-24T19:30:08Z

Curle: fix factual errors related to ForgeCapabilities vs the capability provider implementations

'''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">
@AutoRegisterCapability
public interface MyCapability {
String getValue();
void setValue(String value);
}

public class MyCapabilityImplementation implements MyCapability {
private String value;

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

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

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

=== The Capability Provider ===

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

=== Tying it All Together ===

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

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

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

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

=== Class Diagram ===

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

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

== Custom Capability Providers ==

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

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

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

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

== Code Examples ==

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

[[Category:Data Storage]]

Capabilities

2022-09-24T19:22:44Z

Curle: Undo revision 3332 by Nexus-Dino

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Working with Capabilities ==

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

=== Obtaining a Capability ===

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

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

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

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

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

=== Exposing a Capability ===

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Attaching a Capability ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Accessing a Capability ===

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

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

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

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

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

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

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

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

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

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

== Creating Custom Capabilities ==

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

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

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

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

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

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

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

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

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

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

public class MyCapabilityImplementation implements MyCapability {
private String value;

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

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

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

=== The Capability Provider ===

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

=== Tying it All Together ===

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

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

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

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

=== Class Diagram ===

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

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

== Custom Capability Providers ==

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

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

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

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

== Code Examples ==

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

[[Category:Data Storage]]

Capabilities

2021-12-18T00:00:18Z

Curle: Change example gist to one hosted by a Wiki admin (to fix invalidation problem)

'''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>, <code>IEnergyStorage</code>, and
<code>IAnimationStateMachine</code>. Each one of these capabilities will be discussed in the corresponding section.

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

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

This effectively '''replaces''' the vanilla interfaces <code>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>.

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

The <code>IAnimationStateMachine</code> capability refers to the ability for any capability provider to leverage the Forge Animation State Machine API for animations. This api does not work post 1.12 at the moment.

== 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]]

Capabilities

2021-12-17T23:58:00Z

Curle: Add note on invalidation, remove invalidation listener from example code.

'''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>, <code>IEnergyStorage</code>, and
<code>IAnimationStateMachine</code>. Each one of these capabilities will be discussed in the corresponding section.

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

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

This effectively '''replaces''' the vanilla interfaces <code>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>.

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

The <code>IAnimationStateMachine</code> capability refers to the ability for any capability provider to leverage the Forge Animation State Machine API for animations. This api does not work post 1.12 at the moment.

== 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/N1K-x/a17812bac9de4cf064baa789e9ccb96a A Gist showing a quick and dirty example on how to implement a Capability effectively]

[[Category:Data Storage]]

Events

2021-12-08T18:04:04Z

Curle: Spacing

{{Under construction}}

An '''event''' is a signal that is fired on an '''event bus''' to inform registered listeners about some type of action or state. This is the primary way by which Forge allows mods to hook into vanilla and game behavior; Forge has an array of different events which are fired when different actions happen within the game, and mods may act upon receiving these events.

Additionally, mods may create their own events and fire them for other mods to listen for, allowing for higher compatibility. For a class to be considered an event, it must be a subclass of <code>Event</code>.

== Generic Events ==
'''Generic events''' are events which supply additional generic type information, allowing event listeners to filter based on that secondary type. Generic events must implement <code>IGenericEvent<T></code>, and return their generic type from the <code>IGenericEvent#getType()</code> method. As a convenience, events that wish to be generic events may extend the <code>GenericEvent<T></code> instead of manually implementing the interface.

For generic events, the generic type must be an exact match with the listener's generic type filter to pass; if an <code>AttachCapabilitiesEvent<ItemStack></code> is fired and a listener is listening for <code>AttachCapabilitiesEvent<Object></code>, the listener does not receive the event. A event listener may listen to events with any generic type by supplying a wildcard generic (<code><?></code>). Nested generic types are ignored.

== Cancellable Events ==
An event may be marked as '''cancellable''', which allows event listeners to cancel the event.

A cancellable event may be cancelled by using <code>Event#setCanceled(true)</code>. Attempting to call this method on a non-cancellable event will result in a <code>UnsupportedOperationException</code>. A cancelled event behaves similarly to a regular noncancelled event, with one main difference: an event listener will not receive cancelled events unless they are explicitly registered to listen for cancelled events.

To mark an event as cancellable, the event class should be annotated with <code>@Cancelable</code>. This will automatically make <code>Event#isCancelable()</code> return <code>true</code>. Modders may check if an event has a result through the presence of the annotation or by calling the given method.

== Events with Results ==
An event may have a '''result''', which is an enum of <code>Event.Result</code>.

The <code>Event.Result</code> enum has three values: <code>ALLOW</code>, <code>DEFAULT</code>, and <code>DENY</code>. The meaning of these result values is entirely dependent on the event itself.

An event's current result can be retrieved through <code>Event#getResult()</code>. The result on an event can be set through <code>Event#setResult(Event.Result)</code>. You can set the result for an event which is not marked as having a result, however this will cause nothing to happen if the event does not use the result value.

To mark an event as having a result, the event class should be annotated with <code>@Event.HasResult</code>. This will automatically make <code>Event#hasResult</code> return <code>true</code>. Modders may check if an event has a result through the presence of the annotation or by calling the given method.

==Event Bus==
An '''event bus''' is an object which holds a list of event listeners, and the logic for firing the events. Events may be posted on these event buses, which then invokes the handlers. The main class for event buses is <code>IEventBus</code>, and a bus is created using <code>BusBuilder</code>.

You can find a more detailed explanation on the Event Bus pattern [https://dzone.com/articles/design-patterns-event-bus here.]
===Existing Buses===
Forge exposes three main families of event buses: the main Forge event bus, the mod-specific event buses, and the network channel event buses.
====Main Forge Event Bus====
The '''main Forge event bus''' is located at <code>MinecraftForge#EVENT_BUS</code>, and is where most events relating to ingame actions or events are fired on, such as events for ticking, block interactions, and entity interactions.

List of events fired on the main Forge event bus{{:Events/Forge bus}}

====Mod-Specific Event Buses====
The '''mod-specific event buses''' are the family of event buses where mod-related initialization and registration events are fired, such as the events for [[Registration|registering objects]] or setup on different physical sides. Only events which implement <code>IModBusEvent</code> may be fired or listened for on these event buses.

Each loaded mod has their own instance of a mod-specific event bus. The mod-specific event bus for the currently loading mod can be retrieved from <code>FMLModContainer#getEventBus()</code>, which is also accessible from <code>FMLJavaModLoadingContext#getModEventBus()</code>.

{{Tip|title=Tip|The mod-specific event buses are provided by the <code>javafml</code> language provider which is builtin to Forge Mod Loader. Custom language providers may provide other ways for mods to receive the different mod-related initialization and registration events; see the documentation of your custom language provider for details.}}
====Network Channel Event Buses====
The '''network channel event buses''' are the family of event buses where different network-related events are fired. Each registered [[Networking|networking channel]] has their own instance of an event-bus in <code>NetworkInstance</code>, where only events pertinent to that channel are fired on.

The network channel event buses cannot be accessed directly; <code>EventNetworkChannel</code> provides methods to register events listeners to the event bus.

== Event Listeners ==
An '''event listener''' (also known as an '''event handler''') is a class, object, or method registered to an event bus to capture for specific events (and their subclasses).

[[File:Guide to Event Handlers.png|thumb|upright 0.9|A visual guide on how event listeners are registered.]]

An event listener may be registered in three ways:
* The <code>IEventBus#register(Object)</code> method on a class or instance;
* The <code>@EventBusSubscriber</code> annotation on a class; or
* The <code>IEventBus#addListener</code> and <code>IEventBus#addGenericListener</code> on a method reference or lambda.

=== Priority and Receiving Cancelled Events ===
An event listener may be registered to a specific '''event priority''' and whether to '''receive cancelled events'''.

The event priority levels allows a listener to react to an event before other event listeners of a lower level, such as to change the values within an event or cancel it outright.

There are five levels of event listeners priority; in descending order from first to receive an event to last: <code>HIGHEST</code>, <code>HIGH</code>, <code>NORMAL</code>, <code>LOW</code>, and <code>LOWEST</code>. Event listeners are registered by default on a priority of <code>NORMAL</code>.

An event listener normally never receives a cancelled event, however they may change this by being registered to receive these cancelled events. Non-cancellable events are unaffected by this, and will always be sent to all event listeners (in the order specified by their priority).

=== <tt>IEventBus.register</tt> ===
The <code>IEventBus#register(Object)</code> method allows for registering an object instance or a <code>Class<?></code> to the event bus. The method exhibits two different behaviors, depending on what is passed into it:

* '''an object instance''' - registers all ''instance or non-<code>static</code>'' methods annotated with <code>@SubscribeEvent</code> from the object
* '''a <code>Class<?></code> instance''' - registers all ''class or <code>static</code>'' methods annotated with <code>@SubscribeEvent</code> from the class which is represented by the passed in <code>Class<?></code>

<tab collapsed name="Example of how event listeners are registered with the IEventBus.register method">
<syntaxhighlight lang="java">
class EventHandler {
public static void nonAnnotatedStatic(Event event) {}

@SubscribeEvent
public static void annotatedStatic(Event event) {}

public void nonAnnotatedInstance(Event event) {}

@SubscribeEvent
public void annotatedInstance(Event event) {}
}

// Within the execution of the program
IEventBus bus = ...;

// This will register the "annotatedStatic" method from the class
bus.register(EventHandler.class);
// This would register "annotatedStatic", but it is already registered
bus.register(EventHandler.class);

EventHandler instanceA = new EventHandler();
EventHandler instanceB = new EventHandler();

// This will register the "annotatedInstance" method from the instanceA object, and will not touch the instanceB object
bus.register(instanceA);
</syntaxhighlight>
If an <code>Event</code> were to be fired on the event bus in the example above, the <code>EventHandler#annotatedStatic</code> would receive the event, and the <code>annotatedInstance</code> method from the <code>instanceA</code> object instance would receive the event.

Neither the unnannotated methods will receive the event, nor will the <code>annotatedInstance</code> method from the <code>instanceB</code> object instance.

</tab>

==== <tt>@SubscribeEvent</tt> ====
The <code>@SubscribeEvent</code> annotation is used to mark a method as an event listener when its containing class or object is registered using <code>IEventBus#register</code>.

They have two fields: <code>EventPriority priority</code> and <code>boolean receiveCancelled</code>, which sets the event priority for the listener and whether the listener receives cancelled events, respectively.

= WIP =
TODO: @EventBusSubscriber, addListener, Generic Events? (probably higher up)

<tab name="Partial previous content of page, to be removed" collapsed>
== Forge and Mod Buses ==
There are two event buses of note to a mod: the '''main Forge event bus''', and the '''mod-specific event bus'''.

The Forge event bus, which can be referenced through <code>MinecraftForge.EVENT_BUS</code> or <code>EventBusSubscriber.Bus.FORGE</code> (the latter being an enum that provides handy references to both busses), fires events that depend solely on the game state. This means that:
* Entity Events
* Ticking Events
* Server Events
and more, are fired on the Forge bus.

The Mod bus, referenced through <code>FMLJavaModLoadingContext.get().getModEventBus()</code> or <code>EventBusSubscriber.Bus.MOD</code>, fires events that depend solely on mod state, or which are used to initialise such.
This means that:
* Registration Events
* Mod Lifecycle Events
* Model Events (bake and register)
* Config Events
* Data Provider Events
and more, are fired on the Mod bus. See [[Stages of Modloading|mod loading events]]. Note that some of these are fired in parallel.

== Sub Events ==

Many events have different variations of themselves, these can be different but all based around one common factor (e.g. <code>PlayerEvent</code>) or can be an event that has multiple phases (e.g. <code>PotionBrewEvent</code>). Take note that if you listen to the parent event class, you will receive calls to your method for ''all'' subclasses.

== Event Handlers ==
Event handlers are methods, which have four main properties. They are communicated to the event bus you want them to listen on, and when the event is posted on that bus, the hander is invoked.

Event handlers' properties are as such:
- Registered to an event bus
- May be static or instance
- Have a single argument, which is used to determine the event that is being listened for
- The argument given is the instance of the Event being posted.

Note that handlers may take the form of anonymous functions - lambdas.

== Registering Event Handlers ==
Event handlers are registered typically one of four ways:
* <code>EventBusSubscriber</code> (which requires a static, annotated handler method)
* <code>EventBus#register(T.class)</code> (which requires a static, annotated handler method)
* <code>EventBus#register(new X())</code> (which requires an instance, annotated handler method)
* <code>EventBus#addListener(Class::function)</code> (which requires an instance, non-annotated handler method)
* as an extension of the above: <code>EventBus#<LivingHurtEvent>addListener(event -> { code })</code>

Each of these will be explained in detail as follows.

=== Annotated Event Handlers ===

<syntaxhighlight lang="java">
public class MyForgeEventHandler {
@SubscribeEvent
public void pickupItem(EntityItemPickupEvent event) {
System.out.println("Item picked up!");
}
}
</syntaxhighlight>

This event handler listens for the <code>EntityItemPickupEvent</code>, which is, as the name states, posted to the event bus whenever an <code>Entity</code> picks up an item.

This function would be registered with <code>EventBus#register(new X())</code> in the above examples.

=== Static Event Handlers ===

An event handler may also be static. The handling method is still annotated with <code>@SubscribeEvent</code> with the only difference from an instance handler is that it is also marked static. In order to register a static event handler, an instance of the class won’t do, the Class itself has to be passed in. An example:

<syntaxhighlight lang="java">
public class MyStaticForgeEventHandler {
@SubscribeEvent
public static void arrowNocked(ArrowNockEvent event) {
System.out.println("Arrow nocked!");
}
}
</syntaxhighlight>

which must be registered <code>EventBus#register(MyStaticForgeEventHandler.class)</code>.

<h3 id="eventbussubscriber">Using <tt style="font-size: 100%">@Mod.EventBusSubscriber</tt></h3>

A class may be annotated with the <code>@Mod.EventBusSubscriber</code> annotation. Such a class is automatically registered to the configured bus when the <code>@Mod</code> class itself is constructed. This is essentially equivalent to adding <code>EventBus#register(AnnotatedClass.class);</code> at the end of the <code>@Mod</code> class's constructor.

The mod ID must be specified unless your class is already annotated with an <code>@Mod</code> annotation. You can pass the bus you want to listen to inside the <code>@Mod.EventBusSubscriber</code> annotation.

The bus registered with <code>EventBusSubscriber</code> defaults to the Forge event bus.

You can also specify the <code>Dist</code>s to load this event subscriber on. This can be used to not load client specific event subscribers on the dedicated server.

An example for a static event listener listening to <code>RenderWorldLastEvent</code> which will only be called on the physical client:

<syntaxhighlight lang="java">
@Mod.EventBusSubscriber(modid = "examplemod", dist = Dist.CLIENT)
public class MyStaticClientOnlyEventHandler {
@SubscribeEvent
public static void drawLast(RenderWorldLastEvent event) {
System.out.println("Drawing!");
}
}
</syntaxhighlight>

{{Tip/Important|This does not register an instance of the class; it registers the class itself (i.e. the event handling methods must be static).}}

=== Non-Annotated Event Handlers ===

Event handlers do not need to be annotated if they are directly referred to using <code>EventBus#addListener</code> (or <code>EventBus#addGenericListener</code> for generic events).

<syntaxhighlight lang="java">
@Mod("examplemod")
public class MyMainModClass {

public MyMainModClass() {
FMLJavaModLoadingContext.get().getModEventBus().addGenericListener(Entity.class, this::entityCap);
}

private void entityCap(AttachCapabilitiesEvent<Entity> event) {
System.out.println("Capability attached!");
}
}
</syntaxhighlight>

{{Tip/Important|The generic passed into the event must be referenced directly within the code itself. Otherwise, the event will not be called whatsoever. For example, if you use <code>AttachCapabilitiesEvent<LivingEntity></code>, the event will never be called as no call of this event uses <code>LivingEntity</code>, only <code>Entity</code>.}}

== Cancelling ==

If an event can be cancelled, it will be marked with the <code>@Cancelable</code> annotation, and the method <code>Event#isCancelable()</code> will return <code>true</code>. The cancel state of a cancellable event may be modified by calling <code>Event#setCanceled(boolean canceled)</code>, wherein passing the boolean value <code>true</code> is interpreted as cancelling the event, and passing the boolean value <code>false</code> is interpreted as “un-cancelling” the event.

{{Tip/Important|Not all events can be cancelled! Attempting to cancel an event that is not cancellable will result in an unchecked <code>UnsupportedOperationException</code> being thrown, which is expected to result in the game crashing. Always check that an event can be cancelled using <code>Event#isCancelable()</code> before attempting to cancel it.}}

== Results ==

Some events have an <code>Event.Result</code> as denoted by <code>@HasResult</code>. A result can be one of three things: <code>DENY</code> which stops the event, <code>DEFAULT</code> which uses the Vanilla behavior, and <code>ALLOW</code> which forces the action to take place, regardless of if it would have originally. The result of an event can be set by calling <code>setResult</code> with an Event.Result on the event.

{{Colored box|title=Information|content=Different events may use results in different ways, refer to the event's JavaDoc before using the result.}}

== Priority ==

Event handler methods have a priority. You can set the <code>priority</code> of an event handler method by setting the priority value of the annotation or the listener. The priority can be any value of the <code>EventPriority</code> enum (<code>HIGHEST</code>, <code>HIGH</code>, <code>NORMAL</code>, <code>LOW</code>, and <code>LOWEST</code>). Event handlers with priority <code>HIGHEST</code> are executed first and from there in descending order until <code>LOWEST</code> events which are executed last.

== Mod Event Bus ==
The mod event bus is primarily used for listening to lifecycle events in which mods should initialize. Many of these events are also ran in parallel so mods can be initialized at the same time. This does mean you cannot directly execute code from other mods in these events. Use the <code>InterModComms</code> system for that.

It is impossible for an event to be posted on the Mod bus that does not inherit the IModBusEvent interface.
Thus, this provides a good, easy way to tell which events are fired on this bus.

These are the four most commonly used lifecycle events that are called during mod initialization on the mod event bus:
* <code>FMLCommonSetupEvent</code>
* <code>FMLClientSetupEvent</code> & <code>FMLDedicatedServerSetupEvent</code> (''These events are only called on their respective [[Sides#Different_Kinds_of_Sides|physical side]].'')
* <code>InterModEnqueueEvent</code>
* <code>InterModProcessEvent</code>

These four lifecycle events are all ran in parallel. If you want to run code on the main thread during these events you can use the <code>enqueueWork</code> methods within the events to do so.

Next to the lifecycle events there are a few miscellaneous events that are fired on the mod event bus where you can register, set up, or initialize various things. Most of these events are not ran in parallel in contrast to the lifecycle events:
* <code>ColorHandlerEvent</code>
* <code>ModelBakeEvent</code>
* <code>TextureStitchEvent</code>
* <code>RegistryEvent</code>
* <code>GatherDataEvent</code>
* <code>SoundLoadEvent</code>
* <code>ParticleFactoryRegisterEvent</code>
* <code>ModConfigEvent</code>

A good rule of thumb: events are fired on the mod event bus when they should be handled during initialization of a mod. or where they are used to set state (eg. the config event.)

Detailed information about these events will be found in their respective pages, once they are ready.

== Forge Event Bus ==
The Forge event bus is where game state events are fired. If anything changes to do with the game, or anything happens that you would need to know about, there's a good chance it's sent here.

A full list of the events fired here is as follows, split into discrete categories:

{{Tree list}}
* <code>Event</code> - ''The root event class''
** '''Rendering events''' ('''client-only''')
*** <code>RenderWorldLastEvent</code> - Fired after world rendering to allow mods to add custom renders
*** <code>RenderHandEvent</code> - Fired before and after the hand of the player is rendered in the first person POV
*** <code>RenderLivingEvent</code> - Fired before and after a <code>LivingRenderer</code> is executed
*** <code>RenderItemInFrameEvent</code> - Fired before the item in an <code>ItemFrameEntity</code> is rendered
*** <code>RenderBlockOverlayEvent</code> - Fired before the block overlay for the player's screen is rendered
*** <code>DrawHighlightEvent</code> - Fired before the block highlight outline is rendered
*** <code>RenderTooltipEvent</code> - Fired before and during rendering of a text tooltip on a screen
*** <code>EntityViewRenderEvent</code> - Superclass for events relating to the player's viewpoint
*** <code>RenderGameOverlayEvent</code> - Superclass, fired for each element on the player's HUD or game overlay
*** <code>FOVUpdateEvent</code> - Fired when the FOV of the player is requested (?)
** '''GUI/Screen events''' ('''client-only''')
*** <code>GuiScreenEvent</code> - Superclass for events relating to <code>Screen</code>s
*** <code>GuiContainerEvent</code> - Superclsas for events relating to <code>ContainerScreen</code>s
*** <code>GuiOpenEvent</code> - Fired before a new screen is opened on the game window
** '''Superclass events''' - ''These events exist to be superclasses of other events''
*** <code>GenericEvent</code> - ''from EventBus'', superclass of events which have a generic type
*** <code>BlockEvent</code> - Superclass for events relating to a block within the world
*** <code>WorldEvent</code> - Superclass for events relating to the world
*** <code>InputEvent</code> - ('''client-only''') Superclass for events relating to the player's keyboard and mouse inputs
*** <code>NetworkEvent</code> - Superclass for events relating to networking
*** <code>ExplosionEvent</code> - Fired before an explosion explodes in the world
*** <code>SoundEvent</code> - ('''client-only''') Superclass for events related to sounds
*** <code>EntityEvent</code> - Superclass for events relating to entities
*** <code>TickEvent</code> - Superclass for events fired before and after ticking
** '''Chat events'''
*** <code>ServerChatEvent</code> ('''server-only''') - Fired when the server receives a chat message and before it relays the message
*** <code>ClientChatEvent</code> ('''client-only''') - Fired before the client is about to send a chat message
*** <code>ClientChatReceivedEvent</code> ('''client-only''') - Fired when the client receives a chat message from the server
** '''Data loading events'''
*** <code>RecipesUpdatedEvent</code>
*** <code>BiomeLoadingEvent</code>
*** <code>LootTableLoadEvent</code>
*** <code>StructureSpawnListGatherEvent</code>
** '''Startup events'''
*** <code>AddReloadListenerEvent</code>
*** <code>RegisterCommandsEvent</code>
*** <code>ServerLifecycleEvent</code>
** '''Gamemode events'''
*** <code>DifficultyChangeEvent</code>
*** <code>ClientPlayerChangeGamemodeEvent</code>
**'''Trade events'''
*** <code>WandererTradesEvent</code>
*** <code>VillagerTradesEvent</code>
** '''Other events'''
*** <code>FurnaceFuelBurnTimeEvent</code>
*** <code>BabyEntitySpawnEvent</code>
*** <code>VillageSiegeEvent</code>
*** <code>TagsUpdatedEvent</code>
*** <code>PotionBrewEvent</code>
*** <code>ScreenshotEvent</code>
*** <code>EnchantmentLevelSetEvent</code>
*** <code>CommandEvent</code>
*** <code>AnvilUpdateEvent</code>
*** <code>ItemAttributeModifierEvent</code>
*** <code>ClientPlayerNetworkEvent</code>
*** <code>ChunkWatchEvent</code>
{{Tree list/end}}

Like before, each of these events (especially the Super Events, which contain most of the useful events in the game) will have their own article explaining their purpose and usefulness.
</tab>

[[Category:Events]]

[[Category:Common Concepts]]

Events

2021-12-08T18:03:23Z

Curle: Event bus grammar

{{Under construction}}

An '''event''' is a signal that is fired on an '''event bus''' to inform registered listeners about some type of action or state. This is the primary way by which Forge allows mods to hook into vanilla and game behavior; Forge has an array of different events which are fired when different actions happen within the game, and mods may act upon receiving these events.

Additionally, mods may create their own events and fire them for other mods to listen for, allowing for higher compatibility. For a class to be considered an event, it must be a subclass of <code>Event</code>.

== Generic Events ==
'''Generic events''' are events which supply additional generic type information, allowing event listeners to filter based on that secondary type. Generic events must implement <code>IGenericEvent<T></code>, and return their generic type from the <code>IGenericEvent#getType()</code> method. As a convenience, events that wish to be generic events may extend the <code>GenericEvent<T></code> instead of manually implementing the interface.

For generic events, the generic type must be an exact match with the listener's generic type filter to pass; if an <code>AttachCapabilitiesEvent<ItemStack></code> is fired and a listener is listening for <code>AttachCapabilitiesEvent<Object></code>, the listener does not receive the event. A event listener may listen to events with any generic type by supplying a wildcard generic (<code><?></code>). Nested generic types are ignored.

== Cancellable Events ==
An event may be marked as '''cancellable''', which allows event listeners to cancel the event.

A cancellable event may be cancelled by using <code>Event#setCanceled(true)</code>. Attempting to call this method on a non-cancellable event will result in a <code>UnsupportedOperationException</code>. A cancelled event behaves similarly to a regular noncancelled event, with one main difference: an event listener will not receive cancelled events unless they are explicitly registered to listen for cancelled events.

To mark an event as cancellable, the event class should be annotated with <code>@Cancelable</code>. This will automatically make <code>Event#isCancelable()</code> return <code>true</code>. Modders may check if an event has a result through the presence of the annotation or by calling the given method.

== Events with Results ==
An event may have a '''result''', which is an enum of <code>Event.Result</code>.

The <code>Event.Result</code> enum has three values: <code>ALLOW</code>, <code>DEFAULT</code>, and <code>DENY</code>. The meaning of these result values is entirely dependent on the event itself.

An event's current result can be retrieved through <code>Event#getResult()</code>. The result on an event can be set through <code>Event#setResult(Event.Result)</code>. You can set the result for an event which is not marked as having a result, however this will cause nothing to happen if the event does not use the result value.

To mark an event as having a result, the event class should be annotated with <code>@Event.HasResult</code>. This will automatically make <code>Event#hasResult</code> return <code>true</code>. Modders may check if an event has a result through the presence of the annotation or by calling the given method.

==Event Bus==
An '''event bus''' is an object which holds a list of event listeners, and the logic for firing the events. Events may be posted on these event buses, which then invokes the handlers. The main class for event buses is <code>IEventBus</code>, and a bus is created using <code>BusBuilder</code>.

You can find a more detailed explanation on the Event Bus pattern[https://dzone.com/articles/design-patterns-event-bus here.]
===Existing Buses===
Forge exposes three main families of event buses: the main Forge event bus, the mod-specific event buses, and the network channel event buses.
====Main Forge Event Bus====
The '''main Forge event bus''' is located at <code>MinecraftForge#EVENT_BUS</code>, and is where most events relating to ingame actions or events are fired on, such as events for ticking, block interactions, and entity interactions.

List of events fired on the main Forge event bus{{:Events/Forge bus}}

====Mod-Specific Event Buses====
The '''mod-specific event buses''' are the family of event buses where mod-related initialization and registration events are fired, such as the events for [[Registration|registering objects]] or setup on different physical sides. Only events which implement <code>IModBusEvent</code> may be fired or listened for on these event buses.

Each loaded mod has their own instance of a mod-specific event bus. The mod-specific event bus for the currently loading mod can be retrieved from <code>FMLModContainer#getEventBus()</code>, which is also accessible from <code>FMLJavaModLoadingContext#getModEventBus()</code>.

{{Tip|title=Tip|The mod-specific event buses are provided by the <code>javafml</code> language provider which is builtin to Forge Mod Loader. Custom language providers may provide other ways for mods to receive the different mod-related initialization and registration events; see the documentation of your custom language provider for details.}}
====Network Channel Event Buses====
The '''network channel event buses''' are the family of event buses where different network-related events are fired. Each registered [[Networking|networking channel]] has their own instance of an event-bus in <code>NetworkInstance</code>, where only events pertinent to that channel are fired on.

The network channel event buses cannot be accessed directly; <code>EventNetworkChannel</code> provides methods to register events listeners to the event bus.

== Event Listeners ==
An '''event listener''' (also known as an '''event handler''') is a class, object, or method registered to an event bus to capture for specific events (and their subclasses).

[[File:Guide to Event Handlers.png|thumb|upright 0.9|A visual guide on how event listeners are registered.]]

An event listener may be registered in three ways:
* The <code>IEventBus#register(Object)</code> method on a class or instance;
* The <code>@EventBusSubscriber</code> annotation on a class; or
* The <code>IEventBus#addListener</code> and <code>IEventBus#addGenericListener</code> on a method reference or lambda.

=== Priority and Receiving Cancelled Events ===
An event listener may be registered to a specific '''event priority''' and whether to '''receive cancelled events'''.

The event priority levels allows a listener to react to an event before other event listeners of a lower level, such as to change the values within an event or cancel it outright.

There are five levels of event listeners priority; in descending order from first to receive an event to last: <code>HIGHEST</code>, <code>HIGH</code>, <code>NORMAL</code>, <code>LOW</code>, and <code>LOWEST</code>. Event listeners are registered by default on a priority of <code>NORMAL</code>.

An event listener normally never receives a cancelled event, however they may change this by being registered to receive these cancelled events. Non-cancellable events are unaffected by this, and will always be sent to all event listeners (in the order specified by their priority).

=== <tt>IEventBus.register</tt> ===
The <code>IEventBus#register(Object)</code> method allows for registering an object instance or a <code>Class<?></code> to the event bus. The method exhibits two different behaviors, depending on what is passed into it:

* '''an object instance''' - registers all ''instance or non-<code>static</code>'' methods annotated with <code>@SubscribeEvent</code> from the object
* '''a <code>Class<?></code> instance''' - registers all ''class or <code>static</code>'' methods annotated with <code>@SubscribeEvent</code> from the class which is represented by the passed in <code>Class<?></code>

<tab collapsed name="Example of how event listeners are registered with the IEventBus.register method">
<syntaxhighlight lang="java">
class EventHandler {
public static void nonAnnotatedStatic(Event event) {}

@SubscribeEvent
public static void annotatedStatic(Event event) {}

public void nonAnnotatedInstance(Event event) {}

@SubscribeEvent
public void annotatedInstance(Event event) {}
}

// Within the execution of the program
IEventBus bus = ...;

// This will register the "annotatedStatic" method from the class
bus.register(EventHandler.class);
// This would register "annotatedStatic", but it is already registered
bus.register(EventHandler.class);

EventHandler instanceA = new EventHandler();
EventHandler instanceB = new EventHandler();

// This will register the "annotatedInstance" method from the instanceA object, and will not touch the instanceB object
bus.register(instanceA);
</syntaxhighlight>
If an <code>Event</code> were to be fired on the event bus in the example above, the <code>EventHandler#annotatedStatic</code> would receive the event, and the <code>annotatedInstance</code> method from the <code>instanceA</code> object instance would receive the event.

Neither the unnannotated methods will receive the event, nor will the <code>annotatedInstance</code> method from the <code>instanceB</code> object instance.

</tab>

==== <tt>@SubscribeEvent</tt> ====
The <code>@SubscribeEvent</code> annotation is used to mark a method as an event listener when its containing class or object is registered using <code>IEventBus#register</code>.

They have two fields: <code>EventPriority priority</code> and <code>boolean receiveCancelled</code>, which sets the event priority for the listener and whether the listener receives cancelled events, respectively.

= WIP =
TODO: @EventBusSubscriber, addListener, Generic Events? (probably higher up)

<tab name="Partial previous content of page, to be removed" collapsed>
== Forge and Mod Buses ==
There are two event buses of note to a mod: the '''main Forge event bus''', and the '''mod-specific event bus'''.

The Forge event bus, which can be referenced through <code>MinecraftForge.EVENT_BUS</code> or <code>EventBusSubscriber.Bus.FORGE</code> (the latter being an enum that provides handy references to both busses), fires events that depend solely on the game state. This means that:
* Entity Events
* Ticking Events
* Server Events
and more, are fired on the Forge bus.

The Mod bus, referenced through <code>FMLJavaModLoadingContext.get().getModEventBus()</code> or <code>EventBusSubscriber.Bus.MOD</code>, fires events that depend solely on mod state, or which are used to initialise such.
This means that:
* Registration Events
* Mod Lifecycle Events
* Model Events (bake and register)
* Config Events
* Data Provider Events
and more, are fired on the Mod bus. See [[Stages of Modloading|mod loading events]]. Note that some of these are fired in parallel.

== Sub Events ==

Many events have different variations of themselves, these can be different but all based around one common factor (e.g. <code>PlayerEvent</code>) or can be an event that has multiple phases (e.g. <code>PotionBrewEvent</code>). Take note that if you listen to the parent event class, you will receive calls to your method for ''all'' subclasses.

== Event Handlers ==
Event handlers are methods, which have four main properties. They are communicated to the event bus you want them to listen on, and when the event is posted on that bus, the hander is invoked.

Event handlers' properties are as such:
- Registered to an event bus
- May be static or instance
- Have a single argument, which is used to determine the event that is being listened for
- The argument given is the instance of the Event being posted.

Note that handlers may take the form of anonymous functions - lambdas.

== Registering Event Handlers ==
Event handlers are registered typically one of four ways:
* <code>EventBusSubscriber</code> (which requires a static, annotated handler method)
* <code>EventBus#register(T.class)</code> (which requires a static, annotated handler method)
* <code>EventBus#register(new X())</code> (which requires an instance, annotated handler method)
* <code>EventBus#addListener(Class::function)</code> (which requires an instance, non-annotated handler method)
* as an extension of the above: <code>EventBus#<LivingHurtEvent>addListener(event -> { code })</code>

Each of these will be explained in detail as follows.

=== Annotated Event Handlers ===

<syntaxhighlight lang="java">
public class MyForgeEventHandler {
@SubscribeEvent
public void pickupItem(EntityItemPickupEvent event) {
System.out.println("Item picked up!");
}
}
</syntaxhighlight>

This event handler listens for the <code>EntityItemPickupEvent</code>, which is, as the name states, posted to the event bus whenever an <code>Entity</code> picks up an item.

This function would be registered with <code>EventBus#register(new X())</code> in the above examples.

=== Static Event Handlers ===

An event handler may also be static. The handling method is still annotated with <code>@SubscribeEvent</code> with the only difference from an instance handler is that it is also marked static. In order to register a static event handler, an instance of the class won’t do, the Class itself has to be passed in. An example:

<syntaxhighlight lang="java">
public class MyStaticForgeEventHandler {
@SubscribeEvent
public static void arrowNocked(ArrowNockEvent event) {
System.out.println("Arrow nocked!");
}
}
</syntaxhighlight>

which must be registered <code>EventBus#register(MyStaticForgeEventHandler.class)</code>.

<h3 id="eventbussubscriber">Using <tt style="font-size: 100%">@Mod.EventBusSubscriber</tt></h3>

A class may be annotated with the <code>@Mod.EventBusSubscriber</code> annotation. Such a class is automatically registered to the configured bus when the <code>@Mod</code> class itself is constructed. This is essentially equivalent to adding <code>EventBus#register(AnnotatedClass.class);</code> at the end of the <code>@Mod</code> class's constructor.

The mod ID must be specified unless your class is already annotated with an <code>@Mod</code> annotation. You can pass the bus you want to listen to inside the <code>@Mod.EventBusSubscriber</code> annotation.

The bus registered with <code>EventBusSubscriber</code> defaults to the Forge event bus.

You can also specify the <code>Dist</code>s to load this event subscriber on. This can be used to not load client specific event subscribers on the dedicated server.

An example for a static event listener listening to <code>RenderWorldLastEvent</code> which will only be called on the physical client:

<syntaxhighlight lang="java">
@Mod.EventBusSubscriber(modid = "examplemod", dist = Dist.CLIENT)
public class MyStaticClientOnlyEventHandler {
@SubscribeEvent
public static void drawLast(RenderWorldLastEvent event) {
System.out.println("Drawing!");
}
}
</syntaxhighlight>

{{Tip/Important|This does not register an instance of the class; it registers the class itself (i.e. the event handling methods must be static).}}

=== Non-Annotated Event Handlers ===

Event handlers do not need to be annotated if they are directly referred to using <code>EventBus#addListener</code> (or <code>EventBus#addGenericListener</code> for generic events).

<syntaxhighlight lang="java">
@Mod("examplemod")
public class MyMainModClass {

public MyMainModClass() {
FMLJavaModLoadingContext.get().getModEventBus().addGenericListener(Entity.class, this::entityCap);
}

private void entityCap(AttachCapabilitiesEvent<Entity> event) {
System.out.println("Capability attached!");
}
}
</syntaxhighlight>

{{Tip/Important|The generic passed into the event must be referenced directly within the code itself. Otherwise, the event will not be called whatsoever. For example, if you use <code>AttachCapabilitiesEvent<LivingEntity></code>, the event will never be called as no call of this event uses <code>LivingEntity</code>, only <code>Entity</code>.}}

== Cancelling ==

If an event can be cancelled, it will be marked with the <code>@Cancelable</code> annotation, and the method <code>Event#isCancelable()</code> will return <code>true</code>. The cancel state of a cancellable event may be modified by calling <code>Event#setCanceled(boolean canceled)</code>, wherein passing the boolean value <code>true</code> is interpreted as cancelling the event, and passing the boolean value <code>false</code> is interpreted as “un-cancelling” the event.

{{Tip/Important|Not all events can be cancelled! Attempting to cancel an event that is not cancellable will result in an unchecked <code>UnsupportedOperationException</code> being thrown, which is expected to result in the game crashing. Always check that an event can be cancelled using <code>Event#isCancelable()</code> before attempting to cancel it.}}

== Results ==

Some events have an <code>Event.Result</code> as denoted by <code>@HasResult</code>. A result can be one of three things: <code>DENY</code> which stops the event, <code>DEFAULT</code> which uses the Vanilla behavior, and <code>ALLOW</code> which forces the action to take place, regardless of if it would have originally. The result of an event can be set by calling <code>setResult</code> with an Event.Result on the event.

{{Colored box|title=Information|content=Different events may use results in different ways, refer to the event's JavaDoc before using the result.}}

== Priority ==

Event handler methods have a priority. You can set the <code>priority</code> of an event handler method by setting the priority value of the annotation or the listener. The priority can be any value of the <code>EventPriority</code> enum (<code>HIGHEST</code>, <code>HIGH</code>, <code>NORMAL</code>, <code>LOW</code>, and <code>LOWEST</code>). Event handlers with priority <code>HIGHEST</code> are executed first and from there in descending order until <code>LOWEST</code> events which are executed last.

== Mod Event Bus ==
The mod event bus is primarily used for listening to lifecycle events in which mods should initialize. Many of these events are also ran in parallel so mods can be initialized at the same time. This does mean you cannot directly execute code from other mods in these events. Use the <code>InterModComms</code> system for that.

It is impossible for an event to be posted on the Mod bus that does not inherit the IModBusEvent interface.
Thus, this provides a good, easy way to tell which events are fired on this bus.

These are the four most commonly used lifecycle events that are called during mod initialization on the mod event bus:
* <code>FMLCommonSetupEvent</code>
* <code>FMLClientSetupEvent</code> & <code>FMLDedicatedServerSetupEvent</code> (''These events are only called on their respective [[Sides#Different_Kinds_of_Sides|physical side]].'')
* <code>InterModEnqueueEvent</code>
* <code>InterModProcessEvent</code>

These four lifecycle events are all ran in parallel. If you want to run code on the main thread during these events you can use the <code>enqueueWork</code> methods within the events to do so.

Next to the lifecycle events there are a few miscellaneous events that are fired on the mod event bus where you can register, set up, or initialize various things. Most of these events are not ran in parallel in contrast to the lifecycle events:
* <code>ColorHandlerEvent</code>
* <code>ModelBakeEvent</code>
* <code>TextureStitchEvent</code>
* <code>RegistryEvent</code>
* <code>GatherDataEvent</code>
* <code>SoundLoadEvent</code>
* <code>ParticleFactoryRegisterEvent</code>
* <code>ModConfigEvent</code>

A good rule of thumb: events are fired on the mod event bus when they should be handled during initialization of a mod. or where they are used to set state (eg. the config event.)

Detailed information about these events will be found in their respective pages, once they are ready.

== Forge Event Bus ==
The Forge event bus is where game state events are fired. If anything changes to do with the game, or anything happens that you would need to know about, there's a good chance it's sent here.

A full list of the events fired here is as follows, split into discrete categories:

{{Tree list}}
* <code>Event</code> - ''The root event class''
** '''Rendering events''' ('''client-only''')
*** <code>RenderWorldLastEvent</code> - Fired after world rendering to allow mods to add custom renders
*** <code>RenderHandEvent</code> - Fired before and after the hand of the player is rendered in the first person POV
*** <code>RenderLivingEvent</code> - Fired before and after a <code>LivingRenderer</code> is executed
*** <code>RenderItemInFrameEvent</code> - Fired before the item in an <code>ItemFrameEntity</code> is rendered
*** <code>RenderBlockOverlayEvent</code> - Fired before the block overlay for the player's screen is rendered
*** <code>DrawHighlightEvent</code> - Fired before the block highlight outline is rendered
*** <code>RenderTooltipEvent</code> - Fired before and during rendering of a text tooltip on a screen
*** <code>EntityViewRenderEvent</code> - Superclass for events relating to the player's viewpoint
*** <code>RenderGameOverlayEvent</code> - Superclass, fired for each element on the player's HUD or game overlay
*** <code>FOVUpdateEvent</code> - Fired when the FOV of the player is requested (?)
** '''GUI/Screen events''' ('''client-only''')
*** <code>GuiScreenEvent</code> - Superclass for events relating to <code>Screen</code>s
*** <code>GuiContainerEvent</code> - Superclsas for events relating to <code>ContainerScreen</code>s
*** <code>GuiOpenEvent</code> - Fired before a new screen is opened on the game window
** '''Superclass events''' - ''These events exist to be superclasses of other events''
*** <code>GenericEvent</code> - ''from EventBus'', superclass of events which have a generic type
*** <code>BlockEvent</code> - Superclass for events relating to a block within the world
*** <code>WorldEvent</code> - Superclass for events relating to the world
*** <code>InputEvent</code> - ('''client-only''') Superclass for events relating to the player's keyboard and mouse inputs
*** <code>NetworkEvent</code> - Superclass for events relating to networking
*** <code>ExplosionEvent</code> - Fired before an explosion explodes in the world
*** <code>SoundEvent</code> - ('''client-only''') Superclass for events related to sounds
*** <code>EntityEvent</code> - Superclass for events relating to entities
*** <code>TickEvent</code> - Superclass for events fired before and after ticking
** '''Chat events'''
*** <code>ServerChatEvent</code> ('''server-only''') - Fired when the server receives a chat message and before it relays the message
*** <code>ClientChatEvent</code> ('''client-only''') - Fired before the client is about to send a chat message
*** <code>ClientChatReceivedEvent</code> ('''client-only''') - Fired when the client receives a chat message from the server
** '''Data loading events'''
*** <code>RecipesUpdatedEvent</code>
*** <code>BiomeLoadingEvent</code>
*** <code>LootTableLoadEvent</code>
*** <code>StructureSpawnListGatherEvent</code>
** '''Startup events'''
*** <code>AddReloadListenerEvent</code>
*** <code>RegisterCommandsEvent</code>
*** <code>ServerLifecycleEvent</code>
** '''Gamemode events'''
*** <code>DifficultyChangeEvent</code>
*** <code>ClientPlayerChangeGamemodeEvent</code>
**'''Trade events'''
*** <code>WandererTradesEvent</code>
*** <code>VillagerTradesEvent</code>
** '''Other events'''
*** <code>FurnaceFuelBurnTimeEvent</code>
*** <code>BabyEntitySpawnEvent</code>
*** <code>VillageSiegeEvent</code>
*** <code>TagsUpdatedEvent</code>
*** <code>PotionBrewEvent</code>
*** <code>ScreenshotEvent</code>
*** <code>EnchantmentLevelSetEvent</code>
*** <code>CommandEvent</code>
*** <code>AnvilUpdateEvent</code>
*** <code>ItemAttributeModifierEvent</code>
*** <code>ClientPlayerNetworkEvent</code>
*** <code>ChunkWatchEvent</code>
{{Tree list/end}}

Like before, each of these events (especially the Super Events, which contain most of the useful events in the game) will have their own article explaining their purpose and usefulness.
</tab>

[[Category:Events]]

[[Category:Common Concepts]]

Access Transformers

2021-08-12T23:48:13Z

Curle: parameters, man.

{{Under construction}}

Access Transformers are Forge's native way of allowing you to access (read and write) functions that have a lower-than-ideal visibility, and/or removing finality.

== Visibility ==

Here's a quick rundown of the visibility options offered by Java 16:

* <code>public</code> visible to all classes inside and outside its package
* <code>protected</code> visible only to classes inside the package and subclasses
* <code>default</code> visible only to classes inside the package
* <code>private</code> visible only to inside the class

Additionally, there are final variants of each of these, each represented by the phrase "-f" on the end of the access specifier.

== How It Works ==

As Forge is loading, it scans the jar file for the META-INF/accesstransformers.cfg file. if it's found, it is parsed according to the specification:

<code ->NewAccessSpecifier ClassSignature MemberSignature # comment</code>

If you're targetting a class itself, you may omit the Member Signature.<br>
However, it is required if you're targetting a method or field inside the class.<br>
<code>MemberSignature</code>s use the Java specification for parts.<br>
Importantly, method descriptors are <code>name(parameters)return</code>, classes in the parameters are in the form <code>Lpath/to/Class;</code>,and <code>V</code> is void.<br>

A couple random examples to understand the syntax:

<code>
public net.minecraft.world.level.chunk.PaletteResize # makes the PaletteResize class public<br>
protected net.minecraft.client.gui.Gui f_168667_ # COLOR_WHITE<br>
public net.minecraft.client.renderer.GameRenderer m_109128_(Lnet/minecraft/resources/ResourceLocation;)V # loadEffect </code>

If a valid entry is found on a line, Forge will look into the bytecode of the file where that member is defined, and change its access to whatever you desire it to be.

This startup modification means accessing is O(1) for all accesses after this initial change, which makes it a great option for performance if you're looking at something a lot

=== Removing Finality ===
Access transformers can also be used to remove the '''final''' keyword on code elements. To do this, append <code>-f</code> to the access specifier.

An example of this in place:

<code ->public-f net.minecraft.world.level.chunk.PaletteResize # makes PaletteResize public</code>

Note: You can also use this to ''add'' a final keyword via <code>+f</code>. This is never recommended however, and should be avoided at all costs unless absolutely necessary.

== Using Access Transformers in your mod ==

{{Tip/Important|You should avoid using ATs if a private variable / function you're looking at has a getter or a setter. Variables are usually private for a reason.}}

Step 1: Uncomment the access transformer line in your build.gradle

[[File:Access-transformers-uncomment-this-line-in-build-gradle.png|600px|frameless]]

Step 2: Create a new file called "accesstransformer.cfg" in the <code><nowiki>src/main/resources/META-INF/</nowiki></code> folder.

Step 3: Refresh the Gradle project. This can be done natively in IDEA and Eclipse.

== When not to use Access Transformers ==
* Unnecessary access transformations (e.g. using ATs to make something <code>public</code> when it's already <code>public</code>)

Access Transformers

2021-08-12T23:47:07Z

Curle: Adjust potentially confusing wording

{{Under construction}}

Access Transformers are Forge's native way of allowing you to access (read and write) functions that have a lower-than-ideal visibility, and/or removing finality.

== Visibility ==

Here's a quick rundown of the visibility options offered by Java 16:

* <code>public</code> visible to all classes inside and outside its package
* <code>protected</code> visible only to classes inside the package and subclasses
* <code>default</code> visible only to classes inside the package
* <code>private</code> visible only to inside the class

Additionally, there are final variants of each of these, each represented by the phrase "-f" on the end of the access specifier.

== How It Works ==

As Forge is loading, it scans the jar file for the META-INF/accesstransformers.cfg file. if it's found, it is parsed according to the specification:

<code ->NewAccessSpecifier ClassSignature MemberSignature # comment</code>

If you're targetting a class itself, you may omit the Member Signature.<br>
However, it is required if you're targetting a method or field inside the class.<br>
<code>MemberSignature</code>s use the Java specification for parts.<br>
Importantly, method descriptors are <code>name(parameters)return</code>, classes in the paramters are in the form <code>Lpath/to/Class;</code>,and <code>V</code> is void.<br>

A couple random examples to understand the syntax:

<code>
public net.minecraft.world.level.chunk.PaletteResize # makes the PaletteResize class public<br>
protected net.minecraft.client.gui.Gui f_168667_ # COLOR_WHITE<br>
public net.minecraft.client.renderer.GameRenderer m_109128_(Lnet/minecraft/resources/ResourceLocation;)V # loadEffect </code>

If a valid entry is found on a line, Forge will look into the bytecode of the file where that member is defined, and change its access to whatever you desire it to be.

This startup modification means accessing is O(1) for all accesses after this initial change, which makes it a great option for performance if you're looking at something a lot

=== Removing Finality ===
Access transformers can also be used to remove the '''final''' keyword on code elements. To do this, append <code>-f</code> to the access specifier.

An example of this in place:

<code ->public-f net.minecraft.world.level.chunk.PaletteResize # makes PaletteResize public</code>

Note: You can also use this to ''add'' a final keyword via <code>+f</code>. This is never recommended however, and should be avoided at all costs unless absolutely necessary.

== Using Access Transformers in your mod ==

{{Tip/Important|You should avoid using ATs if a private variable / function you're looking at has a getter or a setter. Variables are usually private for a reason.}}

Step 1: Uncomment the access transformer line in your build.gradle

[[File:Access-transformers-uncomment-this-line-in-build-gradle.png|600px|frameless]]

Step 2: Create a new file called "accesstransformer.cfg" in the <code><nowiki>src/main/resources/META-INF/</nowiki></code> folder.

Step 3: Refresh the Gradle project. This can be done natively in IDEA and Eclipse.

== When not to use Access Transformers ==
* Unnecessary access transformations (e.g. using ATs to make something <code>public</code> when it's already <code>public</code>)

Access Transformers

2021-08-12T23:39:35Z

Curle: "a class or field inside the class" -> "a method or field inside the class"

{{Under construction}}

Access Transformers are Forge's native way of allowing you to access (read and write) functions that have a lower-than-ideal visibility, and/or removing finality.

== Visibility ==

Here's a quick rundown of the visibility options offered by Java 16:

* <code>public</code> visible to all classes inside and outside its package
* <code>protected</code> visible only to classes inside the package and subclasses
* <code>default</code> visible only to classes inside the package
* <code>private</code> visible only to inside the class

Additionally, there are final variants of each of these, each represented by the phrase "-f" on the end of the access specifier.

== How It Works ==

As Forge is loading, it scans the jar file for the META-INF/accesstransformers.cfg file. if it's found, it is parsed according to the specification:

<code ->NewAccessSpecifier ClassSignature MemberSignature # comment</code>

If you're targetting a class itself, you may omit the Member Signature.<br>
However, it is required if you're targetting a method or field inside the class.<br>
<code>MemberSignature</code>s use the Java specification for parts.<br>
Importantly, classes are in the form <code>Lpath/to/Class;</code>, method descriptors are <code>name(parameters)return</code> and <code>V</code> is void.<br>

A couple random examples to understand the syntax:

<code>
public net.minecraft.world.level.chunk.PaletteResize # makes the PaletteResize class public<br>
protected net.minecraft.client.gui.Gui f_168667_ # COLOR_WHITE<br>
public net.minecraft.client.renderer.GameRenderer m_109128_(Lnet/minecraft/resources/ResourceLocation;)V # loadEffect </code>

If a valid entry is found on a line, Forge will look into the bytecode of the file where that member is defined, and change its access to whatever you desire it to be.

This startup modification means accessing is O(1) for all accesses after this initial change, which makes it a great option for performance if you're looking at something a lot

=== Removing Finality ===
Access transformers can also be used to remove the '''final''' keyword on code elements. To do this, append <code>-f</code> to the access specifier.

An example of this in place:

<code ->public-f net.minecraft.world.level.chunk.PaletteResize # makes PaletteResize public</code>

Note: You can also use this to ''add'' a final keyword via <code>+f</code>. This is never recommended however, and should be avoided at all costs unless absolutely necessary.

== Using Access Transformers in your mod ==

{{Tip/Important|You should avoid using ATs if a private variable / function you're looking at has a getter or a setter. Variables are usually private for a reason.}}

Step 1: Uncomment the access transformer line in your build.gradle

[[File:Access-transformers-uncomment-this-line-in-build-gradle.png|600px|frameless]]

Step 2: Create a new file called "accesstransformer.cfg" in the <code><nowiki>src/main/resources/META-INF/</nowiki></code> folder.

Step 3: Refresh the Gradle project. This can be done natively in IDEA and Eclipse.

== When not to use Access Transformers ==
* Unnecessary access transformations (e.g. using ATs to make something <code>public</code> when it's already <code>public</code>)

Access Transformers

2021-08-12T23:38:25Z

Curle: Add information on member signatures. TODO: add a link to the Java specification on signatures

{{Under construction}}

Access Transformers are Forge's native way of allowing you to access (read and write) functions that have a lower-than-ideal visibility, and/or removing finality.

== Visibility ==

Here's a quick rundown of the visibility options offered by Java 16:

* <code>public</code> visible to all classes inside and outside its package
* <code>protected</code> visible only to classes inside the package and subclasses
* <code>default</code> visible only to classes inside the package
* <code>private</code> visible only to inside the class

Additionally, there are final variants of each of these, each represented by the phrase "-f" on the end of the access specifier.

== How It Works ==

As Forge is loading, it scans the jar file for the META-INF/accesstransformers.cfg file. if it's found, it is parsed according to the specification:

<code ->NewAccessSpecifier ClassSignature MemberSignature # comment</code>

If you're targetting a class itself, you may omit the Member Signature.<br>
However, it is required if you're targetting a class or field inside the class.<br>
<code>MemberSignature</code>s use the Java specification for parts.<br>
Importantly, classes are in the form <code>Lpath/to/Class;</code>, method descriptors are <code>name(parameters)return</code> and <code>V</code> is void.<br>

A couple random examples to understand the syntax:

<code>
public net.minecraft.world.level.chunk.PaletteResize # makes the PaletteResize class public<br>
protected net.minecraft.client.gui.Gui f_168667_ # COLOR_WHITE<br>
public net.minecraft.client.renderer.GameRenderer m_109128_(Lnet/minecraft/resources/ResourceLocation;)V # loadEffect </code>

If a valid entry is found on a line, Forge will look into the bytecode of the file where that member is defined, and change its access to whatever you desire it to be.

This startup modification means accessing is O(1) for all accesses after this initial change, which makes it a great option for performance if you're looking at something a lot

=== Removing Finality ===
Access transformers can also be used to remove the '''final''' keyword on code elements. To do this, append <code>-f</code> to the access specifier.

An example of this in place:

<code ->public-f net.minecraft.world.level.chunk.PaletteResize # makes PaletteResize public</code>

Note: You can also use this to ''add'' a final keyword via <code>+f</code>. This is never recommended however, and should be avoided at all costs unless absolutely necessary.

== Using Access Transformers in your mod ==

{{Tip/Important|You should avoid using ATs if a private variable / function you're looking at has a getter or a setter. Variables are usually private for a reason.}}

Step 1: Uncomment the access transformer line in your build.gradle

[[File:Access-transformers-uncomment-this-line-in-build-gradle.png|600px|frameless]]

Step 2: Create a new file called "accesstransformer.cfg" in the <code><nowiki>src/main/resources/META-INF/</nowiki></code> folder.

Step 3: Refresh the Gradle project. This can be done natively in IDEA and Eclipse.

== When not to use Access Transformers ==
* Unnecessary access transformations (e.g. using ATs to make something <code>public</code> when it's already <code>public</code>)

Sounds/1.16

2021-08-08T01:20:59Z

Curle: Add note about mono sounds and attenuation.

Although not essential, sounds bring a greater immersion into the Minecraft world. Their usages within and outside the development environment gives a bit more polish to an already existing mod from background music to a single block break.

== Creating a Sound ==

Sounds in Minecraft are comprised of two things: an audio file and a reference pointer to that audio file.

The reference pointer is known as <code>sounds.json</code> which should be created at <code><nowiki>assets/<modid>/sounds.json</nowiki></code>. This JSON defines resource names to point to the audio files added by a specific mod. The only thing necessary to define a sound is by creating an object, naming it, and then defining the location of the sound within a list.

By default, the only supported audio format is [https://xiph.org/vorbis/ Ogg Vorbis] represented by the extension <code>.ogg</code>. The file <code>namespace:path</code> when referenced in the JSON will be located within <code><nowiki>assets/<namespace>/sounds/<path>.ogg</nowiki></code>.

<syntaxhighlight lang="json">
{
"example_sound": {
"sounds": [ "examplemod:example_sound_file" ]
}
}
</syntaxhighlight>

Using the example above, it creates a sound called <code>example_sound</code> and references the file <code><nowiki>assets/<modid>/sounds/example_sound_file.ogg</nowiki></code>.

{{Tip/Danger | Due to [https://bugs.mojang.com/browse/MC-146721 the way OpenAL (Minecraft's sound engine) works], for your sound to have attenuation - that is, for it to get quieter as the player walks away, it absolutely MUST be mono (have one audio channel).

Stereo sounds are always played at the '''player's''' location, making them ideal for ambient sounds and background music.

}}

Instead of being constructed as a list of strings, each entry could also be an object which allows a greater control over what and how it is played.

Here are some variables that could be defined:
{| class="wikitable sortable" border=1
!Parameter !!Description
|-
| name || Sets the path to the sound file excluding the <code>.ogg</code> extension.
|-
| stream || Determines whether the sound should be streamed from the file. When true, it reduces the amount of lag from loading a large file; however, it only allows four instances of the sound to be played at once.
|-
| volume || A value between 0 and 1 to determine the volume of the sound played.
|-
|}

<syntaxhighlight lang="json">
{
"example_sound": {
"sounds": [ "examplemod:example_sound_file" ]
},
"example_sound_complex": {
"sounds":
[
{
"name": "examplemod:complex/example_complex",
"pitch": 0.6,
"stream": true
}
]
}
}
</syntaxhighlight>

Now there is a new sound within our JSON called <code>example_sound_complex</code>. This points to the audio file at <code>assets/examplemod/sounds/complex/example_complex.json</code>. The sound's pitch is lowered to 0.6 of its original value. The <code>stream</code> parameter is also set to true.

There are many more parameters that can give greater control on how sounds are played. However, this is left as an exercise to the reader to try and construct with the [https://minecraft.gamepedia.com/Sounds.json wiki].

== Creating <code>SoundEvent</code>s ==

A <code>sounds.json</code> left in its current state would only be defined in-game. There is currently no way to reference the sound within a mod. To do this, we utilize the <code>SoundEvent</code> class. Each <code>SoundEvent</code> class holds a <code>ResourceLocation</code> to reference a sound pointer defined in the <code>sounds.json</code> file. The <code>sounds.json</code> file used is determined by the namespace or the resource location passed into the class.

For example, to reference <code>example_complex.ogg</code>, you would store the reference name (e.g. <code>example_sound_complex</code>) within a <code>new SoundEvent(new ResourceLocation("examplemod", "example_sound_complex"))</code>. This will locate <code>assets/examplemod/sounds.json</code> and try to find an <code>example_sound_complex</code> object nested within it.

<code>SoundEvent</code>s must be [[Registration/1.16|registered]] to be referenced in code.

== Playing Sounds ==

Vanilla has lots of methods for playing sounds that can be used in different scenarios.

=== <code>World</code> ===

# <code><nowiki>playSound(PlayerEntity, BlockPos, SoundEvent, SoundCategory, volume, pitch)</nowiki></code>
#*Simply forwards to overload (2), adding 0.5 to each coordinate of the BlockPos given.
# <code><nowiki>playSound(PlayerEntity, double x, double y, double z, SoundEvent, SoundCategory, volume, pitch)</nowiki></code>
#* <code>Client Behavior</code>: If the passed in player is the client player, plays the sound event to the client player.
#* <code>Server Behavior</code>: Plays the sound event to everyone nearby except the passed in player. Player can be <code>null</code>.
#* <code>Usage</code>: The correspondence between the behaviors implies that these two methods are to be called from some player-initiated code that will be run on both logical sides at the same time - the logical client handles playing it to the user and the logical server handles everyone else hearing it without re-playing it to the original user. They can also be used to play any sound in general at any position server-side by calling it on the logical server and passing in a <code>null</code> player, thus letting everyone hear it.
# <code><nowiki>playSound(double x, double y, double z, SoundEvent, SoundCategory, volume, pitch, distanceDelay)</nowiki></code>
#* <code>Client Behavior</code>: Just plays the sound event in the client world. If distanceDelay is true, then delays the sound based on how far it is from the player.
#* <code>Server Behavior</code>: Does nothing.
#* <code>Usage</code>: This method only works client-side, and thus is useful for sounds sent in custom packets, or other client-only effect-type sounds. Used for thunder.

=== <code> ClientWorld </code> ===

# <code><nowiki>playSound(BlockPos, SoundEvent, SoundCategory, volume, pitch, distanceDelay)</nowiki></code>
#* Simply forwards to <code>World</code>‘s overload (3), adding 0.5 to each coordinate of the <code>BlockPos</code> given.

=== <code> Entity </code> ===

# <code><nowiki>playSound(SoundEvent, volume, pitch)</nowiki></code>
#* Forwards to <code>World</code>‘s overload (2), passing in <code>null</code> as the player.
#* <code>Client Behavior</code>: Does nothing.
#* <code>Server Behavior</code>: Plays the sound event to everyone at this entity’s position.
#* <code>Usage</code>: Emitting any sound from any non-player entity server-side.

=== <code> PlayerEntity</code> ===

# <code><nowiki>playSound(SoundEvent, volume, pitch)</nowiki></code> (overriding the one in <code>[[Sounds#Entity/1.16|Entity]]</code>)
#* Forwards to <code>World</code>‘s overload (2), passing in <code>this</code> as the player.
#* <code>Client Behavior</code>: Does nothing, see override in <code>[[Sounds#clientplayerentity/1.16|ClientPlayerEntity]]</code>.
#* <code>Server Behavior</code>: Plays the sound to everyone nearby <code>except</code> this player.
#* <code>Usage</code>: See <code>[[Sounds#clientplayerentity/1.16|ClientPlayerEntity]]</code>.

=== <code> ClientPlayerEntity</code> ===

# <code><nowiki>playSound(SoundEvent, volume, pitch)</nowiki></code> (overriding the one in <code>[[Sounds#playerentity/1.16|PlayerEntity]]</code>)
#* Forwards to <code>World</code>‘s overload (2), passing in <code>this</code> as the player.
#* <code>Client Behavior</code>: Just plays the Sound Event.
#* <code>Server Behavior</code>: Method is client-only.
#* <code>Usage</code>: Just like the ones in <code>World</code>, these two overrides in the player classes seem to be for code that runs together on both sides. The client handles playing the sound to the user, while the server handles everyone else hearing it without re-playing to the original user.

[[Category:Game Effects/1.16|Category:Game Effects]]

Sounds

2021-08-08T01:20:32Z

Curle: Add note about mono sounds and attenuation.

Although not essential, sounds bring a greater immersion into the Minecraft world. Their usages within and outside the development environment gives a bit more polish to an already existing mod from background music to a single block break.

== Creating a Sound ==

Sounds in Minecraft are comprised of two things: an audio file and a reference pointer to that audio file.

The reference pointer is known as <code>sounds.json</code> which should be created at <code><nowiki>assets/<modid>/sounds.json</nowiki></code>. This JSON defines resource names to point to the audio files added by a specific mod. The only thing necessary to define a sound is by creating an object, naming it, and then defining the location of the sound within a list.

By default, the only supported audio format is [https://xiph.org/vorbis/ Ogg Vorbis] represented by the extension <code>.ogg</code>. The file <code>namespace:path</code> when referenced in the JSON will be located within <code><nowiki>assets/<namespace>/sounds/<path>.ogg</nowiki></code>.

<syntaxhighlight lang="json">
{
"example_sound": {
"sounds": [ "examplemod:example_sound_file" ]
}
}
</syntaxhighlight>

Using the example above, it creates a sound called <code>example_sound</code> and references the file <code><nowiki>assets/<modid>/sounds/example_sound_file.ogg</nowiki></code>.

{{Tip/Danger | Due to [https://bugs.mojang.com/browse/MC-146721 the way OpenAL (Minecraft's sound engine) works], for your sound to have attenuation - that is, for it to get quieter as the player walks away, it absolutely MUST be mono (have one audio channel).

Stereo sounds are always played at the '''player's''' location, making them ideal for ambient sounds and background music.

}}

Instead of being constructed as a list of strings, each entry could also be an object which allows a greater control over what and how it is played.

Here are some variables that could be defined:
{| class="wikitable sortable" border=1
!Parameter !!Description
|-
| name || Sets the path to the sound file excluding the <code>.ogg</code> extension.
|-
| stream || Determines whether the sound should be streamed from the file. When true, it reduces the amount of lag from loading a large file; however, it only allows four instances of the sound to be played at once.
|-
| volume || A value between 0 and 1 to determine the volume of the sound played.
|-
|}

<syntaxhighlight lang="json">
{
"example_sound": {
"sounds": [ "examplemod:example_sound_file" ]
},
"example_sound_complex": {
"sounds":
[
{
"name": "examplemod:complex/example_complex",
"pitch": 0.6,
"stream": true
}
]
}
}
</syntaxhighlight>

Now there is a new sound within our JSON called <code>example_sound_complex</code>. This points to the audio file at <code>assets/examplemod/sounds/complex/example_complex.json</code>. The sound's pitch is lowered to 0.6 of its original value. The <code>stream</code> parameter is also set to true.

There are many more parameters that can give greater control on how sounds are played. However, this is left as an exercise to the reader to try and construct with the [https://minecraft.gamepedia.com/Sounds.json wiki].

== Creating <code>SoundEvent</code>s ==

A <code>sounds.json</code> left in its current state would only be defined in-game. There is currently no way to reference the sound within a mod. To do this, we utilize the <code>SoundEvent</code> class. Each <code>SoundEvent</code> class holds a <code>ResourceLocation</code> to reference a sound pointer defined in the <code>sounds.json</code> file. The <code>sounds.json</code> file used is determined by the namespace or the resource location passed into the class.

For example, to reference <code>example_complex.ogg</code>, you would store the reference name (e.g. <code>example_sound_complex</code>) within a <code>new SoundEvent(new ResourceLocation("examplemod", "example_sound_complex"))</code>. This will locate <code>assets/examplemod/sounds.json</code> and try to find an <code>example_sound_complex</code> object nested within it.

<code>SoundEvent</code>s must be [[Registration|registered]] to be referenced in code.

== Playing Sounds ==

Vanilla has lots of methods for playing sounds that can be used in different scenarios.

=== <code>Level</code> ===

# <code><nowiki>playSound(Player, BlockPos, SoundEvent, SoundCategory, volume, pitch)</nowiki></code>
#*Simply forwards to overload (2), adding 0.5 to each coordinate of the BlockPos given.
# <code><nowiki>playSound(Player, double x, double y, double z, SoundEvent, SoundCategory, volume, pitch)</nowiki></code>
#* <code>Client Behavior</code>: If the passed in player is the client player, plays the sound event to the client player.
#* <code>Server Behavior</code>: Plays the sound event to everyone nearby except the passed in player. Player can be <code>null</code>.
#* <code>Usage</code>: The correspondence between the behaviors implies that these two methods are to be called from some player-initiated code that will be run on both logical sides at the same time - the logical client handles playing it to the user and the logical server handles everyone else hearing it without re-playing it to the original user. They can also be used to play any sound in general at any position server-side by calling it on the logical server and passing in a <code>null</code> player, thus letting everyone hear it.
# <code><nowiki>playSound(double x, double y, double z, SoundEvent, SoundCategory, volume, pitch, distanceDelay)</nowiki></code>
#* <code>Client Behavior</code>: Just plays the sound event in the client level. If distanceDelay is true, then delays the sound based on how far it is from the player.
#* <code>Server Behavior</code>: Does nothing.
#* <code>Usage</code>: This method only works client-side, and thus is useful for sounds sent in custom packets, or other client-only effect-type sounds. Used for thunder.

=== <code>ClientLevel</code> ===

# <code><nowiki>playSound(BlockPos, SoundEvent, SoundCategory, volume, pitch, distanceDelay)</nowiki></code>
#* Simply forwards to <code>Level</code>‘s overload (3), adding 0.5 to each coordinate of the <code>BlockPos</code> given.

=== <code>Entity</code> ===

# <code><nowiki>playSound(SoundEvent, volume, pitch)</nowiki></code>
#* Forwards to <code>LEvel</code>‘s overload (2), passing in <code>null</code> as the player.
#* <code>Client Behavior</code>: Does nothing.
#* <code>Server Behavior</code>: Plays the sound event to everyone at this entity’s position.
#* <code>Usage</code>: Emitting any sound from any non-player entity server-side.

=== <code>Player</code> ===

# <code><nowiki>playSound(SoundEvent, volume, pitch)</nowiki></code> (overriding the one in <code>[[Sounds#Entity|Entity]]</code>)
#* Forwards to <code>Level</code>‘s overload (2), passing in <code>this</code> as the player.
#* <code>Client Behavior</code>: Does nothing, see override in <code>[[Sounds#localplayer|LocalPlayer]]</code>.
#* <code>Server Behavior</code>: Plays the sound to everyone nearby <code>except</code> this player.
#* <code>Usage</code>: See <code>[[Sounds#localplayer|LocalPlayer]]</code>.

=== <code>LocalPlayer</code> ===

# <code><nowiki>playSound(SoundEvent, volume, pitch)</nowiki></code> (overriding the one in <code>[[Sounds#player|Player]</code>)
#* Forwards to <code>Level</code>‘s overload (2), passing in <code>this</code> as the player.
#* <code>Client Behavior</code>: Just plays the Sound Event.
#* <code>Server Behavior</code>: Method is client-only.
#* <code>Usage</code>: Just like the ones in <code>Level</code>, these two overrides in the player classes seem to be for code that runs together on both sides. The client handles playing the sound to the user, while the server handles everyone else hearing it without re-playing to the original user.

[[Category:Game Effects]]

Dynamic Loot Modification

2021-07-30T13:57:30Z

Curle: Formatting adjust?

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

== Registering a Global Loot Modifier ==

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

Finally, the serializer for your operational class is [[Registration|registered]] as any other <code>ForgeRegistryEntry</code>.

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

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

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

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

== The serialized json ==

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

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

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

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

They are deserialized manually in the next section.}}

== The LootModifier Subclass ==

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

<syntaxhighlight lang="java">
private static class WheatSeedsConverterModifier extends LootModifier {
private final int numSeedsToConvert;
private final Item itemToCheck;
private final Item itemReward;
public WheatSeedsConverterModifier(ILootCondition[] conditionsIn, int numSeeds, Item itemCheck, Item reward) {
super(conditionsIn);
numSeedsToConvert = numSeeds;
itemToCheck = itemCheck;
itemReward = reward;
}

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

private static class Serializer extends GlobalLootModifierSerializer<WheatSeedsConverterModifier> {

@Override
public WheatSeedsConverterModifier read(ResourceLocation name, JsonObject object, ILootCondition[] conditionsIn) {
int numSeeds = JSONUtils.getInt(object, "numSeeds");
Item seed = ForgeRegistries.ITEMS.getValue(new ResourceLocation((JSONUtils.getString(object, "seedItem"))));
Item wheat = ForgeRegistries.ITEMS.getValue(new ResourceLocation(JSONUtils.getString(object, "replacement")));
return new WheatSeedsConverterModifier(conditionsIn, numSeeds, seed, wheat);
}
}
}
</syntaxhighlight>

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

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

Also take note of the <code>read</code> method in the serializer. The conditions are already deserialized for you and if you have no other data, simply <code>return new MyModifier(conditionsIn)</code>. However, the full <code>JsonObject</code> is available if needed.

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

Dynamic Loot Modification

2021-07-30T13:57:09Z

Curle: Formatting adjust?

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

== Registering a Global Loot Modifier ==

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

Finally, the serializer for your operational class is [[Registration|registered]] as any other <code>ForgeRegistryEntry</code>.

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

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

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

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

== The serialized json ==

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

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

{{Tip|<code>conditions</code> is the only object needed by the system specification, everything else is the mod maker's data.
<code>seedItem</code>, <code>numSeeds</code> and <code>replacement</code> are NOT standard elements of Global Loot Modifiers.
They are deserialized manually in the next section.}}

== The LootModifier Subclass ==

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

<syntaxhighlight lang="java">
private static class WheatSeedsConverterModifier extends LootModifier {
private final int numSeedsToConvert;
private final Item itemToCheck;
private final Item itemReward;
public WheatSeedsConverterModifier(ILootCondition[] conditionsIn, int numSeeds, Item itemCheck, Item reward) {
super(conditionsIn);
numSeedsToConvert = numSeeds;
itemToCheck = itemCheck;
itemReward = reward;
}

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

private static class Serializer extends GlobalLootModifierSerializer<WheatSeedsConverterModifier> {

@Override
public WheatSeedsConverterModifier read(ResourceLocation name, JsonObject object, ILootCondition[] conditionsIn) {
int numSeeds = JSONUtils.getInt(object, "numSeeds");
Item seed = ForgeRegistries.ITEMS.getValue(new ResourceLocation((JSONUtils.getString(object, "seedItem"))));
Item wheat = ForgeRegistries.ITEMS.getValue(new ResourceLocation(JSONUtils.getString(object, "replacement")));
return new WheatSeedsConverterModifier(conditionsIn, numSeeds, seed, wheat);
}
}
}
</syntaxhighlight>

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

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

Also take note of the <code>read</code> method in the serializer. The conditions are already deserialized for you and if you have no other data, simply <code>return new MyModifier(conditionsIn)</code>. However, the full <code>JsonObject</code> is available if needed.

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

Dynamic Loot Modification

2021-07-30T13:55:58Z

Curle: Move qualification into a tip box.

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

== Registering a Global Loot Modifier ==

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

Finally, the serializer for your operational class is [[Registration|registered]] as any other <code>ForgeRegistryEntry</code>.

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

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

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

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

== The serialized json ==

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

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

{{Tip|<code>conditions</code> is the only object needed by the system specification, everything else is the mod maker's data. <code>seedItem</code>, <code>numSeeds</code> and <code>replacement</code> are NOT standard elements of Global Loot Modifiers.}}

== The LootModifier Subclass ==

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

<syntaxhighlight lang="java">
private static class WheatSeedsConverterModifier extends LootModifier {
private final int numSeedsToConvert;
private final Item itemToCheck;
private final Item itemReward;
public WheatSeedsConverterModifier(ILootCondition[] conditionsIn, int numSeeds, Item itemCheck, Item reward) {
super(conditionsIn);
numSeedsToConvert = numSeeds;
itemToCheck = itemCheck;
itemReward = reward;
}

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

private static class Serializer extends GlobalLootModifierSerializer<WheatSeedsConverterModifier> {

@Override
public WheatSeedsConverterModifier read(ResourceLocation name, JsonObject object, ILootCondition[] conditionsIn) {
int numSeeds = JSONUtils.getInt(object, "numSeeds");
Item seed = ForgeRegistries.ITEMS.getValue(new ResourceLocation((JSONUtils.getString(object, "seedItem"))));
Item wheat = ForgeRegistries.ITEMS.getValue(new ResourceLocation(JSONUtils.getString(object, "replacement")));
return new WheatSeedsConverterModifier(conditionsIn, numSeeds, seed, wheat);
}
}
}
</syntaxhighlight>

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

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

Also take note of the <code>read</code> method in the serializer. The conditions are already deserialized for you and if you have no other data, simply <code>return new MyModifier(conditionsIn)</code>. However, the full <code>JsonObject</code> is available if needed.

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

Dynamic Loot Modification

2021-07-30T13:53:15Z

Curle: Qualify where seedItem, numSeeds and replacement come from.

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

== Registering a Global Loot Modifier ==

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

Finally, the serializer for your operational class is [[Registration|registered]] as any other <code>ForgeRegistryEntry</code>.

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

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

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

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

== The serialized json ==

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

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

Note that seedItem, numSeeds and replacement are NOT standard elements of Global Loot Modifiers. They are added by the creator of this json, and are parsed manually using the Serializer of the next section:

== The LootModifier Subclass ==

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

<syntaxhighlight lang="java">
private static class WheatSeedsConverterModifier extends LootModifier {
private final int numSeedsToConvert;
private final Item itemToCheck;
private final Item itemReward;
public WheatSeedsConverterModifier(ILootCondition[] conditionsIn, int numSeeds, Item itemCheck, Item reward) {
super(conditionsIn);
numSeedsToConvert = numSeeds;
itemToCheck = itemCheck;
itemReward = reward;
}

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

private static class Serializer extends GlobalLootModifierSerializer<WheatSeedsConverterModifier> {

@Override
public WheatSeedsConverterModifier read(ResourceLocation name, JsonObject object, ILootCondition[] conditionsIn) {
int numSeeds = JSONUtils.getInt(object, "numSeeds");
Item seed = ForgeRegistries.ITEMS.getValue(new ResourceLocation((JSONUtils.getString(object, "seedItem"))));
Item wheat = ForgeRegistries.ITEMS.getValue(new ResourceLocation(JSONUtils.getString(object, "replacement")));
return new WheatSeedsConverterModifier(conditionsIn, numSeeds, seed, wheat);
}
}
}
</syntaxhighlight>

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

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

Also take note of the <code>read</code> method in the serializer. The conditions are already deserialized for you and if you have no other data, simply <code>return new MyModifier(conditionsIn)</code>. However, the full <code>JsonObject</code> is available if needed.

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

Structures

2021-07-24T02:11:52Z

Curle: new page

https://github.com/TelepathicGrunt/StructureTutorialMod

File:Hammer150.png

2021-05-15T16:13:57Z

Curle:

MediaWiki:Common.css

2021-02-20T05:07:27Z

Curle: Make question text stand out on create account screen

/* CSS placed here will be applied to all skins */

/* Hides the Main Page's first header */
body.page-Main_Page h1.firstHeading,
body.page-Main_Page #siteSub {
display: none;
}

.htmlform-tip + .mw-htmlform-field-HTMLInfoField { color:red; }

Events/FMLCommonSetupEvent

2021-02-14T01:46:01Z

Curle: Create page.

This event is a parallel dispatch event - you must use <code>event.enqueueWork</code> to interact with the game state in any way.

CommonSetup is fired after all the [[Events/RegistryEvent]]s, but before the [[Events/FMLClientSetupEvent]] and [[Events/FMLDedicatedServerSetupEvent]]. This makes it useful for non-specific mod setup.

Register it any way you would normally register an event.

Events

2021-02-14T01:31:01Z

Curle: fix code tag

Events

2021-02-14T01:29:45Z

Curle: Rewrite article.

Getting Started

2021-02-07T20:16:29Z

Curle: Test Edit

'''Minecraft Forge''' is a modding framework, designed to allow different mods to load and work together to be compatible. Through the years, there has been many changes in the Forge tooling to make working with mods as seamless as possible. It is now easier than ever to start making your own mod.

== The Mod Development Kit ==
The '''Mod Development Kit''' or '''MDK''' is a downloadable archive that contains the basic skeleton for starting a new mod. It contains the following files and folders:

{{Tree list}}
* '''The Mod Development Kit'''
** <code>gradle/wrapper/</code> - The folder containing the [https://docs.gradle.org/current/userguide/gradle_wrapper.html Gradle wrapper]'', Forge uses Gradle '''4.10.3'''''
** <code>src</code> - The sources folder
*** <code>main</code> - The <code>main</code> source set
**** <code>java</code> - The java sources for the <code>main</code> source set
***** ...
**** <code>resources</code> - The resources for the <code>main</code> source set
***** <code>META-INF</code> - The folder for '''metadata inf'''ormation files<ref>[https://stackoverflow.com/a/6075320/14416954 StackOverflow answer]: ''... Basically, if it was stored in META-INF, it was Meta-data Information...''</ref>
****** <code>mods.toml</code> - The [[Proper Mod Structuring#The mods.toml file|<tt>mods.toml</tt> file]], where mods are declared
***** <code>pack.mcmeta</code> - File used by Minecraft to [[mc:Data Pack#pack.mcmeta|identify data and resource packs]]
** <code>.gitattributes</code> - Used by [[wikipedia:Git|Git]] for specifying attributes for files<ref>[https://git-scm.com/docs/gitattributes Official git documentation on <tt>.gitattributes</tt>]</ref>
** <code>.gitignore</code> - Used by Git for specifying intentionally untracked/ignored files<ref>[https://git-scm.com/docs/gitignore Official git documentation on <tt>.gitignore</tt>]</ref>
** <code>build.gradle</code> - The Gradle buildscript, which defines the project and tasks<ref>[https://docs.gradle.org/4.10.3/userguide/tutorial_using_tasks.html Gradle User Guide for 4.10.3: ''Build Script Basics'']</ref>
** <code>changelog.txt</code> - The Forge version changelog
** <code>CREDITS.txt</code> - Forge's credits/''thank you'' file
** <code>gradle.properties</code> - The Gradle properties file, for defining additional variables and options<ref>[https://docs.gradle.org/4.10.3/userguide/build_environment.html#sec:gradle_configuration_properties Gradle User Guide for 4.10.3: ''Build Environment § Gradle properties'']</ref>
** <code>gradlew</code> - The *nix shell file for executing the Gradle wrapper
** <code>gradlew.bat</code> - The Windows batch file for executing the Gradle wrapper
** <code>LICENSE.txt</code> - File containing the licensing information for Forge and libraries
** <code>README.txt</code> - Readme file with basic setup instructions
{{Tree list/end}}

== Basic MDK Setup ==
# Download the MDK from the [https://files.minecraftforge.net/ official Minecraft Forge download site] and extract the MDK into an empty folder.
# Open your IDE of choice, and import the project as a Gradle project.
#* For '''Eclipse''': <tt>File > Import > Gradle > Existing Gradle Project</tt>, select the folder for the <tt>Project root directory</tt>, click <tt>Finish</tt>
#* For '''IntelliJ IDEA''': <tt>File > Open</tt>, select and open the folder, select the <tt>build.gradle</tt> file, click <tt>OK</tt>, click <tt>Open as Project</tt>
# Wait for the setup process to complete and the Minecraft sources are decompiled.
# Generate the run configurations for your IDE using the appropriate Gradle task. <br>These tasks can be run on the command line using ''(Windows)'' <code>gradlew gen***Runs</code> or ''(*nix)'' <code>./gradlew gen***Runs</code>.
#* For ''Eclipse'': the task is <code>genEclipseRuns</code>; to run in the IDE directly, open the <tt>Gradle Tasks</tt> tab on the bottom panel, ''wait until the tasks have loaded'' then expand the folder, expand the <tt>fg_runs</tt> folder, then double-click <tt>genEclipseRuns</tt>.
#* For ''IntelliJ IDEA'': the task is <code>genIntellijRuns</code>; to run in the IDE directly, open the <tt>Gradle</tt> on the right, expand the project folder, double-click <tt>Tasks > fg_runs > genIntellijRuns</tt>.
#* For ''Visual Studio Code'': the task is <code>genVSCodeRuns</code>

{{Tip/Warning|Although there is a run generation task for Visual Studio Code, it is ''not'' officially supported by Forge. Using Visual Studio Code as an IDE for Forge mod development is not supported, and any broken functionality due to this must be solved by the user on their own.}}

== Customizing the MDK ==
The MDK provides default values for the buildscript and <tt>mods.toml</tt> file. These values should be replaced with your own mod's information.

All edits should be done below the <code>apply plugin: 'net.minecraftforge.gradle'</code> line. The lines above it are required for the Forge MDK to work correctly, and should not be modified without proper knowledge.
* All references to <code>examplemod</code> in the buildscript should be replaced with your modid.
** Use your IDE's find-and-replace function to quickly replace these values.
** Pick a unique and memorable modid. The modid must be between 2 and 64 characters, and must consist of lowercase letters, numbers, underscores (<code>_</code>) and hyphens (<code>-</code>). The recommendation is to avoid using acronyms and abbreviations.
* Change the <code>archivesBaseName</code> variable to your modid. This is used as the base name for the JAR file when you build your mod, and as the <tt>artifactId</tt> of your mod's [https://maven.apache.org/pom.html#Maven_Coordinates maven coordinates].
* Change the <code>group</code> to your [[Proper Mod Structuring#Packaging|unique root java package]]. This is used as the <tt>groupId</tt> of your mod's maven coordinates.
* In the <code>jar</code> task, change the values of the <code>Specification-Vendor</code> and <code>Implementation-Vendor</code> keys to your username/brand name or other form of identification.
* ''Optional suggestion: '' Change the <code>version</code> variable to have a 0 as the major version (ex. <code>'0.1'</code>. This is to follow [[Semantic Versioning#During Development|semantic versioning guidelines]] for versions in active development.

== Building and Testing ==
You can test your mod in the development environment using either your IDE's run configurations and built-in debugging utilities, or by running the <code>run*</code> task as defined by the buildscript's run configurations.

There are three default run configurations with the MDK:
* <code>runClient</code>, for starting the client.
* <code>runServer</code>, for starting the dedicated server. ''You will need to accept the EULA through the <tt>eula.txt</tt> after running the server for the first time.''
* <code>runData</code>, for starting the client in [[Datageneration|data generation]] mode.

{{Tip|Always test your mod in both the client and the dedicated server, even if you are making a one-sided mod. Mods should not crash when running on both sides, and one-sided mods should not crash if they run on the wrong side.}}

You can build your mod's final JAR using the <code>build</code> task. The resulting JAR will be located in the <code>build/libs</code> folder under your project directory.

[[Category:Getting Started]]

Toolchain

2021-01-19T02:09:09Z

Curle: SRG->Searge's Retro Guard

{{DISPLAYTITLE:Deobfuscation Process}}
{{Under construction}}

The Forge toolchain is designed to clean up, merge, deobfuscate, rename, patch and provide the Minecraft source code for the usage of modders, researchers, or just those curious about how the game works.

This serves as an explanation as to how the development environment sets up your code, and aims to help you troubleshoot in case something goes wrong.

== Overall process ==
When setting up the environment for the first time, a gradle refresh triggers three things:
# ForgeGradle downloads the MCPConfig zip for the file you're using, and triggers the SetupMCP task.
# After that, it processes the jar - applies access transformers, MCPCleanup and others
# Finally, it patches and finalises the code, ready for modder consumption.

== Needed knowledge ==
=== Obfuscation ===
'''Obfuscation''' is the process of renaming all of the fields, methods, and classes of the compiled code into unreadable, machine-generated names (such as <code>aaa</code>, <code>bC</code>), and removing package structures (this makes everything package-local and makes the obfuscated code smaller somewhat. This is commonly used by companies to prevent external entities from easily decompiling their released binaries/executables and retrieving their source code/intellectual property, though it does have size advantages.

Additionally, due to the way the Local Variable Table (LVT) of Java bytecode is stored, every function-local variable name is turned to ☃ (that's right, a snowman) in the compiled files. This makes immediate recompilation of the game literally and physically impossible, as every Java compiler currently available requires that local variables have unique names.

Minecraft is a commercial game, which means the source code is unavailable to all except the developers of Mojang. To prevent piracy and the copying of their intellectual property, Mojang applies this obfuscation process to the game before they release it. They use a tool called [https://www.guardsquare.com/en/products/proguard ProGuard], which is both an optimizer<ref>An optimizer is a program that removes redundant/unused instructions and compacts the code to be faster and smaller.</ref> and an obfuscator.

=== Problematic Naming ===
There are a few big problems with using these obfuscated names directly for modding.

# It is incredibly difficult to create mods using these obfuscated names. It requires immense patience to reverse-engineer the meanings behind each and every name, and to keep relating those names to what was already reverse-engineered. Although, tools do exist to make this process easier, such as IntelliJ IDEA plugins that provide naming hints automatically.
# Because the obfuscation process takes place after compilation (the obfuscator operates on the compiled classes), the obfuscated names are not handled by the compiler. Thus, obfuscated classes may contain member<ref>'''member''' refers to class fields and methods.</ref> names that are invalid in the Java source language, but valid in compiled bytecode (like ☃ discussed earlier); this means that the decompiled source of the game is not immediately recompilable.
# These obfuscated names are automatically generated by the obfuscator for each independent release. This means that the obfuscated names may change signficantly between any two versions, making it harder for mod developers to update mods between releases.

=== SRGification ===
Some background on what SRG is and how it works:

'''SRG''' stands for '''S'''earge's ''R'''etro ''G''uard; RetroGuard being an early attempt to reverse the ProGuard obfuscation, and Searge being co-author of the Mod Creator Pack, who created this process.
Each obfuscated class, method, and field is assigned a unique number by the [[Toolchain:MCPConfig|backend]], via a sequential counter. This unique number is called the '''SRG ID''' of that class/method/field (henceforth called member).

The SRG name of the member is then derived from its SRG ID, its type (function {given the prefix func_}, field {given the prefix field_}, parameter {given the prefix p_, or p_i if this is the parameter of a constructor}), and (optionally) the obfuscated name of the object at the time it was given its SRG name<ref>The SRG name for a given member is only created once, when it first appears in the code. Therefore, the SRG postfix may be different from the current obf name.</ref>. This inclusion of the SRG ID into the name guarantees that the SRG name for all members are unique, and is the reason the ID is generated.

The actual conversion of obf names to SRG names is done by a tool called [[Toolchain:SpecialSource|SpecialSource]]. More information on how it works can be found on that page.

== The Setup ==
The process can be broken up into 3 steps; MCPConfig, patch and provide.
The MCPConfig step is, understandably, the biggest and most prone to failure.
An explanation of MCPConfig itself, how it works, what it's for (but NOT how to use it) can be found [[Toolchain:MCPConfig|here]]. For the purpose of this guide, you need only know that its' goal is to get the game decompiled, and into a state where it can immediately be recompiled. Due to certain flaws in the rest of the toolchain, this means it needs to fix and patch the source code before passing it onto Forge.

In this way, MCPConfig can be thought of the vanilla side of the setup. It does not modify the game.

The following steps are all executed in order of appearance.

=== Download and parsing MCPConfig ===
The first thing that ForgeGradle does upon initialising a first-time setup, is starting the [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/SetupMCPTask.java#L91 SetupMCP] task.

This task then seeks to [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/DownloadMCPConfigTask.java#L78 download the MCPConfig.zip jar] for the version you're setting up.
Once it is acquired, it
[https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/util/MCPRuntime.java#L74 parses the steps contained within the config.json]. It does this by interpreting the file with the following rules:
* Every key, except for libraries, is interpreted as the name of a step.
* Steps are executed in order.
* The version value is interpreted as a maven coordinate of a file to download.
* If there is a repo value, it is used instead of the maven repositories defined in the buildscript, to retrieve the version.
* The args array is parsed, and {values} like this are interpreted as inputs, which can be substituted accordingly.
* Once the step is all parsed in, it is executed:
** java -jar <version> <args> <jvmArgs>

An example config.json can be found [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/config.json here].

It defines the steps:
* [[Toolchain:MCinjector|mcinjector]]
** version: de.oceanlabs.mcp:mcinjector:3.8.0:fatjar
** args: --in {input} --out {output} --log {log} --level=INFO --lvt=LVT --exc {exceptions} --acc {access} --ctr {constructors}
* [[Toolchain:ForgeFlower|fernflower]]
** version: net.minecraftforge:forgeflower:1.5.478.16
** args: -din=1 -rbr=1 -dgs=1 -asc=1 -rsy=1 -iec=1 -jvn=1 -isl=0 -iib=1 -log=TRACE -cfg {libraries} {input} {output}
** jvmargs: -Xmx4G
* [[Toolchain:Mergetool|merge]]
** version: net.minecraftforge:mergetool:1.1.1:fatjar
** args: --client {client} --server {server} --ann {version} --output {output} --inject false"
* [[Toolchain:MCInjector|rename]]
** version: net.md-5:SpecialSource:1.8.3:shaded
** args: --in-jar {input} --out-jar {output} --srg-in {mappings}
** repo: https://repo1.maven.org/maven2/

More information about each of these tools can be found at the link provided, as well as what each of these arguments do. A brief description is provided.

=== MCInjector ===
[https://github.com/ModCoderPack/MCInjector MCInjector] is the tool we use to apply various fixes to the code, while it is still in bytecode form. That meaning, it works on compiled code, not sourcecode. It does this because it's easier to rename LVT entries (from the snowman) to readable names while you can search for every other code path that references that specific entry; ergo renaming all accesses at once. This is impossible in sourcecode, where every name is identical and string matching is impossible.

It:
* Removes synthetic parameters from constructors
** In bytecode, inner classes have the outer class as their first constructor parameter, but Java source code does not.
* Handles adding annotations for parameters that have synthetic data
** In bytecode, these Nonnull (or whatever) annotations are attached to the parameters, not to the function that contains them.
* Adds constructors for inner classes
** These are removed by Proguard sometimes, as they are not required in the bytecode if the parent has a default constructor.
* Adds synthetic (invisible) constructors for classes without them

It also applies fixes for things like EXC;
* Renaming parameters inside constructors, such that subclasses retain the ID of their parent.
* Fixing access for select functions, where it is required for the proper recompilation.
* Applying proper typing to constructor parameters
* Applying proper external (LWJGL) exception data to functions and classes.

Note that it does NOT rename to SRG. LVT (Local Variables) are renamed to lvt_<index>_<version><ref>Index means: the place where this item was found. If it is the 4th entry in the table, it is index 3.</ref>

=== ForgeFlower ===
After the code has been cleaned up by MCInjector, to a state where it no longer conflicts with itself, it can be passed to the decompiler.

The decompiler used by ForgeGradle is a custom fork of [https://github.com/JetBrains/intellij-community/tree/master/plugins/java-decompiler/engine Jetbrains' FernFlower], called [https://github.com/MinecraftForge/ForgeFlower ForgeFlower].

It simply searches the jar for files, converts the bytecode into a reasonable best-guess interpretation.

As you can see by the repository, a lot of work has gone into tuning it for Minecraft's needs, but it is still a far way from perfect. This is why the patches are needed.

If you [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/patches/ look at the patches] for 1.16.4, they are mostly incredibly simple changes. Adding generics, making types more strict.

This is all stuff that should be done by the decompiler, and PRs are always welcome at the ForgeFlower repository for changes and fixes that would reduce the amount of MCPConfig patches required to get the game to compile.

For now, it is a necessity.

=== Mergetool ===
The game is split into two distributions; server and client.

Because the server contains no rendering code, and the client contains none of the server-specific code (like the UI), this means there are differences between what can run on one side or the other.

To get around this, we have a tool called Mergetool, which can search for the differences between two files (down to the function level) and merge them into one large (referred to as joined) jar file.

It is a simple program, but it works.

=== SpecialSource ===
SpecialSource is where SRG starts to come into play. It serves the role of our deobfuscator, performing deobfuscation.

This process is done with the help of a '''deobfusation map''', a file generated by the original obfuscator (in this case, ProGuard) that contains a map of the obfuscated names to original, non-obfuscated names. This is commonly used on debofuscating stack traces outputted by an obfuscated program, for debugging purposes.<ref name="retrace"/>

We have three sets of deobfuscation maps available to us; the obf->SRG mappings distributed with the MCPConfig system, the Yarn intermediary system, or the offical mappings.<ref name="mojmappings"/>.

To rectify this problem, Forge has it's own process to create deobfuscation mappings for the game, using community-sourced human-readable names. This process is split into two separate parts: the '''SRG renaming''', and the '''MCP mapping'''. During the SetupMCP task, only the SRG renaming is performed.

SpecialSource itself operates on the source jar, as can be gathered by the name, and takes in a .tsrg file, like that [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/joined.tsrg contained in the MCPConfig zip].

It first renames classes, straight into MCP names.
Then, iterating the members of the class, it renames fields, methods, parameters and inner classes.

A recap from earlier:
* For classes -> <code>c_###_</code> (but it is immediately changed without the c_ being written to disk)
* For functions/methods -> <code>func_<ID>_<obf-name></code>
* For fields -> <code>field_<ID>_<obf-name></code>
* For function/method parameters -> <code>p_###_#_</code> for normal methods, <code>p_i###_#</code> for constructors; the second number is the index<ref>The index is the position of the argument. 0 on the left, 1 after that, 2 after that. Note that double and long arguments increase their index by two, rather than one.</ref> of the parameter.

For example, <code>func_71410_x</code> refers to a function with SRG ID 71410 and original obfuscated name of <code>x</code>.<ref>For version 1.16.2, <code>func_71410_x</code> refers to <code>Minecraft.getInstance()</code>, with real obfuscated name of <code>B</code>, but when the getInstance() function was first discovered in code, it was called x.</ref>

At this point, combined with the MCInjector step from earlier, we have a completely SRGed-up source jar.

=== Patches ===
Once we have the source code ready to go, the final step in the setup is to apply patches.
These are done trivially, using diffs and [https://github.com/CadixDev/gitpatcher gitpatcher].

=== Clean-up ===
Because of the way Proguard (or whatever obfuscator) and ForgeFlower mangle the source code, we need to take some steps to clean it up before we can proceed.

Assorted cleanup fixes are performed by the [https://github.com/MinecraftForge/MCPCleanup/ MCPCleanup] utility. These include:
* removing trailing whitespace at the end of lines
* removing extra newlines at the start and end of files
* removing extra newlines between every line of code (every set of concurrent newlines is replaced with a single)
* removing comments (// hello, /* hello */)
** the purpose of this step is unclear - it seems to be a preventative measure to ensure that Java changes do not interfere with the patch alignment in the future. Comments from the decompiler are still sometimes present in the source code.
* removing imports from the package a class is in
* removing comments that include the phrase <code>GL_[^*]+</code>
* replacing [[Toolchain:Magic Constants|magic constants]] with their code substitutions
* replacing <code>Character.valueOf(<character>)</code> with <code><character></code>
* replacing OpenGL integer constants with their code representation
* converting unicode character constants back into integer representation
* formatting the code with JAStyle

It also adjusts abstract functions in some way - after running the program on a jar, the parameters of a default abstract function get renamed, but it is unclear exactly what part of the source code does this.

== The Forge Side ==

After the MCPConfig/SetupMCP tasks are finished, ForgeGradle will print '''MCP Environment Setup is complete''' and wait for the user input.

The next step is to run the <code>gradlew setup</code> task, which does what it implies: Applying the Forge system to the processed vanilla code.

First, it applies ATs. After that, patches. Finally, MCP/Crowdsourced mappings are applied.

All in all, compared to the MCPConfig setup, this is a string of extremely basic tasks - mostly just one-line commands.

=== Applying Access Transformers ===

[[Access Transformers]] are a way of changing the visibility and finality of classes and class members. A full explanation of how it works, what the specification is, and what exactly they're used for, can be found at that page.

They are applied by passing the AT Config (nowadays called accesstransformer.cfg) into SpecialSource:
* <code>SpecialSource.jar --in-jar {input} --out-jar {output} --access-transformer {at.cfg}</code>

[https://github.com/MinecraftForge/MinecraftForge/blob/c3e84646db70f518dd0b37a8fcfc42cb814d7ba8/src/main/resources/META-INF/accesstransformer.cfg The current AT cfg can be found here.]

=== Applying Patches ===

The patches used for Forge itself are different from those used by MCPConfig, which means there are two separate patching stages performed.

As opposed to the minimal MCPConfig patching, with the goal to make the code recompileable, the Forge patching is done to apply the API and modloader to the code.

It does this in a very similar way, with the [https://github.com/CadixDev/gitpatcher gitpatcher] utility.

=== Applying Mappings ===
This step isn't strictly necessary, and it can be ommitted. However, working with exclusively SRG names is confusing for most people, so we have an extra step to apply human names to the SRG.

These renames can come from any source; as mentioned earlier, the MCP/Crowdsourced naming, the Yarn naming, or the Mojang Obf-map naming. ForgeGradle does not care, as long as there is a valid SRG->names map.

How ForgeGradle retrieves these mappings is covered in the [[ForgeGradle/mappings|appropriate article]].

The process of renaming itself is a simple regex substitution, performed by [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/common/java/net/minecraftforge/gradle/common/util/McpNames.java#L104 ForgeGradle itself]. This is made possible by the assured uniqueness of SRG names.

=== Post-processing ===

At this point, the files are ready to go. We have processed the Minecraft jar such that it can be recompiled, we have applied appropriate access transformers and the Forge patches, and optionally renamed every applicable SRG name to whatever chosen distribution of mappings.

There is not much left to do but package the code into a jar file, and place it into the gradle cache (so that this process does not occur every single time the project is opened). It calculates this name based on many factors, and this is covered in the [[ForgeGradle#naming|naming]] article.

== Some additional Infos ==
# You will never see c_XXX_ for classes, because the class names are picked beforehand
#* this is still crowdsourced, but before a new version is ready for Forge, all classes are given an <code>MCP</code> name
#* this <code>MCP</code> name stays constant throughout the game version it was picked for; it can change between versions, but it usually wont for already-named classes (except for misspells, typos, and misnames)
# If you look into the JAR, you won't see any packages for the obfuscated classes, but the deobfuscated classes do have the packages, this is because the same process that names the classes, also decides what package they belong to
# parameters have special names
#* there are two types of parameter names: <code>p_XXX_X_</code> and <code>p_iXXX_X_</code>
#* the one with the i means that it's a parameter for a constructor
#* the first set of numbers are the SRG ID of their parent method, and the second number denotes the index of the parameter
#* the index of the parameter is a bit more involved, but this will not be explained here
# If you look into the source, you'll see that parameters for lambdas don't have mapped names
#* This is because of a complication in how the lambdas are compiled/decompiled; it's a more advanced topic which involves how the compiler compiles lambdas which we will not explain here.

== See also ==
* [https://en.wikipedia.org/wiki/Obfuscation_(software) Obfuscation]

<references>
<ref name="retrace">For ProGuard users (such as Mojang), this is done using [https://www.guardsquare.com/en/products/proguard/manual/retrace ReTrace].</ref>
<ref name="mojmappings">Mojang recently released their deobfuscation mappings for Minecraft (colloquially named <code>mojmappings</code>), but the licensing for its uses is a bit ambiguous. [https://cpw.github.io/MinecraftMappingData See this post by cpw] for more information.</ref>
</references>

Main Page

2021-01-11T17:04:00Z

Curle: Rename toolchain article

__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.4'''. 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|Getting Started]]
* [[Proper_Mod_Structuring|Proper Mod Structuring]]
* [[Debug_Profiler|The Debug Profiler]]
* [[Update_Checker|Update Checker]]
</div>

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

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

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

<div class="box">
<h3>Blocks</h3>
* [[Making_Blocks|Creating Blocks]]
* [[Understanding_Blockstates|Understanding Blockstates]]
* [[Interacting_With_Blocks|Block Interactions]]
</div>

<div class="box">
<h3>Items</h3>
* [[Making_Items|Making Items]]
* [[Making_Tools|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|Using Tile Entity Renderers]]
</div>

<div class="box">
<h3>Models</h3>
* [[Introduction_to_Models|Introduction]]
* [[Model_JSONs|Model JSONs]]
* [[BlockState_JSONs|BlockState JSONs]]
* [[Coloring_textures_dynamically|Dynamically Colored Textures]]
* [[Item_Overrides|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|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|World Saved Data]]
</div>

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

<div class="box">
<h3>Others</h3>
* [[Dynamic_Loot_Modification|Dynamic Loot Modification]]
* [[Key_Bindings|Key Bindings]]
* [[Access_Transformers|Access Transformers]]
* [[Toolchain|ForgeGradle Setup]]
</div>

</div>

Toolchain

2021-01-11T17:00:18Z

Curle:

{{DISPLAYTITLE:Deobfuscation Process}}
{{Under construction}}

The Forge toolchain is designed to clean up, merge, deobfuscate, rename, patch and provide the Minecraft source code for the usage of modders, researchers, or just those curious about how the game works.

This serves as an explanation as to how the development environment sets up your code, and aims to help you troubleshoot in case something goes wrong.

== Overall process ==
When setting up the environment for the first time, a gradle refresh triggers three things:
# ForgeGradle downloads the MCPConfig zip for the file you're using, and triggers the SetupMCP task.
# After that, it processes the jar - applies access transformers, MCPCleanup and others
# Finally, it patches and finalises the code, ready for modder consumption.

== Needed knowledge ==
=== Obfuscation ===
'''Obfuscation''' is the process of renaming all of the fields, methods, and classes of the compiled code into unreadable, machine-generated names (such as <code>aaa</code>, <code>bC</code>), and removing package structures (this makes everything package-local and makes the obfuscated code smaller somewhat. This is commonly used by companies to prevent external entities from easily decompiling their released binaries/executables and retrieving their source code/intellectual property, though it does have size advantages.

Additionally, due to the way the Local Variable Table (LVT) of Java bytecode is stored, every function-local variable name is turned to ☃ (that's right, a snowman) in the compiled files. This makes immediate recompilation of the game literally and physically impossible, as every Java compiler currently available requires that local variables have unique names.

Minecraft is a commercial game, which means the source code is unavailable to all except the developers of Mojang. To prevent piracy and the copying of their intellectual property, Mojang applies this obfuscation process to the game before they release it. They use a tool called [https://www.guardsquare.com/en/products/proguard ProGuard], which is both an optimizer<ref>An optimizer is a program that removes redundant/unused instructions and compacts the code to be faster and smaller.</ref> and an obfuscator.

=== Problematic Naming ===
There are a few big problems with using these obfuscated names directly for modding.

# It is incredibly difficult to create mods using these obfuscated names. It requires immense patience to reverse-engineer the meanings behind each and every name, and to keep relating those names to what was already reverse-engineered. Although, tools do exist to make this process easier, such as IntelliJ IDEA plugins that provide naming hints automatically.
# Because the obfuscation process takes place after compilation (the obfuscator operates on the compiled classes), the obfuscated names are not handled by the compiler. Thus, obfuscated classes may contain member<ref>'''member''' refers to class fields and methods.</ref> names that are invalid in the Java source language, but valid in compiled bytecode (like ☃ discussed earlier); this means that the decompiled source of the game is not immediately recompilable.
# These obfuscated names are automatically generated by the obfuscator for each independent release. This means that the obfuscated names may change signficantly between any two versions, making it harder for mod developers to update mods between releases.

=== SRGification ===
Some background on what SRG is and how it works:

'''SRG''' stands for '''S'''ea'''RG'''e, co-author of the Mod Creator Pack, who created this process.
Each obfuscated class, method, and field is assigned a unique number by the [[Toolchain:MCPConfig|backend]], via a sequential counter. This unique number is called the '''SRG ID''' of that class/method/field (henceforth called member).

The SRG name of the member is then derived from its SRG ID, its type (function {given the prefix func_}, field {given the prefix field_}, parameter {given the prefix p_, or p_i if this is the parameter of a constructor}), and (optionally) the obfuscated name of the object at the time it was given its SRG name<ref>The SRG name for a given member is only created once, when it first appears in the code. Therefore, the SRG postfix may be different from the current obf name.</ref>. This inclusion of the SRG ID into the name guarantees that the SRG name for all members are unique, and is the reason the ID is generated.

The actual conversion of obf names to SRG names is done by a tool called [[Toolchain:SpecialSource|SpecialSource]]. More information on how it works can be found on that page.

== The Setup ==
The process can be broken up into 3 steps; MCPConfig, patch and provide.
The MCPConfig step is, understandably, the biggest and most prone to failure.
An explanation of MCPConfig itself, how it works, what it's for (but NOT how to use it) can be found [[Toolchain:MCPConfig|here]]. For the purpose of this guide, you need only know that its' goal is to get the game decompiled, and into a state where it can immediately be recompiled. Due to certain flaws in the rest of the toolchain, this means it needs to fix and patch the source code before passing it onto Forge.

In this way, MCPConfig can be thought of the vanilla side of the setup. It does not modify the game.

The following steps are all executed in order of appearance.

=== Download and parsing MCPConfig ===
The first thing that ForgeGradle does upon initialising a first-time setup, is starting the [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/SetupMCPTask.java#L91 SetupMCP] task.

This task then seeks to [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/DownloadMCPConfigTask.java#L78 download the MCPConfig.zip jar] for the version you're setting up.
Once it is acquired, it
[https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/util/MCPRuntime.java#L74 parses the steps contained within the config.json]. It does this by interpreting the file with the following rules:
* Every key, except for libraries, is interpreted as the name of a step.
* Steps are executed in order.
* The version value is interpreted as a maven coordinate of a file to download.
* If there is a repo value, it is used instead of the maven repositories defined in the buildscript, to retrieve the version.
* The args array is parsed, and {values} like this are interpreted as inputs, which can be substituted accordingly.
* Once the step is all parsed in, it is executed:
** java -jar <version> <args> <jvmArgs>

An example config.json can be found [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/config.json here].

It defines the steps:
* [[Toolchain:MCinjector|mcinjector]]
** version: de.oceanlabs.mcp:mcinjector:3.8.0:fatjar
** args: --in {input} --out {output} --log {log} --level=INFO --lvt=LVT --exc {exceptions} --acc {access} --ctr {constructors}
* [[Toolchain:ForgeFlower|fernflower]]
** version: net.minecraftforge:forgeflower:1.5.478.16
** args: -din=1 -rbr=1 -dgs=1 -asc=1 -rsy=1 -iec=1 -jvn=1 -isl=0 -iib=1 -log=TRACE -cfg {libraries} {input} {output}
** jvmargs: -Xmx4G
* [[Toolchain:Mergetool|merge]]
** version: net.minecraftforge:mergetool:1.1.1:fatjar
** args: --client {client} --server {server} --ann {version} --output {output} --inject false"
* [[Toolchain:MCInjector|rename]]
** version: net.md-5:SpecialSource:1.8.3:shaded
** args: --in-jar {input} --out-jar {output} --srg-in {mappings}
** repo: https://repo1.maven.org/maven2/

More information about each of these tools can be found at the link provided, as well as what each of these arguments do. A brief description is provided.

=== MCInjector ===
[https://github.com/ModCoderPack/MCInjector MCInjector] is the tool we use to apply various fixes to the code, while it is still in bytecode form. That meaning, it works on compiled code, not sourcecode. It does this because it's easier to rename LVT entries (from the snowman) to readable names while you can search for every other code path that references that specific entry; ergo renaming all accesses at once. This is impossible in sourcecode, where every name is identical and string matching is impossible.

It:
* Removes synthetic parameters from constructors
** In bytecode, inner classes have the outer class as their first constructor parameter, but Java source code does not.
* Handles adding annotations for parameters that have synthetic data
** In bytecode, these Nonnull (or whatever) annotations are attached to the parameters, not to the function that contains them.
* Adds constructors for inner classes
** These are removed by Proguard sometimes, as they are not required in the bytecode if the parent has a default constructor.
* Adds synthetic (invisible) constructors for classes without them

It also applies fixes for things like EXC;
* Renaming parameters inside constructors, such that subclasses retain the ID of their parent.
* Fixing access for select functions, where it is required for the proper recompilation.
* Applying proper typing to constructor parameters
* Applying proper external (LWJGL) exception data to functions and classes.

Note that it does NOT rename to SRG. LVT (Local Variables) are renamed to lvt_<index>_<version><ref>Index means: the place where this item was found. If it is the 4th entry in the table, it is index 3.</ref>

=== ForgeFlower ===
After the code has been cleaned up by MCInjector, to a state where it no longer conflicts with itself, it can be passed to the decompiler.

The decompiler used by ForgeGradle is a custom fork of [https://github.com/JetBrains/intellij-community/tree/master/plugins/java-decompiler/engine Jetbrains' FernFlower], called [https://github.com/MinecraftForge/ForgeFlower ForgeFlower].

It simply searches the jar for files, converts the bytecode into a reasonable best-guess interpretation.

As you can see by the repository, a lot of work has gone into tuning it for Minecraft's needs, but it is still a far way from perfect. This is why the patches are needed.

If you [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/patches/ look at the patches] for 1.16.4, they are mostly incredibly simple changes. Adding generics, making types more strict.

This is all stuff that should be done by the decompiler, and PRs are always welcome at the ForgeFlower repository for changes and fixes that would reduce the amount of MCPConfig patches required to get the game to compile.

For now, it is a necessity.

=== Mergetool ===
The game is split into two distributions; server and client.

Because the server contains no rendering code, and the client contains none of the server-specific code (like the UI), this means there are differences between what can run on one side or the other.

To get around this, we have a tool called Mergetool, which can search for the differences between two files (down to the function level) and merge them into one large (referred to as joined) jar file.

It is a simple program, but it works.

=== SpecialSource ===
SpecialSource is where SRG starts to come into play. It serves the role of our deobfuscator, performing deobfuscation.

This process is done with the help of a '''deobfusation map''', a file generated by the original obfuscator (in this case, ProGuard) that contains a map of the obfuscated names to original, non-obfuscated names. This is commonly used on debofuscating stack traces outputted by an obfuscated program, for debugging purposes.<ref name="retrace"/>

We have three sets of deobfuscation maps available to us; the obf->SRG mappings distributed with the MCPConfig system, the Yarn intermediary system, or the offical mappings.<ref name="mojmappings"/>.

To rectify this problem, Forge has it's own process to create deobfuscation mappings for the game, using community-sourced human-readable names. This process is split into two separate parts: the '''SRG renaming''', and the '''MCP mapping'''. During the SetupMCP task, only the SRG renaming is performed.

SpecialSource itself operates on the source jar, as can be gathered by the name, and takes in a .tsrg file, like that [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/joined.tsrg contained in the MCPConfig zip].

It first renames classes, straight into MCP names.
Then, iterating the members of the class, it renames fields, methods, parameters and inner classes.

A recap from earlier:
* For classes -> <code>c_###_</code> (but it is immediately changed without the c_ being written to disk)
* For functions/methods -> <code>func_<ID>_<obf-name></code>
* For fields -> <code>field_<ID>_<obf-name></code>
* For function/method parameters -> <code>p_###_#_</code> for normal methods, <code>p_i###_#</code> for constructors; the second number is the index<ref>The index is the position of the argument. 0 on the left, 1 after that, 2 after that. Note that double and long arguments increase their index by two, rather than one.</ref> of the parameter.

For example, <code>func_71410_x</code> refers to a function with SRG ID 71410 and original obfuscated name of <code>x</code>.<ref>For version 1.16.2, <code>func_71410_x</code> refers to <code>Minecraft.getInstance()</code>, with real obfuscated name of <code>B</code>, but when the getInstance() function was first discovered in code, it was called x.</ref>

At this point, combined with the MCInjector step from earlier, we have a completely SRGed-up source jar.

=== Patches ===
Once we have the source code ready to go, the final step in the setup is to apply patches.
These are done trivially, using diffs and [https://github.com/CadixDev/gitpatcher gitpatcher].

=== Clean-up ===
Because of the way Proguard (or whatever obfuscator) and ForgeFlower mangle the source code, we need to take some steps to clean it up before we can proceed.

Assorted cleanup fixes are performed by the [https://github.com/MinecraftForge/MCPCleanup/ MCPCleanup] utility. These include:
* removing trailing whitespace at the end of lines
* removing extra newlines at the start and end of files
* removing extra newlines between every line of code (every set of concurrent newlines is replaced with a single)
* removing comments (// hello, /* hello */)
** the purpose of this step is unclear - it seems to be a preventative measure to ensure that Java changes do not interfere with the patch alignment in the future. Comments from the decompiler are still sometimes present in the source code.
* removing imports from the package a class is in
* removing comments that include the phrase <code>GL_[^*]+</code>
* replacing [[Toolchain:Magic Constants|magic constants]] with their code substitutions
* replacing <code>Character.valueOf(<character>)</code> with <code><character></code>
* replacing OpenGL integer constants with their code representation
* converting unicode character constants back into integer representation
* formatting the code with JAStyle

It also adjusts abstract functions in some way - after running the program on a jar, the parameters of a default abstract function get renamed, but it is unclear exactly what part of the source code does this.

== The Forge Side ==

After the MCPConfig/SetupMCP tasks are finished, ForgeGradle will print '''MCP Environment Setup is complete''' and wait for the user input.

The next step is to run the <code>gradlew setup</code> task, which does what it implies: Applying the Forge system to the processed vanilla code.

First, it applies ATs. After that, patches. Finally, MCP/Crowdsourced mappings are applied.

All in all, compared to the MCPConfig setup, this is a string of extremely basic tasks - mostly just one-line commands.

=== Applying Access Transformers ===

[[Access Transformers]] are a way of changing the visibility and finality of classes and class members. A full explanation of how it works, what the specification is, and what exactly they're used for, can be found at that page.

They are applied by passing the AT Config (nowadays called accesstransformer.cfg) into SpecialSource:
* <code>SpecialSource.jar --in-jar {input} --out-jar {output} --access-transformer {at.cfg}</code>

[https://github.com/MinecraftForge/MinecraftForge/blob/c3e84646db70f518dd0b37a8fcfc42cb814d7ba8/src/main/resources/META-INF/accesstransformer.cfg The current AT cfg can be found here.]

=== Applying Patches ===

The patches used for Forge itself are different from those used by MCPConfig, which means there are two separate patching stages performed.

As opposed to the minimal MCPConfig patching, with the goal to make the code recompileable, the Forge patching is done to apply the API and modloader to the code.

It does this in a very similar way, with the [https://github.com/CadixDev/gitpatcher gitpatcher] utility.

=== Applying Mappings ===
This step isn't strictly necessary, and it can be ommitted. However, working with exclusively SRG names is confusing for most people, so we have an extra step to apply human names to the SRG.

These renames can come from any source; as mentioned earlier, the MCP/Crowdsourced naming, the Yarn naming, or the Mojang Obf-map naming. ForgeGradle does not care, as long as there is a valid SRG->names map.

How ForgeGradle retrieves these mappings is covered in the [[ForgeGradle/mappings|appropriate article]].

The process of renaming itself is a simple regex substitution, performed by [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/common/java/net/minecraftforge/gradle/common/util/McpNames.java#L104 ForgeGradle itself]. This is made possible by the assured uniqueness of SRG names.

=== Post-processing ===

At this point, the files are ready to go. We have processed the Minecraft jar such that it can be recompiled, we have applied appropriate access transformers and the Forge patches, and optionally renamed every applicable SRG name to whatever chosen distribution of mappings.

There is not much left to do but package the code into a jar file, and place it into the gradle cache (so that this process does not occur every single time the project is opened). It calculates this name based on many factors, and this is covered in the [[ForgeGradle#naming|naming]] article.

== Some additional Infos ==
# You will never see c_XXX_ for classes, because the class names are picked beforehand
#* this is still crowdsourced, but before a new version is ready for Forge, all classes are given an <code>MCP</code> name
#* this <code>MCP</code> name stays constant throughout the game version it was picked for; it can change between versions, but it usually wont for already-named classes (except for misspells, typos, and misnames)
# If you look into the JAR, you won't see any packages for the obfuscated classes, but the deobfuscated classes do have the packages, this is because the same process that names the classes, also decides what package they belong to
# parameters have special names
#* there are two types of parameter names: <code>p_XXX_X_</code> and <code>p_iXXX_X_</code>
#* the one with the i means that it's a parameter for a constructor
#* the first set of numbers are the SRG ID of their parent method, and the second number denotes the index of the parameter
#* the index of the parameter is a bit more involved, but this will not be explained here
# If you look into the source, you'll see that parameters for lambdas don't have mapped names
#* This is because of a complication in how the lambdas are compiled/decompiled; it's a more advanced topic which involves how the compiler compiles lambdas which we will not explain here.

== See also ==
* [https://en.wikipedia.org/wiki/Obfuscation_(software) Obfuscation]

<references>
<ref name="retrace">For ProGuard users (such as Mojang), this is done using [https://www.guardsquare.com/en/products/proguard/manual/retrace ReTrace].</ref>
<ref name="mojmappings">Mojang recently released their deobfuscation mappings for Minecraft (colloquially named <code>mojmappings</code>), but the licensing for its uses is a bit ambiguous. [https://cpw.github.io/MinecraftMappingData See this post by cpw] for more information.</ref>
</references>

Toolchain

2021-01-11T16:59:09Z

Curle: Forge side

{{DISPLAYTITLE:Deobfuscation Process}}
{{Under construction}}

The Forge toolchain is designed to clean up, merge, deobfuscate, rename, patch and provide the Minecraft source code for the usage of modders, researchers, or just those curious about how the game works.

This serves as an explanation as to how the development environment sets up your code, and aims to help you troubleshoot in case something goes wrong.

== Overall process ==
When setting up the environment for the first time, a gradle refresh triggers three things:
# ForgeGradle downloads the MCPConfig zip for the file you're using, and triggers the SetupMCP task.
# After that, it processes the jar - applies access transformers, MCPCleanup and others
# Finally, it patches and finalises the code, ready for modder consumption.

== Needed knowledge ==
=== Obfuscation ===
'''Obfuscation''' is the process of renaming all of the fields, methods, and classes of the compiled code into unreadable, machine-generated names (such as <code>aaa</code>, <code>bC</code>), and removing package structures (this makes everything package-local and makes the obfuscated code smaller somewhat. This is commonly used by companies to prevent external entities from easily decompiling their released binaries/executables and retrieving their source code/intellectual property, though it does have size advantages.

Additionally, due to the way the Local Variable Table (LVT) of Java bytecode is stored, every function-local variable name is turned to ☃ (that's right, a snowman) in the compiled files. This makes immediate recompilation of the game literally and physically impossible, as every Java compiler currently available requires that local variables have unique names.

Minecraft is a commercial game, which means the source code is unavailable to all except the developers of Mojang. To prevent piracy and the copying of their intellectual property, Mojang applies this obfuscation process to the game before they release it. They use a tool called [https://www.guardsquare.com/en/products/proguard ProGuard], which is both an optimizer<ref>An optimizer is a program that removes redundant/unused instructions and compacts the code to be faster and smaller.</ref> and an obfuscator.

=== Problematic Naming ===
There are a few big problems with using these obfuscated names directly for modding.

# It is incredibly difficult to create mods using these obfuscated names. It requires immense patience to reverse-engineer the meanings behind each and every name, and to keep relating those names to what was already reverse-engineered. Although, tools do exist to make this process easier, such as IntelliJ IDEA plugins that provide naming hints automatically.
# Because the obfuscation process takes place after compilation (the obfuscator operates on the compiled classes), the obfuscated names are not handled by the compiler. Thus, obfuscated classes may contain member<ref>'''member''' refers to class fields and methods.</ref> names that are invalid in the Java source language, but valid in compiled bytecode (like ☃ discussed earlier); this means that the decompiled source of the game is not immediately recompilable.
# These obfuscated names are automatically generated by the obfuscator for each independent release. This means that the obfuscated names may change signficantly between any two versions, making it harder for mod developers to update mods between releases.

=== SRGification ===
Some background on what SRG is and how it works:

'''SRG''' stands for '''S'''ea'''RG'''e, co-author of the Mod Creator Pack, who created this process.
Each obfuscated class, method, and field is assigned a unique number by the [[Toolchain:MCPConfig|backend]], via a sequential counter. This unique number is called the '''SRG ID''' of that class/method/field (henceforth called member).

The SRG name of the member is then derived from its SRG ID, its type (function {given the prefix func_}, field {given the prefix field_}, parameter {given the prefix p_, or p_i if this is the parameter of a constructor}), and (optionally) the obfuscated name of the object at the time it was given its SRG name<ref>The SRG name for a given member is only created once, when it first appears in the code. Therefore, the SRG postfix may be different from the current obf name.</ref>. This inclusion of the SRG ID into the name guarantees that the SRG name for all members are unique, and is the reason the ID is generated.

The actual conversion of obf names to SRG names is done by a tool called [[Toolchain:SpecialSource|SpecialSource]]. More information on how it works can be found on that page.

== The Setup ==
The process can be broken up into 3 steps; MCPConfig, patch and provide.
The MCPConfig step is, understandably, the biggest and most prone to failure.
An explanation of MCPConfig itself, how it works, what it's for (but NOT how to use it) can be found [[Toolchain:MCPConfig|here]]. For the purpose of this guide, you need only know that its' goal is to get the game decompiled, and into a state where it can immediately be recompiled. Due to certain flaws in the rest of the toolchain, this means it needs to fix and patch the source code before passing it onto Forge.

In this way, MCPConfig can be thought of the vanilla side of the setup. It does not modify the game.

The following steps are all executed in order of appearance.

=== Download and parsing MCPConfig ===
The first thing that ForgeGradle does upon initialising a first-time setup, is starting the [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/SetupMCPTask.java#L91 SetupMCP] task.

This task then seeks to [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/DownloadMCPConfigTask.java#L78 download the MCPConfig.zip jar] for the version you're setting up.
Once it is acquired, it
[https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/util/MCPRuntime.java#L74 parses the steps contained within the config.json]. It does this by interpreting the file with the following rules:
* Every key, except for libraries, is interpreted as the name of a step.
* Steps are executed in order.
* The version value is interpreted as a maven coordinate of a file to download.
* If there is a repo value, it is used instead of the maven repositories defined in the buildscript, to retrieve the version.
* The args array is parsed, and {values} like this are interpreted as inputs, which can be substituted accordingly.
* Once the step is all parsed in, it is executed:
** java -jar <version> <args> <jvmArgs>

An example config.json can be found [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/config.json here].

It defines the steps:
* [[Toolchain:MCinjector|mcinjector]]
** version: de.oceanlabs.mcp:mcinjector:3.8.0:fatjar
** args: --in {input} --out {output} --log {log} --level=INFO --lvt=LVT --exc {exceptions} --acc {access} --ctr {constructors}
* [[Toolchain:ForgeFlower|fernflower]]
** version: net.minecraftforge:forgeflower:1.5.478.16
** args: -din=1 -rbr=1 -dgs=1 -asc=1 -rsy=1 -iec=1 -jvn=1 -isl=0 -iib=1 -log=TRACE -cfg {libraries} {input} {output}
** jvmargs: -Xmx4G
* [[Toolchain:Mergetool|merge]]
** version: net.minecraftforge:mergetool:1.1.1:fatjar
** args: --client {client} --server {server} --ann {version} --output {output} --inject false"
* [[Toolchain:MCInjector|rename]]
** version: net.md-5:SpecialSource:1.8.3:shaded
** args: --in-jar {input} --out-jar {output} --srg-in {mappings}
** repo: https://repo1.maven.org/maven2/

More information about each of these tools can be found at the link provided, as well as what each of these arguments do. A brief description is provided.

=== MCInjector ===
[https://github.com/ModCoderPack/MCInjector MCInjector] is the tool we use to apply various fixes to the code, while it is still in bytecode form. That meaning, it works on compiled code, not sourcecode. It does this because it's easier to rename LVT entries (from the snowman) to readable names while you can search for every other code path that references that specific entry; ergo renaming all accesses at once. This is impossible in sourcecode, where every name is identical and string matching is impossible.

It:
* Removes synthetic parameters from constructors
** In bytecode, inner classes have the outer class as their first constructor parameter, but Java source code does not.
* Handles adding annotations for parameters that have synthetic data
** In bytecode, these Nonnull (or whatever) annotations are attached to the parameters, not to the function that contains them.
* Adds constructors for inner classes
** These are removed by Proguard sometimes, as they are not required in the bytecode if the parent has a default constructor.
* Adds synthetic (invisible) constructors for classes without them

It also applies fixes for things like EXC;
* Renaming parameters inside constructors, such that subclasses retain the ID of their parent.
* Fixing access for select functions, where it is required for the proper recompilation.
* Applying proper typing to constructor parameters
* Applying proper external (LWJGL) exception data to functions and classes.

Note that it does NOT rename to SRG. LVT (Local Variables) are renamed to lvt_<index>_<version><ref>Index means: the place where this item was found. If it is the 4th entry in the table, it is index 3.</ref>

=== ForgeFlower ===
After the code has been cleaned up by MCInjector, to a state where it no longer conflicts with itself, it can be passed to the decompiler.

The decompiler used by ForgeGradle is a custom fork of [https://github.com/JetBrains/intellij-community/tree/master/plugins/java-decompiler/engine Jetbrains' FernFlower], called [https://github.com/MinecraftForge/ForgeFlower ForgeFlower].

It simply searches the jar for files, converts the bytecode into a reasonable best-guess interpretation.

As you can see by the repository, a lot of work has gone into tuning it for Minecraft's needs, but it is still a far way from perfect. This is why the patches are needed.

If you [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/patches/ look at the patches] for 1.16.4, they are mostly incredibly simple changes. Adding generics, making types more strict.

This is all stuff that should be done by the decompiler, and PRs are always welcome at the ForgeFlower repository for changes and fixes that would reduce the amount of MCPConfig patches required to get the game to compile.

For now, it is a necessity.

=== Mergetool ===
The game is split into two distributions; server and client.

Because the server contains no rendering code, and the client contains none of the server-specific code (like the UI), this means there are differences between what can run on one side or the other.

To get around this, we have a tool called Mergetool, which can search for the differences between two files (down to the function level) and merge them into one large (referred to as joined) jar file.

It is a simple program, but it works.

=== SpecialSource ===
SpecialSource is where SRG starts to come into play. It serves the role of our deobfuscator, performing deobfuscation.

This process is done with the help of a '''deobfusation map''', a file generated by the original obfuscator (in this case, ProGuard) that contains a map of the obfuscated names to original, non-obfuscated names. This is commonly used on debofuscating stack traces outputted by an obfuscated program, for debugging purposes.<ref name="retrace"/>

We have three sets of deobfuscation maps available to us; the obf->SRG mappings distributed with the MCPConfig system, the Yarn intermediary system, or the offical mappings.<ref name="mojmappings"/>.

To rectify this problem, Forge has it's own process to create deobfuscation mappings for the game, using community-sourced human-readable names. This process is split into two separate parts: the '''SRG renaming''', and the '''MCP mapping'''. During the SetupMCP task, only the SRG renaming is performed.

SpecialSource itself operates on the source jar, as can be gathered by the name, and takes in a .tsrg file, like that [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/joined.tsrg contained in the MCPConfig zip].

It first renames classes, straight into MCP names.
Then, iterating the members of the class, it renames fields, methods, parameters and inner classes.

A recap from earlier:
* For classes -> <code>c_###_</code> (but it is immediately changed without the c_ being written to disk)
* For functions/methods -> <code>func_<ID>_<obf-name></code>
* For fields -> <code>field_<ID>_<obf-name></code>
* For function/method parameters -> <code>p_###_#_</code> for normal methods, <code>p_i###_#</code> for constructors; the second number is the index<ref>The index is the position of the argument. 0 on the left, 1 after that, 2 after that. Note that double and long arguments increase their index by two, rather than one.</ref> of the parameter.

For example, <code>func_71410_x</code> refers to a function with SRG ID 71410 and original obfuscated name of <code>x</code>.<ref>For version 1.16.2, <code>func_71410_x</code> refers to <code>Minecraft.getInstance()</code>, with real obfuscated name of <code>B</code>, but when the getInstance() function was first discovered in code, it was called x.</ref>

At this point, combined with the MCInjector step from earlier, we have a completely SRGed-up source jar.

=== Patches ===
Once we have the source code ready to go, the final step in the setup is to apply patches.
These are done trivially, using diffs and [https://github.com/CadixDev/gitpatcher gitpatcher].

=== Clean-up ===
Because of the way Proguard (or whatever obfuscator) and ForgeFlower mangle the source code, we need to take some steps to clean it up before we can proceed.

Assorted cleanup fixes are performed by the [https://github.com/MinecraftForge/MCPCleanup/ MCPCleanup] utility. These include:
* removing trailing whitespace at the end of lines
* removing extra newlines at the start and end of files
* removing extra newlines between every line of code (every set of concurrent newlines is replaced with a single)
* removing comments (// hello, /* hello */)
** the purpose of this step is unclear - it seems to be a preventative measure to ensure that Java changes do not interfere with the patch alignment in the future. Comments from the decompiler are still sometimes present in the source code.
* removing imports from the package a class is in
* removing comments that include the phrase <code>GL_[^*]+</code>
* replacing [[Toolchain:Magic Constants|magic constants]] with their code substitutions
* replacing <code>Character.valueOf(<character>)</code> with <code><character></code>
* replacing OpenGL integer constants with their code representation
* converting unicode character constants back into integer representation
* formatting the code with JAStyle

It also adjusts abstract functions in some way - after running the program on a jar, the parameters of a default abstract function get renamed, but it is unclear exactly what part of the source code does this.

== The Forge Side ==

After the MCPConfig/SetupMCP tasks are finished, ForgeGradle will print '''MCP Environment Setup is complete''' and wait for the user input.

The next step is to run the <code>gradlew setup</code> task, which does what it implies: Applying the Forge system to the processed vanilla code.

First, it applies ATs. After that, patches. Finally, MCP/Crowdsourced mappings are applied.

All in all, compared to the MCPConfig setup, this is a string of extremely basic tasks - mostly just one-line commands.

=== Applying Access Transformers ===

[[Access Transformers]] are a way of changing the visibility and finality of classes and class members. A full explanation of how it works, what the specification is, and what exactly they're used for, can be found at that page.

They are applied by passing the AT Config (nowadays called accesstransformer.cfg) into SpecialSource:
* <code>SpecialSource.jar --in-jar {input} --out-jar {output} --access-transformer {at.cfg}</code>

[https://github.com/MinecraftForge/MinecraftForge/blob/c3e84646db70f518dd0b37a8fcfc42cb814d7ba8/src/main/resources/META-INF/accesstransformer.cfg The current AT cfg can be found here.]

=== Applying Patches ===

The patches used for Forge itself are different from those used by MCPConfig, which means there are two separate patching stages performed.

As opposed to the minimal MCPConfig patching, with the goal to make the code recompileable, the Forge patching is done to apply the API and modloader to the code.

It does this in a very similar way, with the [https://github.com/CadixDev/gitpatcher gitpatcher] utility.

=== Applying Mappings ===
This step isn't strictly necessary, and it can be ommitted. However, working with exclusively SRG names is confusing for most people, so we have an extra step to apply human names to the SRG.

These renames can come from any source; as mentioned earlier, the MCP/Crowdsourced naming, the Yarn naming, or the Mojang Obf-map naming. ForgeGradle does not care, as long as there is a valid SRG->names map.

How ForgeGradle retrieves these mappings is covered in the [[ForgeGradle/mappings appropriate article]].

The process of renaming itself is a simple regex substitution, performed by [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/common/java/net/minecraftforge/gradle/common/util/McpNames.java#L104 ForgeGradle itself]. This is made possible by the assured uniqueness of SRG names.

=== Post-processing ===

At this point, the files are ready to go. We have processed the Minecraft jar such that it can be recompiled, we have applied appropriate access transformers and the Forge patches, and optionally renamed every applicable SRG name to whatever chosen distribution of mappings.

There is not much left to do but package the code into a jar file, and place it into the gradle cache (so that this process does not occur every single time the project is opened). It calculates this name based on many factors, and this is covered in the [[ForgeGradle#naming]] article.

== Some additional Infos ==
# You will never see c_XXX_ for classes, because the class names are picked beforehand
#* this is still crowdsourced, but before a new version is ready for Forge, all classes are given an <code>MCP</code> name
#* this <code>MCP</code> name stays constant throughout the game version it was picked for; it can change between versions, but it usually wont for already-named classes (except for misspells, typos, and misnames)
# If you look into the JAR, you won't see any packages for the obfuscated classes, but the deobfuscated classes do have the packages, this is because the same process that names the classes, also decides what package they belong to
# parameters have special names
#* there are two types of parameter names: <code>p_XXX_X_</code> and <code>p_iXXX_X_</code>
#* the one with the i means that it's a parameter for a constructor
#* the first set of numbers are the SRG ID of their parent method, and the second number denotes the index of the parameter
#* the index of the parameter is a bit more involved, but this will not be explained here
# If you look into the source, you'll see that parameters for lambdas don't have mapped names
#* This is because of a complication in how the lambdas are compiled/decompiled; it's a more advanced topic which involves how the compiler compiles lambdas which we will not explain here.

== See also ==
* [https://en.wikipedia.org/wiki/Obfuscation_(software) Obfuscation]

<references>
<ref name="retrace">For ProGuard users (such as Mojang), this is done using [https://www.guardsquare.com/en/products/proguard/manual/retrace ReTrace].</ref>
<ref name="mojmappings">Mojang recently released their deobfuscation mappings for Minecraft (colloquially named <code>mojmappings</code>), but the licensing for its uses is a bit ambiguous. [https://cpw.github.io/MinecraftMappingData See this post by cpw] for more information.</ref>
</references>

Toolchain:Magic Constants

2021-01-11T05:55:12Z

Curle: Curle moved page Toolchain:Magic Constants to Toolchain/Magic Constants

#REDIRECT [[Toolchain/Magic Constants]]

Toolchain/Magic Constants

2021-01-11T05:55:11Z

Curle: Curle moved page Toolchain:Magic Constants to Toolchain/Magic Constants

The [[Toolchain:MCPCleanup]] utility has many functions, one among them is to convert known constants into code representation for easier visualisation.

== Constants ==

The known substitutions are:

* <code>1.7976[0-9]*[Ee]+308[Dd]</code> -> <code>Double.MAX_VALUE</code>
* <code>3.1415[0-9]*[Dd]</code> -> <code>Math.PI</code>
* <code>3.1415[0-9]*[Ff]</code> -> <code>(float)Math.PI</code>
* <code>6.2831[0-9]*[Dd]</code> -> <code>(Math.PI * 2D)</code>
* <code>6.2831[0-9]*[Ff]</code> -> <code>((float)Math.PI * 2F)</code>
* <code>4.7123[0-9]*[Dd]</code> -> <code>(Math.PI * 3D / 2D)</code>
* <code>4.7123[0-9]*[Ff]</code> -> <code>((float)Math.PI * 3F / 2F)</code>
* <code>0.7853[0-9]*[Dd]</code> -> <code>(Math.PI / 4D)</code>
* <code>0.7853[0-9]*[Ff]</code> -> <code>((float)Math.PI / 4F)</code>
* <code>6.2831[0-9]*[Ff]</code> -> <code>((float)Math.PI * 2F)</code>
* <code>0.6283[0-9]*[Dd]</code> -> <code>(Math.PI / 5D)</code>
* <code>0.6283[0-9]*[Ff]</code> -> <code>((float)Math.PI / 5F)</code>
* <code>57.295[0-9]*[Dd]</code> -> <code>(180D / Math.PI)</code>
* <code>57.295[0-9]*[Ff]</code> -> <code>(180F / (float)Math.PI)</code>
* <code>0.6981[0-9]*[Dd]</code> -> <code>(Math.PI * 2D / 9D)</code>
* <code>0.6981[0-9]*[Ff]</code> -> <code>((float)Math.PI * 2F / 9F)</code>
* <code>0.3141[0-9]*[Dd]</code> -> <code>(Math.PI / 10D)</code>
* <code>0.3141[0-9]*[Ff]</code> -> <code>((float)Math.PI / 10F)</code>
* <code>1.2566[0-9]*[Dd]</code> -> <code>(Math.PI * 2D / 5D)</code>
* <code>1.2566[0-9]*[Ff]</code> -> <code>((float)Math.PI 2F / 5F)</code>
* <code>0.21991[0-9]*[Dd]</code> -> <code>(Math.PI * 7D / 100D)</code>
* <code>0.21991[0-9]*[Ff]</code> -> <code>((float)Math.PI * 7F / 100F)</code>
* <code>5.8119[0-9]*[Dd]</code> -> <code>(Math.PI * 185D / 100D)</code>
* <code>0.8119[0-9]*[Ff]</code> -> <code>((float)Math.PI * 185F / 100F)</code>

Toolchain/Magic Constants

2021-01-11T05:52:08Z

Curle: Create page

Toolchain

2021-01-11T05:34:50Z

Curle: Undo weirdness from visual editor

{{DISPLAYTITLE:Deobfuscation Process}}
{{Under construction}}

The Forge toolchain is designed to clean up, merge, deobfuscate, rename, patch and provide the Minecraft source code for the usage of modders, researchers, or just those curious about how the game works.

This serves as an explanation as to how the development environment sets up your code, and aims to help you troubleshoot in case something goes wrong.

== Overall process ==
When setting up the environment for the first time, a gradle refresh triggers three things:
# ForgeGradle downloads the MCPConfig zip for the file you're using, and triggers the SetupMCP task.
# After that, it processes the jar - applies access transformers, MCPCleanup and others
# Finally, it patches and finalises the code, ready for modder consumption.

== Needed knowledge ==
=== Obfuscation ===
'''Obfuscation''' is the process of renaming all of the fields, methods, and classes of the compiled code into unreadable, machine-generated names (such as <code>aaa</code>, <code>bC</code>), and removing package structures (this makes everything package-local and makes the obfuscated code smaller somewhat. This is commonly used by companies to prevent external entities from easily decompiling their released binaries/executables and retrieving their source code/intellectual property, though it does have size advantages.

Additionally, due to the way the Local Variable Table (LVT) of Java bytecode is stored, every function-local variable name is turned to ☃ (that's right, a snowman) in the compiled files. This makes immediate recompilation of the game literally and physically impossible, as every Java compiler currently available requires that local variables have unique names.

Minecraft is a commercial game, which means the source code is unavailable to all except the developers of Mojang. To prevent piracy and the copying of their intellectual property, Mojang applies this obfuscation process to the game before they release it. They use a tool called [https://www.guardsquare.com/en/products/proguard ProGuard], which is both an optimizer<ref>An optimizer is a program that removes redundant/unused instructions and compacts the code to be faster and smaller.</ref> and an obfuscator.

=== Problematic Naming ===
There are a few big problems with using these obfuscated names directly for modding.

# It is incredibly difficult to create mods using these obfuscated names. It requires immense patience to reverse-engineer the meanings behind each and every name, and to keep relating those names to what was already reverse-engineered. Although, tools do exist to make this process easier, such as IntelliJ IDEA plugins that provide naming hints automatically.
# Because the obfuscation process takes place after compilation (the obfuscator operates on the compiled classes), the obfuscated names are not handled by the compiler. Thus, obfuscated classes may contain member<ref>'''member''' refers to class fields and methods.</ref> names that are invalid in the Java source language, but valid in compiled bytecode (like ☃ discussed earlier); this means that the decompiled source of the game is not immediately recompilable.
# These obfuscated names are automatically generated by the obfuscator for each independent release. This means that the obfuscated names may change signficantly between any two versions, making it harder for mod developers to update mods between releases.

=== SRGification ===
Some background on what SRG is and how it works:

'''SRG''' stands for '''S'''ea'''RG'''e, co-author of the Mod Creator Pack, who created this process.
Each obfuscated class, method, and field is assigned a unique number by the [[Toolchain:MCPConfig|backend]], via a sequential counter. This unique number is called the '''SRG ID''' of that class/method/field (henceforth called member).

The SRG name of the member is then derived from its SRG ID, its type (function {given the prefix func_}, field {given the prefix field_}, parameter {given the prefix p_, or p_i if this is the parameter of a constructor}), and (optionally) the obfuscated name of the object at the time it was given its SRG name<ref>The SRG name for a given member is only created once, when it first appears in the code. Therefore, the SRG postfix may be different from the current obf name.</ref>. This inclusion of the SRG ID into the name guarantees that the SRG name for all members are unique, and is the reason the ID is generated.

The actual conversion of obf names to SRG names is done by a tool called [[Toolchain:SpecialSource|SpecialSource]]. More information on how it works can be found on that page.

== The Setup ==
The process can be broken up into 3 steps; MCPConfig, patch and provide.
The MCPConfig step is, understandably, the biggest and most prone to failure.
An explanation of MCPConfig itself, how it works, what it's for (but NOT how to use it) can be found [[Toolchain:MCPConfig|here]]. For the purpose of this guide, you need only know that its' goal is to get the game decompiled, and into a state where it can immediately be recompiled. Due to certain flaws in the rest of the toolchain, this means it needs to fix and patch the source code before passing it onto Forge.

In this way, MCPConfig can be thought of the vanilla side of the setup. It does not modify the game.

=== Download and parsing MCPConfig ===
The first thing that ForgeGradle does upon initialising a first-time setup, is starting the [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/SetupMCPTask.java#L91 SetupMCP] task.
This task then seeks to [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/DownloadMCPConfigTask.java#L78 download the MCPConfig.zip jar] for the version you're setting up.
Once it is acquired, it [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/util/MCPRuntime.java#L74 parses the steps contained within the config.json]. It does this by interpreting the file with the following rules:
* Every key, except for libraries, is interpreted as the name of a step.
* Steps are executed in order.
* The version value is interpreted as a maven coordinate of a file to download.
* If there is a repo value, it is used instead of the maven repositories defined in the buildscript, to retrieve the version.
* The args array is parsed, and {values} like this are interpreted as inputs, which can be substituted accordingly.
* Once the step is all parsed in, it is executed:
** java -jar <version> <args> <jvmArgs>

An example config.json can be found [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/config.json here].

It defines the steps:
* [[Toolchain:MCinjector|mcinjector]]
** version: de.oceanlabs.mcp:mcinjector:3.8.0:fatjar
** args: --in {input} --out {output} --log {log} --level=INFO --lvt=LVT --exc {exceptions} --acc {access} --ctr {constructors}
* [[Toolchain:ForgeFlower|fernflower]]
** version: net.minecraftforge:forgeflower:1.5.478.16
** args: -din=1 -rbr=1 -dgs=1 -asc=1 -rsy=1 -iec=1 -jvn=1 -isl=0 -iib=1 -log=TRACE -cfg {libraries} {input} {output}
** jvmargs: -Xmx4G
* [[Toolchain:Mergetool|merge]]
** version: net.minecraftforge:mergetool:1.1.1:fatjar
** args: --client {client} --server {server} --ann {version} --output {output} --inject false"
* [[Toolchain:MCInjector|rename]]
** version: net.md-5:SpecialSource:1.8.3:shaded
** args: --in-jar {input} --out-jar {output} --srg-in {mappings}
** repo: https://repo1.maven.org/maven2/

More information about each of these tools can be found at the link provided, as well as what each of these arguments do. A brief description is provided.

=== MCInjector ===
[https://github.com/ModCoderPack/MCInjector MCInjector] is the tool we use to apply various fixes to the code, while it is still in bytecode form. That meaning, it works on compiled code, not sourcecode. It does this because it's easier to rename LVT entries (from the snowman) to readable names while you can search for every other code path that references that specific entry; ergo renaming all accesses at once. This is impossible in sourcecode, where every name is identical and string matching is impossible.

It:
* Removes synthetic parameters from constructors
** In bytecode, inner classes have the outer class as their first constructor parameter, but Java source code does not.
* Handles adding annotations for parameters that have synthetic data
** In bytecode, these Nonnull (or whatever) annotations are attached to the parameters, not to the function that contains them.
* Adds constructors for inner classes
** These are removed by Proguard sometimes, as they are not required in the bytecode if the parent has a default constructor.
* Adds synthetic (invisible) constructors for classes without them

It also applies fixes for things like EXC;
* Renaming parameters inside constructors, such that subclasses retain the ID of their parent.
* Fixing access for select functions, where it is required for the proper recompilation.
* Applying proper typing to constructor parameters
* Applying proper external (LWJGL) exception data to functions and classes.

Note that it does NOT rename to SRG. LVT (Local Variables) are renamed to lvt_<index>_<version><ref>Index means: the place where this item was found. If it is the 4th entry in the table, it is index 3.</ref>

=== ForgeFlower ===
After the code has been cleaned up by MCInjector, to a state where it no longer conflicts with itself, it can be passed to the decompiler.

The decompiler used by ForgeGradle is a custom fork of [https://github.com/JetBrains/intellij-community/tree/master/plugins/java-decompiler/engine Jetbrains' FernFlower], called [https://github.com/MinecraftForge/ForgeFlower ForgeFlower].

It simply searches the jar for files, converts the bytecode into a reasonable best-guess interpretation.
As you can see by the repository, a lot of work has gone into tuning it for Minecraft's needs, but it is still a far way from perfect. This is why the patches are needed.

If you [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/patches/ look at the patches] for 1.16.4, they are mostly incredibly simple changes. Adding generics, making types more strict.

This is all stuff that should be done by the decompiler, and PRs are always welcome at the ForgeFlower repository for changes and fixes that would reduce the amount of MCPConfig patches required to get the game to compile.

For now, it is a necessity.

=== Mergetool ===
The game is split into two distributions; server and client.

Because the server contains no rendering code, and the client contains none of the server-specific code (like the UI), this means there are differences between what can run on one side or the other.

To get around this, we have a tool called Mergetool, which can search for the differences between two files (down to the function level) and merge them into one large (referred to as joined) jar file.

It is a simple program, but it works.

=== SpecialSource ===
SpecialSource is where SRG starts to come into play. It serves the role of our deobfuscator, performing deobfuscation.

This process is done with the help of a '''deobfusation map''', a file generated by the original obfuscator (in this case, ProGuard) that contains a map of the obfuscated names to original, non-obfuscated names. This is commonly used on debofuscating stack traces outputted by an obfuscated program, for debugging purposes.<ref name="retrace"/>

We have three sets of deobfuscation maps available to us; the obf->SRG mappings distributed with the MCPConfig system, the Yarn intermediary system, or the offical mappings.<ref name="mojmappings"/>.

To rectify this problem, Forge has it's own process to create deobfuscation mappings for the game, using community-sourced human-readable names. This process is split into two separate parts: the '''SRG renaming''', and the '''MCP mapping'''. During the SetupMCP task, only the SRG renaming is performed.

SpecialSource itself operates on the source jar, as can be gathered by the name, and takes in a .tsrg file, like that [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/joined.tsrg contained in the MCPConfig zip].

It first renames classes, straight into MCP names.
Then, iterating the members of the class, it renames fields, methods, parameters and inner classes.

A recap from earlier:
* For classes -> <code>c_###_</code> (but it is immediately changed without the c_ being written to disk)
* For functions/methods -> <code>func_<ID>_<obf-name></code>
* For fields -> <code>field_<ID>_<obf-name></code>
* For function/method parameters -> <code>p_###_#_</code> for normal methods, <code>p_i###_#</code> for constructors; the second number is the index<ref>The index is the position of the argument. 0 on the left, 1 after that, 2 after that. Note that double and long arguments increase their index by two, rather than one.</ref> of the parameter.

For example, <code>func_71410_x</code> refers to a function with SRG ID 71410 and original obfuscated name of <code>x</code>.<ref>For version 1.16.2, <code>func_71410_x</code> refers to <code>Minecraft.getInstance()</code>, with real obfuscated name of <code>B</code>, but when the getInstance() function was first discovered in code, it was called x.</ref>

At this point, combined with the MCInjector step from earlier, we have a completely SRGed-up source jar.

=== Patches ===
Once we have the source code ready to go, the final step in the setup is to apply patches.
These are done trivially, using diffs and [https://github.com/CadixDev/gitpatcher gitpatcher].

=== Clean-up ===
Because of the way Proguard (or whatever obfuscator) and ForgeFlower mangle the source code, we need to take some steps to clean it up before we can proceed.

Assorted cleanup fixes are performed by the [https://github.com/MinecraftForge/MCPCleanup/ MCPCleanup] utility. These include:
* removing trailing whitespace at the end of lines
* removing extra newlines at the start and end of files
* removing extra newlines between every line of code (every set of concurrent newlines is replaced with a single)
* removing comments (// hello, /* hello */)
** the purpose of this step is unclear - it seems to be a preventative measure to ensure that Java changes do not interfere with the patch alignment in the future. Comments from the decompiler are still sometimes present in the source code.
* removing imports from the package a class is in
* removing comments that include the phrase <code>GL_[^*]+</code>
* replacing [[Toolchain:Magic Constants|magic constants]] with their code substitutions
* replacing <code>Character.valueOf(<character>)</code> with <code><character></code>
* replacing OpenGL integer constants with their code representation
* converting unicode character constants back into integer representation
* formatting the code with JAStyle

It also adjusts abstract functions in some way - after running the program on a jar, the parameters of a default abstract function get renamed, but it is unclear exactly what part of the source code does this.

== Mappings ==
We don't need this step but coding with the <code>SRG</code> names is hard and not really fun.
So we need to take the <code>SRG</code> names and make them more user friendly, the user friendly names are community sourced names.
Since <code>SRG</code> names are uniquely identifiable, due to the unique ID, it literally does a search-and-replace on all the source code text to do that <code>SRG</code>-><code>MCP</code>(( <code>MCP</code> stands for ModCoderPack (or previously, Minecraft Coder Pack) which was the toolchain that did all of this before the advent of ForgeGradle)) application.

== Some additional Infos ==
# You will never see c_XXX_ for classes, because the class names are picked beforehand
#* this is still crowdsourced, but before a new version is ready for Forge, all classes are given an <code>MCP</code> name
#* this <code>MCP</code> name stays constant throughout the game version it was picked for; it can change between versions, but it usually wont for already-named classes (except for misspells, typos, and misnames)
# If you look into the JAR, you won't see any packages for the obfuscated classes, but the deobfuscated classes do have the packages, this is because the same process that names the classes, also decides what package they belong to
# parameters have special names
#* there are two types of parameter names: <code>p_XXX_X_</code> and <code>p_iXXX_X_</code>
#* the one with the i means that it's a parameter for a constructor
#* the first set of numbers are the SRG ID of their parent method, and the second number denotes the index of the parameter
#* the index of the parameter is a bit more involved, but this will not be explained here
# If you look into the source, you'll see that parameters for lambdas don't have mapped names
#* This is because of a complication in how the lambdas are compiled/decompiled; it's a more advanced topic which involves how the compiler compiles lambdas which we will not explain here.

== See also ==
* [https://en.wikipedia.org/wiki/Obfuscation_(software) Obfuscation]

<references>
<ref name="retrace">For ProGuard users (such as Mojang), this is done using [https://www.guardsquare.com/en/products/proguard/manual/retrace ReTrace].</ref>
<ref name="mojmappings">Mojang recently released their deobfuscation mappings for Minecraft (colloquially named <code>mojmappings</code>), but the licensing for its uses is a bit ambiguous. [https://cpw.github.io/MinecraftMappingData See this post by cpw] for more information.</ref>
</references>

Toolchain

2021-01-11T05:33:15Z

Curle: Fix link to "magic constants"

{{DISPLAYTITLE:Deobfuscation Process}}
{{Under construction}}

The Forge toolchain is designed to clean up, merge, deobfuscate, rename, patch and provide the Minecraft source code for the usage of modders, researchers, or just those curious about how the game works.

This serves as an explanation as to how the development environment sets up your code, and aims to help you troubleshoot in case something goes wrong.

== Overall process ==
When setting up the environment for the first time, a gradle refresh triggers three things:
# ForgeGradle downloads the MCPConfig zip for the file you're using, and triggers the SetupMCP task.
# After that, it processes the jar - applies access transformers, MCPCleanup and others
# Finally, it patches and finalises the code, ready for modder consumption.

== Needed knowledge ==
=== Obfuscation ===
'''Obfuscation''' is the process of renaming all of the fields, methods, and classes of the compiled code into unreadable, machine-generated names (such as <code>aaa</code>, <code>bC</code>), and removing package structures (this makes everything package-local and makes the obfuscated code smaller somewhat. This is commonly used by companies to prevent external entities from easily decompiling their released binaries/executables and retrieving their source code/intellectual property, though it does have size advantages.

Additionally, due to the way the Local Variable Table (LVT) of Java bytecode is stored, every function-local variable name is turned to ☃ (that's right, a snowman) in the compiled files. This makes immediate recompilation of the game literally and physically impossible, as every Java compiler currently available requires that local variables have unique names.

Minecraft is a commercial game, which means the source code is unavailable to all except the developers of Mojang. To prevent piracy and the copying of their intellectual property, Mojang applies this obfuscation process to the game before they release it. They use a tool called [https://www.guardsquare.com/en/products/proguard ProGuard], which is both an optimizer<ref>An optimizer is a program that removes redundant/unused instructions and compacts the code to be faster and smaller.</ref> and an obfuscator.

=== Problematic Naming ===
There are a few big problems with using these obfuscated names directly for modding.

# It is incredibly difficult to create mods using these obfuscated names. It requires immense patience to reverse-engineer the meanings behind each and every name, and to keep relating those names to what was already reverse-engineered. Although, tools do exist to make this process easier, such as IntelliJ IDEA plugins that provide naming hints automatically.
# Because the obfuscation process takes place after compilation (the obfuscator operates on the compiled classes), the obfuscated names are not handled by the compiler. Thus, obfuscated classes may contain member<ref>'''member''' refers to class fields and methods.</ref> names that are invalid in the Java source language, but valid in compiled bytecode (like ☃ discussed earlier); this means that the decompiled source of the game is not immediately recompilable.
# These obfuscated names are automatically generated by the obfuscator for each independent release. This means that the obfuscated names may change signficantly between any two versions, making it harder for mod developers to update mods between releases.

=== SRGification ===
Some background on what SRG is and how it works:

'''SRG''' stands for '''S'''ea'''RG'''e, co-author of the Mod Creator Pack, who created this process.
Each obfuscated class, method, and field is assigned a unique number by the [[Toolchain:MCPConfig|backend]], via a sequential counter. This unique number is called the '''SRG ID''' of that class/method/field (henceforth called member).

The SRG name of the member is then derived from its SRG ID, its type (function {given the prefix func_}, field {given the prefix field_}, parameter {given the prefix p_, or p_i if this is the parameter of a constructor}), and (optionally) the obfuscated name of the object at the time it was given its SRG name<ref>The SRG name for a given member is only created once, when it first appears in the code. Therefore, the SRG postfix may be different from the current obf name.</ref>. This inclusion of the SRG ID into the name guarantees that the SRG name for all members are unique, and is the reason the ID is generated.

The actual conversion of obf names to SRG names is done by a tool called [[Toolchain:SpecialSource|SpecialSource]]. More information on how it works can be found on that page.

== The Setup ==
The process can be broken up into 3 steps; MCPConfig, patch and provide.
The MCPConfig step is, understandably, the biggest and most prone to failure.
An explanation of MCPConfig itself, how it works, what it's for (but NOT how to use it) can be found [[Toolchain:MCPConfig|here]]. For the purpose of this guide, you need only know that its' goal is to get the game decompiled, and into a state where it can immediately be recompiled. Due to certain flaws in the rest of the toolchain, this means it needs to fix and patch the source code before passing it onto Forge.

In this way, MCPConfig can be thought of the vanilla side of the setup. It does not modify the game.

=== Download and parsing MCPConfig ===
The first thing that ForgeGradle does upon initialising a first-time setup, is starting the [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/SetupMCPTask.java#L91 SetupMCP] task.
This task then seeks to [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/DownloadMCPConfigTask.java#L78 download the MCPConfig.zip jar] for the version you're setting up.
Once it is acquired, it [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/util/MCPRuntime.java#L74 parses the steps contained within the config.json]. It does this by interpreting the file with the following rules:
* Every key, except for libraries, is interpreted as the name of a step.
* Steps are executed in order.
* The version value is interpreted as a maven coordinate of a file to download.
* If there is a repo value, it is used instead of the maven repositories defined in the buildscript, to retrieve the version.
* The args array is parsed, and {values} like this are interpreted as inputs, which can be substituted accordingly.
* Once the step is all parsed in, it is executed:
** java -jar <version> <args> <jvmArgs>

An example config.json can be found [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/config.json here].

It defines the steps:
* [[Toolchain:MCinjector|mcinjector]]
** version: de.oceanlabs.mcp:mcinjector:3.8.0:fatjar
** args: --in {input} --out {output} --log {log} --level=INFO --lvt=LVT --exc {exceptions} --acc {access} --ctr {constructors}
* [[Toolchain:ForgeFlower|fernflower]]
** version: net.minecraftforge:forgeflower:1.5.478.16
** args: -din=1 -rbr=1 -dgs=1 -asc=1 -rsy=1 -iec=1 -jvn=1 -isl=0 -iib=1 -log=TRACE -cfg {libraries} {input} {output}
** jvmargs: -Xmx4G
* [[Toolchain:Mergetool|merge]]
** version: net.minecraftforge:mergetool:1.1.1:fatjar
** args: --client {client} --server {server} --ann {version} --output {output} --inject false"
* [[Toolchain:MCInjector|rename]]
** version: net.md-5:SpecialSource:1.8.3:shaded
** args: --in-jar {input} --out-jar {output} --srg-in {mappings}
** repo: https://repo1.maven.org/maven2/

More information about each of these tools can be found at the link provided, as well as what each of these arguments do. A brief description is provided.

=== MCInjector ===
[https://github.com/ModCoderPack/MCInjector MCInjector] is the tool we use to apply various fixes to the code, while it is still in bytecode form. That meaning, it works on compiled code, not sourcecode. It does this because it's easier to rename LVT entries (from the snowman) to readable names while you can search for every other code path that references that specific entry; ergo renaming all accesses at once. This is impossible in sourcecode, where every name is identical and string matching is impossible.

It:
* Removes synthetic parameters from constructors
** In bytecode, inner classes have the outer class as their first constructor parameter, but Java source code does not.
* Handles adding annotations for parameters that have synthetic data
** In bytecode, these Nonnull (or whatever) annotations are attached to the parameters, not to the function that contains them.
* Adds constructors for inner classes
** These are removed by Proguard sometimes, as they are not required in the bytecode if the parent has a default constructor.
* Adds synthetic (invisible) constructors for classes without them

It also applies fixes for things like EXC;
* Renaming parameters inside constructors, such that subclasses retain the ID of their parent.
* Fixing access for select functions, where it is required for the proper recompilation.
* Applying proper typing to constructor parameters
* Applying proper external (LWJGL) exception data to functions and classes.

Note that it does NOT rename to SRG. LVT (Local Variables) are renamed to lvt_<index>_<version><ref>Index means: the place where this item was found. If it is the 4th entry in the table, it is index 3.</ref>

=== ForgeFlower ===
After the code has been cleaned up by MCInjector, to a state where it no longer conflicts with itself, it can be passed to the decompiler.

The decompiler used by ForgeGradle is a custom fork of [https://github.com/JetBrains/intellij-community/tree/master/plugins/java-decompiler/engine Jetbrains' FernFlower], called [https://github.com/MinecraftForge/ForgeFlower ForgeFlower].

It simply searches the jar for files, converts the bytecode into a reasonable best-guess interpretation.
As you can see by the repository, a lot of work has gone into tuning it for Minecraft's needs, but it is still a far way from perfect. This is why the patches are needed.

If you [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/patches/ look at the patches] for 1.16.4, they are mostly incredibly simple changes. Adding generics, making types more strict.

This is all stuff that should be done by the decompiler, and PRs are always welcome at the ForgeFlower repository for changes and fixes that would reduce the amount of MCPConfig patches required to get the game to compile.

For now, it is a necessity.

=== Mergetool ===
The game is split into two distributions; server and client.

Because the server contains no rendering code, and the client contains none of the server-specific code (like the UI), this means there are differences between what can run on one side or the other.

To get around this, we have a tool called Mergetool, which can search for the differences between two files (down to the function level) and merge them into one large (referred to as joined) jar file.

It is a simple program, but it works.

=== SpecialSource ===
SpecialSource is where SRG starts to come into play. It serves the role of our deobfuscator, performing deobfuscation.

This process is done with the help of a '''deobfusation map''', a file generated by the original obfuscator (in this case, ProGuard) that contains a map of the obfuscated names to original, non-obfuscated names. This is commonly used on debofuscating stack traces outputted by an obfuscated program, for debugging purposes.<ref name="retrace"/>

We have three sets of deobfuscation maps available to us; the obf->SRG mappings distributed with the MCPConfig system, the Yarn intermediary system, or the offical mappings.<ref name="mojmappings"/>.

To rectify this problem, Forge has it's own process to create deobfuscation mappings for the game, using community-sourced human-readable names. This process is split into two separate parts: the '''SRG renaming''', and the '''MCP mapping'''. During the SetupMCP task, only the SRG renaming is performed.

SpecialSource itself operates on the source jar, as can be gathered by the name, and takes in a .tsrg file, like that [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/joined.tsrg contained in the MCPConfig zip].

It first renames classes, straight into MCP names.
Then, iterating the members of the class, it renames fields, methods, parameters and inner classes.

A recap from earlier:
* For classes -> <code>c_###_</code> (but it is immediately changed without the c_ being written to disk)
* For functions/methods -> <code>func_<ID>_<obf-name></code>
* For fields -> <code>field_<ID>_<obf-name></code>
* For function/method parameters -> <code>p_###_#_</code> for normal methods, <code>p_i###_#</code> for constructors; the second number is the index<ref>The index is the position of the argument. 0 on the left, 1 after that, 2 after that. Note that double and long arguments increase their index by two, rather than one.</ref> of the parameter.

For example, <code>func_71410_x</code> refers to a function with SRG ID 71410 and original obfuscated name of <code>x</code>.<ref>For version 1.16.2, <code>func_71410_x</code> refers to <code>Minecraft.getInstance()</code>, with real obfuscated name of <code>B</code>, but when the getInstance() function was first discovered in code, it was called x.</ref>

At this point, combined with the MCInjector step from earlier, we have a completely SRGed-up source jar.

=== Patches ===
Once we have the source code ready to go, the final step in the setup is to apply patches.
These are done trivially, using diffs and [https://github.com/CadixDev/gitpatcher gitpatcher].

===Clean-up===
Because of the way Proguard (or whatever obfuscator) and ForgeFlower mangle the source code, we need to take some steps to clean it up before we can proceed.

Assorted cleanup fixes are performed by the [https://github.com/MinecraftForge/MCPCleanup/ MCPCleanup] utility. These include:
* removing trailing whitespace at the end of lines
* removing extra newlines at the start and end of files
* removing extra newlines between every line of code (every set of concurrent newlines is replaced with a single)
* removing comments (// hello, /* hello */)
** the purpose of this step is unclear - it seems to be a preventative measure to ensure that Java changes do not interfere with the patch alignment in the future. Comments from the decompiler are still sometimes present in the source code.
* removing imports from the package a class is in
* removing comments that include the phrase <code>GL_[^*]+</code>
* replacing [[Toolchain:Magic Constants|magic constants]] with their code substitutions
* replacing <code>Character.valueOf(<character>)</code> with <code><character></code>
* replacing OpenGL integer constants with their code representation
* converting unicode character constants back into integer representation
* formatting the code with JAStyle

It also adjusts abstract functions in some way - after running the program on a jar, the parameters of a default abstract function get renamed, but it is unclear exactly what part of the source code does this.

== Mappings ==
We don't need this step but coding with the <code>SRG</code> names is hard and not really fun.
So we need to take the <code>SRG</code> names and make them more user friendly, the user friendly names are community sourced names.
Since <code>SRG</code> names are uniquely identifiable, due to the unique ID, it literally does a search-and-replace on all the source code text to do that <code>SRG</code>-><code>MCP</code>(( <code>MCP</code> stands for ModCoderPack (or previously, Minecraft Coder Pack) which was the toolchain that did all of this before the advent of ForgeGradle)) application.

== Some additional Infos ==
# You will never see c_XXX_ for classes, because the class names are picked beforehand
#* this is still crowdsourced, but before a new version is ready for Forge, all classes are given an <code>MCP</code> name
#* this <code>MCP</code> name stays constant throughout the game version it was picked for; it can change between versions, but it usually wont for already-named classes (except for misspells, typos, and misnames)
# If you look into the JAR, you won't see any packages for the obfuscated classes, but the deobfuscated classes do have the packages, this is because the same process that names the classes, also decides what package they belong to
# parameters have special names
#* there are two types of parameter names: <code>p_XXX_X_</code> and <code>p_iXXX_X_</code>
#* the one with the i means that it's a parameter for a constructor
#* the first set of numbers are the SRG ID of their parent method, and the second number denotes the index of the parameter
#* the index of the parameter is a bit more involved, but this will not be explained here
# If you look into the source, you'll see that parameters for lambdas don't have mapped names
#* This is because of a complication in how the lambdas are compiled/decompiled; it's a more advanced topic which involves how the compiler compiles lambdas which we will not explain here.

== See also ==
* [https://en.wikipedia.org/wiki/Obfuscation_(software) Obfuscation]

<references>
<ref name="retrace">For ProGuard users (such as Mojang), this is done using [https://www.guardsquare.com/en/products/proguard/manual/retrace ReTrace].</ref>
<ref name="mojmappings">Mojang recently released their deobfuscation mappings for Minecraft (colloquially named <code>mojmappings</code>), but the licensing for its uses is a bit ambiguous. [https://cpw.github.io/MinecraftMappingData See this post by cpw] for more information.</ref>
</references>

Toolchain

2021-01-11T05:29:11Z

Curle: Major overhaul. Still have yet to get into the Forge side of things.

{{DISPLAYTITLE:Deobfuscation Process}}
{{Under construction}}

The Forge toolchain is designed to clean up, merge, deobfuscate, rename, patch and provide the Minecraft source code for the usage of modders, researchers, or just those curious about how the game works.

This serves as an explanation as to how the development environment sets up your code, and aims to help you troubleshoot in case something goes wrong.

== Overall process ==
When setting up the environment for the first time, a gradle refresh triggers three things:
# ForgeGradle downloads the MCPConfig zip for the file you're using, and triggers the SetupMCP task.
# After that, it processes the jar - applies access transformers, MCPCleanup and others
# Finally, it patches and finalises the code, ready for modder consumption.

== Needed knowledge ==
=== Obfuscation ===
'''Obfuscation''' is the process of renaming all of the fields, methods, and classes of the compiled code into unreadable, machine-generated names (such as <code>aaa</code>, <code>bC</code>), and removing package structures (this makes everything package-local and makes the obfuscated code smaller somewhat. This is commonly used by companies to prevent external entities from easily decompiling their released binaries/executables and retrieving their source code/intellectual property, though it does have size advantages.

Additionally, due to the way the Local Variable Table (LVT) of Java bytecode is stored, every function-local variable name is turned to ☃ (that's right, a snowman) in the compiled files. This makes immediate recompilation of the game literally and physically impossible, as every Java compiler currently available requires that local variables have unique names.

Minecraft is a commercial game, which means the source code is unavailable to all except the developers of Mojang. To prevent piracy and the copying of their intellectual property, Mojang applies this obfuscation process to the game before they release it. They use a tool called [https://www.guardsquare.com/en/products/proguard ProGuard], which is both an optimizer<ref>An optimizer is a program that removes redundant/unused instructions and compacts the code to be faster and smaller.</ref> and an obfuscator.

=== Problematic Naming ===
There are a few big problems with using these obfuscated names directly for modding.

# It is incredibly difficult to create mods using these obfuscated names. It requires immense patience to reverse-engineer the meanings behind each and every name, and to keep relating those names to what was already reverse-engineered. Although, tools do exist to make this process easier, such as IntelliJ IDEA plugins that provide naming hints automatically.
# Because the obfuscation process takes place after compilation (the obfuscator operates on the compiled classes), the obfuscated names are not handled by the compiler. Thus, obfuscated classes may contain member<ref>'''member''' refers to class fields and methods.</ref> names that are invalid in the Java source language, but valid in compiled bytecode (like ☃ discussed earlier); this means that the decompiled source of the game is not immediately recompilable.
# These obfuscated names are automatically generated by the obfuscator for each independent release. This means that the obfuscated names may change signficantly between any two versions, making it harder for mod developers to update mods between releases.

=== SRGification ===
Some background on what SRG is and how it works:

'''SRG''' stands for '''S'''ea'''RG'''e, co-author of the Mod Creator Pack, who created this process.
Each obfuscated class, method, and field is assigned a unique number by the [[Toolchain:MCPConfig|backend]], via a sequential counter. This unique number is called the '''SRG ID''' of that class/method/field (henceforth called member).

The SRG name of the member is then derived from its SRG ID, its type (function {given the prefix func_}, field {given the prefix field_}, parameter {given the prefix p_, or p_i if this is the parameter of a constructor}), and (optionally) the obfuscated name of the object at the time it was given its SRG name<ref>The SRG name for a given member is only created once, when it first appears in the code. Therefore, the SRG postfix may be different from the current obf name.</ref>. This inclusion of the SRG ID into the name guarantees that the SRG name for all members are unique, and is the reason the ID is generated.

The actual conversion of obf names to SRG names is done by a tool called [[Toolchain:SpecialSource|SpecialSource]]. More information on how it works can be found on that page.

== The Setup ==
The process can be broken up into 3 steps; MCPConfig, patch and provide.
The MCPConfig step is, understandably, the biggest and most prone to failure.
An explanation of MCPConfig itself, how it works, what it's for (but NOT how to use it) can be found [[Toolchain:MCPConfig|here]]. For the purpose of this guide, you need only know that its' goal is to get the game decompiled, and into a state where it can immediately be recompiled. Due to certain flaws in the rest of the toolchain, this means it needs to fix and patch the source code before passing it onto Forge.

In this way, MCPConfig can be thought of the vanilla side of the setup. It does not modify the game.

=== Download and parsing MCPConfig ===
The first thing that ForgeGradle does upon initialising a first-time setup, is starting the [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/SetupMCPTask.java#L91 SetupMCP] task.
This task then seeks to [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/task/DownloadMCPConfigTask.java#L78 download the MCPConfig.zip jar] for the version you're setting up.
Once it is acquired, it [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/mcp/java/net/minecraftforge/gradle/mcp/util/MCPRuntime.java#L74 parses the steps contained within the config.json]. It does this by interpreting the file with the following rules:
* Every key, except for libraries, is interpreted as the name of a step.
* Steps are executed in order.
* The version value is interpreted as a maven coordinate of a file to download.
* If there is a repo value, it is used instead of the maven repositories defined in the buildscript, to retrieve the version.
* The args array is parsed, and {values} like this are interpreted as inputs, which can be substituted accordingly.
* Once the step is all parsed in, it is executed:
** java -jar <version> <args> <jvmArgs>

An example config.json can be found [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/config.json here].

It defines the steps:
* [[Toolchain:MCinjector|mcinjector]]
** version: de.oceanlabs.mcp:mcinjector:3.8.0:fatjar
** args: --in {input} --out {output} --log {log} --level=INFO --lvt=LVT --exc {exceptions} --acc {access} --ctr {constructors}
* [[Toolchain:ForgeFlower|fernflower]]
** version: net.minecraftforge:forgeflower:1.5.478.16
** args: -din=1 -rbr=1 -dgs=1 -asc=1 -rsy=1 -iec=1 -jvn=1 -isl=0 -iib=1 -log=TRACE -cfg {libraries} {input} {output}
** jvmargs: -Xmx4G
* [[Toolchain:Mergetool|merge]]
** version: net.minecraftforge:mergetool:1.1.1:fatjar
** args: --client {client} --server {server} --ann {version} --output {output} --inject false"
* [[Toolchain:MCInjector|rename]]
** version: net.md-5:SpecialSource:1.8.3:shaded
** args: --in-jar {input} --out-jar {output} --srg-in {mappings}
** repo: https://repo1.maven.org/maven2/

More information about each of these tools can be found at the link provided, as well as what each of these arguments do. A brief description is provided.

=== MCInjector ===
[https://github.com/ModCoderPack/MCInjector MCInjector] is the tool we use to apply various fixes to the code, while it is still in bytecode form. That meaning, it works on compiled code, not sourcecode. It does this because it's easier to rename LVT entries (from the snowman) to readable names while you can search for every other code path that references that specific entry; ergo renaming all accesses at once. This is impossible in sourcecode, where every name is identical and string matching is impossible.

It:
* Removes synthetic parameters from constructors
** In bytecode, inner classes have the outer class as their first constructor parameter, but Java source code does not.
* Handles adding annotations for parameters that have synthetic data
** In bytecode, these Nonnull (or whatever) annotations are attached to the parameters, not to the function that contains them.
* Adds constructors for inner classes
** These are removed by Proguard sometimes, as they are not required in the bytecode if the parent has a default constructor.
* Adds synthetic (invisible) constructors for classes without them

It also applies fixes for things like EXC;
* Renaming parameters inside constructors, such that subclasses retain the ID of their parent.
* Fixing access for select functions, where it is required for the proper recompilation.
* Applying proper typing to constructor parameters
* Applying proper external (LWJGL) exception data to functions and classes.

Note that it does NOT rename to SRG. LVT (Local Variables) are renamed to lvt_<index>_<version><ref>Index means: the place where this item was found. If it is the 4th entry in the table, it is index 3.</ref>

=== ForgeFlower ===
After the code has been cleaned up by MCInjector, to a state where it no longer conflicts with itself, it can be passed to the decompiler.

The decompiler used by ForgeGradle is a custom fork of [https://github.com/JetBrains/intellij-community/tree/master/plugins/java-decompiler/engine Jetbrains' FernFlower], called [https://github.com/MinecraftForge/ForgeFlower ForgeFlower].

It simply searches the jar for files, converts the bytecode into a reasonable best-guess interpretation.
As you can see by the repository, a lot of work has gone into tuning it for Minecraft's needs, but it is still a far way from perfect. This is why the patches are needed.

If you [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/patches/ look at the patches] for 1.16.4, they are mostly incredibly simple changes. Adding generics, making types more strict.

This is all stuff that should be done by the decompiler, and PRs are always welcome at the ForgeFlower repository for changes and fixes that would reduce the amount of MCPConfig patches required to get the game to compile.

For now, it is a necessity.

=== Mergetool ===
The game is split into two distributions; server and client.

Because the server contains no rendering code, and the client contains none of the server-specific code (like the UI), this means there are differences between what can run on one side or the other.

To get around this, we have a tool called Mergetool, which can search for the differences between two files (down to the function level) and merge them into one large (referred to as joined) jar file.

It is a simple program, but it works.

=== SpecialSource ===
SpecialSource is where SRG starts to come into play. It serves the role of our deobfuscator, performing deobfuscation.

This process is done with the help of a '''deobfusation map''', a file generated by the original obfuscator (in this case, ProGuard) that contains a map of the obfuscated names to original, non-obfuscated names. This is commonly used on debofuscating stack traces outputted by an obfuscated program, for debugging purposes.<ref name="retrace"/>

We have three sets of deobfuscation maps available to us; the obf->SRG mappings distributed with the MCPConfig system, the Yarn intermediary system, or the offical mappings.<ref name="mojmappings"/>.

To rectify this problem, Forge has it's own process to create deobfuscation mappings for the game, using community-sourced human-readable names. This process is split into two separate parts: the '''SRG renaming''', and the '''MCP mapping'''. During the SetupMCP task, only the SRG renaming is performed.

SpecialSource itself operates on the source jar, as can be gathered by the name, and takes in a .tsrg file, like that [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/joined.tsrg contained in the MCPConfig zip].

It first renames classes, straight into MCP names.
Then, iterating the members of the class, it renames fields, methods, parameters and inner classes.

A recap from earlier:
* For classes -> <code>c_###_</code> (but it is immediately changed without the c_ being written to disk)
* For functions/methods -> <code>func_<ID>_<obf-name></code>
* For fields -> <code>field_<ID>_<obf-name></code>
* For function/method parameters -> <code>p_###_#_</code> for normal methods, <code>p_i###_#</code> for constructors; the second number is the index<ref>The index is the position of the argument. 0 on the left, 1 after that, 2 after that. Note that double and long arguments increase their index by two, rather than one.</ref> of the parameter.

For example, <code>func_71410_x</code> refers to a function with SRG ID 71410 and original obfuscated name of <code>x</code>.<ref>For version 1.16.2, <code>func_71410_x</code> refers to <code>Minecraft.getInstance()</code>, with real obfuscated name of <code>B</code>, but when the getInstance() function was first discovered in code, it was called x.</ref>

At this point, combined with the MCInjector step from earlier, we have a completely SRGed-up source jar.

=== Patches ===
Once we have the source code ready to go, the final step in the setup is to apply patches.
These are done trivially, using diffs and [https://github.com/CadixDev/gitpatcher gitpatcher].

=== Clean-up ===
Because of the way Proguard (or whatever obfuscator) and ForgeFlower mangle the source code, we need to take some steps to clean it up before we can proceed.

Assorted cleanup fixes are performed by the [https://github.com/MinecraftForge/MCPCleanup/ MCPCleanup] utility. These include:
* removing trailing whitespace at the end of lines
* removing extra newlines at the start and end of files
* removing extra newlines between every line of code (every set of concurrent newlines is replaced with a single)
* removing comments (// hello, /* hello */)
** the purpose of this step is unclear - it seems to be a preventative measure to ensure that Java changes do not interfere with the patch alignment in the future. Comments from the decompiler are still sometimes present in the source code.
* removing imports from the package a class is in
* removing comments that include the phrase <code>GL_[^*]+</code>
* replacing [Toolchain:Magic Constants|magic constants] with their code substitutions
* replacing <code>Character.valueOf(<character>)</code> with <code><character></code>
* replacing OpenGL integer constants with their code representation
* converting unicode character constants back into integer representation
* formatting the code with JAStyle

It also adjusts abstract functions in some way - after running the program on a jar, the parameters of a default abstract function get renamed, but it is unclear exactly what part of the source code does this.

== Mappings ==
We don't need this step but coding with the <code>SRG</code> names is hard and not really fun.
So we need to take the <code>SRG</code> names and make them more user friendly, the user friendly names are community sourced names.
Since <code>SRG</code> names are uniquely identifiable, due to the unique ID, it literally does a search-and-replace on all the source code text to do that <code>SRG</code>-><code>MCP</code>(( <code>MCP</code> stands for ModCoderPack (or previously, Minecraft Coder Pack) which was the toolchain that did all of this before the advent of ForgeGradle)) application.

== Some additional Infos ==
# You will never see c_XXX_ for classes, because the class names are picked beforehand
#* this is still crowdsourced, but before a new version is ready for Forge, all classes are given an <code>MCP</code> name
#* this <code>MCP</code> name stays constant throughout the game version it was picked for; it can change between versions, but it usually wont for already-named classes (except for misspells, typos, and misnames)
# If you look into the JAR, you won't see any packages for the obfuscated classes, but the deobfuscated classes do have the packages, this is because the same process that names the classes, also decides what package they belong to
# parameters have special names
#* there are two types of parameter names: <code>p_XXX_X_</code> and <code>p_iXXX_X_</code>
#* the one with the i means that it's a parameter for a constructor
#* the first set of numbers are the SRG ID of their parent method, and the second number denotes the index of the parameter
#* the index of the parameter is a bit more involved, but this will not be explained here
# If you look into the source, you'll see that parameters for lambdas don't have mapped names
#* This is because of a complication in how the lambdas are compiled/decompiled; it's a more advanced topic which involves how the compiler compiles lambdas which we will not explain here.

== See also ==
* [https://en.wikipedia.org/wiki/Obfuscation_(software) Obfuscation]

<references>
<ref name="retrace">For ProGuard users (such as Mojang), this is done using [https://www.guardsquare.com/en/products/proguard/manual/retrace ReTrace].</ref>
<ref name="mojmappings">Mojang recently released their deobfuscation mappings for Minecraft (colloquially named <code>mojmappings</code>), but the licensing for its uses is a bit ambiguous. [https://cpw.github.io/MinecraftMappingData See this post by cpw] for more information.</ref>
</references>

File:Exclamation.svg

2020-11-08T16:49:02Z

Curle: Exclamation mark for various templates

== Summary ==
Exclamation mark for various templates
== Licencing ==
{{subst:uwl}}

Template:Copy Guard

2020-11-08T16:47:25Z

Curle: Fix clr

<templatestyles src="Copy Guard/style.css"/>
<div class="mw-tpl-nocopy">
[[File:exclamation.svg|60px|class=mw-tpl-nocopy-exclamation|link=|alt=Important]]
<div>
<div class="mw-tpl-nocopy-title">This code will not compile.</div>
<div class="mw-tpl-nocopy-content">The content of this snippet is designed to show you how to use the relevant feature, but it will NOT compile if you copy-paste it. This is intentional.{{clr}}</div>
</div>
</div>

Template:Copy Guard

2020-11-08T16:46:23Z

Curle: Created page with "<templatestyles src="Copy Guard/style.css"/> <div class="mw-tpl-nocopy"> alt=Important <div> <div class="mw..."

Template:Copy Guard/style.css

2020-11-08T16:46:21Z

Curle: Created page with ".mw-tpl-nocopy { display: flex; align-items: center; width: 75%; margin: auto; border-radius: 0.2em; background: rgb(27, 32, 35); box-shadow: 0 0 0.2em #999999; overfl..."

.mw-tpl-nocopy {
display: flex;
align-items: center;
width: 75%;
margin: auto;
border-radius: 0.2em;
background: rgb(27, 32, 35);
box-shadow: 0 0 0.2em #999999;
overflow: auto;
}

.mw-tpl-nocopy-title {
color: #FFFFFF;
font-size: 120%;
font-weight: bold;
padding: 0.25em 1em;
}

.mw-tpl-nocopy-exclamation {
float: left;
opacity: 0.8;
margin: 1em;
}

.mw-tpl-nocopy-content {
padding: 0.5em 1em 0.5em 1em;
color: #FFFFFF;
}

Proper Mod Structuring

2020-11-04T23:34:01Z

Curle: revert attempted fix?

The structure of your mod is important in keeping your mod organized, for both your benefit and the benefit of anyone who wishses to make a feature for your mod. A disorganized mod structure may cause headaches when someone is trying to update it to a higher version, especially if they cannot modify the package structure, due to i.e. licensing.

{{Colored box|title=Tip|background-title-color=#633193|content=Note that this page is only a recommendation for your mod structure; you may structure your mod in any way you see fit.}}

== Packaging ==

Pick a unique package name for your mod. If you own a URL associated with your project, you can use it as your top level package. For example if you own "example.com", you may use <code>com.example</code> as your top level package.
The next level package is usually your mod's ID: if your mod ID is <code>examplemod</code>, your mod's package will be <code>com.example.examplemod</code>.

{{Colored box|title=Important|content=Do not use a domain for your top level package if you do not own that domain. It is perfectly acceptable to have your top level package be named with anything, such as your name/nickname, or the name of the mod (<code>me.exampledude.examplemod</code>).}}

=== Using Subpackages ===

Rather than clutter up a single class and package with everything, it is recommended you break your mod into subpackages.

A common strategy is to make a subpackage for grouping classes that have a common purpose. For example, your blocks classes can be under <code>blocks</code>, your entities classes can be under <code>entities</code>, your helper utilities can be under <code>helpers</code>, etc.

It is recommended to add a <code>client</code> subpackage under your main package, to isolate your [[Sides|client-only code]] from the rest, such as your GUIs and renderers.

By keeping your code in clean subpackages, you can grow your mod much more organically.

== Class Naming Schemes ==

A common class naming scheme allows easier deciphering of the purpose of the class, and makes it easier for someone developing for your mod to find specific classes.

The usual style is to use suffixes for your classes, for example:

* An <code>Item</code> called <code>PowerRing</code> would be in the <code>items</code> package, with a class name of <code>PowerRingItem</code>.
* A <code>Block</code> called <code>NotDirt</code> would be in a <code>blocks</code> package, with a class name of <code>NotDirtBlock</code>.
* A <code>TileEntity</code> for a block called <code>SuperChewer</code> would be in a <code>tile</code> or <code>tileentity</code> package, with a class name of <code>SuperChewerTile</code>.

== The Mod File ==

The main mod class - the class that is annotated with <code>@Mod</code> - is usually put into the main package of your mod, and not placed into a subpackage. This allows an easier time to access this, as your main mod class is the entrypoint of your mod.

The <code>@Mod</code> annotation indicates to the mod loader that this class is the entry point of your mod. Each <code>@Mod</code> annotation and their value should be paired with a mod id entry in your <code>mods.toml</code> file.

== The <code>mods.toml</code> file ==

The <code>mods.toml</code> file is read by the mod loader to determine what mods are packaged into your JAR file, and what information to display to the user in the Mods listing screen (accessible by pressing the "Mods" button on the main menu of the game).

The <code>mods.toml</code> file is formatted in [https://toml.io/en/ Tom's Obvious Minimal Language], or TOML for short. The example <code>mods.toml</code> file in the MDK provides comments explaining the contents of the file. It should be stored under the <code>META-INF</code> folder in your resources directory (<code>src/main/resources/META-INF/mods.toml</code>).

<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 <code>mods.toml</code> file</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="TOML">
modLoader="javafml"
# Forge for 1.16.3 is version 34
loaderVersion="[34,)"
license="All rights reserved"
issueTrackerURL="github.com/MinecraftForge/MinecraftForge/issues"
showAsResourcePack=false

[[mods]]
modId="examplemod"
version="1.0.0.0"
displayName="Example Mod"
updateJSONURL="minecraftforge.net/versions.json"
displayURL="minecraftforge.net"
logoFile="logo.png"
credits="I'd like to thank my mother and father."
authors="Author"
description='''
Lets you craft dirt into diamonds. This is a traditional mod that has existed for eons. It is ancient. The holy Notch created it. Jeb rainbowfied it. Dinnerbone made it upside down. Etc.
'''

[[dependencies.examplemod]]
modId="forge"
mandatory=true
versionRange="[34,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.16.3]"
ordering="NONE"
side="BOTH"
</syntaxhighlight>
</div>
</div>

The default Gradle configuration replaces <code>${file.jarVersion}</code> with the project version, but only within <code>mods.toml</code>, so you should use those instead of directly writing them out. Here is a table of attributes that may be given to a mod, where <code>mandatory</code> means there is no default and the absence of the property causes an error.

The <code>mods.toml</code> is split into three parts: the non-mod-specific properties, which are linked to the mod file; the mod properties, with a section for each mod; and dependency configurations, with a section for each mod's dependencies.

=== Non-Mod-Specific Properties ===

{| class="wikitable"
! Property !! Type !! Defaults
! Description
! Example
|-
| <code>modLoader</code> || string || '''mandatory'''
| The language loader for the mod. Used to specify an alternative language for the mod, such as Kotlin, if one exists. The Forge-provided Java loader is <code>javafml</code>.
| <code>"javafml"</code>
|-
| <code>loaderVersion</code> || string || '''mandatory'''
| The acceptable version range of the language loader, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. For the Forge-provided Java loader, the version is the major version of the Forge version.
| <code>"[34,)"</code>
|-
| <code>license</code> || string || '''mandatory'''
| The license for the mod(s) in this JAR. This string may be any valid string, but it is suggested to set the value to be the name of your license, and/or a link to that license.
| <code>"GNU GPL v3, https://www.gnu.org/licenses/gpl-3.0.en.html"</code>
|-
| <code>showAsResourcePack</code> || boolean || <code>false</code>
| Whether to display this mod's resources as a separate option in the resource pack menu. If disabled, the mod's resources will be rolled into the "Mod resources" pack.
| <code>true</code>
|-
| <code>properties</code> || table || <code>{}</code>
| A table of custom substitution properties. This is used by <code>StringSubstitutor</code> to replace values, using <code>${file.*}</code>.
| <code>{ "thingy" = 1 }</code>, used in <code>${file.thingy}</code>
|-
| <code>issueTrackerURL</code> || string || ''nothing''
| A URL for an issues tracker. <inline alert> This should never be a blank string, as that will cause an error. </inline>
| <code>"http://my.issue.tracker/"</code>
|}

=== Mod Properties ===

A mod entry is defined by a new section starting with a <code><nowiki>[[mods]]</nowiki></code> header (In TOML, the <code><nowiki>[[mods]]</nowiki></code> defines an [https://toml.io/en/v1.0.0-rc.2#array-of-tables array of tables]). All properties from that line until the next header will become the properties for that mod.

{| class="wikitable"
! Property !! Type !! Defaults
! Description
! Example
|-
| <code>modId</code> || string || '''mandatory'''
| The mod's identifier (modid). This must match the following regex: <code>^[a-z][a-z0-9_-]{1,63}$</code> (starts with a lowercase letter; other characters must be a lowercase letter, number, underscore or hyphen; must be 2-64 characters long).
| <code>"examplemod"</code>
|-
| <code>namespace</code> || string || value of <code>modId</code>
| An override namespace. <inline info> Currently, there is no use for this property </inline>
| <code>example</code>
|-
| <code>version</code> || string || <code>"1"</code>
| The version of the mod jar, used when the mod is a dependency of another mod, expressed as numbers seperated by dots (<code>.</code>), ideally conforming to [[Semantic_Versioning|Semantic Versioning]]. The default value in the MDK for this is <code>${file.jarVersion}</code>, which is replaced at runtime with the <code>Implementation-Version</code> found in the jar's manifest file.
| <code>"0.2.4-beta1"</code>
|-
| <code>displayName</code> || string || value of <code>modId</code>
| The display name of the mod, for use in the Mods listing screen
| <code>"Example Mod"</code>
|-
| <code>description</code> || string || <code>"MISSING DESCRIPTION"</code>
| The description of the mod, for use in the Mods listing screen. It's recommended to use a multiline string (surrounded by <code>'''<code>)
| <code>"Adds things and stuff. "</code>
|-
| <code>logoFile</code> || string || ''nothing''
| The path of the logo file image, for use in the Mods listing screen. The image must be in the root of the jar file, not in any subfolder thereof (e.g. the file is directly in <code>src/main/resources</code>)
| <code>"myAwesomeLogo.png"</code>
|-
| <code>logoBlur</code> || boolean || <code>true</code>
| Whether to do some blurring on the mod's logo in the Mods listing screen. Has no effect if <code>logoFile</code> is not set.
| <code>false</code>
|-
| <code>updateJSONURL</code> || string || ''nothing''
| The update JSON URL, used by the [Update_Checker update checker]. <inline alert> This should never be a blank string, as that will cause an error. </inline>
| <code>http://myurl.me/path/to/update.json</code>
|-
| <code>modproperties</code> || table || <code>{}</code>
| A table of custom mod properties; this is not used for Forge, but is mainly for use by mods.
| <code>{ "useThing" = true }</code>
|-
| <code>credits</code> || string || ''nothing''
| Credits and acknowledgements for the mod, for use in the Mods listing screen. Can be any string.
| <code>"This person and that guy"</code>
|-
| <code>authors</code> || string || ''nothing''
| Authors for the mod, for use in the Mods listing screen. Can be any string.
| <code>"ExampleDude"</code>
|-
| <code>displayURL</code> || string || ''nothing''
| A URL, displayed on the Mods listing screen. Can be any string.
| <code>http://example.com/</code>
|}

=== Dependency Configurations ===

Mods can define dependencies for their mods, which are checked by Forge before loading mods. This is used for e.g. ensuring your mod loads after another, or hard-crashing if a mod with a specified version does not exist.

These dependency configurations, like the mod properties, are defined by a new section starting with <code>[[dependencies.<modid>]]</code>, with <code><modid></code> being the mod id that has this dependency. All properties from that line until the next header will become the properties of that dependency configuration.

{|
! Property !! Type !! Defaults
! Description
! Example
|-
| <code>modId</code> || string || '''mandatory'''
| The mod id of the dependency.
| <code>examplelibrary</code>
|-
| <code>mandatory</code> || boolean || '''mandatory'''
| Whether to crash if this dependency is not met.
| <code>true</code>
|-
| <code>versionRange</code> || string || <code>""</code>
| The acceptable version range of the dependency, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. An empty string is an unbounded version range, which matches any version.
| <code>"[1.0,2.0)"</code>
|-
| <code>ordering</code> || string || <code>"NONE"</code>
| Defines if the mod must load before or after this dependency. The valid values are <code>BEFORE</code> (must load before), <code>AFTER</code> (must load after), and <code>NONE</code> (does not care about order).
| <code>"AFTER"</code>
|-
| <code>side</code> || string || <code>"BOTH"</code>
| Defines if this dependency needs only to be met on a specfic [[Sides|physical side]]. The valid values are <code>CLIENT</code> (present on the client), <code>SERVER</code> (present on the dedicated server), and <code>BOTH</code> (present on both sides).
| <code>"CLIENT"</code>
|}

{{Colored box|title=Important|content=When specifying dependency ordering between two or more mods, beware of cyclic order!: ex. if mod A must load before mod B, and mod B must load before mod A, the game will crash because of the circular cycle.}}

[[Category:Getting Started]]

Proper Mod Structuring

2020-11-04T23:02:41Z

Curle: attempt to fix highlight

The structure of your mod is important in keeping your mod organized, for both your benefit and the benefit of anyone who wishses to make a feature for your mod. A disorganized mod structure may cause headaches when someone is trying to update it to a higher version, especially if they cannot modify the package structure, due to i.e. licensing.

{{Colored box|title=Tip|background-title-color=#633193|content=Note that this page is only a recommendation for your mod structure; you may structure your mod in any way you see fit.}}

== Packaging ==

Pick a unique package name for your mod. If you own a URL associated with your project, you can use it as your top level package. For example if you own "example.com", you may use <code>com.example</code> as your top level package.
The next level package is usually your mod's ID: if your mod ID is <code>examplemod</code>, your mod's package will be <code>com.example.examplemod</code>.

{{Colored box|title=Important|content=Do not use a domain for your top level package if you do not own that domain. It is perfectly acceptable to have your top level package be named with anything, such as your name/nickname, or the name of the mod (<code>me.exampledude.examplemod</code>).}}

=== Using Subpackages ===

Rather than clutter up a single class and package with everything, it is recommended you break your mod into subpackages.

A common strategy is to make a subpackage for grouping classes that have a common purpose. For example, your blocks classes can be under <code>blocks</code>, your entities classes can be under <code>entities</code>, your helper utilities can be under <code>helpers</code>, etc.

It is recommended to add a <code>client</code> subpackage under your main package, to isolate your [[Sides|client-only code]] from the rest, such as your GUIs and renderers.

By keeping your code in clean subpackages, you can grow your mod much more organically.

== Class Naming Schemes ==

A common class naming scheme allows easier deciphering of the purpose of the class, and makes it easier for someone developing for your mod to find specific classes.

The usual style is to use suffixes for your classes, for example:

* An <code>Item</code> called <code>PowerRing</code> would be in the <code>items</code> package, with a class name of <code>PowerRingItem</code>.
* A <code>Block</code> called <code>NotDirt</code> would be in a <code>blocks</code> package, with a class name of <code>NotDirtBlock</code>.
* A <code>TileEntity</code> for a block called <code>SuperChewer</code> would be in a <code>tile</code> or <code>tileentity</code> package, with a class name of <code>SuperChewerTile</code>.

== The Mod File ==

The main mod class - the class that is annotated with <code>@Mod</code> - is usually put into the main package of your mod, and not placed into a subpackage. This allows an easier time to access this, as your main mod class is the entrypoint of your mod.

The <code>@Mod</code> annotation indicates to the mod loader that this class is the entry point of your mod. Each <code>@Mod</code> annotation and their value should be paired with a mod id entry in your <code>mods.toml</code> file.

== The <code>mods.toml</code> file ==

The <code>mods.toml</code> file is read by the mod loader to determine what mods are packaged into your JAR file, and what information to display to the user in the Mods listing screen (accessible by pressing the "Mods" button on the main menu of the game).

The <code>mods.toml</code> file is formatted in [https://toml.io/en/ Tom's Obvious Minimal Language], or TOML for short. The example <code>mods.toml</code> file in the MDK provides comments explaining the contents of the file. It should be stored under the <code>META-INF</code> folder in your resources directory (<code>src/main/resources/META-INF/mods.toml</code>).

<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 <code>mods.toml</code> file</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="toml">
modLoader="javafml"
# Forge for 1.16.3 is version 34
loaderVersion="[34,)"
license="All rights reserved"
issueTrackerURL="github.com/MinecraftForge/MinecraftForge/issues"
showAsResourcePack=false

[[mods]]
modId="examplemod"
version="1.0.0.0"
displayName="Example Mod"
updateJSONURL="minecraftforge.net/versions.json"
displayURL="minecraftforge.net"
logoFile="logo.png"
credits="I'd like to thank my mother and father."
authors="Author"
description='''
Lets you craft dirt into diamonds. This is a traditional mod that has existed for eons. It is ancient. The holy Notch created it. Jeb rainbowfied it. Dinnerbone made it upside down. Etc.
'''

[[dependencies.examplemod]]
modId="forge"
mandatory=true
versionRange="[34,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.16.3]"
ordering="NONE"
side="BOTH"
</syntaxhighlight>
</div>
</div>

The default Gradle configuration replaces <code>${file.jarVersion}</code> with the project version, but only within <code>mods.toml</code>, so you should use those instead of directly writing them out. Here is a table of attributes that may be given to a mod, where <code>mandatory</code> means there is no default and the absence of the property causes an error.

The <code>mods.toml</code> is split into three parts: the non-mod-specific properties, which are linked to the mod file; the mod properties, with a section for each mod; and dependency configurations, with a section for each mod's dependencies.

=== Non-Mod-Specific Properties ===

{| class="wikitable"
! Property !! Type !! Defaults
! Description
! Example
|-
| <code>modLoader</code> || string || '''mandatory'''
| The language loader for the mod. Used to specify an alternative language for the mod, such as Kotlin, if one exists. The Forge-provided Java loader is <code>javafml</code>.
| <code>"javafml"</code>
|-
| <code>loaderVersion</code> || string || '''mandatory'''
| The acceptable version range of the language loader, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. For the Forge-provided Java loader, the version is the major version of the Forge version.
| <code>"[34,)"</code>
|-
| <code>license</code> || string || '''mandatory'''
| The license for the mod(s) in this JAR. This string may be any valid string, but it is suggested to set the value to be the name of your license, and/or a link to that license.
| <code>"GNU GPL v3, https://www.gnu.org/licenses/gpl-3.0.en.html"</code>
|-
| <code>showAsResourcePack</code> || boolean || <code>false</code>
| Whether to display this mod's resources as a separate option in the resource pack menu. If disabled, the mod's resources will be rolled into the "Mod resources" pack.
| <code>true</code>
|-
| <code>properties</code> || table || <code>{}</code>
| A table of custom substitution properties. This is used by <code>StringSubstitutor</code> to replace values, using <code>${file.*}</code>.
| <code>{ "thingy" = 1 }</code>, used in <code>${file.thingy}</code>
|-
| <code>issueTrackerURL</code> || string || ''nothing''
| A URL for an issues tracker. <inline alert> This should never be a blank string, as that will cause an error. </inline>
| <code>"http://my.issue.tracker/"</code>
|}

=== Mod Properties ===

A mod entry is defined by a new section starting with a <code><nowiki>[[mods]]</nowiki></code> header (In TOML, the <code><nowiki>[[mods]]</nowiki></code> defines an [https://toml.io/en/v1.0.0-rc.2#array-of-tables array of tables]). All properties from that line until the next header will become the properties for that mod.

{| class="wikitable"
! Property !! Type !! Defaults
! Description
! Example
|-
| <code>modId</code> || string || '''mandatory'''
| The mod's identifier (modid). This must match the following regex: <code>^[a-z][a-z0-9_-]{1,63}$</code> (starts with a lowercase letter; other characters must be a lowercase letter, number, underscore or hyphen; must be 2-64 characters long).
| <code>"examplemod"</code>
|-
| <code>namespace</code> || string || value of <code>modId</code>
| An override namespace. <inline info> Currently, there is no use for this property </inline>
| <code>example</code>
|-
| <code>version</code> || string || <code>"1"</code>
| The version of the mod jar, used when the mod is a dependency of another mod, expressed as numbers seperated by dots (<code>.</code>), ideally conforming to [[Semantic_Versioning|Semantic Versioning]]. The default value in the MDK for this is <code>${file.jarVersion}</code>, which is replaced at runtime with the <code>Implementation-Version</code> found in the jar's manifest file.
| <code>"0.2.4-beta1"</code>
|-
| <code>displayName</code> || string || value of <code>modId</code>
| The display name of the mod, for use in the Mods listing screen
| <code>"Example Mod"</code>
|-
| <code>description</code> || string || <code>"MISSING DESCRIPTION"</code>
| The description of the mod, for use in the Mods listing screen. It's recommended to use a multiline string (surrounded by <code>'''<code>)
| <code>"Adds things and stuff. "</code>
|-
| <code>logoFile</code> || string || ''nothing''
| The path of the logo file image, for use in the Mods listing screen. The image must be in the root of the jar file, not in any subfolder thereof (e.g. the file is directly in <code>src/main/resources</code>)
| <code>"myAwesomeLogo.png"</code>
|-
| <code>logoBlur</code> || boolean || <code>true</code>
| Whether to do some blurring on the mod's logo in the Mods listing screen. Has no effect if <code>logoFile</code> is not set.
| <code>false</code>
|-
| <code>updateJSONURL</code> || string || ''nothing''
| The update JSON URL, used by the [Update_Checker update checker]. <inline alert> This should never be a blank string, as that will cause an error. </inline>
| <code>http://myurl.me/path/to/update.json</code>
|-
| <code>modproperties</code> || table || <code>{}</code>
| A table of custom mod properties; this is not used for Forge, but is mainly for use by mods.
| <code>{ "useThing" = true }</code>
|-
| <code>credits</code> || string || ''nothing''
| Credits and acknowledgements for the mod, for use in the Mods listing screen. Can be any string.
| <code>"This person and that guy"</code>
|-
| <code>authors</code> || string || ''nothing''
| Authors for the mod, for use in the Mods listing screen. Can be any string.
| <code>"ExampleDude"</code>
|-
| <code>displayURL</code> || string || ''nothing''
| A URL, displayed on the Mods listing screen. Can be any string.
| <code>http://example.com/</code>
|}

=== Dependency Configurations ===

Mods can define dependencies for their mods, which are checked by Forge before loading mods. This is used for e.g. ensuring your mod loads after another, or hard-crashing if a mod with a specified version does not exist.

These dependency configurations, like the mod properties, are defined by a new section starting with <code>[[dependencies.<modid>]]</code>, with <code><modid></code> being the mod id that has this dependency. All properties from that line until the next header will become the properties of that dependency configuration.

{|
! Property !! Type !! Defaults
! Description
! Example
|-
| <code>modId</code> || string || '''mandatory'''
| The mod id of the dependency.
| <code>examplelibrary</code>
|-
| <code>mandatory</code> || boolean || '''mandatory'''
| Whether to crash if this dependency is not met.
| <code>true</code>
|-
| <code>versionRange</code> || string || <code>""</code>
| The acceptable version range of the dependency, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. An empty string is an unbounded version range, which matches any version.
| <code>"[1.0,2.0)"</code>
|-
| <code>ordering</code> || string || <code>"NONE"</code>
| Defines if the mod must load before or after this dependency. The valid values are <code>BEFORE</code> (must load before), <code>AFTER</code> (must load after), and <code>NONE</code> (does not care about order).
| <code>"AFTER"</code>
|-
| <code>side</code> || string || <code>"BOTH"</code>
| Defines if this dependency needs only to be met on a specfic [[Sides|physical side]]. The valid values are <code>CLIENT</code> (present on the client), <code>SERVER</code> (present on the dedicated server), and <code>BOTH</code> (present on both sides).
| <code>"CLIENT"</code>
|}

{{Colored box|title=Important|content=When specifying dependency ordering between two or more mods, beware of cyclic order!: ex. if mod A must load before mod B, and mod B must load before mod A, the game will crash because of the circular cycle.}}

[[Category:Getting Started]]

Proper Mod Structuring

2020-09-19T04:14:44Z

Curle: /* The mods.toml file */

== Structuring Your Mod ==

We’ll look at how to organize your mod into different files and what those files should do.
=== Packaging ===

Pick a unique package name. If you own a URL associated with your project, you can use it as your top level package. For example if you own “example.com”, you may use <code>com.example</code> as your top level package.

{{Colored box|title=Important|content=If you do not own a domain, do not use it for your top level package. It is perfectly acceptable to start your package with anything, such as your name/nickname, or the name of the mod.}}

After the top level package (if you have one) you append a unique name for your mod, such as <code>examplemod</code>. In our case it will end up as <code>com.example.examplemod</code>.

=== The <code>mods.toml</code> file ===

This file defines the metadata of your mod. Its information may be viewed by users from the main screen of the game through the Mods button. A single info file can describe several mods.

The <code>mods.toml</code> file is formatted as [https://github.com/toml-lang/toml TOML], the example mods.toml file in the MDK provides comments explaining the contents of the file. It should be stored as <code>src/main/resources/META-INF/mods.toml</code>. A basic <code>mods.toml</code>, describing one mod, may look like this:
<syntaxhighlight lang="toml">

# The name of the mod loader type to load - for regular FML @Mod mods it should be javafml
modLoader="javafml"
# A version range to match for said mod loader - for regular FML @Mod it will be the forge version
# Forge for 1.15.2 is version 31
loaderVersion="[31,)"
# A URL to refer people to when problems occur with this mod
issueTrackerURL="github.com/MinecraftForge/MinecraftForge/issues"
# If the mods defined in this file should show as seperate resource packs
showAsResourcePack=false
[[mods]]
modId="examplemod"
version="1.0.0.0"
displayName="Example Mod"
updateJSONURL="minecraftforge.net/versions.json"
displayURL="minecraftforge.net"
logoFile="assets/examplemod/textures/logo.png"
credits="I'd like to thank my mother and father."
authors="Author"
description='''
Lets you craft dirt into diamonds. This is a traditional mod that has existed for eons. It is ancient. The holy Notch created it. Jeb rainbowfied it. Dinnerbone made it upside down. Etc.
'''

[[dependencies.examplemod]]
modId="forge"
mandatory=true
versionRange="[31,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.15.2]"
ordering="NONE"
side="BOTH"
</syntaxhighlight>

The default Gradle configuration replaces <code>${file.jarVersion}</code> with the project version, but ''only'' within <code>mods.toml</code>, so you should use those instead of directly writing them out. Here is a table of attributes that may be given to a mod, where <code>mandatory</code> means there is no default and the absence of the property causes an error.

{| class="wikitable"
|-
! Property !! Type !! Default !! Description
|-
| modid || string || mandatory || The modid this file is linked to.
|-
| version || string || mandatory || The version of the mod. It should be just numbers seperated by dots, ideally conforming to Semantic Versioning.
|-
| license || string || mandatory || The license that the mod is held under
|-
| displayName || string || mandatory || The user-friendly name of this mod.
|-
| updateJSONURL || string || "" || The URL to a version JSON.
|-
| displayURL || string || "" || A link to the mod’s homepage.
|-
| logoFile || string || "" || The filename of the mod’s logo. It must be placed in the root resource folder, not in a subfolder.
|-
| credits || string || "" || A string that contains any acknowledgements you want to mention.
|-
| authors || string || "" || The authors to this mod.
|-
| description || string || mandatory || A description of this mod.
|-
| dependencies || [list] || [] || A list of dependencies of this mod.
|}

NOTE: All version ranges use the [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven Version Range Specification].

=== The Mod File ===

Generally, we’ll start with a file named after your mod, and put into your package. This is the ''entry point'' to your mod and will contain some special indicators marking it as such.

==== What is <code>@Mod</code>? ====

This is an annotation indicating to the Forge Mod Loader that the class is a Mod entry point. The <code>@Mod</code> annotation’s value should match a mod id in the <code>src/main/resources/META-INF/mods.toml</code> file.

==== Keeping Your Code Clean Using Sub-packages ====

Rather than clutter up a single class and package with everything, it is recommended you break your mod into subpackages.

A common subpackage strategy has packages for <code>common</code> and <code>client</code> code, which is code that can be run on server/client and client, respectively. Inside the <code>common</code> package would go things like Items, Blocks, and Tile Entities (which can each in turn be another subpackage). Things like GUIs and Renderers would go inside the <code>client</code> package.

{{Colored box|title=Note|content=This package style is only a suggestion, though it is a commonly used style. Feel free to use your own packaging system.}}

By keeping your code in clean subpackages, you can grow your mod much more organically.

==== Class Naming Schemes ====

A common class naming scheme allows easier deciphering of what a class is, and also makes it easier for someone developing with your mod to find things.

For Example:

* An <code>Item</code> called <code>PowerRing</code> would be in an <code>item</code> package, with a class name of <code>PowerRingItem</code>.
* A <code>Block</code> called <code>NotDirt</code> would be in a <code>block</code> package, with a class name of <code>NotDirtBlock</code>.
* Finally, a <code>TileEntity</code> for a block called <code>SuperChewer</code> would be in a <code>tile</code> or <code>tileentity</code> package, with a class name of <code>SuperChewerTile</code>.

Appending your class names with what ''kind'' of object they are makes it easier to figure out what a class is, or guess the class for an object.

[[Category:Getting Started]]

Proper Mod Structuring

2020-09-19T04:01:16Z

Curle: Add Mod Structuring article

== Structuring Your Mod ==

We’ll look at how to organize your mod into different files and what those files should do.
=== Packaging ===

Pick a unique package name. If you own a URL associated with your project, you can use it as your top level package. For example if you own “example.com”, you may use <code>com.example</code> as your top level package.

{{Colored box|title=Important|content=If you do not own a domain, do not use it for your top level package. It is perfectly acceptable to start your package with anything, such as your name/nickname, or the name of the mod.}}

After the top level package (if you have one) you append a unique name for your mod, such as <code>examplemod</code>. In our case it will end up as <code>com.example.examplemod</code>.

=== The <code>mods.toml</code> file ===

This file defines the metadata of your mod. Its information may be viewed by users from the main screen of the game through the Mods button. A single info file can describe several mods.

The <code>mods.toml</code> file is formatted as [https://github.com/toml-lang/toml TOML], the example mods.toml file in the MDK provides comments explaining the contents of the file. It should be stored as <code>src/main/resources/META-INF/mods.toml</code>. A basic <code>mods.toml</code>, describing one mod, may look like this:
<syntaxhighlight lang="toml">
# The name of the mod loader type to load - for regular FML @Mod mods it should be javafml
modLoader="javafml"
# A version range to match for said mod loader - for regular FML @Mod it will be the forge version
# Forge for 1.15.2 is version 31
loaderVersion="[31,)"
# A URL to refer people to when problems occur with this mod
issueTrackerURL="github.com/MinecraftForge/MinecraftForge/issues"
# If the mods defined in this file should show as seperate resource packs
showAsResourcePack=false
[[mods]]
modId="examplemod"
version="1.0.0.0"
displayName="Example Mod"
updateJSONURL="minecraftforge.net/versions.json"
displayURL="minecraftforge.net"
logoFile="assets/examplemod/textures/logo.png"
credits="I'd like to thank my mother and father."
authors="Author"
description='''
Lets you craft dirt into diamonds. This is a traditional mod that has existed for eons. It is ancient. The holy Notch created it. Jeb rainbowfied it. Dinnerbone made it upside down. Etc.
'''

[[dependencies.examplemod]]
modId="forge"
mandatory=true
versionRange="[31,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.15.2]"
ordering="NONE"
side="BOTH"
</syntaxhighlight>
The default Gradle configuration replaces <code>${file.jarVersion}</code> with the project version, but ''only'' within <code>mods.toml</code>, so you should use those instead of directly writing them out. Here is a table of attributes that may be given to a mod, where <code>mandatory</code> means there is no default and the absence of the property causes an error.

{| class="wikitable"
|-
! Property !! Type !! Default !! Description
|-
| modid || string || mandatory || The modid this file is linked to.
|-
| version || string || mandatory || The version of the mod. It should be just numbers seperated by dots, ideally conforming to Semantic Versioning.
|-
| license || string || mandatory || The license that the mod is held under
|-
| displayName || string || mandatory || The user-friendly name of this mod.
|-
| updateJSONURL || string || "" || The URL to a version JSON.
|-
| displayURL || string || "" || A link to the mod’s homepage.
|-
| logoFile || string || "" || The filename of the mod’s logo. It must be placed in the root resource folder, not in a subfolder.
|-
| credits || string || "" || A string that contains any acknowledgements you want to mention.
|-
| authors || string || "" || The authors to this mod.
|-
| description || string || mandatory || A description of this mod.
|-
| dependencies || [list] || [] || A list of dependencies of this mod.
|}

NOTE: All version ranges use the [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven Version Range Specification].

=== The Mod File ===

Generally, we’ll start with a file named after your mod, and put into your package. This is the ''entry point'' to your mod and will contain some special indicators marking it as such.

==== What is <code>@Mod</code>? ====

This is an annotation indicating to the Forge Mod Loader that the class is a Mod entry point. The <code>@Mod</code> annotation’s value should match a mod id in the <code>src/main/resources/META-INF/mods.toml</code> file.

==== Keeping Your Code Clean Using Sub-packages ====

Rather than clutter up a single class and package with everything, it is recommended you break your mod into subpackages.

A common subpackage strategy has packages for <code>common</code> and <code>client</code> code, which is code that can be run on server/client and client, respectively. Inside the <code>common</code> package would go things like Items, Blocks, and Tile Entities (which can each in turn be another subpackage). Things like GUIs and Renderers would go inside the <code>client</code> package.

{{Colored box|title=Note|content=This package style is only a suggestion, though it is a commonly used style. Feel free to use your own packaging system.}}

By keeping your code in clean subpackages, you can grow your mod much more organically.

==== Class Naming Schemes ====

A common class naming scheme allows easier deciphering of what a class is, and also makes it easier for someone developing with your mod to find things.

For Example:

* An <code>Item</code> called <code>PowerRing</code> would be in an <code>item</code> package, with a class name of <code>PowerRingItem</code>.
* A <code>Block</code> called <code>NotDirt</code> would be in a <code>block</code> package, with a class name of <code>NotDirtBlock</code>.
* Finally, a <code>TileEntity</code> for a block called <code>SuperChewer</code> would be in a <code>tile</code> or <code>tileentity</code> package, with a class name of <code>SuperChewerTile</code>.

Appending your class names with what ''kind'' of object they are makes it easier to figure out what a class is, or guess the class for an object.

[[Category:Getting Started]]

Template:Colored box/style.css

2020-09-19T03:04:08Z

Curle:

.mw-tpl-colorbox {
box-sizing: border-box;
margin: 0.5em 0.5em 1em 0.5em;
border-radius: 0.2em;
background: rgb(27, 32, 35);
box-shadow: 0 0 0.2em #999999;
}

.mw-tpl-colorbox-title {
background: rgb(0, 71, 127);
color: #FFFFFF;
border-radius: 0.2em 0.2em 0 0;
padding: 0.5em 1em 0.5em 1em;
}

.mw-tpl-colorbox-title-icon {
opacity: 0.8;
}

.mw-tpl-colorbox-title-corner {
float: right;
font-size: 0.7em;
}

.mw-tpl-colorbox-content {
padding: 0.5em 1em 0.5em 1em;
color: #FFFFFF;
}

Template:Colored box

2020-09-19T03:03:49Z

Curle:

<templatestyles src="Colored box/style.css"/><div class="mw-tpl-colorbox" style="{{#if:{{{background-content-color|}}}| background-color: {{{background-content-color|rgb(27, 32, 35)}}}; }} {{{style|}}};"><div class="mw-tpl-colorbox-title" style="{{#if:{{{background-title-color|}}}|background-color:{{{background-title-color|rgb(0, 71, 127)}}};}}">{{#if:{{{icon|}}}|[[File:{{{icon}}}|20px|class=colorbox-title-icon|link=|alt=]] }}<strong style="{{#if:{{{title-color|}}}| color: {{{title-color|#FFFFFF}}}; }}">{{{title}}}</strong>{{#if:{{{link|}}}|<div class="mw-tpl-colorbox-title-corner">[[{{{link}}}|<span style="{{#if:{{{link-color|{{{title-color|}}}}}}| color: {{{link-color|{{{title-color|}}}}}}; }}">{{{view-text|view}}}</span>]]</div>}}
</div><div class="mw-tpl-colorbox-content">
{{{content}}}{{clr}}</div>
</div>

Template:Colored box

2020-09-19T03:03:22Z

Curle:

<templatestyles src="Colored box/style.css"/><div class="mw-tpl-colorbox" style="{{#if:{{{background-content-color|}}}| background-color: {{{background-content-color|rgb(27, 32, 35)}}}; }} {{{style|}}};"><div class="mw-tpl-colorbox-title" style="{{#if:{{{background-title-color|}}}|background-color:{{{background-title-color|rgb(0, 71, 127)}}};}}">{{#if:{{{icon|}}}|[[File:{{{icon}}}|20px|class=colorbox-title-icon|link=|alt=]] }}<strong style="{{#if:{{{title-color|}}}| color: {{{title-color|#000000}}}; }}">{{{title}}}</strong>{{#if:{{{link|}}}|<div class="mw-tpl-colorbox-title-corner">[[{{{link}}}|<span style="{{#if:{{{link-color|{{{title-color|}}}}}}| color: {{{link-color|{{{title-color|}}}}}}; }}">{{{view-text|view}}}</span>]]</div>}}
</div><div class="mw-tpl-colorbox-content">
{{{content}}}{{clr}}</div>
</div>

Template:Colored box/style.css

2020-09-19T03:02:25Z

Curle:

.mw-tpl-colorbox {
box-sizing: border-box;
margin: 0.5em 0.5em 1em 0.5em;
border-radius: 0.2em;
background: rgb(27, 32, 35);
box-shadow: 0 0 0.2em #999999;
}

.mw-tpl-colorbox-title {
background: rgb(0, 71, 127);
color: #000000;
border-radius: 0.2em 0.2em 0 0;
padding: 0.5em 1em 0.5em 1em;
}

.mw-tpl-colorbox-title-icon {
opacity: 0.8;
}

.mw-tpl-colorbox-title-corner {
float: right;
font-size: 0.7em;
}

.mw-tpl-colorbox-content {
padding: 0.5em 1em 0.5em 1em;
color: #11151d;
}

Template:Colored box/style.css

2020-09-19T03:01:00Z

Curle:

.mw-tpl-colorbox {
box-sizing: border-box;
margin: 0.5em 0.5em 1em 0.5em;
border-radius: 0.2em;
background: rgb(27, 32, 35);
box-shadow: 0 0 0.2em #999999;
}

.mw-tpl-colorbox-title {
background: #7dbae8;
color: #000000;
border-radius: 0.2em 0.2em 0 0;
padding: 0.5em 1em 0.5em 1em;
}

.mw-tpl-colorbox-title-icon {
opacity: 0.8;
}

.mw-tpl-colorbox-title-corner {
float: right;
font-size: 0.7em;
}

.mw-tpl-colorbox-content {
padding: 0.5em 1em 0.5em 1em;
color: #11151d;
}

Category:Getting Started

2020-09-19T02:56:53Z

Curle: Created page with "For absolute beginners who need an introduction to the whole system. Important information is split up across the subcategories for those who need help with the less commonly..."

For absolute beginners who need an introduction to the whole system.
Important information is split up across the subcategories for those who need help with the less commonly explained things.

Getting Started

2020-09-19T02:55:31Z

Curle:

= Home =
== Getting Started with Forge ==
This is a simple guide to get you from nothing to a basic mod. The rest of this documentation is about where to go from here.
=== From Zero to Modding ===
# Obtain a source distribution from forge’s [https://files.minecraftforge.net/ files] site. (Look for the MDK file type)
# Extract the downloaded source distribution to an empty directory. You should see a bunch of files, and an example mod is placed in <code>src/main/java</code> for you to look at. Only a few of these files are strictly necessary for mod development, and you may reuse these files for all your projects These files are:
#* <code>build.gradle</code>
#* <code>gradlew.bat</code>
#* <code>gradlew</code>
#* the <code>gradle</code> folder
# Move the files listed above to a new folder, this will be your mod project folder.
# Choose your IDE:
#* Forge explicitly supports developing with Eclipse or IntelliJ environments, but any environment, from Netbeans to vi/emacs, can be made to work.
#* For both Intellij IDEA and Eclipse their Gradle integration will handle the rest of the initial workspace setup, this includes downloading packages from Mojang, MinecraftForge, and a few other software sharing sites.
#* For most, if not all, changes to the build.gradle file to take effect Gradle will need to be invoked to re-evaluate the project, this can be done through Refresh buttons in the Gradle panels of both the previously mentioned IDEs.
# Generating IDE Launch/Run Configurations:
#*For Eclipse, run the <code>genEclipseRuns</code> gradle task (<code>gradlew genEclipseRuns</code>). This will generate the Launch Configurations and download any required assets for the game to run. After this has finished refresh your project.
#*or IntelliJ, run the <code>genIntellijRuns</code> gradle task (<code>gradlew genIntellijRuns</code>). This will generate the Run Configurations and download any required assets for the game to run. After this has finished edit your Configurations to fix the “module not specified” error by changing selecting your “main” module.

=== Customizing Your Mod Information ===
Edit the <code>build.gradle</code> file to customize how your mod is built (the file names, versions, and other things).

{{Colored box|title=Important|content='''Do not''' edit the <code>buildscript {}</code> section of the build.gradle file, its default text is necessary for ForgeGradle to function.}}

Almost anything underneath the <code>// Only edit below this line, the above code adds and enables the necessary things for Forge to be setup.</code> marker can be changed, many things can be removed and customized there as well.

There is a whole site dedicated to customizing the forge <code>build.gradle</code> files - the [https://forgegradle.readthedocs.org/en/latest/cookbook/ ForgeGradle cookbook]. Once you’re comfortable with your mod setup, you’ll find many useful recipes there.

==== Simple build.gradle Customizations ====
These customizations are highly recommended for all projects.
* To change the name of the file you build - edit the value of <code>archivesBaseName</code> to suit.
* To change your “maven coordinates” - edit the value of <code>group</code> as well.
* To change the version number - edit the value of <code>version</code>.
* To update the run configurations - replace all occurrences of <code>examplemod</code> to the mod id of your mod.

=== Building and Testing Your Mod ===
# To build your mod, run <code>gradlew build</code>. This will output a file in <code>build/libs</code> with the name <code>[archivesBaseName]-[version].jar</code>. This file can be placed in the <code>mods</code> folder of a forge enabled Minecraft setup, and distributed.
# To test run with your mod, the easiest way is to use the run configs that were generated when you set up your project. Otherwise, you can run <code>gradlew runClient</code>. This will launch Minecraft from the <code><runDir></code> location, including your mod code. There are various customizations to this command. Consult the [https://forgegradle.readthedocs.org/en/latest/cookbook/ ForgeGradle cookbook] for more information.
# You can also run a dedicated server using the server run config, or <code>gradlew runServer</code>. This will launch the Minecraft server with its GUI.

{{Colored box|title=Note|content=It is always advisable to test your mod in a dedicated server environment if it is intended to run there.}}

[[Category:Getting Started]]

Template:Colored box/style.css

2020-09-19T02:54:13Z

Curle:

.mw-tpl-colorbox {
box-sizing: border-box;
margin: 0.5em 0.5em 1em 0.5em;
border-radius: 0.2em;
background: #fff;
box-shadow: 0 0 0.2em #999999;
}

.mw-tpl-colorbox-title {
background: #eaecf0;
color: #000000;
border-radius: 0.2em 0.2em 0 0;
padding: 0.5em 1em 0.5em 1em;
}

.mw-tpl-colorbox-title-icon {
opacity: 0.8;
}

.mw-tpl-colorbox-title-corner {
float: right;
font-size: 0.7em;
}

.mw-tpl-colorbox-content {
padding: 0.5em 1em 0.5em 1em;
color: #11151d;
}

Template:Colored box

2020-09-19T02:34:02Z

Curle:

<templatestyles src="Colored box/style.css"/><div class="mw-tpl-colorbox" style="{{#if:{{{background-content-color|}}}| background-color: {{{background-content-color|#fff}}}; }} {{{style|}}};"><div class="mw-tpl-colorbox-title" style="{{#if:{{{background-title-color|}}}|background-color:{{{background-title-color|#eaecf0}}};}}">{{#if:{{{icon|}}}|[[File:{{{icon}}}|20px|class=colorbox-title-icon|link=|alt=]] }}<strong style="{{#if:{{{title-color|}}}| color: {{{title-color|#000000}}}; }}">{{{title}}}</strong>{{#if:{{{link|}}}|<div class="mw-tpl-colorbox-title-corner">[[{{{link}}}|<span style="{{#if:{{{link-color|{{{title-color|}}}}}}| color: {{{link-color|{{{title-color|}}}}}}; }}">{{{view-text|view}}}</span>]]</div>}}
</div><div class="mw-tpl-colorbox-content">
{{{content}}}{{clr}}</div>
</div>