Events

module:event(name, fn) subscribes. The callback gets one table of fields, or nothing when the event has none. Names are exact snake_case strings.

Three rules cover the whole list:

Cancellable events carry :cancel().

module:event("chat", function(e)
    if e.text:find("spam") then
        e:cancel()   -- drop the message
    end
end)

Writable fields are read back after the callback. Assign one and the game uses your value.

module:event("input", function(e)
    e.jump = true    -- jump this tick
end)

The table is dead after the callback returns. Copy out what you need; do not store it.

Numbers are plain Lua numbers (integer marks the whole ones), colors are 0xAARRGGBB, and positions arrive as raw x, y, z scalars rather than vec3. Callbacks run only while the module is enabled.

Lifecycle

Event	Fires
`enable`	Module toggled on
`disable`	Module toggled off

Ticks

Event	Fields	Notes
`tick`	none	Before the player tick. Cancellable
`post_tick`	none	After the player tick
`pre_interaction`	none	Before attacks and item use are processed

Input

Event	Fields	Notes
`input`	`forward, backward, left, right, jump, sneak, sprint` — `boolean`, all writable	Cancellable. Drives player movement
`key`	`key, action, mods` — `integer`	Cancellable. GLFW key codes; mouse buttons arrive too as `0` left, `1` right, `2` middle
`char`	`char` — `string`; `codepoint, mods` — `integer`	Cancellable. Typed character
`mouse_move`	`x, y` — `number`	Cancellable
`mouse_scroll`	`horizontal, vertical` — `number`	Cancellable
`mouse_look`	`delta_x, delta_y` — `number`	Cancellable. Camera rotation by mouse
`cursor_lock`	`state` — `"lock"` / `"unlock"`	Cancellable
`slot_drag`	`slot` — `integer` (`-1` outside a slot); `button` — `integer`; `shift` — `boolean`	Cancellable

Screens

Event	Fields	Notes
`screen_open`	`type` — `string`; `title` — text; `handled` — `boolean`	Cancellable. A screen is about to open, same fields as `screen.current()`. It is not current yet and gets its widgets on the next tick
`screen_close`	none	Cancellable. The open screen is about to close. A container screen has already told the server by then, so cancelling only keeps a dead screen up

Cancelling screen_open for a server's container menu leaves the menu open without a screen: container still reads it and interaction.click_slot still clicks it.

Chat and text

Event	Fields	Notes
`chat`	`text` — `string`	Cancellable. A message arrived
`chat_send`	`text` — `string`	Cancellable. You are about to send
`title`	`text` — `string`; `kind` — `"title"` / `"subtitle"` / `"actionbar"`	A title appeared
`boss_bar`	`text` — `string`	Boss bar text changed

Combat and interaction

Event	Fields	Notes
`attack`	`target` — entity	Cancellable. Before you hit
`post_attack`	`target` — entity	After the hit
`auto_attack_target`	`target` — entity or `nil`, writable	Cancellable. Auto Attack's target for this tick
`auto_attack_rotation`	`target` — entity; `yaw, pitch` — `number`, writable	Cancellable. Auto Attack's aim before the rotation service sees it
`item_use`	`cooldown` — `integer`, writable	Cancellable. A right click; cancelling drops it before the game uses an item or a block
`block_interact`	`hand` — `"main"` / `"off"`; `x, y, z` — `integer`; `side` — `string`	Cancellable
`block_place`	`hand`; `x, y, z`; `side`; `item` — item
`block_breaking`	`state` — `"start"` / `"stop"`; `block` — block id; `x, y, z`

The two auto_attack_* events fire each interaction tick while Auto Attack is on, so you can steer it instead of replacing it:

module:event("auto_attack_target", function(e)
    if e.target and e.target:name() == "Bot" then
        e:cancel()
    end
end)

module:event("auto_attack_rotation", function(e)
    e.pitch = e.pitch - 2
end)

rotation below sits lower: it fires for every rotation the service applies, including the one Auto Attack requests here.

Movement

Event	Fields	Notes
`jump`	`yaw` — `number`; `cooldown` — `integer`; both writable	Cancellable
`land`	`x, y, z, fall_distance` — `number`	Touched the ground
`slowdown`	`multiplier` — `number`, writable	Cancellable. Slowdown while using an item
`rotation`	`yaw, pitch` — `number`, writable; `priority` — `integer`, read-only	Cancellable. Every rotation the service applies

Network

Event	Fields	Notes
`packet_send`	`name` — `string`, plus decoded fields	Cancellable
`packet_receive`	`name` — `string`, plus decoded fields	Cancellable
`packet_process`	none	Received packets applied to the world
`movement_packets`	none	After movement packets are sent
`player_packets`	none	After player packets are sent

name is the stable snake_case packet name that packets.send also accepts. Common packets carry decoded fields too; the full list is on Packets.

module:event("packet_receive", function(e)
    if e.name == "entity_velocity" and e.entity_id == player:id() then
        e:cancel()   -- ignore knockback aimed at us
    end
end)

:::caution packet_send and packet_receive run on network threads. Collect data there and act in tick; never draw or call projection from them. :::

World and modules

Event	Fields
`chunk_load`	`x, z` — `integer`, chunk coordinates
`chunk_unload`	`x, z` — `integer`
`world_change`	`dimension` — `string`. Fires on every join, reconnect, server switch and dimension change
`disconnect`	none. Fires as you leave a server or singleplayer world
`module_state`	`module` — `string`; `enabled` — `boolean`

Rendering

render_2d, render_gui and render_3d receive a drawing object instead of a field table.

Event	Fields	Notes
`frame`	none	Every frame
`render_2d`	2D canvas	Draw over the game
`render_gui`	2D canvas	Draw during GUI screens
`render_3d`	3D renderer	Draw in the world
`camera`	`x, y, z, yaw, pitch` — `number`, all writable; `tick_progress` — `number`	Camera pose each frame, after it is positioned. Free Camera moves through this event, so writing the fields overrides it too
`sky_color`	`color` — writable; `original` — the value without you
`time_of_day`	`time` — daytime ticks, writable; `original` — `integer`	Visual only
`skybox`	`rendered` — `boolean`, writable; `true` hides the vanilla sky
`fog`	`red, green, blue, alpha, environmental_start, environmental_end, render_distance_start, render_distance_end` — `number`, all writable	Color channels are `0..1`, the rest are world distances
`window_resize`	`width, height` — `integer`