API Worldgen Structure Geometry

Structure geometry elements

Lua API / World generation / Structure documents / Geometry

Geometry elements write named palette states into structure-local coordinates. They do not inspect or modify the world. Unless stated otherwise, elements accept optional tags and write fields.

Basic blocks and boxes

{
"elements": [
  { "type": "block", "pos": [0, 3, 0], "state": "cap" },
  { "type": "fill", "from": [-3, 0, -3], "to": [3, 0, 3], "state": "floor" },
  {
    "type": "shell",
    "from": [-3, 1, -3],
    "to": [3, 4, 3],
    "thickness": 1,
    "faces": ["north", "east", "south", "west"],
    "state": "wall"
  },
  { "type": "frame", "from": [-3, 1, -3], "to": [3, 4, 3], "state": "beam" }
]
}

Field definitions

Type	Required fields	Behavior
block	pos, state	Writes one cell. Optional facing gives directional metadata a local authored orientation.
fill	from, to, state	Fills the complete inclusive cuboid.
shell	from, to, state	Writes selected outer faces. thickness defaults to 1; faces defaults to all six faces.
frame	from, to, state	Writes the cuboid's twelve edges. thickness defaults to 1.

For a box from [0,0,0] to [4,4,4], thickness 1 selects the outer coordinate layer. Thickness 2 also selects the next layer inward. from and to may be reversed on any axis.

Lines

{
  "type": "line",
  "from": [0, 0, 0],
  "to": [5, 3, 2],
  "state": "beam"
}

line includes both endpoints. For a diagonal, BetaMoon follows the dominant axis and adds connected bridging cells when more than one coordinate changes between steps. The result is a face-connected block path rather than isolated corner-touching cells.

Staircases

{
  "type": "staircase",
  "from": [-4, 0, 0],
  "to": [4, 4, 0],
  "width": 3,
  "facing": "east",
  "state": "stairs"
}

The endpoints must differ along exactly one horizontal axis. Height is interpolated between the endpoints, and width expands equally around the travel line, with the extra cell on the positive side for an even width.

facing does not select travel direction; from and to do that. It declares the local orientation used to transform directional block metadata. Valid facings are north, east, south, and west.

Cylinders

{
  "type": "cylinder",
  "base": [0, 0, 0],
  "radius": 4,
  "height": 6,
  "axis": "y",
  "mode": "shell",
  "thickness": 1,
  "caps": ["top"],
  "state": "stone"
}

base is the center of the first cross-section. axis defaults to y; height extends in the positive axis direction and accepts 1–128. Radius may be one integer or a two-axis radius. mode is solid by default or shell. Caps are absent by default and may contain top, bottom, or both. In shell mode, thickness applies to the curved wall and selected caps.

Ellipsoids

{
  "type": "ellipsoid",
  "center": [0, 5, 0],
  "radius": [4, 2, 3],
  "mode": "shell",
  "thickness": 1,
  "state": "stone"
}

The radius array is [x, y, z]. X/Z radii accept 1–32 and Y accepts 1–127. A scalar radius creates a sphere. solid fills the volume; shell retains its boundary with the configured thickness.

Voxel maps

{
  "type": "voxel_map",
  "at": [-2, 0, -1],
  "legend": {
    "#": "stone",
    "G": "glass",
    ".": null
  },
  "layers": [
    ["#####", "#...#", "#####"],
    ["##G##", "G...G", "##G##"]
  ]
}

layers are ordered upward from local Y zero. Each layer contains Z rows and each character advances X. Every layer must have the same row count, every row must have the same length, and every used ASCII character must have a one-character legend entry. A null legend value leaves that coordinate unauthored; it does not place air.

Editing earlier symbolic content

{
"elements": [
  { "type": "fill", "from": [-4, 0, -4], "to": [4, 4, 4], "state": "stone" },
  { "type": "clear", "from": [-3, 1, -3], "to": [3, 3, 3] },
  {
    "type": "replace_state",
    "from": [-4, 0, -4],
    "to": [4, 1, 4],
    "replace": ["stone"],
    "with": "foundation"
  }
]
}

Type	Behavior
clear	Removes previously authored symbolic cells inside the inclusive box. It does not place air and does not clear world blocks.
replace_state	Changes matching earlier symbolic states inside the box to with.

If the final structure must clear a world block, define an air palette state and register the structure with processors.includeAir = true.

Overlapping writes

Two writes of the same state to the same coordinate merge their element tags. Two different states at one coordinate are an authoring conflict unless the later element explicitly sets:

{ "write": "replace" }

This authorizes that intentional authored overwrite. It does not bypass placement-time replaceOnly, tile collision, or other world safety rules. A conflicting conditional branch rejects that resolved placement before any block is changed.

Next: templates and conditional composition.