Forge Community Wiki - User contributions [en-gb]

Dynamic Loot Modification

2021-03-13T23:38:08Z

Unbekannt: add folder for serialized jsons

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

== Registering a Global Loot Modifier ==

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

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

== The global_loot_modifiers.json ==

All you need to add here are the registry names of your loot modifiers.
<syntaxhighlight lang="json">
{
"replace": false,
"entries": [
"global_loot_test:silk_touch_bamboo",
"global_loot_test:smelting",
"global_loot_test:wheat_harvest"
]
}
</syntaxhighlight>

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

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

== The serialized json ==

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

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

== The LootModifier Subclass ==

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

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

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

private static class Serializer extends GlobalLootModifierSerializer<WheatSeedsConverterModifier> {

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

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

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

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

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

Saplings

2021-03-11T17:59:33Z

Unbekannt: fix formatting

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.

Additional Resources

2021-02-12T17:44:57Z

Unbekannt: add Mcjty's Tutorial

{{Under construction}}

There are hundreds of different resources and libraries that make modding for Forge easier to understand and use. This page contains a collection of these entries that is recommended for use.

== Informational Resources ==

* [https://mcforge.readthedocs.io/ Official Forge Documentation]
* [https://minecraft.gamepedia.com/Minecraft_Wiki Minecraft Wiki]
* [https://wiki.mcjty.eu/modding/index.php?title=YouTube-Tutorials Mcjty's Tutorials]

== Useful Libraries and APIs ==

{| class="wikitable sortable"
! Library !! Author !! Description
|-
| Example || Example || Example
|}

Semantic Versioning

2020-12-21T13:49:54Z

Unbekannt: remove old Box to new one

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

Internationalization

2020-12-21T13:48:35Z

Unbekannt: update Box to use new Templates

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

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

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

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

== Language files ==

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

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

== Usage with Blocks and Items ==

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

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

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

== Localization methods ==

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

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

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

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

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

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

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

Resources

2020-12-21T13:45:39Z

Unbekannt: update link

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

Resources

2020-12-21T13:43:14Z

Unbekannt: update kink

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

2020-12-21T13:33:35Z

Unbekannt: update Link to Resource Location

Registration is the process of taking the objects of a mod (such as items, blocks, sounds, etc.) and making them known to the game. Registering things is important, as without registration the game will simply not know about these objects, which will cause unexplainable behaviors and crashes.

Most things that require registration in the game are handled by the Forge registries. A registry is an object similar to a map that assigns values to keys. Forge uses registries with [[Using Resources#ResourceLocation|ResourceLocation]] keys to register objects. This allows the <code>ResourceLocation</code> to act as the "registry name" for objects. The registry name for an object may be accessed with <code>#getRegistryName</code>/<code>#setRegistryName</code>. The setter can only be called once; calling it twice results in an exception.

Every type of registrable object has its own registry. To see all registries supported by Forge, see the <code>ForgeRegistries</code> class. All registry names within a registry always be unique; attempting to register with an already existing registry name will cause the newly registered object to override whatever was registered previously. However, names in different registries will not collide. For example, there's a <code>Block</code> registry, and an <code>Item</code> registry. A <code>Block</code> and an <code>Item</code> may be registered with the same name <code>example:thing</code> without colliding; however, if two different <code>Block</code>s or <code>Item</code>s were registered with the same exact name, the second object will override the first.

== Methods for Registering ==

There are two proper ways to register objects: the <code>DeferredRegister</code> class, and the <code>RegistryEvent.Register</code> lifecycle event.

=== DeferredRegister ===

<code>DeferredRegister</code> is the newer and documented way to register objects. It allows the use and convenience of static initialisers while avoiding the issues associated with it. It simply maintains a list of suppliers for entries and registers the objects from those suppliers during the proper <code>RegistryEvent.Register</code> event.

An example of a mod registering a custom block:

<syntaxhighlight lang="java">
private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> ROCK_BLOCK = BLOCKS.register("rock", () -> new Block(Block.Properties.create(Material.ROCK)));

public ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().getModEventBus());
}
</syntaxhighlight>

=== RegistryEvent.Register ===

The <code>RegistryEvent</code>s are the second and more flexible way to register objects. These [[Events|events]] are fired after the mod constructors and before the loading of configs.

The event used in registering objects is the <code>RegistryEvent.Register<T></code>, where the type parameter <code>T</code> is the type of the object being registered. Calling <code>#getRegistry</code> will return the registry, upon which objects are registered with <code>#register</code> (pass it a single object that you want to register) or <code>#registerAll</code> (pass it a list of objects).

The latter is very useful for minimising calls to <code>#register</code>.

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

<syntaxhighlight lang="java">
@SubscribeEvent
public void registerBlocks(RegistryEvent.Register<Block> event) {
event.getRegistry().registerAll(new Block(...), new Block(...), ...);
}
</syntaxhighlight>

{{Tip/Important|Some classes cannot by themselves be registered; instead, <code>*Type</code> classes are registered, and used in the formers' constructors. For example, [[Tile_Entities|<code>TileEntity</code>]] has <code>TileEntityType</code>, and <code>Entity</code> has <code>EntityType</code>. These <code>*Type</code> classes are factories that simply create the containing type on demand.

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

<syntaxhighlight lang="java">
public static final RegistryObject<TileEntityType<ExampleTile>> EXAMPLE_TILE = REGISTER.register(
"example_tile", () -> TileEntityType.Builder.create(ExampleTile::new, EXAMPLE_BLOCK.get()).build(null)
);
</syntaxhighlight>}}

== Referencing Registered Objects ==

Registered objects should not be stored in fields when they are created and registered. They are to be always newly created and registered whenever their respective <code>RegistryEvent.Register</code> event is fired. This is to allow dynamic loading and unloading of mods in a future version of 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 are available. These are used by <code>DeferredRegister</code> to return a reference to registered objects. Their references are updated after their corresponding registry's <code>RegistryEvent.Register</code> event is fired, along with the <code>@ObjectHolder</code> annotations.

To get a <code>RegistryObject</code>, call <code>RegistryObject.of</code> with a <code>ResourceLocation</code> and the <code>IForgeRegistry</code> of the registrable object. Custom registries can also be used through giving a supplier of the custom object's class. Store the <code>RegistryObject</code> in a <code>public static final</code> field, and call <code>#get</code> whenever you need the registered object.

An example of using <code>RegistryObject</code>:

<syntaxhighlight lang="java">
public static final RegistryObject<Item> BOW = RegistryObject.of(new ResourceLocation("minecraft:bow"), ForgeRegistries.ITEMS);

// assume that ManaType is a valid registry, and 'neomagicae:coffeinum' is a valid object within that registry
public static final RegistryObject<ManaType> COFFEINUM = RegistryObject.of(new ResourceLocation("neomagicae", "coffeinum"), () -> ManaType.class);
</syntaxhighlight>

=== Using @ObjectHolder ===

Registered objects from registries can be injected into the <code>public static</code> fields by annotating classes or fields with <code>@ObjectHolder</code> and supplying enough information to construct a <code>ResourceLocation</code> to identify a specific object in 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>;
** 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 7
* 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 values after their corresponding registry's <code>RegistryEvent.Register</code> event is fired, along with the <code>RegistryObject</code>s.

{{Colored box|title=Informational|content=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.}}

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 ItemGroup group = null; // No annotation. [public static final] is required.
// ItemGroup does not have a corresponding registry.
// No supertypes of ItemGroup 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 ==

You might want to create a new registry for your mod. This might be usefull 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 2 ways of making a new registry.

=== Using RegistryEvent.NewRegistry ===

Custom registries are created by using <code>RegistryBuilder</code> during the <code>RegistryEvent.NewRegistry</code> event. The class <code>RegistryBuilder</code> takes certain parameters (such as the registry name, the <code>Class</code> of its values, and various callbacks for different events happening on the registry). Calling <code>RegistryBuilder#create</code> will result in the registry being built, registered to the <code>RegistryManager</code>, and returned to the caller for additional processing.

The <code>Class</code> of the value of the registry must implement <code>IForgeRegistryEntry</code>, which defines that <code>#setRegistryName</code> and <code>#getRegistryName</code> can be called on the objects of that class. For most custom objects, is recommended to extend the default implementation of <code>ForgeRegistryEntry</code>, instead of implementing the interface directly. When <code>#setRegistryName(String)</code> is called with a string, and that string does not have an explicit namespace, its namespace will be set to the current modid.

The Forge registries can be accessed through the <code>ForgeRegistries</code> class. All registries, Forge-provided or custom, can be retrieved by calling <code>GameRegistry.findRegistry(Class)</code> with the appropriate class for the registry. For example, the registry for <code>Block</code>s can be retrieved by calling <code>GameRegistry.findRegistry(Block.class)</code>.

<syntaxhighlight lang="Java">
@SubscribeEvent
public static void onNewRegistry(RegistryEvent.NewRegistry registry){
RegistryBuilder<ArcaneFuelType> registryBuilder = new RegistryBuilder<ArcaneFuelType>();
registryBuilder.setName(ArcaneRituals.location("arcane_fuel"));
registryBuilder.setType(ArcaneFuelType.class);
registryBuilder.create();
}
</syntaxhighlight>

=== With DeferredRegister ===

TODO

Sides

2020-12-21T13:20:42Z

Unbekannt: modloading process is missing

{{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>Client 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>World#isRemote</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>World</code> object establishes the logical side that the world belongs to. That is, if this field is <code>true</code>, the world extends <code>ClientWorld</code> and is currently running on the logical client, while if the field is <code>false</code>, the world extends <code>ServerWorld</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>world.isRemote</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 [[Modloading|modloading process]]. Most of these events are fired on both physical sides, except for the '''sided setup events''': <code>FMLClientSetupEvent</code> and <code>FMLDedicatedServerSetupEvent</code>, which is fired on the physical client and the physical/dedicated server respectively.

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

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

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

If any class you write references those names in any way, they will crash the game when that respective class is loaded in an environment where those names do not exist. For example, a very common mistake in beginners is to call <code>Minecraft.getMinecraft().<doStuff>()</code> in block or tile 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.

{{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>World</code> object to check <code>isRemote</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>world.isRemote</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 little to no reason for using this annotation directly. The only valid reason to use this annotation is if you are extending a vanilla class that is already annotated with <code>@OnlyIn</code>. In all other cases where you need to dispatch behavior based on physical sides, 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 network packets. It is incredibly tempting, when in a single player scenario, to directly transfer data from the logical server to the logical client.

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

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

=== Writing One-Sided Mods ===

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

So for one-sided mods, you would typically register your event handlers using [[#DistExecutor|<code>DistExecutor</code>]] or ''@EventBusSubscriber(value = Dist.*)'', 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 override the <code>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)

<syntaxhighlight lang="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(ExtensionPoint.DISPLAYTEST, () -> Pair.of(() -> FMLNetworkConstants.IGNORESERVERONLY, (a, b) -> true));
</syntaxhighlight>

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.

Getting Started

2020-12-21T13:11:22Z

Unbekannt: cookbook links do not work is there an alternative?

{{Under construction}} 
= Home =
== Getting Started with Forge ==
This is a simple guide to get you from nothing to a basic mod. The rest of this documentation is about where to go from here.
=== From Zero to Modding ===
# Obtain a source distribution from forge’s [https://files.minecraftforge.net/ files] site. (Look for the MDK file type)
# Extract the downloaded source distribution to an empty directory. You should see a bunch of files, and an example mod is placed in <code>src/main/java</code> for you to look at. Only a few of these files are strictly necessary for mod development, and you may reuse these files for all your projects These files are:
#* <code>build.gradle</code>
#* <code>gradlew.bat</code>
#* <code>gradlew</code>
#* the <code>gradle</code> folder
# Move the files listed above to a new folder, this will be your mod project folder.
# Choose your IDE:
#* Forge explicitly supports developing with Eclipse or IntelliJ environments, but any environment, from Netbeans to vi/emacs, can be made to work.
#* For both Intellij IDEA and Eclipse their Gradle integration will handle the rest of the initial workspace setup, this includes downloading packages from Mojang, MinecraftForge, and a few other software sharing sites.
#* For most, if not all, changes to the build.gradle file to take effect Gradle will need to be invoked to re-evaluate the project, this can be done through Refresh buttons in the Gradle panels of both the previously mentioned IDEs.
# Generating IDE Launch/Run Configurations:
#*For Eclipse, run the <code>genEclipseRuns</code> gradle task (<code>gradlew genEclipseRuns</code>). This will generate the Launch Configurations and download any required assets for the game to run. After this has finished refresh your project.
#*or IntelliJ, run the <code>genIntellijRuns</code> gradle task (<code>gradlew genIntellijRuns</code>). This will generate the Run Configurations and download any required assets for the game to run. After this has finished edit your Configurations to fix the “module not specified” error by changing selecting your “main” module.

=== Customizing Your Mod Information ===
Edit the <code>build.gradle</code> file to customize how your mod is built (the file names, versions, and other things).

{{Tip/Important|'''Do not''' edit the <code>buildscript {}</code> section of the build.gradle file, its default text is necessary for ForgeGradle to function.}}

Almost anything underneath the <code>// Only edit below this line, the above code adds and enables the necessary things for Forge to be setup.</code> marker can be changed, many things can be removed and customized there as well.

There is a whole site dedicated to customizing the forge <code>build.gradle</code> files - the [https://forgegradle.readthedocs.org/en/latest/cookbook/ ForgeGradle cookbook]. Once you’re comfortable with your mod setup, you’ll find many useful recipes there.

==== Simple build.gradle Customizations ====
These customizations are highly recommended for all projects.
* To change the name of the file you build - edit the value of <code>archivesBaseName</code> to suit.
* To change your “maven coordinates” - edit the value of <code>group</code> as well.
* To change the version number - edit the value of <code>version</code>.
* To update the run configurations - replace all occurrences of <code>examplemod</code> to the mod id of your mod.

=== Building and Testing Your Mod ===
# To build your mod, run <code>gradlew build</code>. This will output a file in <code>build/libs</code> with the name <code>[archivesBaseName]-[version].jar</code>. This file can be placed in the <code>mods</code> folder of a forge enabled Minecraft setup, and distributed.
# To test run with your mod, the easiest way is to use the run configs that were generated when you set up your project. Otherwise, you can run <code>gradlew runClient</code>. This will launch Minecraft from the <code><runDir></code> location, including your mod code. There are various customizations to this command. Consult the [https://forgegradle.readthedocs.org/en/latest/cookbook/ ForgeGradle cookbook] for more information.
# You can also run a dedicated server using the server run config, or <code>gradlew runServer</code>. This will launch the Minecraft server with its GUI.

{{Colored box|title=Note|content=It is always advisable to test your mod in a dedicated server environment if it is intended to run there.}}

[[Category:Getting Started]]

Datageneration/Loot Tables

2020-12-20T22:26:26Z

Unbekannt: WIP and it is horriable

{{Under construction}}
Loot Tables are not so polished like the other Providers. You need need to do some work to get them to a good state.

== Preperation ==
First you would need a new Class that extend the <code>LootTableProvider</code>. In this class you would override the <code>act</code> and optionally <code>getName</code> Method.
In the <code>getName</code> you just return the Name shown in the Logs.
Also you should create a abstract Method which you would override in subclasses but this is not strickly needded.
Also you need a Gson constant. You would create it like this <code> private static final Gson GSON = new GsonBuilder().setPrettyPrinting().disableHtmlEscaping().create(); </code>
You should also save the <code>DataGenerator</code> for later use since you can't access from the <code>LootTableProvider</code>.
Also you would need two Maps, one with the the Class witch is used to get the Lootable Resource Location in this example the Block and one the Loot Table Builder.
The second Map consist of a <code>ResourceLocation</code> and the actual <code>LootTable</code>. Look at the Code for more info.

<syntaxhighlight lang="java">
private static final Gson GSON = new GsonBuilder().setPrettyPrinting().disableHtmlEscaping().create();

protected final Map<Block, LootTable.Builder> lootTables = new HashSet<>();
public static Map<ResourceLocation, LootTable> tables = new HashMap<>();
protected final DataGenerator generator;
</syntaxhighlight>

Also you would need a Function to save the Tables
<syntaxhighlight lang="java">
private void writeTables(DirectoryCache cache, Map<ResourceLocation, LootTable> tables) {
Path outputFolder = this.generator.getOutputFolder();
tables.forEach((key, lootTable) -> {
Path path = outputFolder.resolve("data/" + key.getNamespace() + "/loot_tables/" + key.getPath() + ".json");
try {
IDataProvider.save(GSON, cache, LootTableManager.toJson(lootTable), path);
} catch (IOException e) {
LOGGER.error("Couldn't write loot table {}", path, (Object) e);
}
});
}
</syntaxhighlight>

For the writeTables method you would need to convert the First Map to the second map, for this we need to iterate over the first map.
<syntaxhighlight lang="java">
lootTables.forEach(blockBuilderMap -> {
for (Map.Entry<Block, LootTable.Builder> entry : blockBuilderMap.entrySet()) {
tables.put(entry.getKey().getLootTable(), entry.getValue().build());
}
});
</syntaxhighlight>

in the act Method you would then first call the Method where you create the tables or just create them in there (if you do you can ignore the next section), then you would convert the Tables and at last you would save the loottables.

== The actual Class for Lootables ==
=== Another class (Optional) ===
Create a new class that extends from the Class you created in the Section above and override the abstract function in there you can begin to create your Lootables

=== The LootPool Builder ===
This is where the magic happens /s.

DynamicOps

2020-12-19T09:07:48Z

Unbekannt: Corret Link

<code>DynamicOps</code> is a helper interface that's used to convert files into data types and vice versa. Their usages will probably never be explored by most modders. They are overshadowed by [[codecs]].

== <code>NBTDynamicOps</code> ==

<code>NBTDynamicOps</code> is a handler that converts an NBT file to an <code>INBT</code> tag. They are also used to parse information from codecs to send them across networks.

There is only one public instance of <code>NBTDynamicOps</code>: <code>INSTANCE</code>.

== <code>JsonOps</code> ==

<code>JsonOps</code> are similar in which they convert a JSON file into a <code>JsonElement</code>. These are usually used in conjunction with codecs as well to serialize/deserialize instances.

There are two public instances of <code>JsonOps</code>: <code>INSTANCE</code> and <code>COMPRESSED</code>. Compressed data is represented as a single string to read/write. However, this is never used within vanilla itself.

Recipes

2020-12-19T08:52:28Z

Unbekannt: removed old Block

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 [https://mcforge.readthedocs.io/en/latest/utilities/recipes/datapacks.md datapacks]. 

== Loading Recipes ==
Forge will load all recipes which can be found within the <code><nowiki>./data/<modid>/recipes/</nowiki></code> folder. You can call these files whatever you want, thought 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":
[
"xxa",
"x x",
"xxx"
],
"key":
{
"x":
{
"tag": "forge:gems/diamond"
},
"a":
{
"item": "mymod:myfirstitem",
}
},
"result":
{
"item": "mymod:myitem",
"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.}}

=== Type ===
The type of a recipe with the type field. You can think of this as the definition of which crafting layout is to be used, for example <code><nowiki>minecraft:crafting_shaped</nowiki></code> or <code><nowiki>minecraft:crafting_shapeless</nowiki></code>.

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

== Types of crafting recipes ==
Within this section we will take a closer look on 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. A pattern 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 on the other hand define what items are to be used instead of the placeholders. A key is defined by a placeholder character and the item.

=== Shapeless crafting ===
A shapeless recipe doesn’t make use of the <code><nowiki>pattern</nowiki></code> and <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 which 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 does only allow 9 items to be placed for each crafting recipe.}}
The following example shows how an ingredient list looks like within JSON.
<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 seen 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 patterns and 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 multiply items as it 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> has to have a result tag to define the output item.

When crafting something, you can get out more than one item. This is achieved by defining the <code><nowiki>count</nowiki></code> number. 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 for the result.

Debug Profiler

2020-12-19T08:38:16Z

Unbekannt: update Block to Colored Box

Minecraft provides a Debug Profiler that can be used to find time consuming code. Specially considering things like TickEvents and Ticking TileEntities this can be very useful for modders and server owners that want to find a lag source.

== Using the Debug Profiler ==

The Debug Profiler is very simple to use. It requires two commands <code><nowiki>/debug start</nowiki></code>, which starts the profiling process, and <code><nowiki>/debug stop</nowiki></code>, which ends it. The important part here is that the more time you give it to collect the data the better the results will be. It is recommended to at least let it collect data for a minute.

{{Colored box|title=Tip|content=Naturally, you can only profile code paths that are actually being reached. Entities and TileEntities that you want to profile must exist in the world to show up in the results.}}

After you’ve stopped the debugger it will create a new file, it can be found within the <code><nowiki>debug</nowiki></code> subdirectory in your run directory. The file name will be formatted with the date and time as <code><nowiki>profile-results-yyyy-mm-dd_hh.mi.ss.txt</nowiki></code>.

== Reading a Profiling result ==

At the top it first tells you how long in milliseconds it was running and how many ticks ran in that time.

Below that, you will find information similar to the snippet below:

<syntaxhighlight>
[00] levels - 96.70%/96.70%
[01] | World Name - 99.76%/96.47%
[02] | | tick - 99.31%/95.81%
[03] | | | entities - 47.72%/45.72%
[04] | | | | regular - 98.32%/44.95%
[04] | | | | blockEntities - 0.90%/0.41%
[05] | | | | | unspecified - 64.26%/0.26%
[05] | | | | | minecraft:furnace - 33.35%/0.14%
[05] | | | | | minecraft:chest - 2.39%/0.01%
</syntaxhighlight>

Here is a small explanation of what each part means

{| class="wikitable sortable" border=1
! [02] !! tick !! 99.31% !! 95.81%
|-
| The Depth of the section || The Name of the Section || The percentage of time it took in relation to it’s parent. For Layer 0 it’s the percentage of the time a tick takes, while for Layer 1 it’s the percentage of the time its parent takes || The second Percentage tells you how much Time it took from the entire tick.
|-
|}

== Profiling your own code ==

The Debug Profiler has basic support for <code><nowiki>Entity</nowiki></code> and <code><nowiki>TileEntity</nowiki></code>. If you would like to profile something else, you may need to manually create your sections like so:

<syntaxhighlight lang="Java">
Profiler#startSection(yourSectionName : String);
''The code you want to profile
Profiler#endSection();
</syntaxhighlight>

You can obtain the the <code><nowiki>Profiler</nowiki></code> instance from a <code><nowiki>World</nowiki></code>, <code><nowiki>MinecraftServer</nowiki></code>, or <code><nowiki>Minecraft</nowiki></code> instance. Now you just need to search the File for your section name.

Block Entities

2020-12-19T08:33:01Z

Unbekannt: update the Blocks with the Cplored Box

Tile entities are like simplified entities that are bound to a <code>Block</code>. They are used to store dynamic data, execute tick based tasks and for dynamic rendering. Some examples from vanilla Minecraft would be: handling of inventories (chests), smelting logic on furnaces, or area effects for beacons. More advanced examples exist in mods, such as quarries, sorting machines, pipes, and displays.

{{Colored box|title=Tip|content=A <code>TileEntity</code> isn’t a solution for everything, and they can cause lag when used wrongly. When possible, try to avoid them.}}

== Creating a <code>TileEntity</code> ==

In order to create a <code>TileEntity</code> you need to extend the <code>TileEntity</code> class. To register it, listen for the appropriate registry event and create a <code>TileEntityType</code>:
<syntaxhighlight lang="java">
@SubscribeEvent
public static void registerTE(RegistryEvent.Register<TileEntityType<?>> evt) {
TileEntityType<?> type = TileEntityType.Builder.create(factory, validBlocks).build(null);
type.setRegistryName("examplemod", "myte");
evt.getRegistry().register(type);
}
</syntaxhighlight>
You can also use a <code>DeferredRegister</code> instead.
<syntaxhighlight lang="java">
public static final DeferredRegister<TileEntityType<?>> TILE_ENTITIES = DeferredRegister.create(ForgeRegistries.TILE_ENTITIES, "examplemod");

public static final RegistryObject<TileEntityType<?>> MY_TE = TILE_ENTITIES.register("myte", () -> TileEntityType.Builder.create(factory, validBlocks).build(null));
</syntaxhighlight>

In this example, <code>factory</code> is a function that creates a new instance of your <code>TileEntity</code>. A method reference or a lambda is commonly used. The variable <code>validBlocks</code> is one or more blocks (<code><nowiki>TileEntityType$Builder::create</nowiki></code> is varargs) that the tile entity can exist for.

== Attaching a <code>TileEntity</code> to a <code>Block</code> ==
To attach your new <code>TileEntity</code> to a <code>Block</code> you need to override 2 (two) methods within the <code>Block</code> class.
<syntaxhighlight lang="java">
IForgeBlock#hasTileEntity(BlockState state)

IForgeBlock#createTileEntity(BlockState state, IBlockReader world)
</syntaxhighlight>
Using the parameters you can choose if the block should have a <code>TileEntity</code> or not. Usually you will return true in the first method and a new instance of your <code>TileEntity</code> in the second method.

== Storing Data within your <code>TileEntity</code> ==
In order to save data, override the following two methods
<code>
TileEntity#write(CompoundNBT nbt)

TileEntity#read(BlockState state, CompoundNBT nbt)
</code>
These methods are called whenever the <code>Chunk</code> containing the <code>TileEntity</code> gets loaded from/saved to NBT. Use them to read and write to the fields in your tile entity class.

{{Colored box|title=Tip|content=Whenever your data changes you need to call <code><nowiki>TileEntity#markDirty()</nowiki></code>, otherwise the <code>Chunk</code> containing your <code>TileEntity</code> might be skipped while the world is saved.}}

{{Colored box|title=Important|content=It is important that you call the super methods!

The tag names <code>id</code>, <code>x</code>, <code>y</code>, <code>z</code>, <code>ForgeData</code> and <code>ForgeCaps</code> are reserved by the super methods.}}

== Ticking <code>TileEntity</code> ==
If you need a ticking <code>TileEntity</code>, for example to keep track of the progress during a smelting process, you need to add the <code><nowiki>ITickableTileEntity</nowiki></code> interface to your <code>TileEntity</code>. Now you can implement all your calculations within
<syntaxhighlight lang="java">
ITickableTileEntity#tick()
</syntaxhighlight>

{{Colored box|title=Tip|content=This method is called each tick. Therefore, you should avoid having complicated calculations in here. If possible, you should make more complex calculations just every X ticks. (The amount of ticks in a second may be lower than 20 (twenty) but won’t be higher)}}

== Synchronizing the Data to the Client ==
There are 3 (three) ways of syncing data to the client. Synchronizing on chunk load, synchronizing on block updates and synchronizing with a custom network message.
=== Synchronizing on chunk load ===
For this you need to override
<syntaxhighlight lang="java">
TileEntity#getUpdateTag()

IForgeTileEntity#handleUpdateTag(BlockState state, CompoundNBT tag)
</syntaxhighlight>
Again, this is pretty simple, the first method collects the data that should be send to the client, while the second one processes that data. If your <code>TileEntity</code> doesn’t contain much data you might be able to use the methods out of the [[#storing_data|Storing Data]] section.

{{Colored box|title=Important|content=Synchronizing excessive/useless data for tile entities can lead to network congestion. You should optimize your network usage by sending only the information the client needs when the client needs it. For instance, it is more often than not unnecessary to send the inventory of a tile entity in the update tag, as this can be synchronized via its GUI.)}}

=== Synchronizing on block update ===
This method is a bit more complicated, but again you just need to override 2 methods. Here is a tiny example implementation of it
<syntaxhighlight lang="java">
@Override
public SUpdateTileEntityPacket getUpdatePacket(){
CompoundNBT nbtTag = new CompoundNBT();
//Write your data into the nbtTag
return new SUpdateTileEntityPacket(getPos(), -1, nbtTag);
}

@Override
public void onDataPacket(NetworkManager net, SUpdateTileEntityPacket pkt){
CompoundNBT tag = pkt.getNbtCompound();
//Handle your Data
}
</syntaxhighlight>
The Constructor of <code>SUpdateTileEntityPacket</code> takes:
* The position of your <code>TileEntity</code>.
* An ID, though it isn’t really used besides by Vanilla, therefore you can just put a -1 in there.
* An <code>CompoundNBT</code> which should contain your data.

Now, to send the packet, an update notification must be given on the server.
<code>
World#notifyBlockUpdate(BlockPos pos, BlockState oldState, BlockState newState, int flags)
</code>
The <code>pos</code> should be your <code>TileEntity</code>’s position. For <code>oldState</code> and <code>newState</code> you can pass the current <code>BlockState</code> at that position. The <code>flags</code> are a bitmask and should contain <code>2</code>, which will sync the changes to the client. See <code>Constants$BlockFlags</code> for more info as well as the rest of the flags. The flag <code>2</code> is equivalent to <code><nowiki>Constants$BlockFlags#BLOCK_UPDATE</nowiki></code>.

=== Synchronizing using a custom network message ===

This way of synchronizing is probably the most complicated one, but is usually also the most optimized one, as you can make sure that only the data you need to be synchronized is actually synchronized. You should first check out the <code>[[latest:advanced:networking:start|Networking]]</code> section and especially <code>[[latest:advanced:networking:simplechannel|SimpleImpl]]</code> before attempting this. Once you’ve created your custom network message, you can send it to all users that have the <code>TileEntity</code> loaded with:
<syntaxhighlight lang="java">
SimpleChannel#send(PacketDistributor.TRACKING_CHUNK.with(() -> chunk), MSG);
</syntaxhighlight>
{{Colored box|title=Alert|content=It is important that you do safety checks, the TileEntity might already be destroyed/replaced when the message arrives at the player! You should also check if the area is loaded using (<code><nowiki>World#isAreaLoaded(BlockPos, int)</nowiki></code>)}}

Datageneration/I18n

2020-11-11T21:04:10Z

Unbekannt: Inital Creation short but the most important info should be there

Lang Files can be generated by creating an extension of the File <code>LangurageProvider</code> class. From there you can add the Translations in the <code>addTranslations</code> Method, you must override.

To add a Translation you call the <code>LanguageProvider#add</code> method, this method takes the [[Internationalization|translation key]] and a String which is the displayname for the key.

Access Transformers

2020-11-11T15:58:30Z

Unbekannt: changed old Block to new Colored box

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

== Visibility ==

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

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

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

== How It Works ==

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

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

A random example to understand the syntax:

<code ->
public net.minecraft.util.palette.IResizeCallback # makes IResizeCallback public
</code>

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

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

== Using Access Transformers in your mod ==

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

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

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

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

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

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

Datageneration/Tags

2020-11-05T14:39:39Z

Unbekannt: some style fixes

{{Under construction}}

Tags can be generated by extending the <code>ItemTagsProvider</code> for Items or <code>BlockTagsProvider</code> for Blocks. For Custom Objects you would need to expand <code>TagsProvider</code> and give it the Object you want tags for. For the registration of you Tags you need to override the <code>TagsProvider#registerTags</code> method.

{{Colored box|title=Information|content=You can still use <code>TagsProvider</code> for Items and Blocks but you would need to implement a lot of stuff that is already done in <code>ItemTagsProvider</code> and <code>BlockTagsProvider</code>}}

==Items/Blocks==
First you should make a <code>ITag.INamedTag</code>(NamedTag) with <code>ItemTags#makeWrapperTag</code> for Items or <code>BlockTags#makeWrapperTag</code> for blocks, this will take the name of you Tag, see [[Tags#Conventions]]

for more info. After you have the <code>NamedTag</code> you can start with the actual creation of the Tag, you would first call <code>TagsProvider#getOrCreateBuilder</code> which takes the NamedTag as an Argument, this returns a <code>TagsProvider.Builder</code>. Now you can with <code>TagsProvider.Builder#add</code> add one or more Items/Blocks or other Tags to your own Tags.

Example for an Item Tag:
<syntaxhighlight lang="java">
ITag.INamedTag<Item> copperTag = ItemTags.makeWrapperTag("forge:ore/copper");
getOrCreateBuilder(copperTag).add(Init.COPPER_ORE_ITEM.get());
</syntaxhighlight>

==Custom Type for Tags==
TBD

Datageneration/Tags

2020-11-05T14:38:22Z

Unbekannt: added {{Under construction}}

<span style="color: rgb(220, 221, 222); --darkreader-inline-color:#d3cfc9;" andale="" mono="" wt",="" "andale="" mono",="" "lucida="" console",="" sans="" typewriter",="" "dejavu="" "bitstream="" vera="" "liberation="" "nimbus="" l",="" monaco,="" "courier="" new",="" courier,="" monospace;="" font-size:="" 13.6px;="" font-style:="" normal;="" font-variant-ligatures:="" font-variant-caps:="" font-weight:="" 400;="" letter-spacing:="" orphans:="" 2;="" text-align:="" start;="" text-indent:="" 0px;="" text-transform:="" none;="" white-space:="" pre-wrap;="" widows:="" word-spacing:="" -webkit-text-stroke-width:="" background-color:="" rgb(47,="" 49,="" 54);="" text-decoration-style:="" initial;="" text-decoration-color:="" display:="" inline="" !important;="" float:="" none;"="" data-darkreader-inline-color="">{{Under construction}}</span>

<style data-mw-deduplicate="TemplateStyles:r2197">.mw-parser-output .mw-tpl-construction{display:flex;align-items:center;width:75%;margin:auto;border-radius:0.2em;background:rgb(27,32,35);box-shadow:0 0 0.2em #999999;overflow:auto}.mw-parser-output .mw-tpl-construction-title{color:#FFFFFF;font-size:120%;font-weight:bold;padding:0.25em 1em}.mw-parser-output .mw-tpl-construction-title-icon{float:left;opacity:0.8;margin:1em}.mw-parser-output .mw-tpl-construction-content{padding:0.5em 1em 0.5em 1em;color:#FFFFFF}</style><style class="darkreader darkreader--sync" media="screen"></style><img alt="" src="/images/d/dc/Under_construction.svg" class="mw-tpl-construction-title-icon" width="60" height="60">This page is under construction.This page is incomplete, and needs more work. Feel free to edit and improve this page!

Tags can be generated by extending the <code>ItemTagsProvider</code> for Items or <code>BlockTagsProvider</code> for Blocks. For Custom Objects you would need to expand <code>TagsProvider</code> and give it the Object you want tags for. For the registration of you Tags you need to override the <code>TagsProvider#registerTags</code> method.

{{Colored box|title=Information|content=You can still use <code>TagsProvider</code> for Items and Blocks but you would need to implement a lot of stuff that is already done in <code>ItemTagsProvider</code> and <code>BlockTagsProvider</code>}}

<style data-mw-deduplicate="TemplateStyles:r2068">.mw-parser-output .mw-tpl-colorbox{box-sizing:border-box;margin:0.5em 0.5em 1em 0.5em;border-radius:0.2em;background:rgb(27,32,35);box-shadow:0 0 0.2em #999999}.mw-parser-output .mw-tpl-colorbox-title{background:rgb(0,71,127);color:#FFFFFF;border-radius:0.2em 0.2em 0 0;padding:0.5em 1em 0.5em 1em}.mw-parser-output .mw-tpl-colorbox-title-icon{opacity:0.8}.mw-parser-output .mw-tpl-colorbox-title-corner{float:right;font-size:0.7em}.mw-parser-output .mw-tpl-colorbox-content{padding:0.5em 1em 0.5em 1em;color:#FFFFFF}</style><style class="darkreader darkreader--sync" media="screen"></style><strong style="">Information</strong>You can still use <code>TagsProvider</code> for Items and Blocks but you would need to implement a lot of stuff that is already done in <code>ItemTagsProvider</code> and <code>BlockTagsProvider</code>

==Items/Blocks==
First you should make a <code>ITag.INamedTag</code>(NamedTag) with <code>ItemTags#makeWrapperTag</code> for Items or <code>BlockTags#makeWrapperTag</code> for blocks, this will take the name of you Tag, see [[Tags#Conventions]]

for more info. After you have the <code>NamedTag</code> you can start with the actual creation of the Tag, you would first call <code>TagsProvider#getOrCreateBuilder</code> which takes the NamedTag as an Argument, this returns a <code>TagsProvider.Builder</code>. Now you can with <code>TagsProvider.Builder#add</code> add one or more Items/Blocks or other Tags to your own Tags.

Example for an Item Tag:
<syntaxhighlight lang="java">
ITag.INamedTag<Item> copperTag = ItemTags.makeWrapperTag("forge:ore/copper");
getOrCreateBuilder(copperTag).add(Init.COPPER_ORE_ITEM.get());
</syntaxhighlight>

==Custom Type for Tags==
TBD

Datageneration/Tags

2020-11-04T17:45:46Z

Unbekannt: Inital write up still needs work in the Custom Type Section

Tags can be generated by extending the <code>ItemTagsProvider</code> for Items or <code>BlockTagsProvider</code> for Blocks. For Custom Objects you would need to expand <code>TagsProvider</code> and give it the Object you want tags for. For the registration of you Tags you need to override the <code>TagsProvider#registerTags</code> method.

{{Colored box|title=Information|content=You can still use <code>TagsProvider</code> for Items and Blocks but you would need to implement a lot of stuff that is already done in <code>ItemTagsProvider</code> and <code>BlockTagsProvider</code>}}

== Items/Blocks ==
First you should make a <code>ITag.INamedTag</code>(NamedTag) with <code>ItemTags#makeWrapperTag</code> for Items or <code>BlockTags#makeWrapperTag</code> for blocks, this will take the name of you Tag, see [[Tags#Conventions]] for more info. After you have the <code>NamedTag</code> you can start with the actual creation of the Tag, you would first call <code>TagsProvider#getOrCreateBuilder</code> which takes the NamedTag as an Argument, this returns a <code>TagsProvider.Builder</code>. Now you can with <code>TagsProvider.Builder#add</code> add one or more Items/Blocks or other Tags to your own Tags.

Example for an Item Tag:
<syntaxhighlight lang="java">
ITag.INamedTag<Item> copperTag = ItemTags.makeWrapperTag("forge:ore/copper");
getOrCreateBuilder(copperTag).add(Init.COPPER_ORE_ITEM.get());
</syntaxhighlight>

== Custom Type for Tags ==
TBD

Datageneration/Recipes

2020-11-04T16:44:52Z

Unbekannt: changed the old block tag to colored box

Recipes can be generated by creating an extension of Minecraft's <code>RecipeProvider</code> class. From there, recipes can be registered by overriding <code>RecipeProvider#registerRecipes</code>.

{{Colored box|title=Info|content=Remove the <code>super</code> call within the method. Otherwise, you will generate all recipes from Minecraft as well.}}

== Recipe Builders ==

All recipes need to be formatted as an <code>IFinishedRecipe</code>. Each vanilla recipe has a static constructor builder that can be used to create a finished recipe. These can be built by passing the required parameters and then calling <code><nowiki>#build</nowiki></code>.

{{Colored box|title=important|content=All recipes must have a different path. If two recipes have the same result, use <code><nowiki>#build(Consumer<IFinishedRecipe>, ResourceLocation)</nowiki></code> instead. This will allow you to specify a different name for the recipe such that it will not override the other.}}

There are six vanilla recipe builders: <code>ShapedRecipeBuilder</code> for shaped recipes, <code>ShapelessRecipeBuilder</code> for shapeless recipes, <code>CookingRecipeBuilder</code> for furnace type recipes, <code>CustomRecipeBuilder</code> for nondeterministic logic, <code>SingleItemRecipeBuilder</code> for stonecutting recipes, and <code>SmithingRecipeBuilder</code> for smithing recipes.

For any recipe to be valid, a criterion must be met to obtain the recipe within the recipe book. This can be attached via <code><nowiki>#addCriterion</nowiki></code>. The <code>RecipeProvider</code> class has some basic criteria creators to check whether a player's inventory has a certain item or whether a player has entered into a specific block.

== <code>ConditionalRecipe</code> ==

To specify if a recipe should be loaded at runtime, a <code>ConditionalRecipe</code> can be used in conjunction with a recipe builder. Conditions must be added before the recipe via <code>ConditionalRecipe$Builder#addCondition</code>. Then, once a recipe is added, all previous conditions are cleared for the next to be added. There are a few helper methods for conditions that can be implemented via <code>IConditionBuilder</code>.

User:Unbekannt

2020-11-04T16:38:12Z

Unbekannt: Created page with "Hi, i will mostly do back end stuff and Moderation in this wiki."

Hi,
i will mostly do back end stuff and Moderation in this wiki.

FCWMeta:Wiki Policy

2020-10-25T18:46:48Z

Unbekannt: Inital Import dokuwiki

= Wiki Policy =

This Community Wiki is governed by the same principles and follows a similar policy to the official [https://forums.minecraftforge.net/ Forge Forums] and the official [https://discord.gg/UvedJ9m Forge Discord].

== Staff ==
The staff is responsible for the whole wiki, and forms policies. The staff is divided into two groups: the Admins and the Mods.

The Admins are responsible for maintaining the site, and enforcing decisions through user rights management.
The Mods are responsible for curating the wiki and its contents, and can revert edits and delete pages.

=== Conflict of Interest ===
Staff members who are involved in a dispute or conflict may not use their powers to enforce their decision. An uninvolved Admin must be present to make and enforce a decision. If there are no uninvolved Admins, the decision must be made by deliberation of the staff, and this decision is final.

=== Admin Discretion ===
Admins may immediately respond and apply any action they deem necessary to any situation not covered under this policy. After any situation in which this policy is applied, Admins may deliberate with the staff to clarify this policy.

=== Appeals ===
If a user is unsatisfied with the decision made by any staff member, they may appeal to an uninvolved Admin, who may either maintain or overturn the decision, or if necessary deliberate with the staff to make a final decision. Any decision made by staff deliberation is final.

== Supported Versions ==
In keeping with the official policy of the Forge project, this wiki will only support and include information relating to the '''Latest''' and '''LTS''' versions. The currently supported versions are listed on the [https://github.com/MinecraftForge/MinecraftForge/blob/1.16.x/docs/README.md#minecraftforge README of the MinecraftForge repository].

== Violations ==
Users who violate this policy will be given an increasing amount of warnings and sanctions. These sanctions are not set in stone; they may vary from case to case, depending on the judgement of the acting Administrator, and the severity of the infraction.

In increasing order of severity, here are the applicable sanctions:

* Verbal warning
* Revocation of rights
** From the involved page/namespace
** From the site <code>(a.k.a read-only purgatory)</code>
* Deletion of account
* IP block

Sending Packets

2020-10-25T12:41:34Z

Unbekannt: Inital Import dokuwiki

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:

Using FriendlyByteBuf

2020-10-25T12:35:39Z

Unbekannt: Created page with "<code>PacketBuffer</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 i..."

<code>PacketBuffer</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>PacketBuffer</code>s ==

In most cases, one will use a premade <code>PacketBuffer</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 <code>writing</code> to a <code>PacketBuffer</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>CompoundNBT</code>, <code>ItemStack</code>s, etc. if they are needed.

When you are <code>reading</code> from a <code>PacketBuffer</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.

Named Binary Tag

2020-10-25T12:31:41Z

Unbekannt: Inital Import dokuwiki

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>CompoundNBT</code>s within a <code>TileEntity</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>INBT</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>EndNBT</code> || Specifies the end of an nbt file.
|-
| 1 || <code>ByteNBT</code> || Holds a byte. Also used to store a boolean value.
|-
| 2 || <code>ShortNBT</code> || Holds a short.
|-
| 3 || <code>IntNBT</code> || Holds an integer.
|-
| 4 || <code>LongNBT</code> || Holds a long.
|-
| 5 || <code>FloatNBT</code> || Holds a float.
|-
| 6 || <code>DoubleNBT</code> || Holds a double.
|-
| 7 || <code>ByteArrayNBT</code> || Holds a byte array. Can be parsed from an array of primitive bytes or a list of byte objects.
|-
| 8 || <code>StringNBT</code> || Holds a string.
|-
| 9 || <code>ListNBT</code> || Holds a list of a specific <code>INBT</code>.
|-
| 10 || <code>CompoundNBT</code> || Holds an object comprised of <code>INBT</code>s. It works similarly to a java object where it can store other primitives, objects, or itself inside.
|-
| 11 || <code>IntArrayNBT</code> || Holds an integer array. Can be parsed from an array of primitive integers or a list of integer objects.
|-
| 12 || <code>LongArrayNBT</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>NumberNBT</code> || Holds a generic number. Used when the specific <code>INBT</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>CompoundNBT</code> and <code>ListNBT</code>. The others are usually handled internally by whichever type uses them.

== Common Usages ==
<code>CompoundNBT</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>ListNBT</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.

Capabilities/Attaching

2020-10-25T12:22:56Z

Unbekannt: Inital Import dokuwiki

As mentioned, attaching capabilities to objects that you have not created can be done using <code>AttachCapabilitiesEvent</code>. The same event is used for all objects that can provide capabilities. <code>AttachCapabilitiesEvent</code> has five valid generic types providing the following events:
* <code><nowiki>AttachCapabilitiesEvent<Entity></nowiki></code>: Fires only for entities.
* <code><nowiki>AttachCapabilitiesEvent<TileEntity></nowiki></code>: Fires only for tile entities.
* <code><nowiki>AttachCapabilitiesEvent<ItemStack></nowiki></code>: Fires only for item stacks.
* <code><nowiki>AttachCapabilitiesEvent<World></nowiki></code>: Fires only for worlds.
* <code><nowiki>AttachCapabilitiesEvent<Chunk></nowiki></code>: Fires only for chunks.

The generic type cannot be more specific than the above types. For example: If you want to attach capabilities to <code>PlayerEntity</code>, you have to subscribe to the <code><nowiki>AttachCapabilitiesEvent<Entity></nowiki></code>, and then determine that the provided object is an <code>PlayerEntity</code> before attaching the capability.

In all cases, the event has a method <code>addCapability</code>, which can be used to attach capabilities to the target object. Instead of adding capabilities themselves to the list, you add capability providers, which have the chance to return capabilities only from certain sides. While the provider only needs to implement <code>ICapabilityProvider</code>, if the capability needs to store data persistently it is possible to implement <code><nowiki>ICapabilitySerializable<T extends INBT></nowiki></code> which, on top of returning the capabilities, will allow providing NBT save/load functions.

For information on how to implement <code>ICapabilityProvider</code>, refer to the [[Capabilities|a Capability]] section.

== Creating Your Own Capability ==
In general terms, a capability is declared and registered through a single method call to <code><nowiki>CapabilityManager#INSTANCE#register</nowiki></code>. One possibility is to define a static <code><nowiki>register</nowiki></code> method inside a dedicated class for the capability, but this is not required by the capability system. For the purpose of this documentation we will be describing each part as a separate named class, although anonymous classes are an option.
<syntaxhighlight lang="java">
CapabilityManager.INSTANCE.register(capability_interface_class, storage, default_implementation_factory);
</syntaxhighlight>
The first parameter to this method, is the type that describes the capability feature. In our example, this will be <code>IExampleCapability.class</code>.

The second parameter is an instance of a class that implements <code><nowiki>Capability.IStorage<T></nowiki></code>, where T is the same class we specified in the first parameter. This storage class will help manage saving and loading for the default implementation, and it can, optionally, also support other implementations.
<syntaxhighlight lang="java">
private static class Storage
implements Capability.IStorage<IExampleCapability> {

@Override
public INBT writeNBT(Capability<IExampleCapability> capability, IExampleCapability instance, Direction side) {
// return an NBT tag
}

@Override
public void readNBT(Capability<IExampleCapability> capability, IExampleCapability instance, Direction side, INBT nbt) {
// load from the NBT tag
}
}
</syntaxhighlight>
The last parameter is a callable factory that will return new instances of the default implementation.
<syntaxhighlight lang="java">
private static class Factory implements Callable<IExampleCapability> {

@Override
public IExampleCapability call() throws Exception {
return new Implementation();
}
}
</syntaxhighlight>
Finally, we will need the default implementation itself, to be able to instantiate it in the factory. Designing this class is up to you, but it should at least provide a basic skeleton that people can use to test the capability, if it’s not a fully usable implementation on itself.

== Persisting Chunk and TileEntity capabilities ==
Unlike <code>Worlds</code>, <code>Entities</code> and <code>ItemStacks</code>, <code>Chunks</code> and <code>TileEntities</code> are only written to disk when they have been marked as dirty. A <code>capability</code> implementation with persistent state for a <code>Chunk</code> or a <code>TileEntity</code> should therefore ensure that whenever its state changes, its owner is marked as dirty.

<code>ItemStackHandler</code>, commonly used for inventories in <code>TileEntities</code>, has an overridable method <code><nowiki>void onContentsChanged(int slot)</nowiki></code> designed to be used to mark the <code>TileEntity</code> as dirty.
<syntaxhighlight lang="java">
public class MyTileEntity extends TileEntity {

private final IItemHandler inventory = new ItemStackHandler(...) {
@Override
protected void onContentsChanged(int slot) {
super.onContentsChanged(slot);
markDirty();
}
}

...
}
</syntaxhighlight>
== Synchronizing Data with Clients ==
By default, Capability data is not sent to clients. In order to change this, the mods have to manage their own synchronization code using packets.

There are three different situation in which you may want to send synchronization packets, all of them optional:
# When the entity spawns in the world, or the block is placed, you may want to share the initialization-assigned values with the clients.
# When the stored data changes, you may want to notify some or all of the watching clients.
# When a new client starts viewing the entity or block, you may want to notify it of the existing data.

Refer to the [[Understanding Networking|Networking]] page for more information on implementing network packets.

== Persisting across Player Deaths ==
By default, the capability data does not persist on death. In order to change this, the data has to be manually copied when the player entity is cloned during the respawn process.

This can be done by handling the <code><nowiki>PlayerEvent.Clone</nowiki></code> event, reading the data from the original entity, and assigning it to the new entity. In this event, the <code>wasDead</code> field can be used to distinguish between respawning after death, and returning from the End. This is important because the data will already exist when returning from the End, so care has to be taken to not duplicate values in this case.

Capabilities

2020-10-25T12:11:14Z

Unbekannt: Inital Import dokuwiki

Capabilities allow exposing features in a dynamic and flexible way, without having to resort to directly implementing many interfaces.

In general terms, each capability provides a feature in the form of an interface, alongside with a default implementation which can be requested, and a storage handler for at least this default implementation. The storage handler can support other implementations, but this is up to the capability implementor, so look it up in their documentation before trying to use the default storage with non-default implementations.

Forge adds capability support to <code>TileEntities</code>, <code>Entities</code>, <code>ItemStack</code>s, <code>World</code>s and <code>Chunk</code>s, which can be exposed either by attaching them through an event or by overriding the capability methods in your own implementations of the objects. This will be explained in more detail in the following sections.

== Forge-provided Capabilities ==
Forge provides three capabilities: <code>IItemHandler</code>, <code>IFluidHandler</code> and <code>IEnergyStorage</code>.

<code>IItemHandler</code> exposes an interface for handling inventory slots. It can be applied to <code>TileEntities</code> (chests, machines, etc.), <code>Entities</code> (extra player slots, mob/creature inventories/bags), or <code>ItemStacks</code> (portable backpacks and such). It replaces the old <code>IInventory</code> and <code>ISidedInventory</code> with an automation-friendly system.

<code>IFluidHandler</code> exposes an interface for handling fluid inventories. It can also be applied to <code>TileEntities</code> <code>Entities</code>, or <code>ItemStacks</code>. It replaces the old <code>IFluidHandler</code> with a more consistent and automation-friendly system.

<code>IEnergyStorage</code> exposes an interface for handling energy containers. It can be applied to <code>TileEntities</code>, <code>Entities</code> or <code>ItemStacks</code>. It is based on the RedstoneFlux API by TeamCoFH.

== Using an Existing Capability ==
As mentioned earlier, <code>TileEntities</code>, <code>Entities</code>, and <code>ItemStacks</code> implement the capability provider feature, through the <code>ICapabilityProvider</code> interface. This interface adds the method <code>getCapability</code>, which can be used to query the capabilities present in the objects.

In order to obtain a capability, you will need to refer it by its unique instance. In the case of the <code>IItemHandler</code>, this capability is primarily stored in <code><nowiki>CapabilityItemHandler#ITEM_HANDLER_CAPABILITY</nowiki></code>, but it is possible to get other instance references by using the <code>@CapabilityInject</code> annotation.
<syntaxhighlight lang="java">
@CapabilityInject(IItemHandler.class)
static Capability<IItemHandler> ITEM_HANDLER_CAPABILITY = null;
</syntaxhighlight>
This annotation can be applied to fields and methods. When applied to a field, it will assign the instance of the capability (the same one gets assigned to all fields) upon registration of the capability, and left to the existing value (<code>null</code>), if the capability was never registered. Because local static field accesses are fast, it is a good idea to keep your own local copy of the reference for objects that work with capabilities. This annotation can also be used on a method, in order to get notified when a capability is registered, so that certain features can be enabled conditionally.

Both the <code>getCapability</code> methods have a second parameter, of type <code>Direction</code>, which can be used in the to request the specific instance for that one face. If passed <code>null</code>, it can be assumed that the request comes either from within the block, or from some place where the side has no meaning, such as a different dimension. In this case a general capability instance that does not care about sides will be requested instead. The return type of <code>getCapability</code> will correspond to the type declared in the capability passed to the method. For the item handler capability, this is indeed <code>IItemHandler</code>.

== Exposing a Capability ==

In order to expose a capability, you will first need an instance of the underlying capability type. Note that you should assign a separate instance to each object that keeps the capability, since the capability will most probably be tied to the containing object.

There’s two ways to obtain such an instance, through the <code>Capability</code> itself, or by explicitly instantiating an implementation of it. The first method is designed to use a default implementation via <code>Capability#getDefaultInstance</code>, if those default values are useful for you. In the case of the item handler capability, the default implementation will expose a single slot inventory, which is most probably not what you want.

The second method can be used to provide custom implementations. In the case of <code>IItemHandler</code>, the default implementation uses the <code>ItemStackHandler</code> class, which has an optional argument in the constructor, to specify a number of slots. However, relying on the existence of these default implementations should be avoided, as the purpose of the capability system is to prevent loading errors in contexts where the capability is not present, so instantiation should be protected behind a check testing if the capability has been registered (see the remarks about <code>@CapabilityInject</code> in the previous section).

Once you have your own instance of the capability interface, you will want to notify users of the capability system that you expose this capability and provide a holder of the instance. This is done by overriding the <code>getCapability</code> method, and comparing the instance with the capability you are exposing. If your machine has different slots based on which side is being queried, you can test this with the <code>side</code> parameter. For <code>Entities</code> and <code>ItemStack</code>s, this parameter can be ignored, but it is still possible to have side as a context, such as different armor slots on a player (top side => head slot?), or about the surrounding blocks in the inventory (west => slot on the left?). Don’t forget to fall back to <code>super</code>, otherwise the attached capabilities will stop working. Make sure to invalidate the holder of the instance at the end of the provider's lifecycle.

<syntaxhighlight lang="java">
// Somewhere in your TileEntity subclass
LazyOptional<IItemHandler> inventoryHandlerLazyOptional;

// After initializing inventoryHandler
inventoryHandlerLazyOptional = LazyOptional.of(() -> inventoryHandler);

public <T> LazyOptional<T> getCapability(Capability<T> cap, Direction side) {
if (cap == CapabilityItemHandler.ITEM_HANDLER_CAPABILITY) {
return inventoryHandlerLazyOptional.cast();
}
return super.getCapability(cap, side);
}

@Override
public void remove() {
super.remove();
inventoryHandlerLazyOptional.invalidate();
}
</syntaxhighlight>

<code>Item</code>s are a special case since their capability providers are stored on an <code>ItemStack</code>. Instead, a provider should be attached through <code>Item#initCapabilities</code> when applicable. This should hold your capabilities for the lifecycle of the stack.

It is strongly suggested that direct checks in code are used to test for capabilities instead of attempting to rely on maps or other data structures, since capability tests can be done by many objects every tick, and they need to be as fast as possible in order to avoid slowing down the game.

Sounds

2020-10-25T12:04:03Z

Unbekannt: update page links

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

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

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

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

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

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

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

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

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

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

== Playing Sounds ==

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

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

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

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

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

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

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

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

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

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

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

Sounds

2020-10-25T12:00:17Z

Unbekannt: Inital import dokuwiki

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

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

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

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

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

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

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

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

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

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

== Playing Sounds ==

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

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

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

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

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

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

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

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

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

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

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

Particles

2020-10-25T11:37:19Z

Unbekannt: Inital Import dokuwiki

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|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 an <code>IParticleData</code> to sync the information. On the client, an <code>IParticleFactory</code> is used to generate a <code>Particle</code> from the synced <code>IParticleData</code>. To be more specific, a <code>ParticleType<?></code> holds the registry reference of the particle itself. An <code>IParticleData</code> hooks into a <code>ParticleType<?></code> to send information to the <code>IParticleFactory</code>. An <code>IParticleFactory</code> creates the specified particle in some place within the world. 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>BasicParticleType</code>, a basic implementation of <code>ParticleType</code> and <code>IParticleData</code>. This is used whenever server data is not necessary to spawn the particle. The only vanilla particles that do not use <code>BasicParticleType</code> are redstone dust and block/item texture dependent particles. When requiring server data, a direct implementation of <code>IParticleData</code> is needed. A good way is to extend <code>ParticleType<?></code> and implement <code>IParticleData</code> on the same class. In the case of a more generic solution, an implementation of <code>IParticleData</code> can be referenced while the standard <code>ParticleType<?></code> class is used.

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

=== <code>IParticleData</code> ===

Beside the standard reference to a <code>ParticleType<?></code>, an <code>IParticleData</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">
IParticleData#write(PacketBuffer)

IParticleData$IDeserializer#read(ParticleType, PacketBuffer)
</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">
IParticleData#getParameters

IParticleData$IDeserializer#deserialize(ParticleType, StringReader)
</syntaxhighlight>

These two are used to read/write data to NBT as well as get information to spawn the particle in the world 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>SpriteTexturedParticle</code>. This abstract class renders a texture specified by the user as the particle to go according to the logic rendered.

=== <code>IParticleFactory</code>s ===
Finally, a particle must be created using an <code>IParticleFactory</code>. This simply just decides where the particle should be placed in the world 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.

An <code>IParticleFactory</code> must be attached to a <code>ParticleType</code> using <code>ParticleManager#registerFactory</code>. This should be called during <code>ParticleFactoryRegisterEvent</code> on the mod event bus.

{{Colored box|title=Important|content=<code>IParticleFactory</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 world instance. Each side, however, has a specific way of calling them. The <code>ClientWorld</code> can call either <code>addParticle</code> or <code>addOptionalParticle</code>. The <code>ServerWorld</code> must call <code>spawnParticle</code> as it sends a packet to the client world to call one of the other two methods. Calling the two <code>ClientWorld</code> methods on the server will result in nothing happening.

Potions

2020-10-25T11:27:19Z

Unbekannt: Inital Import dokuwiki

A <code>Potion</code> is simply a list of <code>Effect</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 effects, potions need to be [[Registration|registered]].

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

A <code>Potion</code> requires a passed in list of <code>EffectInstance</code>s to apply to the player when the potion is "consumed". There is also a nullable parameter called <code>baseName</code> that can be set if you would like to use the same name for multiple potions (e.g. a <code>SWIFTNESS</code> and <code>LONG_SWIFTNESS</code> entry 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>.

{{Colored box|title=Important|content=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.}}

Mob Effects

2020-10-25T11:20:38Z

Unbekannt: Inital Import dokuwiki

An <code>Effect</code> is what handles the specific logic on the entity it is on. For example, <code>Effects#SPEED</code> adds an attribute modifier that affects the movement speed while <code>Effects#WITHER</code> attacks the entity from a <code>DamageSource</code> whenever the potion effect is ready to be applied.

== Creating an <code>Effect</code> ==

You can create an <code>Effect</code> using two methods. The first creates a regular <code>Effect</code> and applies the logic in some event method. The other method involves extending the <code>Effect</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 effect you are creating. In each scenario, you should take into account whether you should extend <code>Effect</code> or <code>InstantEffect</code>.

Here are the classes and methods to review:

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

{| class="wikitable sortable" border=1
!Method !!Description
|-
| <code>isReady</code> || Determines how fast an effect should call <code>performEffect</code> while applied. This is overridden by <code>InstantEffect</code> to occur after one tick. If too fast, the server will not have enough time to execute the damage on the entity.
|-
| <code>performEffect</code> || Executes the logic on the entity when called.
|-
| <code>isInstant</code> || Determines if the effect is instant. Returns true in <code>InstantEffect</code>.
|-
| <code>affectEntity</code> || Executes the logic on the entity when called. <code>isInstant</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 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.

Effects need to be [[Registration|registered]].

== <code>EffectInstance</code> ==

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

DynamicOps

2020-10-25T11:14:31Z

Unbekannt: Inital Import dokuwiki

<code>DynamicOps</code> is a helper interface that's used to convert files into data types and vice versa. Their usages will probably never be explored by most modders. They are overshadowed by [[latest:advanced:handle:codecs|codecs]].

== <code>NBTDynamicOps</code> ==

<code>NBTDynamicOps</code> is a handler that converts an NBT file to an <code>INBT</code> tag. They are also used to parse information from codecs to send them across networks.

There is only one public instance of <code>NBTDynamicOps</code>: <code>INSTANCE</code>.

== <code>JsonOps</code> ==

<code>JsonOps</code> are similar in which they convert a JSON file into a <code>JsonElement</code>. These are usually used in conjunction with codecs as well to serialize/deserialize instances.

There are two public instances of <code>JsonOps</code>: <code>INSTANCE</code> and <code>COMPRESSED</code>. Compressed data is represented as a single string to read/write. However, this is never used within vanilla itself.

Datageneration/States and Models

2020-10-25T11:10:56Z

Unbekannt: Inital Import dokuwiki

The model providers are a specific type of data generators for defining models. All model providers are a subclass of <code>ModelProvider</code>.

<code>ModelProvider</code> provides methods to define models for blocks and items alike: cubes, single textures, doors, slabs, and even custom non-data-generated models as parent models.

== Existing Files ==
All references to textures or other data files not generated for data generation must reference existing files on the system. This is to ensure that all referenced textures are in the correct places, so typos can be found and corrected.

<code>ExistingFileHelper</code> is the class responsible for validating the existence of those data files. An instance can be retrieved from <code><nowiki>GatherDataEvent#getExistingFileHelper()</nowiki></code>.

The <code><nowiki>--existing <folderpath></nowiki></code> argument allows the specified folder and its subfolders to be used when validating the existence of files. By default, only the vanilla datapack and resources are available to the <code>ExistingFileHelper</code>.

== Implementation ==
There are three main abstract implementations of <code>ModelProvider</code>: <code>ItemModelProvider</code>, <code>BlockModelProvider</code>, and <code>BlockStateProvider</code>.

For items, use <code>ItemModelProvider</code> to define their models: override <code>#generateModels</code> and use the helper methods.

For blocks, it is recommended to use <code>BlockStateProvider</code> to define the blockstates, models, and their item models in a single class. It contains an instance of both <code>BlockModelProvider</code> and <code>ItemModelProvider</code>, which can be accessed through <code>#models()</code> and <code><nowiki>#itemModels()</nowiki></code>. <code>BlockModelProvider</code> is used to define only block models.

Call <code><nowiki>#getVariantBuilder(Block)</nowiki></code> to get a <code><nowiki>VariantBlockStateBuilder</nowiki></code> for building a blockstate with different variants, or <code><nowiki>#getMultipartBuilder(Block)</nowiki></code> to get a <code>MultiPartBlockStateBuilder</code> for building a blockstate using multiparts.

Datageneration/Recipes

2020-10-25T11:04:02Z

Unbekannt: Inital Import dokuwiki

Recipes can be generated by creating an extension of Minecraft's <code>RecipeProvider</code> class. From there, recipes can be registered by overriding <code>RecipeProvider#registerRecipes</code>.

{{Colored box|title=Info|content=Remove the <code>super</code> call within the method. Otherwise, you will generate all recipes from Minecraft as well.}}

== Recipe Builders ==

All recipes need to be formatted as an <code>IFinishedRecipe</code>. Each vanilla recipe has a static constructor builder that can be used to create a finished recipe. These can be built by passing the required parameters and then calling <code><nowiki>#build</nowiki></code>.

<block important>All recipes must have a different path. If two recipes have the same result, use <code><nowiki>#build(Consumer<IFinishedRecipe>, ResourceLocation)</nowiki></code> instead. This will allow you to specify a different name for the recipe such that it will not override the other.</block>

There are six vanilla recipe builders: <code>ShapedRecipeBuilder</code> for shaped recipes, <code>ShapelessRecipeBuilder</code> for shapeless recipes, <code>CookingRecipeBuilder</code> for furnace type recipes, <code>CustomRecipeBuilder</code> for nondeterministic logic, <code>SingleItemRecipeBuilder</code> for stonecutting recipes, and <code>SmithingRecipeBuilder</code> for smithing recipes.

For any recipe to be valid, a criterion must be met to obtain the recipe within the recipe book. This can be attached via <code><nowiki>#addCriterion</nowiki></code>. The <code>RecipeProvider</code> class has some basic criteria creators to check whether a player's inventory has a certain item or whether a player has entered into a specific block.

== <code>ConditionalRecipe</code> ==

To specify if a recipe should be loaded at runtime, a <code>ConditionalRecipe</code> can be used in conjunction with a recipe builder. Conditions must be added before the recipe via <code>ConditionalRecipe$Builder#addCondition</code>. Then, once a recipe is added, all previous conditions are cleared for the next to be added. There are a few helper methods for conditions that can be implemented via <code>IConditionBuilder</code>.

Datageneration

2020-10-25T10:50:46Z

Unbekannt: Intial Import dokuwiki

Data generators are a way to programmatically generate the assets and data of mods. It allows the definition of the contents of these files in the code and their automatic generation, without worrying about the specifics.

The data generator system is loaded by the main class <code>net.minecraft.data.Main</code>. Different command-line arguments can be passed to customize which mods’ data are gathered, what existing files are considered, etc. The class responsible for data generation is <code>net.minecraft.data.DataGenerator</code>.

The default configurations in the MDK <code>build.gradle</code> adds the <code>runData</code> task for running the data generators.

== Generator Modes ==
The data generator can be configured to run 4 different data generations, which are configured from the command-line parameters, and can be checked from <code><nowiki>GatherDataEvent#include()</nowiki></code> methods.
* <code>Client Assets</code>
** Generates client-only files in <code>assets</code>: <code>block</code>/<code>item</code> models, <code>blockstate JSON</code>s, language files, etc.
** <code><nowiki>--client</nowiki></code>, <code><nowiki>includeClient()</nowiki></code>
* <code>Server Data</code>
** Generates server-only files in <code>data</code>: <code>recipes</code>, <code>advancements</code>, <code>tags</code>, etc.
** <code><nowiki>--server</nowiki></code>, <code><nowiki>includeServer()</nowiki></code>
* <code>Development Tools</code>
** Runs some development tools: converting SNBT to NBT and vice-versa, etc.
** <code><nowiki>--dev</nowiki></code>, <code>includeDev()</code>
* <code>Reports</code>
** Dumps all registered blocks, items, commands, etc.
** <code><nowiki>--reports</nowiki></code>, <code>includeReports()</code>

== Data Providers ==
Data providers are the classes that actually define what data will be generated and provided. All data providers implement <code>IDataProvider</code>. Minecraft has abstract implementations for most assets and data, so modders need only to extend and override the specified method.

The <code>GatherDataEvent</code> is fired on the mod event bus when the data generator is being created, and the <code>DataGenerator</code> can be obtained from the event. Create and register data providers using <code><nowiki>DataGenerator#addProvider</nowiki></code>.
=== Client Assets ===
* <code>net.minecraftforge.common.data.LanguageProvider</code> - for language strings; override <code><nowiki>#addTranslations</nowiki></code>
* <code><nowiki>ModelProvider<?></nowiki></code> - base class for all model providers
** ''These classes are under the <code>net.minecraftforge.client.model.generators</code> package''
*** <code>ItemModelProvider</code> - for item models; override <code>#registerModels</code>
*** <code>BlockStateProvider</code> - for blockstates and their block and item models; override <code>#registerStatesAndModels</code>
*** <code>BlockModelProvider</code> - for block models; override <code>#registerModels</code>

=== Server Data ===
* ''These classes are under the <code>net.minecraft.data</code> package''
* <code>LootTableProvider</code> - for loot tables; override <code>#getTables</code>
* <code>RecipeProvider</code> - for recipes and their unlocking advancements; override <code>#registerRecipes</code>
* <code>TagsProvider</code> - for tags; override <code>#registerTags</code>

{{Colored box|title=Tip|content=An <code>AdvancementProvider</code> class does exists, however it is hardcoded for only the vanilla advancements.}}

Toolchain

2020-10-24T22:03:17Z

Unbekannt: changed ref to right position

This page will explain <code>decompile</code>-><code>deobfuscate</code>-><code>reobfuscate</code> process that forge uses when you install the <code>MDK</code>.

== Why we need to do this ==
Minecraft is a commercial game, which means the source code is locked away, and not only is the source code unavailable to us, but they obfuscate the game code.

If you look into the client/server JAR, you'll see that all the class names have short, nonsense names like <code>aa</code>, <code>ab</code>, <code>xy</code>, etc. This is called Obfuscating.
The problem is, we don't<ref name="license">Mojang recently released this information in what we call <code>mojmappings</code>, but the licensing is a bit iffy [https://cpw.github.io/MinecraftMappingData For more info]</ref> have the information to convert those nonsensical names to readable, understandable names.
So we need a toolchain to make it possible for us to read the source code so we can mod the game.

For more information about [https://en.wikipedia.org/wiki/Obfuscation_(software) Obfiscating].

== Deobfuscation ==
First the obfuscated names need unique names. Since there could be some methods with the same name, the resulting code then would not compile.

For this all of these obfuscated classes/methods/fields are assigned a number. This number increments sequentially and is called the <code>SRG ID</code>((SRG stands for Searge, which was one of the co-founders of the original set of scripts and programs which did this in the beginning)) of that class/method/field, this ensures all these classes/methods/fields (henceforth called members) have a unique name.\\
These IDs are converted to <code>SRG</code> names, also called <code>Notch names</code>, simply by combining their ID and the type of member\\
<code>class</code> -> <code>c_XXX_</code> (you won't ever see this because of reasons, explained later)\\
<code>function</code> -> <code>func_XXX_</code>\\
<code>field</code> -> <code>field_XXX_</code>\\
<code>parameter</code> -> <code>p_XXX_X_</code> (there are two types of parameter names, also explained later)\\
These Ids will be gernerated automatically.

== Decompilation ==
More general [https://en.wikipedia.org/wiki/Decompiler info]

=== FernFlower/ForgeFlower ===
Forge uses [https://github.com/MinecraftForge/ForgeFlower ForgeFlower], which is a Fork of [https://github.com/MinecraftForge/FernFlower FernFlower].
FernFlower is a decompiler that takes the compiled Minecraft Jar and turn it in to semi readable source code.

Why semi readable?<br >
Because the decompiler has no sense of formatting or indentation.

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

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

== Reobfuscation ==
TBD

<references/>

Toolchain

2020-10-24T22:00:55Z

Unbekannt: Inital Import dokuwiki

This page will explain <code>decompile</code>-><code>deobfuscate</code>-><code>reobfuscate</code> process that forge uses when you install the <code>MDK</code>.

== Why we need to do this ==
Minecraft is a commercial game, which means the source code is locked away, and not only is the source code unavailable to us, but they obfuscate the game code.

If you look into the client/server JAR, you'll see that all the class names have short, nonsense names like <code>aa</code>, <code>ab</code>, <code>xy</code>, etc. This is called Obfuscating.
The problem is, we don't((Mojang recently released this information in what we call <code>mojmappings</code>, but the licensing is a bit iffy<ref name="license">[https://cpw.github.io/MinecraftMappingData For more info]</ref> have the information to convert those nonsensical names to readable, understandable names.
So we need a toolchain to make it possible for us to read the source code so we can mod the game.

For more information about [https://en.wikipedia.org/wiki/Obfuscation_(software) Obfiscating].

== Deobfuscation ==
First the obfuscated names need unique names. Since there could be some methods with the same name, the resulting code then would not compile.

For this all of these obfuscated classes/methods/fields are assigned a number. This number increments sequentially and is called the <code>SRG ID</code>((SRG stands for Searge, which was one of the co-founders of the original set of scripts and programs which did this in the beginning)) of that class/method/field, this ensures all these classes/methods/fields (henceforth called members) have a unique name.\\
These IDs are converted to <code>SRG</code> names, also called <code>Notch names</code>, simply by combining their ID and the type of member\\
<code>class</code> -> <code>c_XXX_</code> (you won't ever see this because of reasons, explained later)\\
<code>function</code> -> <code>func_XXX_</code>\\
<code>field</code> -> <code>field_XXX_</code>\\
<code>parameter</code> -> <code>p_XXX_X_</code> (there are two types of parameter names, also explained later)\\
These Ids will be gernerated automatically.

== Decompilation ==
More general [https://en.wikipedia.org/wiki/Decompiler info]

=== FernFlower/ForgeFlower ===
Forge uses [https://github.com/MinecraftForge/ForgeFlower ForgeFlower], which is a Fork of [https://github.com/MinecraftForge/FernFlower FernFlower].
FernFlower is a decompiler that takes the compiled Minecraft Jar and turn it in to semi readable source code.

Why semi readable?<br >
Because the decompiler has no sense of formatting or indentation.

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

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

== Reobfuscation ==
TBD

<references/>

Access Transformers

2020-10-24T21:01:54Z

Unbekannt: Inital Import dokuwiki

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

== Visibility ==

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

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

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

== How It Works ==

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

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

A random example to understand the syntax:

<code ->
public net.minecraft.util.palette.IResizeCallback # makes IResizeCallback public
</code>

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

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

== Using Access Transformers in your mod ==

<block important>
You should avoid using ATs if a private variable / function you're looking at has a getter or a setter. Variables are usually private for a reason.
</block>

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

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

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

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

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

File:Access-transformers-uncomment-this-line-in-build-gradle.png

2020-10-24T20:59:37Z

Unbekannt:

== Licencing ==
{{subst:uwl}}

Networking with Entities

2020-10-24T20:48:11Z

Unbekannt: Inital Import dokuwiki

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.

== 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>DataParameter<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>EntityDataManager.createKey()</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>DataSerializers</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>registerData()</nowiki></code> and call <code><nowiki>this.dataManager.register()</nowiki></code> for each of your data parameters, passing the parameter and an initial value to use. Remember to always call <code><nowiki>super.registerData()</nowiki></code> first!

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

Networking

2020-10-24T20:44:25Z

Unbekannt: update Link

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

Read an [[Understanding Networking#overview|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|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.

SimpleChannel

2020-10-24T20:42:31Z

Unbekannt: Inital Import dokuwiki

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, PacketBuffer></nowiki></code> responsible for encoding the message into the provided <code><nowiki>PacketBuffer</nowiki></code>
* The fourth parameter is a <code><nowiki>Function<PacketBuffer, MSG></nowiki></code> responsible for decoding the message from the provided <code><nowiki>PacketBuffer</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(PacketBuffer)</nowiki></code> still satisfies <code><nowiki>BiConsumer<MSG, PacketBuffer></nowiki></code>, the <code><nowiki>MSG</nowiki></code> simply becomes the implicit first argument.

== 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)
EntityPlayerMP sender = ctx.get().getSender(); // the client that sent this packet
// do stuff
});
ctx.get().setPacketHandled(true);
}
</syntaxhighlight>

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

{{Colored box|title=Alert|content=Packets are by default handled on the network thread.
<br><br>
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 instead using <code><nowiki>IThreadListener.addScheduledTask</nowiki></code>.
Simply call <code><nowiki>ctx.get().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=Alert|content=Be defensive when handling packets on the server. A client could attempt to exploit the packet handling by sending unexpected data.
<br><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 tile entities. When accessing blocks and tile entities in unloaded areas of the world, 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 tile entities if <code><nowiki>world.isBlockLoaded(pos)</nowiki></code> is true.}}

== 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, entityPlayerMP.connection.getNetworkManager(), 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(playerMP), new MyMessage());

// Send to all players tracking this chunk
INSTANCE.send(PacketDistributor.TRACKING_CHUNK.with(chunk), 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.

Networking

2020-10-24T20:32:10Z

Unbekannt: fixed links

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

Read an [[Understanding Networking#overview|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 [[latest:advanced:networking:simplechannel|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.

Networking

2020-10-24T20:29:17Z

Unbekannt: Inital Import dokuwiki

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

Read an [[Understanding Networking#overview|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 [[latest:advanced:networking:simplechannel|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:

1. Making sure the client view is "in sync" with the server view
## The flower at coordinates X, Y, Z just grew
2. 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.

BlockEntityWithoutLevelRenderer

2020-10-24T20:26:10Z

Unbekannt: Inital Import dokuwiki

<code>ItemStackTileEntityRenderer</code> is a class that allows custom usages of <code>MatrixStack</code>s and <code>IRenderTypeBuffer</code>s to render items.

== Using <code>ItemStackTileEntityRenderer</code> ==
<code>ItemStackTileEntityRenderer</code> allows you to render your item by extending the class and overriding <code><nowiki>ItemStackTileEntityRenderer#func_239207_a_</nowiki></code>.

In order to use a ISTER, the Item must first return true for <code><nowiki>IBakedModel#isBuiltInRenderer</nowiki></code>. It is also recommended that if you are using a block that <code>AbstractBlock#getRenderType</code> returns <code>BlockRenderType#ENTITYBLOCK_ANIMATED</code> so that it will render correctly in layers and minecarts. Once that returns true, the Item’s ISTER will be accessed for rendering. If it does not have one, it will use the default <code>ItemStackTileEntityRenderer#instance</code>.

To set the ISTER for an Item, use <code><nowiki>Item.Properties#setISTER</nowiki></code>. Each Item can only ever provide one ISTER, and the getter is final so that mods do not return new instances each frame.

That’s it, no additional setup is necessary to use a ISTER.

If you need to access the <code>TransformType</code> for rendering, you can store the one passed through <code><nowiki>IBakedModel#handlePerspective</nowiki></code> and use it during rendering. This method will always be called before <code><nowiki>ItemStackTileEntityRenderer#func_239207_a_</nowiki></code>.

Dynamic Loot Modification

2020-10-24T20:20:26Z

Unbekannt: Inital Import dokuwiki

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

== Registering a Global Loot Modifier ==

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

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

== The global_loot_modifiers.json ==

All you need to add here are the registry names of your loot modifiers.
<syntaxhighlight lang="json">
{
"replace": false,
"entries": [
"global_loot_test:silk_touch_bamboo",
"global_loot_test:smelting",
"global_loot_test:wheat_harvest"
]
}
</syntaxhighlight>

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

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

== The serialized json ==

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

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

== The LootModifier Subclass ==

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

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

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

private static class Serializer extends GlobalLootModifierSerializer<WheatSeedsConverterModifier> {

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

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

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

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

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

Item Properties

2020-10-24T20:02:37Z

Unbekannt: Inital Import dokuwiki

Item properties are a way for the "properties" of items to be exposed to the model system. An example is the bow, where the most important property is how far the bow has been pulled. This information is then used to choose a model for the bow, creating an animation for pulling it.

An item property assigns a certain <code>float</code> value to every <code>ItemStack</code> it is registered for, and vanilla item model definitions can use these values to define “overrides”, where an item defaults to a certain model, but if an override matches, it overrides the model and uses another. They are useful mainly because of the fact that they are continuous. For example, bows use item properties to define their pull animation. Since the value of the property is a <code>float</code>, it increases continuously from 0 to 1. This allows resource packs to add as many models as they want for the bow pulling animation along that spectrum, instead of being stuck with four “slots” for their models in the animation. The same is true of the compass and clock.

== Adding Properties to Items ==
<code><nowiki>ItemModelsProperties::registerProperty</nowiki></code> is used to add a property to a specific item. The <code>ResourceLocation</code> parameter is the name given to the property (e.g. <code><nowiki>new ResourceLocation("pull")</nowiki></code>). The <code>IItemPropertyGetter</code> is a function that takes the <code>ItemStack</code>, the <code>ClientWorld</code> it’s in, and the <code>LivingEntity</code> that holds it, returning the <code>float</code> value for the property. Some examples are the <code><nowiki>pulling</nowiki></code> and <code><nowiki>pull</nowiki></code> properties for <code>Items#BOW</code>, and the several default ones in <code>ItemModelProperties</code>. For modded item properties, it is recommended that the modid of the mod is used as the namespace (e.g. <code><nowiki>examplemod:property</nowiki></code> and not just <code>property</code>, as that really means <code><nowiki>minecraft:property</nowiki></code>).

== Using Overrides ==
A good example can be found in <code><nowiki>model/item/bow.json</nowiki></code>. For reference, here is a hypothetical example of an item with an <code><nowiki>examplemod:power</nowiki></code> property. If the values have no match, the default is the current model.
<block important>A predicate applies to all values greater than or equal to the given value.</block>
<syntaxhighlight lang="json">
{
"parent": "item/generated",
"textures": {
"__comment": "Default",
"layer0": "examplemod:items/examplePartial"
},
"overrides": [
{
"__comment": "power >= .75",
"predicate": {
"examplemod:power": 0.75
},
"model": "examplemod:item/examplePowered"
}
]
}
</syntaxhighlight>
And here’s a hypothetical snippet from the supporting code. (This does not have to be client-only; it will work on a server too. In vanilla, properties are registered in the item’s constructor.)
<syntaxhighlight lang="java">
public void clientSetup(final FMLCLientSetupEvent event) {
ItemModelProperties.registerProperty(item, new ResourceLocation("examplemod:power"), new IItemPropertyGetter() {
@Override
public float call(ItemStack stack, @Nullable ClientWorld world, @Nullable LivingEntity entity) {
return (float)getPowerLevel(stack) / (float)getMaxPower(stack); // Some external methods
}
}
}
</syntaxhighlight>