Forge Community Wiki - User contributions [en-gb]

Dynamic Loot Modification

2021-05-09T19:07:36Z

Tslat: /* The global_loot_modifiers.json */

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

== Registering a Global Loot Modifier ==

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

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

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

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

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

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

== The serialized json ==

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

Dynamic Loot Modification

2021-05-09T19:07:23Z

Tslat: /* The global_loot_modifiers.json */

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

== Registering a Global Loot Modifier ==

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

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

==The global_loot_modifiers.json==
All you need to add here are the file names of your loot modifiers.

These are the names of the json files you have made in the loot_modifiers folder, in ResourceLocation format.

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

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

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

== The serialized json ==

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

DynamicOps

2021-01-19T08:21:23Z

Tslat: /* Format Conversion */

The <code>DynamicOps</code> class is part of mojang's DataFixerUpper serialization library; DynamicOps are used alongside [[codecs]] to convert java objects to a serialized format and back. While Codecs describe how a java object is to be serialized, DynamicOps describe the format the object is to be serialized to.

The DataFixerUpper library includes several DynamicOps for serializing to json; vanilla minecraft also includes a DynamicOps for serializing to minecraft's [[Using_NBT|NBT]] format.

= Builtin DynamicOps =

== JsonOps ==

The <code>JsonOps</code> DynamicOps are used to serialize and deserialize json data. These are instances of <code>DynamicOps<JsonElement></code>, meaning that they are used to convert java objects to and from <code>JsonElement</code> instances. These can used in conjunction with codecs to serialize/deserialize objects from assets and datapacks.

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

== NBTDynamicOps ==

The <code>NBTDynamicOps.INSTANCE</code> is an instance of <code>DynamicOps<INBT></code>, meaning it is used to convert java objects to and from <code>INBT</code> instances. This can be used for serializing data into packets to send across networks, as well as serializing persistant data for entities and similar objects.

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

= Using DynamicOps =

== Serializing and Deserializing ==

By combining a <code>Codec<SomeJavaType></code> with a <code>DynamicOps<SomeSerializedFormat></code>, the proper java object can be converted to the serialized form and back. See [[codecs]] for details on this subject.

== Format Conversion ==

By using the <code>DynamicOps#convertTo</code> instance method with a second DynamicOps instance, data can be converted between two different serialized formats, such as JsonElement to INBT and back.

<syntaxhighlight lang=java>
// converting INBT to JsonElement
JsonElement someJsonElement = NBTDynamicOps.INSTANCE.convertTo(JsonOps.INSTANCE, someNBT);

// converting JsonElement to INBT
INBT someNBT = JsonOps.INSTANCE.convertTo(NBTDynamicOps.INSTANCE, someJsonElement);
</syntaxhighlight>

Depending on the implementation of the DynamicOps used, this may throw an exception or return an empty object if the two formats are incompatible.

In particular, it is '''not''' safe to convert lists of numbers to NBT in this manner, due to the NBT format's strong typing and the way the NBTDynamicOps attempts to create lists of numbers.

= External Links =
* [https://kvverti.github.io/Documented-DataFixerUpper/snapshot/com/mojang/serialization/DynamicOps.html DynamicOps unofficial javadocs]

Access Transformers

2021-01-10T22:41:41Z

Tslat: Add final access modifier AT section

Access Transformers are Forge's native way of allowing you to access (read and 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 lot

=== Removing Finality ===
Access transformers can also be used to remove the '''final''' keyword on code elements. To do this, append <code>-f</code> to the access specifier.

An example of this in place:

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

Note: You can also use this to ''add'' a final keyword via <code>+f</code>. This is never recommended however, and should be avoided at all costs unless absolutely necessary.

== Using Access Transformers in your mod ==

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

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

Access Transformers

2021-01-10T22:31:17Z

Tslat: /* How It Works */

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

== Using Access Transformers in your mod ==

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

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