Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Chapter 40 — Structure Blocks and Structure Files

Part XI — Advanced: World Generation. This is the start of the hardest part of the book. World generation is where data packs become most powerful and most complex, and these chapters assume you are comfortable with everything from Parts I–VIII. Take them slowly. The good news: this first chapter doesn’t involve a single line of JSON. It’s about a special block and the files it writes.

What You’ll Build

Everything you’ve built so far, you’ve built by describing it: a recipe is a JSON file that lists ingredients, a loot table is a JSON file that lists drops. But some things are easier to build by hand: a cottage, a watchtower, a fountain. You place the blocks in the world the normal way, then you want to keep that building so your data pack can stamp copies of it wherever you like.

That’s exactly what a structure block does. By the end of this chapter you’ll take a small building you place by hand in your test world (the one from Chapter 1), capture it with a structure block into a structure file (a .nbt file the game writes for you), and then move that file into the mypack data pack you started in Chapter 9. Once it lives in your pack, you can drop the building back into the world any time, in any of your functions.

This is also the foundation for the next chapter. In Chapter 41 you’ll learn how to make Minecraft generate a building naturally as the world is explored, and every piece of those generated structures is one of these same .nbt files. Save a building first; teach the world to spawn it second.

Figure (to be captured). a small cottage in the world with a structure block beside it, the white structure outline drawn around the building

What a structure block is

Here’s the plain definition:

“A structure block is used to generate structures manually. They can also be used to save and load structures, alongside structure void blocks.”

So a structure block has two jobs: save a chunk of the world (its blocks, and optionally the entities standing in it) into a file, and load that file back into the world later. Think of it as a camera for buildings: it photographs a box-shaped region and can re-print the photo anywhere.

You can’t find a structure block while mining; it’s an operator tool. Structure blocks are obtained using the setblock, fill, or give commands, or from the Creative inventory in Java Edition through the “Operator Utilities” tab. Once placed, structure blocks are unbreakable in Survival and have the same blast resistance as bedrock, so don’t worry about a creeper destroying your work. To give yourself one, you’ll run a command from a function (commands live in .mcfunction files, never the chat bar; that’s been our rule since Chapter 1). Here’s a tiny helper for your pack:

mypack/data/mypack/function/get_structure_block.mcfunction

give @s minecraft:structure_block

Run it with function mypack:get_structure_block, and a structure block appears in your inventory.

To use the block, place it and right-click it to open its window. There’s a catch worth knowing: the GUI opens only if the player is in Creative mode and has permission level 2 or higher. A GUI (graphical user interface) is just the pop-up screen of buttons and text boxes the block shows you. So: be in Creative mode and be an operator. (You made yourself an operator back in Chapter 8.)

One structure block can be switched between several modes, and switching between modes preserves the settings of the structure block wherever possible, so you won’t lose your typed-in name when you flip from one mode to another. Once you name a structure, its name appears above the structure block when highlighted, preceded by the block mode (e.g. “Save:minecraft:example”), a handy way to see at a glance what a block is set to do.

The modes that matter for us are Save, Load, and Corner. There are two more (a Windows-only 3D Export mode and a deprecated Data mode), and we’ll mention what those are near the end so you recognize them, but you won’t need them.

The structure file: what .nbt is and where it lives

When a structure block saves a building, it writes a structure file:

“A structure file (also called structure template) is an NBT file that stores small structures of blocks and entities. Structure files are used to store some structures such as end cities, igloos, and fossils.”

So a structure file is a single file, ending in .nbt, that holds a snapshot of some blocks (and maybe entities). It’s the same kind of file Mojang themselves use for the prefab pieces of vanilla structures. NBT stands for Named Binary Tag; for now all you need to know is that it’s a packed binary format you don’t open in a text editor. (We’ll peek at what’s inside it later in this chapter, under “Under the Hood.”)

The important fact is where these files go inside a data pack. You learned the data-pack folder rule in Chapter 9: a file at data/<namespace>/<registry>/<path> loads into Minecraft under the ID <namespace>:<path>. Structure files follow that exact rule, with one twist: they use the .nbt extension instead of .json or .mcfunction. The structure folder holds .nbt files defining a saved structure of blocks, and structure files always use the .nbt extension.

So a structure called cottage in your mypack namespace will live at:

mypack/data/mypack/structure/cottage.nbt

and its namespaced ID (the name you’ll use to place it) is mypack:cottage. Same pattern as functions, recipes, and everything else: the folder is named for what’s inside it, and sub-folders become part of the ID after a slash.

Modern Minecraft — structure, not structures

If you follow an older tutorial online, you may see the folder called structures (plural) sitting next to a data folder shaped a bit differently. Modern data packs use the singular structure folder under data/<namespace>/. The world-save folder the game writes saved files into is still called generated/<namespace>/structures (plural; you’ll see that path in a moment), but the folder inside your pack is the singular structure. Watch the spelling; a misnamed folder is the single most common reason a structure won’t load.

Walkthrough A — Save a building

