FEATURES DOCUMENTATION
Version: 1.16.220.2

Index

Overview
JSON format
Adding features
Supported features
minecraft:aggregate_feature
minecraft:sequence_feature
minecraft:cave_carver_feature
minecraft:growing_plant_feature
minecraft:hell_cave_carver_feature
minecraft:ore_feature
minecraft:scatter_feature
minecraft:search_feature
minecraft:single_block_feature
minecraft:snap_to_surface_feature
minecraft:structure_template_feature
minecraft:underwater_cave_carver_feature
minecraft:tree_feature
minecraft:weighted_random_feature
Attaching features
Feature rules
Feature rule schema
Forced features
Back to top

Overview

Features are decorations scattered throughout the world. Things such as trees, plants, flowers, springs, ore, and coral are all features. Basically, if it isn't the terrain or a mob, it's probably a feature!
Features can be standalone or composed of multiple sub-features. In practice, most features in Minecraft are defined as a chain of two or more features. These chains typically end with features that place blocks in the world. Other feature types control flow such as conditional, sequential, or random distribution.
Back to top

JSON format

All features must specify the version that they target via the "format_version" field. The remainder of the data is contained in independet JSON sub-objects for each supported feature type. These feature types define the behavior of the feature and include properties specific to that behavior. To be valid, a definition must include exactly one of these type objects. See the full feature schema below for additional details and the full list of supported feature types.

Here is a sample feature

Back to top

Adding features

Features are read from JSON files in the "features" subfolder of behavior packs. Loading enforces one feature per file; the file name and the name of the feature must match. Feature names can include a namespace of the form "namespace:feature_name" to help distinguish them from features that may be in other behavior packs. This namespace is not considered when matching the filename to the feature name. For example, in a file called "my_tree_feature.json" both "my_tree_feature" and "my_pack_name:my_tree_feature" would be valid identifiers. If two behavior packs define the same feature name (including namespace), then the feature from the highest pack in the stack will be used. This allows users to override base features if desired.
Back to top

Supported features

minecraft:aggregate_feature

'minecraft:aggregate_feature' places a collection of features in an arbitary order. All features in the collection use the same input position. Features should not depend on each other, as there is no guarantee on the order the features will be placed.
Succeeds if: At lease one feature is placed successfully.
Fails if: All features fail to be placed.

Example use: scattering multiple different plants around a monument.

Back to top

minecraft:sequence_feature

'minecraft:sequence_feature' places a collection of features sequentially, in the order they appear in data. The output position of the previous feature is used as the input position for the next. For example, a tree feature is placed at (0, 0, 0) and places blocks up to (0, 10, 0). The next feature in the sequence begins at (0, 10, 0).
Succeeds if: All features in the sequence are successfully placed.
Fails if: Any feature in the sequence fails to be placed. Features that have not yet been placed at the time of failure are skipped.

Example use: Scattering fruit throughout the canopy of a tree.

Back to top

minecraft:cave_carver_feature

'minecraft:cave_carver_feature' carves a cave through the world in the current chunk, and in every chunk around the current chunk in an 8 radial pattern.This feature will also only work when placed specifically in the pass "pregeneration_pass".

Example use: Carve caves normally.

Back to top

minecraft:growing_plant_feature

'minecraft:growing_plant_feature' places a growing plant in the world. A growing plant is a column that is anchored either to the ceiling or the floor, based on its growth direction.
The growing plant has a body and a head, where the head is the tip of the plant, and the body consists of the remainder blocks.
This feature can be used to define growing plants with variable body and head blocks, e.g. Cave Vines.

Example use: Defining a growing plant feature with variable body and head blocks and height distribution.

Back to top

minecraft:hell_cave_carver_feature

'minecraft:hell_cave_carver_feature' carves a cave through the Nether in the current chunk, and in every chunk around the current chunk in an 8 radial pattern.This feature will also only work when placed specifically in the pass "pregeneration_pass".

Example use: Carve nether caves normally.

Back to top

minecraft:ore_feature

'minecraft:ore_feature' places a vein of blocks to simulate ore deposits. Despite the name, any block can be placed by this feature. During placement, existing world blocks are checked to see if they can be replaced by the new ore block based on the list provided in the 'may_replace' field. If no 'may_replace' field is specified, the ore block can replace any existing block.
Succeeds if: At least one ore block is successfully placed.
Fails if: All ore block placements fail.

Example use: Oil deposits in the sand.

Back to top

minecraft:scatter_feature

'minecraft:scatter_feature' scatters a feature throughout a chunk. The 'x', 'y', and 'z' fields are per-coordinate parameters. Note that coordinates represent an offset from the input position, not an absolute position. Coordinates may be a single value, a random distribution, or molang expression that resolves to a numeric value. The 'coordinate_eval_order' field is provided for finer control of coordinate resolution (particularly when using the 'grid' distribution). 'iterations' controls how many individual placements should occur if the 'scatter_chance' check succeeds. The 'scatter_chance' check happens once, so either all placements will run or none will.
Succeeds if: At least one feature placement succeeds.
Fails if: All feature placements fail.

