Wally

Add the dependency and run the installer.

[dependencies]
VoidSentry2 = "elentium/voidsentry2@0.1.1"

Then run wally install and require the module from your tree (for example game.ReplicatedStorage.Packages.VoidSentry2 depending on layout).

Pesde

Install with the Pesde CLI, then require the module from the path Pesde uses in your project (commonly under your packages tree).

pesde add elentium/voidsentry2

Package page

GitHub

Clone github.com/Elentium/VoidSentry2 and wire the src tree into your project with Rojo (or copy the source into ReplicatedStorage). Point require at the package entry module.

Model file (.rbxm)

A packaged /roblox/VoidSentry2.rbxm model is provided for drag-and-drop into Studio. Insert it under ReplicatedStorage (or your preferred folder) and require the ModuleScript entry.

Roblox Creator Store

The library is published as a Creator Store asset so you can add it from the toolbox.

Creator Store

Options

Related code

src/shared/config/init.luau re-exports the constants plus typeSigns for the rest of the package. Game code does not require it directly — the module is only touched when you maintain a fork of VoidSentry2.

Library properties

Top-level members of the module returned by require(VoidSentry2).

Static API

Each static call has exactly one root type node. To send multiple logical fields, wrap them in a single struct (or array / map).

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 API

Dynamic packs a variable list of values. Each value is tagged with a 1-byte type id so the receiver can decode without a shared schema. No root node; decode order matches encode order. Leading arguments are options, not values.

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)

Types

Every member of VoidSentry2.types. Sizes below are for the payload only; collection types also write a length or count prefix as noted.

Integers

Floats

Primitives & strings

Vectors & CFrames

Collections

Roblox-specific

Specials

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

Static vs dynamic — how to choose

Use static when the layout is stable across calls: gameplay state, inventory snapshots, save blobs, RPC payloads with a fixed shape. The wire carries no per-field type metadata, so the result is smaller and faster than dynamic and matches what the code already knows about the data.

Use dynamic when the values or their types change call-to-call: debug tooling, admin commands, "send whatever mix I have right now". You pay one tag byte per value plus any extra metadata (enum id, serInstance class id) but avoid maintaining a schema per shape.

A static struct covers the "many fields, one message" case without reaching for dynamic.

Type nodes and one root value

Entries in VoidSentry2.types are small internal objects. You build them at module scope and pass them to static.serialize / static.deserialize. One static call = one root value — usually a struct wrapping the real fields.

local T = VS.types
local Packet = T.struct({ id = T.uint16, name = T.string255 })

Strict vs lax failure (strictMode)

With strictMode = true (default), invalid input or buffer overflows throw. With false, they warn and serialize/deserialize return nil. In lax mode every call site must check the result.

Important: an absent optional(T) legally decodes to nil on success. In lax mode a nil result from deserialize is ambiguous — use strict mode, an outer length/checksum, or protocol context to distinguish "absent" from "failed".

Headers with offset

Pass a positive offset to reserve that many leading bytes for your own header (magic, protocol version, chunk length). The returned buffer's bytes [0, offset) are zero-filled and yours to overwrite. Deserialize with the same value so reading begins after the header.

If keeping the header in the same buffer is inconvenient, serialize with offset = 0 and frame the payload yourself.

Compression choices

Zstd (via Roblox EncodingService) costs CPU on both ends and rarely shrinks small payloads meaningfully. Measure on real traffic: it helps the most on repetitive or string-heavy blobs, less on mostly-numeric packets that are already compact.

Manual buffer mode

The manual cursor API (writeStart/writeFinish, readStart/readFinish) exposes the same scratch buffer used internally. You can call a type node's write/read directly between writeStart and writeFinish to interleave your own buffer.write* calls with VoidSentry2 nodes. This is an escape hatch — prefer the static API for everything that fits in a single schema.

Player snapshot (static)

Assume local VS = require(...), local T = VS.types, local static = VS.static for each block below.

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

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

local buf = static.serialize(Player, {
    id = 1,
    name = "Aria",
    pos = Vector3.new(0, 10, 0),
    hp = 100,
}, nil, nil)

local round = static.deserialize(Player, buf, nil, nil)

Batched entities + Zstd

Serialize with a numeric level; deserialize with wasCompressed = true.

local EntityList = T.array(T.struct({
    id = T.uint16,
    x = T.float32,
    y = T.float32,
}))

local buf = static.serialize(EntityList, entities, nil, 5)
local out = static.deserialize(EntityList, buf, nil, true)

Offset: reserve bytes, then write a header

First HEADER bytes stay zero until you fill magic/version; payload starts at HEADER. Deserialize with the same offset.

