User Tools

Site Tools


This is an old revision of the document!

Adding Biomes

NOTE: There is a ongoing pull request on Fabric API that adds biome API for 1.16.2. Please use this tutorial as a workaround until it gets merged.


There are 3 steps that are required to add a biome to the world.

  • Creating a biome
  • Registering a biome
  • Adding a biome to a climate zone in the world

In this tutorial, we will add new biome called obsiland biome, whose surface is covered with obsidians.

Creating a Biome

To create a biome, use Biome.Builder and configure properties. Missing one property will likely cause the game to crash. It is recommended to look at vanilla biomes (created in DefaultBiomeCreator) as examples.

public class ExampleMod implements ModInitializer {
  // SurfaceBuilder defines how the surface of your biome looks.
  // We use custom surface builder for our biome to cover surface with obsidians.
  private static final ConfiguredSurfaceBuilder<TernarySurfaceConfig> OBSIDIAN_SURFACE_BUILDER = SurfaceBuilder.DEFAULT
    .withConfig(new TernarySurfaceConfig(
  private static final Biome OBSILAND = createObsiland();
  private static Biome createObsiland() {
    // We specify what entities spawn and what features generate in the biome.
    // Aside from some structures, trees, rocks, plants and
    //   custom entities, these are mostly the same for each biome.
    // Vanilla configured features for biomes are defined in DefaultBiomeFeatures.
    SpawnSettings.Builder spawnSettings = new SpawnSettings.Builder();
    DefaultBiomeFeatures.addMonsters(spawnSettings, 95, 5, 100);
    GenerationSettings.Builder generationSettings = new GenerationSettings.Builder();
    return (new Biome.Builder())
      .effects((new BiomeEffects.Builder())

Registering Biomes

We register our biome at the entrypoint onInitialize. If you use your own surface builder, you will also have to register it.

public class ExampleMod implements ModInitializer {
  public static final RegistryKey<Biome> OBSILAND_KEY = RegistryKey.of(Registry.BIOME_KEY, new Identifier("tutorial", "obsiland"));
  public void onInitialize() {
    Registry.register(BuiltinRegistries.CONFIGURED_SURFACE_BUILDER, new Identifier("tutorial", "obsidian"), OBSIDIAN_SURFACE_BUILDER);
    Registry.register(BuiltinRegistries.BIOME, OBSILAND_KEY.getValue(), OBSILAND);
    BuiltinBiomesAccessor.getRawIdMap().put(BuiltinRegistries.BIOME.getRawId(OBSILAND), OBSILAND_KEY);
public interface BuiltinBiomesAccessor {
  public static Int2ObjectMap<RegistryKey<Biome>> getRawIdMap() {
    throw new AssertionError();

You should also give your biome a language entry in your en_us.json file:

  "biome.tutorial.obsiland": "Obsiland"

Adding a biome to a climate zone in the world

The vanilla biomes used in the overworld is defined in VanillaLayeredBiomeSource.BIOMES. We have to add our biome to it first.

public class ExampleMod implements ModInitializer {
  public void onInitialize() {
    // We have to copy existing List because it is immutable.
    List<RegistryKey<Biome>> biomes = new ArrayList<>(VanillaLayeredBiomeSourceAccessor.getBiomes());
public interface VanillaLayeredBiomeSourceAccessor {
  public static List<RegistryKey<Biome>> getBiomes() {
    throw new AssertionError();
  public static void setBiomes(List<RegistryKey<Biome>> biomes) {
    throw new AssertionError();

Secondly, we need to specify the climate to which the biome is added. In this tutorial, we will add the custom biome to the temperate climate as an example. We modify SetBaseBiomesLayer.TEMPERATE_BIOMES to accomplish this.

public class ExampleMod implements ModInitializer {
  public void onInitialize() {
    // SetBaseBiomesLayer.TEMPERATE_BIOMES is an array of raw biome IDs.
    // We have to get the raw id of our biome and append it to TEMPERATE_BIOMES.
      ArrayUtils.add(SetBaseBiomesLayerAccessor.getTemperateBiomes(), BuiltinRegistries.BIOME.getRawId(OBSILAND)));
public interface SetBaseBiomesLayerAccessor {
  public static int[] getTemperateBiomes() {
    throw new AssertionError();
  public static void setTemperateBiomes(int[] biomes) {
    throw new AssertionError();


Congratulations! Your biome should now be generating in the world! You can use below command to find your biome in the world.

/locatebiome tutorial:obsiland

tutorial/biomes.1602901100.txt.gz · Last modified: 2020/10/17 02:18 by hydos