API Worldgen Regional Structures

Regional structures

Lua API / World generation / Regional structures

Regional structures assemble registered local structures into deterministic layouts that can cross chunk boundaries. BetaMoon saves the chosen start, pieces, transforms, terrain adjustments, and completed chunk parts with the world so generation order and restarts do not change the layout.

betamoon.worldgen.structures:addRegional(definition)

Registers a regional structure and returns a reference. Keys normalize to namespace:structure/path.

local structures = betamoon.worldgen.structures

local gate = structures:add { key = "mymod:ruins/gate" }
local road = structures:add { key = "mymod:ruins/road" }
local house = structures:add { key = "mymod:ruins/house" }

local ruins = structures:addRegional {
    key = "mymod:ruined_village",
    start = gate,
    spacing = 32,
    separation = 8,
    height = { type = "solid_surface" },
    site = "land_surface",
    siteSearch = { attempts = 8, radius = 7 },
    pieces = {
        { pool = "road", structure = road, weight = 4 },
        { pool = "road", structure = house, weight = 2 }
    },
    maxDepth = 5,
    maxPieces = 40,
    maxDistance = 160,
    terminationChance = 0.2,
    markers = { entities = true }
}

Field definitions

Field	Default / behavior
key	Required stable key.
start	Required local structure reference/key used as the root piece.
dimensions	overworld; one value or a list containing overworld/minecraft:overworld and nether/minecraft:nether.
spacing	32; random-spread region size in chunks, from 2 through 512.
separation	min(8, spacing - 1); from 0 through spacing - 1.
salt	0; stable extra seed input for this distribution.
height	{ type = "surface", offset = 0 }; a fixed Y, { type = "fixed", value = y }, or a supported surface sampler with optional offset.
site	Optional environment profile applied to the root and candidate child pieces.
siteSearch	Optional same-chunk fallback { attempts = 1..32, radius = 0..7 }; defaults to one attempt and radius zero. When present, omitted fields default to 8 and 7.
connectorVerticalTolerance	0, from 0 through 16; maximum vertical adjustment accepted while joining pieces.
pieces	Weighted { pool, structure, weight = 1 } candidates. May be omitted for a root-only structure.
maxDepth	4, from 0 through 16 connector steps from the root.
maxPieces	32, from 1 through 128, including the root.
maxDistance	128 blocks, from 16 through 512 and no greater than spacing * 16.
terminationChance	0.2, from 0 through 1; independent chance to close an open connector before choosing a piece.
markers.entities	false; enables the regional entity-marker pass.

getRegional(key) returns a reference or nil; getRegionalRequired(key) raises an error when absent.

Connectors and piece pools

A connector marker's coordinate is its connection point and facing points outward from that piece. Matching connectors have the same pool and opposite world-facing directions after transforms. The candidate is translated so the two marker coordinates meet.

Root piece:

{ "type": "marker", "pos": [6, 0, 4], "name": "connector", "value": { "pool": "road", "facing": "east" } }

Child piece:

{ "type": "marker", "pos": [0, 0, 2], "name": "connector", "value": { "pool": "road", "facing": "west" } }

A pieces entry's pool determines which open connectors may select that structure. The candidate structure must also contain a compatible connector with which to attach. Weights are relative: weights 4 and 2 select the first candidate twice as often when both can fit. Before selection, terminationChance may close the connector without adding anything.

BetaMoon tries deterministic weighted candidates and horizontal rotations. It rejects candidates whose bounds overlap an existing piece, whose connector cannot align within connectorVerticalTolerance, whose terrain or site checks fail, or which exceed distance, depth, piece, block, or world-height limits.

Height, site, and terrain order

The root height chooses its initial Y. The root local structure's terrain policy then performs fitting or terrain preparation. The regional site validates the resulting environment. Each child begins from connector alignment, runs its own local terrain policy, and must remain within connectorVerticalTolerance of the connection. This division is important: a site profile decides whether terrain is suitable, while the local structure's terrain mode decides how the piece is moved or supported.

That local policy includes selector-based conforming columns and independent excavation. Once a regional structure's layout is chosen, later chunk generation uses the same terrain fitting and excavation result for its remaining parts.

siteSearch tries a bounded deterministic sequence around an invalid root location within the originally selected chunk. It never searches or loads a neighboring chunk. See structure terrain placement for samplers, modes, site profiles, and rejection reasons.

Entity markers

Entity markers are optional and only run when markers = { entities = true } is present. A string value names the registered BetaMoon entity type; an object can also set orientation.

{ "type": "marker", "pos": [3, 1, 4], "name": "entity", "value": "mymod:guard" }

{
  "type": "marker",
  "pos": [3, 1, 4],
  "name": "entity",
  "value": { "type": "mymod:guard", "yaw": 90, "pitch": 0 }
}

yaw defaults to 0 and accepts -360 through 360; pitch defaults to 0 and accepts -90 through 90. The piece transform updates yaw. The entity is spawned at the horizontal center of the marker block (x + 0.5, z + 0.5) and at its marker Y. Entity marker failures are reported in diagnostics after blocks commit and are not retried automatically.

Use a dedicated structure loot element for inventory contents; loot participates in the same block-and-inventory transaction instead of the entity post-pass.

Saved plans and chunk generation

Regional generation never loads neighboring chunks. When an intersecting chunk becomes available, BetaMoon validates and commits only that chunk's part of the saved layout. If that block or inventory transaction fails, it leaves no partial changes and may retry when the chunk loads again. Atomicity is per chunk part, not across the complete multi-chunk settlement.

Changing templates, processors, terrain policies, regional placement settings, or referenced loot tables prevents an unfinished saved plan from mixing incompatible old and new definitions. Restore the matching declaration to finish that plan; new starts use the current declarations. Completed parts are not rewritten.

regional:locate(world, x, z, maxRegions)

Available on an authoritative action-world handle. It returns the nearest candidate within the requested region radius (32 by default, maximum 128) as { x, y, z, chunkX, chunkZ, generated }. generated means a saved start plan exists; it does not mean that every intersecting chunk or entity marker has finished. y is nil until the start has been planned. Locating does not generate or load terrain.

The World content debug export includes worldgen_regional_structures.txt with distribution settings, limits, completed or recovered chunk counts, block totals, rejection reasons, and disabled state.

Example: regional structures package.