Placed feature

A placed feature determines where a configured feature should be attempted to be placed using placement modifiers. They can be referenced in biomes.

Placed features are stored as JSON files within a data pack, in the data/<namespace>/worldgen/placed_feature folder.

JSON format

• [NBT Compound / JSON Object]: Root object.
  • [String][NBT Compound / JSON Object] feature: One configured feature (an [String] ID, or a new [NBT Compound / JSON Object] configured feature definition) — The feature to place.
  • [NBT List / JSON Array] placement: A list of placement modifiers, applied in order.
    • [NBT Compound / JSON Object]: A placement modifier.
      • [String] type: The type of this placement modifier.
      • Other additional fields depend on the value of [String] type, described below.

Placement modifiers

When a placed feature is referenced through a biome file, the placed feature tells the configured feature in the feature field to place once on the northwest corner of each chunk at the bottom layer of the world. When a placed feature is referenced from a configured feature file or through the /place command, the placed feature tells the configured feature in the feature field to place once where the original feature/player is located respectively. Placement modifiers can change the position of the feature and the amount of placements.

Placed features are applied in order to determine where feature placement attempt(s) should occur. This can include moving the placement's position, number of positions, and filtering out positions based on given conditions. Each placement attempt applies placement modifiers separately.

The possible values for [String] type and associated additional fields:

• biome — Returns the current position if the biome at that position includes this placed feature, otherwise returns empty. No additional field. In effect, this predicate restricts features from being placed outside the edges of any biome that generates the feature. This modifier type cannot be used in placed features that are referenced from other configured features (for example, from entries in a random_selector type feature). Minecraft does not catch this type of error automatically on trying to load the world; instead the game runs normally until it tries to generate the feature, which causes the game to crash.

• block_predicate_filter — Returns the current position when the predicate is passed, otherwise return empty.
  • [NBT Compound / JSON Object] predicate: The block predicate to test.
    • [String] type: The type of the block predicate. See Block predicate § Types for options.
    • additional fields depending on [String] type. See Block predicate § Types.

• count — Returns multiple copies of the current block position. Although the count is limited to 4096, multiple count predicates can be used, allowing them to be stacked multiplicatively to achieve much higher values.
  • [Int][NBT Compound / JSON Object] count: Value between 0 and 4096 (inclusive).
    • Int provider see Template:Nbt inherit/int_provider/template

• count_on_every_layer — In the horizontal relative range (0,0) to (16,16), at each vertical layer separated by air, lava or water, tries to randomly select the specified number of horizontal positions, whose Y coordinate is one block above this layer at this selected horizontal position. Return these selected positions.
  • [Int][NBT Compound / JSON Object] count：Count on each layer. Value between 0 and 256 (inclusive).
    • Int provider see Template:Nbt inherit/int_provider/template

• cuboid — Repeats a feature in a cuboid shape.
  • [Int][NBT Compound / JSON Object] xz_size: The size of the cuboid along the x and z axes. Value between 1 and 16 (inclusive).
  • [Int][NBT Compound / JSON Object] y_size: The size of the cuboid along the y axis. Value between 1 and 16 (inclusive).
    • Int provider see Template:Nbt inherit/int_provider/template
  • [Boolean][NBT Compound / JSON Object] include_interior: Optional; Whether to place interior blocks of the cuboid. Defaults to true.
  • [Boolean][NBT Compound / JSON Object] include_edges: Optional; Whether to place edge blocks of the cuboid. Defaults to true. If set to false, the cuboid is generated as "somewhat rounded".

• environment_scan — Scans blocks either up or down, until the target condition is met. Returns the block position for which the target condition matches. If no target can be found within the maximum number of steps, returns empty.
  • [String] direction_of_search: One of up or down.
  • [Int] max_steps: Value between 1 and 32 (inclusive).
  • [NBT Compound / JSON Object] target_condition: The block predicate that is searched for.
    • [String] type: The type of the block predicate. See Block predicate § Types for options.
    • additional fields depending on [String] type. See Block predicate § Types.
  • [NBT Compound / JSON Object] allowed_search_condition: (optional) If specified, each step must match this block predicate in order to continue the scan. If a block that doesn't match it is met, but no target block found, returns empty.
    • [String] type: The type of the block predicate. See Block predicate § Types for options.
    • additional fields depending on [String] type. See Block predicate § Types.

• fixed_placement — Returns all specified positions, if they are in the current chunk.
  • [NBT List / JSON Array] positions: A list of all placement positions. Requires at least one element.​^{[upcoming: JE 26.4]}
    • [NBT List / JSON Array]: A position
      • [Int]: x coordinate
      • [Int]: y coordinate
      • [Int]: z coordinate

