API Structured Data

Structured data

Lua API / Structured data

Tile data, capability state/configuration, capability requests/responses, logical-network signals, and world services use the same declared data fields. Declarations are validated when the mod loads; values are validated on every write and saved automatically where the owning API is persistent.

Field definition

Every field requires type.

data = {
    owner = { type = "content_key", default = "mymod:team/neutral" },
    home = { type = "block_position" },
    samples = {
        type = "list",
        maxLength = 16,
        element = { type = "number" }
    },
    profile = {
        type = "record",
        fields = {
            enabled = { type = "boolean", default = true },
            label = { type = "string", default = "Machine" }
        }
    }
}

Type	Lua value	Default	Notes
boolean	boolean	false
integer	integer	0	32-bit signed.
number	finite number	0.0
string	string	""	At most 1024 characters.
vector	{ x, y, z }	zero vector	Finite components within world coordinate limits.
block_position	{ x, y, z, dimension? }	origin in dimension 0	Integer X/Z within world limits; Y 0–127.
item_stack	{ id, count, damage } or nil	nil	Detached stack data.
content_key	string	minecraft:air	Lowercase namespace:path.
list	array	empty	Requires element; maxLength defaults to 64 and may be 1–256.
record	table	field defaults	Requires fields.

entity_reference remains available to entity data because it needs an entity callback context. Other structured-data APIs reject it.

Structured data may nest at most four levels and one value may contain at most 4096 nodes. Record definitions allow at most 64 fields. These bounds keep saves and callbacks predictable.

Persistence and compatibility

Unknown saved fields are preserved when loading and saving data. Missing declared fields receive their defaults. An incompatible saved type makes that data store unavailable and reports an error instead of silently converting the value.

Adding a field with a compatible default is safe. Changing a field's type, narrowing a list limit, or changing nested structure requires a saved-world compatibility plan. Structural registrations still require a restart.

All tables returned as snapshots are detached. Changing them does not change the world; use the owning data access set method.