Custom structure

Structures (also known as structure features) are a special type of feature that generates a structure.

Structure Feature Type

A structure feature type determines how and what to generate.

List

All structure feature types and their roles are listed below:

• buried_treasure
  • To generate a buried treasure with hardcode.
• desert_pyramid
  • To generate a desert temple with hardcode.
• end_city
  • To generate an end city with structure templates.
• fortress
  • To generate a nether fortress with hardcode.
• igloo
  • To generate an igloo with structure templates.
• jigsaw
  • To generate a structure feature using custom structure templates. Often used to generate large structures by connecting multiple structural templates via jigsaw blocks.
• jungle_temple
  • To generate a jungle temple with hardcode.
• mineshaft
  • To generate a mineshaft with hardcode.
• nether_fossil
  • To generate a nether fossil with structure templates.
• ocean_monument
  • To generate an ocean monument with hardcode.
• ocean_ruin
  • To generate an underwater ruin with structure templates.
• ruined_portal
  • To generate a ruined portal with structure templates.
• shipwreck
  • To generate a shipwreck with structure templates.
• stronghold
  • To generate a stronghold with hardcode.
• swamp_hut
  • To generate a swamp hut with hardcode.
• woodland_mansion
  • To generate a woodland mansion with structure templates.

Structure Template

Structure template refers to a structure file, which stores the template used to generate structure features. For structures of jigsaw type, the resource locations of the structure templates is customized. While for other structure features, such as end city, igloo, etc., the resource locations of structure templates are hardcoded.

Structure Pool

A structure pool (aka. jigsaw pool, template pool) groups multiple structure templates or placed features together to randomly select one of them to generate. Used in structures of type jigsaw. Stored as JSON files within a data pack in the data/<namespace>/worldgen/template_pool.

JSON Format

• The root tag
  •  fallback: The fallback pool. Should be an ID of a structure pool. Template in the fallback pool generates in the following two cases:
    1. When the generation of jigsaw reaches the specified level/depth number, the fallback pool generates at the end of the last level.
    2. All the elements in this structure pool can not be successfully generated.

    In the above two cases, the game will try to generate a template from the fallback pool.
    When trying to generate a template from the fallback pool, if all the elements in the fallback pool cannot be generated successfully, nothing will be generated.
  •  elements: A list of elements to randomly select from.
    For the start pool of the jigsaw structure feature, if the name of the start jigsaw block is specified, but there's no jigsaw block with the corresponding name in the selected element, the whole structure feature fails to generate. For the non-start pool, a selected element successfully generates when the following conditions are met:

    1. There is a jigsaw block with the corresponding name and corresponding direction (the horizontal jigsaw blocks correspond to each other, and a up facing jigsaw block corresponds to a down facing block, while a down facing block corresponds to a up facing block) in the element.
    2. The 3D Chebyshev distance between the element and the start of the structure doesn't exceed the maximum distance specified in the configured structure feature, or doesn't exceed 128 when generated by commands or jigsaw block GUI.
    3. The element will not overlap with other generated jigsaws, unless the block pointed by the jigsaw block is inside the current jigsaw.
    4. If the block pointed by the jigsaw block is inside the current jigsaw, then this element and all the jigsaws generated later by this element must be completely inside the jigsaw where this jigsaw block is located.

    If the element fails to generate, it will try again to generate another element in the list. If all of the elements in the list cannot be generated successfully, the fallback pool will be used.
    • : An element.
      •  weight: How likely this element is to be chosen when using this pool. Value between 1 and 150 (inclusive).
      •  element: The properties of this element.
        •  projection: Can be rigid to place a fixed structure (like a house), or terrain_matching to match the terrain height (like a village road).
        •  element_type: Can be minecraft:empty_pool_element to generate nothing, minecraft:feature_pool_element to generate a placed feature, minecraft:list_pool_element to generate multiple elements one after another (lower elements replace their front ones), and minecraft:legacy_single_pool_element or minecraft:single_pool_element to generate a structure template. The difference between legacy_single_pool_element and single_pool_element, is that the legacy_single_pool_element will not replace existing blocks with air, and the single_pool_element will replace blocks with air and relies on the structure_void block to avoid not replacing blocks.

          If  element_type is feature_pool_element, additional fields are as follows:

        •  feature: The namespaced id of the placed feature.

          If  element_type is list_pool_element, additional fields are as follows:

        •  elements: A list of elements to choose from.
          • : An element, with the same format above.

          If  element_type is legacy_single_pool_element or single_pool_element, additional fields are as follows:

        •  location: The namespaced id of the structure template to generate.
        •  processors: (Required, but can be empty) The namespaced ID of a processor list, or a object of a processor list, or a list of processors.

