Forge Community Wiki - User contributions [en-gb]

World Saved Data/1.18

2022-06-10T07:46:34Z

ShrimpBot: Copy World Saved Data to MC1.18 archive

#REDIRECT [[Saved Data/1.18|Saved Data]]

Version Checker/1.18

2022-06-10T07:46:32Z

ShrimpBot: Copy Version Checker to MC1.18 archive

The '''Version Checker''' is a Forge-provided utility for mods to check for new versions based on an online update JSON file. It is lightweight, toggleable, asynchoronous to the main mod loading, and integrates cleanly with the mods list menu.

If there are outdated mods according to the version checker, a flashing emerald indicator will be shown on the Mods button on the main menu. The entries for the outdated mods in the mods list screen have the flashing emerald indicator. The information screen for outdated mods will have an <code>Update available:</code> line with the <code>homepage</code> URL from the update JSON file, and a list of mod versions and corresponding text after the mod description, for the mod versions between the most up-to-date and the currently installed version.


The version checker can be configured through the <code>versionCheck</code> option in the FML config (<tt>config/fml.toml</tt>). This option controls the version checking for all mods, including Forge.

== Update JSON format ==
The version checker checks the update JSON, specified by the <code>updateJSONURL</code> for the [[Proper Mod Structuring#Mod Properties/1.18|mod in the <tt>mods.toml</tt>]]. An example of a JSON file is the [https://files.minecraftforge.net/maven/net/minecraftforge/forge/promotions_slim.json update JSON for Minecraft Forge]. The JSON file must be in the following format:
{{Tree list}}
* '''Root object'''
** <code>homepage</code> (string): A URL, displayed on the mod's information screen on the Mods list screen
** <code>promos</code> (object)
*** <code>'''''<nowiki><minecraft version></nowiki>'''''-latest</code> (string): A version string, for the latest mod version corresponding to the given Minecraft version
*** <code>'''''<nowiki><minecraft version></nowiki>'''''-recommended</code> (string): A version string, for the recommended mod version corresponding to the given Minecraft version
*** ...
** <code>'''''<nowiki><minecraft version></nowiki>'''''</code> (object)
*** <code>'''''<nowiki><mod version></nowiki>'''''</code> (string): Any text, displayed when the the specified mod version in the key is ahead of currently installed version; used as a changelog
*** ...
{{Tree list/end}}

== Update status ==
There are 7 possible version checker statuses, according to the <code>VersionChecker.Status</code> enum:
* <code>PENDING</code> - The version checker has not or is currently retrieving the version from the update JSON. This is temporary, and will change into one of the other statuses.
* <code>FAILED</code> - The version checker failed, either to retrieve the update JSON or some other error (such as failure to parse broken JSON).
* <code>UP_TO_CODE</code> - The currently installed version is the same as the recommended version for the current Minecraft version.
* <code>OUTDATED</code> - The currently installed version is either behind the recommended version for the MC version, or ahead of the recommended version, but behind the latest version for the MC version.
* <code>AHEAD</code> - The currently installed version is ahead of the recommended version for the MC version, and there is no more up-to-date latest version for the MC version. 
* <code>BETA</code> - There is no recommended version, and either the currently installed version is up-to-date or ahead of the latest version, or there is no latest version for the MC version.
* <code>BETA_OUTDATED</code> - There is no recommended version, and the currently installed version is behind the latest version for the MC version.

== <tt>CheckResult</tt> ==
The version checker result for a mod can be retrieving using the <code>VersionChecker.getResult(IModInfo)</code> static method which returns a <code>CheckResult</code>. (<code>IModInfo</code> is the information for a specific mod; see <code>ModList#getModContainerById(String)</code> and <code>ModContainer#getModInfo()</code>).

The <code>CheckResult</code> contains four unmodifiable fields:
* <code>status</code>, the version checker status as a <code>VersionChecker.Status</code> enum value.
* <code>target</code>, the version which caused the <code>OUTDATED</code>, <code>BETA</code> or <code>BETA_OUTDATED</code>
** If the status is <code>OUTDATED</code>, this is the newest recommended or latest version from the JSON.
** If the status is <code>BETA_OUTDATED</code> or <code>BETA</code>, this is the highest newest version from the JSON.
** This may be <code>null</code> if the status is <code>BETA</code>, and there is no recommended or latest version defined in the JSON file.
* <code>changes</code>, an unmodifiable map of mod versions and their corresponding text based on the MC version, where the mod versions are higher than the currently installed version. This information is shown on the mods information screen, as a changelog.
* <code>url</code>, the URL from the <code>homepage</code> string in the update JSON, displayed on the mods information screen.

Using Tile Entity Renderers/1.18

2022-06-10T07:46:30Z

ShrimpBot: Copy Using Tile Entity Renderers to MC1.18 archive

#REDIRECT [[Tile Entity Renderer/1.18|Tile Entity Renderer]]

Using SimpleChannel/1.18

2022-06-10T07:46:29Z

ShrimpBot: Copy Using SimpleChannel to MC1.18 archive

#REDIRECT [[SimpleChannel/1.18|SimpleChannel]]

Using Resources/1.18

2022-06-10T07:46:27Z

ShrimpBot: Copy Using Resources to MC1.18 archive

#REDIRECT [[Resources/1.18|Resources]]

[[Category:Resources and Data/1.18|Category:Resources and Data]]

Using PacketBuffer/1.18

2022-06-10T07:46:25Z

ShrimpBot: Copy Using PacketBuffer to MC1.18 archive

#REDIRECT [[Using FriendlyByteBuf/1.18|Using FriendlyByteBuf]]

Using NBT/1.18

2022-06-10T07:46:23Z

ShrimpBot: Copy Using NBT to MC1.18 archive

#REDIRECT [[Named Binary Tag/1.18|Named Binary Tag]]

Using FriendlyByteBuf/1.18

2022-06-10T07:46:22Z

ShrimpBot: Copy Using FriendlyByteBuf to MC1.18 archive

<code>FriendlyByteBuf</code>s are essentially a byte array of zero or more bytes to sync information across a network. It works similarly to a queue: the information is written in to a specific order and read in the order it was written.

== Using <code>FriendlyByteBuf</code>s ==

In most cases, one will use a premade <code>FriendlyByteBuf</code> passed in from some network. Most of the time this is a heap buffer of some sort; however, understanding how it works is best left as an explanation of data structures.

When you are '''writing''' to a <code>FriendlyByteBuf</code>, you are calling one of the many write functions to store information as bytes (e.g. <code>writeBlockPos</code> or <code>writeVarInt</code>). There are a couple of helpers for objects like <code>CompoundTag</code>, <code>ItemStack</code>s, etc. if they are needed.

When you are '''reading''' from a <code>FriendlyByteBuf</code>, you are calling the equivalent read function in the same order. For example, if you call <code>writeBlockPos</code> and then <code>writeVarInt</code>, you would call <code>readBlockPos</code> and then <code>readVarInt</code> in that order. Each of these method returns the value from the buffer.

Update Checker/1.18

2022-06-10T07:46:20Z

ShrimpBot: Copy Update Checker to MC1.18 archive

#REDIRECT [[Version Checker/1.18|Version Checker]]

[[Category:Beginner Topics/1.18|Category:Beginner Topics]]

Understanding Networking/1.18

2022-06-10T07:46:18Z

ShrimpBot: Copy Understanding Networking to MC1.18 archive

#REDIRECT [[Networking/1.18|Networking]]

Understanding Blockstates/1.18

2022-06-10T07:46:16Z

ShrimpBot: Copy Understanding Blockstates to MC1.18 archive

#REDIRECT [[BlockStates/1.18|BlockStates]]

[[Category:Blocks/1.18|Category:Blocks]]

Toolchain:Magic Constants/1.18

2022-06-10T07:46:15Z

ShrimpBot: Copy Toolchain:Magic Constants to MC1.18 archive

#REDIRECT [[Toolchain/Magic Constants/1.18|Toolchain/Magic Constants]]

Toolchain/Retro/2.1/1.18

2022-06-10T07:46:13Z

ShrimpBot: Copy Toolchain/Retro/2.1 to MC1.18 archive

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The following steps are all executed in order of appearance.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For now, it is a necessity.

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

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

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

It is a simple program, but it works.

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

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

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

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

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

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

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

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

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

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

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

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

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

== The Forge Side ==

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

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

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

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

=== Applying Access Transformers ===

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

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

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

=== Applying Patches ===

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

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

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

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

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

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

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

=== Post-processing ===

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

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

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

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

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

Toolchain/Magic Constants/1.18

2022-06-10T07:46:11Z

ShrimpBot: Copy Toolchain/Magic Constants to MC1.18 archive

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

== Constants ==

The known substitutions are:

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

Toolchain/1.18

2022-06-10T07:46:09Z

ShrimpBot: Copy Toolchain to MC1.18 archive

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

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

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

== Overall process ==
Whenever a gradle refresh is triggered, a few things occur:
# ForgeGradle downloads the jar and MCPConfig zip and triggers the extractSrg/createSrgToMcp task.
# After that, it processes the jar - applies access transformers from forge/userdev, SAS from forge, and decompiles.
# Finally, it patches and finalizes the code, ready for modder consumption.

This is triggered whenever the <code>setup</code> task is ran.

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

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

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

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

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

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

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

The SRG name of the member is then derived from its SRG ID and its type (method {given the prefix <code>m_</code>}, field {given the prefix <code>f_</code>}, or parameter {given the prefix <code>p_</code>}). <ref>The SRG name for a given member is only created once, when it first appears in the code.</ref>. This inclusion of the SRG ID into the name guarantees that the SRG name for all members are unique, and is the reason the ID is generated.

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

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

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

The following steps are all executed in order of appearance.

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

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

{{Tip|content=A config.json can be found [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.17.1/config.json here] which defines the following steps:
* [[Toolchain:ForgeFlower/1.18|fernflower]]
** version: net.minecraftforge:forgeflower:1.5.498.12
** args: -din=1 -rbr=1 -dgs=1 -asc=1 -rsy=1 -iec=1 -jvn=1 -isl=0 -iib=1 -log=TRACE -cfg {libraries} {input} {output}
** jvmargs: -Xmx4G
* [[Toolchain:Mergetool/1.18|merge]]
** version: net.minecraftforge:mergetool:1.1.3:fatjar
** args: --client {client} --server {server} --ann {version} --output {output} --inject false
* [[Toolchain:MCInjector/1.18|rename]]
** version: net.minecraftforge.lex:vignette:0.2.0.10
** args: --jar-in {input} --jar-out {output} --mapping-format tsrg2 --mappings {mappings} --fernflower-meta --cfg {libraries} --create-inits --fix-param-annotations

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

=== ForgeFlower ===
The decompiler used by ForgeGradle is a custom fork of [https://github.com/JetBrains/intellij-community/tree/master/plugins/java-decompiler/engine Jetbrains' FernFlower], called [https://github.com/MinecraftForge/ForgeFlower ForgeFlower] which searches the jar for files, cleans up the bytecode, and then converts it into a reasonable best-guess interpretation.

It also produces the following side effects:
* Removes synthetic parameters from constructors
** In bytecode, inner classes have the outer class as their first constructor parameter, but Java source code does not.
* Adds constructors for inner classes
** These are removed by Proguard sometimes, as they are not required in the bytecode if the parent has a default constructor.
* Hides bridge methods
* Decompiles generic signatures
* Encodes non-ASCII characters in string and character literals as Unicode escaped characters
* Hides synthetic class members
* Prevents simple lambdas from being inlined

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

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

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

For now, it is a necessity.

=== Mergetool ===
The game is split into two distributions; server and client. Since the server is just a subset of the client, the client contains the server-only classes as well.

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

It is a simple program, but it works.

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

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

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

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

Vignette itself operates on the compiled jar and takes in a .tsrg file, like that [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.17.1/joined.tsrg contained in the MCPConfig zip]. It does this because it's easier to rename LVT entries (from the snowman) to readable names while you can search for every other code path that references that specific entry; ergo renaming all accesses at once. This is impossible in source code, where every name is identical and string matching is impossible.

It also:
* Handles adding annotations for parameters that have synthetic data
** In bytecode, these Nonnull (or whatever) annotations are attached to the parameters, not to the function that contains them.
* Adds synthetic (invisible) constructors for classes without them

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

First, the class names are renamed from their obfuscated target to the specified mapping output.
Then, iterating the members of the class, it renames fields, methods, parameters, and inner classes.

A recap from earlier:
* For classes -> <code>C_###_</code> (but it is transparently remapped without the C_ being written to disk)
* For functions/methods -> <code>m_<ID>_</code>
* For fields -> <code>f_<ID>_</code>
* For function/method parameters -> <code>p_###_</code><ref>The index is the position of the argument. 0 on the left, 1 after that, 2 after that. Note that double and long arguments increase their index by two, rather than one of the parameter</ref>.

For example, <code>m_91087_</code> refers to a function with SRG ID 91087.<ref>For version 1.17.1, <code>m_91087_</code> refers to <code>Minecraft#getInstance</code> with an obfuscated name of <code>dvp$C</code>.</ref>

At this point, we have a completely remapped jar.

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

== The Forge Side ==

When Forge is first loaded by gradle, it prepares the files for setting up the workspace.

The initial setup is done through the <code>gradlew setup</code> task. It will run the SetupMCP tasks and then start applying the Forge system to the processed vanilla code. After the MCPConfig/SetupMCP tasks are finished, ForgeGradle will print '''MCP Environment Setup is complete''' and continue. The text '''pausing after requested step''' is also printed twice during this task such that some necessary data can be extracted.

First, it applies ATs. After that, patches. Finally, the official mappings, or some other mappings from a provider like Parchment, are applied.

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

=== Applying Access Transformers ===

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

They are applied by passing the AT Config (nowadays called accesstransformer.cfg) into AccessTransformers:
* <code>AccessTransformers.jar --inJar {input} --outJar {output} --logFile accesstransform.log --atFile {at.cfg}</code>

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

=== Applying Patches ===

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

As opposed to the minimal MCPConfig patching, with the goal to make the code recompilable, the Forge patching is done to apply the API and mod loader to the code.

It does this in a very similar way, with the [https://github.com/MinecraftForge/BinaryPatcher BinaryPatcher] utility used at install time/during a CI build or [https://github.com/MinecraftForge/DiffPatch DiffPatch] in all other situations.

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

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

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

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

=== Post-processing ===

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

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

== Some Additional Info ==
# You will never see C_XXX_ for classes, because the class names are picked beforehand using the official mapping class names
# If you look into the JAR, you won't see any packages for the obfuscated classes, but the deobfuscated classes do have the packages, this is because the same process that names the classes, also decides what package they belong to

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

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

Tinted Textures/1.18

2022-06-10T07:46:07Z

ShrimpBot: Copy Tinted Textures to MC1.18 archive

Many blocks and items in vanilla change their texture color depending on where they are, such as grass. Models support specifying “tint indices” on faces, which are integers that can then be handled by <code>BlockColor</code>s and <code>IItemColor</code>s. See the wiki for information on how tint indices are defined in vanilla models.

=== BlockColor / ItemColor ===
Both of these are single-method interfaces. <code>BlockColor</code> takes a <code>BlockState</code>, a (<code>nullable</code>) <code>BlockAndTintGetter</code>, and a (<code>nullable</code>) <code>BlockPos</code>. <code>ItemColor</code> takes an <code>ItemStack</code>. Both of them take a parameter <code>tintIndex</code>, which is the tint index of the face being colored. Both of them return an <code>int</code>, a color multiplier. This int is treated as four unsigned bytes, alpha, red, green, and blue, in that order, from most significant byte to least. For each pixel in the tinted face, the value of each color channel is <code><nowiki>(int)((float)base * multiplier / 255)</nowiki></code>, where <code>base</code> is the original value for the channel, and <code>multiplier</code> is the associated byte from the color multiplier. Note that blocks do not use the alpha channel. For example, the grass texture, untinted, looks white and gray. The <code>BlockColor</code> and <code>ItemColor</code> for grass return color multipliers with low red and blue components, but high alpha and green components, (at least in warm biomes) so when the multiplication is performed, the green is brought out and the red/blue diminished.

If an item inherits from the <code><nowiki>builtin/generated</nowiki></code> model, each layer (“layer0”, “layer1”, etc.) has a tint index corresponding to its layer index. For blocks, the “particle” layer is index 0.

=== Creating Color Handlers ===
<code>BlockColor</code>s need to be registered to the <code>BlockColors</code> instance of the game. <code>BlockColors</code> can be acquired through <code>ColorHandlerEvent$Block</code>, and an <code>BlockColor</code> can be registered by <code><nowiki>BlockColors#register</nowiki></code>. Note that this does not cause the <code>BlockItem</code> for the given block to be colored. <code>BlockItem</code> are items and need to colored with an <code>ItemColor</code>.
{{Template:Tabs/Code_Snippets
|java=public void registerBlockColors(final ColorHandlerEvent.Block event) {
event.getBlockColors().register(myBlockColor, coloredBlock1, coloredBlock2, ...);
}
|groovy=void registerBlockColors(final ColorHandlerEvent.Block event) {
event.blockColors.register(myBlockColor, coloredBlock1, coloredBlock2, ...);
}
|}}
<code>ItemColor</code>s need to be registered to the <code>ItemColors</code> instance of the game. <code>ItemColors</code> can be acquired through <code><nowiki>ColorHandlerEvent$Item</nowiki></code>, and an <code>ItemColor</code> can be registered by <code><nowiki>ItemColors#register</nowiki></code>. This method is overloaded to also take <code>Block</code>s, which simply registers the color handler for the item <code><nowiki>Block#asItem</nowiki></code> (i.e. the block’s <code>BlockItem</code>).
{{Template:Tabs/Code_Snippets
|java=public void registerItemColors(final ColorHandlerEvent.Item event) {
event.getItemColors().register(myItemColor, coloredItem1, coloredItem2, ...);
}
|groovy=void registerBlockColors(final ColorHandlerEvent.Item event) {
event.itemColors.register(myItemColor, coloredItem1, coloredItem2, ...);
}
|}}
This registration must be done client-side, in the initialization phase.

Tile Entity Renderer/1.18

2022-06-10T07:46:05Z

ShrimpBot: Copy Tile Entity Renderer to MC1.18 archive

#REDIRECT [[Block Entity Renderer/1.18|Block Entity Renderer]]

Tile Entity/1.18

2022-06-10T07:46:04Z

ShrimpBot: Copy Tile Entity to MC1.18 archive

#REDIRECT [[Tile Entities/1.18|Tile Entities]]

Tile Entities/1.18

2022-06-10T07:46:02Z

ShrimpBot: Copy Tile Entities to MC1.18 archive

#REDIRECT [[Block Entities/1.18|Block Entities]]

Text Components/1.18

2022-06-10T07:46:00Z

ShrimpBot: Copy Text Components to MC1.18 archive

#REDIRECT [[Components/1.18|Components]]

Tags/1.18

2022-06-10T07:45:58Z

ShrimpBot: Copy Tags to MC1.18 archive

Tags are generalized sets of objects in the game, used for grouping related things together and providing fast membership checks.

== Declaring Your Own Groupings ==
Tags are declared in your mod’s [https://mcforge.readthedocs.io/en/latest/utilities/tags/datapacks.md datapack]. For example, a <code><nowiki>TagKey<Block></nowiki></code> with a given identifier of <code><nowiki>modid:foo/tagname</nowiki></code> will reference a tag at <code><nowiki>/data/<modid>/tags/blocks/foo/tagname.json</nowiki></code>. Tags for <code><nowiki>Block</nowiki></code>s, <code><nowiki>Item</nowiki></code>s, <code><nowiki>EntityType</nowiki></code>s, <code><nowiki>Fluid</nowiki></code>s, and <code><nowiki>GameEvent</nowiki></code>s use the plural forms for their folder location while all other registries use the singular version (<code><nowiki>EntityType</nowiki></code> uses the folder <code><nowiki>entity_types</nowiki></code> while <code><nowiki>Potion</nowiki></code> would use the folder <code><nowiki>potion</nowiki></code>). Similarly, you may append to or override tags declared in other domains, such as Vanilla, by declaring your own JSONs. For example, to add your own mod’s saplings to the Vanilla sapling tag, you would specify it in <code><nowiki>/data/minecraft/tags/blocks/saplings.json</nowiki></code>, and Vanilla will merge everything into one tag at reload, if the <code><nowiki>replace</nowiki></code> option is false. If <code><nowiki>replace</nowiki></code> is true, then all entries before the json specifying <code><nowiki>replace</nowiki></code> will be removed.

Values listed that are not present will cause the tag to error unless the value is listed using an <code><nowiki>id</nowiki></code> string and <code><nowiki>required</nowiki></code> boolean set to false, as in the following example:

<syntaxhighlight lang="json">
{
"replace": false,
"values": [
"minecraft:gold_ingot",
"mymod:my_ingot",
{
"id": "othermod:ingot_other",
"required": false
}
]
}
</syntaxhighlight>

See the [https://minecraft.gamepedia.com/Tag#JSON_format Vanilla wiki] for a description of the base syntax.

There is also a Forge extension on the Vanilla syntax.
You may declare a <code><nowiki>remove</nowiki></code> array of the same format as the <code><nowiki>values</nowiki></code> array. Any values listed here will be removed from the tag. This acts as a finer grained version of the Vanilla <code><nowiki>replace</nowiki></code> option.

==Using Tags In Code==
Tags for all registries are automatically sent from the server to any remote clients on login and reload. <code><nowiki>Block</nowiki></code>s, <code><nowiki>Item</nowiki></code>s, <code><nowiki>EntityType</nowiki></code>s, <code><nowiki>Fluid</nowiki></code>s, and <code><nowiki>GameEvent</nowiki></code>s are special cased as they have <code><nowiki>Holder</nowiki></code>s allowing for available tags to be accessible through the object itself.

Tags wrappers can be created using <code><nowiki>TagKey#create</nowiki></code> where the registry the tag should belong to and the tag name are supplied. Some vanilla defined helpers are also available to create wrappers via <code><nowiki>*Tags#create</nowiki></code> where <code><nowiki>*</nowiki></code> refers to the name of the registry object. Forge wrapped registries can create a tag using <code><nowiki>ITagManager</nowiki></code> via <code><nowiki>IForgeRegistry#tags</nowiki></code>. <code><nowiki>TagKey</nowiki></code>s can then be obtained via <code><nowiki>ITagManager#createTagKey</nowiki></code>.

Forge wrapped registry objects can grab their associated holder using <code><nowiki>IForgeRegistry#getHolder</nowiki></code>. Additionally, other streamlined operations can be performed using <code><nowiki>ITagManager</nowiki></code>. Non-Forge registry objects use either <code><nowiki>Registry#getHolder</nowiki></code> or <code><nowiki>Registry#getHolderOrThrow</nowiki></code> to get the current holder.

They then can compare if the registry object has a tag using <code><nowiki>Holder#is</nowiki></code>. Tag-holding registry objects contain a method called <code><nowiki>#is</nowiki></code> in either their registry object or state-aware class to check whether the object belongs to a certain tag.

As an example:
<syntaxhighlight lang="java">
public static final TagKey<Item> myItemTag = ItemTags.create(new ResourceLocation("mymod", "myitemgroup"));

public static final TagKey<Potion> myPotionTag = ForgeRegistries.POTIONS.tags().createTagKey(new ResourceLocation("mymod", "mypotiongroup"));

public static final TagKey<VillagerType> myVillagerTypeTag = TagKey.create(Registry.VILLAGER_TYPE, new ResourceLocation("mymod", "myvillagertypegroup"));

// In some method where stack is an ItemStack
boolean isInItemGroup = stack.is(myItemTag);

// In some method where potion is a Potion
boolean isInPotionGroup = ForgeRegistries.POTIONS.tags().getTag(myPotionTag).contains(potion);

// In some method where villagerTypeKey is a ResourceKey<VillagerType>
boolean isInVillagerTypeGroup = Registry.VILLAGER_TYPE.getHolder(villagerTypeKey).map(holder -> holder.is(myVillagerTypeTag)).orElse(false);
</syntaxhighlight>

== Migration from OreDictionary ==
* For recipes, tags can be used directly in the vanilla recipe format (see below)
* For matching items in code, see the section above.
* If you are declaring a new type of item grouping, follow a couple naming conventions:
** Use <code><nowiki>domain:type/material</nowiki></code>. When the name is a common one that all modders should adopt, use the <code><nowiki>forge</nowiki></code> domain.
** For example, brass ingots should be registered under the <code><nowiki>forge:ingots/brass</nowiki></code> tag, and cobalt nuggets under the <code><nowiki>forge:nuggets/cobalt</nowiki></code> tag.

== Using Tags in Recipes and Advancements ==
Tags are directly supported by Vanilla, see the respective Vanilla wiki pages for [https://minecraft.gamepedia.com/Recipe#JSON_format recipes] and [https://minecraft.gamepedia.com/Advancements advancements] for usage details.

== Conventions ==

There are several conventions that will help facilitate compatibility in the ecosystem:
* If there is a Vanilla tag that fits your block or item, add it to that tag. See the [https://minecraft.gamepedia.com/Tag#List_of_tags list of Vanilla tags].
* If there is a Forge tag that fits your block or item, add it to that tag. The list of tags declared by Forge can be seen on [https://github.com/MinecraftForge/MinecraftForge/tree/1.18.x/src/generated/resources/data/forge/tags GitHub].
* If there is a group of something you feel should be shared by the community, consider PR-ing it to Forge instead of making your own tag
* Tag naming conventions should follow Vanilla conventions. In particular, item and block groupings are plural instead of singular. E.g. <code><nowiki>minecraft:logs</nowiki></code>, <code><nowiki>minecraft:saplings</nowiki></code>.
* Item tags should be sorted into subdirectories according to the type of item, e.g. <code><nowiki>forge:ingots/iron</nowiki></code>, <code><nowiki>forge:nuggets/brass</nowiki></code>, etc.

=== Forge Tags ===

This is a list of all [https://github.com/MinecraftForge/MinecraftForge/tree/1.18.x/src/generated/resources/data/forge/tags tags] using the <code>forge</code> namespace that are currently defined by Forge along those that are commonly used by other mods. These can all be found within the [https://github.com/MinecraftForge/MinecraftForge/blob/1.18.x/src/main/java/net/minecraftforge/common/Tags.java <code>Tags</code>] class.

{{Tip/Important|Tags that are not officially defined within the Forge codebase will have <code>*</code> as a suffix. To use those outside the Forge codebase, an <code>IOptionalNamedTag</code> must be created using <code>*Tags#createOptional</code> where the asterisk can be replaced by its associated class name.}}

==== Blocks ====

{| class="wikitable"
|-
! Name !! Super Tag(s) !! Contains
|-
| <code>forge:barrels</code> || None || Barrels
|-
| <code>forge:barrels/wooden</code> || <code>forge:barrels</code> || Wooden barrels
|-
| <code>forge:chests</code> || None || Chests
|-
| <code>forge:chests/ender</code> || <code>forge:chests</code> || Ender chests
|-
| <code>forge:chests/trapped</code> || <code>forge:chests</code> || Trapped chests
|-
| <code>forge:chests/wooden</code> || <code>forge:chests</code> || Wooden chests
|-
| <code>forge:cobblestone</code> || None || Cobblestones
|-
| <code>forge:cobblestone/normal</code> || <code>forge:cobblestone</code> || Normal cobblestones
|-
| <code>forge:cobblestone/infested</code> || <code>forge:cobblestone</code> || Infested cobblestones
|-
| <code>forge:cobblestone/mossy</code> || <code>forge:cobblestone</code> || Mossy cobblestones
|-
| <code>forge:cobblestone/deepslate</code> || <code>forge:cobblestone</code> || Deepslate cobblestones
|-
| <code>forge:end_stones</code> || None || End stones
|-
| <code>forge:enderman_place_on_blacklist</code> || None || Blocks that an enderman cannot place its held block on
|-
| <code>forge:fence_gates</code> || None || Fence gates
|-
| <code>forge:fence_gates/wooden</code> || <code>forge:fence_gates</code> || Wooden fence gates
|-
| <code>forge:fences</code> || None || Fences
|-
| <code>forge:fences/nether_brick</code> || <code>forge:fences</code> || Nether brick fences
|-
| <code>forge:fences/wooden</code> || <code>forge:fences</code> || Wooden fences
|-
| <code>forge:glass</code> || None || Glass
|-
| <code>forge:glass/black</code> || None || Black glass
|-
| <code>forge:glass/blue</code> || None || Blue glass
|-
| <code>forge:glass/brown</code> || None || Brown glass
|-
| <code>forge:glass/colorless</code> || <code>forge:glass</code> || Normal glass
|-
| <code>forge:glass/cyan</code> || None || Cyan glass
|-
| <code>forge:glass/gray</code> || None || Gray glass
|-
| <code>forge:glass/green</code> || None || Green glass
|-
| <code>forge:glass/light_blue</code> || None || Light blue glass
|-
| <code>forge:glass/light_gray</code> || None || Light gray glass
|-
| <code>forge:glass/lime</code> || None || Lime glass
|-
| <code>forge:glass/magenta</code> || None || Magenta glass
|-
| <code>forge:glass/orange</code> || None || Orange glass
|-
| <code>forge:glass/pink</code> || None || Pink glass
|-
| <code>forge:glass/purple</code> || None || Purple glass
|-
| <code>forge:glass/red</code> || None || Red glass
|-
| <code>forge:glass/silica</code> || None || Sand-based glass with minor ingredient variation
|-
| <code>forge:glass/tinted</code> || <code>forge:glass</code> || Tinted glass
|-
| <code>forge:glass/white</code> || None || White glass
|-
| <code>forge:glass/yellow</code> || None || Yellow glass
|-
| <code>forge:glass_panes</code> || None || Glass panes
|-
| <code>forge:glass_panes/black</code> || None || Black glass panes
|-
| <code>forge:glass_panes/blue</code> || None || Blue glass panes
|-
| <code>forge:glass_panes/brown</code> || None || Brown glass panes
|-
| <code>forge:glass_panes/colorless</code> || <code>forge:glass_panes</code> || Normal glass panes
|-
| <code>forge:glass_panes/cyan</code> || None || Cyan glass panes
|-
| <code>forge:glass_panes/gray</code> || None || Gray glass panes
|-
| <code>forge:glass_panes/green</code> || None || Green glass panes
|-
| <code>forge:glass_panes/light_blue</code> || None || Light blue glass panes
|-
| <code>forge:glass_panes/light_gray</code> || None || Light gray glass panes
|-
| <code>forge:glass_panes/lime</code> || None || Lime glass panes
|-
| <code>forge:glass_panes/magenta</code> || None || Magenta glass panes
|-
| <code>forge:glass_panes/orange</code> || None || Orange glass panes
|-
| <code>forge:glass_panes/pink</code> || None || Pink glass panes
|-
| <code>forge:glass_panes/purple</code> || None || Purple glass panes
|-
| <code>forge:glass_panes/red</code> || None || Red glass panes
|-
| <code>forge:glass_panes/white</code> || None || White glass panes
|-
| <code>forge:glass_panes/yellow</code> || None || Yellow glass panes
|-
| <code>forge:gravel</code> || None || Gravel
|-
| <code>forge:netherrack</code> || None || Netherrack
|-
| <code>forge:obsidian</code> || None || Obsidian
|-
| <code>forge:ore_bearing_ground/deepslate</code> || None || Blocks replaced by deepslate ores during world generation
|-
| <code>forge:ore_bearing_ground/netherrack</code> || None || Blocks replaced by netherrack ores during world generation
|-
| <code>forge:ore_bearing_ground/stone</code> || None || Blocks replaced by stone ores during world generation
|-
| <code>forge:ore_rates/dense</code> || None || Ores which produce numerous resources on average
|-
| <code>forge:ore_rates/singular</code> || None || Ores which produce a single resource on average
|-
| <code>forge:ore_rates/sparse</code> || None || Ores which produce less than a single resource on average
|-
| <code>forge:ores</code> || None || Ores
|-
| <code>forge:ores/coal</code> || <code>forge:ores</code> || Coal ores
|-
| <code>forge:ores/copper</code> || <code>forge:ores</code> || Copper ores
|-
| <code>forge:ores/diamond</code> || <code>forge:ores</code> || Diamond ores
|-
| <code>forge:ores/emerald</code> || <code>forge:ores</code> || Emerald ores
|-
| <code>forge:ores/gold</code> || <code>forge:ores</code> || Gold ores
|-
| <code>forge:ores/lapis</code> || <code>forge:ores</code> || Lapis ores
|-
| <code>forge:ores/netherite_scrap</code> || <code>forge:ores</code> || Netherite scrap ores
|-
| <code>forge:ores/quartz</code> || <code>forge:ores</code> || Quartz ores
|-
| <code>forge:ores/redstone</code> || <code>forge:ores</code> || Redstone ores
|-
| <code>forge:ores_in_ground/deepslate</code> || None || Ores which can be found in deepslate
|-
| <code>forge:ores_in_ground/netherrack</code> || None || Ores which can be found in netherrack
|-
| <code>forge:ores_in_ground/stone</code> || None || Ores which can be found in stone
|-
| <code>forge:sand</code> || None || Sand
|-
| <code>forge:sand/colorless</code> || <code>forge:sand</code> || Normal sand
|-
| <code>forge:sand/red</code> || <code>forge:sand</code> || Red sand
|-
| <code>forge:sandstone</code> || None || Sandstone
|-
| <code>forge:stained_glass</code> || <code>forge:glass</code> || Stained glass
|-
| <code>forge:stained_glass_panes</code> || <code>forge:glass_panes</code> || Stained glass planes
|-
| <code>forge:stone</code> || None || Stones
|-
| <code>forge:storage_blocks</code> || None || Storage blocks
|-
| <code>forge:storage_blocks/amethyst</code> || <code>forge:storage_blocks</code> || Amethyst blocks
|-
| <code>forge:storage_blocks/coal</code> || <code>forge:storage_blocks</code> || Coal blocks
|-
| <code>forge:storage_blocks/copper</code> || <code>forge:storage_blocks</code> || Copper blocks
|-
| <code>forge:storage_blocks/diamond</code> || <code>forge:storage_blocks</code> || Diamond blocks
|-
| <code>forge:storage_blocks/emerald</code> || <code>forge:storage_blocks</code> || Emerald blocks
|-
| <code>forge:storage_blocks/gold</code> || <code>forge:storage_blocks</code> || Gold blocks
|-
| <code>forge:storage_blocks/iron</code> || <code>forge:storage_blocks</code> || Iron blocks
|-
| <code>forge:storage_blocks/lapis</code> || <code>forge:storage_blocks</code> || Lapis blocks
|-
| <code>forge:storage_blocks/netherite</code> || <code>forge:storage_blocks</code> || Netherite blocks
|-
| <code>forge:storage_blocks/quartz</code> || <code>forge:storage_blocks</code> || Quartz blocks
|-
| <code>forge:storage_blocks/raw_copper</code> || <code>forge:storage_blocks</code> || Raw copper blocks
|-
| <code>forge:storage_blocks/raw_gold</code> || <code>forge:storage_blocks</code> || Raw gold blocks
|-
| <code>forge:storage_blocks/raw_iron</code> || <code>forge:storage_blocks</code> || Raw iron blocks
|-
| <code>forge:storage_blocks/redstone</code> || <code>forge:storage_blocks</code> || Redstone blocks
|-
| <code>forge:needs_wood_tool</code> || None || Blocks which need a wooden tool to be mined efficiently
|-
| <code>forge:needs_gold_tool</code> || None || Blocks which need a gold tool to be mined efficiently
|-
| <code>forge:needs_netherite_tool</code> || None || Blocks which need a netherite tool to be mined efficiently
|}

==== Items ====

{| class="wikitable"
|-
! Name !! Super Tag(s) !! Contains
|-
| <code>forge:barrels</code> || None || Barrels
|-
| <code>forge:barrels/wooden</code> || <code>forge:barrels</code> || Wooden barrels
|-
| <code>forge:bones</code> || None || Bones
|-
| <code>forge:bookshelves</code> || None || Bookshelves
|-
| <code>forge:chests</code> || None || Chests
|-
| <code>forge:chests/ender</code> || <code>forge:chests</code> || Ender chests
|-
| <code>forge:chests/trapped</code> || <code>forge:chests</code> || Trapped chests
|-
| <code>forge:chests/wooden</code> || <code>forge:chests</code> || Wooden chests
|-
| <code>forge:cobblestone</code> || None || Cobblestones
|-
| <code>forge:cobblestone/normal</code> || <code>forge:cobblestone</code> || Normal cobblestones
|-
| <code>forge:cobblestone/infested</code> || <code>forge:cobblestone</code> || Infested cobblestones
|-
| <code>forge:cobblestone/mossy</code> || <code>forge:cobblestone</code> || Mossy cobblestones
|-
| <code>forge:cobblestone/deepslate</code> || <code>forge:cobblestone</code> || Deepslate cobblestones
|-
| <code>forge:crops</code> || None || Crops
|-
| <code>forge:crops/beetroot</code> || <code>forge:crops</code> || Beetroot crops
|-
| <code>forge:crops/carrot</code> || <code>forge:crops</code> || Carrot crops
|-
| <code>forge:crops/nether_wart</code> || <code>forge:crops</code> || Nether wart crops
|-
| <code>forge:crops/potato</code> || <code>forge:crops</code> || Potato crops
|-
| <code>forge:crops/wheat</code> || <code>forge:crops</code> || Wheat crops
|-
| <code>forge:dusts</code> || None || Dusts
|-
| <code>forge:dusts/prismarine</code> || <code>forge:dusts</code> || Prismarine dusts
|-
| <code>forge:dusts/redstone</code> || <code>forge:dusts</code> || Redstone dusts
|-
| <code>forge:dusts/glowstone</code> || <code>forge:dusts</code> || Glowstone dusts
|-
| <code>forge:dyes</code> || None || Dyes
|-
| <code>forge:dyes/black</code> || <code>forge:dyes</code> || Black dyes
|-
| <code>forge:dyes/blue</code> || <code>forge:dyes</code> || Blue dyes
|-
| <code>forge:dyes/brown</code> || <code>forge:dyes</code> || Brown dyes
|-
| <code>forge:dyes/cyan</code> || <code>forge:dyes</code> || Cyan dyes
|-
| <code>forge:dyes/gray</code> || <code>forge:dyes</code> || Gray dyes
|-
| <code>forge:dyes/green</code> || <code>forge:dyes</code> || Green dyes
|-
| <code>forge:dyes/light_blue</code> || <code>forge:dyes</code> || Light blue dyes
|-
| <code>forge:dyes/light_gray</code> || <code>forge:dyes</code> || Light green dyes
|-
| <code>forge:dyes/lime</code> || <code>forge:dyes</code> || Lime dyes
|-
| <code>forge:dyes/magenta</code> || <code>forge:dyes</code> || Magenta dyes
|-
| <code>forge:dyes/orange</code> || <code>forge:dyes</code> || Orange dyes
|-
| <code>forge:dyes/pink</code> || <code>forge:dyes</code> || Pink dyes
|-
| <code>forge:dyes/purple</code> || <code>forge:dyes</code> || Purple dyes
|-
| <code>forge:dyes/red</code> || <code>forge:dyes</code> || Red dyes
|-
| <code>forge:dyes/white</code> || <code>forge:dyes</code> || White dyes
|-
| <code>forge:dyes/yellow</code> || <code>forge:dyes</code> || Yellow dyes
|-
| <code>forge:eggs</code> || None || Eggs
|-
| <code>forge:enchanting_fuels</code> || None || Enchantment table fuels
|-
| <code>forge:end_stones</code> || None || End stones
|-
| <code>forge:ender_pearls</code> || None || Ender pearls
|-
| <code>forge:feathers</code> || None || Feathers
|-
| <code>forge:fence_gates</code> || None || Fence gates
|-
| <code>forge:fence_gates/wooden</code> || <code>forge:fence_gates</code> || Wooden fence gates
|-
| <code>forge:fences</code> || None || Fences
|-
| <code>forge:fences/nether_brick</code> || <code>forge:fences</code> || Nether brick fences
|-
| <code>forge:fences/wooden</code> || <code>forge:fences</code> || Wooden fences
|-
| <code>forge:gems</code> || None || Gems
|-
| <code>forge:gems/amethyst</code> || <code>forge:gems</code> || Amethyst gems
|-
| <code>forge:gems/diamond</code> || <code>forge:gems</code> || Diamond gems
|-
| <code>forge:gems/emerald</code> || <code>forge:gems</code> || Emerald gems
|-
| <code>forge:gems/lapis</code> || <code>forge:gems</code> <code>forge:enchanting_fuels</code> || Lapis gems
|-
| <code>forge:gems/prismarine</code> || <code>forge:gems</code> || Prismarine gems
|-
| <code>forge:gems/quartz</code> || <code>forge:gems</code> || Quartz gems
|-
| <code>forge:glass</code> || None || Glass
|-
| <code>forge:glass/black</code> || None || Black glass
|-
| <code>forge:glass/blue</code> || None || Blue glass
|-
| <code>forge:glass/brown</code> || None || Brown glass
|-
| <code>forge:glass/colorless</code> || <code>forge:glass</code> || Normal glass
|-
| <code>forge:glass/cyan</code> || None || Cyan glass
|-
| <code>forge:glass/gray</code> || None || Gray glass
|-
| <code>forge:glass/green</code> || None || Green glass
|-
| <code>forge:glass/light_blue</code> || None || Light blue glass
|-
| <code>forge:glass/light_gray</code> || None || Light gray glass
|-
| <code>forge:glass/lime</code> || None || Lime glass
|-
| <code>forge:glass/magenta</code> || None || Magenta glass
|-
| <code>forge:glass/orange</code> || None || Orange glass
|-
| <code>forge:glass/pink</code> || None || Pink glass
|-
| <code>forge:glass/purple</code> || None || Purple glass
|-
| <code>forge:glass/red</code> || None || Red glass
|-
| <code>forge:glass/silica</code> || None || Sand-based glass with minor ingredient variation
|-
| <code>forge:glass/tinted</code> || <code>forge:glass</code> || Tinted glass
|-
| <code>forge:glass/white</code> || None || White glass
|-
| <code>forge:glass/yellow</code> || None || Yellow glass
|-
| <code>forge:glass_panes</code> || None || Glass panes
|-
| <code>forge:glass_panes/black</code> || None || Black glass panes
|-
| <code>forge:glass_panes/blue</code> || None || Blue glass panes
|-
| <code>forge:glass_panes/brown</code> || None || Brown glass panes
|-
| <code>forge:glass_panes/colorless</code> || <code>forge:glass_panes</code> || Normal glass panes
|-
| <code>forge:glass_panes/cyan</code> || None || Cyan glass panes
|-
| <code>forge:glass_panes/gray</code> || None || Gray glass panes
|-
| <code>forge:glass_panes/green</code> || None || Green glass panes
|-
| <code>forge:glass_panes/light_blue</code> || None || Light blue glass panes
|-
| <code>forge:glass_panes/light_gray</code> || None || Light gray glass panes
|-
| <code>forge:glass_panes/lime</code> || None || Lime glass panes
|-
| <code>forge:glass_panes/magenta</code> || None || Magenta glass panes
|-
| <code>forge:glass_panes/orange</code> || None || Orange glass panes
|-
| <code>forge:glass_panes/pink</code> || None || Pink glass panes
|-
| <code>forge:glass_panes/purple</code> || None || Purple glass panes
|-
| <code>forge:glass_panes/red</code> || None || Red glass panes
|-
| <code>forge:glass_panes/white</code> || None || White glass panes
|-
| <code>forge:glass_panes/yellow</code> || None || Yellow glass panes
|-
| <code>forge:gravel</code> || None || Gravel
|-
| <code>forge:gunpowder</code> || None || Gunpowder
|-
| <code>forge:heads</code> || None || Heads
|-
| <code>forge:ingots</code> || None || Ingots
|-
| <code>forge:ingots/brick</code> || <code>forge:ingots</code> || Brick ingots
|-
| <code>forge:ingots/copper</code> || <code>forge:ingots</code> || Copper ingots
|-
| <code>forge:ingots/gold</code> || <code>forge:ingots</code> || Gold ingots
|-
| <code>forge:ingots/iron</code> || <code>forge:ingots</code> || Iron ingots
|-
| <code>forge:ingots/netherite</code> || <code>forge:ingots</code> || Netherite ingots
|-
| <code>forge:ingots/nether_brick</code> || <code>forge:ingots</code> || Nether brick ingots
|-
| <code>forge:leather</code> || None || Leather
|-
| <code>forge:mushrooms</code> || None || Mushrooms
|-
| <code>forge:nether_stars</code> || None || Nether stars
|-
| <code>forge:netherrack</code> || None || Netherrack
|-
| <code>forge:nuggets</code> || None || Nuggets
|-
| <code>forge:nuggets/gold</code> || <code>forge:nuggets</code> || Gold nuggets
|-
| <code>forge:nuggets/iron</code> || <code>forge:nuggets</code> || Iron nuggets
|-
| <code>forge:obsidian</code> || None || Obsidian
|-
| <code>forge:ore_bearing_ground/deepslate</code> || None || Blocks replaced by deepslate ores during world generation
|-
| <code>forge:ore_bearing_ground/netherrack</code> || None || Blocks replaced by netherrack ores during world generation
|-
| <code>forge:ore_bearing_ground/stone</code> || None || Blocks replaced by stone ores during world generation
|-
| <code>forge:ore_rates/dense</code> || None || Ores which produce numerous resources on average
|-
| <code>forge:ore_rates/singular</code> || None || Ores which produce a single resource on average
|-
| <code>forge:ore_rates/sparse</code> || None || Ores which produce less than a single resource on average
|-
| <code>forge:ores</code> || None || Ores
|-
| <code>forge:ores/coal</code> || <code>forge:ores</code> || Coal ores
|-
| <code>forge:ores/copper</code> || <code>forge:ores</code> || Copper ores
|-
| <code>forge:ores/diamond</code> || <code>forge:ores</code> || Diamond ores
|-
| <code>forge:ores/emerald</code> || <code>forge:ores</code> || Emerald ores
|-
| <code>forge:ores/gold</code> || <code>forge:ores</code> || Gold ores
|-
| <code>forge:ores/lapis</code> || <code>forge:ores</code> || Lapis ores
|-
| <code>forge:ores/netherite_scrap</code> || <code>forge:ores</code> || Netherite scrap ores
|-
| <code>forge:ores/quartz</code> || <code>forge:ores</code> || Quartz ores
|-
| <code>forge:ores/redstone</code> || <code>forge:ores</code> || Redstone ores
|-
| <code>forge:ores_in_ground/deepslate</code> || None || Ores which can be found in deepslate
|-
| <code>forge:ores_in_ground/netherrack</code> || None || Ores which can be found in netherrack
|-
| <code>forge:ores_in_ground/stone</code> || None || Ores which can be found in stone
|-
| <code>forge:raw_materials</code> || None || Raw materials
|-
| <code>forge:raw_materials/copper</code> || <code>forge:raw_materials</code> || Copper raw materials
|-
| <code>forge:raw_materials/gold</code> || <code>forge:raw_materials</code> || Gold raw materials
|-
| <code>forge:raw_materials/iron</code> || <code>forge:raw_materials</code> || Iron raw materials
|-
| <code>forge:rods</code> || None || Rods
|-
| <code>forge:rods/blaze</code> || <code>forge:rods</code> || Blaze rods
|-
| <code>forge:rods/wooden</code> || <code>forge:rods</code> || Wooden rods
|-
| <code>forge:sand</code> || None || Sand
|-
| <code>forge:sand/colorless</code> || <code>forge:sand</code> || Normal sand
|-
| <code>forge:sand/red</code> || <code>forge:sand</code> || Red sand
|-
| <code>forge:sandstone</code> || None || Sandstone
|-
| <code>forge:seeds</code> || None || Seeds
|-
| <code>forge:seeds/beetroot</code> || <code>forge:seeds</code> || Beetroot seeds
|-
| <code>forge:seeds/melon</code> || <code>forge:seeds</code> || Melon seeds
|-
| <code>forge:seeds/pumpkin</code> || <code>forge:seeds</code> || Pumpkin seeds
|-
| <code>forge:seeds/wheat</code> || <code>forge:seeds</code> || Wheat seeds
|-
| <code>forge:shears</code> || None || Shears
|-
| <code>forge:slimeballs</code> || None || Slimeballs
|-
| <code>forge:stained_glass</code> || <code>forge:glass</code> || Stained glass
|-
| <code>forge:stained_glass_panes</code> || <code>forge:glass_panes</code> || Stained glass planes
|-
| <code>forge:stone</code> || None || Stones
|-
| <code>forge:storage_blocks</code> || None || Storage blocks
|-
| <code>forge:storage_blocks/amethyst</code> || <code>forge:storage_blocks</code> || Amethyst blocks
|-
| <code>forge:storage_blocks/coal</code> || <code>forge:storage_blocks</code> || Coal blocks
|-
| <code>forge:storage_blocks/copper</code> || <code>forge:storage_blocks</code> || Copper blocks
|-
| <code>forge:storage_blocks/diamond</code> || <code>forge:storage_blocks</code> || Diamond blocks
|-
| <code>forge:storage_blocks/emerald</code> || <code>forge:storage_blocks</code> || Emerald blocks
|-
| <code>forge:storage_blocks/gold</code> || <code>forge:storage_blocks</code> || Gold blocks
|-
| <code>forge:storage_blocks/iron</code> || <code>forge:storage_blocks</code> || Iron blocks
|-
| <code>forge:storage_blocks/lapis</code> || <code>forge:storage_blocks</code> || Lapis blocks
|-
| <code>forge:storage_blocks/netherite</code> || <code>forge:storage_blocks</code> || Netherite blocks
|-
| <code>forge:storage_blocks/quartz</code> || <code>forge:storage_blocks</code> || Quartz blocks
|-
| <code>forge:storage_blocks/raw_copper</code> || <code>forge:storage_blocks</code> || Raw copper blocks
|-
| <code>forge:storage_blocks/raw_gold</code> || <code>forge:storage_blocks</code> || Raw gold blocks
|-
| <code>forge:storage_blocks/raw_iron</code> || <code>forge:storage_blocks</code> || Raw iron blocks
|-
| <code>forge:storage_blocks/redstone</code> || <code>forge:storage_blocks</code> || Redstone blocks
|-
| <code>forge:string</code> || None || String
|}

==== Fluids ====

{| class="wikitable"
|-
! Name !! Super Tag(s) !! Contains
|-
| <code>forge:milk</code> || None || Milk
|}

[[Category:Resources and Data/1.18|Category:Resources and Data]]

Structures/1.18

2022-06-10T07:45:57Z

ShrimpBot: Copy Structures to MC1.18 archive

https://github.com/TelepathicGrunt/StructureTutorialMod

Stages of Modloading/1.18

2022-06-10T07:45:55Z

ShrimpBot: Copy Stages of Modloading to MC1.18 archive

The FML mod loading process is broken into several stages, with each stage having associated events fired alongside with it on the mod-specific event bus. These events are known as the <code>mod lifecycle events</code>, as they are fired during the different phases of a mod's life.

The different mod loading stages are represented each by a value in the enum class <code><nowiki>net.minecraftforge.fml.ModLoadingStage</nowiki></code>. Their states are split between the <code><nowiki>net.minecraftforge.fml.core.ModStateProvider</nowiki></code> for mod states (construct, common setup, etc.) and <code><nowiki>net.minecraftforge.fmllegacy.ForgeStatesProvider</nowiki></code> for forge injected states (creating registries, injecting capabilities, etc.) Most of the mod lifecycle events are stored in the <code><nowiki>net.minecraftforge.fml.event.lifecycle</nowiki></code> package.

== Parallelism ==

The mod loading system is parallelized to some extent. While all of the stages are changed at the same time across all mods, most of the events are fired in parallel to each mod. That is, all mods will concurrently receive the event, then FML will wait until all mods have processed the event before moving to the next stage and firing the next event. These concurrently dispatched events are distinguished by them extending <code><nowiki>ParallelDispatchEvent</nowiki></code>.

This does means that in these parallel mod lifecycle events, care must be taken to be thread-safe, like when calling external methods which are backed by non-thread-safe collections. Most of the systems in Forge are protected for this; however, vanilla systems and external mods' APIs may not be thread-safe. FML provides a way for mods to defer tasks/work until the event is finished dispatching, where it will be run sequentially along with other events on the main thread. This is done with the <code><nowiki>#enqueueWork</nowiki></code> method, which is a member of all events which extend <code><nowiki>ParallelDispatchEvent</nowiki></code>.

== Common Transition Stages and Events ==

{| class="wikitable sortable" border=1
! Name !! Enum Constant !! Lifecycle Event !! Parallel? !! Description
|-
| Construction || <code><nowiki>CONSTRUCT</nowiki></code> || <code><nowiki>FMLConstructModEvent</nowiki></code> || Yes || Fired when the mod's constructor has been called. Can be used to initialize listeners outside of the constructor. There is usually no reason to use this event, as any code should be placed in the mod constructor instead.
|-
| Registry Creation || <code><nowiki>CREATE_REGISTRIES</nowiki></code> || <code><nowiki>RegistryEvent.NewRegistry</nowiki></code> || No || Fired for mods to create and initialize their custom registries.
|-
| Registry Population || <code><nowiki>LOAD_REGISTRIES</nowiki></code> || <code><nowiki>RegistryEvent.Register</nowiki></code> || No || Fired when a registry is open to registrations for any registrable objects, such as blocks, items, etc.
|-
| Config Loading || <code><nowiki>CONFIG_LOAD</nowiki></code> || (inlined in <code><nowiki>ModStateProvider</nowiki></code>) || ? || Loads config files associated with registered mod configs. Before this stage, mod config values only return their default values unless manually loaded earlier.
|-
| Common Setup || <code><nowiki>COMMON_SETUP</nowiki></code> || <code><nowiki>FMLCommonSetupEvent</nowiki></code> || Yes || Used for doing any work or action that should be run on both '''physical''' sides.
|-
| Sided Setup || <code><nowiki>SIDED_SETUP</nowiki></code> || <code><nowiki>FMLClientSetupEvent</nowiki></code> for physical client, <code><nowiki>FMLDedicatedServerSetupEvent</nowiki></code> for physical server || Yes || Used for doing any physical side-specific initialization work.
|-
| IMC Enqueue || <code><nowiki>ENQUEUE_IMC</nowiki></code> || <code><nowiki>InterModEnqueueEvent</nowiki></code> || Yes || Fired for mods to enqueue messages for other mods using the <code><nowiki>InterModComms</nowiki></code> system.
|-
| IMC Processing || <code><nowiki>PROCESS_IMC</nowiki></code> || <code><nowiki>InterModProcessEvent</nowiki></code> || Yes || Fired for mods to process messages from other mods sent using the <code><nowiki>InterModComms</nowiki></code> system in the previous stage.
|-
| Loading Complete || <code><nowiki>COMPLETE</nowiki></code> || <code><nowiki>FMLLoadCompleteEvent</nowiki></code> || Yes || Fired when mod loading is complete, before handing control back to the main game. There is usually no reason to use this event, as most actions can be done during the Common or Sided Setup stages.
|-
|}

Sounds/1.18

2022-06-10T07:45:53Z

ShrimpBot: Copy Sounds to MC1.18 archive

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

== Creating a Sound ==

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

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

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

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

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

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

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

}}

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

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

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

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

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

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

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

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

{{Tip/Warning|<code>SoundEvent</code>s must be [[Registration/1.16/1.18|registered]] on the <code>ModEventBus</code> to properly reference a sound on a server. However, <code>SoundEvent</code>s or referencing a sound by name will still work on the client when the sound is not registered as long as the sound exists in <code>sounds.json</code>!}}

== Playing Sounds ==

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

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

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

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

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

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

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

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

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

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

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

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

SimpleChannel/1.18

2022-06-10T07:45:51Z

ShrimpBot: Copy SimpleChannel to MC1.18 archive

SimpleChannel is the name given to the packet system that revolves around the <code><nowiki>SimpleChannel</nowiki></code> class. Using this system is by far the easiest way to send custom data between clients and the server.

== Getting Started ==

First you need to create your <code><nowiki>SimpleChannel</nowiki></code> object. We recommend that you do this in a separate class, possibly something like <code><nowiki>ModidPacketHandler</nowiki></code>. Create your <code><nowiki>SimpleChannel</nowiki></code> as a static field in this class, like so:

<syntaxhighlight lang="java">
private static final String PROTOCOL_VERSION = "1";
public static final SimpleChannel INSTANCE = NetworkRegistry.newSimpleChannel(
new ResourceLocation("mymodid", "main"),
() -> PROTOCOL_VERSION,
PROTOCOL_VERSION::equals,
PROTOCOL_VERSION::equals
);
</syntaxhighlight>

The first argument is a name for the channel. The second argument is a <code><nowiki>Supplier<String></nowiki></code> returning the current network protocol version. The third and fourth arguments respectively are <code><nowiki>Predicate<String></nowiki></code> checking whether an incoming connection protocol version is network-compatible with the client or server, respectively.
Here, we simply compare with the <code><nowiki>PROTOCOL_VERSION</nowiki></code> field directly, meaning that the client and server <code><nowiki>PROTOCOL_VERSION</nowiki></code>s must always match or FML will deny login.

== Protocol Versions ==
If your mod does not require the other side to have a specific network channel, or to be a Forge instance at all, you should take care that you properly define your version compatibility checkers (the <code><nowiki>Predicate<String></nowiki></code> parameters) to handle additional "meta-versions" (defined in <code><nowiki>NetworkRegistry</nowiki></code>) that can be received by the version checker. These are:
* <code><nowiki>ABSENT</nowiki></code> - if this channel is missing on the other endpoint. Note that in this case, the endpoint is still a Forge endpoint, and may have other mods.
* <code><nowiki>ACCEPTVANILLA</nowiki></code> - if the endpoint is a vanilla (or non-Forge) endpoint.

Returning <code><nowiki>false</nowiki></code> for both means that this channel must be present on the other endpoint. If you just copy the code above, this is what it does. Note that these values are also used during the list ping compatibility check, which is responsible for showing the green check / red cross in the multiplayer server select screen.

== Registering Packets ==

Next, we must declare the types of messages that we would like to send and receive. This is done using the <code><nowiki>INSTANCE.registerMessage</nowiki></code> method, which takes 5 parameters.

* The first parameter is the discriminator for the packet. This is a per-channel unique ID for the packet. We recommend you use a local variable to hold the ID, and then call registerMessage using <code><nowiki>id++</nowiki></code>. This will guarantee 100% unique IDs.
* The second parameter is the actual packet class <code><nowiki>MSG</nowiki></code>.
* The third parameter is a <code><nowiki>BiConsumer<MSG, FriendlyByteBuf></nowiki></code> responsible for encoding the message into the provided <code><nowiki>FriendlyByteBuf</nowiki></code>
* The fourth parameter is a <code><nowiki>Function<FriendlyByteBuf, MSG></nowiki></code> responsible for decoding the message from the provided <code><nowiki>FriendlyByteBuf</nowiki></code>
* The final parameter is a <code><nowiki>BiConsumer<MSG, Supplier<NetworkEvent.Context>></nowiki></code> responsible for handling the message itself

The last three parameters can be method references to either static or instance methods in Java. Remember that an instance method <code><nowiki>MSG.encode(FriendlyByteBuf)</nowiki></code> still satisfies <code><nowiki>BiConsumer<MSG, FriendlyByteBuf></nowiki></code>, the <code><nowiki>MSG</nowiki></code> simply becomes the implicit first argument.

<syntaxhighlight lang="java">
// A class MessagePacket
public void encoder(FriendlyByteBuf buffer) {
// Write to buffer
}

public static MessagePacket decoder(FriendlyByteBuf buffer) {
// Create packet from buffer data
}

public void messageConsumer(Supplier<NetworkEvent.Context>> ctx) {
// Handle message
}

// For some SimpleChannel channel
channel.registerMessage(id, MessagePacket::encoder, MessagePacket::decoder, MessagePacket::messageConsumer);
</syntaxhighlight>

== Handling Packets ==

There are a couple things to highlight in a packet handler. A packet handler has both the message object and the network context available to it. The context allows access to the player that sent the packet (if on the server), and a way to enqueue threadsafe work.

<syntaxhighlight lang="java">
public static void handle(MyMessage msg, Supplier<NetworkEvent.Context> ctx) {
ctx.get().enqueueWork(() -> {
// Work that needs to be threadsafe (most work)
ServerPlayer sender = ctx.get().getSender(); // the client that sent this packet
// do stuff
});
ctx.get().setPacketHandled(true);
}
</syntaxhighlight>

Packets sent from the server to the client should be handled in another class and wrapped via <code>DistExecutor#unsafeRunWhenOn</code>.

<syntaxhighlight lang="java">
// In Packet class
public static void handle(MyClientMessage msg, Supplier<NetworkEvent.Context> ctx) {
ctx.get().enqueueWork(() ->
// Make sure it's only executed on the physical client
DistExecutor.unsafeRunWhenOn(Dist.CLIENT, () -> () -> ClientPacketHandlerClass.handlePacket(msg, ctx))
);
ctx.get().setPacketHandled(true);
}

// In ClientPacketHandlerClass
public static void handlePacket(MyClientMessage msg, Supplier<NetworkEvent.Context> ctx) {
// Do stuff
}
</syntaxhighlight>

Note the presence of <code><nowiki>#setPacketHandled</nowiki></code>, which used to tell the network system that the packet has successfully completed handling.

=== Common Packet Handling Pitfalls ===

{{Colored box|title=Know that packets are by default handled on the network thread.|content=
That means that your handler can ''not'' interact with most game objects directly.
Forge provides a convenient way to make your code execute on the main thread through the supplied <code><nowiki>NetworkEvent$Context</nowiki></code>.
Simply call <code><nowiki>NetworkEvent$Context#enqueueWork(Runnable)</nowiki></code>, which will call the given <code><nowiki>Runnable</nowiki></code> on the main thread at the next opportunity.}}

{{Colored box|title=Be defensive when handling packets on the server.|content=
A client could attempt to exploit the packet handling by sending unexpected data.
<br>
A common problem is vulnerability to <code>arbitrary chunk generation</code>. This typically happens when the server is trusting a block position sent by a client to access blocks and block entities. When accessing blocks and block entities in unloaded areas of the level, the server will either generate or load this area from disk, then promply write it to disk. This can be exploited to cause <code>catastrophic damage</code> to a server's performance and storage space without leaving a trace.
<br>
To avoid this problem, a general rule of thumb is to only access blocks and block entities if <code><nowiki>Level#hasChunkAt</nowiki></code> is true.}}

{{Colored box|title=Register encoders on the physical client, as well as the physical server.|content=
If you only register an encoder for a clientbound packet on the physical server, your mod will likely crash or present unintended behaviour in single-player worlds. ''Forge will happily send packets that have no encoder defined, '''without a warning or error message!''''' They will be encoded as a 256-long byte buffer filled only with null bytes, by default.
<br>}}

== Sending Packets ==

=== Sending to the Server ===

There is but one way to send a packet to the server. This is because there is only ever *one* server the client can be connected to at once. To do so, we must again use that <code><nowiki>SimpleChannel</nowiki></code> that was defined earlier. Simply call <code><nowiki>INSTANCE.sendToServer(new MyMessage())</nowiki></code>. The message will be sent to the handler for its type, if one exists.

=== Sending to Clients ===

Packets can be sent directly to a client using the <code><nowiki>SimpleChannel</nowiki></code>: <code><nowiki>HANDLER.sendTo(MSG, serverPlayer.connection.getConnection(), NetworkDirection.PLAY_TO_CLIENT)</nowiki></code>. However, this can be quite inconvenient. Forge has some convenience functions that can be used:

<syntaxhighlight lang="java">
// Sending to one player
INSTANCE.send(PacketDistributor.PLAYER.with(serverPlayer), new MyMessage());

// Send to all players tracking this level chunk
INSTANCE.send(PacketDistributor.TRACKING_CHUNK.with(levelChunk), new MyMessage());

// Sending to all connected players
INSTANCE.send(PacketDistributor.ALL.noArg(), new MyMessage());
</syntaxhighlight>

There are additional <code><nowiki>PacketDistributor</nowiki></code> types available, check the documentation on the <code><nowiki>PacketDistributor</nowiki></code> class for more details.

Sides/1.18

2022-06-10T07:45:49Z

ShrimpBot: Copy Sides to MC1.18 archive

{{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/1.18|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/1.18|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/1.18|<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/1.18|Category:Common Concepts]]

Sending Packets/1.18

2022-06-10T07:45:47Z

ShrimpBot: Copy Sending Packets to MC1.18 archive

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

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

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

== Client Packet Locations ==

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

Here is a list of distributors available:

Semantic Versioning/1.18

2022-06-10T07:45:45Z

ShrimpBot: Copy Semantic Versioning to MC1.18 archive

[https://semver.org/ Semantic Versioning] is a versioning system where three variable are used to represent the version, in the format of <code>MAJOR.MINOR.PATCH</code>. However, in the case of modding, it may be beneficial to add additional variable such as the Minecraft version, to allow distinction between mods that work for which Minecraft versions.

{{Tip|The information presented here is purely informative. You are free to use any versioning system you wish.}}

When incrementing any variable, all lesser variables should reset to <code>0</code>. For instance, if <code>MINOR</code> would increment, <code>PATCH</code> would become <code>0</code>. If <code>MAJORMOD</code> would increment, all other variables would become <code>0</code>.

== Hybrid Versioning ==

A good hybrid of Semantic Versioning for Minecraft mods is the format: <code>MCVERSION-MAJORMOD.MAJORAPI.MINOR.PATCH</code>.

{|
! Variable !! Description
! When to Change
|-
| <code>MCVERSION</code> || The Minecraft version being targeted.
| The target Minecraft version is updated.
|-
| <code>MAJORMOD</code> || The major version of the mod.
| Exising mod objects - such as items, blocks, tile entities - are removed or fundamental mechanics are modified.
|-
| <code>MAJORAPI</code> || The major version of the mod's API.
| Any part of the mod's public-facing API is changed, such as reordered enums, method signature changes, or removal of public methods.
|-
| <code>MINOR</code> || The minor version of the mod.
| Mod objects or non-fundamental mechanics are added, or elements of the API are deprecated (but not removed).
|-
| <code>PATCH</code> || The patch version of the mod release.
| Bugs are fixed or the changes are unnoticable.
|}

== Classifiers ==

A classifer can be appended to the build version to denote it is a special build of some note. These classifiers are appended after the version variables are incremented and reset.

=== Pre-releases ===

It is also possible to pre-release work-in-progress features, which means new features are released that are not quite done yet. These can be seen as a sort of "beta". These versions should be appended with <code>-betaX</code>, where <code>X</code> is the number of the pre-release. Already released versions before the initial release can not go into pre-release; a variable must be incremented (e.g. the <code>MINOR</code> variable) and others updated before applying this classifier.

{{Tip/Important|This guide does not use the <code>-preX</code> classifier for pre-releases, because the library used to compare versions does not accept it as an alias for <code>-betaX</code>.}}

=== Release Candidates ===

If you are confident enough that a build is ready to be a release but a bit more testing is required, you may make it a ''release candidate''. These release candidates may receive the <code>-rcX</code> classifier, where <code>X</code> is the number of the release candidate, incremented for every new release candidate build. Already released versions before the initial release can not go into pre-release; a variable must be incremented (e.g. the <code>MINOR</code> variable) and others updated before applying this classifier.

The final released build will have the same version as the release candidate with the classifier omitted, and will usually be exactly the same or have a few unnoticable bugfixes included.

=== Final Release ===

When dropping support for a Minecraft version, the ''final build'' for that Minecraft version may receive the <code>-final</code> classifer. This denotes that the mod will no longer be supported for the denoted <code>MCVERSION</code> and players should upgrade their Minecraft version to continue receiving updates and fixes.

== During Development ==

If you are in the initial development stage of your mod (before any official releases), the <code>MAJORMOD</code> and <code>MAJORAPI</code> should be kept at <code>0</code>. Only <code>MINOR.PATCH</code> should be updated every time you build your mod. During this development stage, you are free to change or restructure your mod's API, objects, and mechanics as you wish without updating the major version variables. Once you build an official public release, you should increment the <code>MAJORMOD</code> version, reset the others to <code>0</code>, and follow your versioning strictly.

Saved Data/1.18

2022-06-10T07:45:44Z

ShrimpBot: Copy Saved Data to MC1.18 archive

<code>SavedData</code> is an alternative to capabilities that stores data per dimension or globally depending on how the context is passed.

==Class Structure==

The class can be broken down into two important methods:
- <code>save</code>: Write the data to nbt.
- <code>setDirty</code>: Tell the game that the data has changed and needs to be saved to file.

The <code>save</code> method need to be implemented while <code>setDirty</code> should be called whenever the data is going to be manipulated. As the class is abstract, it should be subclassed with these three methods implemented.

==Attaching to a Level ==

To attach a Saved Data to a particular level, you must have access to an instance of <code>ServerLevel</code> or <code>ServerChunkCache</code>. From there, you can call the method <code>#getSavedData</code> which will give you an instance of the <code>DimensionDataStorage</code>: the class that stores all saved data for that particular dimension. You can attach an instance or get the current instance of the data using <code>DimensionDataStorage#computeIfAbsent</code>. This takes in three arguments: the first to construct a saved data with data already existing in some <code>CompoundTag</code>, the second to construct a saved data with no existing data, and the third to specify the name of the file to save the data to within the <code>data</code> folder in the overworld or in the specific dimension of the save.

Global attachments are the same except that they should only be attached to the overworld as that level will always persist.

[[Category:Data Storage/1.18|Category:Data Storage]]

Saplings/1.18

2022-06-10T07:45:42Z

ShrimpBot: Copy Saplings to MC1.18 archive

Let's start with a basic example by extending SaplingBlock.First create a class that extends SaplingBlock.

<code>public class ExampleSapling extends SaplingBlock{}</code>

After that you can insert the constructor. It must call super with the Parameters :

{| class="wikitable" border=1
!Name !! Type !!Description
|-
| <code>treeIn</code> || <code>net.minecraft.block.trees.Tree</code> || <code>The Tree your Sapling is related to</code>
|-
| <code>properties</code> || <code>net.minecraft.block.AbstractBlock.Properties</code> || <code>The Block Properties of the Sapling</code>
|-
|}

That means we need to make a Tree for ourselves, but more on that in a bit.
If you want to have the Sapling be placeable on your own Mods Block, you need to override <code>isValidGround</code> and make your own additions to the vanilla provided Blocks. I recommend making a
<code>private static final List<Block> validBlocks = ImmutableList.of(Blocks block...)</code> to add Blocks to the List of possible Blocks.
If you have that, your function could look like :
<syntaxhighlight lang="java">
protected boolean isValidGround(@Nonnull BlockState state,@Nonnull IBlockReader worldIn,@Nonnull BlockPos pos) {
return validBlocks.stream().anyMatch(state::isIn) || super.isValidGround(state, worldIn, pos);
}
</syntaxhighlight>

Now onto making the Tree for your Sapling.

Start by making a <code>class</code> that extends <code>Tree</code> :

<code>public class ExampleTree extends Tree </code>
This <code>class</code> will only contain one <code>function</code> which is :
<code>protected ConfiguredFeature<BaseTreeFeatureConfig, ?> getTreeFeature(Random randomIn, boolean largeHive)</code>
As you can see, this function requires to return a ConfiguredFeature<BaseTreeFeatureConfig, ?>. This will be the Tree that is Placed in the World.
The <code>ConfiguredFeature<BaseTreeFeatureConfig, ?></code> will look sth like this :
<syntaxhighlight lang="java">
public static final ConfiguredFeature<BaseTreeFeatureConfig, ?> EXAMPLETREEFEATURE =
Feature.TREE.withConfiguration(
new BaseTreeFeatureConfig.Builder(
new SimpleBlockStateProvider(BlockInit.EXAMPLE_WOOD.get().getDefaultState()),
new SimpleBlockStateProvider(BlockInit.EXAMPLE_LEAVES.get().getDefaultState()),
new BlobFoliagePlacer(FeatureSpread.func_242252_a(2), FeatureSpread.func_242252_a(0), 3),
new StraightTrunkPlacer(4, 2, 0),
new TwoLayerFeature(1, 0, 1)
).setIgnoreVines().build());
</syntaxhighlight>
After we have our ExampleTree we need to register it. This is done via 2 functions :
<syntaxhighlight lang="java">
public static void registerTrees() {
register("example_tree", EXAMPLETREE);
}
</syntaxhighlight>
and also the function <code>register</code> :
<syntaxhighlight lang="java">
public void register(String key, ConfiguredFeature<FC, ?> configuredFeature){
Registry.register(WorldGenRegistries.CONFIGURED_FEATURE, key, configuredFeature);
}
</syntaxhighlight >

If you have everything setup, call registerTrees() in FMLCommonSetupEvent.<br>
Back to the Sapling. Your constructor can now be completed by putting the Tree we just registered as the first super parameter and the Properties as the second parameter :
<syntaxhighlight lang="java">
public ExampleSapling() {
super(new ExampleTree(), AbstractBlock.Properties.create(Material.PLANTS).doesNotBlockMovement().tickRandomly().zeroHardnessAndResistance().sound(SoundType.PLANT));
}
</syntaxhighlight >
Also in your ExampleTree class, instead of null, the function now should return your TreeFeature : <br>
<syntaxhighlight lang="java">
protected ConfiguredFeature<BaseTreeFeatureConfig, ?> getTreeFeature(@Nonnull Random randomIn, boolean largeHive) {
return EXAMPLETREEFEATURE;
}
</syntaxhighlight >
Now register the Sapling like any other Block and it should be able to be placed and grow with the correct Tree.

Resources/1.18

2022-06-10T07:45:40Z

ShrimpBot: Copy Resources to MC1.18 archive

A resource is extra data used by the game, and is stored in a data file, instead of being in the code. Minecraft has two primary resource systems active: one on the client used for visuals such as models, textures, and localization called <code><nowiki>assets</nowiki></code>, the other used for gameplay such as recipes and loot tables called <code><nowiki>data</nowiki></code>. Resource packs control the former, while data packs control the latter.

When multiple resource packs or data packs are enabled, they are merged. Generally, files from packs at the top of the stack override those below; however, for certain files, such as localization files and tags, data is actually merged contentwise. Mods actually define resource and data packs too, in their <code><nowiki>resources</nowiki></code> directories, but they are seen as subsets of the “Default” pack. Mod resource packs cannot be disabled, but they can be overridden by other resource packs. Mod datapacks can be disabled with the vanilla <code><nowiki>/datapack</nowiki></code> command.

All resources should have '''snake case''' paths and filenames (lowercase, using “_” for word boundaries).

== ResourceLocation ==

Minecraft identifies resources using <code><nowiki>ResourceLocation</nowiki></code>s. A <code><nowiki>ResourceLocation</nowiki></code> contains two parts: a namespace and a path. It generally points to the resource at <code><nowiki><assets|data>/<namespace>/<ctx>/<path></nowiki></code>, where <code><nowiki>ctx</nowiki></code> is a context-specific path fragment that depends on how the ResourceLocation is being used. When a <code><nowiki>ResourceLocation</nowiki></code> is written from/read as a string, it is seen as <code><nowiki><namespace>:<path></nowiki></code>. If the namespace and the colon are left out, then when the string is read into an ResourceLocation the namespace will almost always default to <code><nowiki>minecraft</nowiki></code>. A mod should put its resources into a namespace with the same name as its modid (E.g. a mod with id <code><nowiki>examplemod</nowiki></code> should place its resources in <code><nowiki><assets|data>/examplemod</nowiki></code>, and <code><nowiki>ResourceLocation</nowiki></code>s pointing to those files would look like <code><nowiki>examplemod:<path></nowiki></code>). This is not a requirement, and in some cases it can be desirable to use a different (or even more than one) namespace. <code><nowiki>ResourceLocation</nowiki></code>s are used outside the resource system, too, as they happen to be a great way to uniquely identify objects (e.g. [[Registration/1.18|registries]]).

== Important Directories ==

Minecraft expects certain parts of your project to be in certain locations, such as textures and JSONs.

All locations and items covered in this page are relative to your <code><nowiki>./src/main/resources/</nowiki></code> directory.

== General Files ==

=== mods.toml ===

The <code><nowiki>mods.toml</nowiki></code> file is in the <code><nowiki>./META-INF/</nowiki></code> directory. This holds the basic information relating to your mod.

=== pack.mcmeta ===

The <code><nowiki>pack.mcmeta</nowiki></code> file is in the current directory. This allows Minecraft to notice the assets provided by your mod.

== Assets ==

The <code><nowiki>./assets</nowiki></code> folder holds all client related files for a specific user. These files are only specific to the computer they're on.

=== Blockstates ===

Blockstate definition files are in the JSON format and are in the <code><nowiki>./assets/<modid>/blockstates/</nowiki></code> folder.

=== Localizations ===

Localizations are plain-text files with the file extension <code><nowiki>.json</nowiki></code> and the name being their [https://docs.microsoft.com/en-us/previous-versions/commerce-server/ee825488(v=cs.20)?redirectedfrom=MSDN language code] in lowercase such as <code><nowiki>en_us</nowiki></code>.

They are located in the <code><nowiki>./assets/<modid>/lang/</nowiki></code> folder.

=== Models ===

Model files are in JSON format and are located in <code><nowiki>./assets/<modid>/models/block/</nowiki></code> or <code><nowiki>./assets/<modid>/models/item/</nowiki></code> depending on whether they are for a block or an item, respectively.

=== Textures ===

Textures are in the PNG format and are located in <code><nowiki>./assets/<modid>/textures/block/</nowiki></code> or <code><nowiki>./assets/<modid>/textures/item/</nowiki></code> depending on whether they are for a block or an item, respectively. For other entries, they will be placed in their specified location within <code><nowiki>./assets/<modid>/textures/</nowiki></code>.

== Data ==

The <code><nowiki>./data</nowiki></code> folder holds all server related files for a specific game file. These files are synced across the network from the hosting server location.

=== Advancements ===

Advancements are in JSON format and are located in <code><nowiki>./data/<modid>/advancements/<group>/</nowiki></code> where <code><nowiki>group</nowiki></code> is the tab the advancement is part of.

=== Loot Tables ===

Loot tables are in JSON format and are located in <code><nowiki>./data/<modid>/loot_tables/<group>/</nowiki></code> where <code><nowiki>group</nowiki></code> is the general object where the loot table drops from (e.g. a block's loot table is in <code><nowiki>blocks</nowiki></code>).

=== Recipes ===

Recipes are in JSON format and are located in <code><nowiki>./data/<modid>/recipes/</nowiki></code>.

=== Tags ===

Tags are in JSON format and are located in <code><nowiki>./data/<modid>/tags/<group>/</nowiki></code> where <code><nowiki>group</nowiki></code> is the registry object to create the tags for (e.g. an entity tag would be in <code><nowiki>entity_types</nowiki></code>).

Registration/1.18

2022-06-10T07:45:38Z

ShrimpBot: Copy Registration to MC1.18 archive

{{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/1.18|ResourceLocation]]. This "registry name" can be accessed with its respective getter and setter: <code>#getRegistryName</code> and <code>#setRegistryName</code>. You can only set the "registry name" of a given object once; otherwise, an exception will be thrown.

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

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

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

== Methods for Registering ==

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

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

=== DeferredRegister ===

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

An example of a mod registering a custom block:

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

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

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

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

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

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

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

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

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

=== RegistryEvent.Register ===

The <code>RegistryEvent</code>s are another, more slightly flexible way to register objects. These [[Events/1.18|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/1.18|<code>BlockEntity</code>]] is wrapped via <code>BlockEntityType</code>, and <code>Entity</code> is wrapped via <code>EntityType</code>. These <code>*Type</code> classes hold factories that simply create the containing type on demand.

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

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

=== Non-Forge Registries ===

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

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

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

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

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

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

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

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

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

=== Data Driven Entries ===

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

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

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

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

== Referencing Registered Objects ==

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

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

===Using RegistryObjects===
<code>RegistryObject</code>s can be used to retrieve references to registered objects once they become available. Their references are updated along with all <code>@ObjectHolder</code> annotations after the associated <code>RegistryEvent$Register</code> has been dispatched and frozen.

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

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

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

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

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

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

=== Using @ObjectHolder ===

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

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

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

<code>@ObjectHolder</code> annotated fields are injected with their associated object values after their corresponding registry's <code>RegistryEvent$Register</code> event is fired, along with <code>RegistryObject</code>s.

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

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

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

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

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

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

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

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

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

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

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

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

== Creating Custom Registries ==

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

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

For the class that implements <code>IForgeRegistryEntry</code>, it is recommended in most cases to extend the default implementation of <code>ForgeRegistryEntry</code>. For interfaces, it should extend <code>IForgeRegistryEntry</code> with its implementations extending <code>ForgeRegistryEntry</code>.

=== With DeferredRegister ===

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

Here is an example:

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

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

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

final lazy val REGISTRY = EXAMPLE.makeRegistry(classOf[ExampleRegistry], () => new RegistryBuilder).get
|}}

=== Using `NewRegistryEvent` ===

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

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

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

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

== Handling Missing Entries ==

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

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

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

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

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

[[Category:Common Concepts/1.18|Category:Common Concepts]]

Recipes/1.18

2022-06-10T07:45:36Z

ShrimpBot: Copy Recipes to MC1.18 archive

With the update to Minecraft 1.12, Mojang introduced a new data-driven recipe system based on JSON files. Since then, it has been adopted by Forge as well and was expanded in Minecraft 1.13 into [[datapacks/1.18|datapacks]].

== Loading Recipes ==
Forge will load all recipes found within the <code><nowiki>./resources/data/<modid>/recipes/</nowiki></code> folder of your mod. You can call these files whatever you want, though the vanilla convention is to name them after the output item. For multiple recipes from different sources (smelting, crafting, etc) one vanilla convention is to use <code><nowiki>item_name_from_smelting.json</nowiki></code>. This name is also used as the registration key but does not affect the operation of the recipe.

== The Recipe File ==
A basic recipe file might look like the following example:
<syntaxhighlight lang="json">
{
"type": "minecraft:crafting_shaped",
"pattern":
[
"XXX",
"XAX",
"XXX"
],
"key":
{
"X":
{
"tag": "forge:gems/diamond"
},
"A":
{
"item": "mymod:myfirstitem"
}
},
"result":
{
"item": "mymod:myseconditem",
"count": 9
}
}
</syntaxhighlight>
{{Colored box|title=Tip|content=When you first obtain an ingredient to a vanilla recipe, it will automatically unlock the recipe in the recipe book. To achieve the same effect, you have to use the <code><nowiki>Advancement</nowiki></code> system and create a new <code><nowiki>Advancement</nowiki></code> for each of your ingredients.
<br><br>
The advancement has to exist. This doesn’t mean it has to be visible in the advancement tree.}}

=== Groups ===
Optionally, you can add a group to your recipes to be displayed within the recipe helper interface. All recipes with the same group String will be shown in the same group. For example, this can be used to have all door recipes shown in the recipe helper interface as a single entry, even though there are different types of doors.

=== Type ===
The type of the recipe. You can think of this as the definition of which crafting layout is to be used. <code><nowiki>minecraft:crafting_shaped</nowiki></code> and <code><nowiki>minecraft:crafting_shapeless</nowiki></code> are the two options.

== Types of Crafting Recipes ==
In this section, we will take a closer look at the differences between defining a shaped and a shapeless crafting recipe.

=== Shaped Crafting ===
Shaped recipes require the <code><nowiki>pattern</nowiki></code> and <code><nowiki>key</nowiki></code> keywords.
The '''Pattern''' keyword defines the slot an item must appear in using placeholder characters. You can choose whatever character you want to be a placeholder for an item.
'''Keys''' define what items the placeholders stand for. A key is defined by a placeholder character and the item or tag it stands for (in the correct format).

=== Shapeless Crafting ===
A shapeless recipe doesn’t use the <code><nowiki>pattern</nowiki></code> or <code><nowiki>key</nowiki></code> keywords.

To define a shapeless recipe, you have to use the <code><nowiki>ingredients</nowiki></code> list. It defines which items have to be used for the crafting process. There are many more of these types that can be used here, and you can even register your own. It is even possible to define multiple instances of the same item which means multiple of these items have to be in place for the crafting recipe to take place.

{{Colored box|title=Tip|content=While there is no limit on how many ingredients your recipe requires, the vanilla crafting table only allows 9 items for each crafting recipe.}}
Below is an example of an ingredient list:
<syntaxhighlight lang="json">
"ingredients": [
{
"tag": "forge:gems/diamond"
},
{
"item": "minecraft:nether_star"
}
],
</syntaxhighlight>

== Recipe Elements ==

=== Patterns ===
A pattern will be defined with the <code><nowiki>pattern</nowiki></code> list. Each string represents one row in the crafting grid and each placeholder character within the string represents a column. As shown in the example above, a space means that no item needs to be inserted at that position.

=== Keys ===
A key set is used in combination with a pattern set. It contains keys whose name is the same as the placeholder character in the pattern list which it represents. One key may be defined to represent multiple items, as is the case for the wooden button. This means that the player can use one of the defined items for the crafting recipe, for example, different types of wood.
<syntaxhighlight lang="json">
"key": {
"#": [
{
"item": "minecraft:oak_planks"
},
{
"item": "minecraft:spruce_planks"
}
]
}
</syntaxhighlight>

=== Results ===

Every <code><nowiki>recipe</nowiki></code> must have a result tag to define the output item.

When crafting something, you can get more than one item. This is achieved by defining the <code><nowiki>count</nowiki></code> value. If this is left out, meaning it doesn’t exist within the result block, it defaults to 1. Negative values are not allowed here as an itemstack cannot be smaller than 0. There is no option to use the <code><nowiki>count</nowiki></code> number anywhere else than the result.

[[Category:Resources and Data/1.18|Category:Resources and Data]]

Proper Mod Structuring/1.18

2022-06-10T07:45:34Z

ShrimpBot: Copy Proper Mod Structuring to MC1.18 archive

The structure of your mod is important in keeping your mod organized, for both your benefit and the benefit of anyone who wishes to make a feature or an
add-on 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/1.18|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.

== mods.toml 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).

More information about the structure of this file and the possible configuration options available to you can be found on the [[Mods.toml file/1.18|dedicated page]].

[[Category:Getting Started/1.18|Category:Getting Started]]
[[Category:Beginner Topics/1.18|Category:Beginner Topics]]

Potions/1.18

2022-06-10T07:45:31Z

ShrimpBot: Copy Potions to MC1.18 archive

A <code>Potion</code> is simply a list of <code>MobEffectInstance</code>s to be applied when used. Each <code>Potion</code> gets applied to every <code>Items#POTION</code>, <code>Items#SPLASH_POTION</code>, <code>Items#LINGERING_POTION</code>, and <code>Items#TIPPED_ARROW</code>. Like mob effects, potions need to be [[Registration/1.18|registered]].

== Creating a <code>Potion</code> ==

A <code>Potion</code> requires a passed in list of <code>MobEffectInstance</code>s to apply to the player when the potion is "consumed". There is also a nullable parameter called <code>name</code> that can be set if you would like to use the same name for multiple potions (e.g. <code>SWIFTNESS</code> and <code>LONG_SWIFTNESS</code> can be both <code>swiftness</code> potions).

== Adding a Brewing Recipe ==

Brewing Recipes can be added using <code>BrewingRecipeRegistry::addRecipe</code>. The most common constructor takes in an <code>Ingredient</code> input, an <code>Ingredient</code> reactant, and an <code>ItemStack</code> output. This can be registered during <code>FMLCommonSetupEvent</code>.

{{Tip/Important|If you want to use NBT information in your inputs (e.g. create a potion from another potion), you need to pass in an <code>NBTIngredient</code> instead.}}

{{Colored box|title=Alert|content=<code>BrewingRecipeRegistry</code> is '''not''' thread-safe. It should be called within <code>enqueueWork</code> in the specified parallel dispatch event.}}

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

Particles/1.18

2022-06-10T07:45:30Z

ShrimpBot: Copy Particles to MC1.18 archive

Particles are one of the few effects within the game that are used as polish to better improve immersion. Their usefulness also requires great caution due to how they are created and referenced in the game.

== Sided Issues ==
Particles are problematic due to their presence only on the [[Sides/1.18|physical client]]. They have no existence on a server whatsoever. This means that if specific data from a server is needed, it needs to be synced from the server to create the particle on the client.

== Creating a Particle ==
A particle can be broken up into four distinct classes. On the server, a <code>ParticleType<?></code> holds a <code>ParticleOptions</code> to sync the information. On the client, a <code>ParticleProvider</code> is used to generate a <code>Particle</code> from the synced <code>ParticleOptions</code>. To be more specific, a <code>ParticleType<?></code> holds the registry reference of the particle itself. A <code>ParticleOptions</code> hooks into a <code>ParticleType<?></code> to send information to the <code>ParticleProvider</code>. A <code>ParticleProvider</code> creates the specified particle in some place within the level. Then, the <code>Particle</code> goes and handles the rendering logic to make it appear in game.

=== <code>ParticleType</code>s ===

While there are a lot of different particles in vanilla, in almost all cases vanilla uses <code>SimpleParticleType</code>, a basic implementation of <code>ParticleType</code> and <code>ParticleOptions</code>. This is used whenever server data is not necessary to spawn the particle. The only vanilla particles that do not use <code>SimpleParticleType</code> are redstone dust and block/item texture dependent particles. When requiring server data, a direct implementation of <code>ParticleOptions</code> is needed. A good way is to extend <code>ParticleType<?></code> and implement <code>ParticleOptions</code> on the same class. In the case of a more generic solution, an implementation of <code>ParticleOptions</code> can be referenced while the standard <code>ParticleType<?></code> class is used.

<code>ParticleType</code>s must be [[Registration#registering-things/1.18|registered]].

=== <code>ParticleOptions</code> ===

Beside the standard reference to a <code>ParticleType<?></code>, a <code>ParticleOptions</code> is made up of two main methods and two accessory methods for compatibility across Minecraft usage.

First there are the sync methods:
<syntaxhighlight lang="java">
ParticleOptions#writeToNetwork(FriendlyByteBuf)

ParticleOptions$Deserializer#fromNetwork(ParticleType, FriendlyByteBuf)
</syntaxhighlight>

These two are used to sync information across the network. All information from the server should be synced in this fashion.

The other two are for compatibility with other Minecraft systems:
<syntaxhighlight lang="java">
ParticleOptions#writeToString

ParticleOptions$Deserializer#fromCommand(ParticleType, StringReader)
</syntaxhighlight>

These two are used to read/write data to NBT as well as get information to spawn the particle in the level using a command.

=== <code>Particle</code>s ===

<code>Particle</code>s will be left as an exercise to the reader as it is mainly about deciding what the reader wants to render to the screen. One of the most common classes to subclass, however, is <code>TextureSheetParticle</code>. This abstract class renders a texture specified by the user as the particle to go according to the logic rendered.

=== <code>ParticleProvider</code>s ===
Finally, a particle must be created using a <code>ParticleProvider</code>. This simply just decides where the particle should be placed in the level at some speed in most cases. Since a <code>Particle</code> is not beholden to any particular <code>ParticleType<?></code>, it can be reused over and over again in different factories if necessary.

A <code>ParticleProvider</code> must be attached to a <code>ParticleType</code> using <code>ParticleEngine#register</code>. If a particle has a json defined sprite location, then the <code>ParticleEngine$SpriteParticleRegistration</code> variant must be used instead as otherwise an exception will be thrown. This should be called during <code>ParticleFactoryRegisterEvent</code> on the mod event bus.

{{Tip/Important|<code>ParticleProvider</code> is only present on the client, so the event needs to be isolated via <code>DistExecutor</code> or some other method.}}

== Spawning Particles ==
Particles can be spawned from a level instance. Each side, however, has a specific way of calling them. The <code>ClientLevel</code> can call either <code>addParticle</code> or <code>addAlwaysVisibleParticle</code>. The <code>ServerLevel</code> must call <code>sendParticles</code> as it sends a packet to the client level to call one of the other two methods. Calling the two <code>ClientLevel</code> methods on the server will result in nothing happening.

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

Networking with Entities/1.18

2022-06-10T07:45:28Z

ShrimpBot: Copy Networking with Entities to MC1.18 archive

In addition to regular network messages, there are various other systems provided to handle synchronizing entity data.

== Spawn Data ==

In general, the spawning of modded entities is handled seperately, by Forge.

{{Colored box|title=Info|content=This means that simply extending a vanilla entity class may not inherit all its behaviour here. You may need to implement certain vanilla behaviours yourself.}}

You can add extra data to the spawn packet Forge sends by implementing the following interface.

===IEntityAdditionalSpawnData===
If your entity has data that is needed on the client, but doesn't change over time, then it can be added to the entity spawn packet using this interface. <code><nowiki>writeSpawnData()</nowiki></code> and <code><nowiki>readSpawnData()</nowiki></code> control how the data should be en/decoded to/from the network buffer. Also override <code><nowiki>getAddEntityPacket()</nowiki></code> to return <code><nowiki>NetworkHooks.getEntitySpawningPacket(...)</nowiki></code> for the data to be send.

== Dynamic Data ==

=== Data Parameters ===

This is the main vanilla system for synchronizing entity data from the server to the client. As such, a number of vanilla examples are available to refer to.

Firstly you need a <code><nowiki>EntityDataAccessor<T></nowiki></code> for the data you wish to keep synchronized. This should be stored as a static final field in your entity class, obtained by calling <code><nowiki>SynchedEntityData.defineId()</nowiki></code> and passing the entity class and a serializer for that type of data. The available serializer implementations can be found as static constants within the <code><nowiki>EntityDataSerializers</nowiki></code> class.

{{Colored box|title=Alert|content=You should '''only''' create data parameters for your own entities, ''within that entity's class''. Adding parameters to entities you do not control can cause the IDs used to send that data over the network to become desynchronized, causing difficult to debug crashes.}}

Then, override <code><nowiki>Entity#defineSynchedData()</nowiki></code> and call <code><nowiki>this.entityData.define(...)</nowiki></code> for each of your data parameters, passing the parameter and an initial value to use. Remember to always call <code><nowiki>super.defineSynchedData()</nowiki></code> first!

You can then get and set these values via your entity's <code><nowiki>entityData</nowiki></code> instance. Changes made will be synchronized to the client automatically.

Networking/1.18

2022-06-10T07:45:26Z

ShrimpBot: Copy Networking to MC1.18 archive

Communication between servers and clients is the backbone of a successful mod implementation.

Read an [[Understanding Networking#overview/1.18|overview]] of why networking matters and the basic strategies in thinking about networking.

There are a variety of techniques provided by Forge to facilitate communication - mostly built on top of [https://netty.io netty].

The simplest, for a new mod, would be [[Using SimpleChannel/1.18|SimpleImpl]], where most of the complexity of the netty system is
abstracted away. It uses a message and handler style system.

== Overview ==

There are two primary goals in network communication:

# Making sure the client view is "in sync" with the server view
#* The flower at coordinates X, Y, Z just grew
# Giving the client a way to tell the server that something has changed about the player
#* the player pressed a key

The most common way to accomplish these goals is to pass messages between the client and the server. These messages will
usually be structured, containing data in a particular arrangement, for easy sending and receiving.

Named Binary Tag/1.18

2022-06-10T07:45:24Z

ShrimpBot: Copy Named Binary Tag to MC1.18 archive

Information between two points are passed in many different ways in Minecraft. The most common of them is known as NBTs. NBTs are a structured binary file used to store information on the disk. They are also used as intermediaries to hold information that will be sent across a network. Understanding and utilizing NBTs properly is a good start to understanding disk storage in general.

== NBT Types ==
There are a total of fourteen different nbt data types that can be parsed. The most common one to use is <code>CompoundTag</code>s within a <code>BlockEntity</code> or <code>Entity</code> when it comes to writing to the disk. However, on capabilities, other types can be specified to reduce the space it takes on a file.

All types implement <code>Tag</code> in some fashion. This interface holds basic methods for writing to a file and copying itself. It also holds basic methods to determine the output to a chat line.
{| class="wikitable sortable" border=1
!Id !!Name !!Description
|-
| 0 || <code>EndTag</code> || Specifies the end of an nbt file.
|-
| 1 || <code>ByteTag</code> || Holds a byte. Also used to store a boolean value.
|-
| 2 || <code>ShortTag</code> || Holds a short.
|-
| 3 || <code>IntTag</code> || Holds an integer.
|-
| 4 || <code>LongTag</code> || Holds a long.
|-
| 5 || <code>FloatTag</code> || Holds a float.
|-
| 6 || <code>DoubleTag</code> || Holds a double.
|-
| 7 || <code>ByteArrayTag</code> || Holds a byte array. Can be parsed from an array of primitive bytes or a list of byte objects.
|-
| 8 || <code>StringTag</code> || Holds a string.
|-
| 9 || <code>ListTag</code> || Holds a list of a specific <code>Tag</code>.
|-
| 10 || <code>CompoundTag</code> || Holds an object comprised of <code>Tag</code>s. It works similarly to a java object where it can store other primitives, objects, or itself inside.
|-
| 11 || <code>IntArrayTag</code> || Holds an integer array. Can be parsed from an array of primitive integers or a list of integer objects.
|-
| 12 || <code>LongArrayTag</code> || Holds an long array. Can be parsed from an array of primitive long, a list of long objects, or a <code>LongSet</code>.
|-
| 99 || <code>NumericTag</code> || Holds a generic number. Used when the specific <code>Tag</code> for a number is not specified. All numbers can be converted to each other.
|-
|}

In most cases, you will only have to deal with <code>CompoundTag</code> and <code>ListTag</code>. The others are usually handled internally by whichever type uses them.

== Common Usages ==
<code>CompoundTag</code>s are used similar to objects. You can <code>put</code> and value within them using a key. You can then retrieve the value once again with that same key. It has specific methods for putting and getting most of the different types of data (e.g. an integer using <code>putInt</code> and <code>getInt</code>).

<code>ListTag</code>s are functionally the same as <code>ArrayList</code>s. You can <code>add</code>, <code>remove</code>, <code>set</code>, or <code>get</code> a specific NBT type.

NBT/1.18

2022-06-10T07:45:22Z

ShrimpBot: Copy NBT to MC1.18 archive

#REDIRECT [[Named Binary Tag/1.18|Named Binary Tag]]

Mods.toml file/1.18

2022-06-10T07:45:20Z

ShrimpBot: Copy Mods.toml file to MC1.18 archive

#REDIRECT [[Mods.toml/1.18|Mods.toml]]

Mods.toml/1.18

2022-06-10T07:45:18Z

ShrimpBot: Copy Mods.toml to MC1.18 archive

{{Under construction}}

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

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

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

[[mods/1.18|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/1.18|dependencies.examplemod]]
modId="forge"
mandatory=true
versionRange="[40,)"
ordering="NONE"
side="BOTH"

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

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

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

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

{| class="wikitable"
|-
!|Property
!|Type
!|Defaults
!|Description
!|Example
|-
|<code>modLoader</code>
|string
|'''mandatory'''
|The language loader for the mod. Used to specify an alternative language for the mod, such as Kotlin, if one exists. The Forge-provided Java loader is <code>javafml</code>.
|<code>"javafml"</code>
|-
|<code>loaderVersion</code>
|string
|'''mandatory'''
|The acceptable version range of the language loader, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. For the Forge-provided Java loader, the version is the major version of the Forge version.
|<code>"[40,)"</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/1.18|mods]]</nowiki></code> header (In TOML, the <code><nowiki>[[mods/1.18|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/1.18|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/1.18|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/1.18|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/1.18|Category:Getting Started]]
[[Category:Beginner Topics/1.18|Category:Beginner Topics]]

Model JSONs/1.18

2022-06-10T07:45:17Z

ShrimpBot: Copy Model JSONs to MC1.18 archive

A “model” is simply a shape. It can be a simple cube, it can be several cubes, it can be a truncated icosidodecahedron, or anything in between. Most models you’ll see will be in the vanilla JSON format. Models in other formats are loaded into an <code>IModelGeometry</code> by an <code>IModelLoader</code> at runtime. Forge provides default implementations for WaveFront OBJ files, buckets, composite models, models in different render layers, and a reimplementation of Vanilla's <code>builtin/generated</code> item model. Most things do not care about what loaded the model or what format it’s in as they all "bake" into an <code>BakedModel</code>.

When <code>ResourceLocation</code> refers to a model, the path is normally relative to <code>models</code> (e.g. <code><nowiki>examplemod:block/block</nowiki></code> → <code><nowiki>assets/examplemod/models/block/block</nowiki></code>).

Block and item models differ in a few ways, the major one being [[Item Overrides/1.18|item property overrides]].

== Textures ==
Textures, like models, are contained within resource packs and are referred to with <code>ResourceLocation</code>s. When <code>ResourceLocation</code>s refer to textures in models, the paths are taken to be relative to <code><nowiki>textures/</nowiki></code> (e.g. <code><nowiki>examplemod:blocks/test</nowiki></code> → <code><nowiki>assets/examplemod/textures/blocks/test.png</nowiki></code>). Additionally, in Minecraft, the [https://en.wikipedia.org/wiki/UV_mapping UV coordinates] (0,0) are taken to mean the ''<code>top-left</code>'' corner. UVs are <code>always</code> from 0 to 16. If a texture is larger or smaller, the coordinates are scaled to fit. A texture should also be square, and the side length of a texture should be a power of two, as doing otherwise breaks mipmapping. (E.g. 1x1, 2x2, 8x8, 16x16, and 128x128 are good. 5x5 and 30x30 are not recommended because they are not powers of 2. 5x10 and 4x8 are completely broken as they are not square.) If there is an <code>mcmeta</code> file associated with the texture, and an animation is defined, the image can be rectangular and is interpreted as a vertical sequence of square regions from top to bottom, where each square is a frame of the animation.

== JSON Models ==
Vanilla Minecraft’s JSON model format is rather simple. It defines cuboid (cube/rectangular prism) elements, and assigns textures to their faces. On the [https://minecraft.fandom.com/wiki/Model#Block_models wiki], there is a definition of its format.

{{Colored box|title=Tip|content=JSON models only support cuboid elements; there is no way to express a triangular wedge or anything like it. To have more complicated models, another format must be used.}}

When a <code>ResourceLocation</code> refers to the location of a JSON model, it is not suffixed with <code><nowiki>.json</nowiki></code>, unlike OBJ (e.g. <code><nowiki>minecraft:block/cube_all</nowiki></code>, not <code><nowiki>minecraft:block/cube_all.json</nowiki></code>).

== WaveFront OBJ Models ==
Forge adds a loader for the <code>.obj</code> file format. To use these models, the JSON must reference the <code>forge:obj</code> loader. This loader accepts any model location that is in a registered namespace and whose path ends in <code>.obj</code>. The <code>.mtl</code> file should be placed in the same location with the same name as the <code>.obj</code> to be used automatically. The <code>.mtl</code> file will probably have to be manually edited to change the paths pointing to textures defined within the JSON. Additionally, the V axis for textures may be flipped depending on the external program that created the model (i.e. V = 0 may be the bottom edge, not the top). This may be rectified in the modelling program itself or done in the model JSON like so:

<syntaxhighlight lang="json">
{
"__comment": "Add the following line on the same level as a 'model' declaration.",
"loader": "forge:obj",
"flip-v": true,
"model": "examplemod:models/block/model.obj",
"textures": {
"_comment": "Can refer to in .mtl using #texture0",
"texture0": "minecraft:block/dirt",
"particle": "minecraft:block/dirt"
}
}
</syntaxhighlight>

[[Category:Models/1.18|Category:Models]]

Mob Effects/1.18

2022-06-10T07:45:15Z

ShrimpBot: Copy Mob Effects to MC1.18 archive

A <code>MobEffect</code> is what handles the specific logic on the entity it is on. For example, <code>MobEffects#MOVEMENT_SPEED</code> adds an attribute modifier that affects the movement speed while <code>MobEffects#WITHER</code> attacks the entity from a <code>DamageSource</code> whenever the mob effect is ready to be applied.

== Creating a <code>MobEffect</code> ==

You can create a <code>MobEffect</code> using two methods. The first creates a regular <code>MobEffect</code> and applies the logic in some event method. The other method involves extending the <code>MobEffect</code> class and overriding specific methods when needed. This documentation will focus on the second method.

There are four methods that are important depending on the type of mob effect you are creating. In each scenario, you should take into account whether you should extend <code>MobEffect</code> or <code>InstantenousMobEffect</code>.

Here are the classes and methods to review:

{| class="wikitable sortable" border=1
!Class !!Usage
|-
| <code>MobEffect</code> || The basic mob effect class. Should be used if the mob effect happens over time.
|-
| <code>InstantenousMobEffect</code> || An extended version of the mob effect class. Should be used if the mob effect happens only once and instantly.
|-
|}

{| class="wikitable sortable" border=1
!Method !!Description
|-
| <code>isDurationEffectTick</code> || Determines how fast a mob effect should call <code>applyEffectTick</code> while applied. This is overridden by <code>InstantenousMobEffect</code> to occur after one tick. If too fast, the server will not have enough time to execute the damage on the entity.
|-
| <code>applyEffectTick</code> || Executes the logic on the entity when called.
|-
| <code>isInstantenous</code> || Determines if the mob effect is instant. Returns true in <code>InstantenousMobEffect</code>.
|-
| <code>applyInstantenousEffect</code> || Executes the logic on the entity when called. <code>isInstantenous</code> must return true for this to be called.
|-
|}

If you are only modifying an entity <code>Attribute</code>, then there is no need to extend the class. When constructing the mob effect instance, chain <code>addAttributeModifier</code> and select the specific attribute, it's unique id, the amount to affect by, and the operation to apply the amount with.

Mob Effects need to be [[Registration/1.18|registered]].

== <code>MobEffectInstance</code> ==

To allow greater customization, each mob effect is passed in as a <code>MobEffectInstance</code> which allows the user to specify additional information for what the mob effect should do.

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

Making Tools/1.18

2022-06-10T07:45:13Z

ShrimpBot: Copy Making Tools to MC1.18 archive

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Registering ==

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

[[Category:Items/1.18|Category:Items]]

Making Items/1.18

2022-06-10T07:45:11Z

ShrimpBot: Copy Making Items to MC1.18 archive

{{Under construction}}

Along with blocks, items are a key component of most mods. While blocks make up the world around you, items are what let you change it.

== Creating an Item ==
=== Basic Items ===
Basic items that need no special functionality (think sticks or sugar) don’t need custom classes. You can create an item by instantiating the <code><nowiki>Item</nowiki></code> class with an <code><nowiki>Item$Properties</nowiki></code> object. This <code><nowiki>Item$Properties</nowiki></code> object can be made by calling the constructor and can be customised by calling its methods. For instance:
{| class="wikitable sortable" border=1
!Method !!Description
|-
| <code><nowiki>tab</nowiki></code> || Sets which <code><nowiki>CreativeModeTab</nowiki></code> (previously called creative tab) this item is under. Must be called if this item is meant to be shown on the creative menu. Vanilla tabs can be found in the class <code><nowiki>CreativeModeTab</nowiki></code>.
|-
| <code><nowiki>durability</nowiki></code> || Sets the maximum damage value for this item. If it is greater than ''0'', the properties ''damaged'' and ''damage'' are added to keep track of the current ''ItemStack'' damage.
|-
| <code><nowiki>stacksTo</nowiki></code> || Sets the maximum stack size. You cannot have an item that is both damagable and stackable.
|-
| <code><nowiki>setNoRepair</nowiki></code> || Makes this item impossible to repair, even if it is damageable.
|-
| <code><nowiki>craftRemainder</nowiki></code> || Sets this item’s container item. For example, milk buckets give you back an empty bucket when they are crafted.
|-
|}

The above methods are chainable, meaning they <code><nowiki>return this</nowiki></code> to facilitate calling them in series.

=== Advanced Items ===
Setting the properties of an item as above only works for simple items. If you want more complicated items, you should subclass ''Item'' and override its methods.

== Registering an Item ==
Items must be [[Registration/1.18|registered]] to function.

[[Category:Items/1.18|Category:Items]]

Making Blocks/1.18

2022-06-10T07:45:09Z

ShrimpBot: Copy Making Blocks to MC1.18 archive

Blocks are, obviously, essential to the Minecraft world. They make up all of the terrain, structures, and machines. Chances are if you are interested in making a mod, then you will want to add some blocks. This page will guide you through the creation of blocks, and some of the things you can do with them.
==Creating a Block==
===Basic Blocks===
For simple blocks, which need no special functionality (think cobblestone, wooden planks, etc.), a custom class is not necessary. You can create a block by instantiating the <code><nowiki>Block</nowiki></code> class with a <code><nowiki>BlockBehaviour$Properties</nowiki></code> object. This <code><nowiki>BlockBehaviour$Properties</nowiki></code> object can be made using <code><nowiki>BlockBehaviour$Properties::of</nowiki></code> and it can be customised by calling its methods. For instance:
* <code><nowiki>strength</nowiki></code> - The hardness controls the time it takes to break the block. It is an arbitrary value. For reference, stone has a hardness of 1.5, and dirt 0.5. If the block should be unbreakable a hardness of -1.0 should be used, see the definition of <code><nowiki>Blocks#BEDROCK</nowiki></code> as an example. The resistance controls the explosion resistance of the block. For reference, stone has a resistance of 6.0, and dirt 0.5.
* <code><nowiki>sound</nowiki></code> - Controls the sound the block makes when it is punched, broken, or placed. Requires a <code><nowiki>SoundType</nowiki></code> argument, see the [[Sounds/1.18|sounds]] page for more details.
* <code><nowiki>lightLevel</nowiki></code> - Controls the light emission of the block. Takes a function with a ''BlockState'' parameter that returns an integer value from zero to fifteen.
* <code><nowiki>friction</nowiki></code> - Controls how slippery the block is. For reference, ice has a slipperiness of 0.98.

All these methods are ''chainable'' which means you can call them in series. See the <code><nowiki>Blocks</nowiki></code> class for examples of this.

{{Colored box|title=Tip|content=Blocks have no setter for their <code><nowiki>CreativeModeTab</nowiki></code>. This has been moved to the <code><nowiki>BlockItem</nowiki></code> and is now its responsibility.}}

===Advanced Blocks===
Of course, the above only allows for extremely basic blocks. If you want to add functionality, like player interaction, a custom class is required. However, the <code><nowiki>Block</nowiki></code> class has many methods and unfortunately not every single one can be documented here. See the rest of the pages in this section for things you can do with blocks.
==Registering a Block==
Blocks must be [[Registration/1.18|registered]] to function.

{{Tip/Important|A block in the level and a "block" in an inventory are very different things. A block in the level is represented by a <code><nowiki>BlockState</nowiki></code>, and its behavior defined by an instance of <code><nowiki>Block</nowiki></code>. Meanwhile, an item in an inventory is an <code><nowiki>ItemStack</nowiki></code>, controlled by an <code><nowiki>Item</nowiki></code>. As a bridge between the different worlds of <code><nowiki>Block</nowiki></code> and <code><nowiki>Item</nowiki></code>, there exists the class <code><nowiki>BlockItem</nowiki></code>. <code><nowiki>BlockItem</nowiki></code> is a subclass of <code><nowiki>Item</nowiki></code> that has a field <code><nowiki>block</nowiki></code> that holds a reference to the <code><nowiki>Block</nowiki></code> it represents. <code><nowiki>BlockItem</nowiki></code> defines some of the behavior of a "block" as an item, like how a right click places the block. It's possible to have a <code><nowiki>Block</nowiki></code> without an <code><nowiki>BlockItem</nowiki></code>. (E.g. <code><nowiki>minecraft:water</nowiki></code> exists as a block, but not an item. It is therefore impossible to hold it in an inventory as one.)
<br><br>
When a block is registered, ''only'' a block is registered. The block does not automatically have an <code><nowiki>BlockItem</nowiki></code>. To create a basic <code><nowiki>BlockItem</nowiki></code> for a block, one should use <code><nowiki>new BlockItem(block)</nowiki></code> and match the registry name between the two objects. Custom subclasses of <code><nowiki>BlockItem</nowiki></code> may be used as well. Once a <code><nowiki>BlockItem</nowiki></code> has been registered for a block, <code><nowiki>Block#asItem</nowiki></code> can be used to retrieve it. <code><nowiki>Block#asItem</nowiki></code> will default to <code><nowiki>Items#AIR</nowiki></code> if there is no <code><nowiki>BlockItem</nowiki></code> for the <code><nowiki>Block</nowiki></code>, so if you are not certain that there is a <code><nowiki>BlockItem</nowiki></code> for the <code><nowiki>Block</nowiki></code> you are using, check for <code><nowiki>Items#AIR</nowiki></code>.}}

====Optionally Registering Blocks====
Since there is no limit on the amount of blocks that can be register, register all blocks in your mod! If you want a block to be disabled through a configuration file, you should disable the crafting recipe and/or remove the block from the creative menu (<code><nowiki>CreativeModeTab</nowiki></code>).
==Further Reading==
For information about block properties, such as those used for vanilla blocks like fences, walls, and many more, see the section on [[Understanding Blockstates/1.18|blockstates]].

[[Category:Blocks/1.18|Category:Blocks]]

Main Page/styles.css/1.18

2022-06-10T07:45:07Z

ShrimpBot: Copy Main Page/styles.css to MC1.18 archive

.center {
text-align: center;
}

.title {
font-weight: 900;
font-size: 3em;
line-height: 1.2em;
color: #e0a969;
}

.round_warning {
font-weight: 700;
width: 60%;
border-radius: 1em;
margin: auto;
margin-top: 1em;
background-color: #fefefe;
color: #222;
height: 2em;
display: flex;
justify-content: center;
align-items: center;
padding: 0.25em;
}

.round_warning p {
margin-top: 0;
}

.box_container {
display: flex;
flex-flow: row wrap;
}

.box {
flex: 1 1 12em;
padding: 1em;
border: solid;
border-radius: 1em;
margin: 0.5em;
}

.box h1, .box h2, .box h3 {
margin-top: 0
}

.box ul {
list-style-type: none;
margin-left: 0;
}

.box ul li {
line-height: 1.3em;
margin-top: 0.45em;
}

Main Page/1.18

2022-06-10T07:45:05Z

ShrimpBot: Copy Main Page to MC1.18 archive

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

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

The Forge Community Wiki exists so that the community can:

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

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

{{Supported versions}}

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

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

<div class="box_container center">

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

</div>

Key Mappings/1.18

2022-06-10T07:45:03Z

ShrimpBot: Copy Key Mappings to MC1.18 archive

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