Minecraft Custom Structures Data Pack Guide for 26.3

Written for Minecraft 26.3.

Minecraft custom structures data pack work comes in two levels. The easy one: save a build with a structure block and place it by command. The advanced one: register it so it generates in new chunks.

Before you start

• Minecraft Java Edition 26.3 and operator permissions.

• A data pack folder with a valid pack.mcmeta. See Pack basics.

• A finished build no bigger than 48x48x48 blocks. That is the structure block limit.

Save a structure with a structure block

1. Give yourself a structure block and place it at one corner of your build. Set it to Save mode.

2. Type a name such as mypack:cabin. Without a namespace it uses minecraft.

3. Set the offset and size to cover the build, then press Save. Only the Save button writes a file.

4. Open <world>/generated/mypack/structures/ and copy cabin.nbt into your pack at data/mypack/structure/cabin.nbt.

The wiki lists the save folder as structures and the load folder as structure. Use structure inside a data pack.

Place it by command

/place template mypack:cabin ~ ~ ~

Optional arguments follow the position, in this order: rotation, mirror, integrity, seed, then strict.

• Rotation: none, clockwise_90, counterclockwise_90 or 180.

• Mirror: none, front_back or left_right.

• Integrity: 0.0 to 1.0. Below 1 it leaves part of the structure out, which looks like ruins.

• strict places blocks without block or shape updates.

For builds you place yourself, this is enough. Building a world of premade builds? See importing builds with WorldEdit.

Make it generate naturally

Natural generation needs a structure file (JSON), usually a template pool, and a structure set. All three live in data/mypack/worldgen/.

1. Template pool

A template pool lists which pieces the structure may use. The file is data/mypack/worldgen/template_pool/cabin.json:

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

rigid keeps the piece fixed. terrain_matching bends it to the ground, which suits roads. location points to your saved cabin.nbt.

2. Structure

The structure file is data/mypack/worldgen/structure/cabin.json:

{
  "type": "minecraft:jigsaw",
  "biomes": "#minecraft:is_forest",
  "step": "surface_structures",
  "spawn_overrides": {},
  "terrain_adaptation": "beard_thin",
  "start_pool": "mypack:cabin",
  "size": 1,
  "start_height": 0,
  "max_distance_from_center": 80,
  "use_expansion_hack": false
}

size is the jigsaw depth, 0 to 20. A single piece needs only 1. The start_height value here is a placeholder: check how your ground level should be set for 26.3. The biome tag #minecraft:is_forest was not checked against 26.3, so confirm it exists or list biome ids.

3. Structure set

A structure must be in a set to generate. File: data/mypack/worldgen/structure_set/cabin.json:

{
  "structures": [
    { "structure": "mypack:cabin", "weight": 1 }
  ],
  "placement": {
    "type": "minecraft:random_spread",
    "salt": 14357617,
    "spacing": 32,
    "separation": 8
  }
}

spacing is the average distance between attempts in chunks. separation is the minimum and must be smaller than spacing. salt is any number that makes your layout different from others.

Processors and jigsaws

A processor list swaps blocks as a piece is placed. Put it at data/mypack/worldgen/processor_list/mossy.json, then reference it from a pool element's processors key as mypack:mossy:

{
  "processors": [
    {
      "processor_type": "minecraft:rule",
      "rules": [
        {
          "input_predicate": { "predicate_type": "block_match", "block": "minecraft:stone_bricks" },
          "location_predicate": { "predicate_type": "always_true" },
          "output_state": { "Name": "minecraft:mossy_stone_bricks" }
        }
      ]
    }
  ]
}

Jigsaw blocks join several pieces. Each has a target pool, a name, and a target name. A jigsaw links to a piece in the target pool whose jigsaw name equals the first jigsaw's target name. Use size above 1 once you add them.

Restart after changing worldgen files. Structures only generate in chunks that are created after the pack loads. Existing chunks stay as they are, so test in a fresh area or world.

Check it worked

1. Run /place template mypack:cabin ~ ~ ~ and see your build appear.

2. For natural generation, make a new world with the pack and run /locate structure mypack:cabin.

3. Teleport there and check the build faces and sits correctly.

Common problems

Template not found

The file must be at data/<namespace>/structure/<name>.nbt, and the id must match.

The structure never generates

It is not in a structure set, the biome list does not match, or the chunks already existed.

The build floats or is buried

Try terrain_adaptation, or place a foundation layer in the saved build.

Parts of the build are missing

Check the 48 block limit and that your saved size covered the whole build.

Related: custom biomes.