Configured Structure Feature

A structure feature type determines how to generate a structure feature, but the specific details need to be configured additionally. After configured, it is called a configured structure feature, or simply called a structure feature or a structure.

Configured structure features are stored as JSON files within a data pack in the path data/<namespace>/worldgen/structure.

JSON Format

• The root tag
  •  type: The ID of structure feature type.
  •  biomes: Biomes that this structure is allowed to generate in. Can be a biome ID or a biome tag, or a list of biome IDs.
  •  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.
  •  terrain_adaptation: (Optional, defaults to none) The type of terrain adaptation used for the structure . none for no adaptation, beard_thin is used by pillager outposts and villages, beard_box is used by ancient cities, and bury is used by strongholds.
  •  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.
    •  <mob category>: The key must be one of monster, creature, ambient, water_creature, underground_water_creature, water_ambient, misc, or axolotls.
      •  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 boxs of all structure pieces.
      •  spawns：(Required, but can be empty. If empty, mobs in this category will not be spawned) A list of spawner data objects, one for each mob which should spawn in this biome.
        • : The spawner data for a single mob.
          •  type: The namespaced entity id of the mob.
          •  weight: How often this mob should spawn, higher values produce more spawns.
          •  minCount: The minimum count of mobs to spawn in a pack. Must be greater than 0.
          •  maxCount: The maximum count of mobs to spawn in a pack. Must be greater than 0. And must be not less than  minCount.

    If type is minecraft:jigsaw, additional fields are as follows:

  •  start_pool: The structure pool the structure starts from. Can be an ID of structure pool, or a structure pool object.
  •  size: The depth of jigsaw structures to generate. Value between 0 and 7 (inclusive).
  •  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
  •  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.
  •  start_jigsaw_name: (optional) The name of the jigsaw block the structure start attaches to.
  •  max_distance_from_center: The maximum 3D Chebyshev distance from the jigsaw pieces to the structure start. Value between 1 and 128 (inclusive) when  terrain_adaptation is "none", otherwise from 1 to 116 (inclusive).
  •  use_expansion_hack: Only used in villages.

    If type is minecraft:mineshaft, additional fields are as follows:

  •  type: Either normal or mesa. normal for mineshaft made of oak, while mesa for mineshaft made of dark oak.

    If type is minecraft:nether_fossil, additional fields are as follows:

  •  start_height: The y-value that the structure will start.
    • Height provider

    If type is minecraft:ocean_ruin, additional fields are as follows:

  •  biome_temp: Either warm or cold. Determines which variant this structure uses.
  •  large_probability: The probability of this structure using the large variant buildings. Value between 0.0 and 1.0 (inclusive).
  •  cluster_probability: The probability of a cluster of ocean ruins generating, instead of just one. Value between 0.0 and 1.0 (inclusive).

    If type is minecraft:ruined_portal, additional fields are as follows:

  •  setups: (Cannot be empty) A list of ruined portal setups to randomly choose one from it.
    •  weight: The weight this ruined portal setup will be chosen.
    •  placement: Either on_land_surface, partly_buried, on_ocean_floor, in_mountain, underground, in_nether. Determines how the ruined portal will be placed.
    •  air_pocket_probability: The probability that the ruined portal will generate an air pocket around it. Value between 0.0 and 1.0 (inclusive).
    •  mossiness: Determines how mossy the ruined portal is, as an argument for minecraft:block_age processor. Value between 0.0 and 1.0 (inclusive).
    •  overgrown: Determines whether or not jungle leaves generate.
    •  vines: Determines whether or not vines generate on the ruined portal.
    •  can_be_cold: Determines whether or not lava and magma can be replaced with netherrack.
    •  replace_with_blackstone: Determines whether or not stone bricks in the ruined portal will be replaced with their blackstone equivalents.

    If type is minecraft:shipwreck, additional fields are as follows:

  •  is_beached: (optional, defaults to false) Whether or not the shipwreck is beached.

Structure Set

