API Overrides

Overrides

Lua API / Overrides

On this page

• reference:override(definition)
• betamoon.overrides:add(definition)
• Block properties
• Item properties
• Callback overrides
• ctx:base()
• Override handle
• handle:remove()

reference:override(definition)

Applies supported property or callback changes to an existing resource. Returns a handle. Use a direct change table for simple changes, or an envelope with changes, when, and priority.

local handle = betamoon.blocks:getRequired(3):override {
    changes = { displayName = "Garden Dirt" },
    when = { owner = "minecraft" },
    priority = 10
}

Field	Type	Default / meaning
changes	table	Supported property values; if omitted, the block/item definition itself is treated as the change table.
when	table	Optional registration-time conditions, not a continuously evaluated predicate.
when.owner	string	Exact owner required.
when.properties	table	Expected current inspectable values. A mismatch produces an inactive handle.
priority	integer	0; higher-priority layers win, later layers break equal-priority ties.

For block/item overrides, always use explicit changes when including when or priority; their direct shorthand is only for property changes. Recipe overrides support envelope metadata in their shorthand.

betamoon.overrides:add(definition)

Applies an override and returns its handle. Requires an override-capable reference as target; remaining fields follow that target's override contract.

local handle = betamoon.overrides:add {
    target = betamoon.blocks:getRequired(3),
    changes = { hardness = 0.8 }
}

Block properties

Supported changes: displayName, hardness, resistance, texture, light, lightOpacity, stepSound, slipperiness, unbreakable, nested fire.spread/fire.burn, and declarative drops. Texture accepts an atlas index, texture asset reference/key, or PNG path. A resistance override uses the supplied value directly.

All BlockCallback entries, including onTick and onInputChanged, and onDisplayTick may be overridden. Here onInputChanged is a top-level change name; block declarations put it inside redstone.

Item properties

Supported changes: displayName, maxStackSize, maxDamage, hasSubtypes, icon, texture, full3D, efficiency, and damageVsEntity. Icon accepts an integer or { x, y }; texture accepts an index, texture asset reference/key, or PNG path. See Assets. Food additionally accepts healing and wolfFood.

Every item callback can be overridden. These are override capabilities, not the same as declaration field support.

Callback overrides

Use { action = function(ctx) ... end }. A bare function is also accepted by definition-based targets. Inventory tick overrides accept interval (1–1000000, default 1) and when (always/ selected, default always). onDisplayTick accepts chance (0–1) and attempts (1–64) together with its action.

Tick/display overrides follow the content's normal cadence. Callback overrides on existing Minecraft or mod content require the Java agent.

ctx:base()

Calls the next lower active callback layer, or the original behavior at the bottom, at most once. For query and interaction callbacks it returns that lower result. Calling twice or after the callback raises an error.

local handle = betamoon.blocks:getRequired(3):override {
    onClick = { action = function(ctx)
        ctx:base()
        betamoon.chat:send("Clicked dirt")
    end }
}

For notification overrides, call base explicitly to preserve lower behavior. Query nil results and interaction pass/nil results fall back automatically. If base already ran, its cached result is reused. A failing callback layer is isolated so lower behavior remains available.

Other override-capable references

The same handle, priority, ownership, removal, and ctx:base() rules apply to these registries:

Target	Overridable behavior
Native recipes	Shaped pattern/key, shapeless ingredient list, smelting input, output, and enabled state. Unknown third-party recipe types retain output/enabled only.
Sound events	Clips/weights, volume, pitch, range, and enabled state.
BetaMoon entity types	Non-structural body/render/sound/physics/behavior/drop and kind-specific groups, size/name/cadence, and supported lifecycle callbacks. Persistent schemas, key, and kind remain structural.
Ore rules	Enabled state, generated/replaced blocks, vein counts/sizes, height, dimension, and biome filter. Only future chunk generation is affected.
Biomes	Name/colors, surface, weather, spawns, and supported BetaMoon climate/tree settings.
Fuel registrations/sets	Burn time/enabled state; a set's complete include list.
Container GUIs	Complete validated presentation replacement; container schemas and controls are unchanged.
Tile entities	onTick, tick mode/cadence, and onInventoryChanged; inventory/data/capability schemas remain fixed.
Containers	onClose and callbacks of already declared controls; slot/session/control schemas remain fixed.
Capabilities	Implementations of already declared operations; operation/state/request/response schemas remain fixed.
World services	onLoad, onTick, onUnload, and tickInterval; persistent data schema remains fixed.
Logical networks	canConnect, onTick, onPulse, and tickInterval; topology/capability/signal schemas remain fixed.

Each registry page documents its lookup fields and target-specific change table.

Override handle

Field	Meaning
target	Target reference.
active	Whether the layer remains active. This is not a guarantee it wins over higher-priority layers.
reason	Explanation when a conditional override is inactive, when provided.
remove	Removal method on active resource handles and recipe handles.

handle:remove()

Removes the layer and restores the next effective value. Repeated removal is harmless. Inactive block/item condition handles may not expose this method; check active first.

if handle.active then handle:remove() end

Reload cleans up tracked owned overrides automatically. Removing one layer does not remove other scripts' layers. See bulk overrides and recipe overrides.

Example: Conditional and prioritized overrides.