Structure definition

From Minecraft Wiki

👁 Image
Not to be confused with Structure file.

This feature is exclusive to Java Edition.

👁 Image
There is a related tutorial page for this topic!

A structure is a large decoration, covering an area up to 257×8129×257 blocks centered on the structure start. Structures often consist of multiple pieces that are fit together to form the overall structure. They are configured using JSON files within a data pack in the path data/<namespace>/worldgen/structure. To generate in a world, a structure needs to be part of at least one structure set.

JSON format

[edit | edit source]

[NBT Compound / JSON Object] The root tag.
- [String] type: The ID of structure feature type.
- [String][NBT List / JSON Array] biomes: Any number of biome(s) (an [String] ID, or a [String] tag with #, or an [NBT List / JSON Array] array containing [String] IDs) — Biomes that this structure is allowed to generate in.
- [String] step: The step where the structure generates. See also the features field in custom biome. Structure features are generated prior to features in the same step. One of raw_generation, lakes, local_modifications, underground_structures, surface_structures, strongholds, underground_ores, underground_decoration, fluid_springs, vegetal_decoration, and top_layer_modification.
- [String] terrain_adaptation: (Optional, defaults to none) The type of terrain adaptation used for the structure. none for no adaptation, beard_thin for generating terrain under the structure, while removing terrain inside the structure (used by pillager outposts and villages), beard_box for advanced alternative of beard_thin (used by ancient cities), bury for generating terrain surrounding the structure to make it buried (used by strongholds), and encapsulate for advanced alternative of bury (used by Trial Chambers).
- [NBT Compound / JSON Object] spawn_overrides: (Required, but can be empty. If this object doesn't contain a certain category, the category's spawn setting won't be overridden, and mobs are spawned based on biome.) Overrides the mobs that can spawn in this structure. Used for things like blaze and wither skeleton spawning in nether fortresses, and can also be used to block mobs from spawning like in ancient cities.
  - [NBT Compound / JSON Object] <mob category>: The key must be one of monster, creature, ambient, water_creature, underground_water_creature, water_ambient, misc, or axolotls.
    - [String] bounding_box：Can be piece or full. If full, overrides spawn setting inside the full bounding box of the structure. If piece, only the bounding boxes of all structure pieces.
    - [NBT List / JSON Array] spawns：(Required, but can be empty. If empty, mobs in this category do not spawn.) A list of spawner data objects, one for each mob which should spawn in this structure.
      - [NBT Compound / JSON Object]: The spawner data for a single mob.
        [String] type: The namespaced entity id of the mob.
        
        [Int] weight: How often this mob should spawn, higher values produce more spawns.
        
        [Int] minCount: The minimum count of mobs to spawn in a pack. Must be greater than 0.
        
        [Int] maxCount: The maximum count of mobs to spawn in a pack. Must be greater than 0. And must be not less than [Int] minCount.
- Additional fields depending on value of [String] type, see Structure types.

Structure types

[edit | edit source]

Structures use different types. The structure types and their corresponding configuration are listed below:

Using Jigsaw Blocks

[edit | edit source]

Main article: Jigsaw structure

Jigsaw structures are using template pools and jigsaw blocks and allow full customization of structure generation using a datapack.

👁 Image
jigsaw

[NBT Compound / JSON Object] Structure configuration
- [String] type: jigsaw
- Fields common to all structures see Template:Nbt inherit/structure/template
- [String][NBT Compound / JSON Object] start_pool: One template pool (an [String] ID, or a new [NBT Compound / JSON Object] template pool definition) — The template pool the structure starts from.
- [Int] size: Value between 0 and 20 (inclusive) — The depth of jigsaw structures to generate.
- [Int][NBT Compound / JSON Object] start_height: If project_start_to_heightmap is unset, the structure will start at the value provided. Otherwise, the value acts as an offset from the heightmap.
  - Height provider see Template:Nbt inherit/height provider/template
- [String] project_start_to_heightmap: (optional) The heightmap the start height should project to. Can be WORLD_SURFACE_WG, WORLD_SURFACE, OCEAN_FLOOR_WG, OCEAN_FLOOR, MOTION_BLOCKING, or MOTION_BLOCKING_NO_LEAVES.
- [String] start_jigsaw_name: (optional) The name of the jigsaw block the structure start attaches to.
- [Int][NBT Compound / JSON Object] max_distance_from_center: Defines the maximum distance of any piece from the structure start. When defined as a single number, defines both horizontal and vertical distance and is limited to the limits of [Int] horizontal (see below).
  - [Int] horizontal: Value between 1 and 128 (inclusive) when [String] terrain_adaptation is "none", otherwise from 1 to 116 (inclusive). — The maximum horizontal Chebyshev distance from the jigsaw pieces to the structure start.
  - [Int] vertical: Optional value between 1 and 4064 (defaults to 4064) — The maximum vertical distance of any piece to the structure start.
- [Boolean] use_expansion_hack: Allows the structure's vertical limit to be expanded if necessary. Used in villages to prevent cut-off when terrain height varies.
- [NBT List / JSON Array] pool_aliases: (optional) used to rewire jigsaw pool connections by redirecting pool references on individual structure instances.
  - [NBT Compound / JSON Object]: pool alias
- [Int][NBT Compound / JSON Object] dimension_padding: (optional, defaults to 0). Padding on the top and bottom world limit. [Int]: shorthand to set the same value for [Int] bottom and [Int] top.
  - [Int] bottom: (optional, defaults to 0), non-negative. Amount of blocks at the bottom build limit that are excluded from the outer bounding box of the structure.
  - [Int] top: (optional, defaults to 0), non-negative. Amount of blocks at the top build limit that are excluded from the outer bounding box of the structure.
- [String] liquid_settings: (optional, defaults to apply_waterlogging). How blocks with waterlogged block state should generate when they overlap with existing water. apply_waterlogging: waterlog block placed inside water, ignore_waterlogging: keep the waterlogged block state as is.

Using structure templates

[edit | edit source]

These structure types use specific structure templates, but they use hard-coded relative positioning between those structure templates instead of using jigsaw blocks.

👁 Image
end_city

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:end_city
- Fields common to all structures see Template:Nbt inherit/structure/template

👁 Image
igloo

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:igloo
- Fields common to all structures see Template:Nbt inherit/structure/template

👁 Image
nether_fossil

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:nether_fossil
- Fields common to all structures see Template:Nbt inherit/structure/template
- [Int][NBT Compound / JSON Object] start_height: The y-value where the structure starts.
  - Height provider see Template:Nbt inherit/height provider/template

👁 Image
ocean_ruin

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:ocean_ruin
- Fields common to all structures see Template:Nbt inherit/structure/template
- [String] biome_temp: Either warm or cold. Determines which variant this structure uses.
- [Float] large_probability: The probability of this structure using the large variant buildings. Value between 0.0 and 1.0 (inclusive).
- [Float] cluster_probability: The probability of a cluster of ocean ruins generating, instead of just one. Value between 0.0 and 1.0 (inclusive).

The structure filenames and placement of suspicious blocks is hardcoded.

👁 Image
ruined_portal

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:ruined_portal
- Fields common to all structures see Template:Nbt inherit/structure/template
- [NBT List / JSON Array] setups: (Cannot be empty) A list of ruined portal setups to randomly choose one from it.
  - [Int] weight: The weight this ruined portal setup is chosen.
  - [String] placement: Either on_land_surface, partly_buried, on_ocean_floor, in_mountain, underground, in_nether. Determines how the ruined portal is placed.
  - [Float] air_pocket_probability: The probability that the ruined portal generates an air pocket around it. Value between 0.0 and 1.0 (inclusive).
  - [Float] mossiness: Determines how mossy the ruined portal is, as an argument for minecraft:block_age processor. Value between 0.0 and 1.0 (inclusive).
  - [Boolean] overgrown: Determines whether or not jungle leaves generate.
  - [Boolean] vines: Determines whether or not vines generate on the ruined portal.
  - [Boolean] can_be_cold: Determines whether or not lava and magma can be replaced with netherrack.
  - [Boolean] replace_with_blackstone: Determines whether or not stone bricks in the ruined portal are replaced with their blackstone equivalents.

👁 Image
shipwreck

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:shipwreck
- Fields common to all structures see Template:Nbt inherit/structure/template
- [Boolean] is_beached: (optional, defaults to false) Whether or not the shipwreck is beached.

👁 Image
woodland_mansion

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:woodland_mansion
- Fields common to all structures see Template:Nbt inherit/structure/template

Hardcoded structures

[edit | edit source]

These structure types use code to place the blocks of the structure directly.

👁 Image
buried_treasure

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:buried_treasure
- Fields common to all structures see Template:Nbt inherit/structure/template

👁 Image
desert_pyramid

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:desert_pyramid
- Fields common to all structures see Template:Nbt inherit/structure/template

👁 Image
fortress

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:fortress
- Fields common to all structures see Template:Nbt inherit/structure/template

👁 Image
jungle_temple

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:jungle_temple
- Fields common to all structures see Template:Nbt inherit/structure/template

👁 Image
mineshaft

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:mineshaft
- Fields common to all structures see Template:Nbt inherit/structure/template
- [String] mineshaft_type: Either normal or mesa. normal for mineshaft made of oak, while mesa for mineshaft made of dark oak.

👁 Image
ocean_monument

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:ocean_monument
- Fields common to all structures see Template:Nbt inherit/structure/template

👁 Image
stronghold

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:stronghold
- Fields common to all structures see Template:Nbt inherit/structure/template

👁 Image
swamp_hut

[NBT Compound / JSON Object] Structure configuration
- [String] type: minecraft:swamp_hut
- Fields common to all structures see Template:Nbt inherit/structure/template

History

[edit | edit source]

Java Edition
1.19	22w11a	The structure system was rewritten.
		Renamed "configured structure feature" registry to "structure".
		Moved `worldgen/configured_structure_feature` to `worldgen/structure` folder.
	22w12a	Added [Int] max_distance_from_center field to 👁 BlockSprite jigsaw.png: Sprite image for jigsaw in Minecraft jigsaw structures.
	22w13a	Added `rottable_blocks` field into `minecraft:block_rot` processor.
		Now the `integrity` field in `minecraft:block_rot` processor becomes a required field, and now it must be between 0.0 and 1.0 (inclusive).
		Replaced the [Boolean] adapt_noise field in configured structure feature with [String] terrain_adaptation field. Before, it is an optional boolean value that defaults to false.
		All fields except `type` of jigsaw structure are now wrapped in a `value` field.
	22w14a	Reverted the change on jigsaw structure from last snapshot.
	22w14a	Now the `rottable_blocks` field in `minecraft:block_rot` processor also accepts a block ID or a list of block IDs, and the block tag now needs to be prefixed with a `#`.
	22w17a	Added [String] start_jigsaw_name field to 👁 BlockSprite jigsaw.png: Sprite image for jigsaw in Minecraft jigsaw structures.
1.19.3	22w44a	Removed the [String] name field in structure pool. Before, this field was a required field, but had no effect.
1.19.4	Pre-release 1	Now [Int] minCount and [Int] maxCount in [NBT Compound / JSON Object] spawners in configured structure feature must be a positive integer. And [Int] maxCount must be not less than [Int] minCount.
1.20	23w12a	Added `capped` processor.
1.20	23w12a	The [NBT Compound / JSON Object] output_nbt field in the `rule` processor used to set fixed NBT data to the block entity has now been changed to [NBT Compound / JSON Object] block_entity_modifier. Before, [NBT Compound / JSON Object] output_nbt was an NBT compound in JSON object form, see NBT format#JSON and NBT.
1.20.3	23w42a	Added optional [NBT List / JSON Array] pool_aliases field to 👁 BlockSprite jigsaw.png: Sprite image for jigsaw in Minecraft jigsaw structures.
		Aliases represent the possibility to rewire jigsaw pool connections by redirecting pool references on individual structure instances.
		Alias variants are represented in `type`.
1.21	24w19a	Added optional [Int] dimension_padding field to 👁 BlockSprite jigsaw.png: Sprite image for jigsaw in Minecraft jigsaw structures.
	24w20a	[Int][NBT Compound / JSON Object] dimension_padding can now also be specified separately for [Int] bottom and [Int] top padding.
	pre1	Added optional [String] liquid_settings field to 👁 BlockSprite jigsaw.png: Sprite image for jigsaw in Minecraft jigsaw structures.
1.21.9	25w31a	[Int][NBT Compound / JSON Object] max_distance_from_center can now also be specified separately for [Int] horizontal and [Int] vertical distance.
26.2	snap6	Changed the `minecraft:block_rot` structure processor.

External links

[edit | edit source]

Structure Generator on misode.github.io

Navigation

[edit | edit source]

Java Edition technical

General

Concepts

General format

👁 Image
Data values
👁 Image
Data component format
- 👁 Image
  Predicate
👁 Image
Entity format
👁 Image
Block entity format
👁 Image
Map item format
[NBT Compound / JSON Object] NBT format
👁 Image
Particle format
👁 Image
Text component format
§ Formatting codes
👁 Image
Key codes
👁 Image
Random sequence
👁 Image
Structure file format
- 👁 Image
  Schematic file format

World

Legacy

👁 Image
Spawn chunk

Level format

Legacy	👁 Image Classic level format Classic server protocol 👁 Image Indev level format 👁 Image Alpha level format 👁 Image Zone file format 👁 Image Region file format 👁 Image server_level.dat format 👁 Image villages.dat format 👁 Image Generated structures format

.minecraft

Tools

Legacy	👁 Image Obfuscation map

Sound

Commands

All commands

Launching

Legacy	Legacy Minecraft authentication Yggdrasil

Protocol

Server

Protocols	Query RCON Server Management Protocol

Legacy

Data pack

Components

Tag

GameTest

World generation

Noise settings	👁 Image Noise router 👁 Image Density function Noises 👁 Image Surface rule
	👁 Image Structure set 👁 Image Template pool 👁 Image Processor list 👁 Image Structure templates
Removed	👁 Image Configured surface builder

Data packs

Tutorials

Content	👁 Image Custom enchantments 👁 Image Custom paintings 👁 Image Custom trims
World generation	👁 Image New dimension 👁 Image Custom structures

Resource pack

Components

Debug

Tools

Slicer

Legacy	Texture Ender Unstitcher

Tutorials

Retrieved from "https://minecraft.wiki/w/Structure_definition?oldid=3614831"

Categories:

URL: https://minecraft.wiki/w/Custom_structure