API Blocks

Blocks

Lua API / Blocks

On this page

• betamoon.blocks:add(definition)
• Field definitions
  • Identity and physical properties
  • Presentation
  • drops
  • Structural attachments
  • Callbacks
• Block lookup
• Block references and overrides
• Errors and reload

betamoon.blocks:add(definition)

Creates and registers a block from a required declaration table. Returns a block reference. Use type = "fluid" only with an unpublished token from the advanced fluid API; fluid-owned fields follow that specialized contract instead of the ordinary fields below.

local slate = betamoon.blocks:add {
    id = 200, key = "mymod:block/slate", displayName = "Slate",
    material = betamoon.mc.blockMaterials.rock,
    hardness = 1.5, texture = 1
}

Field definitions

Identity and physical properties

Field	Type	Default / behavior
id	integer	Required. Use an unused ID 1–255; zero is air.
key	string	Recommended internal identity field; one of internalName, name, key required.
internalName	string	Takes precedence over name and key.
name	string	Identity alias, preferred over key when both are supplied.
displayName	string	Defaults to resolved internal name.
material	string	Required block material.
hardness	number	Mining resistance; omitted leaves the block default.
resistance	number	Explosion resistance passed to the block setter; omitted leaves default.
unbreakable	boolean	Default false; makes the block unbreakable through ordinary mining.
light	integer	Emitted light setting; use 0–15. Omitted leaves default.
lightOpacity	integer	Light blocking; omitted leaves native default.
stepSound	string	Step sound; omitted leaves native default.
harvest	map of tool-class strings to integers	Required harvest levels, e.g. { pickaxe = 2 }.
replaceable	boolean	Default false; permits replacement by placement.
climbable	boolean	Default false; provides ladder-like climbing behavior.
opaque	boolean	Omitted uses normal block behavior; set explicitly when needed.
normalCube	boolean	Defaults from collision and ordinary rendering settings; model appearances do not change it.
slipperiness	number	Default 0.6; range 0–1.
piston.reaction	string	move (ordinary default), destroy, or block. Tile blocks require block.
fire.spread	integer	Required when fire exists; 0–300. Fire encouragement.
fire.burn	integer	Required when fire exists; 0–300. Burn susceptibility.

state and placement are in State and placement.

Presentation

Field	Meaning
texture, textures	Base and per-face textures.
render	Rendering presets, bounds, and variants.
appearance	Optional model appearance with textures, clips, and pose callbacks. May be replaced by render.variants[metadata].appearance.

drops

drops replaces normal block drops. It accepts legacy shorthand entries, one registered loot table, or inline loot pools. An empty legacy list means no drops.

-- Inside a block declaration:
drops = {
    { item = 4, min = 1, max = 3, chance = 0.5 }
}

-- Reuse a loot table registered from Lua or a JSON asset:
drops = { table = "mymod:common_drops" }

-- Or use the same pool format inline:
drops = {
    pools = {
        {
            key = "main",
            rolls = 1,
            entries = {
                { type = "item", weight = 3, stack = { item = 4 } },
                { type = "empty", weight = 1 }
            }
        }
    }
}

Field	Type	Default / restriction
item	integer or reference	Required registered item/block identity; a block may reference itself.
min	integer	1; range 0–64. For a static block declaration, explicitly supplying min also requires max.
max	integer	Dynamic drop entries default to min; 0–64 and at least min. Supply both bounds in static declarations.
chance	number	1; range 0–1, multiplied by engine drop chance.
damage	integer	0; range 0–32767.

Legacy counts and chances are sampled independently when drops are requested. Loot-table and inline-pool forms use the complete loot-table pool syntax and take a fresh sample from the world's runtime RNG for every request. An explosion's engine drop chance is applied independently to each stack emitted by the table. See getDrops for dynamic drops; it accepts the same three forms.

Structural attachments

Field	Type	Meaning
tileEntity	tile handle	Adds saved per-position data and inventory.
container	container handle	Connects the tile inventory to a player-facing container.
gui	GUI handle	Container screen definition.
redstone	table	Redstone input/output configuration.

Structural handles must have compatible relationships and ownership. See Tile entities and Containers. Structural content requires restart after changes.

Callbacks

The complete callback catalogue is in Block callbacks;
onTick and onDisplayTick have their own tick reference.

Block lookup

Use betamoon.blocks:get, getRequired, find, first, or one to retrieve block references. See References and stacks for the method contracts and query fields.

Block references and overrides

Block references expose the block's live properties and support layered changes through reference:override(definition). See References and stacks for the reference properties and override behavior.

Errors and reload

Missing identity/material, unknown material or sound, occupied IDs and invalid nested definitions fail registration. Compatible owned block identities can be retained during reload; changing the material or saved state schema may require restart. Retained identity is not permission to reuse another script's ID.

Example: Simple block.