Bedrock Edition beta biomes documentation

This is the biome documentation for Bedrock Edition. New features, components, and capabilities in this release are not final and might change without notice before the final release. Be sure to check the documentation once the release is out of beta if the add-on isn't working properly. Resource and behavior packs created for the beta are not guaranteed to work on the final release.

Overview
Biomes describe how a local patch of the world should look and behave. By writing custom biome data, the player can:


 * 1) Change the general shape of terrain for a biome
 * 2) Change the ratio of frequency of biome types
 * 3) Change the blocks that make up the biome, both at the surface and below.
 * 4) Change the distribution of decorative features (e.g. trees, grass, etc.) for a biome.
 * 5) Change the mobs that spawn for a biome
 * 6) Change the climate for a biome

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 you can think of the presence of a component as defining what game behaviors a biome participates in with the component fields defining how it participates. Broadly there are two categories of components:


 * 1) Namespaced components (i.e. those with a 'name:' prefix) 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) Components with no namespace are treated as 'tags': any name consisting of alphanumeric characters, '.' and '_' is permitted; the tag is attached to the biome so that either code or data may check for its existence; tag components may not have member fields.

See the biome properties below for registering biomes.


 * Here is an example of overworld biome

{ "format_version": "1.13.0", "minecraft:biome": { "description": { "identifier": "plains" },   "components": { "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", "sea_material": "minecraft:water" },     "minecraft:overworld_generation_rules": { "hills_transformation": [ [ "forest_hills", 1 ], [ "forest", 2 ] ],       "mutate_transformation": "sunflower_plains", "generate_for_climates": [ [ "medium", 3 ], [ "warm", 1 ], [ "cold", 1 ] ]     },

"animal": {}, "monster": {}, "overworld": {}, "plains": {}, "bee_habitat": {} } } } Here is an example of another overworld biome. This one is custom. { "format_version": "1.13.0", "minecraft:biome": { "description": { "identifier": "taiga_extreme_mountains" },   "components": { "minecraft:climate": { "downfall": 0.8, "snow_accumulation": [ 0.0, 0.125 ], "temperature": 0.25 },     "minecraft:overworld_height": { "noise_params": [ 2.6, 0.64 ] },     "minecraft:surface_parameters": { "sea_floor_depth": 7, "sea_floor_material": "minecraft:gravel", "foundation_material": "minecraft:stone", "mid_material": "minecraft:dirt", "top_material": "minecraft:podzol", "sea_material": "minecraft:water" },     "minecraft:surface_material_adjustments": { "adjustments": [ {           "materials": { "top_material": "minecraft:grass" },           "noise_range": [ 0.25, 1.0 ] }       ]      },      "minecraft:overworld_generation_rules": { "hills_transformation": "extreme_hills", "mutate_transformation": "extreme_hills_mutated", "generate_for_climates": [ [ "frozen", 1 ], [ "cold", 1 ] ]     },

"animal": {}, "monster": {}, "overworld": {}, "pine": {}, "taiga": {} } } } Here is an example of nether biome { "format_version": "1.13.0", "minecraft:biome": { "description": { "identifier": "basalt_deltas" },   "components": { "minecraft:climate": { "downfall": 0.0, "snow_accumulation": [ 0.0, 0.125 ], "temperature": 2.0, "white_ash": 2.0 },     "minecraft:nether_generation_rules": { "target_temperature": -0.5, "target_humidity": 0.0, "target_altitude": 0.0, "target_weirdness": 0.0, "weight": 0.175 },     "minecraft:surface_parameters": { "sea_floor_depth": 1, "sea_floor_material": "minecraft:basalt", "foundation_material": "minecraft:netherrack", "mid_material": "minecraft:basalt", "top_material": "minecraft:basalt", "sea_material": "minecraft:lava" },     "minecraft:surface_material_adjustments": { "adjustments": [ {           "materials": { "top_material": "minecraft:blackstone", "mid_material": "minecraft:blackstone" },           "noise_frequency_scale": 0.1, "noise_range": [ -1.0, 0.0 ] },         {            "materials": { "top_material": "minecraft:gravel" },           "height_range": [ "variable.sea_level - 3", "variable.sea_level + 2" ], "noise_frequency_scale": 0.4125, "noise_range": [ -1.0, 0.5 ] }       ]      },

"nether": {}, "basalt_deltas": {}, "spawn_many_magma_cubes": {}, "spawn_ghast": {} } } }

