Violet

Appearance

In Packet ​

The in_packet object represents incoming packet data. Provided by the system in packet handler callbacks.

System-Provided Only

Cannot create in_packet objects manually. Only available in on_packet_recv and on_packet_send callbacks. Both callbacks receive in_packet objects for read-only decoding.

Methods ​

packet:get_opcode() -> number ​

Returns the packet opcode.

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

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) to preserve the full bit pattern. This is a distinct numeric type from regular number — see Luau Notes › 64-bit packet integers for comparison/arithmetic caveats.

packet:decode_string() -> string ​

Reads a length-prefixed string.

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

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

Access bytes through the buffer library rather than table indexing:

lua
local buf = packet:decode_buffer(16)
for i = 0, buffer.len(buf) - 1 do
    local byte = buffer.readu8(buf, i)  -- 0-indexed, unlike table access
    core.log(string.format("byte[%d] = 0x%02X", i, byte))
end

buffer is mutable, byte-addressable, and avoids the allocation cost of a Lua table per byte. Pass it straight to out_packet:encode_buffer to forward the bytes untouched.

packet:get_length() -> number ​

Returns the total packet length in bytes.

packet:get_offset() -> number ​

Returns the current read offset position.

packet:set_offset(offset: number) ​

Sets the read offset to a specific position. Allows rewinding to re-read data.

Sequential Reading

Decode methods maintain an internal offset. Each read advances the position. Use set_offset() to rewind if you need to re-read data.

Example ​

lua
function on_packet_recv(packet)
    local opcode = packet:get_opcode()

    if opcode == 0x1234 then  -- Replace with actual opcode
        local player_id = packet:decode_4()
        local x_pos = packet:decode_2()
        local y_pos = packet:decode_2()

        core.log(string.format("Player %d at (%d, %d)",
            player_id, x_pos, y_pos))
    end

    return true
end