Forge Community Wiki - User contributions [en-gb]

Custom recipes

2023-04-15T23:01:54Z

SciWhiz12: Redirected page to Custom Recipes

#REDIRECT [[Custom Recipes]]

Main Page

2022-08-13T20:38:46Z

SciWhiz12: change link to Datapack_Registries

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

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

The Forge Community Wiki exists so that the community can:

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

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

{{Supported versions}}

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

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

<div class="box_container center">

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

</div>

Datageneration/Datapack Registries

2022-08-13T20:37:09Z

SciWhiz12: SciWhiz12 moved page Datageneration/Datapack Registries to Datapack Registries: by request of User:SizableShrimp

#REDIRECT [[Datapack Registries]]

Datapack Registries

2022-08-13T20:37:09Z

SciWhiz12: SciWhiz12 moved page Datageneration/Datapack Registries to Datapack Registries: by request of User:SizableShrimp

Datapack Registries (sometimes called dynamic registries or worldgen registries) are a set of registries that are able to load data from JSONS when a server starts. These include all vanilla registries enumerated in RegistryAccess.REGISTRIES (such as biomes, placed features, and dimensiontypes) as well as any [[Registration#Creating_Custom_Registries|custom forge registry]] marked with <code>datapackRegistry()</code> in its registry builder (such as forge's [[Biome Modifiers]] and Structure Modifiers).

These registries have the ability to have their objects registered in Java ''or'' defined in JSON.

If a mod ships a JSON for a datapack registry element in its builtin datapack, then it is not necessary for that mod to register the object in java; however, it is also possible to create the object during GatherDataEvent and datagenerate the JSON.

All datapack registries are automatically datagenerable; each registry has a [[Codecs|Codec]] registered to it, which defines the serialization, and each registry's registry id determines its json directory. Elements of vanilla registries are loaded from <code>data/{element-namespace}/{registry-path}/{element-path}.json</code>, while elements of custom registries are loaded from <code>data/{element-namespace}/{registry-namespace}/{registry-path}/{element-path}.json</code>, using the namespace and path of the registry and the element.

= RegistryOps and RegistryAccess =

RegistryOps is a special [[DynamicOps]] made specifically for de/serializing datapack registries; it provides additional registry context and enables the use of special codecs that can only be used with RegistryOps. Datageneration of datapack registry elements must always be done using RegistryOps to convert elements to JsonElements.

RegistryOps can be created via <code>RegistryOps.create(JsonElement.INSTANCE, RegistryAccess.builtinCopy())</code>. RegistryAccess.builtinCopy() creates a set of writable datapack registries, which is necessary for datagenerating unregistered objects. All datageneration done in a GatherDataEvent handler must use the same RegistryAccess/RegistryOps instances (trying to encode an object in one set of registries that refers to an object in another set of registries will fail with strange holder errors).

== Holders ==

A Holder vaguely resembles a Pair<Key, Value> that either starts with a key and has a value bound later, or starts with a value and may have a key bound later.

Many datapack registry elements must be constructed with Holders that refer to elements of other registries; for example, PlacedFeatures are constructed with a Holder of a ConfiguredFeature. When datagenerating objects, we can use <code>RegistryOps#registry</code> to get a registry and <code>Registry#getOrCreateHolderOrThrow</code> to produce key-only reference holders (the key being the only part of the holder we need, as holder codecs encode only the key of the holder when using a RegistryOps).

Holders referring to datapack registry elements must be retrieved from the RegistryAccess/RegistryOps that will be used for datageneration; holders referring to static registry elements (such as blocks) can come directly from a ForgeRegistry as e.g. there is only ever one registry for blocks.

= JsonCodecProvider =

Forge provides a dataprovider for datapack registry elements that, given a registry key and a map of objects to datagenerate, datagenerates all elements in the map to the locations determined by their keys.

<syntaxhighlight lang="java">
void onGatherData(GatherDataEvent event)
{
DataGenerator generator = event.getDataGenerator();
ExistingFileHelper existingFileHelper = event.getExistingFileHelper();
RegistryAccess registryAccess = RegistryAccess.builtinCopy();
RegistryOps<JsonElement> registryOps = RegistryOps.create(JsonOps.INSTANCE, registryAccess);

ResourceLocation placedFeatureRL = new ResourceLocation("modid", "sponge_everywhere");
PlacedFeature placedFeature = new PlacedFeature(//etc;)
// All placed features to be datagenerated can be in the map
Map<ResourceLocation, PlacedFeature> map = Map.of(placedFeatureRL, placedFeature);

JsonCodecProvider provider = JsonCodecProvider.forDatapackRegistry(
dataGenerator, existingFileHelper, "modid", registryOps, Registry.PLACED_FEATURE_REGISTRY, map);

event.addProvider(event.includeServer(), provider);
}
</syntaxhighlight>

Jar-in-jar

2022-07-06T21:53:19Z

SciWhiz12: SciWhiz12 moved page Jar-in-jar to Jar-in-Jar: capitalization pls

#REDIRECT [[Jar-in-Jar]]

Jar-in-Jar

2022-07-06T21:53:19Z

SciWhiz12: SciWhiz12 moved page Jar-in-jar to Jar-in-Jar: capitalization pls

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 he runs your mod in his 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/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
}
}

Events

2022-01-15T12:12:38Z

SciWhiz12: /* Generic Events */ note wildcard only applies to EventBus#register

{{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.}}
====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]]

Access Transformers

2021-12-31T23:55:37Z

SciWhiz12: /* Background */ fix link to Encapsulation

