Difference between revisions of "Biome Modifiers"

From Forge Community Wiki
m (→‎Add Spawns: removed bad comma)
 
(6 intermediate revisions by 4 users not shown)
Line 5: Line 5:
 
* Modifying the climate of a biome
 
* Modifying the climate of a biome
 
* Modifying a biome's client effects, such as water color
 
* Modifying a biome's client effects, such as water color
 +
 +
<big>'''NOTE:'''</big> Forge provides several [[#Builtin_Biome_Modifier_Types|builtin biome modifier types]], so some basic use cases such as adding features or mob spawns to biomes can be done without registering additional serializers. If you are looking to add a mob or feature to a biome, scroll down to the [[#Builtin_Biome_Modifier_Types|Builtin Biome Modifier Types]] section and use one of those pre-existing Biome Modifiers from Forge instead. No custom Biome Modifier implementation needed.
  
 
Creating and using biome modifiers involves up to three steps:
 
Creating and using biome modifiers involves up to three steps:
Line 12: Line 14:
 
# Creating [[#Biome_Modifier_JSONs|biome modifier JSONs]] to define individual biome modifier instances; each json file provides a glob of data to your serializer to produce an instance of a biome modifier type. These can be [[#Datageneration|datagenerated]] if desired.
 
# Creating [[#Biome_Modifier_JSONs|biome modifier JSONs]] to define individual biome modifier instances; each json file provides a glob of data to your serializer to produce an instance of a biome modifier type. These can be [[#Datageneration|datagenerated]] if desired.
  
Forge provides several [[#Builtin_Biome_Modifier_Types|builtin biome modifier types]], so some basic use cases such as adding features or mob spawns to biomes can be done without registering additional serializers.
 
 
= Biome Modifier Types =
 
  
 +
=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.
 
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.
  
Line 45: Line 45:
 
</syntaxhighlight>
 
</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:
+
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">
 
<syntaxhighlight lang="java">
Line 59: Line 59:
 
</syntaxhighlight>
 
</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.
+
We can also accept [[Holders]] or [[HolderSets|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">
 
<syntaxhighlight lang="java">
Line 133: Line 133:
 
   "biomes": "#minecraft:is_badlands",
 
   "biomes": "#minecraft:is_badlands",
 
   "feature": "yourmod:some_feature"
 
   "feature": "yourmod:some_feature"
}
 
</syntaxhighlight>
 
 
== Side Note on HolderSets ==
 
 
HolderSets are a vanilla feature that, when defined in JSON, can be specified as a single id, list of ids, or tag. Our example above uses a holderset of biomes, so all three of these are valid biome fields:
 
 
<syntaxhighlight lang="json">
 
{
 
  "biomes": "forest",
 
  "biomes": ["forest", "birch_forest"],
 
  "biomes": "#is_forest"
 
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 175: Line 163:
 
{
 
{
 
   "type": "forge:add_features", // required
 
   "type": "forge:add_features", // required
   "biomes": "#namespace:your_biome_tag" // accepts a biome id, [list of biome ids], or #namespace:biome_tag
+
   "biomes": "#namespace:your_biome_tag", // accepts a biome id, [list of biome ids], or #namespace:biome_tag
 
   "features": "namespace:your_feature", // accepts a placed feature id, [list of placed feature ids], or #namespace:feature_tag
 
   "features": "namespace:your_feature", // accepts a placed feature id, [list of placed feature ids], or #namespace:feature_tag
 
   "step": "underground_ores" // accepts a Decoration enum name
 
   "step": "underground_ores" // accepts a Decoration enum name
Line 200: Line 188:
 
{
 
{
 
   "type": "forge:remove_features", // required
 
   "type": "forge:remove_features", // required
   "biomes": "#namespace:your_biome_tag" // accepts a biome id, [list of biome ids], or #namespace:biome_tag
+
   "biomes": "#namespace:your_biome_tag", // accepts a biome id, [list of biome ids], or #namespace:biome_tag
 
   "features": "namespace:your_feature", // accepts a placed feature id, [list of placed feature ids], or #namespace:feature_tag
 
   "features": "namespace:your_feature", // accepts a placed feature id, [list of placed feature ids], or #namespace:feature_tag
 
   "steps": "underground_ores" // optional field specifying a Decoration or list of Decorations to remove features from, defaults to all if not specified
 
   "steps": "underground_ores" // optional field specifying a Decoration or list of Decorations to remove features from, defaults to all if not specified
Line 239: Line 227:
  
 
* 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.
 
* 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.
 +
* Avoid adding the same placed feature with more than one biome modifier, as this can cause feature cycle violations.

Latest revision as of 23:22, 28 August 2023

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

NOTE: Forge provides several builtin biome modifier types, so some basic use cases such as adding features or mob spawns to biomes can be done without registering additional serializers. If you are looking to add a mob or feature to a biome, scroll down to the Builtin Biome Modifier Types section and use one of those pre-existing Biome Modifiers from Forge instead. No custom Biome Modifier implementation needed.

Creating and using biome modifiers involves up to three steps:

  1. Creating a biome modifier type, which defines how to modify a biome.
  2. Registering a biome modifier codec, which defines how to parse a json into your biome modifier type.
  3. Creating biome modifier JSONs to define individual biome modifier instances; each json file provides a glob of data to your serializer to produce an instance of a biome modifier type. These can be datagenerated if desired.


Biome Modifier Types

To define a new type of biome modifier, begin by implementing a new class that extends BiomeModifier. BiomeModifiers can usually be implemented as records, to reduce boilerplate.

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

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.

public void modify(Holder<Biome> biome, Phase phase, Builder builder)
{
  if (phase == Phase.ADD)
  {
    // add things to biomes
  }
}

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:

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

We can also accept Holders or Holders for other 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.

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

Biome Modifier Serializers

Each type of biome modifier must have a Codec registered for it; Deferred Registers are the recommended way to register biome modifier codecs.

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

We can now implement the codec() method in our biome modifier class:

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();
  }
}


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 data/modid/forge/biome_modifier/; a biome modifier at data/modid/forge/biome_modifier/your_biome_modifier.json has the namespaced id modid:your_biome_modifier.

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

{
  "type": "yourmodid:example",
  "biomes": "#minecraft:is_badlands",
  "feature": "yourmod:some_feature"
}

Datageneration

Biome Modifier jsons can be datagenerated via GatherDataEvent. As biome modifiers are datapack registry objects, this can be done by using JsonCodecProvider#forDatapackRegistry as the data provider. Refer to Datageneration/Datapack_Registries for additional information on datagenerating datapack registry elements.

Builtin Biome Modifier Types

Forge provides the following builtin biome modifier types:

None

A no-op biome modifier type, whose jsons have the following format:

{
  "type": "forge:none"
}

This allows pack devs or server operators to disable mods' biome modifiers by overriding their biome modifier jsons with the above.

Add Features

This biome modifier type adds placed features to biomes.

{
  "type": "forge:add_features", // required
  "biomes": "#namespace:your_biome_tag", // accepts a biome id, [list of biome ids], or #namespace:biome_tag
  "features": "namespace:your_feature", // accepts a placed feature id, [list of placed feature ids], or #namespace:feature_tag
  "step": "underground_ores" // accepts a Decoration enum name
}

Decoration steps in order of generation are:

  • raw_generation
  • lakes
  • local_modifications
  • underground_structures
  • surface_structures
  • underground_ores
  • underground_decoration
  • fluid_springs
  • vegetal_decoration
  • top_layer_modification

Remove Features

This biome modifier type removes features from biomes.

{
  "type": "forge:remove_features", // required
  "biomes": "#namespace:your_biome_tag", // accepts a biome id, [list of biome ids], or #namespace:biome_tag
  "features": "namespace:your_feature", // accepts a placed feature id, [list of placed feature ids], or #namespace:feature_tag
  "steps": "underground_ores" // optional field specifying a Decoration or list of Decorations to remove features from, defaults to all if not specified
}

Add Spawns

This biome modifier type adds mob spawns to biomes.

{
  "type": "forge:add_spawns", // Required
  "biomes": "#namespace:biome_tag", // Accepts a biome id, [list of biome ids], or #namespace:biome_tag
  "spawners":
  {
    "type": "namespace:entity_type", // Type of mob to spawn
    "weight": 100, // int, spawn weighting
    "minCount": 1, // int, minimum pack size
    "maxCount": 4 // int, maximum pack size
  }
}

Remove Spawns

This biome modifier type removes mob spawns from biomes.

{
  "type": "forge:remove_spawns", // Required
  "biomes": "#namespace:biome_tag", // Accepts a biome id, [list of biome ids], or #namespace:biome_tag
  "entity_types": "#namespace:entitytype_tag" // Accepts an entity type, list, or tag of entitytypes whose spawns are to be removed from the biomes
}

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.
  • Avoid adding the same placed feature with more than one biome modifier, as this can cause feature cycle violations.