Forge Community Wiki - User contributions [en-gb]

Mods.toml

2021-12-11T17:08:48Z

N1K-x: Update to 1.18.1

{{Under construction}}

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

Example <code>mods.toml</code> file:
<syntaxhighlight lang="TOML">
modLoader="javafml"
# Forge for 1.18.1 is version 39
loaderVersion="[39,)"
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="[39,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.18.1,1.19)"
ordering="NONE"
side="BOTH"
</syntaxhighlight>

If the <code>version</code> is specified as<code>${file.jarVersion}</code>, Forge will replace the string with the 'Implementation Version' specified in the jar manifest at runtime. Since the userdev environment has no jar manifest to pull from, it will be <code>NONE</code> instead. As such, it is usually recommended to leave this field alone.

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

===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>"[39,)"</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. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://my.issue.tracker/"</nowiki></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. Currently, there is no use for this property
|<code>example</code>
|-
|<code>version</code>
|string
|<code>"1"</code>
|The mod's version, 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><nowiki>'''</nowiki></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]]. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://myurl.me/path/to/update.json"</nowiki></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><nowiki>"http://example.com/"</nowiki></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><nowiki>[[dependencies.modid]]</nowiki></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.
{| class="wikitable"
|-
!|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>
|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>
|}

{{Tip/Warning|When specifying dependency ordering between two or more mods, beware of cyclic order!
An example: 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]]
[[Category:Beginner Topics]]

Capabilities

2021-12-10T14:41:48Z

N1K-x: Update the code example Gist to the new version

'''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);
event.addListener(optionalStorage::invalidate);
}
</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);
event.addListener(optionalStorage::invalidate);
}
</syntaxhighlight>

=== Accessing a Capability ===

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

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

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

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

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

<syntaxhighlight lang="java">
// 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]]

Capabilities

2021-12-10T14:32:11Z

N1K-x: Add class diagram to "Creating Custom Capabilities"

'''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);
event.addListener(optionalStorage::invalidate);
}
</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);
event.addListener(optionalStorage::invalidate);
}
</syntaxhighlight>

=== Accessing a Capability ===

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

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

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

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

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

<syntaxhighlight lang="java">
// 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/TheSilkMiner/5cc92ba573e7bdd871dfdbffdd5c2806 A Gist showing a quick and dirty example on how to implement a Capability effectively]

[[Category:Data Storage]]

File:Custom Capability Class Diagram.svg

2021-12-10T14:14:17Z

N1K-x: N1K-x uploaded a new version of File:Custom Capability Class Diagram.svg

A UML Class Diagram showing the essential parts for creating a custom capability.

File:Custom Capability Class Diagram.svg

2021-12-10T14:00:32Z

N1K-x:

A UML Class Diagram showing the essential parts for creating a custom capability.

Getting Started

2021-09-07T13:51:31Z

N1K-x: Update some links (mainly gradle since we no longer use a snapshot version)

