Blocks API

Mods register new block types and read existing ones through the blocks library.

Constants: render mode

Defines a block rendering step.

Constants: block face

Defines a block face used for culling and other grid-aligned operations.

Constants: tool conditionals

Defines a tool category used for block interactions.

Constants: touch responses

Defines a touch response for a block.

Constants: category bits

Freeform grouping tags checked at runtime with blocks.has_tag. Any block can carry any number of tags via the tags registration field.

Constants: schedule source

A scheduled tick is issued non-randomly with a specific timeout. Scheduled ticks can come from different sources.

Constant: null block

blocks.NULL_BLOCK is an empty, undefined, or otherwise invalid block ID. Treat it as a void block for gameplay and gamedev.

Functions

Function: blocks.get(name) -> integer

Retrieves a numeric block stem ID from a namespaced block ID.

Arguments

• name is a namespaced block ID, eg. mymod:coolblockname

Return value

• Numeric block ID on success
• blocks.NULL_BLOCK if the block is missing or the namespace ID is malformed

Notes

• If a block defines states and variants, the return value is a stem ID. The engine does not render, collide with, or raycast a stem placed in the world.

Function: blocks.has_tag(id, tag) -> boolean

Checks if a block has a specified tag.

Arguments

• id is a numeric block ID
• tag is a tag constant, eg. blocks.TAG_SOIL

Return value

• true if the block has the specified tag, false otherwise

Function: blocks.is_replaceable(id) -> boolean

Checks if a block ID can be overwritten without breaking it first (empty cell, or replaceable = true at registration).

Arguments

• id is a numeric block ID (stem or variant), or blocks.NULL_BLOCK for an empty cell

Return value

• true if another block may occupy the cell, false otherwise

Function: blocks.add(name, def) -> integer

Function: blocks.add(name, prototype, def) -> integer

Registers a new block in the registry.

Arguments

• name is a namespaced block ID, eg mymod:coolblockname
• def is a block definition table (see below)
• prototype (3-argument form) is a base definition shared across a family of blocks (eg. all stone variants). def merges on top of prototype. On conflict, fields in def win.

Return value

Returns the numeric block ID.

Notes

Rename rule: on conflict, the engine adds a ~N suffix to the encroaching name. N is the smallest integer, starting at 1, that gives a free id (e.g. mymod:myblock~1). Loading stays deterministic for the same mod list and order.

Block definition

Textures

Albedo

Each texture slot is a list of textures. The engine uses them as position-randomized variations, or as animation frames when animated is true.

Masks

Each texture slot can have a mask texture that the engine uses for certain purposes. Each color channel of an RGBA mask texture can drive per-face logic, and more channels will gain this role in the future.

Facing rotation

model_facing and bcoll_facing each define one 90-degree-step rotation of the whole model or collision shape. They set where the north face of the model points. By default, the north face points world north.

Value	Rotation	Image
blocks.FACE_NORTH	None
blocks.FACE_SOUTH	180 degrees around Y
blocks.FACE_EAST	+90 degrees around Y
blocks.FACE_WEST	-90 degrees around Y
blocks.FACE_TOP	-90 degrees around X
blocks.FACE_BOTTOM	+90 degrees around X

Drops table

drops = {
  {
    when = { effects = { "silk_touch" } },
    items = {
      { name = "stone", count = 1 }
    }
  },
  {
    -- entries without a `when` always match; put fallback
    -- entries last since matching stops at the first hit
    items = {
      { name = "cobblestone", count = 1 }
    }
  }
}

The engine evaluates entries top to bottom. The first entry whose when clause matches (or that has no when) supplies the drops. The engine ignores later entries.

States table

states = {
  <state_name> = {
    default = "<default_state>",
    hint = { "<value_a>", "<value_b>", ... }  -- optional
  }
}

Blockstate values are hashed strings. You can write any value via world.sset. hint does not restrict this at runtime; hint is only a registration-time cross-check. The engine checks every when clause across the variants of this block against the union of hint lists for the states it references. A value missing from hint produces a console warning at load time (typo protection, e.g. orientation = "bottum"). Blocks that omit hint for a state skip validation for that state.

State object

Variants

variants = {
  {
    when = { <state_name> = "<state_value>" },
    overrides = {
      model_name = "slab_top",
      bcoll_offset = { 0, 8, 0 },
      health = 2,
      replaceable = true,
      drops = { ... }
    }
  }
}

overrides is a table of registration fields (same shape as the top-level definition). It merges on top of the base definition of the block when when matches the current blockstate values.

Target table

Some callbacks pass a target table for the block the initiator looked at (the raycast hit). In on_place, this is the block adjacent to the placement cell.

Occupant table

The on_place handler receives an occupant table for the block currently in the placement cell.

on_place handler

on_place = function(bx, by, bz, target, occupant, actor)
  if not occupant.replaceable then
    return nil -- cell is occupied by a non-replaceable block
  end

  -- permits placement with these initial states
  return { <state_name> = "<state_value>", ... }
end

Returning nil blocks placement. Returning a table (empty or not) permits it. Table entries become initial blockstate values for states not covered by their default.

When placement is permitted, the new block overwrites whatever was in the cell. The engine does not break replaceable occupants, and they do not drop items.

on_break handler

on_break = function(bx, by, bz, actor)
  -- Actions to do before the block is broken
end

on_interact handler

on_interact = function(bx, by, bz, target, actor)
  -- Actions to do when someone interacts with the block
end

on_tick handler

on_tick = function(bx, by, bz, source)
  -- Actions to do when the block is ticked via scheduling
  -- source is one of blocks.TICK_XXXX constants
end