BIOMES DOCUMENTATION
Version: 1.21.0.3

Index#

Overview#

Minecraft biomes can have different terrain characteristics. By writing custom biome data you could:
1) Change the general shape of the terrain.
2) Change the ratio of frequency of biome types.
3) Change the blocks that make up the biome, both at the surface and down below.
4) Change the distribution of decorative features like trees, grass, and flowers.
5) Change the mobs that spawn.
6) Change the climate.
7) ...and more!

JSON Format#

All biomes should specify the version that they target via the "format_version" field. The remainder of the biome data is divided up into independent JSON sub-objects, or components.
In general, a component defines what game behaviors a biome participates in, and the component fields define how it participates.

There are basically two categories of components:
1) Namespaced components, such as those with a 'name:' prefix, that map to specific behaviors in-game. They may have member fields that parameterize that behavior. Only names that have a valid mapping are supported.
2) 'tags' which are defined under the "minecraft:tags" component. Tags consist of alphanumeric characters, along with '.' and '_'. A tag is attached to the biome so that either code or data may check for its existence.

Here is a sample biome schema with additional details and the full list of namespaced components.

{
  "plains": {
    "format_version": "1.20.60",

    "minecraft:climate": {
      "downfall": 0.4,
      "snow_accumulation": [ 0.0, 0.125 ],
      "temperature": 0.8
    },
    "minecraft:overworld_height": {
      "noise_type": "lowlands"
    },
    "minecraft:surface_parameters": {
      "sea_floor_depth": 7,
      "sea_floor_material": "minecraft:gravel",
      "foundation_material": "minecraft:stone",
      "mid_material": "minecraft:dirt",
      "top_material": "minecraft:grass_block"
    },
    "minecraft:overworld_generation_rules": {
      "hills_transformation": [
        [ "forest_hills", 1 ],
        [ "forest", 2 ]
      ],
      "mutate_transformation": "sunflower_plains",
      "generate_for_climates": [
        [ "medium", 3 ],
        [ "warm", 1 ],
        [ "cold", 1 ]
      ]
    },

    "minecraft:tags": {
      "tags": [
        "animal",
        "monster",
        "overworld",
        "plains"
      ]
    }
  }
}

Adding Biomes#

Biomes are read from JSON files in the biomes subfolders of behavior packs. Loading enforces one biome per file; and the file name and the actual biome name must match. Adding a file with a new name to the biome data location will make it available for the game to use, while existing biomes can be overridden using files that match their existing name. Note that if you add a new biome, you'll need to write component data that allows it to participate in world generation (as shown in the full schema below), or else it won't show up in your worlds!

Schema#

Biome Components#

Any components that this Biome uses

Name	Type	Required?	Description
minecraft:capped_surface	Object of type minecraft:capped_surface	Optional	Generates surface on blocks with non-solid blocks above or below.
minecraft:climate	Object of type minecraft:climate	Optional	Describes temperature, humidity, precipitation, and similar. Biomes without this component will have default values.
minecraft:frozen_ocean_surface	Object of type minecraft:frozen_ocean_surface	Optional	Similar to overworld_surface. Adds icebergs.
minecraft:mesa_surface	Object of type minecraft:mesa_surface	Optional	Similar to overworld_surface. Adds colored strata and optional pillars.
minecraft:mountain_parameters	Object of type minecraft:mountain_parameters	Optional	Noise parameters used to drive mountain terrain generation in Overworld.
minecraft:multinoise_generation_rules	Object of type minecraft:multinoise_generation_rules	Optional	Controls how this biome is instantiated (and then potentially modified) during world generation of the nether.
minecraft:overworld_generation_rules	Object of type minecraft:overworld_generation_rules	Optional	Controls how this biome is instantiated (and then potentially modified) during world generation of the overworld.
minecraft:overworld_height	Object of type minecraft:overworld_height	Optional	Noise parameters used to drive terrain height in the Overworld.
minecraft:surface_material_adjustments	Object of type minecraft:surface_material_adjustments	Optional	Specify fine-detail changes to blocks used in terrain generation (based on a noise function).
minecraft:surface_parameters	Object of type minecraft:surface_parameters	Optional	Controls the blocks used for the default Minecraft Overworld terrain generation.
minecraft:swamp_surface	Object of type minecraft:swamp_surface	Optional	Similar to overworld_surface. Adds swamp surface details.
minecraft:tags	Object of type minecraft:tags	Optional	Attach arbitrary string tags to this biome.
minecraft:the_end_surface	Object of type minecraft:the_end_surface	Optional	Use default Minecraft End terrain generation.