Let’s capture a building. First, build something small by hand in your test world (a little cottage, say, no bigger than a dozen blocks on a side). Keep it modest: the maximum structure size is 48×48×48 in Java Edition, so a region can be at most 48 blocks in each direction. Note the north-west bottom corner of your building, the corner toward the smallest X, Y, and Z, the same corner-reasoning you used for /fill and /clone in Chapter 2.

Now place a structure block one block away from that bottom north-west corner, open it, and make sure it’s in Save mode. Save mode lets you highlight a structure in the world and save it to memory, the level file, or a separate file. The window gives you these fields:

  • Structure Name — a text box for entering the resource location of the structure to be saved. Type mypack:cottage. Here’s the namespace rule: if no namespace is specified, a default value of minecraft is used; you change that by prefixing the structure name with <namespace>:. So always type your mypack: prefix. Otherwise the game files it under minecraft and you’ll hunt for it in the wrong place.

  • Relative Position / Offset — the X, Y, and Z offsets of the structure, relative to the bottom north-west corner of the structure block. Sets the origin of the structure outline. This is where the captured box starts, measured from the block. The origin must be at most 48 blocks away in all directions.

  • Structure Size / Size — X, Y, and Z offset from the Relative Position coordinates. This sets the opposite corner of the structure and defines the structure’s size. In other words, Offset picks one corner and Size sets how far the box extends. When you get it right, it generates an outline surrounding the structure that’s mostly white except for the red, green, and blue lines that represent the X, Y, and Z axis. That glowing box is your structure outline (also called the bounding box); adjust the numbers until it hugs your building exactly.

  • Include entities — when saving the structure, if this option is on, it saves any entities within the structure as well. Turn this on if you want, say, an armor stand or a painting captured along with the blocks; leave it off for a plain building.

When the white outline wraps your cottage perfectly, press Save. In Java Edition this saves the structure to a file, and the name of the structure is the name of the file. Your building is now a .nbt file. (Two cautions worth knowing: structures can be saved to a file only by manually pressing this button. If a structure block in Save mode is instead powered by redstone, the structure is only saved in memory, and reloading the world clears any structures stored in memory. So press the button yourself; don’t wire a structure block to redstone and expect a file.)

Figure (to be captured). the structure block Save-mode GUI, with Structure Name “mypack:cottage” typed in and the size fields filled

Corner mode — let the game measure the box for you

Typing exact Offset and Size numbers is fiddly. Corner mode does the measuring for you: it allows for an easier and automatic size calculation while saving or loading structures. The idea is to mark the opposite corner of your building with a second block.

Here’s the recipe: place a corner block on the opposite corner of a save structure block or a second corner structure block. Then, using a save block, press “DETECT”. So:

  1. Place a structure block at the bottom north-west corner of your build, set it to Save mode, and name it mypack:cottage.
  2. Place a second structure block at the opposite (top south-east) corner, set it to Corner mode, and give it the same name, mypack:cottage.
  3. Back in the Save block, press Detect structure size and position (the “DETECT” button).

That button automatically calculates the size and position of the structure using a corner block placed on the opposite corner of the structure. One rule to stress: the name of the structure in the save block must match the name within the corner block, or the size calculation fails. Same name on both blocks, every time. When it works, the white outline snaps around your whole building and you can press Save.

Where the file landed — and the move into your pack

Here’s the part that surprises people. When you press Save in Java Edition, the file does not go into your data pack. Here’s exactly where it goes:

“Structures are saved in .minecraft/saves/(WorldName)/generated/(namespace)/structures.”

So your cottage is now sitting at:

.minecraft/saves/<your world>/generated/mypack/structures/cottage.nbt

(<your world> is the folder for the world you’re testing in; mypack is the namespace you typed because you prefixed the name.) This generated/ folder is a scratch area the game writes structure-block saves into. It is not part of any data pack, and it only exists for the one world.

To turn your one-off save into a real, shippable part of your pack, you copy the .nbt file into your pack’s structure folder. Close Minecraft (or at least the world), open your file explorer, and move the file:

FROM:  .minecraft/saves/<your world>/generated/mypack/structures/cottage.nbt
TO:    mypack/data/mypack/structure/cottage.nbt

That single copy is the whole “export” step: build, save, copy into the pack. This is the round trip on the structure-file side: files can be saved and loaded using the structure block, and when saved from structure blocks they are written into the generated/<namespace>/structures subfolder in the world save folder; inside a data pack, structure files are stored as .nbt files in the structure folder. Once the file is in mypack/data/mypack/structure/cottage.nbt, anyone who installs your data pack gets your cottage; it travels with the pack.

What Went Wrong? — “I can’t find the file”

Two things trip people up. First, the file is under generated/, not under datapacks/; those are different folders inside the world save. Second, if you forgot the mypack: prefix when naming the structure, the game used the default minecraft namespace, so your file is at generated/minecraft/structures/cottage.nbt instead. Either way, look for the .nbt file by its name; then copy it into mypack/data/mypack/structure/.

Walkthrough B — Load the building back

Now that cottage.nbt lives in your pack, let’s stamp a copy into the world. There are two ways: a structure block in Load mode, and the /place template command.