'''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 SerializableUUID,
# which accepts two longs and returns an int[]
public net.minecraft.core.SerializableUUID m_123274_(JJ)[I # leastMostToIntArray
</syntaxhighlight>

Sides

2021-12-23T01:50:09Z

SciWhiz12: it's now NetworkConstants without the FML prefix

{{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, but the server menu will display the server as being incompatible (with a red <code>X</code> at the side). Therefore, you should register an <code>IExtensionPoint$DisplayTest</code> extension point to make sure that Forge does not think your mod is required on the server: (this is usually done in the mod constructor)

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

Capability

2021-11-18T15:34:56Z

SciWhiz12: redirect to Capabilities

#REDIRECT [[Capabilities]]

Configs

2021-11-17T15:05:43Z

SciWhiz12: change from markdown to mediawiki syntax, and mark as under construction

{{Under construction}}

Creating configs in Forge is fairly simple as Forge provides a ton of tools for configs. In addition, Forge will automatically update their values as the config files are edited and cache the values so you do not need to do so.

To begin, create a new class file and add this:

<syntaxhighlight lang="java>
public static final ForgeConfigSpec GENERAL_SPEC;

static {
ForgeConfigSpec.Builder configBuilder = new ForgeConfigSpec.Builder();
setupConfig(configBuilder);
GENERAL_SPEC = configBuilder.build();
}

private static void setupConfig(ForgeConfigSpec.Builder builder) {
}
</syntaxhighlight>

ForgeConfigSpec is what will ultimately hold all the data and info about how to make and read your config file. We will be registering this later. In the static block, this will create the builder for ForgeConfigSpec, pass it into setupConfig where we will add all the config entries we want, and then we build the final ForgeConfigSpec to store into GENERAL_SPEC.

Now for creating config entries, lets add an integer config entry by creating a public static field for it and use builder.defineInRange to define it.

<syntaxhighlight lang="java>
public static ForgeConfigSpec.IntValue exampleIntConfigEntry;

private static void setupConfig(ForgeConfigSpec.Builder builder) {
exampleIntConfigEntry = builder.defineInRange("example_int_config_entry", 5, 2, 50);
}
</syntaxhighlight>

Here, setupConfig method will add to the builder that there should be a "example_int_config_entry" entry in the toml file, it has a default value of 5, and will only accept a user-entered value between 2 and 50. The it assigns that resultant ForgeConfigSpec.DoubleValue to the exampleIntConfigEntry field. Now the exampleIntConfigEntry field can be call with <code>.get()</code> anywhere in our code to get the current config value for that config entry at the time.

There are many kinds of config entries you can make. Some of the more commonly used ones are:
* ForgeConfigSpec.IntValue - uses defineInRange
* ForgeConfigSpec.DoubleValue - uses defineInRange
* ForgeConfigSpec.LongValue - uses defineInRange
* ForgeConfigSpec.BooleanValue - uses define
* ForgeConfigSpec.ConfigValue<String> - uses define
* ForgeConfigSpec.ConfigValue<List<? extends String>> - uses defineList ('''IMPORTANT''', do not use .define for lists. Always .defineList)

As for the methods you can use for each of these config types:
* .define - takes the default config value.
* .defineInRange - takes the default, the minimum, and maximum config values in that order.
* .defineList - takes the default list to use and a validator to run on each list entry when the user tries * to change the config file to make sure it is correctly edited by user.

Furthermore, you may attach a comment or translation key to your builder that is creating the config entries. And using <code>builder.push("...")</code> and <code>builder.pop();</code> before and after some config entries will put them into a category (comments can be attached to categories as well). Here is a large example of all this:

<syntaxhighlight lang="java">
public static ForgeConfigSpec.IntValue exampleIntConfigEntry;
public static ForgeConfigSpec.DoubleValue exampleDoubleConfigEntry;
public static ForgeConfigSpec.ConfigValue<Double> exampleUnboundedDoubleConfigEntry;
public static ForgeConfigSpec.LongValue exampleLongConfigEntry;
public static ForgeConfigSpec.BooleanValue exampleBooleanConfigEntry;
public static ForgeConfigSpec.ConfigValue<String> exampleStringConfigEntry;
public static ForgeConfigSpec.ConfigValue<List<? extends String>> exampleStringListConfigEntry;

private static void setupConfig(ForgeConfigSpec.Builder builder) {
builder.comment(" This category holds configs that uses numbers.")
builder.push("Numeric Config Options");

exampleIntConfigEntry = builder.defineInRange("example_int_config_entry", 5, 2, 50);
exampleDoubleConfigEntry = builder.defineInRange("example_double_config_entry", 10D, 0D, 100D);

exampleUnboundedDoubleConfigEntry = builder
.comment("This comment will be attached to example_unbounded_double_config_entry in the config file.")
.define("example_unbounded_double_config_entry", 1000D);

exampleLongConfigEntry = builder.defineInRange("example_long_config_entry", 4L, -900L, 900L);

builder.pop();

builder.comment(" This category holds configs that uses numbers.")
builder.push("String Config Options");

exampleStringConfigEntry = builder
.comment("This config holds a single string.")
.define("example_string_config_entry", "player444");

builder.comment(" This category will be nested inside the String Config Options category.")
builder.push("Nested Category");

exampleStringListConfigEntry = builder
.comment("This config entry will hold a list of strings.")
.defineList("example_string_list_config_entry", Arrays.asList("pie", "trains"), entry -> true);

builder.pop();
builder.pop();
}
</syntaxhighlight>

Now it is time to register your config file so that Forge can create and read the config file. Doing do, you simply call <code>ModLoadingContext.get().registerConfig</code> and pass in, the <code>ModConfig.Type</code>, the <code>GENERAL_SPEC</code> from your config file, and the name of the config file (make sure you include <code>.toml</code> as well. Like so:
<code>ModLoadingContext.get().registerConfig(ModConfig.Type.COMMON, ModConfig.GENERAL_SPEC, "modconfig.toml");</code>

NOTE: Forge will only update the values of your config fields in code after the registry events are finished. Therefore, only attempt to read the config values after the registry events are completed. (FMLCommonSetupEvent and later is safe)

The ModConfig.Type determines where your config files goes and its behavior. While COMMON is generally used the most, the other config types do have specific uses. A simple summary is:
* ModConfig.Type.COMMON - Exists in the config folder above the mods folder and will apply to all worlds created. (Works for both client and servers)
* ModConfig.Type.CLIENT - Same as COMMON except the config file is only ever loaded on the client. Never on server.
* ModConfig.Type.SERVER - Exists only in a world's own config folder ona per-world basis. This is read on both server and on single player as well.

If you are going to have many config files for organization, you make want to put them into a specific folder for your mod within the config folder. Such as <code>configs/modid/blocks.toml</code> and <code>configs/modid/entities.toml</code> However, you would need to make that new folder first as Forge will not do it for you. Example:

<syntaxhighlight lang="java">
FileUtils.getOrCreateDirectory(FMLPaths.CONFIGDIR.get().resolve("modid"), "modid");
ModLoadingContext.get().registerConfig(ModConfig.Type.COMMON, ModIdConfigs.GENERAL_SPEC, "modid/blocks.toml");
ModLoadingContext.get().registerConfig(ModConfig.Type.COMMON, ModIdConfigs.GENERAL_SPEC, "modid/entities.toml");
</syntaxhighlight>

Now your configs are setup, you know a decent chunk of how you can utilize Forge configs, and you are ready to go!

Access Transformers

2021-10-17T17:00:06Z

SciWhiz12: /* Background */ switch same-package and subclasses

'''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|encapsulation]] or private methods which are part of the implementation of the class and should not be 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 SerializableUUID,
# which accepts two longs and returns an int[]
public net.minecraft.core.SerializableUUID m_123274_(JJ)[I # leastMostToIntArray
</syntaxhighlight>

User:SciWhiz12/sandbox

2021-10-12T17:53:39Z

SciWhiz12: test indicator tag

<tabs>
<tab name="Foo">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</tab>
<tab name="Bar">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</tab>
<tab name="Baz">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</tab>
</tabs>

<tab name="My Toggle Box">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</tab>

<tab name="My Toggle Box" collapsed>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</tab>

<tab name="Stationery" dropdown>
* [[Business Cards]]
* [[Letterheads]]
* [[Envelopes]]
</tab>

<indicator name="exclaim">[[File:Exclamation.svg|20px]]</indicator>

FCWMeta:About

2021-09-26T23:27:54Z

SciWhiz12: remove DISPLAYTITLE

The '''Forge Community Wiki''' (abbreviated as '''FCW''') is a community wiki about [https://github.com/MinecraftForge/MinecraftForge Minecraft Forge], the popular open-source modding API for [[wikipedia:Minecraft|Minecraft]].

It is created as an community-centric and more accessible alternative to the [https://mcforge.readthedocs.io/ official Forge documentation], which is actively curated by the Minecraft Forge team.

== History ==
On the September 19, 2020, in the <tt>#squirrels</tt> channel of the official Forge Project discord, user [[User:SciWhiz12|sciwhiz12]] mentioned the idea of creating a wiki for Forge documentation. An official wiki previously existed for Minecraft Forge, however the cost and burden of maintaining such a wiki was too significant on the Minecraft Forge team (which consisted of volunteers), so it was shut down.

Another user, [[User:Curle|Curle]], offered to host a community wiki on their servers, and giving adminship over to sciwhiz12. The community wiki initially started out on the popular wiki engine [[wikipedia:MediaWiki|MediaWiki]], but due to certain technical difficulties, the decision was made to move to using a simpler wiki engine: [[wikipedia:DokuWiki|DokuWiki]].

On October 16, 2020, the community wiki was officially made publicly open. On October 23, 2020, a regular update to the web server that ran the wiki caused severe technical issues, and the wiki staff decided to move back to using MediaWiki as the wiki engine.

== Purpose ==
The Forge Community Wiki was created to serve three major purposes:
# To collectively keep track of features, changes, updates to Minecraft Forge and vanilla code.
# To create and collaborate on articles with in-depth explanations about a variety of Forge-related subjects.
# To contribute example code and tutorials for both simple and difficult concepts.

Mods.toml file

2021-09-22T23:25:01Z

SciWhiz12: SciWhiz12 moved page Mods.toml file to Mods.toml: remove the file suffix, it's unique enough

#REDIRECT [[Mods.toml]]

Mods.toml

2021-09-22T23:25:00Z

SciWhiz12: SciWhiz12 moved page Mods.toml file to Mods.toml: remove the file suffix, it's unique enough

{{Under construction}}

The <code>mods.toml</code> file is read by the mod loader to determine what mods are packaged into your JAR file, and what information to display to the user in the Mods listing screen (accessible by pressing the "Mods" button on the main menu of the game).

The file is formatted in [https://toml.io/en/ Tom's Obvious Minimal Language], or TOML for short. The example <code>mods.toml</code> file in the MDK provides comments explaining the contents of the file. It should be stored under the <code>META-INF</code> folder in your resources directory (<code>src/main/resources/META-INF/mods.toml</code>).

Example <code>mods.toml</code> file:
<syntaxhighlight lang="TOML">
modLoader="javafml"
# Forge for 1.17.1 is version 37
loaderVersion="[37,)"
license="All rights reserved"
issueTrackerURL="github.com/MinecraftForge/MinecraftForge/issues"
showAsResourcePack=false

[[mods]]
modId="examplemod"
version="1.0.0.0"
displayName="Example Mod"
updateJSONURL="minecraftforge.net/versions.json"
displayURL="minecraftforge.net"
logoFile="logo.png"
credits="I'd like to thank my mother and father."
authors="Author"
description='''
Lets you craft dirt into diamonds. This is a traditional mod that has existed for eons. It is ancient. The holy Notch created it. Jeb rainbowfied it. Dinnerbone made it upside down. Etc.
'''

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

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

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

The <code>mods.toml</code> is split into three parts: the non-mod-specific properties, which are linked to the mod file; the mod properties, with a section for each mod; and dependency configurations, with a section for each mod's dependencies. Here is a table of attributes that may be given to a mod, where <code>mandatory</code> means there is no default and the absence of the property causes an error.

===Non-Mod-Specific Properties===

{| class="wikitable"
|-
!|Property
!|Type
!|Defaults
!|Description
!|Example
|-
|<code>modLoader</code>
|string
|'''mandatory'''
|The language loader for the mod. Used to specify an alternative language for the mod, such as Kotlin, if one exists. The Forge-provided Java loader is <code>javafml</code>.
|<code>"javafml"</code>
|-
|<code>loaderVersion</code>
|string
|'''mandatory'''
|The acceptable version range of the language loader, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. For the Forge-provided Java loader, the version is the major version of the Forge version.
|<code>"[37,)"</code>
|-
|<code>license</code>
|string
|'''mandatory'''
|The license for the mod(s) in this JAR. This string may be any valid string, but it is suggested to set the value to be the name of your license, and/or a link to that license.
|<code>"GNU GPL v3, https://www.gnu.org/licenses/gpl-3.0.en.html"</code>
|-
|<code>showAsResourcePack</code>
|boolean
|<code>false</code>
|Whether to display this mod's resources as a separate option in the resource pack menu. If disabled, the mod's resources will be rolled into the "Mod resources" pack.
|<code>true</code>
|-
|<code>properties</code>
|table
|<code>{}</code>
|A table of custom substitution properties. This is used by <code>StringSubstitutor</code> to replace values, using <code>${file.*}</code>.
|<code>{ "thingy" = 1 }</code>, used in <code>${file.thingy}</code>
|-
|<code>issueTrackerURL</code>
|string
|''nothing''
|A URL for an issues tracker. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://my.issue.tracker/"</nowiki></code>
|}

===Mod Properties===
A mod entry is defined by a new section starting with a <code><nowiki>[[mods]]</nowiki></code> header (In TOML, the <code><nowiki>[[mods]]</nowiki></code> defines an [https://toml.io/en/v1.0.0-rc.2#array-of-tables array of tables]). All properties from that line until the next header will become the properties for that mod.
{| class="wikitable"
|-
!|Property
!|Type
!|Defaults
!|Description
!|Example
|-
|<code>modId</code>
|string
|'''mandatory'''
|The mod's identifier (modid). This must match the following regex: <code>^[a-z][a-z0-9_-]{1,63}$</code> (starts with a lowercase letter; other characters must be a lowercase letter, number, underscore or hyphen; must be 2-64 characters long).
|<code>"examplemod"</code>
|-
|<code>namespace</code>
|string
|value of <code>modId</code>
|An override namespace. Currently, there is no use for this property
|<code>example</code>
|-
|<code>version</code>
|string
|<code>"1"</code>
|The mod's version, ideally conforming to [[Semantic Versioning|semantic versioning]]. The default value in the MDK for this is <code>${file.jarVersion}</code>, which is replaced at runtime with the <code>Implementation-Version</code> found in the jar's manifest file.
|<code>"0.2.4-beta1"</code>
|-
|<code>displayName</code>
|string
|value of <code>modId</code>
|The display name of the mod, for use in the Mods listing screen
|<code>"Example Mod"</code>
|-
|<code>description</code>
|string
|<code>"MISSING DESCRIPTION"</code>
|The description of the mod, for use in the Mods listing screen. It's recommended to use a multiline string (surrounded by <code><nowiki>'''</nowiki></code>)
|<code>"Adds things and stuff. "</code>
|-
|<code>logoFile</code>
|string
|''nothing''
|The path of the logo file image, for use in the Mods listing screen. The image must be in the root of the jar file, not in any subfolder thereof (e.g. the file is directly in <code>src/main/resources</code>)
|<code>"myAwesomeLogo.png"</code>
|-
|<code>logoBlur</code>
|boolean
|<code>true</code>
|Whether to do some blurring on the mod's logo in the Mods listing screen. Has no effect if <code>logoFile</code> is not set.
|<code>false</code>
|-
|<code>updateJSONURL</code>
|string
|''nothing''
|The update JSON URL, used by the [[Update_Checker|update checker]]. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://myurl.me/path/to/update.json"</nowiki></code>
|-
|<code>modproperties</code>
|table
|<code>{}</code>
|A table of custom mod properties; this is not used for Forge, but is mainly for use by mods.
|<code>{ "useThing" = true }</code>
|-
|<code>credits</code>
|string
|''nothing''
|Credits and acknowledgements for the mod, for use in the Mods listing screen. Can be any string.
|<code>"This person and that guy"</code>
|-
|<code>authors</code>
|string
|''nothing''
|Authors for the mod, for use in the Mods listing screen. Can be any string.
|<code>"ExampleDude"</code>
|-
|<code>displayURL</code>
|string
|''nothing''
|A URL, displayed on the Mods listing screen. Can be any string.
|<code><nowiki>"http://example.com/"</nowiki></code>
|}

===Dependency Configurations===
Mods can define dependencies for their mods, which are checked by Forge before loading mods. This is used for e.g. ensuring your mod loads after another, or hard-crashing if a mod with a specified version does not exist.

These dependency configurations, like the mod properties, are defined by a new section starting with <code><nowiki>[[dependencies.modid]]</nowiki></code>, with <code>modid</code> being the mod id that has this dependency. All properties from that line until the next header will become the properties of that dependency configuration.
{| class="wikitable"
|-
!|Property
!|Type
!|Defaults
!|Description
!|Example
|-
|<code>modId</code>
|string
|'''mandatory'''
|The mod id of the dependency.
|<code>examplelibrary</code>
|-
|<code>mandatory</code>
|boolean
|'''mandatory'''
|Whether to crash if this dependency is not met.
|<code>true</code>
|-
|<code>versionRange</code>
|string
|<code>""</code>
|The acceptable version range of the dependency, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. An empty string is an unbounded version range, which matches any version.
|<code>"[1.0,2.0)"</code>
|-
|<code>ordering</code>
|string
|<code>"NONE"</code>
|Defines if the mod must load before or after this dependency. The valid values are <code>BEFORE</code> (must load before), <code>AFTER</code> (must load after), and <code>NONE</code> (does not care about order).
|<code>"AFTER"</code>
|-
|<code>side</code>
|string
|<code>"BOTH"</code>
|physical side]]. The valid values are <code>CLIENT</code> (present on the client), <code>SERVER</code> (present on the dedicated server), and <code>BOTH</code> (present on both sides).
|<code>"CLIENT"</code>
|}

{{Tip/Warning|When specifying dependency ordering between two or more mods, beware of cyclic order!
An example: if mod A must load before mod B, and mod B must load before mod A, the game will crash because of the circular cycle.}}

[[Category:Getting Started]]
[[Category:Beginner Topics]]

MediaWiki:Citizen.css

2021-09-07T17:22:59Z

SciWhiz12: more contrast in diffs

/* All CSS here will be loaded for users of the Citizen skin */
@media only screen and (prefers-color-scheme:dark) {
code, .mw-code {
color: #46C410;
}
}

.external {
color: #527ECA;
}

tt {
font-size: 100%;
padding: 0 0.1em;
}

/* ***************** Styling for Tabs : START ***************** */

.tabs-dropdown .tabs-content,
.tabs-dropdown .tabs-container,
.tabs-dropdown li,
.tabs-dropdown ul,
.tabs-dropdown ol {
background-color: rgba(32,32,32,0.2) !important; /* has to be !important */
}

.tabs-label {
background-color: #222;
border-color: #666;
}

.tabs-tabbox > .tabs-container {
border-color: #666;
}
.tabs-plain > .tabs-label {
border-color: #666;
}
.tabs-togglebox >*> .tabs-content {
border-color: #666;
}

.tabs-dropdown >*> .tabs-content,
.tabs-dropdown li ul,
.tabs-dropdown li ol {
box-shadow: 2px 3px 5px #111;
}

.tabs-dropdown li,
.tabs-dropdown >*> .tabs-content> a,
.tabs-dropdown >*> .tabs-content>p> a,
.tabs-dropdown ol>li> a {
border-top-color: #666;
}

.tabs-dropdown li ul,
.tabs-dropdown li ol {
border-color: #666;
}
.tabs-dropdown li ul:before,
.tabs-dropdown li ol:before {
color: #88F;
}

.tabs-label:hover {
background-color: #444;
}
.tabs-label:active, .tabs-label:focus {
background-color: #444;
}
.tabs-tabbox > .tabs-input:checked + .tabs-label,
.tabs-input-0:checked + .tabs-input-1 + .tabs-label {
z-index: 2;
background-color: #444;
}

.tabs-dropdown >*> .tabs-content li:hover {
background-color: #444;
}
.tabs-dropdown a,
.tabs-dropdown a:hover,
.tabs-dropdown a: visited {
color: #15B;
}
.tabs-dropdown a:active {
color: #108;
}
.tabs-dropdown >*> .tabs-content> a:hover,
.tabs-dropdown >*> .tabs-content>p> a:hover,
.tabs-dropdown ol>li> a:hover {
background-color: #444;
}

.tabs-tabbox > .tabs-input.checked + .tabs-label,
.tabs-input-0.checked + .tabs-input-1 + .tabs-label {
background-color: #444;
}

/* ***************** Styling for Tabs : END ***************** */

/* ************* Styling for Datatables : START ************* */

.mw-datatable td, .mw-datatable th {
background-color: transparent;
}

.mw-datatable table {
border: 1px solid #424951;
}

.mw-datatable td, .mw-datatable th {
border: 1px solid #424951;
padding: 0.2em 0.4em;
}

.mw-datatable tr:hover td {
background-color: #202736;
}

/* ************** Styling for Datatables : END ************** */

/* Fixes the colors of diff changes for better contrast */
.diffchange {
color: #222222;
}
.diff-deletedline {
border-color: #d9c284; /* ffe49c */
}
.diff-deletedline .diffchange {
background: #d9c284;
}
.diff-addedline {
border-color: #8bb2d9; /* a3d3ff */
}
.diff-addedline .diffchange {
background: #8bb2d9;
}

MediaWiki:Citizen.css

2021-09-07T17:05:39Z

SciWhiz12: add css to fix contrast in diffs

/* All CSS here will be loaded for users of the Citizen skin */
@media only screen and (prefers-color-scheme:dark) {
code, .mw-code {
color: #46C410;
}
}

.external {
color: #527ECA;
}

tt {
font-size: 100%;
padding: 0 0.1em;
}

/* ***************** Styling for Tabs : START ***************** */

.tabs-dropdown .tabs-content,
.tabs-dropdown .tabs-container,
.tabs-dropdown li,
.tabs-dropdown ul,
.tabs-dropdown ol {
background-color: rgba(32,32,32,0.2) !important; /* has to be !important */
}

.tabs-label {
background-color: #222;
border-color: #666;
}

.tabs-tabbox > .tabs-container {
border-color: #666;
}
.tabs-plain > .tabs-label {
border-color: #666;
}
.tabs-togglebox >*> .tabs-content {
border-color: #666;
}

.tabs-dropdown >*> .tabs-content,
.tabs-dropdown li ul,
.tabs-dropdown li ol {
box-shadow: 2px 3px 5px #111;
}

.tabs-dropdown li,
.tabs-dropdown >*> .tabs-content> a,
.tabs-dropdown >*> .tabs-content>p> a,
.tabs-dropdown ol>li> a {
border-top-color: #666;
}

.tabs-dropdown li ul,
.tabs-dropdown li ol {
border-color: #666;
}
.tabs-dropdown li ul:before,
.tabs-dropdown li ol:before {
color: #88F;
}

.tabs-label:hover {
background-color: #444;
}
.tabs-label:active, .tabs-label:focus {
background-color: #444;
}
.tabs-tabbox > .tabs-input:checked + .tabs-label,
.tabs-input-0:checked + .tabs-input-1 + .tabs-label {
z-index: 2;
background-color: #444;
}

.tabs-dropdown >*> .tabs-content li:hover {
background-color: #444;
}
.tabs-dropdown a,
.tabs-dropdown a:hover,
.tabs-dropdown a: visited {
color: #15B;
}
.tabs-dropdown a:active {
color: #108;
}
.tabs-dropdown >*> .tabs-content> a:hover,
.tabs-dropdown >*> .tabs-content>p> a:hover,
.tabs-dropdown ol>li> a:hover {
background-color: #444;
}

.tabs-tabbox > .tabs-input.checked + .tabs-label,
.tabs-input-0.checked + .tabs-input-1 + .tabs-label {
background-color: #444;
}

/* ***************** Styling for Tabs : END ***************** */

/* ************* Styling for Datatables : START ************* */

.mw-datatable td, .mw-datatable th {
background-color: transparent;
}

.mw-datatable table {
border: 1px solid #424951;
}

.mw-datatable td, .mw-datatable th {
border: 1px solid #424951;
padding: 0.2em 0.4em;
}

.mw-datatable tr:hover td {
background-color: #202736;
}

/* ************** Styling for Datatables : END ************** */

/* Fixes the text color of diff changes to better contrast against the BG */
.diffchange {
color: #444444;
}

User:SciWhiz12

2021-08-29T14:17:22Z

SciWhiz12:

''Hello!'' I'm one of the Administrators of this wiki. _Bring out yer banhammers, fellas!_

If you have any concern with the operations of this wiki, please do not hesitate to talk about it on my talk page, or message me on Discord: '''sciwhiz12#1286'''. I am active on The Forge Project discord and the Minecraft Mod Development discord, and do appear from time to time on the Modded Minecraft discord.

- [[User:SciWhiz12|<span style="color: #d9d916; font-weight: bold">SciWhiz12</span>]] [[User talk:SciWhiz12|💬]] 08:55, 23 October 2020 (UTC)

Proper Mod Structuring

2021-08-29T14:09:11Z

SciWhiz12: remove extraneous whitespace

The structure of your mod is important in keeping your mod organized, for both your benefit and the benefit of anyone who wishses to make a feature for your mod. A disorganized mod structure may cause headaches when someone is trying to update it to a higher version, especially if they cannot modify the package structure, due to i.e. licensing.

{{Tip|Note that this page is only a recommendation for your mod structure; you may structure your mod in any way you see fit.}}

== Packaging ==

Pick a unique package name for your mod. If you own a URL associated with your project, you can use it as your top level package. For example if you own "example.com", you may use <code>com.example</code> as your top level package.
The next level package is usually your mod's ID: if your mod ID is <code>examplemod</code>, your mod's package will be <code>com.example.examplemod</code>.

{{Tip/Important|Do not use a domain for your top level package if you do not own that domain. It is perfectly acceptable to have your top level package be named with anything, such as your name/nickname, or the name of the mod (<code>me.exampledude.examplemod</code>).}}

=== Using Subpackages ===

Rather than clutter up a single class and package with everything, it is recommended you break your mod into subpackages. Below are a few possible methods for laying out your folder structure though you may as well come up with your own layout too.

* '''Group by Logic''': One possible strategy is to make subpackages for logical units of your mod. For example, if you have a block called Super Furnace you would put its block, its block entity and its item all under <code>feature/superfurnace</code>.
* '''Group by Function''': Another common strategy is to make subpackages for grouping classes that have a common purpose. For example, your blocks classes can be under <code>blocks</code>, your entities classes can be under <code>entities</code>, your helper utilities can be under <code>helpers</code>, etc.

No matter how your final structure looks like it is highly recommended to add a <code>client</code> subpackage under your main package. This helps to isolate your [[Sides|client-only code]] from the rest, such as your Screens and renderers.

By keeping your code in clean subpackages, you can grow your mod much more organically.

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

== Class Naming Schemes ==

A common class naming scheme allows easier deciphering of the purpose of the class, and makes it easier for someone developing for your mod to find specific classes.

The usual style is to use suffixes for your classes, for example:

* An <code>Item</code> called <code>PowerRing</code> would have a class name of <code>PowerRingItem</code>.
* A <code>Block</code> called <code>NotDirt</code> would have a class name of <code>NotDirtBlock</code>.
* A <code>BlockEntity</code> for a block called <code>SuperChewer</code> would have a class name of <code>SuperChewerBlockEntity</code>.

== The Mod File ==

The main mod class - the class that is annotated with <code>@Mod</code> - is usually put into the main package of your mod, and not placed into a subpackage. This allows an easier time to access this, as your main mod class is the entrypoint of your mod.

The <code>@Mod</code> annotation indicates to the mod loader that this class is the entry point of your mod. Each <code>@Mod</code> annotation and their value should be paired with a mod id entry in your <code>mods.toml</code> file.

==The <code>mods.toml</code> file==
The <code>mods.toml</code> file is read by the mod loader to determine what mods are packaged into your JAR file, and what information to display to the user in the Mods listing screen (accessible by pressing the "Mods" button on the main menu of the game).

The <code>mods.toml</code> file is formatted in [https://toml.io/en/ Tom's Obvious Minimal Language], or TOML for short. The example <code>mods.toml</code> file in the MDK provides comments explaining the contents of the file. It should be stored under the <code>META-INF</code> folder in your resources directory (<code>src/main/resources/META-INF/mods.toml</code>).

Example <code>mods.toml</code> file
<syntaxhighlight lang="TOML">
modLoader="javafml"
# Forge for 1.17.1 is version 37
loaderVersion="[37,)"
license="All rights reserved"
issueTrackerURL="github.com/MinecraftForge/MinecraftForge/issues"
showAsResourcePack=false

[[mods]]
modId="examplemod"
version="1.0.0.0"
displayName="Example Mod"
updateJSONURL="minecraftforge.net/versions.json"
displayURL="minecraftforge.net"
logoFile="logo.png"
credits="I'd like to thank my mother and father."
authors="Author"
description='''
Lets you craft dirt into diamonds. This is a traditional mod that has existed for eons. It is ancient. The holy Notch created it. Jeb rainbowfied it. Dinnerbone made it upside down. Etc.
'''

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

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

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

The <code>mods.toml</code> is split into three parts: the non-mod-specific properties, which are linked to the mod file; the mod properties, with a section for each mod; and dependency configurations, with a section for each mod's dependencies. Here is a table of attributes that may be given to a mod, where<code>mandatory</code>means there is no default and the absence of the property causes an error.
===Non-Mod-Specific Properties===

{| class="wikitable"
|-
!|Property
!|Type
!|Defaults
!|Description
!|Example
|-
|<code>modLoader</code>
|string
|'''mandatory'''
|The language loader for the mod. Used to specify an alternative language for the mod, such as Kotlin, if one exists. The Forge-provided Java loader is <code>javafml</code>.
|<code>"javafml"</code>
|-
|<code>loaderVersion</code>
|string
|'''mandatory'''
|The acceptable version range of the language loader, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. For the Forge-provided Java loader, the version is the major version of the Forge version.
|<code>"[37,)"</code>
|-
|<code>license</code>
|string
|'''mandatory'''
|The license for the mod(s) in this JAR. This string may be any valid string, but it is suggested to set the value to be the name of your license, and/or a link to that license.
|<code>"GNU GPL v3, https://www.gnu.org/licenses/gpl-3.0.en.html"</code>
|-
|<code>showAsResourcePack</code>
|boolean
|<code>false</code>
|Whether to display this mod's resources as a separate option in the resource pack menu. If disabled, the mod's resources will be rolled into the "Mod resources" pack.
|<code>true</code>
|-
|<code>properties</code>
|table
|<code>{}</code>
|A table of custom substitution properties. This is used by <code>StringSubstitutor</code> to replace values, using <code>${file.*}</code>.
|<code>{ "thingy" = 1 }</code>, used in <code>${file.thingy}</code>
|-
|<code>issueTrackerURL</code>
|string
|''nothing''
|A URL for an issues tracker. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://my.issue.tracker/"</nowiki></code>
|}

===Mod Properties===
A mod entry is defined by a new section starting with a <code><nowiki>[[mods]]</nowiki></code> header (In TOML, the <code><nowiki>[[mods]]</nowiki></code> defines an [https://toml.io/en/v1.0.0-rc.2#array-of-tables array of tables]). All properties from that line until the next header will become the properties for that mod.
{| class="wikitable"
|-
!|Property
!|Type
!|Defaults
!|Description
!|Example
|-
|<code>modId</code>
|string
|'''mandatory'''
|The mod's identifier (modid). This must match the following regex: <code>^[a-z][a-z0-9_-]{1,63}$</code> (starts with a lowercase letter; other characters must be a lowercase letter, number, underscore or hyphen; must be 2-64 characters long).
|<code>"examplemod"</code>
|-
|<code>namespace</code>
|string
|value of <code>modId</code>
|An override namespace. Currently, there is no use for this property
|<code>example</code>
|-
|<code>version</code>
|string
|<code>"1"</code>
|.), ideally conforming to [[Semantic_Versioning>Semantic Versioning]]. The default value in the MDK for this is <code>${file.jarVersion}</code>, which is replaced at runtime with the <code>Implementation-Version</code> found in the jar's manifest file.
|<code>"0.2.4-beta1"</code>
|-
|<code>displayName</code>
|string
|value of <code>modId</code>
|The display name of the mod, for use in the Mods listing screen
|<code>"Example Mod"</code>
|-
|<code>description</code>
|string
|<code>"MISSING DESCRIPTION"</code>
|The description of the mod, for use in the Mods listing screen. It's recommended to use a multiline string (surrounded by <code>'''<code>)</code></code>
|<code>"Adds things and stuff. "</code>
|-
|<code>logoFile</code>
|string
|''nothing''
|The path of the logo file image, for use in the Mods listing screen. The image must be in the root of the jar file, not in any subfolder thereof (e.g. the file is directly in <code>src/main/resources</code>)
|<code>"myAwesomeLogo.png"</code>
|-
|<code>logoBlur</code>
|boolean
|<code>true</code>
|Whether to do some blurring on the mod's logo in the Mods listing screen. Has no effect if <code>logoFile</code> is not set.
|<code>false</code>
|-
|<code>updateJSONURL</code>
|string
|''nothing''
|The update JSON URL, used by the [Update_Checker update checker]. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://myurl.me/path/to/update.json"</nowiki></code>
|-
|<code>modproperties</code>
|table
|<code>{}</code>
|A table of custom mod properties; this is not used for Forge, but is mainly for use by mods.
|<code>{ "useThing" = true }</code>
|-
|<code>credits</code>
|string
|''nothing''
|Credits and acknowledgements for the mod, for use in the Mods listing screen. Can be any string.
|<code>"This person and that guy"</code>
|-
|<code>authors</code>
|string
|''nothing''
|Authors for the mod, for use in the Mods listing screen. Can be any string.
|<code>"ExampleDude"</code>
|-
|<code>displayURL</code>
|string
|''nothing''
|A URL, displayed on the Mods listing screen. Can be any string.
|<code><nowiki>"http://example.com/"</nowiki></code>
|}

===Dependency Configurations===
Mods can define dependencies for their mods, which are checked by Forge before loading mods. This is used for e.g. ensuring your mod loads after another, or hard-crashing if a mod with a specified version does not exist.

These dependency configurations, like the mod properties, are defined by a new section starting with <code>[[dependencies.]]</code>, with <code></code> being the mod id that has this dependency. All properties from that line until the next header will become the properties of that dependency configuration.
{| class="wikitable"
|-
!|Property
!|Type
!|Defaults
!|Description
!|Example
|-
|<code>modId</code>
|string
|'''mandatory'''
|The mod id of the dependency.
|<code>examplelibrary</code>
|-
|<code>mandatory</code>
|boolean
|'''mandatory'''
|Whether to crash if this dependency is not met.
|<code>true</code>
|-
|<code>versionRange</code>
|string
|<code>""</code>
|The acceptable version range of the dependency, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. An empty string is an unbounded version range, which matches any version.
|<code>"[1.0,2.0)"</code>
|-
|<code>ordering</code>
|string
|<code>"NONE"</code>
|Defines if the mod must load before or after this dependency. The valid values are <code>BEFORE</code> (must load before), <code>AFTER</code> (must load after), and <code>NONE</code> (does not care about order).
|<code>"AFTER"</code>
|-
|<code>side</code>
|string
|<code>"BOTH"</code>
|physical side]]. The valid values are <code>CLIENT</code> (present on the client), <code>SERVER</code> (present on the dedicated server), and <code>BOTH</code> (present on both sides).
|<code>"CLIENT"</code>
|}

{{Tip/Warning|When specifying dependency ordering between two or more mods, beware of cyclic order!
An example: if mod A must load before mod B, and mod B must load before mod A, the game will crash because of the circular cycle.}}

[[Category:Getting Started]]

[[Category:Beginner Topics]]

Access Transformers

2021-08-29T13:50:28Z

SciWhiz12: add missing parenthesis

'''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|encapsulation]] or private methods which are part of the implementation of the class and should not be 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
! Subclasses
! Classes in the same package
! 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 SerializableUUID,
# which accepts two longs and returns an int[]
public net.minecraft.core.SerializableUUID m_123274_(JJ)[I # leastMostToIntArray
</syntaxhighlight>

Key Mappings

2021-08-29T13:35:34Z

SciWhiz12: reword lead section

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

Access Transformers

2021-08-13T03:06:51Z

SciWhiz12: whoops, switched the two wildcards

'''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|encapsulation]] or private methods which are part of the implementation of the class and should not be 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
! Subclasses
! Classes in the same package
! 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 SerializableUUID,
# which accepts two longs and returns an int[]
public net.minecraft.core.SerializableUUID m_123274_(JJ)[I # leastMostToIntArray
</syntaxhighlight>

FCWMeta:User access levels

2021-08-13T03:05:48Z

SciWhiz12: add links to members list for each user group

The '''user access level''' of an editor determines what abilities they have and what actions they can perform. Each user access level, or '''user group''', has permissions/rights which are assigned. See [[Special:ListGroupRights]] to see all the available user groups and their permissions/rights.

== Administrators and Moderators ==
'''Administrators''' and '''Moderators''' are editors who have broad rights over the whole wiki, such as protection, deletion, moving of pages, blocking and unblocking of users, and more. Administrators have more sensitive rights, and can assign and remove Moderators.

These editors are part of the ''wiki staff'', which determine the policies of this wiki, enforce any binding decisions, keep the peace of the wiki, and moderate and curate its contents.

The wiki staff may decide, from time to time, to grant Moderator status to active, reputable, and responsible editors. Requests for staff access level will not be entertained, however endorsements for other editors' may be considered.

There are currently [[Special:ListUsers/administrator|'''{{NUMBERINGROUP:administrator}}''' administrators]] and [[Special:ListUsers/moderator|'''{{NUMBERINGROUP:moderator}}''' moderators]].

== Trusted users ==
'''Trusted users''' are editors who have been active in their contributions or are reputable members of the community, and has the trust of the wiki staff. They have the rights to edit semi-protected pages, and patrol changes.

If you have been especially active in contributing, a staff member may grant this access level to you. You may also request this access level by contacting one of the staff; however, repeated requests may warrant sanctions.

There are currently [[Special:ListUsers/trusted|'''{{NUMBERINGROUP:trusted}}''' trusted users]].

== Special access levels ==
These access levels are specially granted to users by decision of the wiki staff. Requests for these access levels will not be considered, and may warrant sanctions.

==== Keepers of the Keys ====
The '''Keepers of the Keys''' are administrators who have the rights to assign and remove access levels from all other users, including other administarotrs.

The origin of this access group is derived from the principle of there being multiple administrators with high-level access to the wiki, to ensure that there is always someone available to administer the wiki and if necessary, take control of the wiki if the other administrators are out-of-contact and unreachable.

There are currently [[Special:ListUsers/root|'''{{NUMBERINGROUP:root}}''' keepers of the keys]].

==== Interface administrators ====
'''Interface administrators''' are editors who are given editing access to the MediaWiki interface CSS and JS files, through the <code>MediaWiki</code> namespace.

There are currently [[Special:ListUsers/interface-admin|'''{{NUMBERINGROUP:interface-admin}}''' interface administrators]].

==== Check users ====
'''Check users''' are editors who have access to a log that lists out usernames used by which IPs and IPs used by which usernames. As this tool can be used to personally identify users through their IP, access is restricted to those who may need need, and use of the checkuser tool is strictly monitored.

There are currently [[Special:ListUsers/checkuser|'''{{NUMBERINGROUP:checkuser}}''' check users]].

==== Suppressors ====
'''Suppressors''' are editors who can hide revisions and log entries from users (and even administrators), in cases such as personal information being posted. As this is a powerful tool, access is restricted to those who may need it, and use of the suppression tools are strictly monitored.

There are currently [[Special:ListUsers/suppress|'''{{NUMBERINGROUP:suppress}}''' suppressors]].

==== Autoconfirmed users ====
'''Autoconfirmed users''' are editors who have at least 5 edits and their account is at least 14 days old.
Currently, these users are only not affected by IP-based rate limits (the <code>autoconfirmed</code> right).

There are currently [[Special:ListUsers/autoconfirmed|'''{{NUMBERINGROUP:autoconfirmed}}''' autoconfirmed users]].

==== Bots ====
'''Bots''' are programs that do automated or mass-editing tasks, which may be tedious or impossible to perform manually.

There are currently [[Special:ListUsers/bot|'''{{NUMBERINGROUP:bot}}''' bots]].

Access Transformers

2021-08-13T02:56:33Z

SciWhiz12: add note about wildcard ATs

'''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|encapsulation]] or private methods which are part of the implementation of the class and should not be 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
! Subclasses
! Classes in the same package
! 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 SerializableUUID,
# which accepts two longs and returns an int[]
public net.minecraft.core.SerializableUUID m_123274_(JJ)[I # leastMostToIntArray
</syntaxhighlight>

User:SciWhiz12/sandbox/policy

2021-08-13T02:47:59Z

SciWhiz12: Some formatting cleanup

= Wiki Policy =

The Forge Community Wiki maintains this '''Wiki Policy''', which is the set of rules and principles which govern the operation, moderation, and community of the wiki.

All wiki editors are required to follow this policy as a requirement for their contributions to this wiki. Editors which violate this policy will be sanctioned.

== Principles ==

The wiki operates on three main principles, which form the foundations of the this policy. Any rules and policies of the wiki will be consistent with these principles, and any interpretations of any such rule or policy should be done in the light of these three principles.

If there is no relevant rule or policy that is applicable in a situation, wiki staff will use these three principles to guide their actions and decisions.

=== Be respectful ===
All editors are expected to show and maintain a decent amount of respect to other editors.

As with any online collaboration, there may be situations where editors will strongly disagree on some decision, topic, or other. In such situations, while both sides may be in disagreement with the other, they must remain civility in both their words and actions. Insults and derogatory remarks should always be avoided, and discussions must remain civil, especially in topics which may provoke animosity or heated debate.

=== Assume good faith ===
Unless there is evidence to the contrary, actions taken by an editor should be seen as being done in good faith and without malicious intentions.

There are cases where actions made by a well-intentioned editor could be perceived to be malicious or harmful to the wiki. Editors are not expected to be perfect, and they will make mistakes from time to time. In such situations, other editors should not immediately go on the offensive against that editor. Wiki editors make contributions to the wiki to help it, not to harm it. A civil discussion should be held to allow the editor to defend their actions.

=== Keep on topic ===
As a wiki centered around the Minecraft Forge modding API, topics within the wiki should be related and kept on topic.

Topics, articles, discussions, and the like should be related to the wiki, whether to the community or governance of the wiki or to the central topic. This is to keep this wiki directed towards its central topic and to avoid having articles which do not hold any meaningful value or relevancy to this wiki.

== Wiki staff ==
The wiki staff is composed of all active [[FCWMeta:User access levels#Administrators and Moderators|moderators and administrators]], which determine the policies of this wiki, enforce any binding decisions, keep the peace within the wiki's community, and moderate and curate the wiki's contents.

Members of wiki staff may be contacted through their emails, their talk page, or their Discord account.

== Moderation ==
The wiki staff may apply sanctions to editors which violate the rules and policies of this wiki. They may use their discretion on what sanction to apply, depending on the severity of the violation and any other factors which may affect their decision.

The following is a list of applicable sanctions, in increasing order of severity. This does not define a rigid list of possible sanctions, as the wiki staff may apply harsher or milder sanctions upon their discretion. Wiki staff may also apply multiple sanctions.

{| class="wikitable"
! Type of Sanction
! Description
|-
| Warning
| A verbal warning is given to the violating editor, which will be logged by staff to be referenced for any future violations by the editor.
|-
| Specific block
| The violating editor is temporarily or permanently blocked from editing specific pages or namespaces within the wiki.
|-
| Revocation of rights
| Any [[FCWMeta:User access levels|special user rights]] granted previously to the violating editor are revoked, either temporarily or permanently.
|-
| Sitewide block
| The violating editor is temporarily or permanently blocked from any contributions to any page in the wiki.
|}

=== Appeals ===
If an editor wishes to appeal a sanction made by a member of the wiki staff, they may appeal to an uninvolved administrator. The appealing administrator may uphold the current decision, overturn and revert the decision and action, or if necessary deliberate with the other wiki staff to make a final binding decision. Repeated attempts to appeal to administrators without any merit shall be sanctioned appropriately at their discretion.

Access Transformers

2021-08-13T02:36:50Z

SciWhiz12: add note about inner classes and $ separator

'''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|encapsulation]] or private methods which are part of the implementation of the class and should not be 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
! Subclasses
! Classes in the same package
! 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
|}

