.mcstructure File Format and Usage

All structure files belong in the structures folder at the root of your behavior pack. Unlike blocks or entities, a .mcstructure file does not contain an internal JSON identifier definition. Instead, Minecraft derives the structure's identifier directly from its subfolder path and file name.

Because the root structures directory maps to the default mystructure namespace unless organized into subfolders, you should always create a subfolder named after your add-on's namespace inside BP/structures/. For example, a file placed at BP/structures/my_addon/watchtower.mcstructure is referenced in commands and JSON files as my_addon:watchtower. If you place watchtower.mcstructure directly in BP/structures/ with no subfolder, the game assigns it the identifier mystructure:watchtower.

You create .mcstructure files inside the game using a Structure Block (`minecraft:structure_block`). After giving yourself one via `/give @s structure_block`, place it down and open its UI to set the bounding box size and offset around your build. Switch the block to Save mode, type a name using the `namespace:name` format, and choose whether to include entities or remove blocks.

To get the actual file out of the game on Windows, click the Export button at the bottom of the Structure Block menu. This opens a standard system file dialog allowing you to save the .mcstructure file directly to your development folder. On platforms where the Export button is not available, saving the structure to disk writes it into the world's internal database; you must instead export the build on a Windows device or extract it from the world's LevelDB storage using an external NBT editor.

Before saving any structure meant for natural world generation, replace solid air pockets that should not overwrite terrain with Structure Void blocks (`minecraft:structure_void`). When the structure loads, any coordinate holding a Structure Void leaves the existing world block untouched instead of replacing it with air.

Unlike most behavior pack assets, a .mcstructure file is not human-readable JSON. It is an uncompressed binary NBT file written in little-endian byte order. You do not edit this file by hand in a text editor, though you can inspect it with a Bedrock-compatible NBT viewer if you need to check which custom blocks or entities were captured inside it.

The root compound tag of the file stores the dimensions of the capture volume, the coordinate where it was originally taken, and the block and entity arrays. Block placement uses two separate layers inside the grid indices so a single coordinate can hold both a primary block (such as a fence or stairs) and a secondary waterlogging block (`minecraft:water`).

The most common use for .mcstructure files in an add-on is natural terrain generation. To place a structure into the world as chunks generate, you wrap it in a `minecraft:structure_template_feature` file inside `BP/features/`. This JSON file tells the game which structure file to load, which direction it can face, and what constraints must be met before it places.

In the example below, the feature references `BP/structures/my_addon/outpost.mcstructure` via its `structure_name` field. The `grounded` constraint forces the bottom layer of the structure to sit entirely on solid terrain so your building does not hang off the edge of a cliff.

{
  "format_version": "1.13.0",
  "minecraft:structure_template_feature": {
    "description": {
      "identifier": "my_addon:outpost_feature"
    },
    "structure_name": "my_addon:outpost",
    "adjustment_radius": 8,
    "facing_direction": "random",
    "constraints": {
      "grounded": {},
      "unburied": {}
    }
  }
}

Outside of world generation, you can place any packaged .mcstructure file on demand using the `/structure load` command inside functions or command blocks. The command accepts rotation, mirror settings, animation modes, and an integrity percentage for ruined builds. In `mcfunction` files, this is the standard way to build multi-room arenas or reset minigame maps.

If your behavior pack uses `@minecraft/server`, you can also manipulate and place structures through the `StructureManager` class accessed via `world.structureManager`. Script access allows you to check whether a structure exists in the pack, place it in a specific dimension, or even create temporary structures in memory at runtime.

Applies to Bedrock Edition 1.13.0 and above. Loading .mcstructure files via commands, features, or the stable Script API does not require any experimental toggles.

Read out of the game itself, so the ids match the version you are building for.