'''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/7.2/userguide/gradle_wrapper.html Gradle wrapper]'', Forge uses Version '''7.2'''''
** <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 '''meta'''data '''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 [[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/7.2/userguide/tutorial_using_tasks.html Gradle User Guide for 7.2: ''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/7.2/userguide/build_environment.html#sec:gradle_configuration_properties Gradle User Guide for 7.2: ''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 the 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>; the Java plugin and Gradle tasks plugin should both be installed for smoother integration.

{{Tip|The most popular IDEs used by Forge and mod developers are [https://www.eclipse.org/eclipseide/ Eclipse] and [https://www.jetbrains.com/idea/ IntelliJ IDEA]. While Visual Studio Code has a run generation task, because of its relative unpopularity as an IDE for Minecraft modding, the user will have to self-diagnose any issues that may arise from their use of it.}}

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

[[Category:Beginner Topics]]

Mods.toml

2021-09-01T11:18:50Z

N1K-x: Fix description description

{{Under construction}}

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

Example <code>mods.toml</code> file:
<syntaxhighlight lang="TOML">
modLoader="javafml"
# Forge for 1.17.1 is version 37
loaderVersion="[37,)"
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="[37,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.17.1,1.18)"
ordering="NONE"
side="BOTH"
</syntaxhighlight>

If the <code>version</code> is specified as<code>${file.jarVersion}</code>, Forge will replace the string with the 'Implementation Version' specified in the jar manifest at runtime. Since the userdev environment has no jar manifest to pull from, it will be <code>NONE</code> instead. As such, it is usually recommended to leave this field alone.

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

===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>"[37,)"</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. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://my.issue.tracker/"</nowiki></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. Currently, there is no use for this property
|<code>example</code>
|-
|<code>version</code>
|string
|<code>"1"</code>
|The mod's version, 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><nowiki>'''</nowiki></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]]. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://myurl.me/path/to/update.json"</nowiki></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><nowiki>"http://example.com/"</nowiki></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><nowiki>[[dependencies.modid]]</nowiki></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.
{| class="wikitable"
|-
!|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>
|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>
|}

{{Tip/Warning|When specifying dependency ordering between two or more mods, beware of cyclic order!
An example: 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]]
[[Category:Beginner Topics]]

Mods.toml

2021-09-01T11:16:23Z

N1K-x: Fix version description

{{Under construction}}

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

Example <code>mods.toml</code> file:
<syntaxhighlight lang="TOML">
modLoader="javafml"
# Forge for 1.17.1 is version 37
loaderVersion="[37,)"
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="[37,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.17.1,1.18)"
ordering="NONE"
side="BOTH"
</syntaxhighlight>

If the <code>version</code> is specified as<code>${file.jarVersion}</code>, Forge will replace the string with the 'Implementation Version' specified in the jar manifest at runtime. Since the userdev environment has no jar manifest to pull from, it will be <code>NONE</code> instead. As such, it is usually recommended to leave this field alone.

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

===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>"[37,)"</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. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://my.issue.tracker/"</nowiki></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. Currently, there is no use for this property
|<code>example</code>
|-
|<code>version</code>
|string
|<code>"1"</code>
|The mod's version, 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></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]]. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://myurl.me/path/to/update.json"</nowiki></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><nowiki>"http://example.com/"</nowiki></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><nowiki>[[dependencies.modid]]</nowiki></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.
{| class="wikitable"
|-
!|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>
|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>
|}

{{Tip/Warning|When specifying dependency ordering between two or more mods, beware of cyclic order!
An example: 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]]
[[Category:Beginner Topics]]

Proper Mod Structuring

2021-09-01T11:08:42Z

N1K-x: Properly reference the mods.toml file page

Proper Mod Structuring

2021-09-01T11:02:24Z

N1K-x:

Main Page

2021-09-01T11:02:11Z

N1K-x:

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

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

The Forge Community Wiki exists so that the community can:

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

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

{{Supported versions}}

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

<div class="center" style="margin-bottom: 2em">
The current ''Latest'' version is '''1.17.1'''. The current ''Long Term Support (LTS)'' version is '''1.16.5'''. '''1.15.2''' is currently in ''grace/LTS''.
</div>

<div class="box_container center">

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

</div>

Mods.toml

2021-09-01T11:00:42Z

N1K-x:

{{Under construction}}

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

Example <code>mods.toml</code> file:
<syntaxhighlight lang="TOML">
modLoader="javafml"
# Forge for 1.17.1 is version 37
loaderVersion="[37,)"
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="[37,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.17.1,1.18)"
ordering="NONE"
side="BOTH"
</syntaxhighlight>

If the <code>version</code> is specified as<code>${file.jarVersion}</code>, Forge will replace the string with the 'Implementation Version' specified in the jar manifest at runtime. Since the userdev environment has no jar manifest to pull from, it will be <code>NONE</code> instead. As such, it is usually recommended to leave this field alone.

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

===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>"[37,)"</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. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://my.issue.tracker/"</nowiki></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. Currently, there is no use for this property
|<code>example</code>
|-
|<code>version</code>
|string
|<code>"1"</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></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]. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://myurl.me/path/to/update.json"</nowiki></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><nowiki>"http://example.com/"</nowiki></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><nowiki>[[dependencies.modid]]</nowiki></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.
{| class="wikitable"
|-
!|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>
|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>
|}

{{Tip/Warning|When specifying dependency ordering between two or more mods, beware of cyclic order!
An example: 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]]
[[Category:Beginner Topics]]

Mods.toml

2021-09-01T11:00:13Z

N1K-x: Created page with "{{Under construction}} 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 th..."

{{Under construction}}

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

Example <code>mods.toml</code> file:
<syntaxhighlight lang="TOML">
modLoader="javafml"
# Forge for 1.17.1 is version 37
loaderVersion="[37,)"
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="[37,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.17.1,1.18)"
ordering="NONE"
side="BOTH"
</syntaxhighlight>

If the <code>version</code> is specified as<code>${file.jarVersion}</code>, Forge will replace the string with the 'Implementation Version' specified in the jar manifest at runtime. Since the userdev environment has no jar manifest to pull from, it will be <code>NONE</code> instead. As such, it is usually recommended to leave this field alone.

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

===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>"[37,)"</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. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://my.issue.tracker/"</nowiki></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. Currently, there is no use for this property
|<code>example</code>
|-
|<code>version</code>
|string
|<code>"1"</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></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]. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://myurl.me/path/to/update.json"</nowiki></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><nowiki>"http://example.com/"</nowiki></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><nowiki>[[dependencies.modid]]</nowiki></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.
{| class="wikitable"
|-
!|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>
|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>
|}

{{Tip/Warning|When specifying dependency ordering between two or more mods, beware of cyclic order!
An example: 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.}}

Proper Mod Structuring

2021-07-29T10:14:38Z

N1K-x: Add another possible way of laying out subpackages

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.

{{Tip|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>.

{{Tip/Important|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. Below are a few possible methods for laying out your folder structure though you may as well come up with your own layout too.

* '''Group by Logic''': One possible strategy is to make subpackages for logical units of your mod. For example, if you have a block called Super Furnace you would put its block, its block entity and its item all under <code>feature/superfurnace</code>.
* '''Group by Function''': Another common strategy is to make subpackages 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.

No matter how your final structure looks like it is highly recommended to add a <code>client</code> subpackage under your main package. This helps 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.

{{Tip|If you are unsure on how exactly you want to structure your mod it can be a good idea to look at the source of others to see how they did it.}}

== 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 have a class name of <code>PowerRingItem</code>.
* A <code>Block</code> called <code>NotDirt</code> would have a class name of <code>NotDirtBlock</code>.
* A <code>BlockEntity</code> for a block called <code>SuperChewer</code> would have a class name of <code>SuperChewerBlockEntity</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>).

Example <code>mods.toml</code> file
<syntaxhighlight lang="TOML">
modLoader="javafml"
# Forge for 1.16.5 is version 36
loaderVersion="[36,)"
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="[36,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.16.5]"
ordering="NONE"
side="BOTH"
</syntaxhighlight>

If the <code>version</code> is specified as<code>${file.jarVersion}</code>, Forge will replace the string with the 'Implementation Version' specified in the jar manifest at runtime. Since the userdev environment has no jar manifest to pull from, it will be <code>NONE</code> instead. As such, it is usually recommended to leave this field alone.

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.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.
===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>"[36,)"</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. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://my.issue.tracker/"</nowiki></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. Currently, there is no use for this property
|<code>example</code>
|-
|<code>version</code>
|string
|<code>"1"</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></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]. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://myurl.me/path/to/update.json"</nowiki></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><nowiki>"http://example.com/"</nowiki></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.]]</code>, with <code></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.
{| class="wikitable"
|-
!|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>
|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>
|}

{{Tip/Warning|When specifying dependency ordering between two or more mods, beware of cyclic order!
An example: 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]]

[[Category:Beginner Topics]]

Getting Started

2021-07-29T09:22:04Z

N1K-x: Change the gradle version

'''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/7.1.1/userguide/gradle_wrapper.html Gradle wrapper]'', Forge uses a Snapshot Version of Gradle '''7.2'''''
** <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 '''meta'''data '''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/7.1.1/userguide/tutorial_using_tasks.html Gradle User Guide for 7.1.1: ''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/7.1.1/userguide/build_environment.html#sec:gradle_configuration_properties Gradle User Guide for 7.1.1: ''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 the 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|The most popular IDEs used by Forge and mod developers are [https://www.eclipse.org/eclipseide/ Eclipse] and [https://www.jetbrains.com/idea/ IntelliJ IDEA]. While Visual Studio Code has a run generation task, because of its relative unpopularity as an IDE for Minecraft modding, the user will have to self-diagnose any issues that may arise from their use of it.}}

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

[[Category:Beginner Topics]]