• height_range — Sets the Y coordinate to a value provided by a height provider. Returns the new position.
  • [NBT Compound / JSON Object] height: The new Y coordinate.
    • Height provider see Template:Nbt inherit/height provider/template

• heightmap — Sets the Y coordinate to one block above the heightmap. Returns the new position.
  • [String] heightmap: The heightmap to use. One of MOTION_BLOCKING, MOTION_BLOCKING_NO_LEAVES, OCEAN_FLOOR, OCEAN_FLOOR_WG, WORLD_SURFACE or WORLD_SURFACE_WG.

• in_square — For both X and Z, it adds a random value between 0 and 15 (both inclusive). This is a shortcut for a random_offset modifier with y_spread set to 0 and xz_spread as a uniform int from 0 to 15. No additional fields.

• noise_based_count — When the noise value at the current block position is positive, returns multiple copies of the current block position, whose count is based on a noise value and can gradually change based on the noise value. When noise value is negative or 0, returns empty. The count is calculated by ceil((noise(x / noise_factor, z / noise_factor) + noise_offset) * noise_to_count_ratio).
  • [Double] noise_factor: Scales the noise input horizontally. Higher values make for wider and more spaced out peaks.
  • [Double] noise_offset：(optional, defaults to 0) Vertical offset of the noise.
  • [Int] noise_to_count_ratio: Ratio of noise value to count.

• noise_threshold_count — Returns multiple copies of the current block position. The count is either below_noise or above_noise, based on the noise value at the current block position. First checks noise(x / 200, z / 200) < noise_level. If that is true, uses below_noise, otherwise above_noise.
  • [Double] noise_level: The threshold within the noise of when to use below_noise or above_noise.
  • [Int] below_noise: The count when the noise is below the threshold. Value lower than 0 is treated as 0.
  • [Int] above_noise: The count when the noise is above the threshold. Value lower than 0 is treated as 0.

• offset — Applies an offset to the current position.
  • [Int][NBT Compound / JSON Object] x: Value between -16 and 16 (inclusive).
  • [Int][NBT Compound / JSON Object] y: Value between -16 and 16 (inclusive).
  • [Int][NBT Compound / JSON Object] z: Value between -16 and 16 (inclusive).
    • Int provider see Template:Nbt inherit/int_provider/template

• random_chance — Gates the feature being placed behind a random chance.
  • [Float][NBT Compound / JSON Object] chance: Value between 0 and 1 representing the chance that the feature gets placed.

• randomly_selected — Randomly selects a placement modifier from a list and delegates placement to it.
  • [NBT List / JSON Array] placements: Non-empty list of placements modifiers to pick from.

• rarity_filter — Either returns the current position or empty. The chance is calculated as 1 / chance.
  • [Int] chance: Must be a positive integer.

• surface_relative_threshold_filter — Returns the current position if the surface is inside a range. Otherwise returns empty.
  • [String] heightmap：The heightmap to use. One of MOTION_BLOCKING, MOTION_BLOCKING_NO_LEAVES, OCEAN_FLOOR, OCEAN_FLOOR_WG, WORLD_SURFACE or WORLD_SURFACE_WG.
  • [Int] min_inclusive: The minimum relative height from the surface to current position.
  • [Int] max_inclusive: The maximum relative height from the surface to current position.

• surface_water_depth_filter — If the number of blocks of a motion blocking material under the surface (the top non-air block) is less than the specified depth, return the current position. Otherwise return empty.
  • [Int] max_water_depth: The maximum allowed depth.

History

Java Edition
1.18			pre1				Introduced placed features, stored in worldgen/placed_feature directory.
1.21			pre2				Added fixed_placement placement modifier.
1.21.2			24w33a				Removed carving_mask placement modifier.
26.1			pre3				Changed the maximum value of [Int][NBT Compound / JSON Object] count field from count placement modifier to 4096.
26.3			snap2				Renamed random_offset to offset.
							Removed offset fields xz_spread and y_spread.
							Added offset fields x, y and z.
			snap3				Added cuboid and random_chance placement modifiers.
			snap8				Added the randomly_selected placement modifier.
Upcoming Java Edition
26.4			snap1				The possible domain in the XZ plane of placed features included in biomes is now validated: feature placement can only occur within a 3×3 chunk region: as such, it is not valid for a Placed Feature to select a position outside of that range.
							The xz_size and y_size fields in cuboid have been adjusted to represent the actual size of the cuboid, instead of implicitly being 1 block larger.
							The positions field in fixed_placement now requires at least one element.

Removed modifiers

Added in 1.18 Pre-release 1. Removed in 24w33a:

• carving_mask — Returns all positions in the current chunk that have been carved out by a carver. This does not include blocks carved out by noise caves.
  • [String] step: The carving step. Either air or liquid. 'Liquid'-type carvers are not used in vanilla.

External links

• Placed feature Generator on misode.github.io