SchematicLoader

A Minecraft Bedrock Edition Script API tool that places .mcstructure structures at runtime, procedurally - no structure_id, no structure block, and no baking the structure into the pack's structures/ folder ahead of time. Supports 0/90/180/270° rotation and X/Z mirroring per placement.

Why two steps?

The Bedrock Script API has no filesystem access, so a running script can't open a .mcstructure file off disk. This project works around that with a small offline conversion step:

1. converter/ - a Node.js CLI you run on your machine (not in-game) that parses the binary NBT .mcstructure format and writes out a plain .js data module.
2. scripts/Schematic/ - the in-game runtime library. It imports that generated module like any other script file and places blocks a batch at a time via system.runJob, so large structures won't trip the watchdog.

Usage

1. Export a structure in-game with a structure block, then find the .mcstructure file under %appdata%\Minecraft Bedrock\users\<Your_User_ID>\games\com.mojang\minecraftWorlds\<world>\structures\ or the file path you exported it to.

2. Convert it:

cd converter
node convert.js path/to/your-structure.mcstructure ../scripts/structures/your-structure.js

Flags:

• --include-air - keep air blocks in the output (useful if you want the structure to clear existing terrain where it's placed; omitted by default to keep files small and placement fast).
• --no-entities - skip captured entities.

3. Point scripts/main.js at your converted file:

import structureData from './structures/your-structure.js';

4. Place it in-game by typing .place in chat at the location you want it. Optional args let you rotate and mirror the placement:

.place              → rotation 0, no mirror
.place 90           → rotated 90°
.place 90 x         → rotated 90°, mirrored on X

Placement progress and errors are reported back in chat. See scripts/main.js for the full command implementation, or call Schematic.place() directly from your own code:

import { Schematic } from './Schematic/Schematic.js';
import structureData from './structures/your-structure.js';

const structure = new Schematic(structureData);

await structure.place(dimension, { x: 100, y: 64, z: 200 }, {
  rotation: 90,
  mirror: 'none',
  onProgress: (placed, total) => console.warn(`${placed}/${total}`),
});

Limitations

• Block state rotation is best-effort. BlockStateRotation.js remaps the common directional state keys (direction, weirdo_direction, minecraft:cardinal_direction, pillar_axis), which covers stairs, logs, doors, and most furniture-style blocks. It does not cover every block in the game - if a block looks wrong after rotating, check its block states in-game and extend BlockStateRotation.js.
• Waterlogging (layer 1 of block_indices) isn't placed. Only the main block layer is used; add layer-1 handling to convert.js if you need it.
• Block entity data (chest contents, sign text, etc., stored in block_position_data) isn't carried over yet - blocks place with their default state.
• Very large structures still take real time to place even batched across ticks; tune blocksPerTick down if you see server hitching.

License

MIT - see LICENSE.