startingBufferSize

Default: 64 bytes. Effect: initial capacity of each write cursor's private buffer when writeStart is called. The buffer grows automatically via alloc when a write would exceed capacity.

Change when: most of your payloads are large — raising this avoids a few early reallocations. Keep it small if you serialize many tiny messages and want to minimize idle allocation.

bufferExpandMultiplier

Default: 1.5. Effect: when a write cursor runs out of room, its capacity is multiplied by this factor (integer division) until the pending write fits.

Change when: tuning the time/memory trade-off of buffer growth. Higher values mean fewer reallocations but more wasted tail space; lower values tighten memory at the cost of more copies.

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: omniSentryConstants, value: T) -> ()

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

Editable constants: startingBufferSize (number), bufferExpandMultiplier (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).
• Invalid constant names or wrong value types error (strict mode) or warn and no-op (lax mode).

local VS = require(path.to.OmniSentry)

VS.setConstant("strictMode", false)
VS.setConstant("startingBufferSize", 256)

Manual cursor API

Low-level hooks for advanced users who want several independent serialize sessions, or to mix OmniSentry type-node writes with their own bytes on the same buffer.

• writeStart(offset: number?) -> cursor — create a new write cursor with a private growable buffer. cursor is { buf, offset, len }.
• alloc(cursor, bytes) -> () — ensure at least bytes of free space remain at the current write position (grows cursor.buf when needed). Type nodes call this internally before writing.
• writeFinish(cursor) -> buffer — copy bytes [0, cursor.offset) into a new exact-sized buffer.
• readStart(buf: buffer, offset: number?) -> cursor — bind a read cursor to buf; cursor.len is buffer.len(buf).

Current byte position on either side is always cursor.offset. Unlike VoidSentry2, there is no global cursor and no readFinish — drop the cursor when you are done.

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

local VS = require(path.to.OmniSentry)
local T = VS.types

local cursor = VS.writeStart()
T.uint16.write(cursor, 42)
VS.alloc(cursor, 4)
buffer.writef32(cursor.buf, cursor.offset, 3.14)
cursor.offset += 4
local buf = VS.writeFinish(cursor)

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; numbers with a fractional part become float32; tables with sequential integer keys become array, otherwise map. Empty tables become void. Instance and vector inference follow dynamicInstanceType / dynamicVectorType in the config. Wider integer widths (uint40, uint48) are not inferred — use the static API when you need them.

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 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.