API Events

Events

Lua API / Events

On this page

• betamoon.events:on(name, callback)
• Subscription handle
• subscription:unsubscribe()
• Event catalogue
• world_join
• world_leave
• player_join
• player_leave
• gui_opened
• gui_closed
• gui_tick
• game_tick
• screen_changed
• key_input
• mouse_input
• block_broken
• block_placed
• item_used
• dimension_changed
• Input context
• Block event context
• Event item reference
• event.item:getId()
• World information

betamoon.events:on(name, callback)

Subscribes callback(event) to a named global event and returns a subscription handle. Event names are trimmed and lowercased. Unknown names or non-function callbacks raise an error. Subscriptions observe events. Lua callback errors are reported.

local subscription = betamoon.events:on("world_join", function(event)
    betamoon.chat:send("Entered %s", event.name)
end)

Subscription handle

active is true while subscribed.

subscription:unsubscribe()

Unsubscribes and changes active to false. Repeated calls are harmless. Script cleanup also unsubscribes tracked listeners.

subscription:unsubscribe()

Event catalogue

Each event below is subscribed using betamoon.events:on("event_name", callback).

world_join

A world becomes active. Context: name (world name), info (world information). Fields are absent if world information is unavailable.

world_leave

The active world is left. Same world context, describing the departing world.

player_join

Player becomes active. Context: name (username when available).

player_leave

Player leaves. Context: name (departing username when available).

gui_opened

A screen opens. Context: name (new/current screen identifier or nil), previousName (previous screen identifier or nil).

gui_closed

A screen closes. Context uses the current/previous screen names; do not assume name identifies the closed screen.

gui_tick

A GUI tick occurs. Context exposes current name and previousName where supplied.

game_tick

A game tick occurs. Context: worldName and worldInfo when world information exists; these may be absent at menus.

screen_changed

The current screen changes. Context: name and previousName; nil denotes no screen. These values are diagnostic screen identifiers rather than visible titles or stable public IDs.

key_input

Keyboard input. Uses input context.

mouse_input

Mouse input. Uses input context.

block_broken

Successful player block destruction. Uses block event context. Requires the Java agent.

block_placed

Successful placement. Uses block event context. Requires the Java agent.

item_used

Item-use notification. Context: itemId, damage, count snapshots and item (event item reference). Requires the Java agent.

dimension_changed

A player dimension transition. Context: integers oldId, newId.

Input context

Read these fields directly from the keyboard or mouse event context.

betamoon.events:on("key_input", function(event)
    if event.pressed then betamoon.chat:send("Key %d", event.keyCode) end
end)

Field	Type / meaning
type	key or mouse.
keyCode	Keyboard code; interpret for key events.
char	Character string; may contain the null character for non-character events.
button	Mouse button; interpret for mouse events.
x, y	Mouse coordinates; interpret for mouse events.
pressed, released	Boolean action flags.
action	pressed, held, or released.

Block event context

Integer x, y, z, id, damage, side; position contains coordinates. name and displayName are provided when the block can be resolved. Side uses native face numbering, not action-context face strings; it may be unavailable as a sentinel value.

Event item reference

event.item:getId()

Returns the item ID captured for an item-use event. This small event reference is not a full resource registry reference.

betamoon.events:on("item_used", function(event)
    local id = event.item:getId()
end)

World information

A snapshot of world-save information. Editing it does not edit the world.

betamoon.events:on("world_join", function(event)
    local spawn = event.info.spawnPos
end)

Field	Meaning
name	World name.
seed	World seed, represented numerically; very large seeds may lose numeric precision.
getSpawnX, getSpawnY, getSpawnZ	Integer spawn coordinates. Despite their names these are properties, not functions.
spawnPos	Spawn position with x/y/z.
worldTime	Saved world time.
lastTimePlayed	Saved last-played timestamp.
sizeOnDisk	Saved disk-size metadata.
dimension	Saved dimension ID.
saveVersion	Save format version.
raining, thundering	Weather flags.
rainTime, thunderTime	Weather timers.

Examples: All events, input.