===== 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 generate a simple pillar feature.

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 "Creating a feature" part of this tutorial.

There are 3 steps that are required to add a feature to a biome.
  * Create a feature
  * Configure a feature
  * Use [[https://github.com/FabricMC/fabric/pull/1097|Biome Modification API in Fabric API]] to add your feature to biomes.


==== Creating a feature ====
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 ExampleFeature extends class_3031<ExampleFeatureConfig> {
  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<ExampleFeatureConfig> context) {
        class_5281 world = context.method_34383();
        // 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();

        // don't worry about where these come from-- we'll implement these methods soon
        int number = config.number();
        class_2960 blockId = config.blockId();

        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!");

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

                        // ensure we don't try to place blocks outside the world
                        if (testPos.getY() >= world.method_8624()) break;
                    }
                    return true;
                }
            }
        }
       // the game couldn't find a place to put the pillar
        return false;
    }
}

</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.
<yarncode java>
public record ExampleFeatureConfig(int number, Identifier blockId) implements FeatureConfig {
    public static final Codec<ExampleFeatureConfig> CODEC = RecordCodecBuilder.create(
        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),
                        Identifier.CODEC.fieldOf("blockID").forGetter(ExampleFeatureConfig::blockId))
                .apply(instance, ExampleFeatureConfig::new));
}
</yarncode>

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 {
    public static final Identifier EXAMPLE_FEATURE_ID = Identifier.of("tutorial", "example_feature");
    public static final ExampleFeature EXAMPLE_FEATURE = new ExampleFeature(ExampleFeatureConfig.CODEC);

    @Override
    public void onInitialize() {
        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. 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 FeatureExampleMod implements ModInitializer {

    public static final Identifier EXAMPLE_FEATURE_ID = Identifier.of("tutorial", "example_feature");
    public static final ExampleFeature EXAMPLE_FEATURE = new ExampleFeature(ExampleFeatureConfig.CODEC);

    public static final ConfiguredFeature<ExampleFeatureConfig, ExampleFeature> EXAMPLE_FEATURE_CONFIGURED = new ConfiguredFeature<>(
                    EXAMPLE_FEATURE,
                    new ExampleFeatureConfig(10, Identifier.of("minecraft", "netherite_block")));
    );


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

FIXME The last line has to be updated

==== Adding a configured feature to a biome ====
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!

Our final initializer class looks like this:
<yarncode java>
public class ExampleMod implements ModInitializer {

    public static final Identifier EXAMPLE_FEATURE_ID = Identifier.of("tutorial", "example_feature");
    public static final ExampleFeature EXAMPLE_FEATURE = new ExampleFeature(ExampleFeatureConfig.CODEC);
    public static final ConfiguredFeature<ExampleFeatureConfig, ExampleFeature> EXAMPLE_FEATURE_CONFIGURED = new ConfiguredFeature<>(
                    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));
    }
}
</yarncode>

The first argument of ''addFeature'' determines what biomes the structure is generated in.

The second argument helps determine when the structure is generated.
For above-ground houses you may go with ''SURFACE_STRUCTURES'', and for caves, you might go with ''RAW_GENERATION''.

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