The biome file

A biome is an area of the world with its own ground, weather, colors and mobs. Plains, deserts and cherry groves are all biomes. In this guide you will make a Ruby Grove: a warm meadow with reddish grass that replaces small parts of the plains.

A biome, like a block, lives in two packs:

• The behavior pack file says how the land is built: its climate, which blocks cover the ground, and where it appears.
• The resource pack file (the "client biome") says how it looks and sounds: grass color, water color, fog, music.

The files

BP/
  biomes/
    ruby_grove.biome.json
RP/
  biomes/
    ruby_grove.client_biome.json

Both files use the same identifier, wiki:ruby_grove. That is how the game knows they belong together.

Step 1: the behavior pack biome

{
  "format_version": "1.26.30",
  "minecraft:biome": {
    "description": {
      "identifier": "wiki:ruby_grove"
    },
    "components": {
      "minecraft:climate": {
        "temperature": 0.9,
        "downfall": 0.4,
        "snow_accumulation": [0.0, 0.125]
      },
      "minecraft:overworld_height": {
        "noise_type": "lowlands"
      },
      "minecraft:surface_builder": {
        "builder": {
          "type": "minecraft:overworld",
          "top_material": "minecraft:grass_block",
          "mid_material": "minecraft:dirt",
          "foundation_material": "minecraft:stone",
          "sea_floor_material": "minecraft:gravel",
          "sea_material": "minecraft:water",
          "sea_floor_depth": 7
        }
      },
      "minecraft:replace_biomes": {
        "replacements": [
          {
            "dimension": "minecraft:overworld",
            "targets": ["plains"],
            "amount": 0.25,
            "noise_frequency_scale": 0.5
          }
        ]
      },
      "minecraft:map_tints": {
        "grass": { "type": "tint", "tint": "#c4504f" },
        "foliage": "#b8433f"
      },
      "minecraft:tags": {
        "tags": ["overworld", "animal", "monster", "plains", "ruby_grove"]
      }
    }
  }
}

The file has two parts:

• description holds the identifier. Use lowercase letters and your own namespace. This is also the name /locate biome uses.
• components holds everything else. Each component switches on one thing the biome does.

Put one biome in each file, and name the file after the biome (ruby_grove.biome.json for wiki:ruby_grove).

The main components

Here are the components you will use most. Every one of them has its own page in Biome components.

How your biome gets into the world

A new biome file on its own does nothing. The game only places a biome that tells it where to go, so a custom biome needs minecraft:replace_biomes:

• targets lists the biomes you take over. Write them without a namespace (plains, not minecraft:plains).
• dimension is minecraft:overworld or minecraft:nether.
• amount is roughly how much of the target you replace, from just above 0 up to 1.
• noise_frequency_scale sets the patch size. Lower values give fewer, bigger patches. Higher values give many small ones.

Tags

Tags are plain words attached to the biome. They do two jobs:

1. Other files check them. Spawn rules and feature rules use tests like has_biome_tag to decide where mobs spawn and where trees or ores go. Give your biome tags like overworld, animal and monster and lots of vanilla content will treat it like a normal overworld biome.
2. Some tags have built-in meaning. For example cold or frozen dress villagers for snow, plains, forest, meadow and swamp choose which flowers grow, and desert and mesa make sand play ambient sounds.

Add your own tag too (here ruby_grove). Then your own features and mobs can target just this biome.

Tags may use letters, numbers, . and _.

Step 2: the client biome

The resource pack side has the same shape, but its root is minecraft:client_biome:

{
  "format_version": "1.21.120",
  "minecraft:client_biome": {
    "description": {
      "identifier": "wiki:ruby_grove"
    },
    "components": {
      "minecraft:grass_appearance": {
        "color": "#c4504f"
      },
      "minecraft:foliage_appearance": {
        "color": "#b8433f"
      },
      "minecraft:water_appearance": {
        "surface_color": "#7a3fd1"
      },
      "minecraft:sky_color": {
        "sky_color": "#ff9a8c"
      },
      "minecraft:fog_appearance": {
        "fog_identifier": "wiki:ruby_fog"
      },
      "minecraft:biome_music": {
        "music_definition": "cherry_grove"
      }
    }
  }
}

Vibrant Visuals adds four more that point at files of their own: atmospherics, lighting, color grading and water. The full list is in Client biome components.

Every component is optional. Anything you leave out uses the default.

Testing

1. Turn both packs on in a new world. Biomes only appear in chunks that have not been made yet.
2. Run /locate biome wiki:ruby_grove to find it.
3. Fly there and check the grass color. If it is the normal green, the client biome identifier does not match.

Next steps

• Fill your biome with ruby ore and plants: Features and feature rules.
• Give it its own mood: Fog.
• Look up any biome name in Biome IDs.