maxBufferSize

Default: 10_000_000 bytes. Effect: hard cap for the internal scratch buffer used during a single serialize call. If a payload would exceed it, serialization fails.

Change when: you know your payloads never approach this size (reduce to catch bugs earlier) or you legitimately serialize larger snapshots (raise it).

strictMode

Default: true. Effect: type mismatches, missing fields, buffer overflows, invalid input, etc. throw an error. With false the same conditions warn and serialize/deserialize return nil.

Change when: shipping to production and you want best-effort failure tolerance (network payloads, corrupted save data). Keep true during development to fail loudly.

dynamicVectorType

Default: "vector". Values: "vector" or "Vector3". Effect: when the dynamic serializer infers a vector value, it chooses the Luau vector node or the Roblox Vector3 node. Both are 12 bytes; the difference is which Luau type is produced on deserialize.

Change when: your codebase prefers one native type over the other. Ignored by the static serializer — static schemas always use whichever node you put in them.

dynamicInstanceType

Default: "instance". Values: "instance" or "serInstance". Effect: when the dynamic serializer encounters an Instance, "instance" writes its numeric id and looks the same object up on the peer; "serInstance" writes a property snapshot using the registered schema for the instance's class.

Change when: dynamic messages should carry property snapshots by default (e.g. template replication) instead of live references. Ignored by the static serializer.

instanceIdAttribute

Default: "_VSID". Effect: attribute name used by types.instance and the server/client instance-map scripts to tag and look up instances. Both sides must agree on this name.

Change when: the default collides with your own attribute names or you want a shorter name. Set once, before any instance is tagged.

unsupportedUnionExTypes

Default: { union, any, void, optional }. Effect: set of exType strings that cannot appear as a variant of T.union(...); the builder throws if you try.

Change when: almost never. These are blocked because they do not round-trip cleanly through extypeof (unions cannot distinguish them from other variants).

Internal status codes

unknownType, success, fail, eor are the numeric flags returned by reader/writer primitives. Do not change.

.types

Table of built-in type nodes and factories (int32, struct(...), array(T), union(...), etc.). You pass these to the static serializer. See Types for the full list.

.static

Schema-based serializer: { serialize, deserialize }. You supply a root typeNode that describes the whole payload. See Static API.

.dynamic

Schemaless serializer: { serialize, deserialize }. You pass a variable list of values; each is tagged with a 1-byte type id on the wire. See Dynamic API.

.registerInstanceSchema(className, schema)

registerInstanceSchema(className: string, schema: { [string]: typeNode }) -> ()

Declares which properties of className should be captured by types.serInstance(className). Keys are property names; values are type nodes (e.g. Name = T.string255). Call once at startup per class, before any serialize that references it.

.combine(t1, t2)

combine<T1, T2>(t1: T1, t2: T2) -> T1 & T2

Shallow merge helper. Useful for composing struct field tables at module scope. Not serialization-specific.

.setConstant(constant, value)

setConstant<T>(constant: voidSentryConstants, value: T) -> ()

Updates a runtime configuration value without editing constants.luau. See the Configuration page for what each option does.

Editable constants: maxBufferSize (number), strictMode (boolean), dynamicVectorType (string), dynamicInstanceType (string), unsupportedUnionExTypes (table).

• For scalar constants, value replaces the current setting.
• For unsupportedUnionExTypes, keys from value are merged into the existing table (shallow).
• When maxBufferSize changes, updateBigBuffer is called automatically.
• Invalid constant names or wrong value types error (strict mode) or warn and no-op (lax mode).

local VS = require(path.to.VoidSentry2)

VS.setConstant("strictMode", false)
VS.setConstant("maxBufferSize", 20_000_000)

.updateBigBuffer()

updateBigBuffer() -> ()

Reallocates the internal serialize scratch buffer so its capacity matches the current maxBufferSize. Existing bytes in the scratch buffer (up to the previous capacity) are copied into the new buffer.

You rarely call this yourself — setConstant("maxBufferSize", ...) invokes it automatically. Use it only if you changed maxBufferSize through another path and need the scratch buffer resized before the next serialize.

Manual cursor API

Low-level hooks for advanced users who want to mix VoidSentry2 writes with their own bytes, or batch several type-node writes under one buffer.

• writeStart(offset: number?) -> () — reset the scratch buffer cursor.
• writeFinish() -> buffer — copy bytes [0, cursor) into a new exact-sized buffer.
• getWriteCursor() -> number — current write position.
• readStart(buf: buffer, offset: number?) -> () — bind the reader to buf.
• readFinish() -> () — release the current read buffer.
• getReadCursor() -> number — current read position.

If you only call static / dynamic you never touch these.

static.serialize(serdes, input, offset?, compressionLevel?) -> buffer?

