API Item Callbacks

Item callbacks

Lua API / Items / Callbacks

Each callback is an optional table with action = function(ctx) ... end. Use the item action context, except harvest and mining-speed queries, which use the small query context documented below. Overrides expose ctx:base() and require the Java agent on existing Minecraft or mod content.

On this page

• Interaction outcomes
• onUseFirst
• onUseOnBlock
• onUse
• onUseOnEntity
• onHitEntity
• onBlockDestroyed
• onCrafted
• canHarvest
• getMiningSpeed
• onInventoryTick

Interaction outcomes

Return	Effect
"pass" or nil	Continue normal handling/fallback.
"handled"	Complete the interaction successfully.
"deny"	Refuse the interaction and suppress applicable fallback use.

Booleans are invalid interaction results. Handler exceptions or invalid results are reported and disable the handler for the current registration.

Prefer the read-only betamoon.callbackResults.pass, .handled, and .deny constants in callback code. The literal strings in the table remain accepted.

onUseFirst

Runs before the targeted block's normal activation. Receives a block target. Mutable context; return an interaction outcome. A handled result intercepts activation.

onUseFirst = { action = function(ctx)
    return betamoon.callbackResults.pass
end }

onUseOnBlock

Handles use against a block after earlier first-use/block handling permits item use. ctx.target.kind is "block"; position and face identify the clicked target. Return an interaction outcome.

onUseOnBlock = { action = function(ctx)
    return ctx.target.block:rotate("clockwise")
        and betamoon.callbackResults.handled
        or betamoon.callbackResults.pass
end }

onUse

Handles ordinary/fallback right-click use. Target is normally "miss"; use ctx:rayTrace() to explicitly inspect a block ahead. Return an interaction outcome.

onUse = { action = function(ctx)
    return betamoon.callbackResults.handled
end }

onUseOnEntity

Handles interaction with an entity. ctx.target.kind is "entity", ctx.target.entity and ctx.entity expose it. Mutable context; return an interaction outcome.

onUseOnEntity = { action = function(ctx)
    return betamoon.callbackResults.pass
end }

onHitEntity

Notifies a successful hit using this item. Adds target entity access. Mutable context.

onHitEntity = { action = function(ctx)
    local isPlayer = ctx.entity:isPlayer()
end }

onBlockDestroyed

Notifies destruction of a block using this item. Includes integer blockId for the destroyed block. Mutable context.

onBlockDestroyed = { action = function(ctx)
    betamoon.chat:send("Destroyed %d", ctx.blockId)
end }

onCrafted

Notifies crafting this item. Uses item context with player/stack where available. Mutable context.

onCrafted = { action = function(ctx)
    betamoon.chat:send("Crafted item %d", ctx.stack.id)
end }

canHarvest

Queries whether the item can harvest a block. Return boolean or nil for the material/tool fallback. Context fields are itemId and block = { id, damage }; no world/player/stack live access is provided.

canHarvest = { action = function(ctx)
    if ctx.block.id == 49 then return true end
    return nil
end }

getMiningSpeed

Queries mining speed for a block. Same query context as canHarvest. Return a finite number 0–100000, or nil for normal speed. Invalid results fall back and disable the handler.

getMiningSpeed = { action = function(ctx)
    if ctx.block.id == 1 then return 8 end
    return nil
end }

onInventoryTick

Runs for stacks in an inventory at the configured interval.

onInventoryTick = {
    interval = 20, when = "selected",
    action = function(ctx)
        local count = ctx.stack:getCount()
    end
}

Field	Type	Default / meaning
action	function(ctx)	Required callback.
interval	integer 1–1000000	1 tick; filters world tick cadence.
when	string	always or selected; default always.

Adds slot (native inventory slot index), selected (boolean), and entity (inventory holder). Player access exists only for a player holder.

Examples: Item interactions, targeted actions, tool queries.