Example use: Scattering flowers at sea level across half the chunks in a biome.

Back to top

minecraft:search_feature

'minecraft:search_feature' sweeps a volume searching for a valid placement location for its referenced feature. The 'search_volume' field specifies the axis-aligned bounding box that defines the boundaries of the search. The search sweeps along the axis defined by the 'search_axis' field, layer by layer. For example, if 'search_axis' = '-x', blocks with greater x values will be checked before blocks with lower x values. Each layer is searched from the bottom-left to the top-right before moving to the next layer along the axis. By default, only one valid position must be found, but this can be altered by specifying the 'required_successes' field. If fewer than the required successes are found, no placement will occur.
Succeeds if: The number of valid positions is equal to the value specified by 'required_successes'.
Fails if: The number of valid positions is less than the value specified by 'required_successes'.

Example use: Attaching apples to a tree canopy

Back to top

minecraft:single_block_feature

'minecraft:single_block_feature' places a single block in the world. The 'may_place_on' and 'may_replace' fields are allowlists which specify where the block can be placed. If these fields are omitted, the block can be placed anywhere. The block's internal survivability and placement rules can optionally be enforced with the 'enforce_survivability_rules' and 'enforce_placement_rules' fields. These rules are specified per-block and are typically designed to produce high quality gameplay or natural behavior. However, enabling this enforcement may make it harder to debug placement failures.
Succeeds if: The block is successfully placed in the world.
Fails if: The block fails to be placed.

Example use: Placing a single pumpkin block.

Back to top

minecraft:snap_to_surface_feature

'minecraft:snap_to_surface_feature' snaps the y-value of a feature placement pos to the floor or the ceiling within the provided 'vertical_search_range'. The placement biome is preserved. If the snap position goes outside of the placement biome, placement will fail.

Example use: Define a feature that snaps the 'cave_vine_feature' to the ceiling.

Back to top

minecraft:structure_template_feature

'minecraft:structure_template_feature' places a structure in the world. The structure must be stored as a .mcstructure file in the "structures" subdirectory of a behavior pack. It is possible to reference structures that are part of other behavior packs, they do not need to come from the same behavior pack as this feature. Constraints can be defined to specify where the structure is allowed to be placed. During placement, the feature will search for a position within the 'adjustment_radius' that satisfies all constraints. If none are found, the structure will not be placed.
Succeeds if: The structure is placed in the world.
Fails if: The structure fails to be placed within the world.

Example use: Place a hot air balloon structure that "floats" in the air.

Back to top

minecraft:underwater_cave_carver_feature

'minecraft:underwater_cave_carver_feature' carves a cave through the world in the current chunk, and in every chunk around the current chunk in an 8 radial pattern.This feature will specifically target creating caves only below sea level.
This feature will also only work when placed specifically in the pass "pregeneration_pass".

Example use: Carve caves normally.

Back to top

minecraft:tree_feature

Feature type 'minecraft:tree_feature' has not yet been documented.
Back to top

minecraft:weighted_random_feature

'minecraft:weighted_random_feature' randomly selects and places a feature based on a weight value. Weights are relative, with higher values making selection more likely.
Succeeds if: The selected feature is placed.
Fails if: The selected feature fails to be placed.

Example use: Selecting and placing a variant of a flower.

Back to top

Feature schema

Here is the complete feature schema



Attaching features

Features must be attached to at least one biome in order to show up in the world. During world generation, biomes attempt to place their attached features chunk-by-chunk. Features can be attached in two ways:
1) Via a feature rule definition
2) Via the "minecraft:forced_features" biome component
Back to top

Feature rules

Feature rules are separate JSON definition files found in the "feature_rules" subfolder of behavior packs. Feature rules follow the same filename rules as features. Each feature rule controls exactly one feature and serves as the root of a chain of feature data. To attach a feature to a biome with a feature rule, the "conditions" object must include the "minecraft:biome_filter" field. This is a list of filter tests that are performed on each biome to determine if the feature should be attached. Most relevant is the "has_biome_tag" test.

Here is a sample feature rule

Back to top

Feature rule schema



Back to top

Forced features

Features attached with the second method are called "forced" or "explicit" features. Unlike feature rules, forced features are not defined in separate JSON files. Instead, they are specified in the existing biome JSON definitions via the "minecraft:forced_features" component. Like feature rules, this component includes fields that define when features should be placed ("placement_pass") and how they should be scattered ("distribution"). For more information about biome components (including the complete JSON schema), consult the biome documentation.
Back to top