A structure block in Load mode lets you load and rotate saved structures. Place a structure block where you want the bottom north-west corner of the copy to appear, set it to Load mode, and type the name mypack:cottage. The useful options here:

  • Relative Position / Offset — same idea as before: where the loaded copy sits relative to the block.
  • Rotation (0, 90, 180, 270) — sets the rotation of the structure to 0° (no rotation), 90° clockwise, 180° clockwise, and 270°. Great for facing a building a different way.
  • Mirror — flips the structure left-to-right or front-to-back.
  • Include entities — includes any entities saved in the structure file when loading the structure. Off by default. Turn it on if you saved entities and want them back.
  • Structure Integrity and Seed — removes random blocks that compose the structure based on a user-defined seed. Lower integrity values result in more blocks being removed; the integrity value must be between 0.0 and 1.0. Leave this at 1.0 for a perfect copy; lower it later if you want a ruined, decayed look.

Load mode looks for the file in a set order, and that order matters. It’s why copying the file into your pack works. It searches, in order: from memory; from a file (…/generated/<namespace>/structures/); from data packs; then built-in structures from minecraft.jar. So a structure block will find mypack:cottage inside your data pack (third in the list) even after the generated/ scratch copy is gone.

Press Load. Note the two-press behavior in Java Edition: press this button once to prepare the outline preview of the structure, then, when satisfied with the position, press again to generate the structure. First press previews where it’ll land; second press builds it.

Try It! — place a structure from a function

A structure block is great for testing, but the whole point of putting the file in your pack is that your functions can place it. Structure files can also be placed using the place template command. So this one-line function stamps your cottage at the spot the command runs from:

mypack/data/mypack/function/place_cottage.mcfunction

place template mypack:cottage ~ ~ ~

Run it with function mypack:place_cottage while standing where you want the building’s corner, and the cottage appears, no structure block needed. This is exactly how a data pack ships a build.

Under the Hood — what’s inside a .nbt structure (skippable)

You never hand-edit a structure file, but it helps to know it isn’t magic. Here’s the shape of the NBT inside. The root holds a DataVersion (which Minecraft version made it), a size (three numbers: the box’s length, height, and depth), a palette (the list of distinct block types used, each with its block ID and block-state properties), a blocks list (every individual block, stored as a position plus an index into the palette, so a wall of 100 stone bricks references one palette entry 100 times instead of repeating “stone brick” 100 times), and an entities list (any saved entities, each with a position and its entity data). That palette-and-index trick is why a structure file stays small even for a big build.

You do not write this by hand. It’s packed binary, the structure block fills it in for you, and the only sensible way to create or change one is the build-save-copy workflow in this chapter. The exact byte-level binary layout of the .nbt file (a gzip-compressed Named Binary Tag stream) is a topic for tooling authors, not pack builders. By design, this book teaches the structure-block workflow, and you never need to crack the file open.

Modern Minecraft — Data mode and structure voids

Two pieces of structure-block lore you’ll see mentioned elsewhere but won’t use here. Data mode is a deprecated mode, superseded by the jigsaw block but still used in some vanilla structures. It marks spots inside vanilla structures to run hardcoded behavior (placing the treasure chest in a shipwreck, for example) and can be used only during natural generation, so it’s not something your pack drives directly. We’ll meet its modern replacement, the jigsaw block, in Chapter 41. The other term is the structure void block, mentioned in the structure-block definition: it’s a special block that marks “leave whatever’s already here” inside a saved structure, so a captured piece can have see-through gaps. You won’t need either to ship a building.

Practice

  1. Save a build of your own. Build something you actually want to reuse (a guard tower, a market stall, a decorative well), keeping it under 48×48×48. Capture it with Save mode (use Corner mode to measure it), name it with your mypack: prefix, and copy the resulting .nbt out of generated/mypack/structures/ into mypack/data/mypack/structure/. Confirm it loaded by running a place template mypack:<name> ~ ~ ~ function.

  2. A rotated row. Write a function that places your structure three times in a row, each copy facing a different way, by running place template at three offset positions. (You can use the ~ relative coordinates from Chapter 2 to space them out.)

  3. A ruined version. Load your structure with a structure block, but lower the Structure Integrity below 1.0 (try 0.6) and watch random blocks drop out. This is how you’d make a weathered, half-collapsed ruin from the same file you used for the pristine building.

What Can Go Wrong

  • The structure won’t load from the pack. Almost always a folder-name or namespace slip. Inside the pack the folder is structure (singular), and the full path must be mypack/data/mypack/structure/cottage.nbt. Check the spelling, check the .nbt extension is really there (not cottage.nbt.txt), and check the name you load matches the name you saved, including the mypack: namespace.

  • “Detect” doesn’t size the box. The Save block and the Corner block must have the exact same name. The rule is firm: the name of the structure in the save block must match the name within the corner block, or the size calculation fails. Re-type the name on both blocks and press Detect again.

  • I saved it but there’s no file. You either powered the structure block with redstone (which only saves to memory, never to disk) or never pressed the Save button by hand. Open the Save block and press the button yourself; then look in generated/<namespace>/structures/.