API Worldgen Structure Format

Structure documents

Lua API / World generation / Local structures / Structure documents

A structure document describes symbolic block geometry before BetaMoon interacts with the world. The same document shape can be loaded from JSON, supplied as a plain Lua table, or assembled through the Lua builder. Start here for the root fields and palette, then use the focused pages for geometry, composition, processors, Lua authoring, and loot.

Minimal document

{
  "format": "betamoon_structure",
  "palette": {
    "stone": {
      "block": 4,
      "tags": ["structural", "weatherable"]
    }
  },
  "elements": [
    { "type": "fill", "from": [-2, 0, -2], "to": [2, 0, 2], "state": "stone" },
    { "type": "marker", "pos": [0, 0, 0], "name": "terrain_support" }
  ],
  "processors": []
}

Field definitions

Field	Behavior
format	Required in JSON and must be betamoon_structure. Lua input inserts it when omitted; an explicitly different value is rejected.
bounds	Optional inclusive { min, max } bounds. Omit it to infer conservative bounds.
palette	Required object of named symbolic states.
templates	Optional reusable local element groups.
elements	Required root element list.
processors	Optional ordered document-processor list.

Coordinates and bounds

Coordinates are [x, y, z] relative to the placement origin [0, 0, 0]:

• X and Z must be from -32 through 32.
• Y must be from -127 through 127.
• Box corners such as from and to may be written in either order.
• Bounds are inclusive and must contain the origin.
• Explicit bounds must contain every possible block, marker, loot target, conditional branch, and deposit target.

Inferred bounds are usually best. Deliberately larger bounds are useful when a structure needs reserved space, but they also enlarge regional overlap checks, full_bounds site validation, and terrace preparation.

Named palette states

A state describes one block result or a weighted set of block variants:

{
"palette": {
  "wall": {
    "variants": [
      { "block": 4, "weight": 4 },
      { "block": 48, "weight": 1 }
    ],
    "tags": ["wall", "weatherable"]
  },
  "chest": {
    "block": 54,
    "meta": 0,
    "tags": ["protected"]
  }
}
}

Field definitions

Field	Behavior
block	Block ID or supported block name for a single-state entry.
meta	Block metadata 0–15; defaults to 0.
data	Typed initial data for a registered BetaMoon tile block. It is not arbitrary native tile NBT.
tags	Semantic labels combined with element tags for processor selection.
variants	Nonempty weighted list replacing the single block, meta, and data fields.
weight	Positive relative weight; defaults to 1.

A variant is sampled independently for every occupied coordinate. A variant with weight w has probability w / sum of all variant weights at that coordinate. It is not chosen once for the whole structure.

Effective cell tags combine the selected palette state's tags with the geometry element's tags. Recoloring or replacing a symbolic state changes the palette tags seen by later processors, while the element tags remain attached to that coordinate.

Marker catalog

Markers attach semantic information without placing a block:

{ "type": "marker", "pos": [0, 0, 0], "name": "terrain_support" }

Marker	Consumer
connector	Regional piece assembly. Its value defines pool and outward facing.
entity	Regional entity spawning when markers.entities = true.
tile_data / data	Merges one object over palette tile data at the same coordinate. Only one tile-data marker may resolve at a coordinate.
terrain_support	Explicit structure-to-terrain contact point. Any explicit support markers replace the automatically inferred support mask.
terrain_clearance	Explicit cell used by clearance-mask site checks. An authored excavation volume may deliberately reuse these exact voxels.
terrain_ignore	Excludes a cell from automatic support derivation.
terrain_conform	Allows an existing support column to move independently in conform mode.
terrain_conform_exclude	Removes an existing support column from the configured conform selection.
terrain_blend	Extends authored terrain blending around a structure.
Custom name	Passive metadata until a documented feature consumes it.

loot is a dedicated element type and is rejected as a marker name. Duplicate tile_data/data markers at the same resolved coordinate reject that placement instead of silently replacing one another.

Processing model

BetaMoon resolves a document in this order:

1. Expand authored geometry and templates.
2. Resolve keyed chance and choice groups.
3. Run document processors in declaration order.
4. Select weighted palette variants per remaining coordinate.
5. Apply the registered structure's placement processors and terrain policy against the world.
6. Commit blocks, typed tile data, and inventory loot transactionally.

Document processors operate only on symbolic structure cells. They never inspect surrounding terrain. Placement processors are the separate processors table supplied to structures:add; see local structures.

Validation and limits

The structure JSON schema catches document shape, allowed fields, enum values, and many local numeric limits. Loading the mod performs the authoritative semantic checks, including referenced states and templates, recursion, expanded coordinates, write conflicts, array products, loot compatibility, processor bounds, and block budgets. A document that shows no editor warning can therefore still be rejected when its references or combined expansion are invalid.

Important limits include:

• at most 8192 resolved block changes;
• at most radius 32 from the placement origin;
• template nesting no deeper than 16;
• at most 256 array instances;
• strict UTF-8 JSON and a 4 MiB structure-file limit;
• unknown fields are rejected rather than ignored.

A failed local plan changes nothing. A regional structure commits independently for each intersecting chunk slice; failure in one slice does not roll back previously completed chunks.

Detailed references

Page	Covers
Geometry elements	Blocks, boxes, lines, stairs, cylinders, ellipsoids, voxel maps, clear, and state replacement.
Templates and conditional composition	Templates, transforms, arrays, repeats, chance, choice, and conflict rules.
Processors and selectors	Recolor, replace, decay, erode, deposit, selectors, patterns, and protection.
Lua authoring and builder	Plain tables, builders, snapshots, and compiled handles.
Structure inventory loot	Fixed items, randomized pools, reusable tables, slot policies, and rollback.
Terrain placement	Surface fitting, masks, foundations, terraces, conforming, excavation, and site profiles.

Example: local structure package