Biome Definition#

Contains a description and components to define a Biome.

Name	Type	Required?	Description
components	Object of type Biome Components	Required	Components for this Biome.
description	Object of type Biome Description	Required	Non-component settings, including the Biome name.

Biome Description#

Contains non-component settings for a Biome.

Name	Type	Required?	Description
identifier	String	Required	The name of the Biome, used by other features like the '/locate biome' command.

Biome JSON File#

Contains a format version and a biome definition

Name	Type	Required?	Description
format_version	String	Required	Version of the JSON schema used by this file
minecraft:biome	Object of type Biome Definition	Required	A single biome definition

Block Specifier#

Specifies a particular block. Can be a string block name or a JSON object

Name	Type	Required?	Description
name	String	Required	Name of the block
states	Object	Optional	Contains members named after each state, with boolean, integer, or string values.

Molang Expression#

A JSON field that specifies a Molang expression. Can be an integer, float, boolean, or string.

minecraft:capped_surface#

Generates surface on blocks with non-solid blocks above or below.

Name	Type	Required?	Description
beach_material	Object of type Block Specifier	Optional	Material used to decorate surface near sea level.
ceiling_materials	Array of Object of type Block Specifier	Required	Materials used for the surface ceiling.
floor_materials	Array of Object of type Block Specifier	Required	Materials used for the surface floor.
foundation_material	Object of type Block Specifier	Required	Material used to replace solid blocks that are not surface blocks.
sea_material	Object of type Block Specifier	Required	Material used to replace air blocks below sea level.

minecraft:climate#

Describes temperature, humidity, precipitation, and similar. Biomes without this component will have default values.

Name	Type	Required?	Description
ash	Float	Optional	Density of ash precipitation visuals
blue_spores	Float	Optional	Density of blue spore precipitation visuals
downfall	Float	Optional	Amount that precipitation affects colors and block changes
red_spores	Float	Optional	Density of blue spore precipitation visuals
snow_accumulation	Array of 2 Floats	Optional	Minimum and maximum snow level, each multiple of 0.125 is another snow layer
temperature	Float	Optional	Temperature affects a variety of visual and behavioral things, including snow and ice placement, sponge drying, and sky color
white_ash	Float	Optional	Density of white ash precipitation visuals

minecraft:frozen_ocean_surface#

Similar to overworld_surface. Adds icebergs.

Name	Type	Required?	Description
foundation_material	Object of type Block Specifier	Required	Controls the block type used deep underground in this biome
mid_material	Object of type Block Specifier	Required	Controls the block type used in a layer below the surface of this biome
sea_floor_depth	Integer	Required	Controls how deep below the world water level the floor should occur
sea_floor_material	Object of type Block Specifier	Required	Controls the block type used as a floor for bodies of water in this biome
sea_material	Object of type Block Specifier	Required	Controls the block type used for the bodies of water in this biome
top_material	Object of type Block Specifier	Required	Controls the block type used for the surface of this biome

minecraft:mesa_surface#

Similar to overworld_surface. Adds colored strata and optional pillars.

