API Block State and Placement

Block state and placement

Lua API / Blocks / State and placement

On this page

• state
• placement.facing
• placement.facingFrom
• placement.attachTo
• placement.requiresSolidSupport
• placement.dropWhenUnsupported
• Face names

state

Maps field names to saved metadata definitions. Fields are allocated in sorted name order. Their encoded widths must fit in four metadata bits; enum widths round up to a whole number of bits.

state = {
    active = { type = "boolean", default = false }
}

Field	Type	Default / requirement
state.<name>.type	string	Required: boolean or enum.
state.<name>.values	list of strings	Required for enums; 2–16 distinct values. Not permitted for booleans.
state.<name>.default	boolean or enum string	False for booleans; first enum value for enums. Must belong to the field.

Use ctx.state:get(name) and ctx.state:set(name, value) from an eligible action context. Unknown fields and incompatible values are errors. Use tile data for larger persistent values.

Changing field names or enum order can change saved metadata interpretation. Keep the schema stable for existing worlds.

placement.facing

Optional string "horizontal". Requires a state.facing enum containing exactly north, east, south and west. Sets orientation when a living entity places the block. Declared collision and selection boxes use the enum's default facing and rotate with the saved facing.

state = {
    facing = { type = "enum", values = { "north", "east", "south", "west" } }
},
placement = { facing = "horizontal", facingFrom = "player" }

placement.facingFrom

Optional string; the only supported value is "player". The block's front faces the placer, like a vanilla furnace.

placement.attachTo

Optional list selecting permitted support categories: "floor", "wall", "ceiling". Defaults to all categories. An empty list allows none.

placement = { attachTo = { "floor" }, requiresSolidSupport = true }

placement.requiresSolidSupport

Boolean, default false. Requires the supporting block face to be solid before placement succeeds.

placement.dropWhenUnsupported

Boolean, default false. Drops the attached block when its support no longer satisfies the support check.

When either support option is enabled for anything beyond floor-only attachment, declare state.attachedFace as an enum containing every allowed clicked face. Floor uses up, ceiling uses down, walls use north/east/south/west. Its metadata records the attachment face.

Face names

Physical faces are down, up, north, south, west, east, corresponding to native sides 0–5. Directional redstone can additionally use relative faces when horizontal facing is configured; see Redstone.

Example: Attached blocks.