minecraft.wiki-mirror/wiki_backup/placed feature.txt

{{Exclusive|java}}

A '''placed feature''' determines where a '''[[configured feature]]''' should be attempted to be placed using placement modifiers. They can be referenced in [[Custom biome|biomes]].

Placed features are stored as JSON files within a data pack, in the {{Cd|code=data/<namespace>/worldgen/placed_feature}} folder.

== JSON Format ==

<div class="treeview">
* {{nbt|compound}}: Root object.
** {{nbt|string}}{{nbt|compound|feature}}: {{json ref|configured feature|inline=1}} &mdash; The feature to place.
** {{nbt|list|placement}}: A list of placement modifiers, applied in order.
*** {{nbt|compound}}: A placement modifier.
**** {{nbt|string|type}}: The type of this placement modifier.
**** Other additional fields depend on the value of {{nbt|string|type}}, described below.
</div>

== Placement Modifiers ==
When a placed feature is referenced through a biome file, the placed feature tells the configured feature in the {{Cd|code=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 [[Commands/place (Java Edition)|/place]] command, the placed feature tells the configured feature in the {{Cd|code=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 {{nbt|string|type}} and associated additional fields:

<div class="treeview" id="biome" style="margin-top: 1em;">
* '''biome'''&mdash;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'''&mdash;Returns the current position when the predicate is passed, otherwise return empty.
** {{nbt|compound|predicate}}: The block predicate to test.
***{{nbt inherit/block_predicate}}
</div>

<div class="treeview" id="carving_mask" style="margin-top: 1em;">
* '''carving_mask'''&mdash;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.
** {{nbt|string|step}}: The carving step. Either <code>air</code> or <code>liquid</code>. 'Liquid'-type carvers are not used in vanilla.
</div>

<div class="treeview" id="count" style="margin-top: 1em;">
* '''count'''&mdash;Returns multiple copies of the current block position. Although the count is limited to 256, multiple count predicates can be used, allowing them to be stacked multiplicatively to achieve much higher values.
** {{nbt|int}}{{nbt|compound|count}}: Value between 0 and 256 (inclusive).
*** {{nbt inherit/int_provider}}
</div>

<div class="treeview" id="count_on_every_layer" style="margin-top: 1em;">
* '''count_on_every_layer'''&mdash;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.
** {{nbt|int}}{{nbt|compound|count}}：Count on each layer. Value between 0 and 256 (inclusive).
*** {{nbt inherit/int_provider}}
</div>

<div class="treeview" id="environment_scan" style="margin-top: 1em;">
* '''environment_scan'''&mdash;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.
** {{nbt|string|direction_of_search}}: One of <code>up</code> or <code>down</code>.
** {{nbt|int|max_steps}}: Value between 1 and 32 (inclusive).
** {{nbt|compound|target_condition}}: The block predicate that is searched for.
*** {{nbt inherit/block_predicate}}
** {{nbt|compound|allowed_search_condition}}:  (optional) If specified, each step must match this block position in order to continue the scan. If a block that doesn't match it is met, but no target block found, returns empty.
*** {{nbt inherit/block_predicate}}
</div>

<div class="treeview" id="surface_water_depth_filter" style="margin-top: 1em;">
* '''fixed_placement'''&mdash;Returns all specified positions, if they are in the current chunk.
** {{nbt|list|positions}}: A list of all placement positions
*** {{nbt|list}}: A position
**** {{nbt|int}}: x coordinate
**** {{nbt|int}}: y coordinate
**** {{nbt|int}}: z coordinate
</div>

<div class="treeview" id="height_range" style="margin-top: 1em;">
* '''height_range'''&mdash;Sets the Y coordinate to a value provided by a height provider. Returns the new position.
** {{nbt|compound|height}}: The new Y coordinate.
*** {{nbt inherit/height_provider}}
</div>

<div class="treeview" id="heightmap" style="margin-top: 1em;">
* '''heightmap'''&mdash;Sets the Y coordinate to one block above the [[heightmap]]. Returns the new position.
** {{nbt|string|heightmap}}: The heightmap to use. One of <code>MOTION_BLOCKING</code>, <code>MOTION_BLOCKING_NO_LEAVES</code>, <code>OCEAN_FLOOR</code>, <code>OCEAN_FLOOR_WG</code>, <code>WORLD_SURFACE</code> or <code>WORLD_SURFACE_WG</code>.
</div>

<div class="treeview" id="in_square" style="margin-top: 1em;">
* '''in_square'''&mdash;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.
</div>

<div class="treeview" id="noise_based_count" style="margin-top: 1em;">
* '''noise_based_count'''&mdash;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 <code>ceil((noise(x / noise_factor, z / noise_factor) + noise_offset) * noise_to_count_ratio)</code>.
** {{nbt|double|noise_factor}}: Scales the noise input horizontally. Higher values make for wider and more spaced out peaks.
** {{nbt|double|noise_offset}}：(optional, defaults to 0) Vertical offset of the noise.
** {{nbt|int|noise_to_count_ratio}}: Ratio of noise value to count.
</div>

<div class="treeview" id="noise_threshold_count" style="margin-top: 1em;">
* '''noise_threshold_count'''&mdash;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 <code>noise(x / 200, z / 200) < noise_level</code>. If that is true, uses <code>below_noise</code>, otherwise <code>above_noise</code>.
** {{nbt|double|noise_level}}: The threshold within the noise of when to use <code>below_noise</code> or <code>above_noise</code>.
** {{nbt|int|below_noise}}: The count when the noise is below the threshold. Value lower than 0 is treated as 0.
** {{nbt|int|above_noise}}: The count when the noise is above the threshold. Value lower than 0 is treated as 0.
</div>

<div class="treeview" id="random_offset" style="margin-top: 1em;">
* '''random_offset'''&mdash;Applies an offset to the current position. Contrary to its name, the applied offset is only random if the specified integer provider isn't a constant. In other words, a y_spread of -12 will always offset the placed feature downwards by 12 blocks. Also note that the even though the x and z axes share the same integer provider, they are sampled individually, so, for example, if a 'uniform' type integer provider is used for the xz_spread with a min of 4 and a max of 16, the x offset could be 12 while the z offset could be 5. Specifying specific, unique X and Z values isn't possible.
** {{nbt|int}}{{nbt|compound|xz_spread}}: Value between -16 and 16 (inclusive).
*** {{nbt inherit/int_provider}}
** {{nbt|int}}{{nbt|compound|y_spread}}: Value between -16 and 16 (inclusive).
*** {{nbt inherit/int_provider}}
</div>

<div class="treeview" id="rarity_filter" style="margin-top: 1em;">
* '''rarity_filter'''&mdash;Either returns the current position or empty. The chance is calculated as <code>1 / chance</code>.
** {{nbt|int|chance}}: Must be a positive integer.
</div>

<div class="treeview" id="surface_relative_threshold_filter" style="margin-top: 1em;">
* '''surface_relative_threshold_filter'''&mdash;Returns the current position if the surface is inside a range. Otherwise returns empty.
** {{nbt|string|heightmap}}：The [[heightmap]] to use. One of <code>MOTION_BLOCKING</code>, <code>MOTION_BLOCKING_NO_LEAVES</code>, <code>OCEAN_FLOOR</code>, <code>OCEAN_FLOOR_WG</code>, <code>WORLD_SURFACE</code> or <code>WORLD_SURFACE_WG</code>.
** {{nbt|int|min_inclusive}}: The minimum relative height from the surface to current position.
** {{nbt|int|max_inclusive}}: The maximum relative height from the surface to current position.
</div>

<div class="treeview" id="surface_water_depth_filter" style="margin-top: 1em;">
* '''surface_water_depth_filter'''&mdash;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.
** {{nbt|int|max_water_depth}}: The maximum allowed depth.
</div>

== History ==
{{WIP|section=1}}
{{HistoryTable
|{{HistoryLine|java}}
|{{HistoryLine||?|Introduced placed features}}
|{{HistoryLine||1.21|dev=pre2|Added {{cd|fixed_placement}} placement modifier}}
}}

== External links ==
* [https://misode.github.io/worldgen/placed-feature/ Placed feature Generator on misode.github.io]

== Navigation ==
{{Navbox Java Edition technical|datapack}}

[[fr:Élément du terrain placé]]
[[pt:Recurso colocado]]
[[zh:地物数据格式]]