API World Services and Data

World services and data views

Lua API / World services and data views

World services hold declared data once per saved world and run scheduled coordination outside individual blocks. World data views expose bounded, detached information through callback ctx.world. Service declarations are structural and require a restart after changes.

Ticks follow actual local-world simulation updates and stop during pausing screens. Non-pausing screens continue them. Remote client worlds do not run authoritative services/networks. The Java agent is required for the simulation driver. Intervals count actual updates from runtime initialization, independently of world-time changes; counters reset when that runtime is recreated. See tick timing.

betamoon.systems:add(definition)

Registers a structural world service with persistent data and optional lifecycle callbacks.

local clock = betamoon.systems:add {
    key = "mymod:system/clock",
    data = { seconds = { type = "integer", default = 0 } },
    tick = { interval = 20 },
    onTick = function(ctx)
        ctx.data:set("seconds", ctx.data:get("seconds") + 1)
    end
}

Field definitions

Field	Meaning
key	Required namespace:system/name.
data	Optional persistent structured fields.
tick.interval	Optional interval from 1–1200 ticks; required with onTick.
onLoad(ctx)	Called when the gameplay world runtime loads.
onTick(ctx)	Called on matching world ticks.
onUnload(ctx)	Called before the runtime releases the world.

Service callbacks

Service context contains key, world, and persistent data:get/set/snapshot. A callback failure disables that service runtime and reports one error. World services and logical-network gameplay callbacks run in integrated singleplayer worlds and do not run on dedicated servers.

Service lookup

Method	Result
betamoon.systems:get(key)	Service reference, or nil when absent.
betamoon.systems:getRequired(key)	Service reference; raises an error when absent.
betamoon.systems:find(query)	Result list filtered by optional key and owner.
betamoon.systems:first(query)	First match, or nil.
betamoon.systems:one(query)	Sole match, nil for none, or an error for multiple matches.

Service reference

A live reference exposes key, owner, exists, and tickInterval.

service:override(definition)

Changes onLoad, onTick, onUnload, and tickInterval. Callback layers can call ctx:base() once to invoke the next lower layer. The persistent data schema remains structural. Removing the returned handle restores the next lower behavior.

ctx.world:getSystemData(system)

Returns a detached table containing a registered service's current declared data, or nil when unavailable. It is read-only; service callbacks own mutations.

World information

ctx.world:getInfo() returns a detached snapshot. It contains the common world-information fields plus:

Field	Meaning
day	Complete elapsed Minecraft days.
timeOfDay	Current time within the day, from 0 through 23999.
celestialAngle	Current normalized celestial angle used by the world.
daytime	Whether the current sky state counts as daytime.
difficulty	Native difficulty setting, from 0 through 3.
height	Build height; 128 in the supported Minecraft version.

Block, tile, biome, and chunk views

These calls accept a position table where shown; numeric forms remain available.

Method	Result
getBlockView(position) / (x,y,z)	Rich block/material/light/power snapshot, or nil when unloaded.
getTile(position) / (x,y,z)	Tile class/validity, detached BetaMoon data and up to 256 inventory slots, plus getNbt; nil when absent/unloaded. inventoryTruncated marks larger inventories.
getBiomeData(position) / (x,z)	Name, colors, surface IDs, weather flags, temperature, humidity.
getChunk(position) / (x,z)	Loaded chunk coordinates/bounds and bounded counts; nil when unloaded. Inputs are block coordinates.

These methods do not load terrain.

Block view

getBlockView returns:

Field	Meaning
position	Detached integer { x, y, z }.
id, damage	Numeric block ID and metadata.
solid	Whether the block is a normal solid cube.
canSeeSky	Whether the position has an unobstructed sky view.
powered	Whether the position receives indirect redstone power.
light	Combined block-light value.
hasTile	Whether a tile entity is present.
material	Detached { liquid, solid, burning, translucent, mobility } material properties.

Tile view

getTile returns:

Field	Meaning
position	Detached integer { x, y, z }.
className	Tile class name for diagnostics.
valid	Whether the tile is still valid.
type	BetaMoon tile type name when this is a BetaMoon tile; otherwise absent.
data	Detached declared BetaMoon data when available; otherwise absent.
inventorySize	Native inventory size when the tile implements an inventory; otherwise absent.
inventory	One-based detached stack table for up to the first 256 native slots; empty slots are nil.
inventoryTruncated	True when the native inventory has more than 256 slots; otherwise absent.

tile:getNbt() captures the tile's current bounded NBT view. It returns nil if the tile was removed, replaced, or invalidated before capture.

Biome view

getBiomeData returns:

Field	Meaning
name	Biome display name.
color	Integer biome color.
topBlockId, fillerBlockId	Numeric surface and filler block IDs.
snow, rain	Current biome weather flags.
temperature, humidity	Climate values at the supplied coordinates.

Biome lookup does not require a loaded chunk and does not load one.

Chunk view

getChunk accepts block coordinates and returns:

Field	Meaning
x, z	Chunk coordinates.
minX, maxX, minZ, maxZ	Inclusive block-coordinate bounds.
loaded	Native loaded-state flag on the returned chunk.
terrainPopulated	Whether terrain population has completed.
modified	Whether the chunk is marked as modified.
lowestHeight	Native cached lowest block height.
entityCount	Current number of loaded entities in all vertical chunk slices.
tileCount	Current number of tile entities in the chunk.

ctx.world:getPlayers(options)

Returns up to limit loaded players within radius, sorted nearest-first. Coordinates default to the callback origin. Radius is greater than zero and at most 128; limit is 1–128. Returned live entity handles expire with the callback.

NBT view

tile:getNbt() captures bounded detached NBT while the callback remains active. The view supports:

• has(key) returns whether the compound contains the key;
• keys() returns a sorted detached list of keys;
• getType(key) returns "byte", "short", "integer", "long", "float", "double", "byte_array", "string", "list", "compound", or nil when absent;
• get(key) returns the detached value without requiring a type;
• getString(key), getNumber(key), getBoolean(key), getCompound(key), and getList(key) return nil for an absent key and raise an error when an existing tag has an incompatible type.

getNumber accepts every numeric NBT type. getBoolean accepts a byte and treats zero as false and any nonzero value as true. Compounds are returned as nested NBT views. Lists and byte arrays are returned as one-based detached Lua tables; compound entries inside a list remain NBT views.

local nbt = tile:getNbt()
if nbt and nbt:has("CustomName") then
    local name = nbt:getString("CustomName")
    local inventory = nbt:getList("Items")
end

NBT views are read-only and limited to 8 levels, 8,192 captured values, 1,024 entries per list, 4,096 characters per string, and 4,096 entries per byte array. Exceeding a bound makes capture fail with an error. NBT is intended for inspection and interoperability; a stable mod API should prefer declared data and capability operations.

Example: World service and data views.