Version: 1.21.60.24
This is the documentation for a preview version of Minecraft. The new features, components, and capabilities in this version are not final and may change without prior notice before the final release.
Be sure to check the documentation once the release is no longer in preview if your add-on is not working correctly. Resource and behavior packs created for this preview version are not guaranteed to work in the final version.
Minecraft biomes can have different terrain features. When writing custom biome data, you can:
All biomes must specify the version they target using the "format_version" field. The remaining biome data is divided into independent JSON sub-objects, or components.
In general, a component defines the game behaviors in which a biome participates, and the component fields define how it participates.
'name:' prefix, which are assigned to specific in-game behaviors. These can have fields that parametrize that behavior. Only names with a valid assignment are supported.
"minecraft:tags" component. Tags consist of alphanumeric characters, along with '.' and '_'. A tag is attached to the biome so that the code or data can check for its existence.
Below is an example of a biome schema with additional details and a complete list of namespace components:
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!Back to topSchema
Biome Components
Any components that this Biome uses| Name | Type | Required? | Description |
|---|---|---|---|
| minecraft:capped_surface | Object | Optional | Generates surface on blocks with non-solid blocks above or below. |
| minecraft:climate | Object | Optional | Describes temperature, humidity, precipitation, and similar. Biomes without this component will have default values. |
| minecraft:frozen_ocean_surface | Object | Optional | Similar to overworld_surface. Adds icebergs. |
| minecraft:mesa_surface | Object | Optional | Similar to overworld_surface. Adds colored strata and optional pillars. |
| minecraft:mountain_parameters | Object | Optional | Noise parameters used to drive mountain terrain generation in Overworld. |
| minecraft:multinoise_generation_rules | Object | Optional | Controls how this biome is instantiated (and then potentially modified) during world generation of the nether. |
| minecraft:overworld_generation_rules | Object | Optional | Controls how this biome is instantiated (and then potentially modified) during world generation of the overworld. |
| minecraft:overworld_height | Object | Optional | Noise parameters used to drive terrain height in the Overworld. |
| minecraft:surface_material_adjustments | Object | Optional | Specify fine-detail changes to blocks used in terrain generation (based on a noise function). |
| minecraft:surface_parameters | Object | Optional | Controls the blocks used for the default Minecraft Overworld terrain generation. |
| minecraft:swamp_surface | Object | Optional | Similar to overworld_surface. Adds swamp surface details. |
| minecraft:tags | Object | Optional | Attach arbitrary string tags to this biome. |
| minecraft:the_end_surface | Object | 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.Back to topminecraft: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.Back to topminecraft: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.Back to topminecraft: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. |
| 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.Back to top