<T>(serdes: typeNode<T>, input: T, offset: number?, compressionLevel: number?) -> buffer?

• serdes — root type node describing the payload shape.
• input — the Luau value matching serdes.
• offset (optional, default 0) — number of bytes to reserve at the start of the returned buffer. These bytes are zero-filled; you can overwrite them with a header, magic value, or version after the call. Deserialize with the same value.
• compressionLevel (optional) — Zstd level passed to EncodingService. When set, the full payload is compressed. When nil, no compression.

Returns the packed buffer, or nil in lax mode when the input fails validation.

static.deserialize(serdes, buf, offset?, wasCompressed?) -> T?

<T>(serdes: typeNode<T>, buf: buffer, offset: number?, wasCompressed: boolean?) -> T?

• serdes — same type node used on the sender side.
• buf — the buffer to decode.
• offset — must match the offset passed to serialize.
• wasCompressed — true only when serialize was called with a non-nil compressionLevel.

Example

local T = VS.types
local static = VS.static

local Player = T.struct({
    id = T.uint32,
    name = T.string255,
    hp = T.float32,
})

local buf = static.serialize(Player, { id = 1, name = "Aria", hp = 100 })
local back = static.deserialize(Player, buf)

dynamic.serialize(compressionLevel?, offset?, ...) -> buffer?

<T...>(compressionLevel: number?, offset: number?, T...) -> buffer?

• compressionLevel — Zstd level, or nil for no compression. First positional argument.
• offset — header-reservation, same semantics as the static API. Second positional argument.
• ... — the values to pack, in order.

dynamic.deserialize(wasCompressed?, offset?, buf) -> ...any?

(wasCompressed: boolean?, offset: number?, buf: buffer) -> ...any?

• wasCompressed — true when the buffer was produced with a compression level; otherwise nil/false.
• offset — must match the offset passed to serialize.
• buf — the buffer to decode.

Returns the unpacked values in the order they were written.

Inference notes

The dynamic serializer picks a type for each value via src/shared/inferValueType.luau. Integers are chosen by magnitude (including uint40/uint48 and int40/int48); out-of-range integers and floats outside float32 range become float64; numbers with a fractional part become float32 when they fit; tables with sequential integer keys become array, otherwise map. Empty tables become void. Instance and vector inference follow dynamicInstanceType / dynamicVectorType in the config.

Example

local dynamic = VS.dynamic

local buf = dynamic.serialize(nil, nil, "Move", 42, Vector3.new(0, 10, 0), true)
local op, id, pos, sprint = dynamic.deserialize(nil, nil, buf)

union(v1, v2, …) — in depth

T.union(...) builds a typeNode that accepts any one of the provided variant nodes. On the wire it emits a 1-byte variant index followed by the chosen variant's payload, so the total size is 1 byte + variant size and the upper bound is 255 variants.

How dispatch works. At write time, the library calls extypeof(value) and looks the returned string up in the union's internal exType → variantNode table. The chosen variant's write runs; the variant's position in the argument list is stored as the index byte. At read time that byte selects the variant and its read runs.

exType rules (enforced at build time).

• Each variant's exType must be unique within the union — the dispatch table rejects duplicates.
• Type families that share an exType therefore collapse into one slot: all integer widths share "int"; all floats share "float"; string and string255 share "string"; every CFrame encoding shares "CFrame"; every Vector3 encoding shares "Vector3"; struct, deltaStruct, deltaStruct16, and map share "map"; instance and serInstance share "Instance". Pick the width/encoding you want, once per union.
• Variants whose exType is listed in config.unsupportedUnionExTypes (union, any, void, optional) are rejected — these cannot participate because their runtime shape does not round-trip through extypeof.
• A value whose extypeof result matches no variant is a serialization error in strict mode (or a warn + nil buffer in lax mode).

What extypeof returns. Numbers become "int" or "float" by value (integer-valued floats go to "int"). Tables are "array" if sequential, otherwise "map". EnumItem becomes "Enum." .. EnumType. Everything else is the raw typeof string ("string", "boolean", "Vector3", "CFrame", "Instance", …).

-- Three-way union: integer | float | string
local MessageField = T.union(T.int32, T.float64, T.string255)

static.serialize(MessageField, 42)         -- routes via "int"    → int32  branch
static.serialize(MessageField, math.pi)    -- routes via "float"  → float64 branch
static.serialize(MessageField, "hi")       -- routes via "string" → string255 branch

-- Build-time error: both widths share exType "int".
-- T.union(T.int32, T.int16)

To route a value shape that extypeof does not distinguish (e.g. two different kinds of non-sequential table), extend extypeof to return a new tag and add a variant whose exType equals that tag. See Extending union.