Name	Type	Required?	Description
bryce_pillars	Boolean	Required	Whether the mesa generates with pillars
clay_material	Object of type Block Specifier	Required	Base clay block to use
foundation_material	Object of type Block Specifier	Required	Controls the block type used deep underground in this biome
hard_clay_material	Object of type Block Specifier	Required	Hardened clay block to use
has_forest	Boolean	Required	Places coarse dirt and grass at high altitudes
mid_material	Object of type Block Specifier	Required	Controls the block type used in a layer below the surface of this biome
sea_floor_depth	Integer	Required	Controls how deep below the world water level the floor should occur
sea_floor_material	Object of type Block Specifier	Required	Controls the block type used as a floor for bodies of water in this biome
sea_material	Object of type Block Specifier	Required	Controls the block type used for the bodies of water in this biome
top_material	Object of type Block Specifier	Required	Controls the block type used for the surface of this biome

minecraft:mountain_parameters#

Noise parameters used to drive mountain terrain generation in Overworld.

Name	Type	Required?	Description
peaks_factor	Float	Optional	Does nothing
steep_material_adjustment	Object of type minecraft:mountain_parameters - steep_material_adjustment settings	Optional	Defines surface material for steep slopes
top_slide	Object of type minecraft:mountain_parameters - top_slide settings	Optional	Controls the density tapering that happens at the top of the world to prevent terrain from reaching too high

minecraft:mountain_parameters - steep_material_adjustment settings#

Defines surface material for steep slopes

Name	Type	Required?	Description
east_slopes	Boolean	Optional	Enable for east-facing slopes
material	Object of type Block Specifier	Optional	Block type use as steep material
north_slopes	Boolean	Optional	Enable for north-facing slopes
south_slopes	Boolean	Optional	Enable for south-facing slopes
west_slopes	Boolean	Optional	Enable for west-facing slopes

minecraft:mountain_parameters - top_slide settings#

Controls the density tapering that happens at the top of the world to prevent terrain from reaching too high.

Name	Type	Required?	Description
enabled	Boolean	Required	If false, top slide will be disabled. If true, other parameters will be taken into account.

minecraft:multinoise_generation_rules#

Controls how this biome is instantiated (and then potentially modified) during world generation of the nether.

Name	Type	Required?	Description
target_altitude	Float	Optional	Altitude with which this biome should be generated, relative to other biomes.
target_humidity	Float	Optional	Humidity with which this biome should be generated, relative to other biomes.
target_temperature	Float	Optional	Temperature with which this biome should be generated, relative to other biomes.
target_weirdness	Float	Optional	Weirdness with which this biome should be generated, relative to other biomes.
weight	Float	Optional	Weight with which this biome should be generated, relative to other biomes.

minecraft:overworld_generation_rules#

Controls how this biome is instantiated (and then potentially modified) during world generation of the overworld.

Name	Type	Required?	Description
generate_for_climates	Array of Object of type minecraft:overworld_generation_rules - Weighted climate categories settings	Optional	Controls the world generation climate categories that this biome can spawn for. A single biome can be associated with multiple categories with different weightings.
hills_transformation	Object of type minecraft:overworld_generation_rules - Weighted biome names settings	Optional	What biome to switch to when converting to a hilly biome
mutate_transformation	Object of type minecraft:overworld_generation_rules - Weighted biome names settings	Optional	What biome to switch to when converting to a mutated biome
river_transformation	Object of type minecraft:overworld_generation_rules - Weighted biome names settings	Optional	What biome to switch to when converting to a river biome (if not the Vanilla 'river' biome)
shore_transformation	Object of type minecraft:overworld_generation_rules - Weighted biome names settings	Optional	What biome to switch to when adjacent to an ocean biome

minecraft:overworld_generation_rules - Weighted biome names settings#

Can be just the string name of a Biome, or an array of any size. If an array, each entry can be a Biome name string, or an array of size 2, where the first entry is a Biome name and the second entry is a positive integer representing how that Biome is weighted against other entries. If no weight is provided, a weight of 1 is used.

minecraft:overworld_generation_rules - Weighted climate categories settings#

An array of any size containing arrays of exactly two elements. For each contained array, the first element is a climate category string ('medium', 'warm', 'lukewarm', 'cold', or 'frozen'). The second element is a positive integer for how much that entry is weighted relative to other entries.

