Buffers

This module is internal. It is documented so you can reason about how Flux behaves and performs, but it is not re-exported from the root Flux module and its surface may change without notice. For everyday use, reach for Flux.Server and Flux.Client.

local Buffers = require(ReplicatedStorage.Flux.Utils.Buffers)

All wire I/O lives here. Compiled with --!strict --!native --!optimize 2, and every buffer and bit32 function is localised at the top of the module.

This is the one internal module you have a legitimate reason to touch, because writing a custom schema type means calling these primitives directly.

Types

export type Writer = {
	buff: buffer,
	cursor: number,
	len: number,
	insts: { Instance },
	instIndex: { [Instance]: number },
}

export type Reader = {
	buff: buffer,
	cursor: number,
	len: number,
	insts: { Instance },
}

buffer

The backing store. Reassigned on the writer when it grows.

number

Current byte offset. Advanced by every read and write.

number

On a writer, the allocated capacity. On a reader, the buffer’s actual length, used as the loop bound when decoding a batch.

{ Instance }

The side array carrying instance references out of band.

{ [Instance]: number }

Writer only. Reverse lookup for deduplicating repeat references.

Lifecycle

CreateWriter / CreateReader

function Buffers.CreateWriter(capacity: number?): Writer
function Buffers.CreateReader(buff: buffer, instances: { Instance }?): Reader

Both take from a free list before allocating. capacity defaults to ALLOC_SIZE (4096) and is ignored when a pooled writer is available.

FreeWriter / FreeReader

function Buffers.FreeWriter(w: Writer): ()
function Buffers.FreeReader(r: Reader): ()

Resets the object and returns it to the pool. FreeWriter zeroes the cursor and clears both instance tables. A writer whose capacity exceeded MAX_REUSE_SIZE (64 KB) is discarded rather than pooled.

Using a writer or reader after freeing it corrupts whichever send is holding it next. If you write a custom type, never call these, because the writer belongs to the Bridge.

Finalize

function Buffers.Finalize(w: Writer): (buffer, { Instance })

Copies the used cursor bytes into an exactly-sized buffer and clones the instance array. Returns both, ready to pass to a remote.

The copy is necessary because the writer’s backing buffer is about to be reused. This is the only allocation steady-state Flux performs, and it is unavoidable, since the remote needs a buffer it owns.

Growth

local function Resize(w: Writer, needed: number)
	local newLen = w.len
	while w.cursor + needed > newLen do
		newLen = newLen * 2
	end
	-- allocate, copy w.cursor bytes, reassign
end

Capacity doubles until the pending write fits. Every public Write* checks cursor + size > len first, so overflow is impossible.

Primitives

Each pair reads and writes a fixed width, advancing the cursor by that many bytes.

Write	Read	Bytes	Range
`WriteU8`	`ReadU8`	1	`0` to `255`
`WriteU16`	`ReadU16`	2	`0` to `65,535`
`WriteU32`	`ReadU32`	4	`0` to `4,294,967,295`
`WriteI8`	`ReadI8`	1	`-128` to `127`
`WriteI16`	`ReadI16`	2	`-32,768` to `32,767`
`WriteI32`	`ReadI32`	4	`-2^31` to `2^31-1`
`WriteF32`	`ReadF32`	4	about 7 digits
`WriteF64`	`ReadF64`	8	lossless
`WriteBool`	`ReadBool`	1	`u8`, reads as `== 1`

These delegate straight to buffer.write*, which does not validate. Out-of-range values silently truncate to the low bits, and non-integers truncate toward zero.

Varints

function Buffers.WriteVarInt(w: Writer, v: number): ()
function Buffers.ReadVarInt(r: Reader): number

LEB128-style: seven payload bits per byte, high bit set to continue. Unsigned only.

Value	Bytes
`0` to `127`	1
`128` to `16,383`	2
`16,384` to `2,097,151`	3

Strings and buffers

function Buffers.WriteString(w: Writer, v: string): ()
function Buffers.ReadString(r: Reader): string

function Buffers.WriteBuffer(w: Writer, v: buffer): ()
function Buffers.ReadBuffer(r: Reader): buffer

Both write a varint length followed by raw bytes. WriteString uses buffer.writestring, so binary content is safe and lengths are in bytes rather than characters.

Roblox datatypes

Pair	Encoding	Bytes
`WriteVector2` / `ReadVector2`	2 `f32`	8
`WriteVector3` / `ReadVector3`	3 `f32`	12
`WriteCFrame` / `ReadCFrame`	position plus axis-angle, 7 `f32`	28
`WriteColor3` / `ReadColor3`	3 `u8`	3
`WriteUDim` / `ReadUDim`	`f32` plus `i32`	8
`WriteUDim2` / `ReadUDim2`	2 UDim	16
`WriteRegion3` / `ReadRegion3`	CFrame plus Vector3	40
`WriteInstance` / `ReadInstance`	varint index	1 to 3
`WriteEnum` / `ReadEnum`	`"Enum.X.Y"` string	1 plus len
`WriteBrickColor` / `ReadBrickColor`	`u16` of `.Number`	2
`WriteTweenInfo` / `ReadTweenInfo`	3 `f64`, 2 enums, `bool`	about 50