== 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 SerializableUUID,
# which accepts two longs and returns an int[]
public net.minecraft.core.SerializableUUID m_123274_(JJ)[I # leastMostToIntArray
</syntaxhighlight>

AT

2021-08-13T02:32:07Z

SciWhiz12: redirect to access transformers page

#REDIRECT [[Access Transformers]]

ATs

2021-08-13T02:31:45Z

SciWhiz12: redirect to access transformers page

#REDIRECT [[Access Transformers]]

Access Transformer

2021-08-13T02:31:07Z

SciWhiz12: redirect to access transformers page

#REDIRECT [[Access Transformers]]

Access Transformers

2021-08-13T02:29:56Z

SciWhiz12: no to java highlighting

'''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|encapsulation]] or private methods which are part of the implementation of the class and should not be 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
! Subclasses
! Classes in the same package
! 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>
|-
| <code>V</code> || <code>void</code> || a void or no-value return type; only available for the return type of a method descriptor
|}

== 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 SerializableUUID,
# which accepts two longs and returns an int[]
public net.minecraft.core.SerializableUUID m_123274_(JJ)[I # leastMostToIntArray
</syntaxhighlight>

Access Transformers

2021-08-13T02:28:30Z

SciWhiz12: Rewrite page to be more 'wiki' in tone and more descriptive in nature, remove under construction header

'''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|encapsulation]] or private methods which are part of the implementation of the class and should not be 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
! Subclasses
! Classes in the same package
! 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>
|-
| <code>V</code> || <code>void</code> || a void or no-value return type; only available for the return type of a method descriptor
|}