minecraft:overworld_height#

Noise parameters used to drive terrain height in the Overworld.

Name	Type	Required?	Description
noise_params	Array of 2 Floats	Optional	First value is depth - more negative means deeper underwater, while more positive means higher. Second value is scale, which affects how much noise changes as it moves from the surface.
noise_type	"default", "default_mutated", "river", "ocean", "deep_ocean", "lowlands", "taiga", "mountains", "highlands", "extreme", "less_extreme", "beach", "stone_beach", "mushroom", "swamp"	Optional	Specifies a preset based on a built-in setting rather than manually using noise_params

minecraft:surface_material_adjustments#

Specify fine-detail changes to blocks used in terrain generation (based on a noise function).

Name	Type	Required?	Description
adjustments	Array of Object of type minecraft:surface_material_adjustments - surface adjustment settings	Optional	All adjustments that match the column's noise values will be applied in the order listed.

minecraft:surface_material_adjustments - surface adjustment materials settings#

The specific blocks used for this surface adjustment

Name	Type	Required?	Description
foundation_material	Object of type Block Specifier	Optional	Controls the block type used deep underground in this biome when this adjustment is active.
mid_material	Object of type Block Specifier	Optional	Controls the block type used in a layer below the surface of this biome when this adjustment is active.
sea_floor_material	Object of type Block Specifier	Optional	Controls the block type used as a floor for bodies of water in this biome when this adjustment is active.
sea_material	Object of type Block Specifier	Optional	Controls the block type used in the bodies of water in this biome when this adjustment is active.
top_material	Object of type Block Specifier	Optional	Controls the block type used for the surface of this biome when this adjustment is active.

minecraft:surface_material_adjustments - surface adjustment settings#

An adjustment to generated terrain, replacing blocks based on the specified settings.

Name	Type	Required?	Description
height_range	Array of 2 Molang expressions	Optional	Defines a range of noise values [min, max] for which this adjustment should be applied.
materials	Object of type minecraft:surface_material_adjustments - surface adjustment materials settings	Required
noise_frequency_scale	Float	Optional	The scale to multiply by the position when accessing the noise value for the material adjustments.
noise_range	Array of 2 Floats	Optional	Defines a range of noise values [min, max] for which this adjustment should be applied.

minecraft:surface_parameters#

Controls the blocks used for the default Minecraft Overworld terrain generation.

Name	Type	Required?	Description
foundation_material	Object of type Block Specifier	Required	Controls the block type used deep underground in this biome.
mid_material	Object of type Block Specifier	Required	Controls the block type used in a layer below the surface of this biome.
sea_floor_depth	Integer	Required	Controls how deep below the world water level the floor should occur.
sea_floor_material	Object of type Block Specifier	Required	Controls the block type used as a floor for bodies of water in this biome.
sea_material	Object of type Block Specifier	Required	Controls the block type used for the bodies of water in this biome.
top_material	Object of type Block Specifier	Required	Controls the block type used for the surface of this biome.

minecraft:swamp_surface#

Similar to overworld_surface. Adds swamp surface details.

Name	Type	Required?	Description
foundation_material	Object of type Block Specifier	Required	Controls the block type used deep underground in this biome.
mid_material	Object of type Block Specifier	Required	Controls the block type used in a layer below the surface of this biome.
sea_floor_depth	Integer	Required	Controls how deep below the world water level the floor should occur.
sea_floor_material	Object of type Block Specifier	Required	Controls the block type used as a floor for bodies of water in this biome.
sea_material	Object of type Block Specifier	Required	Controls the block type used for the bodies of water in this biome.
top_material	Object of type Block Specifier	Required	Controls the block type used for the surface of this biome.

minecraft:tags#

Attach arbitrary string tags to this biome.

Name	Type	Required?	Description
tags	Array of String	Required	Array of string tags used by other systems such as entity spawning

minecraft:the_end_surface#

Use default Minecraft End terrain generation.