A structure set is used to place structures in given locations, stored as JSON files within a data pack in the path data/<namespace>/worldgen/structure_set.

JSON Format

• : Root object.
  •  structures: (Required, but can be empty) The structures that may be placed. One configured structure feature shouldn't be included by two structure sets.
    • : A structure to be placed.
      •  structure: The configured structure feature to be placed. Can be a namespaced ID or an object of configured structure feature.
      •  weight: Determines the chance of it being chosen over others. Must be a positive integer.
  •  placement: How the structures should be placed.
    •  salt: A number that assists in randomization; see salt (cryptography). Must be a non-negative integer.
    •  frequency: (Optional, default to 1.0) Probability to try to generate if other conditions below are met. Values between 0.0 to 1.0 (inclusive). Setting it to a number does not mean one structure is generated this often, only that the game attempts to generate one; biomes or terrain could lead to the structure not being generated.
    •  frequency_reduction_method: (Optional, defaults to default) Provides a random number generator algorithm for frequency. One of default (the random number depends on the the seed, position and  salt), legacy_type_1 (the random number depends only on the seed and position, and randomness only occurs when the locations differ greatly), legacy_type_2 (same as default, but with fixed salt: 10387320) and legacy_type_3 (the random number depends only on seed and position).
    •  exclusion_zone: Specifies that it cannot be placed near certain structures.
      •  chunk_count: Value betwenn 1 and 16 (inclusive).
      •  other_set: A structure set ID.
    •  locate_offset: (optional, defaults to [0,0,0]) The chunk coordinate offset given when using /locate structure.
      • : X. Value between -16 and 16 (inclusive).
      • : Y. Value between -16 and 16 (inclusive).
      • : Z. Value between -16 and 16 (inclusive).
    •  type: One of minecraft:concentric_rings or minecraft:random_spread.

      If type is minecraft:concentric_rings (distributed like strongholds), additional fields are as follows:

    •  distance: The thickness of a ring plus that of a gap between two rings. Value between 0 and 1023 (inclusive). Unit is 6 chunks
    •  count: The total number of generation attempts in this dimension. Value between 1 and 4095 (inclusive).
    •  preferred_biomes: Biomes in which the structure is likely to be generated. Can be a biome ID or a biome tag, or a list of biome IDs.
    •  spread: How many attempts are on the closest ring to spawn. Value between 0 and 1023 (inclusive). The number of attempts on the Nth ring is: spread * (N^2 + 3 * N + 2) / 6, until the number of attempts reaches the total  count.

      If type is minecraft:random_spread (distributed like bastion remnants or swamp huts), additional fields are as follows:

    •  spread_type: (optional, defaults to linear) One of linear or triangular.
    •  spacing: Average distance between two neighboring generation attempts. Value between 0 and 4096 (inclusive).
    •  separation: Minimum distance (in chunks) between two neighboring attempts. Value between 0 and 4096 (inclusive). And be not bigger than  spacing. The maximum distance of two neighboring generation attempts is 2*spacing - separation.

Processor List

A processor list is a list of processors used to transform blocks in a structure template, stored as JSON files within a data pack in the path data/<namespace>/worldgen/processor_list.

JSON Format

A processor list can be a list, or an object that contains a list.

A list:

• : A list of processors.
  • : A processor object.
    • A processor

Or an object:

• : An object of processor list.
  •  processors: A list of processors.
    • : A processor object.
      • A processor

History

Java Edition
1.19		22w11a			The structure system was rewritten.
					Renamed "configured structure feature" to "structure".
					Moved worldgen/configured_structure_feature to worldgen/structure folder.
		22w12a			Added max_distance_from_center field to jigsaw structure.
		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  adapt_noise feild in configured structure feature with  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.
					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  start_jigsaw_name field in minecraft:jigsaw config type of configured structure feature.
1.19.3		22w44a			Removed the  name field in structure pool. Before, this field was a required field, but had no effect.
1.19.4		Pre-release 1			Now  minCount and  maxCount in  spawners in configured structure feature must be a positive integer. And  maxCount must be not less than  minCount.
1.20		23w12a			Added capped processer.
					The  output_nbt field in the rule processer used to set fixed NBT data to the block entity has now been changed to  block_entity_modifier. Before,  output_nbt was an NBT compound in JSON object form, see NBT format#JSON and NBT.