== Examples ==

The following are some examples of access transformer declarations:

<syntaxhighlight lang="java">
# 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 SerializableUUID,
# which accepts two longs and returns an int[]
public net.minecraft.core.SerializableUUID m_123274_(JJ)[I # leastMostToIntArray
</syntaxhighlight>

Registration

2021-08-02T20:31:56Z

SciWhiz12: Avoid using "$" character in header

{{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)
}
|}}

{{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, you will need to call <code>Registry::register(Registry, ResourceLocation, T)</code> where the type parameter <code>T</code> is the object instance being registered. The method can then be called and registered during the highest priority of <code>FMLCommonSetupEvent</code>. We can also utilize a <code>Lazy</code> above to store the result on first access and use within our code.

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

{{Template:Tabs/Code_Snippets
|java=public static final Lazy<ConfiguredFeature<?, ?>> EXAMPLE_CONFIGURED_FEATURE = Lazy.of(() ->
register("example_configured_feature",
Feature.NO_OP.configured(NoneFeatureConfiguration.INSTANCE)
.decorated(FeatureDecorator.NOPE.configured(NoneDecoratorConfiguration.INSTANCE))
)
);

@SubscribeEvent(priority = EventPriority.HIGHEST)
public void register(FMLCommonSetupEvent event) {
event.enqueueWork(EXAMPLE_CONFIGURED_FEATURE::get);
}

private static <T extends ConfiguredFeature<?, ?>> T register(String name, T value) {
return Registry.register(BuiltinRegistries.CONFIGURED_FEATURE, new ResourceLocation(MODID, name), value);
}
|kotlin=val EXAMPLE_CONFIGURED_FEATURE: ConfiguredFeature<*, *> by lazy {
register("example_configured_feature",
Feature.NO_OP.configured(NoneFeatureConfiguration.INSTANCE)
.decorated(FeatureDecorator.NOPE.configured(NoneDecoratorConfiguration.INSTANCE)))
}

object Events {

@SubscribeEvent(priority = EventPriority.HIGHEST)
fun register(event: FMLCommonSetupEvent) {
event.enqueueWork(EXAMPLE_CONFIGURED_FEATURE::getConfig)
}
}

private fun <T: ConfiguredFeature<*, *>> register(name: String, value: T): T =
Registry.register(BuiltinRegistries.CONFIGURED_FEATURE, ResourceLocation(MODID, name), value)
|scala=class Events {
@SubscribeEvent(priority = EventPriority.HIGHEST)
def register(event: FMLCommonSetupEvent): Unit = {
event.enqueueWork(Events.EXAMPLE_CONFIGURED_FEATURE.getConfig _)
}
}
object Events {
final lazy val EXAMPLE_CONFIGURED_FEATURE = register("example_configured_feature",
Feature.NO_OP.configured(NoneFeatureConfiguration.INSTANCE)
.decorated(FeatureDecorator.NOPE.configured(NoneDecoratorConfiguration.INSTANCE)))

private def register[T <: ConfiguredFeature[_, _]](name: String, value: T): T =
Registry.register(BuiltinRegistries.CONFIGURED_FEATURE, new ResourceLocation(MODID, name), value)
}
|}}

{{Tip/Warning|Vanilla registry methods are not thread-safe, so they must be wrapped within the synchronous queue provided within the common setup event via <code>#enqueueWork</code>.}}

Besides the registries within <code>BuiltinRegistries</code>, all other '''non-forge''' wrapped registries can be statically initialized like so:

{{Template:Tabs/Code_Snippets
|java=public static final RecipeType<ExampleRecipe> EXAMPLE_RECIPE = RecipeType.register(MODID + ":example_recipe");
|kotlin=val EXAMPLE_RECIPE: RecipeType<ExampleRecipe> = RecipeType.register("${MODID}:example_recipe")
|scala=final val EXAMPLE_RECIPE = RecipeType.register(s"${MODID}:example_recipe")
|}}

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::of</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.of(new ResourceLocation("examplemod:example_item"), ForgeRegistries.ITEMS);

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

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

// Assume that 'ExampleRegistry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
final val EXAMPLE_OBJECT = RegistryObject.of(new ResourceLocation("examplemod", "example_object"), () => classOf[ExampleRegistry]);
|}}

{{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(Class, String)</code>. The class supplied must extend <code>IForgeRegistryEntry</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(ExampleRegistry.class, MODID);

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

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

final lazy val REGISTRY = EXAMPLE.makeRegistry("example_registry", () => 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''')

<syntaxhighlight lang="Java">
// This will ignore any missing test items from the specified world
@SubscribeEvent
public void onMissingItems(RegistryEvent.MissingMappings<Item> event){
event.getMappings(MODID).stream()
.filter(mapping -> mapping.key.getPath().contains("test"))
.forEach(Mapping::ignore);
}
</syntaxhighlight>

[[Category:Common Concepts]]

MediaWiki:Grouppage-checkuser

2021-08-01T17:11:32Z

SciWhiz12: Created page with "{{ns:project}}:User_access_levels#Check_users"

{{ns:project}}:User_access_levels#Check_users

FCWMeta:User access levels

2021-08-01T17:09:59Z

SciWhiz12: Fix unbalanced header marks

The '''user access level''' of an editor determines what abilities they have and what actions they can perform. Each user access level, or '''user group''', has permissions/rights which are assigned. See [[Special:ListGroupRights]] to see all the available user groups and their permissions/rights.

== Administrators and Moderators ==
'''Administrators''' and '''Moderators''' are editors who have broad rights over the whole wiki, such as protection, deletion, moving of pages, blocking and unblocking of users, and more. Administrators have more sensitive rights, and can assign and remove Moderators.

These editors are part of the ''wiki staff'', which determine the policies of this wiki, enforce any binding decisions, keep the peace of the wiki, and moderate and curate its contents.

The wiki staff may decide, from time to time, to grant Moderator status to active, reputable, and responsible editors. Requests for staff access level will not be entertained, however endorsements for other editors' may be considered.

There are currently '''{{NUMBERINGROUP:administrator}}''' administrators and '''{{NUMBERINGROUP:moderator}}''' moderators.

== Trusted users ==
'''Trusted users''' are editors who have been active in their contributions or are reputable members of the community, and has the trust of the wiki staff. They have the rights to edit semi-protected pages, and patrol changes.

If you have been especially active in contributing, a staff member may grant this access level to you. You may also request this access level by contacting one of the staff; however, repeated requests may warrant sanctions.

There are currently '''{{NUMBERINGROUP:trusted}}''' trusted users.

== Special access levels ==
These access levels are specially granted to users by decision of the wiki staff. Requests for these access levels will not be considered, and may warrant sanctions.

==== Keepers of the Keys ====
The '''Keepers of the Keys''' are administrators who have the rights to assign and remove access levels from all other users, including other administarotrs.

The origin of this access group is derived from the principle of there being multiple administrators with high-level access to the wiki, to ensure that there is always someone available to administer the wiki and if necessary, take control of the wiki if the other administrators are out-of-contact and unreachable.

There are currently '''{{NUMBERINGROUP:root}}''' keepers of the keys.

==== Interface administrators ====
'''Interface administrators''' are editors who are given editing access to the MediaWiki interface CSS and JS files, through the <code>MediaWiki</code> namespace.

There are currently '''{{NUMBERINGROUP:interface-admin}}''' interface administrators.

==== Check users ====
'''Check users''' are editors who have access to a log that lists out usernames used by which IPs and IPs used by which usernames. As this tool can be used to personally identify users through their IP, access is restricted to those who may need need, and use of the checkuser tool is strictly monitored.

There are currently '''{{NUMBERINGROUP:checkuser}}''' check users.

==== Suppressors ====
'''Suppressors''' are editors who can hide revisions and log entries from users (and even administrators), in cases such as personal information being posted. As this is a powerful tool, access is restricted to those who may need it, and use of the suppression tools are strictly monitored.

There are currently '''{{NUMBERINGROUP:suppress}}''' suppressors.

==== Autoconfirmed users ====
'''Autoconfirmed users''' are editors who have at least 5 edits and their account is at least 14 days old.
Currently, these users are only not affected by IP-based rate limits (the <code>autoconfirmed</code> right).

There are currently '''{{NUMBERINGROUP:autoconfirmed}}''' autoconfirmed users.

==== Bots ====
'''Bots''' are programs that do automated or mass-editing tasks, which may be tedious or impossible to perform manually.

There are currently '''{{NUMBERINGROUP:bot}}''' bots.

FCWMeta:User access levels

2021-08-01T17:09:06Z

SciWhiz12: Add info on check users, clarify why keepers exist, add user counts

The '''user access level''' of an editor determines what abilities they have and what actions they can perform. Each user access level, or '''user group''', has permissions/rights which are assigned. See [[Special:ListGroupRights]] to see all the available user groups and their permissions/rights.

== Administrators and Moderators ==
'''Administrators''' and '''Moderators''' are editors who have broad rights over the whole wiki, such as protection, deletion, moving of pages, blocking and unblocking of users, and more. Administrators have more sensitive rights, and can assign and remove Moderators.

These editors are part of the ''wiki staff'', which determine the policies of this wiki, enforce any binding decisions, keep the peace of the wiki, and moderate and curate its contents.

The wiki staff may decide, from time to time, to grant Moderator status to active, reputable, and responsible editors. Requests for staff access level will not be entertained, however endorsements for other editors' may be considered.

There are currently '''{{NUMBERINGROUP:administrator}}''' administrators and '''{{NUMBERINGROUP:moderator}}''' moderators.

== Trusted users ==
'''Trusted users''' are editors who have been active in their contributions or are reputable members of the community, and has the trust of the wiki staff. They have the rights to edit semi-protected pages, and patrol changes.

If you have been especially active in contributing, a staff member may grant this access level to you. You may also request this access level by contacting one of the staff; however, repeated requests may warrant sanctions.

There are currently '''{{NUMBERINGROUP:trusted}}''' trusted users.

== Special access levels ==
These access levels are specially granted to users by decision of the wiki staff. Requests for these access levels will not be considered, and may warrant sanctions.

==== Keepers of the Keys ====
The '''Keepers of the Keys''' are administrators who have the rights to assign and remove access levels from all other users, including other administarotrs.

The origin of this access group is derived from the principle of there being multiple administrators with high-level access to the wiki, to ensure that there is always someone available to administer the wiki and if necessary, take control of the wiki if the other administrators are out-of-contact and unreachable.

There are currently '''{{NUMBERINGROUP:root}}''' keepers of the keys.

==== Interface administrators ====
'''Interface administrators''' are editors who are given editing access to the MediaWiki interface CSS and JS files, through the <code>MediaWiki</code> namespace.

There are currently '''{{NUMBERINGROUP:interface-admin}}''' interface administrators.

=== Check users ====
'''Check users''' are editors who have access to a log that lists out usernames used by which IPs and IPs used by which usernames. As this tool can be used to personally identify users through their IP, access is restricted to those who may need need, and use of the checkuser tool is strictly monitored.

There are currently '''{{NUMBERINGROUP:checkuser}}''' check users.

==== Suppressors ====
'''Suppressors''' are editors who can hide revisions and log entries from users (and even administrators), in cases such as personal information being posted. As this is a powerful tool, access is restricted to those who may need it, and use of the suppression tools are strictly monitored.

There are currently '''{{NUMBERINGROUP:suppress}}''' suppressors.

==== Autoconfirmed users ====
'''Autoconfirmed users''' are editors who have at least 5 edits and their account is at least 14 days old.
Currently, these users are only not affected by IP-based rate limits (the <code>autoconfirmed</code> right).

There are currently '''{{NUMBERINGROUP:autoconfirmed}}''' autoconfirmed users.

==== Bots ====
'''Bots''' are programs that do automated or mass-editing tasks, which may be tedious or impossible to perform manually.

There are currently '''{{NUMBERINGROUP:bot}}''' bots.

Main Page

2021-05-19T01:11:10Z

SciWhiz12: Protected "Main Page": Protect against moving the literal main page of our wiki ([Move=Allow only administrators] (indefinite))

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

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

The Forge Community Wiki exists so that the community can:

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

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

''The wiki is still under heavy construction. Pages may move around, so if you bookmark a page, beware when the page is moved and your bookmarked link dies.''

Please note that we only maintain wiki entries for the Latest and Long Term Support (LTS) releases. Once a documented release is no longer under LTS, it will be removed.

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

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

<div class="box_container center">

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

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

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

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

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

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

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

<div class="box">
<h3>Tile Entities</h3>
* [[Basics of Tile Entities|Introduction]]
* [[Using Tile Entity Renderers]]
</div>

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

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

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

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

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

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

</div>

Dependencies

2021-05-01T08:23:49Z

SciWhiz12: note that flatdirs should only be used temporarily

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/6.8.1/userguide/declaring_dependencies.html Gradle User Guide for 6.8.1: ''Declaring dependencies'']</ref>

For example, to declare a dependency on the <code>net:minecraftforge:eventbus:4.0.0</code> library from the <code>main</code> source set:
<syntaxhighlight lang="gradle">
dependencies {
// 'implementation' is for the main source set
implementation "net.minecraftforge:eventbus:4.0.0"
}
</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/6.8.1/userguide/declaring_repositories.html Gradle User Guide for 6.8.1: ''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 for 6.8.1: ''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/v6.8.1/subprojects/core-api/src/main/java/org/gradle/api/artifacts/repositories/FlatDirectoryArtifactRepository.java gradle/gradle; tag v6.8.1; 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>junit:junit:4.8.1</code>, it will first search for <code>junit-4.8.1.jar</code> then <code>junit.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.
}}

FCWMeta:Village pump

2021-04-20T00:48:12Z

SciWhiz12: use definitions, looks better

__NEWSECTIONLINK__

{{Colored box
|background-content-color=rgba(255, 255, 255, 0.08)
|style=display: block; text-align: center; font-size: 1.75rem
|'''Welcome to the village pump!'''
}}

This is a place for the community to discuss things related to the wiki. Propose new ideas, find people to collaborate in making articles, or ask something related to wiki; don't be afraid to post here!

Want to discuss something quicker, or find help on something? Why not join the [https://discord.gg/Nn42eAh Discord]?

'''Please add your signature''' whenever you make a comment on a topic, by adding <code><nowiki>- ~~~~</nowiki></code> to the end. When replying to a topic or other comment, use nested [[mw:Help:Lists#List basics|definitions]] (<code>:</code>) and indent according to where you're replying.

<hr>

== Tutorials page/namespace ==

One problem often seen in the modding community is the lack of available tutorials. This becomes a hurdle for new developers, who have to scour the internet for decent tutorials, which can be outdated or contain errors.

I propose that we add a ''Tutorials''' page or namespace, to allow the creation of tutorials here on the wiki. By being on the wiki, it can be edited and updated by anyone, allowing quick correction of errors and general improvements, the benefits on being on a publicly-editable wiki.

We have a few questions to answer though:
* Should we have a singular <code>Tutorial</code> page and have tutorials be in subpages (<code>Tutorial/Getting started</code>, <code>Tutorial/Blocks</code>), or use a new namespace (<code>Tutorial:Getting started</code>, <code>Tutorial:Blocks</code>)?
* Should we have example mods on these tutorial pages, or only have snippets? Example mods could be hosted on the [https://github.com/forgecommunitywiki/mod-examples FCW's <tt>mod-examples</tt> GitHub repo], though this raises the barrier of creating and improving these example mods.

Having tutorials on the wiki would improve our visibility (so people recommend the wiki's tutorials), and would benefit new developers who may be overwhelmed by other pages with the more technical details and encyclopedic tone.

- [[User:SciWhiz12|<span style="color: #d9d916; font-weight: bold">SciWhiz12</span>]] [[User talk:SciWhiz12|💬]] 04:39, 19 April 2021 (UTC)

: It would probably be better to have a separate namespace for the pages just for better organization on our part. Another issue to address there is multiple tutorials for the same topic. We would need to handle a way for multiple users to create their own method of handling (assuming it's sane). We could neglect that and just have a common tutorial to which everyone must agree on, but I'm not sure how well that would work in this format. As for example mods on these pages, I would vote no on that. There would be a pain to handle all the different languages that the snippet has to be translated to and PR level of entry here would be quite substantial. I would still have to add the translations here, but it's much easier than having user PRs do it. - [[User:ChampionAsh5357|ChampionAsh5357]] ([[User talk:ChampionAsh5357|talk]]) 04:53, 19 April 2021 (UTC)

FCWMeta:Village pump

2021-04-19T04:45:05Z

SciWhiz12: some signature changes

__NEWSECTIONLINK__

{{Colored box
|background-content-color=rgba(255, 255, 255, 0.08)
|style=display: block; text-align: center; font-size: 1.75rem
|'''Welcome to the village pump!'''
}}

This is a place for the community to discuss things related to the wiki. Propose new ideas, find people to collaborate in making articles, or ask something related to wiki; don't be afraid to post here!

Want to discuss something quicker, or find help on something? Why not join the [https://discord.gg/Nn42eAh Discord]?

'''Please add your signature''' whenever you make a comment on a topic, by adding <code><nowiki>- ~~~~</nowiki></code> to the end. When replying to a topic or other comment, use nested [[mw:Help:Lists#List basics|unordered lists]] and indent according to where you're replying.

<hr>

== Tutorials page/namespace ==

One problem often seen in the modding community is the lack of available tutorials. This becomes a hurdle for new developers, who have to scour the internet for decent tutorials, which can be outdated or contain errors.

I propose that we add a ''Tutorials''' page or namespace, to allow the creation of tutorials here on the wiki. By being on the wiki, it can be edited and updated by anyone, allowing quick correction of errors and general improvements, the benefits on being on a publicly-editable wiki.

We have a few questions to answer though:
* Should we have a singular <code>Tutorial</code> page and have tutorials be in subpages (<code>Tutorial/Getting started</code>, <code>Tutorial/Blocks</code>), or use a new namespace (<code>Tutorial:Getting started</code>, <code>Tutorial:Blocks</code>)?
* Should we have example mods on these tutorial pages, or only have snippets? Example mods could be hosted on the [https://github.com/forgecommunitywiki/mod-examples FCW's <tt>mod-examples</tt> GitHub repo], though this raises the barrier of creating and improving these example mods.

Having tutorials on the wiki would improve our visibility (so people recommend the wiki's tutorials), and would benefit new developers who may be overwhelmed by other pages with the more technical details and encyclopedic tone.

- [[User:SciWhiz12|<span style="color: #d9d916; font-weight: bold">SciWhiz12</span>]] [[User talk:SciWhiz12|💬]] 04:39, 19 April 2021 (UTC)

FCWMeta:Village pump

2021-04-19T04:42:59Z

SciWhiz12: add mention of using nested lists

__NEWSECTIONLINK__

{{Colored box
|background-content-color=rgba(255, 255, 255, 0.08)
|style=display: block; text-align: center; font-size: 1.75rem
|'''Welcome to the village pump!'''
}}

This is a place for the community to discuss things related to the wiki. Propose new ideas, find people to collaborate in making articles, or ask something related to wiki; don't be afraid to post here!

Want to discuss something quicker, or find help on something? Why not join the [https://discord.gg/Nn42eAh Discord]?

'''Please add your signature''' whenever you make a comment on a topic, by adding <code><nowiki>~~~~</nowiki></code> to the end. When replying to a topic or other comment, use nested [[mw:Help:Lists#List basics|unordered lists]] and indent according to where you're replying.

<hr>

== Tutorials page/namespace ==

One problem often seen in the modding community is the lack of available tutorials. This becomes a hurdle for new developers, who have to scour the internet for decent tutorials, which can be outdated or contain errors.

I propose that we add a ''Tutorials''' page or namespace, to allow the creation of tutorials here on the wiki. By being on the wiki, it can be edited and updated by anyone, allowing quick correction of errors and general improvements, the benefits on being on a publicly-editable wiki.

We have a few questions to answer though:
* Should we have a singular <code>Tutorial</code> page and have tutorials be in subpages (<code>Tutorial/Getting started</code>, <code>Tutorial/Blocks</code>), or use a new namespace (<code>Tutorial:Getting started</code>, <code>Tutorial:Blocks</code>)?
* Should we have example mods on these tutorial pages, or only have snippets? Example mods could be hosted on the [https://github.com/forgecommunitywiki/mod-examples FCW's <tt>mod-examples</tt> GitHub repo], though this raises the barrier of creating and improving these example mods.

Having tutorials on the wiki would improve our visibility (so people recommend the wiki's tutorials), and would benefit new developers who may be overwhelmed by other pages with the more technical details and encyclopedic tone. [[User:SciWhiz12|<span style="color: #d9d916; font-weight: bold">SciWhiz12</span>]] [[User talk:SciWhiz12|💬]] 04:39, 19 April 2021 (UTC)

FCWMeta:Village pump

2021-04-19T04:39:10Z

SciWhiz12: add my signature

FCWMeta:Village pump

2021-04-19T04:38:46Z

SciWhiz12: /* Tutorials page/namespace */ new section

FCWMeta:Village pump

2021-04-19T04:23:17Z

SciWhiz12: some small edits

FCWMeta:Village pump

2021-04-19T04:20:30Z

SciWhiz12: create the page

Template:Tabs/Tab/Code Snippet

2021-04-08T20:47:32Z

SciWhiz12: Add lang attribute to code snippet template call

{{#tag:tab
|{{#if:{{{file_name|}}}|{{{file_name}}}{{#if:{{{ext|}}}|.{{{ext|}}}|}}|}}
{{Template:Code_Snippet
|content={{{content|{{{1}}}}}}
|lang={{#if:{{{lang|}}}|{{{lang}}}|}}
}}
|lang={{#if:{{{lang|}}}|{{{lang}}}|}}
|name="{{#if:{{{lang|}}}|{{ucfirst:{{{lang}}}}}|Tab}}"
|style="width:100%;"
}}

Category:Under construction

2021-04-08T11:01:02Z

SciWhiz12: SciWhiz12 moved page Category:Under construction to Category:Pages under construction: imo, a better name

#REDIRECT [[:Category:Pages under construction]]

Category:Pages under construction

2021-04-08T11:01:02Z

SciWhiz12: SciWhiz12 moved page Category:Under construction to Category:Pages under construction: imo, a better name

All pages marked with [[Template:Under construction]] are listed here. Editors are encouraged to edit and improve these pages, and to remove the template once the page looks complete.

Template:Under construction

2021-04-08T11:00:13Z

SciWhiz12: change category to :Category:Pages under construction

{{Colored box
|icon=Under_construction.svg
|border-color=#f6c800
|title={{{title|This page is under construction.}}}
|{{{1|This page is incomplete, and needs more work. Feel free to edit and improve this page!}}}
}}
<includeonly>[[Category:Pages under construction]]</includeonly>