Adding biomes
Biomes are read from JSON files in the biomes subfolders of behavior packs. Loading enforces one biome per file; 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 via 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, or else it won't show up in the worlds.

minecraft:climate
Describes temperature, humidity, precipitation, etc. Biomes without this component will have default values.


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Decimal
 * temperature
 * 0.0
 * Decimal
 * downfall
 * 0.0
 * List
 * snow_accumulation
 * [ 0.0, 0.0 ]
 * Decimal
 * blue_spores
 * 0.0
 * Controls how many blue ash will be in the air.
 * Decimal
 * red_spores
 * 0.0
 * Controls how many red ash will be in the air.
 * Decimal
 * ash
 * 0.0
 * Controls how many black ash will be in the air.
 * Decimal
 * white_ash
 * 0.0
 * Controls how many white ash will be in the air.
 * }
 * Decimal
 * ash
 * 0.0
 * Controls how many black ash will be in the air.
 * Decimal
 * white_ash
 * 0.0
 * Controls how many white ash will be in the air.
 * }
 * }

minecraft:overworld_height
Noise parameters used to drive terrain height in the Overworld.


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * List
 * noise_params
 * [ 150.0, 32.0 ]
 * First number controls the height at which the biome is. Mountains have this number set to big value for example. Second number controls height variation of this biome. The lower the number is the more flat the biome will be.
 * String
 * noise_type
 * default
 * Controls the height of the biome. Including (from lowest to highest) deep_ocean, ocean, swamp, beach, lowlands, taiga, default, mountains, default_mutated, highlands, stone_beach, less_extreme, extreme.
 * }
 * Controls the height of the biome. Including (from lowest to highest) deep_ocean, ocean, swamp, beach, lowlands, taiga, default, mountains, default_mutated, highlands, stone_beach, less_extreme, extreme.
 * }

minecraft:surface_parameters
Control the blocks used for the default Minecraft Overworld terrain generation.


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Integer
 * sea_floor_depth
 * Controls how deep below the world water level the floor should occur.
 * String
 * sea_floor_material
 * Controls the block type used as a floor for bodies of water in this biome.
 * String
 * top_material
 * Controls the block type used for the surface of this biome.
 * String
 * mid_material
 * Controls the block type used in a layer below the surface of this biome.
 * String
 * foundation_material
 * Controls the block type used deep underground in this biome.
 * String
 * sea_material
 * Controls the block under water level.
 * }
 * Controls the block type used in a layer below the surface of this biome.
 * String
 * foundation_material
 * Controls the block type used deep underground in this biome.
 * String
 * sea_material
 * Controls the block under water level.
 * }
 * sea_material
 * Controls the block under water level.
 * }
 * }

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


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * List
 * adjustments
 * All adjustments that match the column's noise values will be applied in the order listed.
 * All adjustments that match the column's noise values will be applied in the order listed.
 * All adjustments that match the column's noise values will be applied in the order listed.

materials

 * "top_material" - Controls the block type used for the surface of this biome when this adjustment is active.


 * "mid_material" - Controls the block type used in a layer below the surface of this biome when this adjustment is active.


 * "floor_material" - Controls the block type used as a floor for bodies of water in this biome when this adjustment is active.


 * "foundation_material" - Controls the block type used deep underground in this biome when this adjustment is active.

noise_range
Defines a range of noise values [min, max] for which this adjustment should be applied. Default value: [ 0.0, 0.0 ]


 * }

minecraft:swamp_surface
Similar to surface_parameters. Adds swamp surface details.


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Integer
 * sea_floor_depth
 * Controls how deep below the world water level the floor should occur.
 * String
 * sea_floor_material
 * Controls the block type used as a floor for bodies of water in this biome.
 * String
 * top_material
 * Controls the block type used for the surface of this biome.
 * String
 * mid_material
 * Controls the block type used in a layer below the surface of this biome.
 * String
 * foundation_material
 * Controls the block type used deep underground in this biome.
 * String
 * sea_material
 * Controls the block under water level.
 * }
 * Controls the block type used in a layer below the surface of this biome.
 * String
 * foundation_material
 * Controls the block type used deep underground in this biome.
 * String
 * sea_material
 * Controls the block under water level.
 * }
 * sea_material
 * Controls the block under water level.
 * }
 * }

