Forge Community Wiki - User contributions [en-gb]

Codecs

2024-01-10T12:57:27Z

ChampionAsh5357: Reverted edits by Blabliblubpaul (talk) to last revision by Commoble

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

= Using Codecs =

== Serialization and Deserialization ==

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

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

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

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

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

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

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

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

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

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

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

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

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

= Creating Codecs =

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Which serializes the following output:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Registering MapCodecCodecs for Dispatch Subcodecs ===

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

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

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

This results in this json when serialized:

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

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

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

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

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

RecordCodecBuilder also produces MapCodecCodecs.

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

Jar-in-Jar

2023-06-06T19:45:31Z

ChampionAsh5357: Fix grammar

Jar-in-Jar is a way to handle the dependencies of your mod.
Sometimes these are libraries pulled from a central maven repository, sometimes these are libraries specially designed for Minecraft and sometimes these are completely other mods.
Whatever the reason for using a library during the development of your mods, you will need to ensure that the end user has them available when someone runs your mod in their environment.

Although there are several options available to achieve this, including for example the Shading plugin, this does not work all the time and can even cause problems along the way when for example two mods need the same dependency.
Introducing the all-new, all-shiny: Jar-In-Jar.

====Central function====
Jar-In-Jar is first and foremost a way to load dependencies for mods, from the jars of the mods.
To achieve this it looks for a file called: ''META-INF/jarjar/metadata.json''. If you are interested in the format of this file, see the following section of the JarJar library which we expose: [https://github.com/MinecraftForge/JarJar/tree/main/metadata/src/main/java/net/minecraftforge/jarjar/metadata JarJar Library - Metadata Source]

In short, this metadata file lists a set of dependencies to include, what their maven coordinate is, the accepted version range that your mod supports, the version of the dependency that is included in your mods jar as well as a path to the jar in your mods jar file.

During the startup of the game, FML will first collect all mods and then collect all their dependencies to load. Jar-In-Jar hooks into this second phase and reads all the dependency files (recursively) and then determines what versions of the dependencies to load.
====Dependency negotiation====
Because different mods might need different versions of the same dependency (and have those included) Jar-In-Jar is first and foremost a negotiation system (hence you having to supply a version range your mod supports). From all dependencies that need to be loaded their supported version range is narrowed down to the agreeable range that all mods support. Then there are in principle three outcomes that can occur:
# No agreeable version range is found: Loading can not continue and the user will see an error message that mods require different dependency versions which are not compatible.
# An agreeable version range is found, but no jar was included in any of the dependencies which have a version that fits in the agreed range: Loading can not continue and the user will see an error message that the mods have agreed upon a supported range, but no file was found with the required version.
# An agreeable version range is found, and a matching jar could be located: That dependency will be loaded.

====Dependency loading====
Once negotiation ends, the selected jars are loaded into the game.
The class loading layer is determined in two ways:
# The default way: If a mod, plugin, or language loader is detected then it is loaded in the appropriate layer and processed as such.
# The override way: If a library is supposed to be loaded which is not aware of Minecraft (for example JGraphT) then it will be loaded as a game library only. Meaning that your mod has access to it, but not plugins or language loaders. Those as such can only use libraries that are Minecraft aware or Shaded instead of Jar-In-Jarred into their respective jar.

=== Using ForgeGradle to generate a Jar-In-Jar ===
Jar-In-Jar is a completely optional system.
To enable it, you need to call `jarJar.enable()` anywhere in your buildscript.
By default, this will include all the dependencies in the `jarjar` configuration into the task output of the `jarJar` task.
''Note: The task jarJar is not accessible via the `jarJar` statement, since this references the project extension to manage Jar-In-Jar. If you need to modify the task use: `tasks.jarJar.configure { ... } `''

==== Using the runtime dependencies ====
To include the runtime dependencies as well, you can invoke `jarJar.fromRuntimeConfiguration()` which will include the dependencies which are found at the runtime. If you use this, it is highly suggested to include a dependency filter, since else every single dependency, including Minecraft, forge, and their dependencies are included as well.

==== Using dependency filters ====
While you can filter the dependencies by including them in the `jarJar` configuration or not, this is not always as flexible as you need it to be. To achieve fine grain filtering the dependency configuration endpoint has been added to the `jarJar` extension as well as to the `jarJar` task.
Using this endpoint you can configure dependency patterns (including using regular expressions) which you can include and exclude from the configuration:

===== Exclude gson example =====
dependencies {
exclude(dependency('com.google.gson.*'))
}
This example excludes any dependency which has `com.google.gson.` as a prefix of the group name of that artifact.

===== Include filters with runtime configuration usage =====
It is generally recommended to set at least one `include` filter when using the `fromRuntimeConfiguration` option.

==== Dependency version pinning ====
Since Jar-In-Jar is first and foremost a negotiation system it is required that you provide a way to supply it with a supported range, by default this is done via the version property of your dependency:
dependencies {
jarJar(group: 'com.google.code.gson', name: 'gson', version: '[2.0,3.0)')
}
However, this might not produce the required result or even the required artifact you wish to include (by default the highest supported version is included based on Gradle dependency resolution rules).
Using dependency version pinning you can specify which version of the dependency Jar-In-Jar should include when the jar is made. To achieve this configure the dependency and invoke: `jarJar.pin(<dependency instance>, "version_string")` as follows:
dependencies {
implementation(group: 'com.google.code.gson', name: 'gson', version: '[2.0,3.0)') {
jarJar.pin(it, "2.8.0")
}
}
The example above will include version 2.8.0 of the GSON library into the Jar-In-Jar jar built by the `jarJar` task.

==== Dependency range pinning ====
Next to dependency version pinning Jar-In-Jar also supports pinning the version range which your mod supports, outside of the compile dependency range that you specify in the dependency statement:
dependencies {
implementation(group: 'com.google.code.gson', name: 'gson', version: '2.8.0') {
jarJar.ranged(it, "[2.0,3.0)")
}
}
As you can see this function is very useful when you combine it with runtime configuration-based dependency selection since it allows you to use a single statement to add the dependency to your project, as well as include it with a properly supported version range within your Jar-In-Jar jar.

==== Publishing a Jar-in-Jar jar to maven ====
Although in practice this is not really useful to do, for archival reasons FG supports publishing Jar-In-Jar artifacts to a maven of choice. The setup is similar to how the Shadow plugin handles this:
publications {
mavenJava(MavenPublication) {
from components.java
jarJar.component(it)

//Other statements related to configuring the POM go here
}
}

Using this technique will add all Jar-In-Jar you build in the project to the publication at once and publish them with the other artifacts.
If you want to only publish a specific Jar-In-Jar artifact to this publication use the following statement, which accepts a task instance to achieve this:
publications {
mavenJava(MavenPublication) {
from components.java
jarJar.component(it, tasks.jarJarOther)

//Other statements related to configuring the POM go here
}
}

Sending Packets

2023-05-27T16:11:10Z

ChampionAsh5357: Move distributor list into a table

Once a packet has been added to the network, it can be called to send a message to the side it refers to. Usually there are four different directions a packet can be sent:

{| class="wikitable sortable" border=1
!Direction !!Description
|-
| <code>PLAY_TO_CLIENT</code> || A packet is sent from the server to the client during gameplay.
|-
| <code>PLAY_TO_SERVER</code> || A packet is sent from the client to the server during gameplay.
|-
| <code>LOGIN_TO_CLIENT</code> || A packet is sent to the client on initial login.
|-
| <code>LOGIN_TO_SERVER</code> || A packet is sent to the server on initial login.
|-
|}

The two login packets are handled internally by forge itself. However, the other two need to be sent using <code>SimpleChannel#send</code> for <code>SimpleChannel#sendToServer</code>. Each method takes a new instance of the message to send.

==Client Packet Locations==

* It might not always be necessary to update every single client with a packet if they are not viewing the entity or are not affected by it. To specify which clients to send a packet from the server to, a <code>PacketDistributor$PacketTarget</code> must also be passed in as a parameter. There are many helpful fields that hold simple implementations of where to send which packet within <code>PacketDistributor</code>. However, they must be supplied with the required input either via <code>PacketDistributor#with</code> or <code>PacketDistributor#noArg</code> if it is going to all players.
*

Here is a list of Forge provided <code>PacketDistributor</code>s:

{| class="wikitable sortable" border=1
!<code>PacketDistributor</code> !!Supplied Value !!Description
|-
| <code>PLAYER</code> || <code>ServerPlayer</code> || Send to the specified player .
|-
| <code>DIMENSION</code> || <code>ResourceKey<Level></code> || Send to all players within the specified dimension.
|-
| <code>NEAR</code> || <code>TargetPoint</code> || Send to all players within the range of the target point.
|-
| <code>ALL</code> || None || Send to all currently logged in players.
|-
| <code>SERVER</code> || None || Send from the player client to the server. This is the only distributor that should be used for client -> server communication.
|-
| <code>TRACKING_ENTITY</code> || <code>Entity</code> || Send to all players currently tracking the specified entity.
|-
| <code>TRACKING_ENTITY_AND_SELF</code> || <code>Entity</code> || Send to all players currently tracking the specified entity and the entity itself, if it is a player.
|-
| <code>TRACKING_CHUNK</code> || <code>LevelChunk</code> || Send to all players tracking the specified chunk.
|-
| <code>NMLIST</code> || <code>List<Connection></code> || Send to the listed connections. Each connection is typically an individual player.
|-
|}

Game Tests

2022-11-20T15:01:25Z

ChampionAsh5357: Fixing gameTestServer: reminder from a month ago

Game Tests are a way to run in-game unit tests. The system was designed to be scalable and in parallel to run large numbers of different tests efficiently. Testing object interactions and behaviors are simply a few of the many applications of this framework.

== Creating a Game Test ==

A standard Game Test follows three basic steps:

# A structure, or template, is loaded holding the scene on which the interaction or behavior is tested.
# A method conducts the logic to perform on the scene.
# The method logic executes. If a successful state is reached, then the test succeeds. Otherwise, the test fails and the result is stored within a lectern adjacent to the scene.

As such, to create a Game Test, there must be an existing template holding the initial start state of the scene and a method which provides the logic of execution.

=== The Test Method ===

A Game Test method is a <code>Consumer<GameTestHelper></code> reference, meaning it takes in a <code>GameTestHelper</code> and returns nothing. For a Game Test method to be recognized, it must have a <code>@GameTest</code> annotation:

<syntaxhighlight lang="java">
public class ExampleGameTests {
@GameTest
public static void exampleTest(GameTestHelper helper) {
// Do stuff
}
}
</syntaxhighlight>

The <code>@GameTest</code> annotation also contains members which configure how the game test should run.

<syntaxhighlight lang="java">
// In some class
@GameTest(
setupTicks = 20L, // The test spends 20 ticks to set up for execution
required = false // The failure is logged but does not affect the execution of the batch
)
public static void exampleConfiguredTest(GameTestHelper helper) {
// Do stuff
}
</syntaxhighlight>

==== Relative Positioning ====

All <code>GameTestHelper</code> methods translate relative coordinates within the structure template scene to its absolute coordinates using the structure block's current location. To allow for easy conversion between relative and absolute positioning, <code>GameTestHelper#absolutePos</code> and <code>GameTestHelper#relativePos</code> can be used respectively.

The relative position of a structure template can be obtained in-game by loading the structure via the [[#Running_Game_Tests|test command]], placing the player at the wanted location, and finally running the <code>/test pos</code> command. This will grab the coordinates of the player relative to the closest structure within 200 blocks of the player. The command will export the relative position as a copyable text component in the chat to be used as a final local variable.

{{Tip|The local variable generated by <code>/test pos</code> can specify its reference name by appending it to the end of the command:

<syntaxhighlight lang="powershell">
/test pos <var> # Exports 'final BlockPos <var> = new BlockPos(...);'
</syntaxhighlight>
}}

==== Successful Completion ====

A Game Test method is responsible for one thing: marking the test was successful on a valid completion. If no success state was achieved before the timeout is reached (as defined by <code>GameTest#timeoutTicks</code>), then the test automatically fails.

There are many abstracted methods within <code>GameTestHelper</code> which can be used to define a successful state; however, four are extremely important to be aware of.

{| class="wikitable"
|-
! Method !! Description
|-
| <code>#succeed</code> || The test is marked as successful.
|-
| <code>#succeedIf</code> || The supplied <code>Runnable</code> is tested immediately and succeeds if no <code>GameTestAssertException</code> is thrown. If the test does not succeed on the immediate tick, then it is marked as a failure.
|-
| <code>#succeedWhen</code> || The supplied <code>Runnable</code> is tested every tick until timeout and succeeds if the check on one of the ticks does not throw a <code>GameTestAssertException</code>.
|-
| <code>#succeedOnTickWhen</code> || The supplied <code>Runnable</code> is tested on the specified tick and will succeed if no <code>GameTestAssertException</code> is thrown. If the <code>Runnable</code> succeeds on any other tick, then it is marked as a failure.
|}

{{Tip/Important|Game Tests are executed every tick until the test is marked as a success. As such, methods which schedule success on a given tick must be careful to always fail on any previous tick.}}

==== Scheduling Actions ====

Not all actions will occur when a test begins. Actions can be scheduled to occur at specific times or intervals:

{| class="wikitable"
|-
! Method !! Description
|-
| <code>#runAtTickTime</code> || The action is ran on the specified tick.
|-
| <code>#runAfterDelay</code> || The action is ran <code>x</code> ticks after the current tick.
|-
| <code>#onEachTick</code> || The action is ran every tick.
|}

==== Assertions ====

At any time during a Game Test, an assertion can be made to check if a given condition is true. There are numerous assertion methods within <code>GameTestHelper</code>; however, it simplifies to throwing a <code>GameTestAssertException</code> whenever the appropriate state is not met.

=== Generated Test Methods ===

If Game Test methods need to be generated dynamically, a test method generator can be created. These methods take in no parameters and return a collection of <code>TestFunction</code>s. For a test method generator to be recognized, it must have a <code>@GameTestGenerator</code> annotation:

<syntaxhighlight lang="java">
public class ExampleGameTests {
@GameTestGenerator
public static Collection<TestFunction> exampleTests() {
// Return a collection of TestFunctions
}
}
</syntaxhighlight>

==== TestFunction ====

A <code>TestFunction</code> is the boxed information held by the <code>@GameTest</code> annotation and the method running the test.

{{Tip|Any methods annotated using <code>@GameTest</code> are translated into a <code>TestFunction</code> using <code>GameTestRegistry#turnMethodIntoTestFunction</code>. That method can be used as a reference for creating <code>TestFunction</code>s without the use of the annotation.}}

=== Batching ===

Game Tests can be executed in batches instead of registration order. A test can be added to a batch by having the same supplied <code>GameTest#batch</code> string.

On its own, batching does not provide anything useful. However, batching can be used to perform setup and teardown states on the current level the tests are running in. This is done by annotating a method with either <code>@BeforeBatch</code> for setup or <code>@AfterBatch</code> for takedown. The `#batch` methods must match the string supplied to the game test.

Batch methods are <code>Consumer<ServerLevel></code> references, meaning they take in a <code>ServerLevel</code> and return nothing:

<syntaxhighlight lang="java">
public class ExampleGameTests {
@BeforeBatch(batch = "firstBatch")
public static void beforeTest(ServerLevel level) {
// Perform setup
}

@GameTest(batch = "firstBatch")
public static void exampleTest2(GameTestHelper helper) {
// Do stuff
}
}
</syntaxhighlight>

== Registering a Game Test ==

A Game Test must be registered to be ran in-game. There are two methods of doing so: via the <code>@GameTestHolder</code> annotation or <code>RegisterGameTestsEvent</code>. Both registration methods still require the test methods to be annotated with either <code>@GameTest</code>, <code>@GameTestGenerator</code>, <code>@BeforeBatch</code>, or <code>@AfterBatch</code>.

=== GameTestHolder ===

The <code>@GameTestHolder</code> annotation registers any test methods within the type (class, interface, enum, or record). <code>@GameTestHolder</code> contains a single method which has multiple uses. In this instance, the supplied <code>#value</code> must be the mod id of the mod; otherwise, the test will not run under default configurations.

<syntaxhighlight lang="java">
@GameTestHolder(MODID)
public class ExampleGameTests {
// ...
}
</syntaxhighlight>

=== RegisterGameTestsEvent ===

<code>RegisterGameTestEvent</code> can also register either classes or methods using <code>#register</code>. The event listener must be [[Events#Event_Listeners|added]] to the mod event bus. Test methods registered this way must supply their mod id to <code>GameTest#templateNamespace</code> on every method annotated with <code>@GameTest</code>.

<syntaxhighlight lang="java">
// In some class
public void registerTests(RegisterGameTestsEvent event) {
event.register(ExampleGameTests.class);
}

// In ExampleGameTests
@GameTest(templateNamespace = MODID)
public static void exampleTest3(GameTestHelper helper) {
// Perform setup
}
</syntaxhighlight>

{{Tip|The value supplied to <code>GameTestHolder#value</code> and <code>GameTest#templateNamespace</code> can be different from the current mod id. The configuration within the [[#Enabling_Other_Namespaces|buildscript]] would need to be changed.}}

== Structure Templates ==

Game Tests are performed within scenes loaded by structures, or templates. All templates define the dimensions of the scene and the initial data (blocks and entities) that will be loaded. The template must be stored as an <code>.nbt</code> file within <code>data/<namespace>/structures</code>.

{{Tip|A structure template can be created and saved using a structure block.}}

The location of the template is specified by a few factors:

* If the namespace of the template is specified.
* If the class should be prepended to the name of the template.
* If the name of the template is specified.

The namespace of the template is determined by <code>GameTest#templateNamespace</code>, then <code>GameTestHolder#value</code> if not specified, then <code>minecraft</code> if neither is specified.

The simple class name is not prepended to the name of the template if the <code>@PrefixGameTestTemplate</code> is applied to a class or method with the test annotations and set to <code>false</code>. Otherwise, the simple class name is made lowercase and prepended and followed by a dot before the template name.

The name of the template is determined by <code>GameTest#template</code>. If not specified, then the lowercase name of the method is used instead.

<syntaxhighlight lang="java">
// Modid for all structures will be MODID
@GameTestHolder(MODID)
public class ExampleGameTests {

// Class name is prepended, template name is not specified
// Template Location at 'modid:examplegametests.exampletest'
@GameTest
public static void exampleTest(GameTestHelper helper) { /*...*/ }

// Class name is not prepended, template name is not specified
// Template Location at 'modid:exampletest2'
@PrefixGameTestTemplate(false)
@GameTest
public static void exampleTest2(GameTestHelper helper) { /*...*/ }

// Class name is prepended, template name is specified
// Template Location at 'modid:examplegametests.test_template'
@GameTest(template = "test_template")
public static void exampleTest3(GameTestHelper helper) { /*...*/ }

// Class name is not prepended, template name is specified
// Template Location at 'modid:test_template2'
@PrefixGameTestTemplate(false)
@GameTest(template = "test_template2")
public static void exampleTest4(GameTestHelper helper) { /*...*/ }
}
</syntaxhighlight>

== Running Game Tests ==

Game Tests can be run using the <code>/test</code> command. The <code>test</code> command is highly configurable; however, only a few are of importance to running tests:

{| class="wikitable"
|-
! Header text !! Header text
|-
| <code>run</code> || Runs the specified test: <code>run <test_name></code>.
|-
| <code>runall</code> || Runs all available tests.
|-
| <code>runthis</code> || Runs the nearest test to the player within 15 blocks.
|-
| <code>runthese</code> || Runs tests within 200 blocks of the player.
|-
| <code>runfailed</code> || Runs all tests that failed in the previous run.
|}

{{Tip|Subcommands follow the test command: <code>/test <subcommand></code>.}}

== Buildscript Configurations ==

Game Tests provide additional configuration settings within a buildscript (the <code>build.gradle</code> file) to run and integrate into different settings.

=== Enabling Other Namespaces ===

If the buildscript was [[Getting_Started#Customizing_the_MDK|setup as recommended]], then only Game Tests under the current mod id would be enabled. To enable other namespaces to load Game Tests from, a run configuration must set the property <code>forge.enabledGameTestNamespaces</code> to a string specifying each namespace separated by a comma. If the property is empty or not set, then all namespaces will be loaded.

<syntaxhighlight lang="gradle">
// Inside a run configuration
property 'forge.enabledGameTestNamespaces', 'modid1,modid2,modid3'
</syntaxhighlight>

{{Tip/Warning|There must be no spaces in-between namespaces; otherwise, the namespace will not be loaded correctly.}}

=== Game Test Server Run Configuration ===

The Game Test Server is a special configuration which runs a build server. The build server returns an exit code of the number of required, failed Game Tests. All failed tests, whether required or optional, are logged. This server can be run using <code>gradlew runGameTestServer</code>.

==== Failure on Successful Test Execution ====

Due to a quirk in how Gradle works, by default, if a task forces a system exit before it has finished executing, even in a zero code exit, the task will be marked as the failure. ForgeGradle sets by default a force exit on run tasks such that any subprojects are not executed in sequence. However, as such, the Game Test Server will always fail.

This can be fixed by disabling the force exit on the run configuration using the <code>#setForceExit</code> method:

<syntaxhighlight lang="gradle">
// For the Game Test Server run configuration
gameTestServer {
// ...
setForceExit false
}
</syntaxhighlight>

=== Enabling Game Tests in Other Run Configurations ===

By default, only the <code>client</code>, <code>server</code>, and <code>gameTestServer</code> run configurations have Game Tests enabled. If another run configuration should run Game Tests, then the <code>forge.enableGameTest</code> property must be set to <code>true</code>.

<syntaxhighlight lang="gradle">
// Inside a run configuration
property 'forge.enableGameTest', 'true'
</syntaxhighlight>

Block Entity Renderer

2022-10-12T19:04:17Z

ChampionAsh5357: Missed one

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

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

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

=== <code>render</code> ===
This method is called every frame in order to render the block entity.

=== Parameters ===

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

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

Block Entity Renderer

2022-10-12T19:04:05Z

ChampionAsh5357: Somehow deleted spaces without knowing, readding

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

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

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

=== <code>render</code> ===
This method is called every frame in order to render the block entity.

=== Parameters ===

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

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

Block Entity Renderer

2022-10-12T16:56:08Z

ChampionAsh5357: Grammar

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

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

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

===<code> render </code>===
This method is called every frame in order to render the block entity.

===Parameters===

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

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

Datageneration/Tags

2022-10-06T22:12:59Z

ChampionAsh5357: Finish tag providers

Tags can be generated for a mod by subclassing <code>TagsProvider</code> and implementing <code>#addTags</code>. After implementation, the provider must be added to the <code>DataGenerator</code>.

= TagsProvider =

The tags provider typically generates tags via <code>#tag</code>.

{{Tip|There is another method called <code>#getOrCreateRawBuilder</code>, but this is typically used only in cases when two registries represent the same object but in different forms (block and items).}}

When <code>#tag</code> is called, a builder is created to which the following methods can be chained:

{| class="wikitable sortable"
! Method !! Description
|-
| <code>#add</code> || Adds an object to a tag.
|-
| <code>#addOptional</code> || Adds an object to a tag through its name. If the object is not present, then the object will be skipped when loading.
|-
| <code>#addTag</code> || Adds a tag to a tag. All elements within the inner tag are now a part of the outer tag.
|-
| <code>#addOptionalTag</code> || Adds a tag to a tag through its name. If the tag is not present, then the tag will be skipped when loading.
|-
| <code>#replace</code> || When <code>true</code>, all previously loaded entries added to this tag from other datapacks will be discarded. If a datapack is loaded after this one, then it will still append the entries to the tag.
|-
| <code>#remove</code> || Removes an object or all objects within a tag from a tag. If the object is not present in the tag, nothing happens.
|}

{{Tabs/Code Snippets|
java=// In some TagProvider#addTags
this.tag(EXAMPLE_TAG)
.add(EXAMPLE_OBJECT) // Adds an object to the tag
.addOptional(new ResourceLocation("othermod", "other_object")); // Adds an object from another mod to the tag

this.tag(EXAMPLE_TAG_2)
.addTag(EXAMPLE_TAG) // Adds a tag to the tag
.remove(EXAMPLE_OBJECT); // Removes an object from this tag
}}

{{Tip/Important|If the mod's tags softly depends on another mod's tags (the other mod may or may not be present at runtime), the other mods' tags should be referenced using the optional methods.}}

== Using Existing Tag Providers ==

Vanilla contains a few tag providers for certain registries that can be subclassed for ease of implementation.

{| class="wikitable sortable"
! Registry Object Type !! Tag Provider
|-
| <code>Block</code> || <code>BlockTagsProvider</code>
|-
| <code>Item</code> || <code>ItemTagsProvider</code>
|-
| <code>EntityType</code> || <code>EntityTypeTagsProvider</code>
|-
| <code>Fluid</code> || <code>FluidTagsProvider</code>
|-
| <code>GameEvent</code> || <code>GameEventTagsProvider</code>
|-
| <code>Biome</code> || <code>BiomeTagsProvider</code>
|-
| <code>FlatLevelGeneratorPreset</code> || <code>FlatLevelGeneratorPresetTagsProvider</code>
|-
| <code>WorldPreset</code> || <code>WorldPresetTagsProvider</code>
|-
| <code>Structure</code> || <code>StructureTagsProvider</code>
|-
| <code>PoiType</code> || <code>PoiTypeTagsProvider</code>
|-
| <code>BannerPattern</code> || <code>BannerPatternTagsProvider</code>
|-
| <code>CatVariant</code> || <code>CatVariantTagsProvider</code>
|-
| <code>PaintingVariant</code> || <code>PaintingVariantTagsProvider</code>
|-
| <code>Instrument</code> || <code>InstrumentTagsProvider</code>
|}

{{Tabs/Code Snippets|
java=public class ExampleBlockTagsProvider extends BlockTagsProvider {

public ExampleBlockTagsProvider(DataGenerator gen, String modId, ExistingFileHelper efh) {
// ...
}

@Override
public void addTags() {
// Add block tags here
}
}
}}

=== ItemTagsProvider#copy ===

Blocks have item representations such that they can be obtained within an inventory. As such, a number of block tags can also be applied to a similar item tag. To easily generate an item tag with the same entries as a block tag, the <code>#copy</code> method can be used.

{{Tabs/Code Snippets|
java=// In #addTags within a ItemTagsProvider subclass
this.copy(EXAMPLE_BLOCK_TAG, EXAMPLE_ITEM_TAG);
}}

== Custom Tag Providers ==

A custom tag provider can be created via a <code>TagsProvider</code> subclass which takes in the <code>Registry</code> to generate tags for.

{{Tabs/Code Snippets|
java=public RecipeTypeTagsProvider(DataGenerator gen, String modId, ExistingFileHelper efh) {
super(gen, Registry.RECIPE_TYPE, modId, efh);
}
}}

=== Forge Registry Tag Providers ===

If a registry is wrapped by Forge or created by a mod, a provider can be created via a <code>ForgeRegistryTagsProvider</code> subclass instead:

{{Tabs/Code Snippets|
java=public AttributeTagsProvider(DataGenerator gen, String modId, ExistingFileHelper efh) {
super(gen, ForgeRegistries.ATTRIBUTES, modId, efh);
}
}}

[[Category:Data Generation]]

Making Entities

2022-10-06T21:49:38Z

ChampionAsh5357: Correct mistakes in entity attributes

{{Under construction}}

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

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

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

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

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

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

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

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

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

== Entity Attributes ==
All <code>LivingEntity</code>s must have an associated <code>AttributeSupplier</code>, which, as named, supplies the default settings for all the attributes an entity has. An <code>Attribute</code> represents a syncable piece of data representing a characteristic, quality, or feature of an entity. Vanilla and Forge both define attributes that an entity can use within <code>Attributes</code> and <code>ForgeMod</code>, respectively.

To attach an attribute to a new entity, you must create an event listener for the <code>EntityAttributeCreationEvent</code> on the '''mod''' event bus and call <code>#put</code>, providing the <code>EntityType<T></code> and the attribute supplier.

{{Tabs/Code Snippets
|java=// On the mod event bus
public void newEntityAttributes(EntityAttributeCreationEvent event) {
event.put(EXAMPLE_ENTITY_TYPE.get(),
AttributeSupplier.builder()
.add(Attributes.MAX_HEALTH) // Sets max health to default value 20
.add(Attributes.KNOCKBACK_RESISTANCE, 4.0D) // Sets knockback resistance to 4
// ...
);
}
}}

You can similarly append new attributes or modify existing attributes for existing entities by listening to <code>EntityAttributeModificationEvent</code> on the '''mod''' event bus and call <code>#add</code>, supplying the <code>EntityType<T></code>, the <code>Attribute</code>, and optionally the value if you do not want the default.

{{Tabs/Code Snippets
|java=// On the mod event bus
public void existingEntityAttributes(EntityAttributeModificationEvent event) {
if (!event.has(EntityType.CREEPER, EXAMPLE_ATTRIBUTE.get())) {
event.add(EntityType.CREEPER,
EXAMPLE_ATTRIBUTE.get() // Applies new attribute to creeper
);
}
}
}}

=== Reusable Attribute Suppliers ===

<code>LivingEntity</code> and its subclasses require specific attributes to be defined on the entity (<code>LivingEntity</code> requires max health, knockback resistance, movement speed, armor, armor toughness, swim speed, nametag distance, entity gravity, and step height addition). To make it such that subclasses can use the previously defined attribute suppliers while still being able to add or override the specified super value, a static method is used to hold the builder, which is then referenced in a later subclass. The resulting method can then be passed into the <code>EntityAttributeCreationEvent</code>.

{{Tabs/Code Snippets
|java=
// In your LivingEntity subclass
public static AttributeSupplier.Builder createExampleAttributes() {
return LivingEntity.createLivingAttributes().add(Attributes.KNOCKBACK_RESISTANCE, 4.0D);
}

// In some separate class on the mod event bus
public void newEntityAttributes(EntityAttributeCreationEvent event) {
event.put(EXAMPLE_ENTITY_TYPE.get(), ExampleEntity.createExampleAttributes().build());
}
}}

{{Tip|Most mobs use this static method attribute builder, so if you are subclassing a different entity class (e.g., <code>Mob</code>), you should look in the superclasses for the associated static method to build the attributes from (e.g., <code>Mob#createMobAttributes</code>).}}

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

Dynamic Loot Modification

2022-09-20T18:30:03Z

ChampionAsh5357: Fix the explanation

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

== Registering a Global Loot Modifier ==

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

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

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

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

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

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

== The serialized json ==

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

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

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

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

They are deserialized manually in the next section.}}

== The LootModifier Subclass ==

You will also need a <code>Codec<T></code> where <code>T</code> is your LootModifier subclass in order to deserialize your json data file into operational code. The codec must be [[Registration|registered]].

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

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

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

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

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

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

The codec can also be used for [[datageneration|data generation]] with a <code>GlobalLootModifierProvider</code>.

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

Registration

2022-06-27T21:32:22Z

ChampionAsh5357: Fix lazy in multilingual examples

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

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

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

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

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

== Methods for Registering ==

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

=== DeferredRegister ===

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

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

An example of a mod registering a custom block:

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

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

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

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

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

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

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

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

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

=== RegisterEvent ===

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

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

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

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

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

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

=== Non-Forge Registries ===

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

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

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

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

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

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

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

=== Data Driven Entries ===

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

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

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

== Referencing Registered Objects ==

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

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

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

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

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

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

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

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

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

=== Using @ObjectHolder ===

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

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

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

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

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

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

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

@ObjectHolder("minecraft:creeper")
public static Entity creeper = null; // Annotation present. [public static] is required.
// The registry has not been specified on the field.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.

@ObjectHolder(registryName = "potion")
public static final Potion levitation = null; // Annotation present. [public static] is required. [final] is optional.
// Registry name is explicitly defined: "minecraft:potion"
// Resource location is not specified on the field
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}
</syntaxhighlight>
</div>
</div>

== Creating Custom Registries ==

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

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

=== With DeferredRegister ===

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

Here is an example:

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

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

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

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

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

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

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

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

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

== Handling Missing Entries ==

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

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

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

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

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

[[Category:Common Concepts]]

Components

2022-06-18T16:16:52Z

ChampionAsh5357: Update to 1.19

'''Components''' (base interface <code>Component</code>) are forms of text used by Minecraft and Forge to concisely hold data relating to text. They form the basis of the chat system used in Minecraft. They are used for serializing and sending text data over network to players, displaying on clients, and styling for how the text appears with modifiers like bold and coloration.

There are two main types of content a component can hold: <code>LiteralContents</code>s and <code>TranslatableContents</code>s. Both serve different purposes, although you should prefer the latter one for most general mod development.

== MutableComponent ==
Components at their most basic level hold a <code>Style</code> object and a list of "sibling" components named <code>siblings</code>. In reality, these "siblings" are actually children of the main component, and are treated as such when formatting with the <code>Style</code> object. A style can be applied to a component by calling <code>withStyle</code> and <code>setStyle</code>. <code>withStyle</code> modifies the existing <code>Style</code> object with the given property, while <code>setStyle</code> replaces the current <code>Style</code> object. By default, components use a style of <code>Style.EMPTY</code>, with an empty color representing white and empty properties meaning no special chat formatting. To add a light blue color for example, one could simple call <code>theMutableComponent.withStyle(ChatFormatting.BLUE)</code>. This will merge the <code>BLUE</code> color with the existing <code>Style</code> object. When applying a parent component's <code>Style</code> to its children components, a non-null property of a child <code>Style</code> will take precedence over its parent <code>Style</code>. This means that if the color is set for both a child and parent component, the child's color will be displayed. Otherwise, non-null properties from a parent component's <code>Style</code> override properties from the child <code>Style</code> if they are null.

=== Appending siblings ===
Siblings can be appended to components similar to the plus (+) operator with Strings via <code>MutableComponent#append(Component)</code>.

== LiteralContents ==
Literal contents are the most basic form of component contents. They are raw contents that contain a single String object. These are not preferred for general mod development as they cannot be translated into other languages.

=== Creating ===
Literal contents are instantiated in the form <code>new LiteralContents("Hello, world!")</code>. A component can be created with the contents using <code>Component#literal</code>. In practice, when sent to a player, this would simply be displayed as declared: <code>Hello, world!</code>.

=== Usage ===
Literal contents are most commonly used to create empty or space-filling components, which can then be used to link multiple components together.

== TranslatableContents ==
Translatable contents are a more advanced form that support String formatting and translation into multiple languages. Translatable contents hold a '''translation key''', which is integral to translation into other languages. Translation keys are then mapped with a language file (commonly know as a lang file) to their appropriate entry for each translated language. It is important to note that the translation key is translated by the client, not the server. The server sends the translation key to the player, and the player's client converts the translation key into its fully expanded form when rendering depending on the player's selected language. If a player selects a specific language for which a translation key is not mapped, it will default to English.

=== Format modifiers ===
Translatable contents also support format modifiers like used in <code>String#format</code>. These format modifiers are declared by using the string <code>%s</code> when creating a translation entry for a given translation key. This format modifier will then be expanded and replaced with the provided object when rendered by the client. Any other format modifiers like <code>%d</code> or <code>%n</code> are ''not supported'' and will throw a formatting error. To get a normal percentage, a double percentage sign must be used (<code>%%</code>). A number can also be inserted, and it will be used as a 1-based index to select the argument. This is useful for choosing a specific argument out of order, or using the same argument twice. This looks like <code>%1$s</code>. The list of arguments to expand these format modifiers are passed to the constructor of the <code>TranslatableContents</code> using an Object varargs parameter, similar to <code>String#format</code>. The arguments passed in the constructor of a <code>TranslatableContents</code> can be either an Object or another <code>Component</code>. Any <code>Component</code>s will be expanded and have any declared <code>Style</code>s properties preserved in the final output. Any objects that are not an instance of <code>Component</code> will have <code>Object#toString</code> called during expansion.

=== Creating ===
Translatable contents are instantiated in the form <code>new TranslatableContents("your.translation_key.here", new Component.literal("thing1").withStyle(ChatFormatting.RED), new Component.literal("thing2").withStyle(ChatFormatting.BLUE))</code>. A component can be created with the contents using <code>Component#translatable</code>. In your lang file, the entry would look something like:

<syntaxhighlight lang="json">
{
"your.translation_key.here": "I like using %1$s and %2$s!"
}
</syntaxhighlight>

In practice, when sent to a player, this would be displayed as <code>I like using thing1 and thing2!</code>, where <code>thing1</code> would be colored as red and <code>thing2</code> would be colored as blue. Normal <code>String</code>s can also be passed in, and they will inherit the <code>Style</code> object of the main component. Note that any more values in the language file must be declared as comma-separated key-value pairs as required by the JSON specification, with the last key-value pair not ending with a comment.

=== Usage ===
Translatable contents are used for sending anything visual to the player. Using them provides a benefit of format modifiers and the ability to be translated into different languages. This means that, given a translator, one could translate the English translation file (by default, <code>en_us.json</code>) into another language for a given mod. This system is also used by Minecraft itself and has been used to translate the game into hundreds of languages. Translation keys are also required for declaring the names of items, blocks, and entities in the game.

[[Category:Translations]]

Key Mappings

2022-06-18T15:03:56Z

ChampionAsh5357: Update to 1.19

A '''key mapping''' or '''keybinding''' is the relation of an action to an input, such as a mouse click or a combination of key presses. The action for the keymapping is defined in the code, while the triggering input is configurable by the user through the [[:mc:Options#Controls|Controls menu]]. In the code, these key mappings are declared and represented by <code>KeyMapping</code> instances

A <code>KeyMapping</code> can be declared with the following parameters:
{| class="wikitable"
! Parameter !! Description
|-
| name || A translation key used to set the name of this key mapping (e.g. <code>key.modid.key_name</code>).
|-
| keyConflictContext || Determines when the key mapping should conflict with another defined key mapping. By default, there are three values within <code>KeyConflictContext</code>: <code>UNIVERSAL</code> which are used in every context, <code>GUI</code> which are used whenever a screen is open, and <code>IN_GAME</code> whenever a screen is not open. Custom contexts can be created by implementing <code>IKeyConflictContext</code>.
|-
| key || Determines the input context this mapping will declare by default. This is a combination of the input type, input code, and any additional modifiers. There are three possible values for the input type: <code>KEYSYM</code> which represents a mapped key, <code>SCANCODE</code> which represents the value emitted by the keyboard itself, and <code>MOUSE</code> which represents a mouse click. The associated input codes and modifiers are based on the specified input type as mapped by <code>GLFW</code>.
|-
| category || A translation key representing the category this key is located in (e.g. <code>key.modid.categories.category_name</code>).
|}
{{Tip|If you would like there to be no mapping by default, use a constructor that contains <code>InputConstants$Key</code> instead and supply <code>InputConstants#UNKNOWN</code> as the argument.}}

The <code>KeyMapping</code> can then be registered using <code>ClientRegistry::registerKeyBinding</code> within <code>FMLClientSetupEvent</code>.

== Using Registered Mappings ==

There are two contexts in which a key mapping can be used normally: in or not in a screen. As such, there are two ways to handle these mappings. When not in a screen, <code>ClientTickEvent</code> should be used to determine whether the key is down using <code>KeyMapping#isDown</code>. If within a screen, the following logic can be applied using <code>IForgeKeyMapping#isActiveAndMatches</code> within <code>GuiEventListener#keyPressed</code> and <code>GuiEventListener#mouseClicked</code> for mouse input. Note that the necessary <code>InputConstants$Key</code> can be constructed using <code>InputConstants::getKey</code> or <code>InputConstants$Type::getOrCreate</code> respectively.

Dynamic Loot Modification

2022-06-18T15:00:52Z

ChampionAsh5357: Update to 1.19

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

== Registering a Global Loot Modifier ==

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

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

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

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

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

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

== The serialized json ==

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

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

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

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

They are deserialized manually in the next section.}}

== The LootModifier Subclass ==

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

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

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

private static class Serializer extends GlobalLootModifierSerializer<WheatSeedsConverterModifier> {

@Override
public WheatSeedsConverterModifier read(ResourceLocation name, JsonObject object, LootItemCondition[] conditions) {
int numSeeds = GsonHelper.getAsInt(object, "numSeeds");
Item seed = ForgeRegistries.ITEMS.getValue(new ResourceLocation((GsonHelper.getAsString(object, "seedItem"))));
Item wheat = ForgeRegistries.ITEMS.getValue(new ResourceLocation(GsonHelper.getAsString(object, "replacement")));
return new WheatSeedsConverterModifier(conditions, numSeeds, seed, wheat);
}

@Override
public JsonObject write(WheatSeedsConverterModifier instance) {
JsonObject json = makeConditions(instance.conditions);
json.addProperty("numSeeds", instance.numSeedsToConvert);
json.addProperty("seedItem", ForgeRegistries.ITEMS.getKey(instance.itemToCheck).toString());
json.addProperty("replacement", ForgeRegistries.ITEMS.getKey(instance.itemReward).toString());
return json;
}
}
}
</syntaxhighlight>

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

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

Also take note of the <code>read</code> method in the serializer. The conditions are already deserialized for you and if you have no other data, simply <code>return new MyModifier(conditions)</code>. However, the full <code>JsonObject</code> is available if needed. The <code>write</code> method, on the other hand, is used for if you want to utilize <code>GlobalLootModifierProvider</code> for [[datageneration|data generation]].

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

BlockState JSONs

2022-06-18T14:44:16Z

ChampionAsh5357: Update to 1.19

Blockstate JSONs are Minecraft’s way to map “variant strings” to models. A variant string can be absolutely anything, from “inventory” to “power=5” to “I am your father.” They represent an actual model, where the blockstate is just a container for them. In code, a variant string within a blockstate JSON is represented by a <code>ModelResourceLocation</code>.

When the game searches for a model corresponding to a block in the world, it takes the [[BlockState JSONs|blockstate]] for that position, and then it uses a map within <code>ModelManager</code> to find the corresponding <code>ModelResourceLocation</code> for it, which then refers to the actual model. <code>BlockModelShaper</code> uses the block's registry name as the location of the blockstate JSON. (E.g. block <code>examplemod:testblock</code> goes to the <code>ResourceLocation</code> <code>examplemod:testblock</code>.) The variant string is pieced together from the <code>BlockState</code>'s properties.

As an example, let’s take a look at the vanilla <code>oak_log.json</code>:
<syntaxhighlight lang="json">
{
"variants": {
"axis=x": {
"model": "minecraft:block/oak_log_horizontal",
"x": 90,
"y": 90
},
"axis=y": {
"model": "minecraft:block/oak_log"
},
"axis=z": {
"model": "minecraft:block/oak_log_horizontal",
"x": 90
}
}
}
</syntaxhighlight>
Here we define three variant strings, and for each we use a certain model: the upright log and the sideways log (rotated about the y-axis or not). These variants will define the look of a log depending on the property axis.

A variant should be defined for every property that invokes a change in the model displayed. Any property not specified in the JSON will not have any bearing to determine the current model (e.g. '''waterlogged''' has no effect on how a model might look).

Each blockstate can be specified using one of two methods: '''variants''' and '''multiparts'''. A variant defines an associated array of states which point to the associated model to render. Note that every single property that changes the model must be defined (e.g. If 4 boolean properties defines how the model looks, then 2 ^ 4 = 16 variants must be defined). Multiparts, on the other hand, use conditions to display a certain model when true (e.g. If a model is only shown when north was true, then when that case occurs, the model will display along with any other models whose conditions are met).

For a better understanding of multiparts, let's look at a variant built fence connection:
<syntaxhighlight lang="json">
"east=true,north=false,south=false,west=false": { "model": "oak_fence_n", "y": 90, "uvlock": true }
</syntaxhighlight>
This represents one variant out of 16 possible states. Even worse, there must be models that can uniquely define unique states (a state that can be rotated to become another state is not unique for this purpose). For fences, there are 6 models: one for no connections, one connection, two connections in a straight line, two perpendicular connections, three connections, and one for all four connections.

Now let's view a modern day multipart built fence connection:
<syntaxhighlight lang="json">
{
"when": { "east": "true" },
"apply": { "model": "minecraft:block/oak_fence_side", "y": 90, "uvlock": true }
}
</syntaxhighlight>
In this case, the JSON defines that if the east connector is true, then show the model <code>minecraft:block/oak_fence_side</code> rotated 90 degrees. This allows the model to be broken up in only two files: the base post and the connection. It can also be represented as 5 statements, one that checks if each of the sides is connected and one that applies the base post unconditionally.

[[Category:Models]]

Access Transformers

2022-06-18T14:39:55Z

ChampionAsh5357: Update to 1.19

'''Access transformers''' (abbreviated as ''ATs'') are declarations for modifying or transforming the access visibility or finality of a class member (classes, fields, methods). These declarations are parsed by a transformer and applied to classes using the ASM library, either modifying the class files on-disk or modifying the class bytes during runtime.

The [https://github.com/MinecraftForge/AccessTransformers AccessTransformers] library provides a pluggable ModLauncher transformation service and a command-line application for applying access transformers on class bytes during runtime and on class files on-disk.

== Background ==
Java provides the mechanism of '''access level modifiers''' (or ''access modifiers''), to modify the ''visibility'' of a member with the modifier to other classes. This is commonly used to hide fields and methods from other classes, such as instance fields for [[:wikipedia:Encapsulation (computer programming)|encapsulation]] or private methods which are part of the implementation of the class and not normally exposed to callers.

A member can be declared with any of the modifier keywords <code>public</code>, <code>private</code>, <code>protected</code> to set the access level of the member, or none of the keywords, which defaults to a ''package-private'' access level.

The following table shows the different access levels and their modifiers, and what classes may access members with that access level:
{| class="wikitable" style="text-align:center;"
|+ Access levels
! Access modifier
! Within the same class
! Classes in the same package
! Subclasses
! All other classes
|-
| <code>public</code>
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
|-
| <code>protected</code>
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
| style="color:indianred" | '''No'''
|-
| ''no modifier''
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
| style="color:indianred" | '''No'''
| style="color:indianred" | '''No'''
|-
| <code>private</code>
| style="color:limegreen" | '''Yes'''
| style="color:indianred" | '''No'''
| style="color:indianred" | '''No'''
| style="color:indianred" | '''No'''
|}

For example, a field marked <code>protected</code> cannot be accessed by a class in another package, but can be accessed by: any class within the same package, any subclass of the class (even if the subclass belongs to another package), and within the same class where the field is declared.

Additionally to the access modifiers, there exists the <code>final</code> keyword, which:
* on classes, prevents any subclassing of the class;
* on fields, marks it as being assignable only once during construction; and
* on methods, prevents any subclasses from overriding the method with their own implementation.

Normally, Java programmers restrict access levels to be as restrictive as they need to be, controlling what is the effective publicly-available surface for the application. For example, a field may be declared as <code>private</code> while providing setter and getter methods to access the field (a technique known as encapsulation).

However, this convention of restricting access levels and marking members as <code>final</code> where approriate presents a problem with modding Minecraft, because they restrict what parts of the game that modders can access or modify, usually without other means to access or modify them (such as setters and getters for fields).

One solution is to use Java [[:wikipedia:reflection|reflection]] to reflectively access these fields and methods during runtime, but they suffer from some problems:
* Reflection is slower than regular method calls or field accesses, as certain optimizations done by the JVM cannot be applied.<ref>[https://docs.oracle.com/javase/tutorial/reflect/index.html The Java™ Tutorials: The Reflection API]: ''"Consequently, reflective operations have slower performance than their non-reflective counterparts, and should be avoided in sections of code which are called frequently in performance-sensitive applications."''</ref> This makes reflection unsuitable for performance-critical code, such as during rendering.
* Reflection cannot allow the modification of <code>final</code> fields which are either marked <code>static</code> or belong to a record class.<ref>[https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/reflect/AccessibleObject.html#setAccessible(boolean) Java 17 javadocs] for <code>java.lang.reflect.AccessibleObject.setAccessible(boolean)</code></ref>
* Runtime reflection loses the benefit of compile-time type checks, which allows dangerous operations such as trying to set a field's value to an incompatible type.
* The use of reflection does not allow a class to extend a non-visible class.

These problems are solved with the use of access transformers, which allow modification of the access modifiers of members such that they can be applied on class files on-disk to allow compiling against them, and applying the same transformer declarations on class bytes during runtime to allow classes which compiled against those transformed classes to work correctly.

== Usage ==

To use access transformers in the development environment, ForgeGradle must be configured with the location of the access transformer configuration file (or files). Because FML is hardwired to look for the configuration file at <code>META-INF/accesstransformer.cfg</code> within JAR files, it is recommended that the AT configuration file for the project be placed at the same location: within the resources folder of the main source set, or <code>src/main/resources/META-INF/accesstransformer.cfg</code>.

To configure the location of the access transformer configuration file with ForgeGradle:
<syntaxhighlight lang="gradle">
minecraft { // Within the minecraft block
// Configures FG to look at the given file path for the AT configuration file
accessTransformer = file("src/main/resources/META-INF/accesstransformer.cfg")
}
</syntaxhighlight>

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

The Forge-provided mod development environment's buildscript contains the above line but commented out, as the MDK does not ship with an access transformer file. Users of the MDK can therefore uncomment out the above line and create the AT configuration file at the same location.

Once the configuration file(s) has been added and everytime the contents or location of the file(s) changes, the developer should then refresh the Gradle nature/project in their IDE of choice for ForgeGradle to apply the access transformers to the compiled source. Each change to the access transformer configuration will trigger a full decompilation of the game.

== Declarations ==

Access transformers are declared line-by-line in configuration files, which are then parsed by ForgeGradle in the development environment and by FML in the production or end-user environment.

The <code>#</code> character and any content after that up to the end of the line is considered a comment, and will be ignored by the parser. Any lines which are either empty or consist of only whitespace or comments are ignored.

An access transformer declaration has three different variations, depending on the target to be transformed:

* for '''classes''': <code>''<modifier>'' ''<class name>''</code>
* for '''methods''': <code>''<modifier>'' ''<class name>'' ''<method name>'''''('''''[parameter descriptors]''''')'''''<return descriptor>''</code>
* for '''fields''': <code>''<modifier>'' ''<class name>'' ''<field name>''</code>

The modifier consists of one of the following words:

* <code>public</code> for the ''public'' access level (denoted by the modifier keyword of the same name)
* <code>protected</code> for the ''protected'' access level (denoted by the modifier keyword of the same name)
* <code>default</code> for the ''package-private'' access level (denoted by the absence of an access modifier keyword)
* <code>private</code> for the ''private'' access level (denoted by the modifier keyword of the same name)
* For any of the preceding words, the <code>-f</code> suffix removes the <code>final</code> modifier, while the <code>+f</code> suffix adds the modifier.

The class name is the fully qualified name of the class, using <code>.</code> (dots) to separate between (sub)packages and classes (for example, <code>java.lang.Object</code>).

For methods, the method descriptor<ref>''[https://docs.oracle.com/javase/specs/jvms/se17/html/jvms-4.html#jvms-4.3.3 Java Virtual Machine Specification, Java SE 17 Edition]'', 4.3.3. Method Descriptors </ref> of the method is included, which consists of the descriptors for each of the method's parameters and the method's return type. The method parameters descriptors can be absent if there are no parameters in the method, but the return type descriptor must be present.

The following are the matching descriptors for each type as seen in the method declaration:
{| class="wikitable"
|+ Matching type descriptors
! Descriptor
! Source form
! Description
|-
| <code>Z</code> || <code>boolean</code> || a <code>true</code> or <code>false</code> value
|-
| <code>B</code> || <code>byte</code> || a 8-bit signed number
|-
| <code>S</code> || <code>short</code> || a 16-bit signed number
|-
| <code>C</code> || <code>char</code> || a Unicode character code point in UTF-16
|-
| <code>I</code> || <code>int</code> || a 32-bit signed number
|-
| <code>F</code> || <code>float</code> || a single-precision floating-point value
|-
| <code>J</code> || <code>long</code> || a 64-bit signed number
|-
| <code>D</code> || <code>double</code> || a double-precision floating-point value
|-
| <code>[''I''</code> || <code>''int''[]</code> || one dimension of an array; this can be repeated, and must end with another descriptor other than an array
|-
| <code>L''java/lang/Object'';</code> || <code>java.lang.Object</code> || a reference type; the internal form of the class' binary name must be present (in the given example, the class referenced is <code>java.lang.Object</code>).
Note that inner classes are separated using the <code>$</code> (dollar sign) character, such as <code>java/lang/System$Logger</code>.
|-
| <code>V</code> || <code>void</code> || a void or no-value return type; only available for the return type of a method descriptor
|}

{{Tip/Danger
|title=Wildcard access transformers
|A special type of access transformers called '''wildcard ATs''' (oftentimes referred to as '''shotgun ATs''' allows transforming the access modifier and finality of ''all'' fields or methods within a class.

To use wildcard access transformers:
* for all methods within a class: <code>''<modifier>'' ''<class name>'' '''*()'''</code>
* for all fields within a class: <code>''<modifier>'' ''<class name>'' '''*'''</code>

'''Modders should avoid using this in live code.''' Access transformers should always have the fewest and narrowest targets possible, and wildcard ATs violate this convention. Use of wildcard ATs may cause problems with both the ForgeGradle setup process. Wildcard ATs may be removed in a future update of the access transformer specification.
}}

== Examples ==

The following are some examples of access transformer declarations:

<syntaxhighlight>
# Makes public the ScreenConstructor class in MenuScreens
public net.minecraft.client.gui.screens.MenuScreens$ScreenConstructor

# Makes protected the 'COLOR_WHITE' field in Gui
protected net.minecraft.client.gui.Gui f_168667_ # COLOR_WHITE

# Makes protected and removes the final modifier from 'random' field in MinecraftServer
protected-f net.minecraft.server.MinecraftServer f_129758_ # random

# Makes public the 'makeExecutor' method in Util,
# which accepts a String and returns an ExecutorService
public net.minecraft.Util m_137477_(Ljava/lang/String;)Ljava/util/concurrent/ExecutorService; # makeExecutor

# Makes public the 'leastMostToIntArray' method in UUIDUtil,
# which accepts two longs and returns an int[]
public net.minecraft.core.UUIDUtil m_235872_(JJ)[I # leastMostToIntArray
</syntaxhighlight>

Access Transformers

2022-06-18T14:39:10Z

ChampionAsh5357: Update to 1.19

'''Access transformers''' (abbreviated as ''ATs'') are declarations for modifying or transforming the access visibility or finality of a class member (classes, fields, methods). These declarations are parsed by a transformer and applied to classes using the ASM library, either modifying the class files on-disk or modifying the class bytes during runtime.

The [https://github.com/MinecraftForge/AccessTransformers AccessTransformers] library provides a pluggable ModLauncher transformation service and a command-line application for applying access transformers on class bytes during runtime and on class files on-disk.

== Background ==
Java provides the mechanism of '''access level modifiers''' (or ''access modifiers''), to modify the ''visibility'' of a member with the modifier to other classes. This is commonly used to hide fields and methods from other classes, such as instance fields for [[:wikipedia:Encapsulation (computer programming)|encapsulation]] or private methods which are part of the implementation of the class and not normally exposed to callers.

A member can be declared with any of the modifier keywords <code>public</code>, <code>private</code>, <code>protected</code> to set the access level of the member, or none of the keywords, which defaults to a ''package-private'' access level.

The following table shows the different access levels and their modifiers, and what classes may access members with that access level:
{| class="wikitable" style="text-align:center;"
|+ Access levels
! Access modifier
! Within the same class
! Classes in the same package
! Subclasses
! All other classes
|-
| <code>public</code>
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
|-
| <code>protected</code>
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
| style="color:indianred" | '''No'''
|-
| ''no modifier''
| style="color:limegreen" | '''Yes'''
| style="color:limegreen" | '''Yes'''
| style="color:indianred" | '''No'''
| style="color:indianred" | '''No'''
|-
| <code>private</code>
| style="color:limegreen" | '''Yes'''
| style="color:indianred" | '''No'''
| style="color:indianred" | '''No'''
| style="color:indianred" | '''No'''
|}

For example, a field marked <code>protected</code> cannot be accessed by a class in another package, but can be accessed by: any class within the same package, any subclass of the class (even if the subclass belongs to another package), and within the same class where the field is declared.

Additionally to the access modifiers, there exists the <code>final</code> keyword, which:
* on classes, prevents any subclassing of the class;
* on fields, marks it as being assignable only once during construction; and
* on methods, prevents any subclasses from overriding the method with their own implementation.

Normally, Java programmers restrict access levels to be as restrictive as they need to be, controlling what is the effective publicly-available surface for the application. For example, a field may be declared as <code>private</code> while providing setter and getter methods to access the field (a technique known as encapsulation).

However, this convention of restricting access levels and marking members as <code>final</code> where approriate presents a problem with modding Minecraft, because they restrict what parts of the game that modders can access or modify, usually without other means to access or modify them (such as setters and getters for fields).

One solution is to use Java [[:wikipedia:reflection|reflection]] to reflectively access these fields and methods during runtime, but they suffer from some problems:
* Reflection is slower than regular method calls or field accesses, as certain optimizations done by the JVM cannot be applied.<ref>[https://docs.oracle.com/javase/tutorial/reflect/index.html The Java™ Tutorials: The Reflection API]: ''"Consequently, reflective operations have slower performance than their non-reflective counterparts, and should be avoided in sections of code which are called frequently in performance-sensitive applications."''</ref> This makes reflection unsuitable for performance-critical code, such as during rendering.
* Reflection cannot allow the modification of <code>final</code> fields which are either marked <code>static</code> or belong to a record class.<ref>[https://docs.oracle.com/en/java/javase/16/docs/api/java.base/java/lang/reflect/AccessibleObject.html#setAccessible(boolean) Java 16 javadocs] for <code>java.lang.reflect.AccessibleObject.setAccessible(boolean)</code></ref>
* Runtime reflection loses the benefit of compile-time type checks, which allows dangerous operations such as trying to set a field's value to an incompatible type.
* The use of reflection does not allow a class to extend a non-visible class.

These problems are solved with the use of access transformers, which allow modification of the access modifiers of members such that they can be applied on class files on-disk to allow compiling against them, and applying the same transformer declarations on class bytes during runtime to allow classes which compiled against those transformed classes to work correctly.

== Usage ==

To use access transformers in the development environment, ForgeGradle must be configured with the location of the access transformer configuration file (or files). Because FML is hardwired to look for the configuration file at <code>META-INF/accesstransformer.cfg</code> within JAR files, it is recommended that the AT configuration file for the project be placed at the same location: within the resources folder of the main source set, or <code>src/main/resources/META-INF/accesstransformer.cfg</code>.

To configure the location of the access transformer configuration file with ForgeGradle:
<syntaxhighlight lang="gradle">
minecraft { // Within the minecraft block
// Configures FG to look at the given file path for the AT configuration file
accessTransformer = file("src/main/resources/META-INF/accesstransformer.cfg")
}
</syntaxhighlight>

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

The Forge-provided mod development environment's buildscript contains the above line but commented out, as the MDK does not ship with an access transformer file. Users of the MDK can therefore uncomment out the above line and create the AT configuration file at the same location.

Once the configuration file(s) has been added and everytime the contents or location of the file(s) changes, the developer should then refresh the Gradle nature/project in their IDE of choice for ForgeGradle to apply the access transformers to the compiled source. Each change to the access transformer configuration will trigger a full decompilation of the game.

== Declarations ==

Access transformers are declared line-by-line in configuration files, which are then parsed by ForgeGradle in the development environment and by FML in the production or end-user environment.

The <code>#</code> character and any content after that up to the end of the line is considered a comment, and will be ignored by the parser. Any lines which are either empty or consist of only whitespace or comments are ignored.

An access transformer declaration has three different variations, depending on the target to be transformed:

* for '''classes''': <code>''<modifier>'' ''<class name>''</code>
* for '''methods''': <code>''<modifier>'' ''<class name>'' ''<method name>'''''('''''[parameter descriptors]''''')'''''<return descriptor>''</code>
* for '''fields''': <code>''<modifier>'' ''<class name>'' ''<field name>''</code>

The modifier consists of one of the following words:

* <code>public</code> for the ''public'' access level (denoted by the modifier keyword of the same name)
* <code>protected</code> for the ''protected'' access level (denoted by the modifier keyword of the same name)
* <code>default</code> for the ''package-private'' access level (denoted by the absence of an access modifier keyword)
* <code>private</code> for the ''private'' access level (denoted by the modifier keyword of the same name)
* For any of the preceding words, the <code>-f</code> suffix removes the <code>final</code> modifier, while the <code>+f</code> suffix adds the modifier.

The class name is the fully qualified name of the class, using <code>.</code> (dots) to separate between (sub)packages and classes (for example, <code>java.lang.Object</code>).

For methods, the method descriptor<ref>''[https://docs.oracle.com/javase/specs/jvms/se16/html/jvms-4.html#jvms-4.3.3 Java Virtual Machine Specification, Java SE 16 Edition]'', 4.3.3. Method Descriptors </ref> of the method is included, which consists of the descriptors for each of the method's parameters and the method's return type. The method parameters descriptors can be absent if there are no parameters in the method, but the return type descriptor must be present.

The following are the matching descriptors for each type as seen in the method declaration:
{| class="wikitable"
|+ Matching type descriptors
! Descriptor
! Source form
! Description
|-
| <code>Z</code> || <code>boolean</code> || a <code>true</code> or <code>false</code> value
|-
| <code>B</code> || <code>byte</code> || a 8-bit signed number
|-
| <code>S</code> || <code>short</code> || a 16-bit signed number
|-
| <code>C</code> || <code>char</code> || a Unicode character code point in UTF-16
|-
| <code>I</code> || <code>int</code> || a 32-bit signed number
|-
| <code>F</code> || <code>float</code> || a single-precision floating-point value
|-
| <code>J</code> || <code>long</code> || a 64-bit signed number
|-
| <code>D</code> || <code>double</code> || a double-precision floating-point value
|-
| <code>[''I''</code> || <code>''int''[]</code> || one dimension of an array; this can be repeated, and must end with another descriptor other than an array
|-
| <code>L''java/lang/Object'';</code> || <code>java.lang.Object</code> || a reference type; the internal form of the class' binary name must be present (in the given example, the class referenced is <code>java.lang.Object</code>).
Note that inner classes are separated using the <code>$</code> (dollar sign) character, such as <code>java/lang/System$Logger</code>.
|-
| <code>V</code> || <code>void</code> || a void or no-value return type; only available for the return type of a method descriptor
|}

{{Tip/Danger
|title=Wildcard access transformers
|A special type of access transformers called '''wildcard ATs''' (oftentimes referred to as '''shotgun ATs''' allows transforming the access modifier and finality of ''all'' fields or methods within a class.

To use wildcard access transformers:
* for all methods within a class: <code>''<modifier>'' ''<class name>'' '''*()'''</code>
* for all fields within a class: <code>''<modifier>'' ''<class name>'' '''*'''</code>

'''Modders should avoid using this in live code.''' Access transformers should always have the fewest and narrowest targets possible, and wildcard ATs violate this convention. Use of wildcard ATs may cause problems with both the ForgeGradle setup process. Wildcard ATs may be removed in a future update of the access transformer specification.
}}

== Examples ==

The following are some examples of access transformer declarations:

<syntaxhighlight>
# Makes public the ScreenConstructor class in MenuScreens
public net.minecraft.client.gui.screens.MenuScreens$ScreenConstructor

# Makes protected the 'COLOR_WHITE' field in Gui
protected net.minecraft.client.gui.Gui f_168667_ # COLOR_WHITE

# Makes protected and removes the final modifier from 'random' field in MinecraftServer
protected-f net.minecraft.server.MinecraftServer f_129758_ # random

# Makes public the 'makeExecutor' method in Util,
# which accepts a String and returns an ExecutorService
public net.minecraft.Util m_137477_(Ljava/lang/String;)Ljava/util/concurrent/ExecutorService; # makeExecutor

# Makes public the 'leastMostToIntArray' method in UUIDUtil,
# which accepts two longs and returns an int[]
public net.minecraft.core.UUIDUtil m_235872_(JJ)[I # leastMostToIntArray
</syntaxhighlight>

Dependencies

2022-06-18T14:32:04Z

ChampionAsh5357: Update to 1.19

A '''dependency''' is the reliance of a piece of software on another piece of software. In the context of Minecraft Forge, it is a mod or library which another mod relies or ''depends'' on.

Dependencies are declared in three ways:
* The <code>dependencies</code> block in a Gradle buildscript defines compile-time and runtime dependencies, which are used by the build system and compiler when building or running the mod in the development environment.
* The act of using classes, fields, and methods from a library creates a dependency on the library in the compiled binaries. The library may be an explicitly declared dependency, or a dependency of an explicitly declared dependency (such as the Guava libraries that Minecraft depends on).
* [[Proper_Mod_Structuring#Dependency_Configurations|Dependency configurations]] are declared in the <tt>mods.toml</tt> metafile, which is then checked by Forge on runtime on whether they are satisfied.

== Hard and Soft Dependencies ==
There are two types of mod dependencies: hard dependencies, and soft dependencies.

A '''hard dependency''' is a dependency where the dependent mod requires that the dependency is present. This may be in the form of a code dependency, wherein the JVM will crash due to the missing class, field, or method from the dependency, or it may be in the form of a dependency configuration which mandates that the dependency is present.

Hard dependencies should be declared using a dependency configuration to allow the Forge Mod Loader to detect the missing dependency and gracefully handle it by showing an error screen to the user, rather than the JVM crashing with a non-user-friendly exception message.

A '''soft dependency''' is a dependency where the dependent mod does not require the dependency is present, but extra features or compatibility is added in the case of the dependency being present. This often takes the form of cross-mod compatibility features, where a mod soft-depends on another mod or the mod's API.

Soft dependencies usually take the form of isolated code dependencies, where the code that depends on the soft-dependency is isolated from the rest of the mod until the soft-dependency is detected as being present.

== Declaring Dependencies ==
A mod declares a dependency on a mod or library through Gradle, through the <code>dependencies</code> block.<ref>[https://docs.gradle.org/7.4.2/userguide/declaring_dependencies.html Gradle User Guide: ''Declaring dependencies'']</ref>

For example, to declare a dependency on the <code>net:minecraftforge:eventbus:5.0.3</code> library from the <code>main</code> source set:
<syntaxhighlight lang="gradle">
dependencies {
// 'implementation' is for the main source set
implementation "net.minecraftforge:eventbus:5.0.3"
}
</syntaxhighlight>

{{Tip|ForgeGradle automatically adds the [https://files.minecraftforge.net/maven/ Forge Maven] and [https://maven.apache.org/repository/ Maven Central] repositories to projects. If a dependency is not present in these (such as dependencies on other mods), the repository containing the dependency must be declared in the <code>repositories</code> block of the Gradle buildscript.<ref>[https://docs.gradle.org/current/userguide/declaring_repositories.html Gradle User Guide: ''Declaring repositories'']</ref>}}

=== Deobfuscating Dependencies ===
Mods (and libraries which use Minecraft code) are usually released as an SRG-obfuscated JAR, which prevents their direct use in development environments due to mismatch between SRG names from the mod/library and the MCP/mapped names in the development environment.

These mods/libraries must be deobfuscated to the development environment's mappings first. This is done using the <code>fg.deobf</code> function, which creates a dependency which is dynamically remapped to the local environment's mappings.

For example, to declare a dependency on the <code>mezz.jei:jei-1.16.5:7.6.1.75</code> library (which is obfuscated):
<syntaxhighlight lang="gradle">
dependencies {
implementation fg.deobf("mezz.jei:jei-1.16.5:7.6.1.75")
}
</syntaxhighlight>

=== Flat Directory Repositories ===
There are occasions where it is needed to temporarily add a dependency on a JAR file that is not present in a Maven repository, such as to add a mod which adds some developer tools during runtime. Gradle allows declaring '''flat directory repositories''', which use a local directory as a simplified repository.<ref>[https://docs.gradle.org/current/userguide/declaring_repositories.html#sub:flat_dir_resolver Gradle User Guide: ''Flat directory repository'']</ref>

A flat directory repository is declared using a <code>flatDir</code> block within the <code>repositories</code> block, and specifying directories using <code>dirs</code>:
<syntaxhighlight lang="gradle">
repositories {
flatDir {
dirs 'lib'
}
}
</syntaxhighlight>

When a dependency artifact is searched for in a flat directory repository, it will look for the following files in order (<code>''ext''</code> defaults to <code>jar</code>)<ref>[https://github.com/gradle/gradle/blob/v7.4.2/subprojects/core-api/src/main/java/org/gradle/api/artifacts/repositories/FlatDirectoryArtifactRepository.java gradle/gradle; tag v7.4.2; org.gradle.api.artifacts.repositories.FlatDirectoryArtifactRepository]</ref>:
* <code>''<artifact>''-''<version>''.''<ext>''</code>
* <code>''<artifact>''-''<version>''-''<classifier>''.''<ext>''</code>
* <code>''<artifact>''.''<ext>''</code>
* <code>''<artifact>''-''<classifier>''.''<ext>''</code>

For example, for the dependency <code>org.junit.jupiter:junit-jupiter-api:5.7.2</code>, it will first search for <code>junit-jupiter-api-5.7.2.jar</code> then <code>junit-jupiter-api.jar</code>. The group ID in the dependency descriptor must be present (due to the presence of non-flat directory repositories as added by ForgeGradle), but it will always be ignored.

{{Tip/Warning
|Flat directory repositories should ''only'' be used temporarily in a local environment, and not used to include a required dependency for your project. For a actual dependency used by your mod, use a remote Maven repository holding the artifact.
}}

=== CurseMaven ===
A commonly used alternative is [https://www.cursemaven.com/ CurseMaven](credits to Wyn Price) which allows you to depend on any file uploaded to [https://www.curseforge.com/minecraft/mc-mods/ CurseForge].

First add the CurseMaven Repository within the <code>repositories</code> block:
<syntaxhighlight lang="gradle">
repositories {
maven {
url 'https://www.cursemaven.com'
// FG4: It's recommended to uncomment the following block
// content {
// includeGroup "curse.maven"
// }
}
}
</syntaxhighlight>

Then declare a dependency using the following format:
* <code>''curse.maven'':''<description>-<project-id>'':''<file-id>''</code>

As an example, the dependency <code>curse.maven:jei-238222:3295418 </code>, would resolve to [https://www.curseforge.com/minecraft/mc-mods/jei/files/3295418 this file] on CurseForge.

For more information on usage, visit [https://www.cursemaven.com/ CurseMaven]

User:ChampionAsh5357/Sandbox/Fluids API

2022-06-15T12:23:46Z

ChampionAsh5357: Add some examples

In Forge 41.0.28, the Fluid API had been completely overhauled. These changes expanded the system to allow for custom physics logic and additional behavior not tied directly to the water and lava tags. This guide will go through all the changes and additions that Fluids now provide for you to use.

An example of the new fluid system can be found in the [https://github.com/MinecraftForge/MinecraftForge/blob/1.19.x/src/test/java/net/minecraftforge/debug/fluid/FluidTypeTest.java test mod].

== Quick Guide ==

This is a quick guide representing the one to one conversions that the Fluid API changed

* <code>FluidAttributes</code> -> <code>FluidType</code> (This is a Forge Registry ''forge:fluid_type'')
* <code>FluidAttributes#BUCKET_VOLUME</code> -> <code>FluidType#BUCKET_VOLUME</code>
* <code>FluidAttributes#getBucket</code> -> <code>FluidType#getBucket</code>
* <code>FluidAttributes#getBlock</code> -> <code>FluidType#getBlockForFluidState</code>
* <code>FluidAttributes#getStateForPlacement</code> -> <code>FluidType#getStateForPlacement</code>
* <code>FluidAttributes#canBePlacedInWorld</code> -> <code>FluidType#canBePlacedInLevel</code>
* <code>FluidAttributes#isLighterThanAir</code> -> <code>FluidType#isLighterThanAir</code>
* <code>FluidAttributes#doesVaporize</code> -> <code>FluidType#isVaporizedOnPlacement</code>
* <code>FluidAttributes#vaporize</code> -> <code>FluidType#onVaporize</code>
* <code>FluidAttributes#getDisplayName(FluidStack)</code> -> <code>FluidType#getDescription(FluidStack)</code>
* <code>FluidAttributes#getTranslationKey(FluidStack)</code> -> <code>FluidType#getDescriptionId(FluidStack)</code>
* <code>FluidAttributes#getTranslationKey</code> -> <code>FluidType#getDescriptionId</code>
* <code>FluidAttributes#getLuminosity</code> -> <code>FluidType#getLightLevel</code>
* <code>FluidAttributes#getDensity</code> -> <code>FluidType#getDensity</code>
* <code>FluidAttributes#getTemperature</code> -> <code>FluidType#getTemperature</code>
* <code>FluidAttributes#getViscosity</code> -> <code>FluidType#getViscosity</code>
* <code>FluidAttributes#isGaseous</code> -> <code>Tags$Fluids#GASEOUS</code>
* <code>FluidAttributes#getRarity</code> -> <code>FluidType#getRarity</code>
* <code>FluidAttributes#getColor</code> -> <code>IFluidTypeRenderProperties#getColorTint</code>
* <code>FluidAttributes#getStillTexture</code> -> <code>IFluidTypeRenderProperties#getStillTexture</code>
* <code>FluidAttributes#getFlowingTexture</code> -> <code>IFluidTypeRenderProperties#getFlowingTexture</code>
* <code>FluidAttributes#getOverlayTexture</code> -> <code>IFluidTypeRenderProperties#getOverlayTexture</code>
* <code>FluidAttributes#getFillSound</code> -> <code>FluidType#getSound(SoundActions.BUCKET_FILL)</code>
* <code>FluidAttributes#getEmptySound</code> -> <code>FluidType#getSound(SoundActions.BUCKET_EMPTY)</code>
* <code>FluidAttributes#getLuminosity(FluidStack)</code> -> <code>FluidType#getLightLevel(FluidStack)</code>
* <code>FluidAttributes#getDensity(FluidStack)</code> -> <code>FluidType#getDensity(FluidStack)</code>
* <code>FluidAttributes#getTemperature(FluidStack)</code> -> <code>FluidType#getTemperature(FluidStack)</code>
* <code>FluidAttributes#getViscosity(FluidStack)</code> -> <code>FluidType#getViscosity(FluidStack)</code>
* <code>FluidAttributes#isGaseous(FluidStack)</code> -> REMOVED
* <code>FluidAttributes#getColor(FluidStack)</code> -> <code>IFluidTypeRenderProperties#getColorTint(FluidStack)</code>
* <code>FluidAttributes#getStillTexture(FluidStack)</code> -> <code>IFluidTypeRenderProperties#getStillTexture(FluidStack)</code>
* <code>FluidAttributes#getFlowingTexture(FluidStack)</code> -> <code>IFluidTypeRenderProperties#getFlowingTexture(FluidStack)</code>
* <code>FluidAttributes#getFillSound(FluidStack)</code> -> <code>FluidType#getSound(FluidStack, SoundActions.BUCKET_FILL</code>
* <code>FluidAttributes#getEmptySound(FluidStack)</code> -> <code>FluidType#getSound(FluidStack, SoundActions.BUCKET_EMPTY)</code>
* <code>FluidAttributes#getLuminosity(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getLightLevel(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getDensity(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getDensity(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getTemperature(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getTemperature(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getViscosity(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getViscosity(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#isGaseous(BlockAndTintGetter, BlockPos)</code> -> REMOVED
* <code>FluidAttributes#getRarity(BlockAndTintGetter, BlockPos)</code> -> REMOVED
* <code>FluidAttributes#getColor(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getColorTint(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getStillTexture(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getStillTexture(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getFlowingTexture(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getFlowingTexture(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getFillSound(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getSound(Player, BlockGetter, BlockPos, SoundActions.BUCKET_FILL)</code>
* <code>FluidAttributes#getEmptySound(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getSound(Player, BlockGetter, BlockPos, SoundActions.BUCKET_EMPTY)</code>
* <code>FluidAttributes#getTextures</code> -> <code>IFluidTypeRenderProperties#getTextures</code>
* <code>FluidAttributes$Builder</code> -> <code>FluidType$Properties</code>
* <code>IForgeBlock#getAiPathNodeType</code> -> <code>IForgeBlock#getBlockPathType</code>
* <code>IForgeEntity#canBeRiddenInWater</code> -> <code>IForgeEntity#canBeRiddenUnderFluidType</code>
* <code>IForgeFluid#isEntityInside</code> -> REMOVED
* <code>IForgeFluid#isAABBInsideMaterial</code> -> REMOVED
* <code>IForgeFluid#getAttributes</code> -> <code>IForgeFluid#getFluidType</code>
* <code>IForgeFluidState#isEntityInside</code> -> REMOVED
* <code>ForgeFlowingFluid$Properties(Fluid, Fluid, FluidAttributes)</code> -> <code>ForgeFlowingFluid$Properties(FluidType, Fluid, Fluid)</code>
* <code>ForgeFlowingFluid#canMultiply</code> -> <code>FluidType#canConvertToSource(FluidState, LevelReader, BlockPos)</code>

== Vanilla Breaking Change: No Physics in Tags ==

One of the largest changes within the Fluid API is that Fluid Tags no longer control the physics of fluids. To account for this, a different unifying object which can represent any group of fluids must be chosen. After much consideration, this became <code>FluidType</code>, which replaced <code>FluidAttributes</code>.

=== Removal of FluidAttributes ===

<code>FluidAttributes</code> has been completely removed with most of its logic being delegated to either <code>FluidType</code> or <code>IFluidTypeRenderProperties</code> for rendering. The object itself wasn't unique and tended to be reconstructed whenever referenced. As such, it was removed in favor of a more singleton approach.

== FluidType ==

<code>FluidType</code> replaces <code>FluidAttributes</code>. All fluids must override <code>IForgeFluid#getFluidType</code> similar to the previous <code>#getAttributes</code>. Additionally, the <code>FluidType</code> can be accessed from the fluid or fluid state for convenience.

<syntaxhighlight lang="java">
private static final DeferredRegister<Fluid> FLUIDS = DeferredRegister.create(ForgeRegistries.FLUIDS, ID);

// TestFluid extends FlowingFluid
private static final RegistryObject<FlowingFluid> TEST_FLUID = FLUIDS.register("test_fluid", () -> new TestFluid() {
@Override
public FluidType getFluidType() {
return TEST_FLUID_TYPE.get();
}
});
</syntaxhighlight>

<code>FluidType</code> is a forge registry, and as such needs to be registered. If using <code>DeferredRegister</code>, you must use the one that takes in the registry name and modid since the registry does not exist during mod construction.

<syntaxhighlight lang="java">
private static final DeferredRegister<FluidType> FLUID_TYPES = DeferredRegister.create(ForgeRegistries.Keys.FLUID_TYPES, ID);

private static final RegistryObject<FluidType> TEST_FLUID_TYPE = FLUID_TYPES.register("test_fluid", () -> new FluidType(FluidType.Properties.create()));
</syntaxhighlight>

=== isVaporizedOnPlacement ===

<code>FluidType#isVaporizedOnPlacement</code> has now been expanded to allow for vaporization to occur outside of only ultra warm dimensions. To do so, simply override the method.

== IFluidTypeRenderProperties ==

<code>IFluidTypeRenderProperties</code> contains all rendering related logic to fluids. This includes the color tint, still texture, flowing texture, and overlay texture. Note that the still texture and flowing texture must be specified by overriding <code>#getStillTexture</code> and <code>#getFlowingTexture</code> respectively.

== Modified Accessors ==

All properties in <code>FluidType</code> and <code>IFluidTypeRenderProperties</code> have either an entity, level, or stack based accessor attached to it. These provide context in question if the behavior of the fluid should change in relation to the entity its acting upon, the location of the fluid in the level, or the containing fluid stack respectively.

There are some accessors with no parameters. These are typically because the use case may not be fully defined in every context that are available to the modder. They should not be used whenever possible as they may be removed in future releases once the context has been fully specified.

== Chained Methods ==

A good portion of the accessors in <code>FluidType</code> are chained in some capacity. This means that modders who are using fluids from other mods can specify unique behavior without having to modify the fluid itself. Let's take two examples: <code>#canHydrate(Level Accessor)</code> and <code>#supportsBoating</code>.

<code>#canHydrate</code> can be modified by the <code>FluidType</code>, <code>Fluid</code>, or <code>Block</code>. This means that the <code>FluidType</code> can define general behavior to use while the <code>Block</code> may define specific behavior for if it can be hydrated.

<code>#supportsBoating</code> works similarly with <code>FluidType</code> and <code>Boat</code>. The <code>FluidType</code> can define in general if boats should work on it while a specific <code>Boat</code> can determine whether it actually can float on the fluid.

== Entity Pathing ==

Entity pathing can now be specified for a given block or the underlying fluid using <code>IForgeBlock#getBlockPathType</code>, <code>IForgeBlock#getAdjacentBlockPathType</code>, <code>FluidType#getBlockPathType</code>, and <code>FluidType#getAdjacentBlockPathType</code>. For clarity, the regular block path type gets the raw type to be used if the adjacents are not specified. The adjacent path type specifically determines which one the entity will move to and will either default to <code>OPEN</code>, <code>WALKABLE</code> or <code>BLOCKED</code> internally. Typically, the entity will pathfind to the smallest positive malus of the type, where negative numbers are considered intraversable. Additional types can be created using <code>BlockPathTypes#create</code>.

== IForgeEntity ==

<code>IForgeEntity</code> now contains many additional commands to handle fluid physics logic. These include the height, which fluid the entity's eyes are in, and if an entity is in a fluid type. All of these methods are properly documented in the extension. Note that these replace their vanilla counterparts and should be used instead.

== IForgeLivingEntity ==

<code>IForgeLivingEntity</code> contains two unique fluid logic handlers: how an entity "jumps" in a fluid, and how they "sink". These methods can currently only be overridden on an entity and not by the <code>FluidType</code>.

== SoundAction ==

<code>SoundAction</code> is the abstracted sound manager for defining which sound to play in a given context. It works exactly like <code>ToolAction</code> where it simply defines a unique name that performs a given action. A new action can be created using <code>SoundAction#get</code>. Vanilla actions are defined within <code>SoundActions</code> (filling/empty bucket, vaporizing).

== Fluid Interactions ==

Fluid interactions are handled by the <code>FluidInteractionRegistry</code>. Interactions define the behavior a block should handle in all directions besides down. The down direction must be defined by the fluid in <code>FlowingFluid#spreadTo</code>, and will not be considered in this registry. An interaction can be registered using <code>#addInteraction</code> in <code>FMLCommonSetupEvent</code> by specifying the source of the interaction (which is typically the fluid being replaced), and the interaction information which defines the conditions of when the interaction should occur and what the interaction should do.

private void commonSetup(FMLCommonSetupEvent event) {
// Test Fluid + Lava (source/flowing) -> Gold Block (Test fluid source/flowing gets replaced)
FluidInteractionRegistry.addInteraction(TEST_FLUID_TYPE.get(), new FluidInteractionRegistry.InteractionInformation(ForgeMod.LAVA_TYPE.get(), Blocks.GOLD_BLOCK.defaultBlockState()));
}

== Gaseous Fluids ==

A <code>Fluid</code> is considered gaseous at room temperature if it is in the <code>forge:gaseous</code> tag. This is typically correlated with a negative density.

User:ChampionAsh5357/Sandbox/Fluids API

2022-06-15T01:43:11Z

ChampionAsh5357: Quick primer

In Forge 41.0.28, the Fluid API had been completely overhauled. These changes expanded the system to allow for custom physics logic and additional behavior not tied directly to the water and lava tags. This guide will go through all the changes and additions that Fluids now provide for you to use.

== Quick Guide ==

This is a quick guide representing the one to one conversions that the Fluid API changed

* <code>FluidAttributes</code> -> <code>FluidType</code> (This is a Forge Registry ''forge:fluid_type'')
* <code>FluidAttributes#BUCKET_VOLUME</code> -> <code>FluidType#BUCKET_VOLUME</code>
* <code>FluidAttributes#getBucket</code> -> <code>FluidType#getBucket</code>
* <code>FluidAttributes#getBlock</code> -> <code>FluidType#getBlockForFluidState</code>
* <code>FluidAttributes#getStateForPlacement</code> -> <code>FluidType#getStateForPlacement</code>
* <code>FluidAttributes#canBePlacedInWorld</code> -> <code>FluidType#canBePlacedInLevel</code>
* <code>FluidAttributes#isLighterThanAir</code> -> <code>FluidType#isLighterThanAir</code>
* <code>FluidAttributes#doesVaporize</code> -> <code>FluidType#isVaporizedOnPlacement</code>
* <code>FluidAttributes#vaporize</code> -> <code>FluidType#onVaporize</code>
* <code>FluidAttributes#getDisplayName(FluidStack)</code> -> <code>FluidType#getDescription(FluidStack)</code>
* <code>FluidAttributes#getTranslationKey(FluidStack)</code> -> <code>FluidType#getDescriptionId(FluidStack)</code>
* <code>FluidAttributes#getTranslationKey</code> -> <code>FluidType#getDescriptionId</code>
* <code>FluidAttributes#getLuminosity</code> -> <code>FluidType#getLightLevel</code>
* <code>FluidAttributes#getDensity</code> -> <code>FluidType#getDensity</code>
* <code>FluidAttributes#getTemperature</code> -> <code>FluidType#getTemperature</code>
* <code>FluidAttributes#getViscosity</code> -> <code>FluidType#getViscosity</code>
* <code>FluidAttributes#isGaseous</code> -> <code>Tags$Fluids#GASEOUS</code>
* <code>FluidAttributes#getRarity</code> -> <code>FluidType#getRarity</code>
* <code>FluidAttributes#getColor</code> -> <code>IFluidTypeRenderProperties#getColorTint</code>
* <code>FluidAttributes#getStillTexture</code> -> <code>IFluidTypeRenderProperties#getStillTexture</code>
* <code>FluidAttributes#getFlowingTexture</code> -> <code>IFluidTypeRenderProperties#getFlowingTexture</code>
* <code>FluidAttributes#getOverlayTexture</code> -> <code>IFluidTypeRenderProperties#getOverlayTexture</code>
* <code>FluidAttributes#getFillSound</code> -> <code>FluidType#getSound(SoundActions.BUCKET_FILL)</code>
* <code>FluidAttributes#getEmptySound</code> -> <code>FluidType#getSound(SoundActions.BUCKET_EMPTY)</code>
* <code>FluidAttributes#getLuminosity(FluidStack)</code> -> <code>FluidType#getLightLevel(FluidStack)</code>
* <code>FluidAttributes#getDensity(FluidStack)</code> -> <code>FluidType#getDensity(FluidStack)</code>
* <code>FluidAttributes#getTemperature(FluidStack)</code> -> <code>FluidType#getTemperature(FluidStack)</code>
* <code>FluidAttributes#getViscosity(FluidStack)</code> -> <code>FluidType#getViscosity(FluidStack)</code>
* <code>FluidAttributes#isGaseous(FluidStack)</code> -> REMOVED
* <code>FluidAttributes#getColor(FluidStack)</code> -> <code>IFluidTypeRenderProperties#getColorTint(FluidStack)</code>
* <code>FluidAttributes#getStillTexture(FluidStack)</code> -> <code>IFluidTypeRenderProperties#getStillTexture(FluidStack)</code>
* <code>FluidAttributes#getFlowingTexture(FluidStack)</code> -> <code>IFluidTypeRenderProperties#getFlowingTexture(FluidStack)</code>
* <code>FluidAttributes#getFillSound(FluidStack)</code> -> <code>FluidType#getSound(FluidStack, SoundActions.BUCKET_FILL</code>
* <code>FluidAttributes#getEmptySound(FluidStack)</code> -> <code>FluidType#getSound(FluidStack, SoundActions.BUCKET_EMPTY)</code>
* <code>FluidAttributes#getLuminosity(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getLightLevel(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getDensity(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getDensity(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getTemperature(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getTemperature(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getViscosity(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getViscosity(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#isGaseous(BlockAndTintGetter, BlockPos)</code> -> REMOVED
* <code>FluidAttributes#getRarity(BlockAndTintGetter, BlockPos)</code> -> REMOVED
* <code>FluidAttributes#getColor(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getColorTint(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getStillTexture(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getStillTexture(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getFlowingTexture(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getFlowingTexture(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getFillSound(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getSound(Player, BlockGetter, BlockPos, SoundActions.BUCKET_FILL)</code>
* <code>FluidAttributes#getEmptySound(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getSound(Player, BlockGetter, BlockPos, SoundActions.BUCKET_EMPTY)</code>
* <code>FluidAttributes#getTextures</code> -> <code>IFluidTypeRenderProperties#getTextures</code>
* <code>FluidAttributes$Builder</code> -> <code>FluidType$Properties</code>
* <code>IForgeBlock#getAiPathNodeType</code> -> <code>IForgeBlock#getBlockPathType</code>
* <code>IForgeEntity#canBeRiddenInWater</code> -> <code>IForgeEntity#canBeRiddenUnderFluidType</code>
* <code>IForgeFluid#isEntityInside</code> -> REMOVED
* <code>IForgeFluid#isAABBInsideMaterial</code> -> REMOVED
* <code>IForgeFluid#getAttributes</code> -> <code>IForgeFluid#getFluidType</code>
* <code>IForgeFluidState#isEntityInside</code> -> REMOVED
* <code>ForgeFlowingFluid$Properties(Fluid, Fluid, FluidAttributes)</code> -> <code>ForgeFlowingFluid$Properties(FluidType, Fluid, Fluid)</code>
* <code>ForgeFlowingFluid#canMultiply</code> -> <code>FluidType#canConvertToSource(FluidState, LevelReader, BlockPos)</code>

== Vanilla Breaking Change: No Physics in Tags ==

One of the largest changes within the Fluid API is that Fluid Tags no longer control the physics of fluids. To account for this, a different unifying object which can represent any group of fluids must be chosen. After much consideration, this became <code>FluidType</code>, which replaced <code>FluidAttributes</code>.

=== Removal of FluidAttributes ===

<code>FluidAttributes</code> has been completely removed with most of its logic being delegated to either <code>FluidType</code> or <code>IFluidTypeRenderProperties</code> for rendering. The object itself wasn't unique and tended to be reconstructed whenever referenced. As such, it was removed in favor of a more singleton approach.

== FluidType ==

<code>FluidType</code> replaces <code>FluidAttributes</code>. All fluids must override <code>IForgeFluid#getFluidType</code> similar to the previous <code>#getAttributes</code>. Additionally, the <code>FluidType</code> can be accessed from the fluid or fluid state for convenience.

<code>FluidType</code> is a forge registry, and as such needs to be registered. If using <code>DeferredRegister</code>, you must use the one that takes in the registry name and modid since the registry does not exist during mod construction.

=== isVaporizedOnPlacement ===

<code>FluidType#isVaporizedOnPlacement</code> has now been expanded to allow for vaporization to occur outside of only ultra warm dimensions. To do so, simply override the method.

== IFluidTypeRenderProperties ==

<code>IFluidTypeRenderProperties</code> contains all rendering related logic to fluids. This includes the color tint, still texture, flowing texture, and overlay texture. Note that the still texture and flowing texture must be specified by overriding <code>#getStillTexture</code> and <code>#getFlowingTexture</code> respectively.

== Modified Accessors ==

All properties in <code>FluidType</code> and <code>IFluidTypeRenderProperties</code> have either an entity, level, or stack based accessor attached to it. These provide context in question if the behavior of the fluid should change in relation to the entity its acting upon, the location of the fluid in the level, or the containing fluid stack respectively.

There are some accessors with no parameters. These are typically because the use case may not be fully defined in every context that are available to the modder. They should not be used whenever possible as they may be removed in future releases once the context has been fully specified.

== Chained Methods ==

A good portion of the accessors in <code>FluidType</code> are chained in some capacity. This means that modders who are using fluids from other mods can specify unique behavior without having to modify the fluid itself. Let's take two examples: <code>#canHydrate(Level Accessor)</code> and <code>#supportsBoating</code>.

<code>#canHydrate</code> can be modified by the <code>FluidType</code>, <code>Fluid</code>, or <code>Block</code>. This means that the <code>FluidType</code> can define general behavior to use while the <code>Block</code> may define specific behavior for if it can be hydrated.

<code>#supportsBoating</code> works similarly with <code>FluidType</code> and <code>Boat</code>. The <code>FluidType</code> can define in general if boats should work on it while a specific <code>Boat</code> can determine whether it actually can float on the fluid.

== Entity Pathing ==

Entity pathing can now be specified for a given block or the underlying fluid using <code>IForgeBlock#getBlockPathType</code>, <code>IForgeBlock#getAdjacentBlockPathType</code>, <code>FluidType#getBlockPathType</code>, and <code>FluidType#getAdjacentBlockPathType</code>. For clarity, the regular block path type gets the raw type to be used if the adjacents are not specified. The adjacent path type specifically determines which one the entity will move to and will either default to <code>OPEN</code>, <code>WALKABLE</code> or <code>BLOCKED</code> internally. Typically, the entity will pathfind to the smallest positive malus of the type, where negative numbers are considered intraversable. Additional types can be created using <code>BlockPathTypes#create</code>.

== IForgeEntity ==

<code>IForgeEntity</code> now contains many additional commands to handle fluid physics logic. These include the height, which fluid the entity's eyes are in, and if an entity is in a fluid type. All of these methods are properly documented in the extension. Note that these replace their vanilla counterparts and should be used instead.

== IForgeLivingEntity ==

<code>IForgeLivingEntity</code> contains two unique fluid logic handlers: how an entity "jumps" in a fluid, and how they "sink". These methods can currently only be overridden on an entity and not by the <code>FluidType</code>.

== SoundAction ==

<code>SoundAction</code> is the abstracted sound manager for defining which sound to play in a given context. It works exactly like <code>ToolAction</code> where it simply defines a unique name that performs a given action. A new action can be created using <code>SoundAction#get</code>. Vanilla actions are defined within <code>SoundActions</code> (filling/empty bucket, vaporizing).

== Fluid Interactions ==

Fluid interactions are handled by the <code>FluidInteractionRegistry</code>. Interactions define the behavior a block should handle in all directions besides down. The down direction must be defined by the fluid in <code>FlowingFluid#spreadTo</code>, and will not be considered in this registry. An interaction can be registered using <code>#addInteraction</code> in <code>FMLCommonSetupEvent</code> by specifying the source of the interaction (which is typically the fluid being replaced), and the interaction information which defines the conditions of when the interaction should occur and what the interaction should do.

== Gaseous Fluids ==

A <code>Fluid</code> is considered gaseous at room temperature if it is in the <code>forge:gaseous</code> tag. This is typically correlated with a negative density.

User:ChampionAsh5357/Sandbox/Fluids API

2022-06-14T23:06:27Z

ChampionAsh5357: Start Fluid API writing.

Registration

2022-06-14T11:29:37Z

ChampionAsh5357: Fix ObjectHolder

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

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

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

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

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

== Methods for Registering ==

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

=== DeferredRegister ===

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

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

An example of a mod registering a custom block:

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

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

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

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

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

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

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

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

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

=== RegisterEvent ===

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

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

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

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

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

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

=== Non-Forge Registries ===

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

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

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

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

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

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

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

=== Data Driven Entries ===

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

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

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

== Referencing Registered Objects ==

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

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

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

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

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

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

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

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

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

=== Using @ObjectHolder ===

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

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

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

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

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

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

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

@ObjectHolder("minecraft:creeper")
public static Entity creeper = null; // Annotation present. [public static] is required.
// The registry has not been specified on the field.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.

@ObjectHolder(registryName = "potion")
public static final Potion levitation = null; // Annotation present. [public static] is required. [final] is optional.
// Registry name is explicitly defined: "minecraft:potion"
// Resource location is not specified on the field
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}
</syntaxhighlight>
</div>
</div>

== Creating Custom Registries ==

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

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

=== With DeferredRegister ===

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

Here is an example:

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

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

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

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

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

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

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

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

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

== Handling Missing Entries ==

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

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

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

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

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

[[Category:Common Concepts]]

Custom Recipes

2022-06-13T20:07:08Z

ChampionAsh5357: Update to 1.19

Recipes are a core concept within the use of items. They allow you to transform some item into another through the use of crafting, smelting, smithing, etc. all of which can be defined in JSON through datapacks. However, the recipe system in its entirety is not only limited to what vanilla can provide. Any modder can create their own custom recipe implementation.

== Creating a New Recipe ==

Creating a new recipe boils down to three things: <code>Recipe</code>, <code>RecipeType</code>, and <code>RecipeSerializer</code>.

For a general overview:

* <code>Recipe</code>: The actual recipe implementation which handles the matching logic, construction logic, and the display data. All custom recipes need some implementation of this class.
* <code>RecipeType</code>: The category the recipe belongs to. For example, a recipe placed in the <code>#CRAFTING</code> category is expected to work within the crafting table. A custom recipe category indicates that recipes of that type will be used in that particular context.
* <code>RecipeSerializer</code>: The serializer which handles decoding the data from JSON and handling the data when syncing across the network. Each serializer can serialize to one <code>Recipe</code> implementation. The <code>type</code> field within any recipe JSON references the registry name of this serializer.

How one uses the recipe and its data is up to the implementing modder.

{{Tip/Warning|Creating a Recipe Book implementation will not be covered here. That is currently hardcoded to only accept vanilla categories.}}

=== Recipe ===

<code>Recipe</code> is an interface which holds data about the recipe being represented and how to test whether it is valid. It has a single parameterized type of some <code>Container</code> subtype. This is used to get a snapshot of the current inventory container, and as such should only be read from in this class. In most cases, this can just be left as <code>Container</code>.

The following methods must be implemented within your implementation:

{| class="wikitable"
|+ Required Methods
|-
! Method !! Description
|-
| getId || This method represents the unique name of the recipe. This usually refers to the name of the JSON file and is passed in while decoding.
|-
| getSerializer || This method represents the serializer used to decode and send this recipe across the network.
|-
| getType || This method represents the category the recipe is in.
|-
| canCraftInDimensions || This takes in a width and height and checks whether the recipe can be created within those bounds. This is only used within the Recipe Book.
|-
| matches || This method checks if the passed in inventory container can craft using the recipe stored in this class. Using the standard <code>RecipeManager</code> interface, this is always used to check whether the recipe can be used.
|-
| assemble || This creates the resulting <code>ItemStack</code> to return to the player if the recipe has been crafted. This should always return a unique instance. If you are unsure whether yours does, call <code>ItemStack#copy</code> on the decoded result before returning.
|-
| getResultItem || This shows the resulting item in displays like the Recipe Book. This does not need to return a unique instance and usually represents the decoded result directly.
|}

{{Tip/Important|If you would like to use your own recipe checker because the inventory container does not provide you with enough data, you will need to reimplement the <code>RecipeManager</code> methods yourself.}}

There are some defaulted methods as well. Although optional, they will be covered as well:

{| class="wikitable"
|+ Optional Methods
|-
! Method !! Description
|-
| getGroup || This gets the group the recipe is currently associated with. This is used by the Recipe Book to group similar recipes into one entry to reduce cluttering. This would be passed in from the decoded JSON. By default, this returns an empty string.
|-
| getIngredients || This gets the ingredients of the recipe. This is once again used by the Recipe Book to display the ingredients of the recipe. These are usually the decoded <code>Ingredient</code>s from JSON. By default, this returns an empty list.
|-
| isSpecial || This usually signals that the recipe cannot purely be represented in JSON as it has some dynamic metadata preventing it from being so. Special recipes will not appear in the Recipe Book for this reason as they provide a number of combinations which cannot be simply expressed. By default, this is false.
|-
| getToastSymbol || This returns the symbol that appears when the recipe is seen in a toast, usually from unlocking via an advancement. This is not the actual recipe output itself, but it signifies what the recipe was made within. By default this returns a crafting table stack.
|-
| getRemainingItems || This returns what items remain in the inventory container after the recipe has been created. By default, this will return a list of container items.
|-
| isIncomplete || This returns whether the supplied ingredients is empty or if any <code>Ingredient</code> has no items to test against. This is another check by the Recipe Book to prevent impossible recipes from appearing.
|}

When in practice, these will be decoded from a <code>RecipeSerializer</code> and stored in a map with a key of the <code>RecipeType</code> category it belongs to. The recipe itself is dynamically registered to the <code>RecipeManager</code> for each decoded instance.

=== RecipeType ===

<code>RecipeType</code> is another interface; however, it does not store any data itself. It is simply a forge-wrapped registry object which represents the category the <code>Recipe</code> implementation belongs to.

=== RecipeSerializer ===

<code>RecipeSerializer</code> is an interface which takes some JSON and transforms it into a <code>Recipe</code>. It is also responsible for syncing the recipe data to the client.

There are only three methods within <code>RecipeSerializer</code>, but they all must be implemented:

{| class="wikitable"
|+ Required Methods
|-
! Method !! Description
|-
| fromJson || This decodes a <code>Recipe</code> from JSON. The <code>ResourceLocation</code> id is separated from the JSON object as it represents the file name and not data within the file.
|-
| toNetwork || This encodes a <code>Recipe</code> on the server to send to the client. The data should be written to the <code>FriendlyByteBuf</code> except for the id as that has already been written.
|-
| fromNetwork || This decodes a <code>Recipe</code> on the client. Besides the id, the rest of the data can be read from the <code>FriendlyByteBuf</code> in order of insertion.
|}

{{Tip|There are some helpful methods for deserializing some objects from JSON such as <code>Ingredient#fromJson</code> and <code>CraftingHelper#getItemStack</code>.}}

This can be registered like any other forge wrapped registry object. The registry name supplied will represent the <code>type</code> supplied in the recipe JSON.

Once that is done, you can create a recipe JSON within <code>data/<modid>/recipes/<path>.json</code> and set the <code>type</code> field, along with any other data, to that handled by your serializer.

== Data Generation ==

Custom recipes can also be generated by the <code>RecipeProvider</code> or as your own implementation. For simplicity purposes, this will be addressed as if one was creating a recipe within <code>RecipeProvider#buildCraftingRecipes</code>.

For a recipe to be consumed by the data provider, whatever builder that is implemented must result in a <code>FinishedRecipe</code>.

All finished recipes must implement the following methods:

{| class="wikitable"
|+ Required Methods
|-
! Method !! Description
|-
| getId || This gets the id of the recipe. When serialized, the recipe will be saved to <code>data/<namespace>/recipes/<path>.json</code>.
|-
| getType || This gets the <code>RecipeSerializer</code> of the recipe. The registry name is set to the <code>type</code> field using this within <code>#serializeRecipe</code>.
|-
| serializeRecipeData || This encodes the data into the supplied JSON object. The data supplied should be the same as when needed to decode via the <code>RecipeSerializer</code>. The <code>type</code> field does not need to be specified as that is already set before this method is called.
|-
| getAdvancementId || This gets the advancement id of the recipe. This will be saved to <code>data/<namespace>/advancements/<path>.json</code>. Usually the path contains <code>recipes/</code> to represent it has a recipe and any other subdividing types like the <code>CreativeModeTab</code>. If unwanted, this should return <code>null</code>.
|-
| serializeAdvancement || This encodes the advancement data into a JSON. If working with an <code>Advancement$Builder</code>, this can be done simply by calling <code>Advancement$Builder#serializeToJson</code>. If unwanted, this should return <code>null</code>.
|}

Once done, have the consumer accept the finished recipe.

Registration

2022-06-13T19:50:17Z

ChampionAsh5357: Fix ObjectHolder info

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

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

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

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

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

== Methods for Registering ==

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

=== DeferredRegister ===

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

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

An example of a mod registering a custom block:

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

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

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

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

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

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

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

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

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

=== RegisterEvent ===

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

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

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

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

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

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

=== Non-Forge Registries ===

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

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

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

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

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

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

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

=== Data Driven Entries ===

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

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

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

== Referencing Registered Objects ==

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

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

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

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

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

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

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

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

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

=== Using @ObjectHolder ===

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

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

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

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

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

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

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

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

public static final Item ENDER_PEARL = null; // No annotation. [public static final] is required.
// Registry name is not explicitly defined.
// So, registry name is inherited from class annotation: "minecraft:block"
// Name path is the name of the field: "ENDER_PEARL" -> "ender_pearl"
// !! ^ Field name is valid, because they are
// converted to lowercase automatically.
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// When registering, this will attempt to force into a Block type, which is not a type or supertype of this object.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.

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

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

public static final CreativeModeTab group = null; // No annotation. [public static final] is required.
// Registry name is not explicitly defined.
// So, registry name is inherited from class annotation: "minecraft:block"
// When registering, this will attempt to force into a Block type, which is not a type or supertype of this object.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}

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

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

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

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

== Creating Custom Registries ==

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

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

=== With DeferredRegister ===

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

Here is an example:

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

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

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

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

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

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

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

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

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

== Handling Missing Entries ==

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

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

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

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

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

[[Category:Common Concepts]]

Internationalization

2022-06-13T19:45:43Z

ChampionAsh5357: Update again

'''Internationalization''' (shortened as '''i18n'''), is a way of designing code so that it requires no changes to be adapted for various languages. '''Localization''' (shortened as '''l10n''') is the process of adapting displayed text to the user’s language.

Internationalization is implemented using ''translation keys''. A translation key is a string that identifies a piece of displayable text in no specific language. For example, <code>block.minecraft.dirt</code> is the translation key referring to the name of the Dirt block. This way, displayable text may be referenced with no concern for a specific language. The code requires no changes to be adapted in a new language.

Localization will happen in the game’s locale. In a Minecraft client the locale is specified by the language settings. On a dedicated server, the only supported locale is <code>en_us</code>. A list of available locales can be found on the [https://minecraft.gamepedia.com/Language#Available_languages Minecraft Wiki].

{{Tip/Important|The only purpose of a translation key is internationalization. Do not use them for logic, such as comparing if two blocks are equal. Use their [[Registration|registry names]] instead.}}

== Language files ==

Language files are located by <code>assets/[namespace]/lang/[locale].json</code> (e.g. the US English translation for <code>examplemod</code> would be <code>assets/examplemod/lang/en_us.json</code>). The file format is simply a json map from translation keys to values. The file must be encoded in UTF-8.

<syntaxhighlight lang="json">
{
"item.examplemod.example_item": "Example Item Name",
"block.examplemod.example_block": "Example Block Name",
"commands.examplemod.example_command.error": "Example Command Errored!"
}
</syntaxhighlight>

== Usage with Blocks and Items ==

Block, Item, and a few other Minecraft classes have built-in translation keys used to display their names. These translation keys are specified by overriding <code>getDescriptionId()</code>. Item also has <code>getDescriptionId(ItemStack)</code> which can be overridden to provide different translation keys depending on <code>ItemStack</code> NBT.

By default, <code>getDescriptionId()</code> will return <code>block</code> or <code>item</code>. prepended to the registry name of the block or item, with the colon replaced by a dot. <code>BlockItem</code>s will take their corresponding Block's translation key by default. For example, an item with ID <code>examplemod:example_item</code> effectively requires the following line in a language file:

<syntaxhighlight lang="json">
{
"item.examplemod.example_item": "Example Item Name"
}
</syntaxhighlight>

== Localization methods ==

{{Tip/Important|A common issue is having the server localize for clients. The server can only localize in its own locale, which does not necessarily match the locale of connected clients.
<br/><br/>
To respect the language settings of clients, the server should have clients localize text in their own locale using components with <code>TranslatableContents</code> or other methods preserving the language neutral translation keys.}}

<h3 id="I18n"><tt style="font-size: 100%">net.minecraft.client.resources.language.I18n</tt></h3>

{{Tip/Danger|'''This I18n class can only be found on the [[Sides#Different_Kinds_of_Sides|physical client]]!''' It is intended to be used by code that only runs on the client. Attempts to use this on a server will throw exceptions and crash.}}

<code>get(String, Object...)</code> localizes in the client’s locale with formatting. The first parameter is a translation key, and the rest are formatting arguments for <code>String.format(String, Object...)</code>.

=== <tt style="font-size: 100%">TranslatableContents</tt> ===

<code>TranslatableContents</code> is a <code>ComponentContents</code> that is localized and formatted lazily. It is very useful when sending messages to players because it will be automatically localized in their own locale.

The first parameter of the <code>TranslatableContents(String, Object...)</code> constructor is a translation key, and the rest are used for formatting. The only supported format specifiers are <code>%s</code> and <code>%1$s</code>, <code>%2$s</code>, <code>%3$s</code> etc. Formatting arguments may be other <code>Component</code>s that will be inserted into the resulting formatted text with all their attributes preserved.

A <code>MutableComponent</code> can be created using <code>Component#translatable</code> by passing in the <code>TranslatableContents</code>'s parameters. It can also be created using <code>MutableComponent#create</code> by passing in the <code>ComponentContents</code> itself.

[[Category:Common Concepts]]

Sides

2022-06-13T19:43:53Z

ChampionAsh5357: Update to 1.19

{{Under construction}} 
A very important concept to understand when modding Minecraft are the two sides: '''client''' and '''server'''. There are many, many common misconceptions and mistakes regarding siding, which can lead to bugs that might not crash the game, but can rather have unintended and often unpredictable effects.

== Different Kinds of Sides ==

When we say "client" or "server", it usually follows with a fairly intuitive understanding of what part of the game we’re talking about. After all, a client is what the user interacts with, and a server is where the user connects for a multiplayer game. Easy, right?

But because of the structure of how Minecraft works, there can be some ambiguity even with two such terms. Here we disambiguate the four possible meanings of "client" and "server":

* '''Physical Client''' - The ''physical client'' is the entire program that runs whenever you launch Minecraft from the launcher. All threads, processes, and services that run during the game’s graphical, interactable lifetime are part of the physical client.
* '''Physical Server''' - Often known as the dedicated server, the ''physical server'' is the entire program that runs whenever you launch any dedicated server executable or JAR (<code>minecraft_server.jar</code>) that does not bring up a playable GUI.
* '''Logical Server''' - The ''logical server'' is what runs game logic: mob spawning, weather, updating inventories, health, AI, and all other game mechanics. The logical server is present within the physical server, but is also can run inside a physical client together with a logical client, as a single player world. The logical server always runs in a thread named the <code>Server Thread</code>.
* '''Logical Client''' - The ''logical client'' is what accepts input from the player and relays it to the logical server. In addition, it also receives information from the logical server and makes it available graphically to the player. The logical client runs in the <code>Render Thread</code>, though often several other threads are spawned to handle things like audio and chunk render batching.

In the Minecraft codebase, the physical sides are represented by an enum called <code>Dist</code>, while the logical sides are represented by an enum called <code>LogicalSide</code>.

{{Tip|It is guaranteed that the logical cient always runs on the physical client; however, the same cannot be said of the logical server.}}

== Performing Side-Specific Operations ==

=== <tt>Level#isClientSide</tt> ===

This <code>boolean</code> check is the most common way (and the most recommended way) to check the currently running '''logical side'''. Querying this field on a <code>Level</code> object establishes the logical side that the level belongs to. That is, if this field is <code>true</code>, the level extends <code>ClientLevel</code> and is currently running on the logical client, while if the field is <code>false</code>, the level extends <code>ServerLevel</code> and is running on the logical server.

It follows that the physical/dedicated server will always contain <code>false</code> in this field, but we cannot assume that <code>false</code> implies a physical server, since this field can also be <code>false</code> for the logical server inside a physical client (in other words, a single player world).

Use this check whenever you need to determine if game logic and other mechanics should be run. For example, if you want to damage the player every time they click your block, or have your machine process dirt into diamonds, you should only do so after ensuring <code>level#isClientSide</code> is <code>false</code>. Applying game logic to the logical client can cause desynchronization (ghost entities, desynchronized stats, etc.) in the best case, and crashes in the worst case.

This check should be used as your go-to default. Aside from the sided events and <code>DistExecutor</code>, rarely will you need the other ways of determining sides and adjusting behavior.

=== Sided Setup Events ===

There are different events which are fired at different stages during the [[Stages_of_Modloading|modloading process]]. Most of these events are fired on both physical sides, except for the '''sided setup events''': <code>FMLClientSetupEvent</code> and <code>FMLDedicatedServerSetupEvent</code>, which is fired on the physical client and the physical/dedicated server respectively.

These events should be used for running side-specific initialization code. It is recommended to either put your sided event handler registration behind a <code>DistExecutor</code> call, or use the <code>@Mod.EventBusSubscriber</code> anntoation with '<code>value = Dist.CLIENT</code> for clients (or <code>value = Dist.DEDICATED_SERVER</code> for the dedicated server) to conditionally register your event handlers and prevent the classes referenced within from crashing upon being loaded.

=== <tt>DistExecutor</tt> ===

Considering the use of a single "universal" jar for client and server mods, and the separation of the physical sides into two jars, an important question comes to mind: How do we use code that is only present on one physical side? All code in <code>net.minecraft.client</code> (such as anything rendering-related) is only present on the physical client, and all code in <code>net.minecraft.server.dedicated</code> is only present on the physical server.

If any class you write references those names in any way, they will crash the game when that respective class is loaded in an environment where those names do not exist. For example, a very common mistake in beginners is to call <code>Minecraft.getMinecraft().<doStuff>()</code> in block or block entity classes, which will crash any physical/dedicated server as soon as the class is loaded.

How do we resolve this? Forge provides the <code>DistExecutor</code> utility class, which provides various methods to run and call different code depending on the physical side. There are two versions of each method: <code>safe*</code> and <code>unsafe</code>. <code>safe*</code> methods accept a supplied method reference from another class; otherwise, an error will be thrown. <code>unsafe*</code> methods accept a doubly supplied instance instead. <code>unsafe*</code> methods could cause <code>ClassNotFoundException</code>s depending on how they are used, though in standard cases referencing an external class within the double supplier should be safe. In any case, make sure you understand how the [https://docs.oracle.com/javase/specs/jvms/se16/html/jvms-5.html#jvms-5.4.1 class verifier] works to load classes before using this.

{{Tip/Important|
It is important to understand that <code>DistExecutor</code> checks the '''physical''' side. A single player world (logical server + logical client within a physical client) will always use <code>Dist.CLIENT</code>!}}

=== Thread Groups ===

If <code>Thread.currentThread().getThreadGroup() == SidedThreadGroups.SERVER</code>, it is likely the current thread is on the logical server. Otherwise, it is likely on the logical client. This is useful to retrieve the '''logical''' side when you do not have access to a <code>Level</code> object to check <code>isClientSide</code>. It ''guesses'' which logical side you are on by looking at the thread group of the currently running thread. Because it is a guess, this method should only be used when other options have been exhausted. In all other cases, you should prefer checking <code>level#isClientSide</code> to this check.

=== <tt>FMLEnvironment.dist</tt> ===

<code>FMLEnvironment.dist</code> holds the '''physical''' side your code is running on, as a value of <code>Dist.CLIENT</code> or <code>Dist.DEDICATED_SERVER</code>. This is determined by the mod loading code, so it always hold the correct value. However, there is little reason to directly query this variable, as most use-cases can use <code>DistExecutor</code> instead (which uses this value internally).

== <tt>@OnlyIn</tt> ==

Annotating a method or field with the <code>@OnlyIn(Dist)</code> annotation indicates to the loader that the respective member should be completely stripped out of the definition not on the specified '''physical''' side. Usually, these are only seen when browsing through the decompiled Minecraft code, indicating methods that the Mojang obfuscator stripped out.

{{Tip/Important|There is '''NO''' reason for using this annotation directly. Use <code>DistExecutor</code> or a check on <code>FMLEnvironment.dist</code> instead.}}

== Common Mistakes ==

=== Reaching Across Logical Sides ===

Whenever you want to send information from one logical side to another, you must '''always''' use [[SimpleChannel|network packets]]. It is incredibly tempting, when in a single player scenario, to directly transfer data from the logical server to the logical client.

This is actually very commonly inadvertently done through static fields. Since the logical client and logical server share the same JVM instance in a single player scenario, both threads writing to and reading from static fields will cause all sorts of race conditions and classical issues associated with threading.

This mistake can also be made explicitly by accessing physical client-only classes such as <code>Minecraft</code> from common code that runs or can run on the logical server. This mistake is easy to miss for beginners, who debug in a physical client. The code will work there, but will immediately crash on a physical server. For this reason, it is always recommended to test your mod with the physical/dedicated server.

===Writing One-Sided Mods===
Your mods are expected to always load, regardless of if they are loaded on the client or the server. For one-sided mods, this means that they must still run on the opposite physical side.

So for one-sided mods, you would typically register your event handlers using [[#DistExecutor|<code>DistExecutor</code>]] or <code>@EventBusSubscriber(value = Dist.*)</code>, instead of directly calling the relevant registration methods in the constructor. The idea is that, if your mod is loaded on the wrong side, it should simply do nothing: listen to no events, do no special behaviors, and so on. A one-sided mod by nature should not register blocks, items, … since they would need to be available on the other side, too.

Additionally, if your mod is one-sided, it typically does not forbid the user from joining a server that is lacking that mod. Therefore, you should set the <code>displayTest</code> property in your [[Mods.toml|mods.toml]] to whatever value is necessary.

<syntaxhighlight lang="toml>
[[mods]]
# ...
# MATCH_VERSION means that your mod will cause a red X if the versions on client and server differ. This is the default behaviour and should be what you choose if you have server and client elements to your mod.
# IGNORE_SERVER_VERSION means that your mod will not cause a red X if it's present on the server but not on the client. This is what you should use if you're a server only mod.
# IGNORE_ALL_VERSION means that your mod will not cause a red X if it's present on the client or the server. This is a special case and should only be used if your mod has no server component.
# NONE means that no display test is set on your mod. You need to do this yourself, see IExtensionPoint.DisplayTest for more information. You can define any scheme you wish with this value.
# IMPORTANT NOTE: this is NOT an instruction as to which environments (CLIENT or DEDICATED SERVER) your mod loads on. Your mod should load (and maybe do nothing!) whereever it finds itself.
displayTest="IGNORE_ALL_VERSION" # MATCH_VERSION is the default if nothing is specified (#optional)
</syntaxhighlight>

If a custom display test is to be used, then the <code>displayTest</code> option should be set to <code>NONE</code>, and an <code>IExtensionPoint$DisplayTest</code> extension should be registered:

{{Template:Tabs/Code_Snippets
|java=// Make sure the mod being absent on the other network side does not cause the client to display the server as incompatible
ModLoadingContext.get().registerExtensionPoint(IExtensionPoint.DisplayTest.class, () -> new IExtensionPoint.DisplayTest(() -> NetworkConstants.IGNORESERVERONLY, (a, b) -> true));
|kotlin=// Make sure the mod being absent on the other network side does not cause the client to display the server as incompatible
ModLoadingContext.get().registerExtensionPoint(IExtensionPoint.DisplayTest.class) { IExtensionPoint.DisplayTest(Supplier { NetworkConstants.IGNORESERVERONLY }, BiPredicate { _: String, _: Boolean -> true }) }
|scala=import scala.compat.java8.FunctionConverters._
// Make sure the mod being absent on the other network side does not cause the client to display the server as incompatible
ModLoadingContext.get.registerExtensionPoint(IExtensionPoint.DisplayTest.class, (() => new IExtensionPoint.DisplayTest((() => NetworkConstants.IGNORESERVERONLY).asJava, asJavaBiPredicate((_: String, _: java.lang.Boolean) => true))).asJava)
|}}

This tells the client that it should ignore the server version being absent, and tells the server that it should not tell the client this mod should be present.

[[Category:Common Concepts]]

Mods.toml

2022-06-13T19:34:15Z

ChampionAsh5357: Basic display test info

{{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.19 is version 41
loaderVersion="[41,)"
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.
'''
displayTest="MATCH_VERSION"

[[dependencies.examplemod]]
modId="forge"
mandatory=true
versionRange="[41,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.19,1.20)"
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>"[41,)"</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>
|-
|<code>displayTest</code>
|string
|<code>"MATCH_VERSION"</code>
|Controls the display of the mod in the server connection screen. Must be either <code>MATCH_VERSION</code>, <code>IGNORE_SERVER_VERSION</code>, <code>IGNORE_ALL_VERSION</code>, or <code>NONE</code>.
|<code>"IGNORE_ALL_VERSION"</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]]

Getting Started

2022-06-13T19:27:01Z

ChampionAsh5357: Buildscript updates

'''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.4.2/userguide/gradle_wrapper.html Gradle wrapper]'', Forge uses Version '''7.4.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.4.2/userguide/tutorial_using_tasks.html Gradle User Guide for 7.4.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.4.2/userguide/build_environment.html#sec:gradle_configuration_properties Gradle User Guide for 7.4.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>
#* For '''Visual Studio Code''': Run <code>./gradlew buildNeeded</code> and then <code>./gradlew eclipse</code>, then <tt>File > Open Folder...</tt> and select the folder
# Wait for the setup process to complete and the Minecraft sources are decompiled.
#* For '''Visual Studio Code''': This step can be skipped as it was already done in the previous step
# Generate the run configurations for your IDE using the appropriate Gradle task. <br>These tasks can be run in the terminal using <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 [https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack Extension Pack for Java] and [https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-gradle Gradle for Java 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>id '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 four 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.
* <code>runGameTestServer</code>, for starting a build server to run [[Game_Tests|game tests]].

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

Making Tools

2022-06-12T18:52:37Z

ChampionAsh5357: Update to 1.19

Tools are simply an extension of the <code>Item</code> class. Their implementations mainly rely on extending a specific class, the <code>TierSortingRegistry</code>, and tags.

== <tt>Tier</tt> ==

To create any tool that does not derive from vanilla tiers, you will need your own implementation of <code>Tier</code>. This is the basis of which all tool levels are created. If you would like to use a vanilla tier, then you should specify one of the enums within <code>Tiers</code>.

Here are what each methods defines:
{| class="wikitable sortable" border=1
!Method !!Return Type !!Description
|-
| <code>getUses</code> || <code>Integer</code> || The durability of all items in this tier.
|-
| <code>getSpeed</code> || <code>Float</code> || The efficiency multiplier of all items in this tier.
|-
| <code>getAttackDamageBonus</code> || <code>Float</code> || The base attack damage of all items in this tier.
|-
| <code>getLevel</code> || <code>Integer</code> || The harvest level of this tier. Vanilla uses values 0-4. As of 37.0.31, Forge deprecates this value in favor of the sorting registry system discussed below. This value will be used if the tier is not registered however.
|-
| <code>getEnchantmentValue</code> || <code>Integer</code> || How enchantable an item of this tier is.
|-
| <code>getRepairIngredient</code> || <code>Ingredient</code> || What ingredient can be used to repair this item.
|-
| <code>getTag</code> || <code>TagKey<Block></code> || What blocks this tier can mine. This should only encompass those blocks which are specific for this tier. Any blocks below this tier will be declared while registering. The naming convention of this tag is <code><modid>:needs_<tier_name>_tool</code>.
|-
|}

{{Tip/Important|An ingredient should be wrapped in a supplier to avoid calling the object directly. Tiers are loaded before registries are populated, so the call to the item needs to be deferred.}}

{{Tip|Forge has a implementation class called <code>ForgeTier</code> to create a common tier, though this does not have to be used.}}

== <tt>TierSortingRegistry</tt> ==

For a tier to be used in the new system, they need to be registered before items most commonly by static initialization. A tier can be registered via <code>TierSortingRegistry#registerTier</code>. Any tier not defined in the sorting system will be defaulted to vanilla behavior.

This has four parameters:
{| class="wikitable sortable" border=1
!Parameter !!Type !!Description
|-
| <code>tier</code> || <code>Tier</code> || The tier object being registered.
|-
| <code>name</code> || <code>ResourceLocation</code> || The name of the tier for dependency resolution.
|-
| <code>after</code> || <code>List<Object></code> || The list of tiers to place this tier after or the tiers of the same level that are weaker than this one. This can either be a <code>String</code>, <code>ResourceLocation</code>, or <code>Tier</code> where the first two are located by the <code>name</code> parameter above.
|-
| <code>before</code> || <code>List<Object></code> || The list of tiers to place this tier before or the tiers of the same level that are stronger than this one. This can either be a <code>String</code>, <code>ResourceLocation</code>, or <code>Tier</code> where the first two are located by the <code>name</code> parameter above.
|-
|}

{{Tip|If your tier is equivalent to another tier, then <code>Tier#getTag</code> should return an empty tag reference defined by <code>BlockTags#createOptional</code> and have the equivalent tier be placed in the <code>after</code> list when registering. If the tier is a vanilla tier, you should also specify the next tier above in the <code>before</code> list.}}

== <tt>DiggerItem</tt> ==

<code>DiggerItem</code> is the base of which all tool items extend. You do not necessarily have to use this or any of its supertypes/subtypes. However, it is convenient if you are looking for standard behavior. The subtypes normally referenced are <code>AxeItem</code>, <code>HoeItem</code>, <code>PickaxeItem</code>, <code>ShovelItem</code>.

Each tool has four parameters: tier, attack damage, attack speed, and properties. Tiers and properties have already been explained in this and within the [[Making Items|item]] docs. Attack damage specifies how much damage to do above the current base set for that specific tier. Attack speed specifies the speed modifier to apply to your current attack speed (the base attack speed for a player is <code>4.0D</code>).

{{Tip|content=If you decide to extend <code>DiggerItem</code>, there will be a fifth parameter which defines a tag of which blocks this item is effective on. The naming convention of these tags is <code><modid>:mineable/<tool_name></code>. If this tag should be shared among other mods, the <code>forge</code> namespace should be used instead. }}

A tool's compatibility and partial implementation is defined by three methods:
{| class="wikitable sortable" border=1
!Method !!Return Type !!Description
|-
| <code>getDestroySpeed</code> || <code>Float</code> || Defines whether a block will be mined faster than an empty hand or wrong tool.
|-
| <code>isCorrectToolForDrops</code> || <code>Boolean</code> || Defines which blocks can drop loot with your tool. If this returns false, then the destroy speed will always slow down mining. This should only be overridden if your item is not a <code>DiggerItem</code> to implement <code>TierSortingRegistry#isCorrectTierForDrops</code> which handles this logic.
|-
| <code>canPerformAction </code> || <code>Boolean</code> || Queries whether a block can perform the associated action. By default, this will do nothing on its own since a <code>ToolAction</code> is just a string. This can be combined with other logic to get the result of the performed action, usually by doing <code>BlockState#getToolModifiedState</code>. New tool actions can be defined via <code>ToolAction#get</code>.
|-
|}

== Registering ==

A tool must be [[Registration|registered]] the same as an item. Defining the tool type and tier level is done via the mineable tag implemented on your tool and the tier tag on your <code>Tier</code>.

[[Category:Items]]

BlockStates

2022-06-12T18:46:30Z

ChampionAsh5357: Wrong param

== Introduction of States ==

The block state system abstracts out the details of the block's properties from the other behaviors of the block.

Each <code>property</code> of a block is described by an instance of <code><nowiki>Property<?></nowiki></code>. Examples of block properties include instruments (<code><nowiki>Property<NoteBlockInstrument></nowiki></code>), direction (<code><nowiki>Property<Direction></nowiki></code>), poweredness (<code><nowiki>Property<Boolean></nowiki></code>), etc. Each property has the value of the type <code><nowiki>T</nowiki></code> parametrized by <code><nowiki>Property<T></nowiki></code>.

A unique triple can be constructed from the <code><nowiki>Block</nowiki></code>, the set of <code><nowiki>Property<?></nowiki></code>, and the set of values for those properties. This unique triple is called a <code><nowiki>BlockState</nowiki></code>. For example, a stone button which is facing east and is powered or held down is represented by <code><nowiki>minecraft:stone_button[facing=east,powered=true]</nowiki></code>.

== Proper Usage of Block States ==

<code><nowiki>BlockState</nowiki></code> is a flexible and powerful system, but it also has limitations. <code><nowiki>BlockState</nowiki></code>s are immutable, and all combinations of their properties are generated on startup of the game. This means that having a <code><nowiki>BlockState</nowiki></code> with many properties and possible values will slow down the loading of the game, and befuddle anyone trying to make sense of your block logic.

Not all blocks and situations require the usage of <code><nowiki>BlockState</nowiki></code>; only the most basic properties of a block should be put into one, and any other situation is better off with having a <code><nowiki>BlockEntity</nowiki></code> or being a separate <code><nowiki>Block</nowiki></code>. Always consider if you actually need to use a state for your purposes.

{{Colored box|title=Tip|content=A good rule of thumb is: '''if it has a different name, it should be a separate block'''.}}

An example is making chair blocks: the ''direction'' of the chair should be a ''property'', while the different ''types of wood'' should be separated into different blocks.
An "Oak Chair" facing east (<code><nowiki>oak_chair[facing=east]</nowiki></code>) is different from a "Spruce Chair" facing west (<code><nowiki>spruce_chair[facing=west]</nowiki></code>).

== Implementing Block States ==

In your Block class, create or reference <code><nowiki>static final</nowiki></code> <code><nowiki>Property<?></nowiki></code> objects for every property that your Block has. You are free to make your own <code><nowiki>Property<?></nowiki></code> implementations, but the means to do that are left as an exercise to the reader. The vanilla code provides several convenience implementations:

* <code><nowiki>IntegerProperty</nowiki></code>
** Implements <code><nowiki>Property<Integer></nowiki></code>. Defines a property that holds an integer value.
** Created by calling <code><nowiki>IntegerProperty.create(String propertyName, int minimum, int maximum)</nowiki></code>.
* <code><nowiki>BooleanProperty</nowiki></code>
** Implements <code><nowiki>Property<Boolean></nowiki></code>. Defines a property that holds a <code><nowiki>true</nowiki></code> or <code><nowiki>false</nowiki></code> value.
** Created by calling <code><nowiki>BooleanProperty.create(String propertyName)</nowiki></code>.
* <code><nowiki>EnumProperty<E extends Enum<E>></nowiki></code>
** Implements <code><nowiki>Property<E></nowiki></code>. Defines a property that can take on the values of an Enum class.
** Created by calling <code><nowiki>EnumProperty.create(String propertyName, Class<E> enumClass)</nowiki></code>.
** It is also possible to use only a subset of the Enum values (e.g. <code><nowiki>RailShape</nowiki></code>s that can only ascend and not turn). See the overloads of <code><nowiki>EnumProperty.create</nowiki></code>.
* <code><nowiki>DirectionProperty</nowiki></code>
** This is a convenience implementation of <code><nowiki>EnumProperty<Direction></nowiki></code>
** Several convenience predicates are also provided. For example, to get a property that represents the cardinal directions, call <code><nowiki>DirectionProperty.create("<name>", Direction.Plane.HORIZONTAL)</nowiki></code>; to get the X directions, <code><nowiki>DirectionProperty.create("<name>", Direction.Axis.X)</nowiki></code>

The class <code><nowiki>BlockStateProperties</nowiki></code> contains shared vanilla properties which should be used or referenced whenever possible, in place of creating your own properties.

When you have your desired <code><nowiki>Property<></nowiki></code> objects, override <code><nowiki>Block#createBlockStateDefinition(StateDefinition$Builder)</nowiki></code> in your ''Block'' class. In that method, call <code><nowiki>StateDefinition$Builder#add(...);</nowiki></code> with the parameters as every <code><nowiki>Property<?></nowiki></code> you wish the block to have.

Every block will also have a "default" state that is automatically chosen for you. You can change this "default" state by calling the <code><nowiki>Block#registerDefaultState(BlockState)</nowiki></code> method from your constructor. When your block is placed it will become this "default" state. An example from <code><nowiki>DoorBlock</nowiki></code>:

<syntaxhighlight lang="java">
this.registerDefaultState(
this.stateDefinition.any()
.setValue(FACING, Direction.NORTH)
.setValue(OPEN, false)
.setValue(HINGE, DoorHingeSide.LEFT)
.setValue(POWERED, false)
.setValue(HALF, DoubleBlockHalf.LOWER)
);
</syntaxhighlight>

If you wish to change what <code><nowiki>BlockState</nowiki></code> is used when placing your block, you can overwrite <code><nowiki>Block#getStateForPlacement(BlockPlaceContext)</nowiki></code>. This can be used to, for example, set the direction of your block depending on where the player is standing when they place it.

Because <code><nowiki>BlockState</nowiki></code>s are immutable, and all combinations of their properties are generated on startup of the game, calling <code><nowiki>BlockState#setValue(Property<T>, T)</nowiki></code> will simply go to the <code><nowiki>Block</nowiki></code>'s <code><nowiki>StateHolder</nowiki></code> and request the <code><nowiki>BlockState</nowiki></code> with the set of values you want.

Because all possible <code><nowiki>BlockState</nowiki></code>s are generated at startup, you are free and encouraged to use the reference equality operator (<code><nowiki>==</nowiki></code>) to check if two <code><nowiki>BlockState</nowiki></code>s are equal.

== Using <tt>BlockState</tt>s ==

You can get the value of a property by calling <code><nowiki>BlockState#getValue(Property<?>)</nowiki></code>, passing it the property you want to get the value of.
If you want to get a <code><nowiki>BlockState</nowiki></code> with a different set of values, simply call <code><nowiki>BlockState#setValue(Property<T>, T)</nowiki></code> with the property and its value.

You can get and place <code><nowiki>BlockState</nowiki></code>s in the level using <code><nowiki>Level#setBlockAndUpdate(BlockPos, BlockState)</nowiki></code> and <code><nowiki>Level#getBlockState(BlockPos)</nowiki></code>. If you are placing a <code><nowiki>Block</nowiki></code>, call <code><nowiki>Block#defaultBlockState()</nowiki></code> to get the "default" state, and use subsequent calls to <code><nowiki>BlockState#setValue(Property<T>, T)</nowiki></code> as stated above to achieve the desired state.

Registration

2022-06-12T18:44:14Z

ChampionAsh5357: Add notice about non-vanilla registries for keys and names with DeferredRegister

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

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

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

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

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

== Methods for Registering ==

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

=== DeferredRegister ===

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

{{Tip/Important|When using <code>DeferredRegister</code>s with non-vanilla registries, the registry key or the registry name should be supplied instead. These include registries for entity data serializers, global loot modifier serializers, world presets, and biome modifier serializers.}}

An example of a mod registering a custom block:

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

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

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

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

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

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

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

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

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

=== RegisterEvent ===

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

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

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

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

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

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

=== Non-Forge Registries ===

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

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

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

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

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

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

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

=== Data Driven Entries ===

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

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

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

== Referencing Registered Objects ==

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

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

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

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

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

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

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

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

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

=== Using @ObjectHolder ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Creating Custom Registries ==

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

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

=== With DeferredRegister ===

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

Here is an example:

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

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

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

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

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

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

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

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

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

== Handling Missing Entries ==

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

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

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

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

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

[[Category:Common Concepts]]

Stages of Modloading

2022-06-11T17:29:03Z

ChampionAsh5357: Update to 1.19

The FML mod loading process is broken into several stages, with each stage having associated events fired alongside with it on the mod-specific event bus. These events are known as the <code>mod lifecycle events</code>, as they are fired during the different phases of a mod's life.

The different mod loading stages are represented each by a value in the enum class <code><nowiki>net.minecraftforge.fml.ModLoadingStage</nowiki></code>. Their states are split between the <code><nowiki>net.minecraftforge.fml.core.ModStateProvider</nowiki></code> for mod states (construct, common setup, etc.) and <code><nowiki>net.minecraftforge.fmllegacy.ForgeStatesProvider</nowiki></code> for forge injected states (creating registries, injecting capabilities, etc.) Most of the mod lifecycle events are stored in the <code><nowiki>net.minecraftforge.fml.event.lifecycle</nowiki></code> package.

== Parallelism ==

The mod loading system is parallelized to some extent. While all of the stages are changed at the same time across all mods, most of the events are fired in parallel to each mod. That is, all mods will concurrently receive the event, then FML will wait until all mods have processed the event before moving to the next stage and firing the next event. These concurrently dispatched events are distinguished by them extending <code><nowiki>ParallelDispatchEvent</nowiki></code>.

This does means that in these parallel mod lifecycle events, care must be taken to be thread-safe, like when calling external methods which are backed by non-thread-safe collections. Most of the systems in Forge are protected for this; however, vanilla systems and external mods' APIs may not be thread-safe. FML provides a way for mods to defer tasks/work until the event is finished dispatching, where it will be run sequentially along with other events on the main thread. This is done with the <code><nowiki>#enqueueWork</nowiki></code> method, which is a member of all events which extend <code><nowiki>ParallelDispatchEvent</nowiki></code>.

== Common Transition Stages and Events ==

{| class="wikitable sortable" border=1
! Name !! Enum Constant !! Lifecycle Event !! Parallel? !! Description
|-
| Construction || <code><nowiki>CONSTRUCT</nowiki></code> || <code><nowiki>FMLConstructModEvent</nowiki></code> || Yes || Fired when the mod's constructor has been called. Can be used to initialize listeners outside of the constructor. There is usually no reason to use this event, as any code should be placed in the mod constructor instead.
|-
| Registry Creation || <code><nowiki>CREATE_REGISTRIES</nowiki></code> || <code><nowiki>NewRegistryEvent</nowiki></code> || No || Fired for mods to create and initialize their custom registries.
|-
| Registry Population || <code><nowiki>LOAD_REGISTRIES</nowiki></code> || <code><nowiki>RegisterEvent</nowiki></code> || No || Fired when a registry is open to registrations for any registrable objects, such as blocks, items, etc.
|-
| Config Loading || <code><nowiki>CONFIG_LOAD</nowiki></code> || <code><nowiki>ModConfigEvent$Loading</nowiki></code> || No || Loads config files associated with registered mod configs. Before this stage, mod config values only return their default values unless manually loaded earlier.
|-
| Common Setup || <code><nowiki>COMMON_SETUP</nowiki></code> || <code><nowiki>FMLCommonSetupEvent</nowiki></code> || Yes || Used for doing any work or action that should be run on both '''physical''' sides.
|-
| Sided Setup || <code><nowiki>SIDED_SETUP</nowiki></code> || <code><nowiki>FMLClientSetupEvent</nowiki></code> for physical client, <code><nowiki>FMLDedicatedServerSetupEvent</nowiki></code> for physical server || Yes || Used for doing any physical side-specific initialization work.
|-
| IMC Enqueue || <code><nowiki>ENQUEUE_IMC</nowiki></code> || <code><nowiki>InterModEnqueueEvent</nowiki></code> || Yes || Fired for mods to enqueue messages for other mods using the <code><nowiki>InterModComms</nowiki></code> system.
|-
| IMC Processing || <code><nowiki>PROCESS_IMC</nowiki></code> || <code><nowiki>InterModProcessEvent</nowiki></code> || Yes || Fired for mods to process messages from other mods sent using the <code><nowiki>InterModComms</nowiki></code> system in the previous stage.
|-
| Loading Complete || <code><nowiki>COMPLETE</nowiki></code> || <code><nowiki>FMLLoadCompleteEvent</nowiki></code> || Yes || Fired when mod loading is complete, before handing control back to the main game. There is usually no reason to use this event, as most actions can be done during the Common or Sided Setup stages.
|-
|}

Registration

2022-06-11T17:25:34Z

ChampionAsh5357: Missed something, whoops

{{Under construction}}

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

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

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

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

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

== Methods for Registering ==

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

=== DeferredRegister ===

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

An example of a mod registering a custom block:

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

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

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

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

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

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

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

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

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

=== RegisterEvent ===

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

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

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

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

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

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

=== Non-Forge Registries ===

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

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

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

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

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

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

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

=== Data Driven Entries ===

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

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

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

== Referencing Registered Objects ==

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

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

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

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

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

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

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

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

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

=== Using @ObjectHolder ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Creating Custom Registries ==

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

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

=== With DeferredRegister ===

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

Here is an example:

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

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

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

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

=== Using `NewRegistryEvent` ===

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

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

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

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

== Handling Missing Entries ==

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

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

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

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

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

[[Category:Common Concepts]]

Registration

2022-06-11T17:24:38Z

ChampionAsh5357: Update to 1.19

{{Under construction}}

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

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

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

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

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

== Methods for Registering ==

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

=== DeferredRegister ===

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

An example of a mod registering a custom block:

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

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

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

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

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

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

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

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

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

=== RegisterEvent ===

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

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

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

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

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

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

=== Non-Forge Registries ===

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

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

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

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

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

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

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

=== Data Driven Entries ===

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

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

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

== Referencing Registered Objects ==

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

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

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

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

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

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

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

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

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

=== Using @ObjectHolder ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Creating Custom Registries ==

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

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

=== With DeferredRegister ===

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

Here is an example:

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

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

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

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

=== Using `NewRegistryEvent` ===

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

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

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

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

== Handling Missing Entries ==

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

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

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

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

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

[[Category:Common Concepts]]

Internationalization

2022-06-11T17:05:12Z

ChampionAsh5357: Update to 1.19

'''Internationalization''' (shortened as '''i18n'''), is a way of designing code so that it requires no changes to be adapted for various languages. '''Localization''' (shortened as '''l10n''') is the process of adapting displayed text to the user’s language.

Internationalization is implemented using ''translation keys''. A translation key is a string that identifies a piece of displayable text in no specific language. For example, <code>block.minecraft.dirt</code> is the translation key referring to the name of the Dirt block. This way, displayable text may be referenced with no concern for a specific language. The code requires no changes to be adapted in a new language.

Localization will happen in the game’s locale. In a Minecraft client the locale is specified by the language settings. On a dedicated server, the only supported locale is <code>en_us</code>. A list of available locales can be found on the [https://minecraft.gamepedia.com/Language#Available_languages Minecraft Wiki].

{{Tip/Important|The only purpose of a translation key is internationalization. Do not use them for logic, such as comparing if two blocks are equal. Use their [[Registration|registry names]] instead.}}

== Language files ==

Language files are located by <code>assets/[namespace]/lang/[locale].json</code> (e.g. the US English translation for <code>examplemod</code> would be <code>assets/examplemod/lang/en_us.json</code>). The file format is simply a json map from translation keys to values. The file must be encoded in UTF-8.

<syntaxhighlight lang="json">
{
"item.examplemod.example_item": "Example Item Name",
"block.examplemod.example_block": "Example Block Name",
"commands.examplemod.example_command.error": "Example Command Errored!"
}
</syntaxhighlight>

== Usage with Blocks and Items ==

Block, Item, and a few other Minecraft classes have built-in translation keys used to display their names. These translation keys are specified by overriding <code>getDescriptionId()</code>. Item also has <code>getDescriptionId(ItemStack)</code> which can be overridden to provide different translation keys depending on <code>ItemStack</code> NBT.

By default, <code>getDescriptionId()</code> will return <code>block</code> or <code>item</code>. prepended to the registry name of the block or item, with the colon replaced by a dot. <code>BlockItem</code>s will take their corresponding Block's translation key by default. For example, an item with ID <code>examplemod:example_item</code> effectively requires the following line in a language file:

<syntaxhighlight lang="json">
{
"item.examplemod.example_item": "Example Item Name"
}
</syntaxhighlight>

== Localization methods ==

{{Tip/Important|A common issue is having the server localize for clients. The server can only localize in its own locale, which does not necessarily match the locale of connected clients.
<br/><br/>
To respect the language settings of clients, the server should have clients localize text in their own locale using components with <code>TranslatableContents</code> or other methods preserving the language neutral translation keys.}}

<h3 id="I18n"><tt style="font-size: 100%">net.minecraft.client.resources.language.I18n</tt></h3>

{{Tip/Danger|'''This I18n class can only be found on the [[Sides#Different_Kinds_of_Sides|physical client]]!''' It is intended to be used by code that only runs on the client. Attempts to use this on a server will throw exceptions and crash.}}

<code>get(String, Object...)</code> localizes in the client’s locale with formatting. The first parameter is a translation key, and the rest are formatting arguments for <code>String.format(String, Object...)</code>.

=== <tt style="font-size: 100%">TranslatableContents</tt> ===

<code>TranslatableContents</code> is a <code>ComponentContents</code> that is localized and formatted lazily. A <code>Component</code> can be created for this using <code>Component#translatable</code>. It is very useful when sending messages to players because it will be automatically localized in their own locale.

The first parameter of the <code>TranslatableContents(String, Object...)</code> constructor is a translation key, and the rest are used for formatting. The only supported format specifiers are <code>%s</code> and <code>%1$s</code>, <code>%2$s</code>, <code>%3$s</code> etc. Formatting arguments may be other <code>Component</code>s that will be inserted into the resulting formatted text with all their attributes preserved.

[[Category:Common Concepts]]

Events/Forge bus

2022-06-11T17:02:31Z

ChampionAsh5357: Update to 1.19

{{Tree list}}
* <code>Event</code> - ''The root superclass for all events''
**<code>MissingMappingsEvent</code>
**<code>RecipesUpdatedEvent</code>
**<code>FurnaceFuelBurnTimeEvent</code>
**<code>DrawSelectionEvent</code>
***<code>HighlightBlock</code> in <code>DrawSelectionEvent</code>
***<code>HighlightEntity</code> in <code>DrawSelectionEvent</code>
**<code>VillagerTradesEvent</code>
**<code>AddReloadListenerEvent</code>
**<code>GameShuttingDownEvent</code>
**<code>ClientPlayerChangeGameTypeEvent</code>
**<code>PlayerNegotiationEvent</code>
**<code>RenderHandEvent</code>
**<code>RenderLivingEvent</code>
***<code>Pre</code> in <code>RenderLivingEvent</code>
***<code>Post</code> in <code>RenderLivingEvent</code>
**<code>RegisterCommandsEvent</code>
**<code>RenderItemInFrameEvent</code>
**<code>RenderBlockOverlayEvent</code>
**<code>BlockEvent</code>
***<code>BlockToolModificationEvent</code> in <code>BlockEvent</code>
***<code>NeighborNotifyEvent</code> in <code>BlockEvent</code>
***<code>NoteBlockEvent</code>
****<code>Change</code> in <code>NoteBlockEvent</code>
****<code>Play</code> in <code>NoteBlockEvent</code>
***<code>BreakEvent</code> in <code>BlockEvent</code>
***<code>EntityPlaceEvent</code> in <code>BlockEvent</code>
****<code>EntityMultiPlaceEvent</code> in <code>BlockEvent</code>
***<code>PistonEvent</code>
****<code>Pre</code> in <code>PistonEvent</code>
****<code>Post</code> in <code>PistonEvent</code>
***<code>PortalSpawnEvent</code> in <code>BlockEvent</code>
***<code>FarmlandTrampleEvent</code> in <code>BlockEvent</code>
***<code>FluidPlaceBlockEvent</code> in <code>BlockEvent</code>
***<code>CropGrowEvent</code> in <code>BlockEvent</code>
****<code>Pre</code> in <code>CropGrowEvent</code> in <code>BlockEvent</code>
****<code>Post</code> in <code>CropGrowEvent</code> in <code>BlockEvent</code>
**<code>WorldEvent</code>
***<code>Load</code> in <code>WorldEvent</code>
***<code>CreateSpawnPosition</code> in <code>WorldEvent</code>
***<code>Unload</code> in <code>WorldEvent</code>
***<code>ChunkEvent</code>
****<code>Load</code> in <code>ChunkEvent</code>
****<code>Unload</code> in <code>ChunkEvent</code>
****<code>ChunkDataEvent</code>
*****<code>Save</code> in <code>ChunkDataEvent</code>
*****<code>Load</code> in <code>ChunkDataEvent</code>
***<code>SleepFinishedTimeEvent</code>
***<code>Save</code> in <code>WorldEvent</code>
***<code>SaplingGrowTreeEvent</code>
**<code>PlayLevelSoundEvent</code>
***<code>AtEntity</code> in <code>PlayLevelSoundEvent</code>
***<code>AtPosition</code> in <code>PlayLevelSoundEvent</code>
**<code>RegisterStructureConversionsEvent</code>
**<code>ContainerScreenEvent</code>
***<code>DrawBackground</code> in <code>ContainerScreenEvent</code>
***<code>DrawForeground</code> in <code>ContainerScreenEvent</code>
**<code>BabyEntitySpawnEvent</code>
**<code>ServerChatEvent</code>
**<code>ScreenEvent</code>
***<code>KeyboardKeyEvent</code> in <code>ScreenEvent</code>
****<code>KeyboardKeyReleasedEvent</code> in <code>ScreenEvent</code>
*****<code>Pre</code> in <code>KeyboardKeyReleasedEvent</code> in <code>ScreenEvent</code>
*****<code>Post</code> in <code>KeyboardKeyReleasedEvent</code> in <code>ScreenEvent</code>
****<code>KeyboardKeyPressedEvent</code> in <code>ScreenEvent</code>
*****<code>Post</code> in <code>KeyboardKeyPressedEvent</code> in <code>ScreenEvent</code>
*****<code>Pre</code> in <code>KeyboardKeyPressedEvent</code> in <code>ScreenEvent</code>
***<code>InitScreenEvent</code> in <code>ScreenEvent</code>
****<code>Pre</code> in <code>InitScreenEvent</code> in <code>ScreenEvent</code>
****<code>Post</code> in <code>InitScreenEvent</code> in <code>ScreenEvent</code>
***<code>MouseInputEvent</code> in <code>ScreenEvent</code>
****<code>MouseReleasedEvent</code> in <code>ScreenEvent</code>
*****<code>Pre</code> in <code>MouseReleasedEvent</code> in <code>ScreenEvent</code>
*****<code>Post</code> in <code>MouseReleasedEvent</code> in <code>ScreenEvent</code>
****<code>MouseScrollEvent</code> in <code>ScreenEvent</code>
*****<code>Pre</code> in <code>MouseScrollEvent</code> in <code>ScreenEvent</code>
*****<code>Post</code> in <code>MouseScrollEvent</code> in <code>ScreenEvent</code>
****<code>MouseClickedEvent</code> in <code>ScreenEvent</code>
*****<code>Post</code> in <code>MouseClickedEvent</code> in <code>ScreenEvent</code>
*****<code>Pre</code> in <code>MouseClickedEvent</code> in <code>ScreenEvent</code>
****<code>MouseDragEvent</code> in <code>ScreenEvent</code>
*****<code>Post</code> in <code>MouseDragEvent</code> in <code>ScreenEvent</code>
*****<code>Pre</code> in <code>MouseDragEvent</code> in <code>ScreenEvent</code>
***<code>KeyboardCharTypedEvent</code> in <code>ScreenEvent</code>
****<code>Pre</code> in <code>KeyboardCharTypedEvent</code> in <code>ScreenEvent</code>
****<code>Post</code> in <code>KeyboardCharTypedEvent</code> in <code>ScreenEvent</code>
***<code>PotionSizeEvent</code> in <code>ScreenEvent</code>
***<code>DrawScreenEvent</code> in <code>ScreenEvent</code>
****<code>Post</code> in <code>DrawScreenEvent</code> in <code>ScreenEvent</code>
****<code>Pre</code> in <code>DrawScreenEvent</code> in <code>ScreenEvent</code>
***<code>BackgroundDrawnEvent</code> in <code>ScreenEvent</code>
**<code>VillageSiegeEvent</code>
**<code>LootTableLoadEvent</code>
**<code>TagsUpdatedEvent</code>
**<code>PotionBrewEvent</code>
***<code>Pre</code> in <code>PotionBrewEvent</code>
***<code>Post</code> in <code>PotionBrewEvent</code>
**<code>ClientChatReceivedEvent</code>
**<code>InputEvent</code>
***<code>ClickInputEvent</code> in <code>InputEvent</code>
***<code>KeyInputEvent</code> in <code>InputEvent</code>
***<code>MouseInputEvent</code> in <code>InputEvent</code>
***<code>RawMouseEvent</code> in <code>InputEvent</code>
***<code>MouseScrollEvent</code> in <code>InputEvent</code>
**<code>RegisterClientCommandsEvent</code>
**<code>GatherComponents</code> in <code>RenderTooltipEvent</code>
**<code>DifficultyChangeEvent</code>
**<code>ScreenshotEvent</code>
**<code>ServerLifecycleEvent</code>
***<code>ServerStoppingEvent</code>
***<code>ServerStoppedEvent</code>
***<code>ServerAboutToStartEvent</code>
***<code>ServerStartedEvent</code>
***<code>ServerStartingEvent</code>
**<code>EnchantmentLevelSetEvent</code>
**<code>RenderTooltipEvent</code>
***<code>Pre</code> in <code>RenderTooltipEvent</code>
***<code>Color</code> in <code>RenderTooltipEvent</code>
**<code>IdMappingEvent</code>
**<code>CreateFluidSourceEvent</code> in <code>BlockEvent</code>
**<code>VanillaGameEvent</code>
**<code>RenderGameOverlayEvent</code>
***<code>Pre</code> in <code>RenderGameOverlayEvent</code>
****<code>Text</code> in <code>RenderGameOverlayEvent</code>
****<code>BossInfo</code> in <code>RenderGameOverlayEvent</code>
****<code>PreLayer</code> in <code>RenderGameOverlayEvent</code>
****<code>Chat</code> in <code>RenderGameOverlayEvent</code>
***<code>Post</code> in <code>RenderGameOverlayEvent</code>
****<code>PostLayer</code> in <code>RenderGameOverlayEvent</code>
**<code>ClientChatEvent</code>
**<code>CommandEvent</code>
**<code>PermissionGatherEvent</code>
***<code>Handler</code> in <code>PermissionGatherEvent</code>
***<code>Nodes</code> in <code>PermissionGatherEvent</code>
**<code>OnDatapackSyncEvent</code>
**<code>StructureSpawnListGatherEvent</code>
**<code>GenericEvent</code>
***<code>AttachCapabilitiesEvent</code>
**<code>ExplosionEvent</code>
***<code>Detonate</code> in <code>ExplosionEvent</code>
***<code>Start</code> in <code>ExplosionEvent</code>
**<code>SoundEvent</code>
***<code>SoundSourceEvent</code> in <code>SoundEvent</code>
****<code>PlaySoundSourceEvent</code>
****<code>PlayStreamingSourceEvent</code>
***<code>PlaySoundEvent</code>
**<code>AnvilUpdateEvent</code>
**<code>ScreenOpenEvent</code>
**<code>RenderArmEvent</code>
**<code>RenderLevelLastEvent</code>
**<code>TickEvent</code>
***<code>PlayerTickEvent</code> in <code>TickEvent</code>
***<code>ServerTickEvent</code> in <code>TickEvent</code>
***<code>WorldTickEvent</code> in <code>TickEvent</code>
***<code>ClientTickEvent</code> in <code>TickEvent</code>
***<code>RenderTickEvent</code> in <code>TickEvent</code>
**<code>WandererTradesEvent</code>
**<code>ItemAttributeModifierEvent</code>
**<code>EntityViewRenderEvent</code>
***<code>FieldOfView</code> in <code>EntityViewRenderEvent</code>
***<code>RenderFogEvent</code> in <code>EntityViewRenderEvent</code>
***<code>FogColors</code> in <code>EntityViewRenderEvent</code>
***<code>CameraSetup</code> in <code>EntityViewRenderEvent</code>
**<code>ClientPlayerNetworkEvent</code>
***<code>LoggedOutEvent</code> in <code>ClientPlayerNetworkEvent</code>
***<code>LoggedInEvent</code> in <code>ClientPlayerNetworkEvent</code>
***<code>RespawnEvent</code> in <code>ClientPlayerNetworkEvent</code>
**<code>FOVModifierEvent</code>
**<code>EntityEvent</code>
***<code>EntityTeleportEvent</code>
****<code>SpreadPlayersCommand</code> in <code>EntityTeleportEvent</code>
****<code>EnderEntity</code> in <code>EntityTeleportEvent</code>
****<code>EnderPearl</code> in <code>EntityTeleportEvent</code>
****<code>TeleportCommand</code> in <code>EntityTeleportEvent</code>
****<code>ChorusFruit</code> in <code>EntityTeleportEvent</code>
***<code>ProjectileImpactEvent</code>
***<code>EntityTravelToDimensionEvent</code>
***<code>EntityMobGriefingEvent</code>
***<code>RenderNameplateEvent</code>
***<code>EntityConstructing</code> in <code>EntityEvent</code>
***<code>EntityMountEvent</code>
***<code>EntityStruckByLightningEvent</code>
***<code>Size</code> in <code>EntityEvent</code>
***<code>EntityJoinWorldEvent</code>
***<code>EnteringSection</code> in <code>EntityEvent</code>
***<code>LivingEvent</code>
****<code>LivingEquipmentChangeEvent</code>
****<code>SleepingLocationCheckEvent</code>
****<code>LivingUpdateEvent</code> in <code>LivingEvent</code>
****<code>PotionColorCalculationEvent</code>
****<code>LivingExperienceDropEvent</code>
****<code>LivingDamageEvent</code>
****<code>LivingAttackEvent</code>
****<code>LivingEntityUseItemEvent</code>
*****<code>Start</code> in <code>LivingEntityUseItemEvent</code>
*****<code>Tick</code> in <code>LivingEntityUseItemEvent</code>
*****<code>Stop</code> in <code>LivingEntityUseItemEvent</code>
*****<code>Finish</code> in <code>LivingEntityUseItemEvent</code>
****<code>PotionEvent</code>
*****<code>PotionExpiryEvent</code> in <code>PotionEvent</code>
*****<code>PotionApplicableEvent</code> in <code>PotionEvent</code>
*****<code>PotionRemoveEvent</code> in <code>PotionEvent</code>
*****<code>PotionAddedEvent</code> in <code>PotionEvent</code>
****<code>EnderManAngerEvent</code>
****<code>LivingPackSizeEvent</code>
****<code>PlayerEvent</code>
*****<code>PlayerChangeGameModeEvent</code> in <code>PlayerEvent</code>
*****<code>PlayerContainerEvent</code>
******<code>Close</code> in <code>PlayerContainerEvent</code>
******<code>Open</code> in <code>PlayerContainerEvent</code>
*****<code>PlayerWakeUpEvent</code>
*****<code>BreakSpeed</code> in <code>PlayerEvent</code>
*****<code>ItemSmeltedEvent</code> in <code>PlayerEvent</code>
*****<code>ArrowLooseEvent</code>
*****<code>Clone</code> in <code>PlayerEvent</code>
*****<code>MovementInputUpdateEvent</code>
*****<code>AdvancementEvent</code>
*****<code>AnvilRepairEvent</code>
*****<code>PlayerSleepInBedEvent</code>
*****<code>PlayerLoggedOutEvent</code> in <code>PlayerEvent</code>
*****<code>PlayerXpEvent</code>
******<code>XpChange</code> in <code>PlayerXpEvent</code>
******<code>LevelChange</code> in <code>PlayerXpEvent</code>
******<code>PickupXp</code> in <code>PlayerXpEvent</code>
*****<code>StopTracking</code> in <code>PlayerEvent</code>
*****<code>FillBucketEvent</code>
*****<code>PlayerDestroyItemEvent</code>
*****<code>BonemealEvent</code>
*****<code>SleepingTimeCheckEvent</code>
*****<code>PlayerInteractEvent</code>
******<code>EntityInteractSpecific</code> in <code>PlayerInteractEvent</code>
******<code>RightClickBlock</code> in <code>PlayerInteractEvent</code>
******<code>EntityInteract</code> in <code>PlayerInteractEvent</code>
******<code>RightClickEmpty</code> in <code>PlayerInteractEvent</code>
******<code>RightClickItem</code> in <code>PlayerInteractEvent</code>
******<code>LeftClickEmpty</code> in <code>PlayerInteractEvent</code>
******<code>LeftClickBlock</code> in <code>PlayerInteractEvent</code>
*****<code>EntityItemPickupEvent</code>
*****<code>HarvestCheck</code> in <code>PlayerEvent</code>
*****<code>ItemPickupEvent</code> in <code>PlayerEvent</code>
*****<code>TabListNameFormat</code> in <code>PlayerEvent</code>
*****<code>PlayerChangedDimensionEvent</code> in <code>PlayerEvent</code>
*****<code>PlayerSetSpawnEvent</code>
*****<code>PlayerFlyableFallEvent</code>
*****<code>LoadFromFile</code> in <code>PlayerEvent</code>
*****<code>PermissionsChangedEvent</code>
*****<code>CriticalHitEvent</code>
*****<code>StartTracking</code> in <code>PlayerEvent</code>
*****<code>ItemFishedEvent</code>
*****<code>ArrowNockEvent</code>
*****<code>PlayerRespawnEvent</code> in <code>PlayerEvent</code>
*****<code>ItemTooltipEvent</code>
*****<code>SaveToFile</code> in <code>PlayerEvent</code>
*****<code>PlayerLoggedInEvent</code> in <code>PlayerEvent</code>
*****<code>ItemCraftedEvent</code> in <code>PlayerEvent</code>
*****<code>NameFormat</code> in <code>PlayerEvent</code>
*****<code>RenderPlayerEvent</code>
******<code>Post</code> in <code>RenderPlayerEvent</code>
******<code>Pre</code> in <code>RenderPlayerEvent</code>
*****<code>AttackEntityEvent</code>
*****<code>PlayerBrewedPotionEvent</code>
****<code>ShieldBlockEvent</code>
****<code>LivingHealEvent</code>
****<code>LootingLevelEvent</code>
****<code>LivingDestroyBlockEvent</code>
****<code>LivingConversionEvent</code>
*****<code>Pre</code> in <code>LivingConversionEvent</code>
*****<code>Post</code> in <code>LivingConversionEvent</code>
****<code>LivingKnockBackEvent</code>
****<code>LivingHurtEvent</code>
****<code>LivingVisibilityEvent</code> in <code>LivingEvent</code>
****<code>LivingDeathEvent</code>
****<code>AnimalTameEvent</code>
****<code>LivingFallEvent</code>
****<code>LivingGetProjectileEvent</code>
****<code>LivingSetAttackTargetEvent</code>
****<code>LivingSpawnEvent</code>
*****<code>AllowDespawn</code> in <code>LivingSpawnEvent</code>
*****<code>CheckSpawn</code> in <code>LivingSpawnEvent</code>
*****<code>SpecialSpawn</code> in <code>LivingSpawnEvent</code>
****<code>LivingJumpEvent</code> in <code>LivingEvent</code>
****<code>LivingDropsEvent</code>
***<code>ZombieEvent</code>
****<code>SummonAidEvent</code> in <code>ZombieEvent</code>
***<code>EntityLeaveWorldEvent</code>
***<code>ItemEvent</code>
****<code>ItemTossEvent</code>
****<code>ItemExpireEvent</code>
**<code>NetworkEvent</code>
***<code>ServerCustomPayloadEvent</code> in <code>NetworkEvent</code>
****<code>ServerCustomPayloadLoginEvent</code> in <code>NetworkEvent</code>
***<code>LoginPayloadEvent</code> in <code>NetworkEvent</code>
***<code>ChannelRegistrationChangeEvent</code> in <code>NetworkEvent</code>
***<code>ClientCustomPayloadEvent</code> in <code>NetworkEvent</code>
****<code>ClientCustomPayloadLoginEvent</code> in <code>NetworkEvent</code>
**<code>GatherLoginPayloadsEvent</code> in <code>NetworkEvent</code>
**<code>ChunkWatchEvent</code>
***<code>UnWatch</code> in <code>ChunkWatchEvent</code>
***<code>Watch</code> in <code>ChunkWatchEvent</code>
{{Tree list/end}}

Events/Mod bus

2022-06-11T16:56:44Z

ChampionAsh5357: Update to 1.19

{{Tree list}}
* <code>IModBusEvent</code> - ''The interface for all mod bus events''
**<code>ModelBakeEvent</code>
**<code>EntityRenderersEvent</code>
***<code>AddLayers</code> in <code>EntityRenderersEvent</code>
***<code>CreateSkullModels</code> in <code>EntityRenderersEvent</code>
***<code>RegisterRenderers</code> in <code>EntityRenderersEvent</code>
***<code>RegisterLayerDefinitions</code> in <code>EntityRenderersEvent</code>
**<code>ModelRegistryEvent</code>
**<code>GatherDataEvent</code>
**<code>RegisterShadersEvent</code>
**<code>AddPackFindersEvent</code>
**<code>ModLifecycleEvent</code>
***<code>ParallelDispatchEvent</code>
****<code>FMLCommonSetupEvent</code>
****<code>InterModProcessEvent</code>
****<code>FMLDedicatedServerSetupEvent</code>
****<code>FMLConstructModEvent</code>
****<code>InterModEnqueueEvent</code>
****<code>FMLClientSetupEvent</code>
****<code>FMLLoadCompleteEvent</code>
**<code>EntityAttributeCreationEvent</code>
**<code>NewRegistryEvent</code>
**<code>RegisterGameTestsEvent</code>
**<code>ParticleFactoryRegisterEvent</code>
**<code>RegisterCapabilitiesEvent</code>
**<code>TextureStitchEvent</code>
***<code>Pre</code> in <code>TextureStitchEvent</code>
***<code>Post</code> in <code>TextureStitchEvent</code>
**<code>EntityAttributeModificationEvent</code>
**<code>SoundEngineLoadEvent</code>
**<code>RegisterClientReloadListenersEvent</code>
**<code>RegisterEvent</code>
**<code>ColorHandlerEvent</code>
***<code>Block</code> in <code>ColorHandlerEvent</code>
***<code>Item</code> in <code>ColorHandlerEvent</code>
**<code>ModConfigEvent</code>
***<code>Reloading</code> in <code>ModConfigEvent</code>
***<code>Loading</code> in <code>ModConfigEvent</code>
{{Tree list/end}}

Version Checker

2022-06-11T16:48:38Z

ChampionAsh5357: Update to 1.19

The '''Version Checker''' is a Forge-provided utility for mods to check for new versions based on an online update JSON file. It is lightweight, toggleable, asynchoronous to the main mod loading, and integrates cleanly with the mods list menu.

If there are outdated mods according to the version checker, a flashing emerald indicator will be shown on the Mods button on the main menu. The entries for the outdated mods in the mods list screen have the flashing emerald indicator. The information screen for outdated mods will have an <code>Update available:</code> line with the <code>homepage</code> URL from the update JSON file, and a list of mod versions and corresponding text after the mod description, for the mod versions between the most up-to-date and the currently installed version.


The version checker can be configured through the <code>versionCheck</code> option in the FML config (<tt>config/fml.toml</tt>). This option controls the version checking for all mods, including Forge.

== Update JSON format ==
The version checker checks the update JSON, specified by the <code>updateJSONURL</code> for the [[Proper Mod Structuring#Mod Properties|mod in the <tt>mods.toml</tt>]]. An example of a JSON file is the [https://files.minecraftforge.net/maven/net/minecraftforge/forge/promotions_slim.json update JSON for Minecraft Forge]. The JSON file must be in the following format:
{{Tree list}}
* '''Root object'''
** <code>homepage</code> (string): A URL, displayed on the mod's information screen on the Mods list screen
** <code>promos</code> (object)
*** <code>'''''<nowiki><minecraft version></nowiki>'''''-latest</code> (string): A version string, for the latest mod version corresponding to the given Minecraft version
*** <code>'''''<nowiki><minecraft version></nowiki>'''''-recommended</code> (string): A version string, for the recommended mod version corresponding to the given Minecraft version
*** ...
** <code>'''''<nowiki><minecraft version></nowiki>'''''</code> (object)
*** <code>'''''<nowiki><mod version></nowiki>'''''</code> (string): Any text, displayed when the the specified mod version in the key is ahead of currently installed version; used as a changelog
*** ...
{{Tree list/end}}

== Update status ==
There are 7 possible version checker statuses, according to the <code>VersionChecker.Status</code> enum:
* <code>PENDING</code> - The version checker has not or is currently retrieving the version from the update JSON. This is temporary, and will change into one of the other statuses.
* <code>FAILED</code> - The version checker failed, either to retrieve the update JSON or some other error (such as failure to parse broken JSON).
* <code>UP_TO_CODE</code> - The currently installed version is the same as the recommended version for the current Minecraft version.
* <code>OUTDATED</code> - The currently installed version is either behind the recommended version for the MC version, or ahead of the recommended version, but behind the latest version for the MC version.
* <code>AHEAD</code> - The currently installed version is ahead of the recommended version for the MC version, and there is no more up-to-date latest version for the MC version. 
* <code>BETA</code> - There is no recommended version, and either the currently installed version is up-to-date or ahead of the latest version, or there is no latest version for the MC version.
* <code>BETA_OUTDATED</code> - There is no recommended version, and the currently installed version is behind the latest version for the MC version.

==<tt>CheckResult</tt>==
The version checker result for a mod can be retrieving using the <code>VersionChecker.getResult(IModInfo)</code> static method which returns a <code>CheckResult</code>. (<code>IModInfo</code> is the information for a specific mod; see <code>ModList#getModContainerById(String)</code> and <code>ModContainer#getModInfo()</code>).

The <code>CheckResult</code> contains four methods:
* <code>status</code>, the version checker status as a <code>VersionChecker.Status</code> enum value.
* <code>target</code>, the version which caused the <code>OUTDATED</code>, <code>BETA</code> or <code>BETA_OUTDATED</code>
** If the status is <code>OUTDATED</code>, this is the newest recommended or latest version from the JSON.
** If the status is <code>BETA_OUTDATED</code> or <code>BETA</code>, this is the highest newest version from the JSON.
** This may be <code>null</code> if the status is <code>BETA</code>, and there is no recommended or latest version defined in the JSON file.
* <code>changes</code>, an unmodifiable map of mod versions and their corresponding text based on the MC version, where the mod versions are higher than the currently installed version. This information is shown on the mods information screen, as a changelog.
* <code>url</code>, the URL from the <code>homepage</code> string in the update JSON, displayed on the mods information screen.

Mods.toml

2022-06-11T16:46:36Z

ChampionAsh5357: Update to 1.19, note to look at feature system later

{{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.19 is version 41
loaderVersion="[41,)"
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="[41,)"
ordering="NONE"
side="BOTH"

[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.19,1.20)"
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>"[41,)"</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]]

Getting Started

2022-06-11T16:39:53Z

ChampionAsh5357: Update to 1.19

'''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.4.2/userguide/gradle_wrapper.html Gradle wrapper]'', Forge uses Version '''7.4.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.4.2/userguide/tutorial_using_tasks.html Gradle User Guide for 7.4.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.4.2/userguide/build_environment.html#sec:gradle_configuration_properties Gradle User Guide for 7.4.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>
#* For '''Visual Studio Code''': Run <code>./gradlew buildNeeded</code> and then <code>./gradlew eclipse</code>, then <tt>File > Open Folder...</tt> and select the folder
# Wait for the setup process to complete and the Minecraft sources are decompiled.
#* For '''Visual Studio Code''': This step can be skipped as it was already done in the previous step
# Generate the run configurations for your IDE using the appropriate Gradle task. <br>These tasks can be run in the terminal using <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 [https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack Extension Pack for Java] and [https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-gradle Gradle for Java 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 four 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.
* <code>runGameTestServer</code>, for starting a build server to run [[Game_Tests|game tests]].

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

Main Page

2022-04-20T04:03:11Z

ChampionAsh5357: Add game tests link

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

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

The Forge Community Wiki exists so that the community can:

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

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

{{Supported versions}}

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

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

<div class="box_container center">

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

</div>

Game Tests

2022-04-20T04:02:15Z

ChampionAsh5357: Add game tests page

Game Tests are a way to run in-game unit tests. The system was designed to be scalable and in parallel to run large numbers of different tests efficiently. Testing object interactions and behaviors are simply a few of the many applications of this framework.

== Creating a Game Test ==

A standard Game Test follows three basic steps:

# A structure, or template, is loaded holding the scene on which the interaction or behavior is tested.
# A method conducts the logic to perform on the scene.
# The method logic executes. If a successful state is reached, then the test succeeds. Otherwise, the test fails and the result is stored within a lectern adjacent to the scene.

As such, to create a Game Test, there must be an existing template holding the initial start state of the scene and a method which provides the logic of execution.

=== The Test Method ===

A Game Test method is a <code>Consumer<GameTestHelper></code> reference, meaning it takes in a <code>GameTestHelper</code> and returns nothing. For a Game Test method to be recognized, it must have a <code>@GameTest</code> annotation:

<syntaxhighlight lang="java">
public class ExampleGameTests {
@GameTest
public static void exampleTest(GameTestHelper helper) {
// Do stuff
}
}
</syntaxhighlight>

The <code>@GameTest</code> annotation also contains members which configure how the game test should run.

<syntaxhighlight lang="java">
// In some class
@GameTest(
setupTicks = 20L, // The test spends 20 ticks to set up for execution
required = false // The failure is logged but does not affect the execution of the batch
)
public static void exampleConfiguredTest(GameTestHelper helper) {
// Do stuff
}
</syntaxhighlight>

==== Relative Positioning ====

All <code>GameTestHelper</code> methods translate relative coordinates within the structure template scene to its absolute coordinates using the structure block's current location. To allow for easy conversion between relative and absolute positioning, <code>GameTestHelper#absolutePos</code> and <code>GameTestHelper#relativePos</code> can be used respectively.

The relative position of a structure template can be obtained in-game by loading the structure via the [[#Running_Game_Tests|test command]], placing the player at the wanted location, and finally running the <code>/test pos</code> command. This will grab the coordinates of the player relative to the closest structure within 200 blocks of the player. The command will export the relative position as a copyable text component in the chat to be used as a final local variable.

{{Tip|The local variable generated by <code>/test pos</code> can specify its reference name by appending it to the end of the command:

<syntaxhighlight lang="powershell">
/test pos <var> # Exports 'final BlockPos <var> = new BlockPos(...);'
</syntaxhighlight>
}}

==== Successful Completion ====

A Game Test method is responsible for one thing: marking the test was successful on a valid completion. If no success state was achieved before the timeout is reached (as defined by <code>GameTest#timeoutTicks</code>), then the test automatically fails.

There are many abstracted methods within <code>GameTestHelper</code> which can be used to define a successful state; however, four are extremely important to be aware of.

{| class="wikitable"
|-
! Method !! Description
|-
| <code>#succeed</code> || The test is marked as successful.
|-
| <code>#succeedIf</code> || The supplied <code>Runnable</code> is tested immediately and succeeds if no <code>GameTestAssertException</code> is thrown. If the test does not succeed on the immediate tick, then it is marked as a failure.
|-
| <code>#succeedWhen</code> || The supplied <code>Runnable</code> is tested every tick until timeout and succeeds if the check on one of the ticks does not throw a <code>GameTestAssertException</code>.
|-
| <code>#succeedOnTickWhen</code> || The supplied <code>Runnable</code> is tested on the specified tick and will succeed if no <code>GameTestAssertException</code> is thrown. If the <code>Runnable</code> succeeds on any other tick, then it is marked as a failure.
|}

{{Tip/Important|Game Tests are executed every tick until the test is marked as a success. As such, methods which schedule success on a given tick must be careful to always fail on any previous tick.}}

==== Scheduling Actions ====

Not all actions will occur when a test begins. Actions can be scheduled to occur at specific times or intervals:

{| class="wikitable"
|-
! Method !! Description
|-
| <code>#runAtTickTime</code> || The action is ran on the specified tick.
|-
| <code>#runAfterDelay</code> || The action is ran <code>x</code> ticks after the current tick.
|-
| <code>#onEachTick</code> || The action is ran every tick.
|}

==== Assertions ====

At any time during a Game Test, an assertion can be made to check if a given condition is true. There are numerous assertion methods within <code>GameTestHelper</code>; however, it simplifies to throwing a <code>GameTestAssertException</code> whenever the appropriate state is not met.

=== Generated Test Methods ===

If Game Test methods need to be generated dynamically, a test method generator can be created. These methods take in no parameters and return a collection of <code>TestFunction</code>s. For a test method generator to be recognized, it must have a <code>@GameTestGenerator</code> annotation:

<syntaxhighlight lang="java">
public class ExampleGameTests {
@GameTestGenerator
public static Collection<TestFunction> exampleTests() {
// Return a collection of TestFunctions
}
}
</syntaxhighlight>

==== TestFunction ====

A <code>TestFunction</code> is the boxed information held by the <code>@GameTest</code> annotation and the method running the test.

{{Tip|Any methods annotated using <code>@GameTest</code> are translated into a <code>TestFunction</code> using <code>GameTestRegistry#turnMethodIntoTestFunction</code>. That method can be used as a reference for creating <code>TestFunction</code>s without the use of the annotation.}}

=== Batching ===

Game Tests can be executed in batches instead of registration order. A test can be added to a batch by having the same supplied <code>GameTest#batch</code> string.

On its own, batching does not provide anything useful. However, batching can be used to perform setup and teardown states on the current level the tests are running in. This is done by annotating a method with either <code>@BeforeBatch</code> for setup or <code>@AfterBatch</code> for takedown. The `#batch` methods must match the string supplied to the game test.

Batch methods are <code>Consumer<ServerLevel></code> references, meaning they take in a <code>ServerLevel</code> and return nothing:

<syntaxhighlight lang="java">
public class ExampleGameTests {
@BeforeBatch(batch = "firstBatch")
public static void beforeTest(ServerLevel level) {
// Perform setup
}

@GameTest(batch = "firstBatch")
public static void exampleTest2(GameTestHelper helper) {
// Do stuff
}
}
</syntaxhighlight>

== Registering a Game Test ==

A Game Test must be registered to be ran in-game. There are two methods of doing so: via the <code>@GameTestHolder</code> annotation or <code>RegisterGameTestsEvent</code>. Both registration methods still require the test methods to be annotated with either <code>@GameTest</code>, <code>@GameTestGenerator</code>, <code>@BeforeBatch</code>, or <code>@AfterBatch</code>.

=== GameTestHolder ===

The <code>@GameTestHolder</code> annotation registers any test methods within the type (class, interface, enum, or record). <code>@GameTestHolder</code> contains a single method which has multiple uses. In this instance, the supplied <code>#value</code> must be the mod id of the mod; otherwise, the test will not run under default configurations.

<syntaxhighlight lang="java">
@GameTestHolder(MODID)
public class ExampleGameTests {
// ...
}
</syntaxhighlight>

=== RegisterGameTestsEvent ===

<code>RegisterGameTestEvent</code> can also register either classes or methods using <code>#register</code>. The event listener must be [[Events#Event_Listeners|added]] to the mod event bus. Test methods registered this way must supply their mod id to <code>GameTest#templateNamespace</code> on every method annotated with <code>@GameTest</code>.

<syntaxhighlight lang="java">
// In some class
public void registerTests(RegisterGameTestsEvent event) {
event.register(ExampleGameTests.class);
}

// In ExampleGameTests
@GameTest(templateNamespace = MODID)
public static void exampleTest3(GameTestHelper helper) {
// Perform setup
}
</syntaxhighlight>

{{Tip|The value supplied to <code>GameTestHolder#value</code> and <code>GameTest#templateNamespace</code> can be different from the current mod id. The configuration within the [[#Enabling_Other_Namespaces|buildscript]] would need to be changed.}}

== Structure Templates ==

Game Tests are performed within scenes loaded by structures, or templates. All templates define the dimensions of the scene and the initial data (blocks and entities) that will be loaded. The template must be stored as an <code>.nbt</code> file within <code>data/<namespace>/structures</code>.

{{Tip|A structure template can be created and saved using a structure block.}}

The location of the template is specified by a few factors:

* If the namespace of the template is specified.
* If the class should be prepended to the name of the template.
* If the name of the template is specified.

The namespace of the template is determined by <code>GameTest#templateNamespace</code>, then <code>GameTestHolder#value</code> if not specified, then <code>minecraft</code> if neither is specified.

The simple class name is not prepended to the name of the template if the <code>@PrefixGameTestTemplate</code> is applied to a class or method with the test annotations and set to <code>false</code>. Otherwise, the simple class name is made lowercase and prepended and followed by a dot before the template name.

The name of the template is determined by <code>GameTest#template</code>. If not specified, then the lowercase name of the method is used instead.

<syntaxhighlight lang="java">
// Modid for all structures will be MODID
@GameTestHolder(MODID)
public class ExampleGameTests {

// Class name is prepended, template name is not specified
// Template Location at 'modid:examplegametests.exampletest'
@GameTest
public static void exampleTest(GameTestHelper helper) { /*...*/ }

// Class name is not prepended, template name is not specified
// Template Location at 'modid:exampletest2'
@PrefixGameTestTemplate(false)
@GameTest
public static void exampleTest2(GameTestHelper helper) { /*...*/ }

// Class name is prepended, template name is specified
// Template Location at 'modid:examplegametests.test_template'
@GameTest(template = "test_template")
public static void exampleTest3(GameTestHelper helper) { /*...*/ }

// Class name is not prepended, template name is specified
// Template Location at 'modid:test_template2'
@PrefixGameTestTemplate(false)
@GameTest(template = "test_template2")
public static void exampleTest4(GameTestHelper helper) { /*...*/ }
}
</syntaxhighlight>

== Running Game Tests ==

Game Tests can be run using the <code>/test</code> command. The <code>test</code> command is highly configurable; however, only a few are of importance to running tests:

{| class="wikitable"
|-
! Header text !! Header text
|-
| <code>run</code> || Runs the specified test: <code>run <test_name></code>.
|-
| <code>runall</code> || Runs all available tests.
|-
| <code>runthis</code> || Runs the nearest test to the player within 15 blocks.
|-
| <code>runthese</code> || Runs tests within 200 blocks of the player.
|-
| <code>runfailed</code> || Runs all tests that failed in the previous run.
|}

{{Tip|Subcommands follow the test command: <code>/test <subcommand></code>.}}

== Buildscript Configurations ==

Game Tests provide additional configuration settings within a buildscript (the <code>build.gradle</code> file) to run and integrate into different settings.

=== Enabling Other Namespaces ===

If the buildscript was [[Getting_Started#Customizing_the_MDK|setup as recommended]], then only Game Tests under the current mod id would be enabled. To enable other namespaces to load Game Tests from, a run configuration must set the property <code>forge.enabledGameTestNamespaces</code> to a string specifying each namespace separated by a comma. If the property is empty or not set, then all namespaces will be loaded.

<syntaxhighlight lang="gradle">
// Inside a run configuration
property 'forge.enabledGameTestNamespaces', 'modid1,modid2,modid3'
</syntaxhighlight>

{{Tip/Warning|There must be no spaces in-between namespaces; otherwise, the namespace will not be loaded correctly.}}

=== Game Test Server Run Configuration ===

The Game Test Server is a special configuration which runs a build server. The build server returns an exit code of the number of required, failed Game Tests. All failed tests, whether required or optional, are logged. This server can be run using <code>gradlew runGameTestServer</code>.

=== Enabling Game Tests in Other Run Configurations ===

By default, only the <code>client</code>, <code>server</code>, and <code>gameTestServer</code> run configurations have Game Tests enabled. If another run configuration should run Game Tests, then the <code>forge.enableGameTest</code> property must be set to <code>true</code>.

<syntaxhighlight lang="gradle">
// Inside a run configuration
property 'forge.enableGameTest', 'true'
</syntaxhighlight>

Events

2022-04-03T13:09:50Z

ChampionAsh5357: Add mod bus list

{{Under construction}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{Tip|title=Tip|The mod-specific event buses are provided by the <code>javafml</code> language provider which is builtin to Forge Mod Loader. Custom language providers may provide other ways for mods to receive the different mod-related initialization and registration events; see the documentation of your custom language provider for details.}}

List of events fired on the Mod-Specific event bus{{:Events/Mod bus}}

====Network Channel Event Buses====
The '''network channel event buses''' are the family of event buses where different network-related events are fired. Each registered [[Networking|networking channel]] has their own instance of an event-bus in <code>NetworkInstance</code>, where only events pertinent to that channel are fired on.

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

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

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

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

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

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

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

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

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

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

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

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

public void nonAnnotatedInstance(Event event) {}

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

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

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

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

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

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

</tab>

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

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

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

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

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

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

== Sub Events ==

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

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

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

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

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

Each of these will be explained in detail as follows.

=== Annotated Event Handlers ===

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

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

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

=== Static Event Handlers ===

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

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

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

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

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

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

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

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

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

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

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

=== Non-Annotated Event Handlers ===

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

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

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

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

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

== Cancelling ==

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

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

== Results ==

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

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

== Priority ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Category:Events]]

[[Category:Common Concepts]]

Events/Mod bus

2022-04-03T13:08:10Z

ChampionAsh5357: Add mod event list

{{Tree list}}
* <code>IModBusEvent</code> - ''The interface for all mod bus events''
** <code>ModelBakeEvent</code>
** <code>EntityRenderersEvent</code>
*** <code>AddLayers</code> in <code>EntityRenderersEvent</code>
*** <code>CreateSkullModels</code> in <code>EntityRenderersEvent</code>
*** <code>RegisterRenderers</code> in <code>EntityRenderersEvent</code>
*** <code>RegisterLayerDefinitions</code> in <code>EntityRenderersEvent</code>
** <code>VanillaRegisterEvent</code>
** <code>SoundLoadEvent</code>
** <code>ModelRegistryEvent</code>
** <code>GatherDataEvent</code>
** <code>RegisterShadersEvent</code>
** <code>AddPackFindersEvent</code>
** <code>ModLifecycleEvent</code>
*** <code>ParallelDispatchEvent</code>
**** <code>FMLCommonSetupEvent</code>
**** <code>InterModProcessEvent</code>
**** <code>FMLDedicatedServerSetupEvent</code>
**** <code>FMLConstructModEvent</code>
**** <code>InterModEnqueueEvent</code>
**** <code>FMLClientSetupEvent</code>
**** <code>FMLLoadCompleteEvent</code>
** <code>EntityAttributeCreationEvent</code>
** <code>NewRegistryEvent</code>
** <code>RegisterGameTestsEvent</code>
** <code>ParticleFactoryRegisterEvent</code>
** <code>RegisterCapabilitiesEvent</code>
** <code>TextureStitchEvent</code>
*** <code>Pre</code> in <code>TextureStitchEvent</code>
*** <code>Post</code> in <code>TextureStitchEvent</code>
** <code>EntityAttributeModificationEvent</code>
** <code>RegistryEvent</code>
*** <code>Register</code> in <code>RegistryEvent</code>
*** <code>MissingMappings</code> in <code>RegistryEvent</code>
** <code>RegisterClientReloadListenersEvent</code>
** <code>ColorHandlerEvent</code>
*** <code>Block</code> in <code>ColorHandlerEvent</code>
*** <code>Item</code> in <code>ColorHandlerEvent</code>
** <code>ModConfigEvent</code>
*** <code>Reloading</code> in <code>ModConfigEvent</code>
*** <code>Loading</code> in <code>ModConfigEvent</code>
{{Tree list/end}}

Events/Forge bus

2022-04-03T13:07:29Z

ChampionAsh5357: Update event list

{{Tree list}}
* <code>Event</code> - ''The root superclass for all events''
** <code>RecipesUpdatedEvent</code>
** <code>BiomeLoadingEvent</code>
** <code>FurnaceFuelBurnTimeEvent</code>
** <code>DrawSelectionEvent</code>
*** <code>HighlightBlock</code> in <code>DrawSelectionEvent</code>
*** <code>HighlightEntity</code> in <code>DrawSelectionEvent</code>
** <code>VillagerTradesEvent</code>
** <code>AddReloadListenerEvent</code>
** <code>ClientPlayerChangeGameTypeEvent</code>
** <code>RenderHandEvent</code>
** <code>RenderLivingEvent</code>
*** <code>Pre</code> in <code>RenderLivingEvent</code>
*** <code>Post</code> in <code>RenderLivingEvent</code>
** <code>RegisterCommandsEvent</code>
** <code>RenderItemInFrameEvent</code>
** <code>IdMappingEvent</code> in <code>RegistryEvent</code>
** <code>RenderBlockOverlayEvent</code>
** <code>BlockEvent</code>
*** <code>NoteBlockEvent</code>
**** <code>Change</code> in <code>NoteBlockEvent</code>
**** <code>Play</code> in <code>NoteBlockEvent</code>
*** <code>NeighborNotifyEvent</code> in <code>BlockEvent</code>
*** <code>BlockToolInteractEvent</code> in <code>BlockEvent</code>
*** <code>BreakEvent</code> in <code>BlockEvent</code>
*** <code>EntityPlaceEvent</code> in <code>BlockEvent</code>
**** <code>EntityMultiPlaceEvent</code> in <code>BlockEvent</code>
*** <code>PistonEvent</code>
**** <code>Pre</code> in <code>PistonEvent</code>
**** <code>Post</code> in <code>PistonEvent</code>
*** <code>PortalSpawnEvent</code> in <code>BlockEvent</code>
*** <code>FarmlandTrampleEvent</code> in <code>BlockEvent</code>
*** <code>FluidPlaceBlockEvent</code> in <code>BlockEvent</code>
*** <code>CropGrowEvent</code> in <code>BlockEvent</code>
**** <code>Pre</code> in <code>CropGrowEvent</code> in <code>BlockEvent</code>
**** <code>Post</code> in <code>CropGrowEvent</code> in <code>BlockEvent</code>
** <code>WorldEvent</code>
*** <code>Load</code> in <code>WorldEvent</code>
*** <code>CreateSpawnPosition</code> in <code>WorldEvent</code>
*** <code>Unload</code> in <code>WorldEvent</code>
*** <code>ChunkEvent</code>
**** <code>Load</code> in <code>ChunkEvent</code>
**** <code>Unload</code> in <code>ChunkEvent</code>
**** <code>ChunkDataEvent</code>
***** <code>Save</code> in <code>ChunkDataEvent</code>
***** <code>Load</code> in <code>ChunkDataEvent</code>
*** <code>SleepFinishedTimeEvent</code>
*** <code>Save</code> in <code>WorldEvent</code>
*** <code>SaplingGrowTreeEvent</code>
** <code>BabyEntitySpawnEvent</code>
** <code>ContainerScreenEvent</code>
*** <code>DrawBackground</code> in <code>ContainerScreenEvent</code>
*** <code>DrawForeground</code> in <code>ContainerScreenEvent</code>
** <code>ServerChatEvent</code>
** <code>ScreenEvent</code>
*** <code>PotionShiftEvent</code> in <code>ScreenEvent</code>
*** <code>KeyboardKeyEvent</code> in <code>ScreenEvent</code>
**** <code>KeyboardKeyReleasedEvent</code> in <code>ScreenEvent</code>
***** <code>Pre</code> in <code>KeyboardKeyReleasedEvent</code> in <code>ScreenEvent</code>
***** <code>Post</code> in <code>KeyboardKeyReleasedEvent</code> in <code>ScreenEvent</code>
**** <code>KeyboardKeyPressedEvent</code> in <code>ScreenEvent</code>
***** <code>Post</code> in <code>KeyboardKeyPressedEvent</code> in <code>ScreenEvent</code>
***** <code>Pre</code> in <code>KeyboardKeyPressedEvent</code> in <code>ScreenEvent</code>
*** <code>InitScreenEvent</code> in <code>ScreenEvent</code>
**** <code>Pre</code> in <code>InitScreenEvent</code> in <code>ScreenEvent</code>
**** <code>Post</code> in <code>InitScreenEvent</code> in <code>ScreenEvent</code>
*** <code>MouseInputEvent</code> in <code>ScreenEvent</code>
**** <code>MouseReleasedEvent</code> in <code>ScreenEvent</code>
***** <code>Pre</code> in <code>MouseReleasedEvent</code> in <code>ScreenEvent</code>
***** <code>Post</code> in <code>MouseReleasedEvent</code> in <code>ScreenEvent</code>
**** <code>MouseScrollEvent</code> in <code>ScreenEvent</code>
***** <code>Pre</code> in <code>MouseScrollEvent</code> in <code>ScreenEvent</code>
***** <code>Post</code> in <code>MouseScrollEvent</code> in <code>ScreenEvent</code>
**** <code>MouseClickedEvent</code> in <code>ScreenEvent</code>
***** <code>Post</code> in <code>MouseClickedEvent</code> in <code>ScreenEvent</code>
***** <code>Pre</code> in <code>MouseClickedEvent</code> in <code>ScreenEvent</code>
**** <code>MouseDragEvent</code> in <code>ScreenEvent</code>
***** <code>Post</code> in <code>MouseDragEvent</code> in <code>ScreenEvent</code>
***** <code>Pre</code> in <code>MouseDragEvent</code> in <code>ScreenEvent</code>
*** <code>KeyboardCharTypedEvent</code> in <code>ScreenEvent</code>
**** <code>Pre</code> in <code>KeyboardCharTypedEvent</code> in <code>ScreenEvent</code>
**** <code>Post</code> in <code>KeyboardCharTypedEvent</code> in <code>ScreenEvent</code>
*** <code>PotionSizeEvent</code> in <code>ScreenEvent</code>
*** <code>DrawScreenEvent</code> in <code>ScreenEvent</code>
**** <code>Post</code> in <code>DrawScreenEvent</code> in <code>ScreenEvent</code>
**** <code>Pre</code> in <code>DrawScreenEvent</code> in <code>ScreenEvent</code>
*** <code>BackgroundDrawnEvent</code> in <code>ScreenEvent</code>
** <code>VillageSiegeEvent</code>
** <code>LootTableLoadEvent</code>
** <code>TagsUpdatedEvent</code>
** <code>PotionBrewEvent</code>
*** <code>Pre</code> in <code>PotionBrewEvent</code>
*** <code>Post</code> in <code>PotionBrewEvent</code>
** <code>ClientChatReceivedEvent</code>
** <code>InputEvent</code>
*** <code>ClickInputEvent</code> in <code>InputEvent</code>
*** <code>KeyInputEvent</code> in <code>InputEvent</code>
*** <code>MouseInputEvent</code> in <code>InputEvent</code>
*** <code>RawMouseEvent</code> in <code>InputEvent</code>
*** <code>MouseScrollEvent</code> in <code>InputEvent</code>
** <code>RegisterClientCommandsEvent</code>
** <code>GatherComponents</code> in <code>RenderTooltipEvent</code>
** <code>DifficultyChangeEvent</code>
** <code>ServerLifecycleEvent</code>
*** <code>ServerStoppingEvent</code>
*** <code>ServerStoppedEvent</code>
*** <code>ServerAboutToStartEvent</code>
*** <code>ServerStartedEvent</code>
*** <code>ServerStartingEvent</code>
** <code>ScreenshotEvent</code>
** <code>EnchantmentLevelSetEvent</code>
** <code>RenderTooltipEvent</code>
*** <code>Pre</code> in <code>RenderTooltipEvent</code>
*** <code>Color</code> in <code>RenderTooltipEvent</code>
** <code>CreateFluidSourceEvent</code> in <code>BlockEvent</code>
** <code>VanillaGameEvent</code>
** <code>RenderGameOverlayEvent</code>
*** <code>Pre</code> in <code>RenderGameOverlayEvent</code>
**** <code>Text</code> in <code>RenderGameOverlayEvent</code>
**** <code>BossInfo</code> in <code>RenderGameOverlayEvent</code>
**** <code>PreLayer</code> in <code>RenderGameOverlayEvent</code>
**** <code>Chat</code> in <code>RenderGameOverlayEvent</code>
*** <code>Post</code> in <code>RenderGameOverlayEvent</code>
**** <code>PostLayer</code> in <code>RenderGameOverlayEvent</code>
** <code>ClientChatEvent</code>
** <code>CommandEvent</code>
** <code>StructureSpawnListGatherEvent</code>
** <code>PermissionGatherEvent</code>
*** <code>Handler</code> in <code>PermissionGatherEvent</code>
*** <code>Nodes</code> in <code>PermissionGatherEvent</code>
** <code>OnDatapackSyncEvent</code>
** <code>GenericEvent</code> - (from EventBus) ''the superclass for events with generic types''
*** <code>AttachCapabilitiesEvent</code>
** <code>ExplosionEvent</code>
*** <code>Detonate</code> in <code>ExplosionEvent</code>
*** <code>Start</code> in <code>ExplosionEvent</code>
** <code>SoundEvent</code>
*** <code>SoundSetupEvent</code>
*** <code>SoundSourceEvent</code> in <code>SoundEvent</code>
**** <code>PlaySoundSourceEvent</code>
**** <code>PlayStreamingSourceEvent</code>
*** <code>PlaySoundEvent</code>
** <code>AnvilUpdateEvent</code>
** <code>ScreenOpenEvent</code>
** <code>RenderArmEvent</code>
** <code>RenderLevelLastEvent</code>
** <code>TickEvent</code>
*** <code>PlayerTickEvent</code> in <code>TickEvent</code>
*** <code>ServerTickEvent</code> in <code>TickEvent</code>
*** <code>WorldTickEvent</code> in <code>TickEvent</code>
*** <code>ClientTickEvent</code> in <code>TickEvent</code>
*** <code>RenderTickEvent</code> in <code>TickEvent</code>
** <code>WandererTradesEvent</code>
** <code>ItemAttributeModifierEvent</code>
** <code>EntityViewRenderEvent</code>
*** <code>FieldOfView</code> in <code>EntityViewRenderEvent</code>
*** <code>FogEvent</code> in <code>EntityViewRenderEvent</code>
**** <code>RenderFogEvent</code> in <code>EntityViewRenderEvent</code>
**** <code>FogDensity</code> in <code>EntityViewRenderEvent</code>
*** <code>FogColors</code> in <code>EntityViewRenderEvent</code>
*** <code>CameraSetup</code> in <code>EntityViewRenderEvent</code>
** <code>ClientPlayerNetworkEvent</code>
*** <code>LoggedOutEvent</code> in <code>ClientPlayerNetworkEvent</code>
*** <code>LoggedInEvent</code> in <code>ClientPlayerNetworkEvent</code>
*** <code>RespawnEvent</code> in <code>ClientPlayerNetworkEvent</code>
** <code>FOVModifierEvent</code>
** <code>EntityEvent</code>
*** <code>EntityTeleportEvent</code>
**** <code>SpreadPlayersCommand</code> in <code>EntityTeleportEvent</code>
**** <code>EnderEntity</code> in <code>EntityTeleportEvent</code>
**** <code>EnderPearl</code> in <code>EntityTeleportEvent</code>
**** <code>TeleportCommand</code> in <code>EntityTeleportEvent</code>
**** <code>ChorusFruit</code> in <code>EntityTeleportEvent</code>
*** <code>ProjectileImpactEvent</code>
*** <code>EntityTravelToDimensionEvent</code>
*** <code>EntityMobGriefingEvent</code>
*** <code>RenderNameplateEvent</code>
*** <code>EntityConstructing</code> in <code>EntityEvent</code>
*** <code>EntityMountEvent</code>
*** <code>EntityStruckByLightningEvent</code>
*** <code>CanUpdate</code> in <code>EntityEvent</code>
*** <code>Size</code> in <code>EntityEvent</code>
*** <code>EntityJoinWorldEvent</code>
*** <code>EnteringSection</code> in <code>EntityEvent</code>
*** <code>LivingEvent</code>
**** <code>LivingEquipmentChangeEvent</code>
**** <code>SleepingLocationCheckEvent</code>
**** <code>LivingUpdateEvent</code> in <code>LivingEvent</code>
**** <code>PotionColorCalculationEvent</code>
**** <code>LivingExperienceDropEvent</code>
**** <code>LivingDamageEvent</code>
**** <code>LivingAttackEvent</code>
**** <code>LivingEntityUseItemEvent</code>
***** <code>Start</code> in <code>LivingEntityUseItemEvent</code>
***** <code>Tick</code> in <code>LivingEntityUseItemEvent</code>
***** <code>Stop</code> in <code>LivingEntityUseItemEvent</code>
***** <code>Finish</code> in <code>LivingEntityUseItemEvent</code>
**** <code>PotionEvent</code>
***** <code>PotionExpiryEvent</code> in <code>PotionEvent</code>
***** <code>PotionApplicableEvent</code> in <code>PotionEvent</code>
***** <code>PotionRemoveEvent</code> in <code>PotionEvent</code>
***** <code>PotionAddedEvent</code> in <code>PotionEvent</code>
**** <code>LivingPackSizeEvent</code>
**** <code>PlayerEvent</code>
***** <code>PlayerChangeGameModeEvent</code> in <code>PlayerEvent</code>
***** <code>PlayerContainerEvent</code>
****** <code>Close</code> in <code>PlayerContainerEvent</code>
****** <code>Open</code> in <code>PlayerContainerEvent</code>
***** <code>PlayerWakeUpEvent</code>
***** <code>BreakSpeed</code> in <code>PlayerEvent</code>
***** <code>ItemSmeltedEvent</code> in <code>PlayerEvent</code>
***** <code>ArrowLooseEvent</code>
***** <code>Clone</code> in <code>PlayerEvent</code>
***** <code>UseHoeEvent</code>
***** <code>MovementInputUpdateEvent</code>
***** <code>AdvancementEvent</code>
***** <code>AnvilRepairEvent</code>
***** <code>PlayerSleepInBedEvent</code>
***** <code>PlayerLoggedOutEvent</code> in <code>PlayerEvent</code>
***** <code>PlayerXpEvent</code>
****** <code>XpChange</code> in <code>PlayerXpEvent</code>
****** <code>LevelChange</code> in <code>PlayerXpEvent</code>
****** <code>PickupXp</code> in <code>PlayerXpEvent</code>
***** <code>StopTracking</code> in <code>PlayerEvent</code>
***** <code>PlayerDestroyItemEvent</code>
***** <code>FillBucketEvent</code>
***** <code>BonemealEvent</code>
***** <code>SleepingTimeCheckEvent</code>
***** <code>PlayerInteractEvent</code>
****** <code>EntityInteractSpecific</code> in <code>PlayerInteractEvent</code>
****** <code>RightClickBlock</code> in <code>PlayerInteractEvent</code>
****** <code>EntityInteract</code> in <code>PlayerInteractEvent</code>
****** <code>RightClickEmpty</code> in <code>PlayerInteractEvent</code>
****** <code>RightClickItem</code> in <code>PlayerInteractEvent</code>
****** <code>LeftClickEmpty</code> in <code>PlayerInteractEvent</code>
****** <code>LeftClickBlock</code> in <code>PlayerInteractEvent</code>
***** <code>EntityItemPickupEvent</code>
***** <code>HarvestCheck</code> in <code>PlayerEvent</code>
***** <code>ItemPickupEvent</code> in <code>PlayerEvent</code>
***** <code>TabListNameFormat</code> in <code>PlayerEvent</code>
***** <code>PlayerChangedDimensionEvent</code> in <code>PlayerEvent</code>
***** <code>PlayerSetSpawnEvent</code>
***** <code>PlayerFlyableFallEvent</code>
***** <code>LoadFromFile</code> in <code>PlayerEvent</code>
***** <code>PermissionsChangedEvent</code>
***** <code>CriticalHitEvent</code>
***** <code>StartTracking</code> in <code>PlayerEvent</code>
***** <code>ItemFishedEvent</code>
***** <code>ArrowNockEvent</code>
***** <code>PlayerRespawnEvent</code> in <code>PlayerEvent</code>
***** <code>ItemTooltipEvent</code>
***** <code>SaveToFile</code> in <code>PlayerEvent</code>
***** <code>PlayerLoggedInEvent</code> in <code>PlayerEvent</code>
***** <code>ItemCraftedEvent</code> in <code>PlayerEvent</code>
***** <code>NameFormat</code> in <code>PlayerEvent</code>
***** <code>RenderPlayerEvent</code>
****** <code>Post</code> in <code>RenderPlayerEvent</code>
****** <code>Pre</code> in <code>RenderPlayerEvent</code>
***** <code>AttackEntityEvent</code>
***** <code>PlayerBrewedPotionEvent</code>
**** <code>LivingHealEvent</code>
**** <code>ShieldBlockEvent</code>
**** <code>LootingLevelEvent</code>
**** <code>LivingDestroyBlockEvent</code>
**** <code>LivingConversionEvent</code>
***** <code>Pre</code> in <code>LivingConversionEvent</code>
***** <code>Post</code> in <code>LivingConversionEvent</code>
**** <code>LivingKnockBackEvent</code>
**** <code>LivingHurtEvent</code>
**** <code>LivingVisibilityEvent</code> in <code>LivingEvent</code>
**** <code>LivingDeathEvent</code>
**** <code>LivingFallEvent</code>
**** <code>AnimalTameEvent</code>
**** <code>LivingGetProjectileEvent</code>
**** <code>LivingSpawnEvent</code>
***** <code>AllowDespawn</code> in <code>LivingSpawnEvent</code>
***** <code>CheckSpawn</code> in <code>LivingSpawnEvent</code>
***** <code>SpecialSpawn</code> in <code>LivingSpawnEvent</code>
**** <code>LivingSetAttackTargetEvent</code>
**** <code>LivingJumpEvent</code> in <code>LivingEvent</code>
**** <code>LivingDropsEvent</code>
*** <code>ZombieEvent</code>
**** <code>SummonAidEvent</code> in <code>ZombieEvent</code>
*** <code>PlaySoundAtEntityEvent</code>
*** <code>EntityLeaveWorldEvent</code>
*** <code>ItemEvent</code>
**** <code>ItemTossEvent</code>
**** <code>ItemExpireEvent</code>
** <code>NetworkEvent</code>
*** <code>ServerCustomPayloadEvent</code> in <code>NetworkEvent</code>
**** <code>ServerCustomPayloadLoginEvent</code> in <code>NetworkEvent</code>
*** <code>LoginPayloadEvent</code> in <code>NetworkEvent</code>
*** <code>ChannelRegistrationChangeEvent</code> in <code>NetworkEvent</code>
*** <code>ClientCustomPayloadEvent</code> in <code>NetworkEvent</code>
**** <code>ClientCustomPayloadLoginEvent</code> in <code>NetworkEvent</code>
** <code>GatherLoginPayloadsEvent</code> in <code>NetworkEvent</code>
** <code>ChunkWatchEvent</code>
*** <code>UnWatch</code> in <code>ChunkWatchEvent</code>
*** <code>Watch</code> in <code>ChunkWatchEvent</code>
{{Tree list/end}}

Registration

2022-04-02T23:36:50Z

ChampionAsh5357: Update registry docs to 8527

{{Under construction}}

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

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

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

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

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

== Methods for Registering ==

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

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

=== DeferredRegister ===

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

An example of a mod registering a custom block:

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

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

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

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

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

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

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

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

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

=== RegistryEvent.Register ===

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

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

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

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

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

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

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

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

=== Non-Forge Registries ===

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

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

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

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

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

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

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

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

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

=== Data Driven Entries ===

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

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

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

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

== Referencing Registered Objects ==

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

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

===Using RegistryObjects===
<code>RegistryObject</code>s can be used to retrieve references to registered objects once they become available. Their references are updated along with all <code>@ObjectHolder</code> annotations after the associated <code>RegistryEvent$Register</code> has been dispatched and frozen.

A <code>RegistryObject</code> can be retrieved as a result of using <code>DeferredRegister</code> or calling the static constructor <code>RegistryObject::create</code>. Each static constructor takes in the "registry name" of the object being referenced and either a <code>IForgeRegistry</code> or, if custom registries are used, a supplier of the object class implementing <code>IForgeRegistryEntry</code>. The <code>RegistryObject</code> can be stored within some field and retrieve the registered object using <code>#get</code>.

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

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

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

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

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

=== Using @ObjectHolder ===

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

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

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

<code>@ObjectHolder</code> annotated fields are injected with their associated object values after their corresponding registry's <code>RegistryEvent$Register</code> event is fired, along with <code>RegistryObject</code>s.

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

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

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

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

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

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

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

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

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

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

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

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

== Creating Custom Registries ==

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

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

For the class that implements <code>IForgeRegistryEntry</code>, it is recommended in most cases to extend the default implementation of <code>ForgeRegistryEntry</code>. For interfaces, it should extend <code>IForgeRegistryEntry</code> with its implementations extending <code>ForgeRegistryEntry</code>.

=== With DeferredRegister ===

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

Here is an example:

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

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

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

final lazy val REGISTRY = EXAMPLE.makeRegistry(classOf[ExampleRegistry], () => new RegistryBuilder).get
|}}

=== Using RegistryEvent$NewRegistry ===

The second method can be done during the <code>RegistryEvent$NewRegistry</code> event. This will call a new instance of the builder directly. From there, the registry can be built and stored via <code>RegistryBuilder#create</code>. This will cause the registry to be registered to the <code>RegistryManager</code> and returned to the caller for additional processing.

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

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

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

== Handling Missing Entries ==

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

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

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

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

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

[[Category:Common Concepts]]

SimpleChannel

2022-03-29T00:30:35Z

ChampionAsh5357: There's your code example shrimp!

SimpleChannel is the name given to the packet system that revolves around the <code><nowiki>SimpleChannel</nowiki></code> class. Using this system is by far the easiest way to send custom data between clients and the server.

== Getting Started ==

First you need to create your <code><nowiki>SimpleChannel</nowiki></code> object. We recommend that you do this in a separate class, possibly something like <code><nowiki>ModidPacketHandler</nowiki></code>. Create your <code><nowiki>SimpleChannel</nowiki></code> as a static field in this class, like so:

<syntaxhighlight lang="java">
private static final String PROTOCOL_VERSION = "1";
public static final SimpleChannel INSTANCE = NetworkRegistry.newSimpleChannel(
new ResourceLocation("mymodid", "main"),
() -> PROTOCOL_VERSION,
PROTOCOL_VERSION::equals,
PROTOCOL_VERSION::equals
);
</syntaxhighlight>

The first argument is a name for the channel. The second argument is a <code><nowiki>Supplier<String></nowiki></code> returning the current network protocol version. The third and fourth arguments respectively are <code><nowiki>Predicate<String></nowiki></code> checking whether an incoming connection protocol version is network-compatible with the client or server, respectively.
Here, we simply compare with the <code><nowiki>PROTOCOL_VERSION</nowiki></code> field directly, meaning that the client and server <code><nowiki>PROTOCOL_VERSION</nowiki></code>s must always match or FML will deny login.

== Protocol Versions ==
If your mod does not require the other side to have a specific network channel, or to be a Forge instance at all, you should take care that you properly define your version compatibility checkers (the <code><nowiki>Predicate<String></nowiki></code> parameters) to handle additional "meta-versions" (defined in <code><nowiki>NetworkRegistry</nowiki></code>) that can be received by the version checker. These are:
* <code><nowiki>ABSENT</nowiki></code> - if this channel is missing on the other endpoint. Note that in this case, the endpoint is still a Forge endpoint, and may have other mods.
* <code><nowiki>ACCEPTVANILLA</nowiki></code> - if the endpoint is a vanilla (or non-Forge) endpoint.

Returning <code><nowiki>false</nowiki></code> for both means that this channel must be present on the other endpoint. If you just copy the code above, this is what it does. Note that these values are also used during the list ping compatibility check, which is responsible for showing the green check / red cross in the multiplayer server select screen.

== Registering Packets ==

Next, we must declare the types of messages that we would like to send and receive. This is done using the <code><nowiki>INSTANCE.registerMessage</nowiki></code> method, which takes 5 parameters.

* The first parameter is the discriminator for the packet. This is a per-channel unique ID for the packet. We recommend you use a local variable to hold the ID, and then call registerMessage using <code><nowiki>id++</nowiki></code>. This will guarantee 100% unique IDs.
* The second parameter is the actual packet class <code><nowiki>MSG</nowiki></code>.
* The third parameter is a <code><nowiki>BiConsumer<MSG, FriendlyByteBuf></nowiki></code> responsible for encoding the message into the provided <code><nowiki>FriendlyByteBuf</nowiki></code>
* The fourth parameter is a <code><nowiki>Function<FriendlyByteBuf, MSG></nowiki></code> responsible for decoding the message from the provided <code><nowiki>FriendlyByteBuf</nowiki></code>
* The final parameter is a <code><nowiki>BiConsumer<MSG, Supplier<NetworkEvent.Context>></nowiki></code> responsible for handling the message itself

The last three parameters can be method references to either static or instance methods in Java. Remember that an instance method <code><nowiki>MSG.encode(FriendlyByteBuf)</nowiki></code> still satisfies <code><nowiki>BiConsumer<MSG, FriendlyByteBuf></nowiki></code>, the <code><nowiki>MSG</nowiki></code> simply becomes the implicit first argument.

<syntaxhighlight lang="java">
// A class MessagePacket
public void encoder(FriendlyByteBuf buffer) {
// Write to buffer
}

public static MessagePacket decoder(FriendlyByteBuf buffer) {
// Create packet from buffer data
}

public void messageConsumer(Supplier<NetworkEvent.Context>> ctx) {
// Handle message
}

// For some SimpleChannel channel
channel.registerMessage(id, MessagePacket::encoder, MessagePacket::decoder, MessagePacket::messageConsumer);
</syntaxhighlight>

== Handling Packets ==

There are a couple things to highlight in a packet handler. A packet handler has both the message object and the network context available to it. The context allows access to the player that sent the packet (if on the server), and a way to enqueue threadsafe work.

<syntaxhighlight lang="java">
public static void handle(MyMessage msg, Supplier<NetworkEvent.Context> ctx) {
ctx.get().enqueueWork(() -> {
// Work that needs to be threadsafe (most work)
ServerPlayer sender = ctx.get().getSender(); // the client that sent this packet
// do stuff
});
ctx.get().setPacketHandled(true);
}
</syntaxhighlight>

Packets sent from the server to the client should be handled in another class and wrapped via <code>DistExecutor#unsafeRunWhenOn</code>.

<syntaxhighlight lang="java">
// In Packet class
public static void handle(MyClientMessage msg, Supplier<NetworkEvent.Context> ctx) {
ctx.get().enqueueWork(() ->
// Make sure it's only executed on the physical client
DistExecutor.unsafeRunWhenOn(Dist.CLIENT, () -> () -> ClientPacketHandlerClass.handlePacket(msg, ctx))
);
ctx.get().setPacketHandled(true);
}

// In ClientPacketHandlerClass
public static void handlePacket(MyClientMessage msg, Supplier<NetworkEvent.Context> ctx) {
// Do stuff
}
</syntaxhighlight>

Note the presence of <code><nowiki>#setPacketHandled</nowiki></code>, which used to tell the network system that the packet has successfully completed handling.

=== Common Packet Handling Pitfalls ===

{{Colored box|title=Know that packets are by default handled on the network thread.|content=
That means that your handler can ''not'' interact with most game objects directly.
Forge provides a convenient way to make your code execute on the main thread through the supplied <code><nowiki>NetworkEvent$Context</nowiki></code>.
Simply call <code><nowiki>NetworkEvent$Context#enqueueWork(Runnable)</nowiki></code>, which will call the given <code><nowiki>Runnable</nowiki></code> on the main thread at the next opportunity.}}

{{Colored box|title=Be defensive when handling packets on the server.|content=
A client could attempt to exploit the packet handling by sending unexpected data.
<br>
A common problem is vulnerability to <code>arbitrary chunk generation</code>. This typically happens when the server is trusting a block position sent by a client to access blocks and block entities. When accessing blocks and block entities in unloaded areas of the level, the server will either generate or load this area from disk, then promply write it to disk. This can be exploited to cause <code>catastrophic damage</code> to a server's performance and storage space without leaving a trace.
<br>
To avoid this problem, a general rule of thumb is to only access blocks and block entities if <code><nowiki>Level#hasChunkAt</nowiki></code> is true.}}

{{Colored box|title=Register encoders on the physical client, as well as the physical server.|content=
If you only register an encoder for a clientbound packet on the physical server, your mod will likely crash or present unintended behaviour in single-player worlds. ''Forge will happily send packets that have no encoder defined, '''without a warning or error message!''''' They will be encoded as a 256-long byte buffer filled only with null bytes, by default.
<br>}}

== Sending Packets ==

=== Sending to the Server ===

There is but one way to send a packet to the server. This is because there is only ever *one* server the client can be connected to at once. To do so, we must again use that <code><nowiki>SimpleChannel</nowiki></code> that was defined earlier. Simply call <code><nowiki>INSTANCE.sendToServer(new MyMessage())</nowiki></code>. The message will be sent to the handler for its type, if one exists.

=== Sending to Clients ===

Packets can be sent directly to a client using the <code><nowiki>SimpleChannel</nowiki></code>: <code><nowiki>HANDLER.sendTo(MSG, serverPlayer.connection.getConnection(), NetworkDirection.PLAY_TO_CLIENT)</nowiki></code>. However, this can be quite inconvenient. Forge has some convenience functions that can be used:

<syntaxhighlight lang="java">
// Sending to one player
INSTANCE.send(PacketDistributor.PLAYER.with(serverPlayer), new MyMessage());

// Send to all players tracking this level chunk
INSTANCE.send(PacketDistributor.TRACKING_CHUNK.with(levelChunk), new MyMessage());

// Sending to all connected players
INSTANCE.send(PacketDistributor.ALL.noArg(), new MyMessage());
</syntaxhighlight>

There are additional <code><nowiki>PacketDistributor</nowiki></code> types available, check the documentation on the <code><nowiki>PacketDistributor</nowiki></code> class for more details.