Tutorial:Custom structures

A custom structure added to the world by a data pack

This tutorial explains how to create a data pack that adds a custom structure to the world. It assumes you already know how to create a data pack.

pack.mcmeta

{
  "pack": {
    "pack_format": 61,
    "description": "A tall tower"
  }
}

Structure Set

A structure set is where the placement starts. It defines where in the world the structure should be placed, and how rare it is.

data/example/worldgen/structure_set/tall_towers.json

{
  "structures": [
    {
      "structure": "example:tall_tower",
      "weight": 1
    }
  ],
  "placement": {
    "type": "minecraft:random_spread",
    "spacing": 5,
    "separation": 2,
    "salt": 1646207470
  }
}

Structure sets are made up of two parts:

• [NBT List / JSON Array] structures takes a weighted list of different structures (see below), allowing structure variants (for example the vanilla Nether has a structure set with both the bastion and fortress).
• [NBT Compound / JSON Object] placement specifies in which chunks to spawn the structure. The simplest option is random_spread where you can give the average distance in chunks ([Int] spacing) and the minimum distance in chunks ([Int] separation). The [Int] salt is then used together with the world seed to randomly place structures in a chunk grid.

Full JSON format

• [NBT Compound / JSON Object]: Root object.
  • [NBT List / JSON Array] structures: (Required, but can be empty) The structures that may be placed. One configured structure feature shouldn't be included by two structure sets.
    • [NBT Compound / JSON Object]: A structure to be placed.
      • [String][NBT Compound / JSON Object] structure: One structure (an [String] ID) — The structure to be placed.
      • [Int] weight: Determines the chance of it being chosen over others. Must be a positive integer.
  • [NBT Compound / JSON Object] placement: How the structures should be placed.
    • [Int] salt: A number that assists in randomization; see salt (cryptography). Must be a non-negative integer.
    • [Float] 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.
    • [String] frequency_reduction_method: (Optional, defaults to default) Provides a random number generator algorithm for frequency. One of default (the random number depends on the seed, position and [Int] 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).
    • [NBT Compound / JSON Object] exclusion_zone: Specifies that it cannot be placed near certain structures.
      • [Int] chunk_count: Value between 1 and 16 (inclusive).
      • [String] other_set: A structure set ID.
    • [NBT List / JSON Array] locate_offset: (optional, defaults to [0,0,0]) The chunk coordinate offset given when using /locate structure.
      • [Int]: X. Value between -16 and 16 (inclusive).
      • [Int]: Y. Value between -16 and 16 (inclusive).
      • [Int]: Z. Value between -16 and 16 (inclusive).
    • [String] type: One of minecraft:concentric_rings or minecraft:random_spread.
    • Additional fields depending on value of [String] type, see Placement types.

Structure

The structure is the ID you will be able to reference in the /locate command. It contains the configuration on what to place in the world, in which biomes, as well as structure properties like mob spawns.

data/example/worldgen/structure/tall_tower.json

{
  "type": "minecraft:jigsaw",
  "biomes": "#minecraft:has_structure/mineshaft",
  "step": "surface_structures",
  "spawn_overrides": {},
  "terrain_adaptation": "beard_thin",
  "start_pool": "example:tall_tower",
  "size": 1,
  "start_height": {
    "absolute": 0
  },
  "project_start_to_heightmap": "WORLD_SURFACE_WG",
  "max_distance_from_center": 80,
  "use_expansion_hack": false
}

When creating custom structures, you should always set [String] type to jigsaw. The [String] biomes field is a biome tag controlling which biomes are allowed to spawn this structure in. The [String] start_pool references a template pool (see below) which will define the actual structure layout. If you want to use jigsaws, make sure to increase the [Int] size value. It is the jigsaw depth limit and it has a maximum of 20.

Full JSON format of jigsaw structures:

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.
  • [NBT Compound / JSON Object][Int] 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.

Template pool

The template pool defines how to build up your structure. The example in this tutorial does not use jigsaw, so this is quite straight forward: we want to place a single structure NBT file.

data/example/worldgen/template_pool/tall_tower.json

{
  "fallback": "minecraft:empty",
  "elements": [
    {
      "weight": 1,
      "element": {
        "element_type": "minecraft:single_pool_element",
        "location": "example:stone_tall_tower",
        "projection": "rigid",
        "processors": "minecraft:empty"
      }
    }
  ]
}

A single structure is selected from the [NBT List / JSON Array] elements list. You can add structure variants by adding multiple elements here. The [String] location field references a structure NBT file

Full JSON format

• [NBT Compound / JSON Object] The root tag.
  • [String] fallback: One template pool (an [String] ID) — Used for terminating pieces (such as the end of a village road) or as fallback if structures in this pool can't generate. (Note that empty pool elements don't trigger this, they just generate nothing.)
  • [NBT List / JSON Array] elements: A list of elements to randomly select from.
    • [NBT Compound / JSON Object]: An element.
      • [Int] weight: How likely this element is to be chosen when using this pool. Value between 1 and 150 (inclusive).
      • [NBT Compound / JSON Object] element: A pool element.
        • [String] element_type: The type of the pool element. See Template pool § Pool elements.
        • [String] projection: Can be rigid to place a fixed structure (like a house), or terrain_matching to match the terrain height (like a village road).
        • Additional fields depending on [String] element_type. See Template pool § Pool elements.
• [NBT Compound / JSON Object] The root tag.
  • [String] format_version: ​^{[more information needed]}
  • [NBT Compound / JSON Object] minecraft:template_pool
    • [NBT Compound / JSON Object] description
      • [String] identifier: The identifier used for this template pool.
    • [String] fallback: One template pool (an [String] ID) — Used for terminating pieces (such as the end of a village road) or as fallback if structures in this pool can't generate. (Note that empty pool elements don't trigger this, they just generate nothing.)
    • [NBT List / JSON Array] elements: A list of elements to randomly select from.
      • [NBT Compound / JSON Object]: An element.
        • [Int] weight: How likely this element is to be chosen when using this pool. Value between 1 and 150 (inclusive).
        • [NBT Compound / JSON Object] element: A pool element.
          • [String] element_type: The type of the pool element. See Template pool § Pool elements.
          • [String] projection: Can be rigid to place a fixed structure (like a house), or terrain_matching to match the terrain height (like a village road). ^[verify]
        • Additional fields depending on [String] element_type. See Template pool § Pool elements.

Structure NBT

The final piece to get a custom structure in your world is to have a structure NBT file.

data/example/structure/stone_tall_tower.nbt

You can create your own structure in-game, or download this one