Packet Handlers

Intercept and inspect incoming and outgoing packets.

Important

Blocking essential packets can cause disconnections. Test thoroughly before production use.

Callbacks

on_packet_recv(packet: in_packet) -> boolean

Called when receiving packets from the server. Return true to allow, false to block.

on_packet_send(packet: in_packet) -> boolean

Called when sending packets to the server. The packet is provided as an in_packet for read-only decoding (same type as on_packet_recv). Return true to allow, false to block.

Plugin Required

Must be part of a plugin with proper metadata structure.

Packet Methods

packet:get_opcode() -> number

Returns the packet opcode.

packet:decode_1() -> number

Reads 1 byte (0-255).

packet:decode_2() -> number

Reads 2 bytes (0-65535).

packet:decode_4() -> number

Reads 4 bytes (0-4294967295).

packet:decode_8() -> integer

Reads 8 bytes as an unsigned 64-bit value, returned as a Luau integer (int64). See Luau Notes › 64-bit packet integers for comparison/arithmetic caveats.

packet:decode_string() -> string

Reads a string.

packet:decode_buffer(size: number) -> buffer | nil

Reads size bytes and returns them as a native Luau buffer, or nil if not enough data remains.

packet:get_length() -> number

Returns the total packet length in bytes.

packet:get_offset() -> number

Returns the current read offset.

packet:set_offset(offset: number)

Sets the current read offset when offset is between 0 and packet:get_length().

INFO

Decode methods read sequentially. Each call advances the read position.

Example

plugin = {
    name = "Packet Logger",
    author = "YourName",
    version = "1.0",
    description = "Logs packet opcodes",
    load = true
}

function on_packet_recv(packet)
    local opcode = packet:get_opcode()
    core.log(string.format("[IN]  0x%04X", opcode))
    return true
end

function on_packet_send(packet)
    local opcode = packet:get_opcode()
    core.log(string.format("[OUT] 0x%04X", opcode))
    return true
end