Structure

Represents a captured box-shaped region of the world with its own internal coordinate system.

Coordinate system:

• When created, the block in the copied region with the smallest x, y, and z values becomes the structure’s origin.

• This origin is mapped to (0, 0, 0) in the structure’s local coordinates.

• All other blocks have non-negative local coordinates relative to this origin.

• The size property gives the dimensions (all values ≥ 1).

Standard usage:

Use structures to capture, store, and reuse any part of the world.

• Create with spell:copyStructure.

• Save to disk with save under any name (for example, "mickkay:castle/tower").

• Load later with Structure:load.

• Place it with spell:pasteStructure.

A structure has a name, not a file path, as all structures in Minecraft have: an ID like "mickkay:castle/tower", of a namespace and a path. That is how the game finds the structures of data packs and its own, and what lets you override one of them. A skin, in contrast, is saved under a file path of your choice, see Skin.

Example: Save and load your own structure

local struct = spell:copyStructure(spell.pos + Vec3(10, 8, 10))
struct:save("mickkay:castle/tower")
-- Later, or in another spell:
local loaded = Structure:load("mickkay:castle/tower")
spell:pasteStructure(loaded)

Advanced usage: Overriding vanilla structures

You can override Minecraft’s built-in structures by saving your own under a built-in name (for example, "minecraft:igloo/top").

• When Minecraft generates that structure, it will use your version instead of the default.

• When loading, if a custom file exists, it is used; if not, the built-in version is loaded.

Example: Override a vanilla structure

-- Replace the top part of igloos with your custom structure
local struct = spell:copyStructure(spell.pos + Vec3(7, 7, 7))
struct:save("minecraft:igloo/top")

Fields

author: string — Read-Only

The name of the entity that created this structure.

nbt: table — Read-Only

The NBT (Named Binary Tag) data for the structure.

size: Vec3 — Read-Only

The dimensions of the structure (width, height, depth).

Methods

load(name: string) → structure: Structure

Loads the structure with the given name. Call it on the class: Structure:load(name).

It finds a structure that save saved in this world, and also the structures of the data packs and of Minecraft itself, like "minecraft:igloo/top". A structure saved in this world under the name of a built-in one comes first. Raises an error if there is none of that name.

Example: Load and paste a structure

local struct = Structure:load("mickkay:castle/tower")
spell:pasteStructure(struct)

Parameters

• name: string — The name of the structure: a namespace and a path, like "mickkay:castle/tower". Without a namespace, it is "minecraft".

Returns

• structure: Structure — The loaded structure.

save(name: string) → path: string

Saves the structure under the given name in the world folder, replacing a structure that is saved under that name already. Structure:load loads it again, also after a restart of the server.

The name is a namespace and a path, like "mickkay:castle/tower", in lower case: letters, digits, "_", "-", "." and, in the path, "/". Without a namespace, it is "minecraft". The structure goes into the file generated/<namespace>/structure/<path>.nbt of the world folder, where Minecraft keeps the structures that a structure block saves.

Returns the file path where the structure was saved, relative to the world folder, with "/" between the folders on every system, so that a spell can pass it to io.open.

Example: Copy and save a structure

local struct = spell:copyStructure(spell.pos + Vec3(10, 10, 10))
local path = struct:save("mickkay:arena")
print("Saved at " .. path) -- generated/mickkay/structure/arena.nbt

Parameters

• name: string — The name to save the structure under.

Returns

• path: string — The file path where the structure is saved, relative to the world folder.