local HEADER = 8
local Payload = T.struct({ score = T.uint16, name = T.string255 })

local buf = static.serialize(Payload, { score = 10, name = "Ann" }, HEADER, nil)
buffer.writeu32(buf, 0, 0x50505332) -- example magic "PPS2"
buffer.writeu32(buf, 4, 1)        -- example protocol version

local data = static.deserialize(Payload, buf, HEADER, nil)

Dynamic with Zstd

First argument to serialize is the compression level (or nil for none). First argument to deserialize is true if that buffer was compressed.

local dynamic = VS.dynamic

local bigString = string.rep("x", 4000)
-- First arg = Zstd level 4; then offset nil; then the values to pack.
local buf = dynamic.serialize(4, nil, "ServerLog", bigString)
if not buf then return end

-- Because we used a compression level above, pass true here.
local label, payload = dynamic.deserialize(true, nil, buf)
-- label == "ServerLog", payload == bigString

Static “RPC-shaped” packet (several fields, one struct)

local Rpc = T.struct({
    op = T.string255,
    playerId = T.uint32,
    amount = T.float32,
})

local buf = static.serialize(Rpc, {
    op = "Damage",
    playerId = 7,
    amount = 12.5,
}, nil, nil)

enum (Roblox EnumItem)

local MaterialField = T.enum(Enum.Material)
local Row = T.struct({ mat = MaterialField })

local buf = static.serialize(Row, { mat = Enum.Material.Slate }, nil, nil)
local back = static.deserialize(Row, buf, nil, nil)

Dynamic RPC-style tuple

Uncompressed dynamic buffer: first two arguments to serialize are nil (no Zstd, no write offset). Receiver unpacks in order.

local dynamic = VS.dynamic

local playerId = 42
local targetPos = Vector3.new(1, 0, 0)

local b = dynamic.serialize(nil, nil, "Move", playerId, targetPos, true)
if not b then return end

local opName, id, pos, wantsJump = dynamic.deserialize(nil, nil, b)
-- opName == "Move", id == playerId, pos == targetPos, wantsJump == true

Optional fields + nested struct

Model “maybe present” values with optional; nest struct for grouped fields.

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

local Profile = T.struct({
    userId = T.uint32,
    displayName = T.string255,
    bio = T.optional(T.string255),
    stats = T.struct({
        kills = T.uint16,
        deaths = T.uint16,
    }),
})

local buf = static.serialize(Profile, {
    userId = 9001,
    displayName = "Neo",
    bio = nil,
    stats = { kills = 12, deaths = 3 },
}, nil, nil)

String keys → numbers (map)

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

local Scores = T.map(T.string255, T.float32)

local buf = static.serialize(Scores, {
    ["arena_1"] = 99.5,
    ["arena_2"] = 12.0,
}, nil, nil)
local out = static.deserialize(Scores, buf, nil, nil)

void, nothing, and any

void is an empty table {} marker (zero payload bytes). nothing is Luau nil with zero bytes. any stores a one-byte type id plus the inner value — useful when one field can hold several shapes.

local Ping = T.struct({ kind = T.string255, payload = T.any })
local buf = static.serialize(Ping, { kind = "int", payload = 42 }, nil, nil)
local back = static.deserialize(Ping, buf, nil, nil)

serInstance: register schema, then serialize

Run registerInstanceSchema once per class name (usually at module load). Then use types.serInstance("ClassName") in your static schema. Deserialization creates a new Instance and assigns properties from the buffer.

local VS = require(game.ReplicatedStorage.VoidSentry2)
local T = VS.types
local static = VS.static

VS.registerInstanceSchema("Part", {
    Name = T.string255,
    Anchored = T.boolean,
})

local PartSnapshot = T.struct({
    template = T.serInstance("Part"),
})

local src = Instance.new("Part")
src.Name = "Floor"
src.Anchored = true

local buf = static.serialize(PartSnapshot, { template = src }, nil, nil)
local copy = static.deserialize(PartSnapshot, buf, nil, nil)
-- copy.template is a new Part with Name / Anchored restored

Mixing instance (by reference) and static structs

types.instance writes a numeric id and resolves the same object on the peer via your instanceMap and _VSID — use for live object graphs. serInstance snapshots property bags into new instances — use for templates or reconstructed props.

-- instance: same Part reference round-trips if both sides share instanceMap + _VSID
local RefPayload = T.struct({ target = T.instance })

-- serInstance: wire carries property values; deserialize builds a fresh Instance
local ClonePayload = T.struct({ cloneOfPart = T.serInstance("Part") })

