22
edits
Changes
Biome modifiers documentation
Biome Modifiers are a data-driven system for modifying biomes. They have the ability to modify biomes in several ways:
* Adding or removing worldgen features and carvers
* Adding or removing mob spawns and mob spawn costs
* Modifying the climate of a biome
* Modifying a biome's client effects, such as water color
= Biome Modifier Types =
To define a new type of biome modifier, begin by implementing a new class that extends <code>BiomeModifier</code>. BiomeModifiers can usually be implemented as records, to reduce boilerplate.
<syntaxhighlight lang="java">
public record ExampleBiomeModifier() implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// This allows modifications to the given biome via the provided Builder.
}
public Codec<? extends BiomeModifier> codec()
{
// This must return a registered Codec, see Biome Modifier Serializers below.
}
}
</syntaxhighlight>
Beware! The modify method is called once per each phase per biome per biome modifier, so it's important to check which phase you're in and only make your changes in one phase.
<syntaxhighlight lang="java">
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
if (phase == Phase.ADD)
{
// add things to biomes
}
}
</syntaxhighlight>
Typically we also want to restrict biome modifiers to only apply to certain biomes. We can do that by accepting a HolderSet<Biome> in our constructor:
<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
if (phase == Phase.ADD && biomes.contains(biome))
{
// add things to biomes
}
}
</syntaxhighlight>
We can also accept Holders or HolderSets for other [[Registration#Data_Driven_Entries|datapack registry elements]], such as PlacedFeatures, which allows our BiomeModifier to refer to those elements, which can then be defined in their own JSON files.
<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes, Holder<PlacedFeature> feature) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// add a feature to all specified biomes
if (phase == Phase.ADD && biomes.contains(biome))
{
builder.getGenerationSettings().addFeature(Decoration.UNDERGROUND_ORES, feature);
}
}
</syntaxhighlight>
= Biome Modifier Serializers =
Each type of biome modifier must have a [[Codecs|Codec]] registered for it; [[Registration#DeferredRegister|Deferred Registers]] are the recommended way to register biome modifier codecs.
<syntaxhighlight lang="java">
public class YourMod
{
static DeferredRegister<Codec<? extends BiomeModifier>> BIOME_MODIFIER_SERIALIZERS =
DeferredRegister.create(ForgeRegistries.Keys.BIOME_MODIFIER_SERIALIZERS, "yourmodid");
static RegistryObject<Codec<ExampleBiomeModifier>> EXAMPLE_CODEC = BIOME_MODIFIER_SERIALIZERS.register("example", () ->
RecordCodecBuilder.create(builder -> builder.group(
// declare fields
Biome.LIST_CODEC.fieldOf("biomes").forGetter(ExampleBiomeModifier::biomes),
PlacedFeature.CODEC.fieldOf("feature").forGetter(ExampleBiomeModifier::feature)
// declare constructor
).apply(builder, ExampleBiomeModifier::new)));
}
</syntaxhighlight>
We can now implement the codec() method in our biome modifier class:
<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes, Holder<PlacedFeature> feature) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// add a feature to all specified biomes
if (phase == Phase.ADD && biomes.contains(biome))
{
builder.getGenerationSettings().addFeature(Decoration.UNDERGROUND_ORES, feature);
}
}
public Codec<? extends BiomeModifier> codec()
{
return YourMod.EXAMPLE_CODEC.get();
}
}
</syntaxhighlight>
= Biome Modifier JSONs =
Once we've registered a codec for our biome modifier type, we can define jsons for it. Biome modifier jsons must be defined in the directory <code>data/modid/forge/biome_modifier/</code>; a biome modifier at <code>data/modid/forge/biome_modifier/your_biome_modifier.json</code> has the namespaced id <code>modid:your_biome_modifier</code>.
Our codec above defines the json format:
* "biomes" is a special HolderSet field that accepts a single biome id, [list of biome ids], or #biome_tag.
* "feature" accepts a single placed feature id. [https://minecraft.fandom.com/wiki/Placed_feature These can be defined in jsons as well].
* We must also specify "type": "yourmodid:example" to tell the data loader to use our registered codec to read our json.
A json instance of our biome modifier that adds some feature to badlands biomes might look like this:
<syntaxhighlight lang="json">
{
"type": "yourmodid:example",
"biomes": "#minecraft:is_badlands",
"feature": "yourmod:some_feature"
}
</syntaxhighlight>
= Builtin Biome Modifier Types =
== None ==
Forge provides a no-op biome modifier type, whose jsons have the following format:
<syntaxhighlight lang="json">
{
"type": "forge:none"
}
</syntaxhighlight>
This allows pack devs or server operators to disable mods' biome modifiers by overriding their biome modifier jsons with the above.
= Best Practices =
* Avoid using biome modifiers to add vanilla placed features to biomes, as this may cause a feature cycle violation (the game will crash if two biomes have the same two features in their feature lists but in different orders). Placed features can be referenced in biome jsons or added via biome modifiers, but should not be used in both.
* Adding or removing worldgen features and carvers
* Adding or removing mob spawns and mob spawn costs
* Modifying the climate of a biome
* Modifying a biome's client effects, such as water color
= Biome Modifier Types =
To define a new type of biome modifier, begin by implementing a new class that extends <code>BiomeModifier</code>. BiomeModifiers can usually be implemented as records, to reduce boilerplate.
<syntaxhighlight lang="java">
public record ExampleBiomeModifier() implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// This allows modifications to the given biome via the provided Builder.
}
public Codec<? extends BiomeModifier> codec()
{
// This must return a registered Codec, see Biome Modifier Serializers below.
}
}
</syntaxhighlight>
Beware! The modify method is called once per each phase per biome per biome modifier, so it's important to check which phase you're in and only make your changes in one phase.
<syntaxhighlight lang="java">
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
if (phase == Phase.ADD)
{
// add things to biomes
}
}
</syntaxhighlight>
Typically we also want to restrict biome modifiers to only apply to certain biomes. We can do that by accepting a HolderSet<Biome> in our constructor:
<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
if (phase == Phase.ADD && biomes.contains(biome))
{
// add things to biomes
}
}
</syntaxhighlight>
We can also accept Holders or HolderSets for other [[Registration#Data_Driven_Entries|datapack registry elements]], such as PlacedFeatures, which allows our BiomeModifier to refer to those elements, which can then be defined in their own JSON files.
<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes, Holder<PlacedFeature> feature) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// add a feature to all specified biomes
if (phase == Phase.ADD && biomes.contains(biome))
{
builder.getGenerationSettings().addFeature(Decoration.UNDERGROUND_ORES, feature);
}
}
</syntaxhighlight>
= Biome Modifier Serializers =
Each type of biome modifier must have a [[Codecs|Codec]] registered for it; [[Registration#DeferredRegister|Deferred Registers]] are the recommended way to register biome modifier codecs.
<syntaxhighlight lang="java">
public class YourMod
{
static DeferredRegister<Codec<? extends BiomeModifier>> BIOME_MODIFIER_SERIALIZERS =
DeferredRegister.create(ForgeRegistries.Keys.BIOME_MODIFIER_SERIALIZERS, "yourmodid");
static RegistryObject<Codec<ExampleBiomeModifier>> EXAMPLE_CODEC = BIOME_MODIFIER_SERIALIZERS.register("example", () ->
RecordCodecBuilder.create(builder -> builder.group(
// declare fields
Biome.LIST_CODEC.fieldOf("biomes").forGetter(ExampleBiomeModifier::biomes),
PlacedFeature.CODEC.fieldOf("feature").forGetter(ExampleBiomeModifier::feature)
// declare constructor
).apply(builder, ExampleBiomeModifier::new)));
}
</syntaxhighlight>
We can now implement the codec() method in our biome modifier class:
<syntaxhighlight lang="java">
public record ExampleBiomeModifier(HolderSet<Biome> biomes, Holder<PlacedFeature> feature) implements BiomeModifier
{
public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
// add a feature to all specified biomes
if (phase == Phase.ADD && biomes.contains(biome))
{
builder.getGenerationSettings().addFeature(Decoration.UNDERGROUND_ORES, feature);
}
}
public Codec<? extends BiomeModifier> codec()
{
return YourMod.EXAMPLE_CODEC.get();
}
}
</syntaxhighlight>
= Biome Modifier JSONs =
Once we've registered a codec for our biome modifier type, we can define jsons for it. Biome modifier jsons must be defined in the directory <code>data/modid/forge/biome_modifier/</code>; a biome modifier at <code>data/modid/forge/biome_modifier/your_biome_modifier.json</code> has the namespaced id <code>modid:your_biome_modifier</code>.
Our codec above defines the json format:
* "biomes" is a special HolderSet field that accepts a single biome id, [list of biome ids], or #biome_tag.
* "feature" accepts a single placed feature id. [https://minecraft.fandom.com/wiki/Placed_feature These can be defined in jsons as well].
* We must also specify "type": "yourmodid:example" to tell the data loader to use our registered codec to read our json.
A json instance of our biome modifier that adds some feature to badlands biomes might look like this:
<syntaxhighlight lang="json">
{
"type": "yourmodid:example",
"biomes": "#minecraft:is_badlands",
"feature": "yourmod:some_feature"
}
</syntaxhighlight>
= Builtin Biome Modifier Types =
== None ==
Forge provides a no-op biome modifier type, whose jsons have the following format:
<syntaxhighlight lang="json">
{
"type": "forge:none"
}
</syntaxhighlight>
This allows pack devs or server operators to disable mods' biome modifiers by overriding their biome modifier jsons with the above.
= Best Practices =
* Avoid using biome modifiers to add vanilla placed features to biomes, as this may cause a feature cycle violation (the game will crash if two biomes have the same two features in their feature lists but in different orders). Placed features can be referenced in biome jsons or added via biome modifiers, but should not be used in both.