Differences

This shows you the differences between two versions of the page.

--- tutorial:features [2021/08/31 13:21] – Edited sentence about decorators mschae23
+++ tutorial:features [2024/10/28 17:58] (current) – Fix new identifier vs Identifier.of cassiancc
@@ Line 1: / Line 1: @@
-===== Adding Features [1.17] =====
+===== Adding Features =====
 Rocks, trees, ores, and ponds are all examples of features.
 They are simple generation additions to the world which generate depending on how they are configured.
-In this tutorial, we'll look at generating a simple stone spiral feature randomly.
+In this tutorial, we'll generate a simple pillar feature.
-If you want to do something similar to vanilla (like ores), you should first look for an existing feature you can use.
+If you want to do something similar to vanilla (like ores or flower patches), you should first look for an existing feature you can use.
-In that case, skip the "Create a feature" part of this tutorial.
+In that case, skip the "Creating a feature" part of this tutorial.
 There are 3 steps that are required to add a feature to a biome.
@@ Line 12: / Line 12: @@
   * Use [[https://github.com/FabricMC/fabric/pull/1097|Biome Modification API in Fabric API]] to add your feature to biomes.
-Note that the Biome Modification API is marked as experimental. If the API doesn't work, consider using [[?rev=1599388928|the mixin version]].
 ==== Creating a feature ====
-A simple Feature looks like this:
+Let's create a feature that spawns a 1x1 pillar of blocks on the ground. As an added challenge, let's also make it configurable, so we can change the height and material of the pillars.
+We'll first create a new class for our feature. This is where the generation logic will go.
 <yarncode java>
-public class StoneSpiralFeature extends class_3031<class_3111> {
+public class ExampleFeature extends class_3031<ExampleFeatureConfig> {
-  public StoneSpiralFeature(Codec<class_3111> configCodec) {
+  public ExampleFeature(Codec<FeatureConfig> configCodec) {
     super(configCodec);
   }
+  // this method is what is called when the game tries to generate the feature. it is where the actual blocks get placed into the world.
   @Override
-  public boolean method_13151(class_5821<class_3111> context) {
+  public boolean method_13151(class_5821<ExampleFeatureConfig> context) {
-    class_2338 topPos = context.method_33652().method_8598(class_2902.class_2903.OCEAN_FLOOR_WG, context.method_33655());
+        class_5281 world = context.method_34383();
-    class_2350 offset = class_2350.NORTH;
+        // the origin is the place where the game starts trying to place the feature
+        class_2338 origin = context.getOrigin();
+        // we won't use the random here, but we could if we wanted to
+        class_5819 random = context.method_33654();
+        ExampleFeatureConfig config = context.method_33656();
-    for (int y = 0; y < 15; y++) {
+        // don't worry about where these come from-- we'll implement these methods soon
-      offset = offset.method_10170();
+        int number = config.number();
-      context.method_33652().method_30092(topPos.method_10086(y).method_10093(offset), class_2246.STONE.method_9564(), 3);
+        class_2960 blockId = config.blockId();
-    }
-    return true;
+        class_2680 blockState = class_7923.field_41175.get(blockId).method_9564();
-  }
+        // ensure the ID is okay
-}
+        if (blockState == null) throw new IllegalStateException(blockId + " could not be parsed to a valid block identifier!");
-</yarncode>
-In our implementation, we'll build a simple 15-block tall spiral of stone starting at the top block in the world.
+        // find the surface of the world
+        class_2338 testPos = new class_2338(origin);
+        for (int y = 0; y < world.method_31605(); y++) {
+            testPos = testPos.method_10086();
+            // the tag name is dirt, but includes grass, mud, podzol, etc.
+            if (world.method_8320(testPos).isIn(class_3481.field_29822)) {
+                if (world.method_8320(testPos.method_10086()).isOf(class_2246.field_10124)) {
+                    for (int i = 0; i < number; i++) {
+                        // create a simple pillar of blocks
+                        world.method_8501(testPos, blockState, 0x10);
+                        testPos = testPos.method_10086();
-The ''<yarn Feature<class_3111>>'' constructor takes in a ''<yarn Codec<class_3111>>''.
+                        // ensure we don't try to place blocks outside the world
-You can pass in ''<yarn class_3111.CODEC>'' for default config features, either directly in the super call in the constructor or when you instantiate the feature.
+                        if (testPos.getY() >= world.method_8624()) break;
+                    }
+                    return true;
+                }
+            }
+        }
+       // the game couldn't find a place to put the pillar
+        return false;
+    }
+}
-''<yarn method_13151>'' is called when the chunk decides to generate the feature.
-If the feature is configured to spawn every chunk, this would be called for each chunk being generated as well.
-In the case of the feature being configured to spawn at a certain rate per biome, ''<yarn method_13151>'' would only be called in instances where the world wants to spawn the structure.
-Our feature uses a ''<yarn class_3111>'' at the moment, which means that it is not configurable. However, you should always try to make your features configurable,
-as that allows you to reuse it for different things, and also lets players change them through data packs if they want.
-A simple config for our feature could look like this:
-<yarncode java>
-public record SpiralFeatureConfig(class_6017 height, class_4651 block) implements class_3037 {
-  public static final Codec<SpiralFeatureConfig> CODEC = RecordCodecBuilder.create(instance -> instance.group(
-    class_6017.field_29946.fieldOf("height").forGetter(SpiralFeatureConfig::height),
-    class_4651.field_24937.fieldOf("block").forGetter(SpiralFeatureConfig::block)
-  ).apply(instance, instance.stable(SpiralFeatureConfig::new)));
-}
 </yarncode>
+Now, we need to implement that ''ExampleFeatureConfig'' record. This is where we define the variables that we use in our ''Feature''. This config is essentially a wrapper for the parameters we want to pass to our feature. Note: while this tutorial only uses integers and BlockStates, other useful objects in the game also have codecs that can give you more control over how your feature generates. ''BlockStateProvider''s are a good example of this.
-Note that we use an ''<yarn class_6017>'' for the height, and a ''<yarn class_4651>'' for the block instead of directly using an int or a ''<yarn class_2680>''.
-This is because they are more powerful to use. For example, you could configure the feature with a ''<yarn class_6019>'', so that its height can vary.
-Now, let's make our feature use the ''SpiralFeatureConfig'' (the class name was also changed, as the feature doesn't always place stone now):
 <yarncode java>
-public class SpiralFeature extends class_3031<SpiralFeatureConfig> {
+public record ExampleFeatureConfig(int number, Identifier blockId) implements FeatureConfig {
-  public SpiralFeature(Codec<SpiralFeatureConfig> configCodec) {
+    public static final Codec<ExampleFeatureConfig> CODEC = RecordCodecBuilder.create(
-    super(configCodec);
+        instance -> instance.group(
-  }
+                        // you can add as many of these as you want, one for each parameter
+                        Codecs.POSITIVE_INT.fieldOf("number").forGetter(ExampleFeatureConfig::number),
-  @Override
+                        Identifier.CODEC.fieldOf("blockID").forGetter(ExampleFeatureConfig::blockId))
-  public boolean method_13151(class_5821<SpiralFeatureConfig> context) {
+                .apply(instance, ExampleFeatureConfig::new));
-    class_2338 pos = context.method_33655();
-    SpiralFeatureConfig config = context.method_33656();
-    class_2350 offset = class_2350.NORTH;
-    int height = config.height().method_35008(context.method_33654());
-    for (int y = 0; y < height; y++) {
-      offset = offset.method_10170();
-      class_2338 blockPos = pos.method_10086(y).method_10093(offset);
-      context.method_33652().method_30092(blockPos, config.block().method_23455(context.method_33654(), blockPos), 3);
-    }
-    return true;
-  }
 }
 </yarncode>
-Features can be registered like most other content in the game, and there aren't any special builders or mechanics you'll have to worry about.
+Now that we have our config defined, the errors in our feature class will resolve. But we're not done yet-- now we need to add our feature to the game. Features can be registered like most other content in the game, and there aren't any special builders or mechanics you'll have to worry about.
 <code java>
 public class ExampleMod implements ModInitializer {
-  private static final Feature<SpiralFeatureConfig> SPIRAL = new SpiralFeature(SpiralFeatureConfig.CODEC);
+    public static final Identifier EXAMPLE_FEATURE_ID = Identifier.of("tutorial", "example_feature");
+    public static final ExampleFeature EXAMPLE_FEATURE = new ExampleFeature(ExampleFeatureConfig.CODEC);
-  @Override
+    @Override
-  public void onInitialize() {
+    public void onInitialize() {
-    Registry.register(Registry.FEATURE, new Identifier("tutorial", "spiral"), SPIRAL);
+        Registry.register(Registries.FEATURE, EXAMPLE_FEATURE_ID, EXAMPLE_FEATURE);
-  }
+    }
 }
 </code>
+If you plan to configure and use your feature using datapacks, you can stop here. To implement it in code, read on.
 ==== Configuring a feature ====
-We need to give a configuration to a feature, before we can add it to biomes. Make sure to register configured features as well as features.
+We need to give a configuration to a feature, before we can add it to biomes. Make sure to register configured features as well as features. Here is where we specify the parameters of our feature. We'll generate 10-block-high pillars out of netherite. In fact, we could register as many of these ''ConfiguredFeatures'' as we wanted, just changing the config parameters each time.
 <yarncode java>
-public class ExampleMod implements ModInitializer {
+public class FeatureExampleMod implements ModInitializer {
-  public static final class_2975<?, ?> STONE_SPIRAL = SPIRAL.method_23397(new SpiralFeatureConfig(ConstantIntProvider.create(15), new SimpleBlockStateProvider(Blocks.STONE.getDefaultState())))
-      .method_30374(class_3284.HEIGHTMAP.method_23475(new HeightmapDecoratorConfig(Heightmap.Type.OCEAN_FLOOR_WG)))
-      .method_30371()
-      .method_30372(5);
-  @Override
+    public static final Identifier EXAMPLE_FEATURE_ID = Identifier.of("tutorial", "example_feature");
-  public void onInitialize() {
+    public static final ExampleFeature EXAMPLE_FEATURE = new ExampleFeature(ExampleFeatureConfig.CODEC);
-    [...]
+    public static final ConfiguredFeature<ExampleFeatureConfig, ExampleFeature> EXAMPLE_FEATURE_CONFIGURED = new ConfiguredFeature<>(
-    RegistryKey<class_2975<?, ?>> stoneSpiral = RegistryKey.of(Registry.CONFIGURED_FEATURE_KEY,
+                    EXAMPLE_FEATURE,
-        new Identifier("tutorial", "stone_spiral"));
+                    new ExampleFeatureConfig(10, Identifier.of("minecraft", "netherite_block")));
-    Registry.register(BuiltinRegistries.CONFIGURED_FEATURE, stoneSpiral.getValue(), STONE_SPIRAL);
+    );
-  }
+    @Override
+    public void onInitialize() {
+        Registry.register(Registry.FEATURE, EXAMPLE_FEATURE_ID, EXAMPLE_FEATURE);
+        Registry.register(BuiltinRegistries.CONFIGURED_FEATURE, EXAMPLE_FEATURE_ID, EXAMPLE_FEATURE_CONFIGURED);
+    }
 }
 </yarncode>
-Note that the height of the spiral (15 blocks) and the block to place (stone) is now configurable here.
+FIXME The last line has to be updated
-The decorators (added with ''decorate'' or with helper methods like ''spreadHorizontally'' and ''applyChance'') are responsible for how and where your feature will be placed.
-To choose the correct decorators, check out vanilla features with a similar style to your own.
 ==== Adding a configured feature to a biome ====
-We use the Biome Modification API.
+We use the Biome Modification API. The final stage of feature configuration is creating a ''PlacedFeature''. This class is a replacement for ''Decorators'' on ''ConfiguredFeatures''. Don't forget to register it as well!
-<code java>
+Our final initializer class looks like this:
+<yarncode java>
 public class ExampleMod implements ModInitializer {
-  [...]
-  @Override
+    public static final Identifier EXAMPLE_FEATURE_ID = Identifier.of("tutorial", "example_feature");
-  public void onInitialize() {
+    public static final ExampleFeature EXAMPLE_FEATURE = new ExampleFeature(ExampleFeatureConfig.CODEC);
-    [...]
+    public static final ConfiguredFeature<ExampleFeatureConfig, ExampleFeature> EXAMPLE_FEATURE_CONFIGURED = new ConfiguredFeature<>(
-    BiomeModifications.addFeature(BiomeSelectors.all(), GenerationStep.Feature.UNDERGROUND_ORES, stoneSpiral);
+                    EXAMPLE_FEATURE,
-  }
+                    new ExampleFeatureConfig(10, Identifier.of("minecraft", "netherite_block"))
+    );
+    // our PlacedFeature. this is what gets passed to the biome modification API to add to the biome.
+    public static PlacedFeature EXAMPLE_FEATURE_PLACED = new PlacedFeature(
+            RegistryEntry.of(
+                    EXAMPLE_FEATURE_CONFIGURED
+                  //  the SquarePlacementModifier makes the feature generate a cluster of pillars each time
+            ), List.of(SquarePlacementModifier.of())
+    );
+    @Override
+    public void onInitialize() {
+        // register the features
+        Registry.register(class_7923.field_41144, EXAMPLE_FEATURE_ID, EXAMPLE_FEATURE);
+        // add it to overworld biomes using FAPI
+        BiomeModifications.addFeature(
+                BiomeSelectors.foundInOverworld(),
+                // the feature is to be added while flowers and trees are being generated
+                GenerationStep.Feature.VEGETAL_DECORATION,
+                RegistryKey.of(RegistryKeys.PLACED_FEATURE, EXAMPLE_FEATURE_ID));
+    }
 }
-</code>
+</yarncode>
 The first argument of ''addFeature'' determines what biomes the structure is generated in.
@@ Line 150: / Line 161: @@
 For above-ground houses you may go with ''SURFACE_STRUCTURES'', and for caves, you might go with ''RAW_GENERATION''.
-=== Result ===
+For more information, the code used in this tutorial is available [[https://github.com/itsmiir/wiki-example/tree/1.19/src/main/java/com/miir/example/feature|on Github]].
-{{https://i.imgur.com/Kr59o0B.png}}