minecraft:frozen_ocean_surface
Similar to surface_parameters. Adds icebergs.


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Integer
 * sea_floor_depth
 * Controls how deep below the world water level the floor should occur.
 * String
 * sea_floor_material
 * Controls the block type used as a floor for bodies of water in this biome.
 * String
 * top_material
 * Controls the block type used for the surface of this biome.
 * String
 * mid_material
 * Controls the block type used in a layer below the surface of this biome.
 * String
 * foundation_material
 * Controls the block type used deep underground in this biome.
 * String
 * sea_material
 * Controls the block under water level.
 * }
 * Controls the block type used in a layer below the surface of this biome.
 * String
 * foundation_material
 * Controls the block type used deep underground in this biome.
 * String
 * sea_material
 * Controls the block under water level.
 * }
 * sea_material
 * Controls the block under water level.
 * }
 * }

minecraft:mesa_surface
Similar to surface_parameters. Adds colored strata and optional pillars.


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * top_material
 * Controls the block type used for the surface of this biome.
 * String
 * mid_material
 * Controls the block type used in a layer below the surface of this biome.
 * String
 * sea_floor_material
 * Controls the block type used as a floor for bodies of water in this biome.
 * String
 * foundation_material
 * Controls the block type used deep underground in this biome.
 * Integer
 * sea_floor_depth
 * Controls how deep below the world water level the floor should occur.
 * String
 * clay_material
 * String
 * hard_clay_material
 * Boolean
 * bryce_pillars
 * Boolean
 * has_forest
 * String
 * sea_material
 * Controls the block under water level.
 * }
 * clay_material
 * String
 * hard_clay_material
 * Boolean
 * bryce_pillars
 * Boolean
 * has_forest
 * String
 * sea_material
 * Controls the block under water level.
 * }
 * Boolean
 * has_forest
 * String
 * sea_material
 * Controls the block under water level.
 * }
 * String
 * sea_material
 * Controls the block under water level.
 * }
 * Controls the block under water level.
 * }
 * }

minecraft:nether_surface
Use default Minecraft Nether terrain generation with use of parameters written here.

minecraft:the_end_surface
Use default Minecraft End terrain generation.

minecraft:overworld_generation_rules
Control how this biome is instantiated (and then potentially modified) during world generation.


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * hills_transformation
 * "", [ "", 0 ]
 * Controls what biome is used as common sub-biome of this biome. Multiple biomes ca be used.
 * String
 * mutate_transformation
 * Controls what biome is used as rare sub-biome of this biome.
 * String
 * river_transformation
 * Controls what biome is used as rivers in this biome.
 * String
 * shore_transformation
 * Controls what biome is used as border between mainland and sea in this biome.
 * List
 * generate_for_climates
 * [ "", 0 ]
 * Controls the world generation climate categories that thism biome can spawn for. A single biome can be associated with multiple categories with different weightings.
 * }
 * Controls what biome is used as border between mainland and sea in this biome.
 * List
 * generate_for_climates
 * [ "", 0 ]
 * Controls the world generation climate categories that thism biome can spawn for. A single biome can be associated with multiple categories with different weightings.
 * }
 * Controls the world generation climate categories that thism biome can spawn for. A single biome can be associated with multiple categories with different weightings.
 * }

Biome Definition Properties
These properties are part of the Biome Definition. This helps the system determine how to parse and initialize this biome.


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * format_version
 * Specifies the version of the game this biome was made in. If the version is lower than the current version, any changes made to the biome in the vanilla version will be applied to it.
 * }
 * Code Example
 * Specifies the version of the game this biome was made in. If the version is lower than the current version, any changes made to the biome in the vanilla version will be applied to it.
 * }
 * Code Example


 * Example

{ "format_version": "1.13.0", "minecraft:biome": { "components": { ...  }    ...  } }

Biome Description Properties

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * identifier
 * The identifier for this biome. The name may include a namespace.
 * }
 * The identifier for this biome. The name may include a namespace.
 * }