WriteUDim, WriteUDim2, WriteRegion3, WriteBrickColor, WriteTweenInfo and WriteBuffer are reachable only through WriteAny, because the Types namespace has no constructor for them. Call them directly from a custom type if you need them under a schema.

Three of these are lossy in ways worth knowing.ReadCFrame rebuilds with CFrame.fromAxisAngle(axis, angle) + pos, which is not bit-exact and is degenerate for zero rotation. ReadColor3 quantises to 8 bits per channel with a downward floor bias. ReadRegion3 rebuilds axis-aligned from position plus or minus half the size, discarding the original CFrame’s rotation entirely.See Serialization.

Instance handling

function Buffers.WriteInstance(w: Writer, v: Instance): ()
function Buffers.ReadInstance(r: Reader): Instance?

WriteInstance appends to w.insts, or reuses the existing w.instIndex[v], and writes a varint index. Nothing about the instance enters the buffer.

ReadInstance returns r.insts[idx], which is nil whenever the receiver cannot see the instance. Note the return type is Instance? while Types.Instance() is typed Type<Instance>, so the non-optional annotation is optimistic. Always nil-check.

Enum caching

WriteEnum memoises tostring(item) in EnumCache, and ReadEnum memoises the reverse in StringToEnumCache, resolving cache misses by splitting on . and indexing Enum. An unresolvable name returns nil rather than erroring.

Packet header

function Buffers.WritePacketHeader(w: Writer, packetType: number, n: number): ()
function Buffers.ReadPacketHeader(r: Reader): (number, number)

Packs a two-bit type into the high bits of one byte and the argument count into the low six. A count of 63 or more writes 63 as an escape and follows with a varint. See Packets.

Dynamic encoder

function Buffers.WriteAny(w: Writer, v: any): ()
function Buffers.ReadAny(r: Reader): any

Writes a one-byte type tag then the value, dispatching on typeof(v). Used for every unschematised event argument and for all invoke traffic.

Integer narrowing

Integers are written at the narrowest width that fits: u8, u16 or u32 when non-negative, i16 or i32 when negative, and f64 otherwise. WriteI8 is never selected, so small negatives cost two bytes.

Table classification

A single pairs walk decides array against dictionary, breaking on the first key that is not an integer in 1..n. Arrays get TYPE_ARRAY plus a varint count; dictionaries get TYPE_TABLE and alternating key and value pairs terminated by a nil key.

Circular references overflow

Recursion has no visited-set and no depth limit, so a table referencing itself recurses until the Luau stack overflows.

Unsupported types degrade silently

An unrecognised typeof logs warn("Unsupported type: " .. t) on the sender and writes TYPE_NIL. The receiver gets nil with no indication anything went wrong, and the argument count still matches.

See the full tag table.

Pack / Unpack

function Buffers.Pack(w: Writer, ...: any): ()
function Buffers.Unpack(r: Reader): { any }

Writes a varint count followed by that many WriteAny values. Unpack returns them as an array.

Public but unused by Flux itself, because the Server and Client modules write their argument counts through the packet header instead. Available if you are building your own framing on top of Buffers.

Constants

Constant	Value	Meaning
`ALLOC_SIZE`	`4096`	Default writer capacity
`POOL_SIZE`	`512`	Maximum pooled writers and readers
`MAX_REUSE_SIZE`	`65536`	Writers above this are discarded, not pooled

4 KB comfortably holds a typical frame of traffic, which is why steady-state Flux performs no buffer allocation. Writers cycle between the pool and the bridge, and only Finalize allocates.

Entry Point

Classes

Namespaces

Internals

Types

Lifecycle

CreateWriter / CreateReader

FreeWriter / FreeReader

Finalize

Growth

Primitives

Varints

Strings and buffers

Roblox datatypes

Instance handling

Enum caching

Packet header

Dynamic encoder

Pack / Unpack

Constants

Next steps

Custom types

Type tags

​Types

​Lifecycle

​CreateWriter / CreateReader

​FreeWriter / FreeReader

​Finalize

​Growth

​Primitives

​Varints

​Strings and buffers

​Roblox datatypes

​Instance handling

​Enum caching

​Packet header

​Dynamic encoder

​Pack / Unpack

​Constants

​Next steps

Custom types

Type tags

Types

Lifecycle

CreateWriter / CreateReader

FreeWriter / FreeReader

Finalize

Growth

Primitives

Varints

Strings and buffers

Roblox datatypes

Instance handling

Enum caching

Packet header

Dynamic encoder

Pack / Unpack

Constants

Next steps