Packets

A flushed buffer contains one or more packets laid end to end. There is no outer header and no packet count, because the receiver simply loops until the cursor reaches the end of the buffer.

while r.cursor < r.len do
	local id = Buffers.ReadString(r)
	local ptype, argCount = Buffers.ReadPacketHeader(r)
	-- read argCount arguments, dispatch, repeat
end

Packet layout

Every packet has the same three-part shape, read in this order:

Order	Segment	Encoding	Size
1	Channel name	varint length, then raw bytes	1 to 3 bytes plus the name
2	Header	packet type and argument count, bit-packed	1 byte, or 1 plus a varint
3	Payload	schema, or one tag and value per argument	varies

varint-prefixed string

The event name you passed to Flux.Server or Flux.Client, written with WriteString. This is what the dispatcher keys listener lookup on, so it is repeated in every packet. Keep names short if you send at very high frequency.

1 byte, or 1 plus a varint

A packed byte holding the packet type and the argument count. See below.

argCount values

Encoded either by the event’s schema or by the dynamic encoder, depending on packet type and whether a schema is registered.

The header byte

The two-bit packet type sits in the high bits and the argument count in the low six.

Bits	Field	Width	Holds
`7` to `6`	packet type	2 bits	`1` EVENT, `2` REQUEST, `3` RESPONSE
`5` to `0`	argument count	6 bits	`0` to `62` directly, or `63` as an escape

Bit 7 is the most significant. The type occupies the top two bits because it is written as packetType << 6, so a header for an event with two arguments is 0x42: 01 in the high bits, 000010 in the low six.

-- Write
if n < 63 then
	Buffers.WriteU8(w, bit32.bor(bit32.lshift(packetType, 6), n))
else
	Buffers.WriteU8(w, bit32.bor(bit32.lshift(packetType, 6), 63))
	Buffers.WriteVarInt(w, n)
end

-- Read
local h = Buffers.ReadU8(r)
local t = bit32.rshift(h, 6)
local c = bit32.band(h, 0x3F)
if c == 63 then c = Buffers.ReadVarInt(r) end

63 is an escape value, not a count. Counts of 0 to 62 fit in the header byte directly; a count of 63 or more writes 63 in the field and follows it with a varint carrying the real count. So the header is one byte for essentially all real traffic.

Packet types

Value	Type	Direction	Schema applied
`1`	`EVENT`	both	if registered
`2`	`REQUEST`	client to server	never
`3`	`RESPONSE`	server to client	never

Only two bits are allocated, so the format has room for one more packet type (0 is unused). Values outside 1 to 3 are ignored by both dispatchers rather than raising an error.

EVENT

The payload is the arguments you passed to Fire, in order.

name("Damage"), header(type=1, n=2), Instance, u16

If a schema is registered for the name, each argument is encoded with schema[i]. Otherwise each is tagged and encoded by WriteAny.

REQUEST

Sent by Client:Invoke. The first payload value is the request id, followed by the invoke arguments.

name("Shop"), header(type=2, n=1+argc), reqId, arg1, ... argN

The request id is a plain incrementing counter kept per channel name on the client. It is written with WriteAny, so a fresh session’s early requests cost one tag plus one byte.

RESPONSE

Sent by the server after OnInvoke returns. The first two payload values are the request id and a success flag, followed by the handler’s return values.

name("Shop"), header(type=3, n=2+retc), reqId, ok, ret1, ... retN

number

Echoed back from the request so the client can find the parked thread.

boolean

The first result of the server’s pcall. When false, the next value is the error message and Invoke re-raises it.

The client accepts true or 1 as success when reading the flag, so the encoding tolerates the boolean arriving as a narrowed integer.

A worked example

Two events fired to the same player in one frame:

Damage:Fire(player, humanoid, 250)   -- schema: { T.Instance(), T.UInt16() }
Chat:Fire(player, "gg")              -- no schema

They share one writer, so a single FireClient carries both packets back to back:

Packet	Segment	Bytes	Notes
1	`varint(6)` plus `"Damage"`	7	channel name
1	`0x42`	1	header, type `1`, argCount `2`
1	`varint(1)`	1	Instance, resolves to `insts[1]`
1	`u16(250)`	2	schema, so no type tag
2	`varint(4)` plus `"Chat"`	5	channel name
2	`0x41`	1	header, type `1`, argCount `1`
2	`TYPE_STRING`	1	dynamic tag
2	`varint(2)` plus `"gg"`	3	the string
	total	21	plus `insts = { humanoid }` alongside the buffer

Note how much of that is the channel names: 12 of 21 bytes. At high frequency, shortening "PlayerPositionUpdate" to "P" is a real saving, and one no schema can give you.

Getting Started

Guides

Concepts

Reference

Packet layout

The header byte

Packet types

EVENT

REQUEST

RESPONSE

A worked example

Next steps

Type tags

Buffers API

​Packet layout

​The header byte

​Packet types

​EVENT

​REQUEST

​RESPONSE

​A worked example

​Next steps

Type tags

Buffers API

Packet layout

The header byte

Packet types

EVENT

REQUEST

RESPONSE

A worked example

Next steps