1. Compose built-in nodes (recommended)

Describe the wire shape by combining existing nodes: struct, array, map, optional, union, numbers, strings, vectors, enum, any. No package changes. Use this for almost every gameplay, RPC, or save-blob shape.

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

local InventorySlot = T.struct({
    itemId = T.uint16,
    count = T.uint8,
})

local PlayerSave = T.struct({
    coins = T.uint32,
    slots = T.array(InventorySlot),
})

local buf = static.serialize(PlayerSave, saveTable)

2. serInstance: snapshot Roblox instances

types.serInstance(className) serializes a declared set of properties for a given class. Flow:

1. Register once per class. VoidSentry2.registerInstanceSchema(className, { PropName = typeNode, ... }). Keys are property names as strings; values are type nodes. Call at startup, before any serialize.
2. Reference in schemas. Use T.serInstance(className) inside a struct or collection.
3. Serialize. Pass a real Instance of that class; the library reads the registered properties and writes them.
4. Deserialize. The library constructs a new Instance.new(className) and assigns properties from the buffer. Object identity is not preserved.

Versus types.instance. instance writes a numeric id (from instanceIdAttribute) and resolves the same live object on the peer via the shared instance map. Use instance for live references, serInstance for templates or fresh clones.

3. Extending union with a custom variant

Once you have a union use-case that the built-in variants don't cover, you can add your own. See union details for how dispatch works; this section focuses on the extension steps.

value  →  extypeof(value)  →  exTypeMap[exType]  →  variant typeNode  →  write / read

Checklist

1. Write the variant node. A frozen table { write, read, exType }. The idiomatic home for a reusable node is a new file under src/types/<name>.luau (matching the convention of every built-in type and allowing T.<name> access) — use any existing file there as a template. Defining the node inline with table.freeze({ ... }) next to the union that uses it is acceptable for a genuine one-off where promoting it to a first-class type would be noise. Either way, exType must be unique within the union and must not appear in config.unsupportedUnionExTypes (union, any, void, optional).
2. Make extypeof return that string for your values. If your variant's values already fall into an existing category ("int", "float", "array", "map", "Enum.<T>", or a raw typeof string), set exType to that category and remember only one variant per category may appear in a union. If your variant handles a shape the defaults don't distinguish, add a branch at the top of src/shared/extypeof.luau that returns your custom tag.
3. Use it. Pass the variant to T.union(variantA, variantB, yourVariant). Writes look up your node by exType and emit a 1-byte variant index; reads use the same index to pick the variant.

Example: routing a tagged Luau table to a dedicated variant

Two shapes both arrive as non-sequential tables but must serialize differently. The defaults map both to "map". Extend extypeof to look at a tag field and return a distinct string for one of them.

-- 1. Your variant node. Prefer src/types/myTagged.luau for reuse;
--    the inline form below is fine for a single-call-site one-off.
local MyTaggedNode = table.freeze({
    write = function(value) --[[ ... ]] return 0 end,
    read = function() --[[ ... ]] return 0, value end,
    exType = "myTagged",
})

-- 2. Patch src/shared/extypeof.luau (simplified):
--    if vType == "table" and rawget(value, "_tag") == "MY_TAGGED" then
--        return "myTagged"
--    end

-- 3. Compose a union that can hold the custom variant alongside plain maps:
local Packet = T.union(T.map(T.string255, T.int32), MyTaggedNode)

4. Forking: adding a brand-new wire type

Only needed when the byte layout you want does not exist in any built-in node. Two layers are involved.

4a. Buffer primitives — src/buffer/writer.luau and src/buffer/reader.luau

Low-level helpers that advance the cursor and write/read raw bytes (U8, U16, writef32, NEED, …). Not typed, no dispatch. Add symmetric write* / read* helpers here if you need a new byte pattern.

4b. Type node — src/types/<name>.luau

Exports a frozen { write, read, exType }. Validates input, calls NEED(n), then writes using the buffer primitives. On read, checks the status and returns (flag, value). Use src/types/uint8.luau or src/types/float32.luau as a template.

4c. Registration — src/shared/config/typeSigns.luau

Add a unique 1-byte id: myformat = 48. The key must match the filename. src/init.luau iterates typeSigns and loads each matching src/types/<name>.luau into signMap and types.

4d. Optional: dynamic inference — src/shared/inferValueType.luau

Only needed if the dynamic serializer should automatically pick your type from plain Luau values. Static schemas reference nodes directly and do not need this step.

After adding all four pieces, the new type is available as T.myformat, works in struct/array/map, and (if added to inferValueType) can be chosen by the dynamic path.