KAWAKI DOCS / LUA · GAME

Packets

The packets global sends; the packet_send and packet_receive events observe. Fields mirror the wire format, so coordinates arrive as raw x, y, z scalars rather than vec3.

module:event("packet_receive", function(e)
    if e.name == "sound" then e:cancel() end   -- mute server-played sounds
end)

Packets are matched by stable snake_case names, the same strings e.name reports and packets.send accepts. Every vanilla packet is mapped, in every protocol phase (handshake, status, login, configuration, play); only a packet a mod adds arrives under its protocol id (a name with a colon) carrying no decoded fields, still cancellable. Ids are strings ("minecraft:stone"), uuids are strings, enums are lowercase names, text components arrive as plain strings and lists are 1-based arrays.

packets.send raises on an unknown name and returns false when a required game object is missing. It goes through the normal client pipeline, so it fires packet_send as well: a module that cancels its own scripted packets swallows them.

local pos = player:position()
packets.send("move_position", { x = pos.x, y = pos.y + 0.05, z = pos.z, on_ground = false })
packets.send("client_command", { mode = "start_sprinting" })
packets.send("player_action", { action = "swap_item_with_offhand", x = 0, y = 0, z = 0 })

local target = world:player("Notch")
if target then
    packets.send("attack_entity", { entity_id = target:id() })
end

For attacking, breaking blocks and clicking slots, interaction is the better tool: it gets swing timers and sequence numbers right. Raw packets are for when you want the wire format yourself.

Sendable packets

Optional fields show their defaults. hand is "main" / "off" (default "main"), side is "up" · "down" · "north" · "south" · "east" · "west" (default "up"), and sequence defaults to 0.

Decoded event fields

Both events always carry name. A ? marks a field that is only present when the packet carries it; x/y/z stands for the three scalars (vel_x/y/z for vel_x, vel_y, vel_z).

Outgoing. Sendable packets decode with the same fields they take, except that move_* carry x/y/z only when the position changed and yaw/pitch only when the look changed, interact_entity_at arrives as interact_entity (entity_id, hand, x/y/z, sneaking), container_click adds changed (predicted slot count) and carried_item?/carried_count?, custom_payload carries channel and brand?, and cookie_response carries key, size?. These go out too but cannot be built, because they are signed or belong to a phase without a game connection:

Incoming.

Light

light_update and level_chunk_with_light carry the chunk's light the way the server sent it.

A mask is a list of bit numbers, and bit i is section world:min_section() - 1 + i: light sections reach one past each end of the chunk column. sky_light[k] is the light of section bit sky_mask[k]. Each string packs one 0–15 level per block, local block x, y, z at nibble y * 256 + z * 16 + x, low half of the byte first:

local function light_at(data, x, y, z)
    local nibble = y * 256 + z * 16 + x
    local byte = data:byte(bit32.rshift(nibble, 1) + 1)
    return bit32.band(bit32.rshift(byte, bit32.band(nibble, 1) * 4), 15)
end

local lit = {}

module:event("packet_receive", function(e)
    if e.name ~= "light_update" and e.name ~= "level_chunk_with_light" then return end
    for k, bit in ipairs(e.block_mask) do
        if light_at(e.block_light[k], 8, 8, 8) > 0 then
            lit[#lit + 1] = { x = e.x, z = e.z, section_bit = bit }
        end
    end
end)

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