@axpecter/lync 2.0.0 → 2.1.1

package/README.md

@@ -1,19 +1,22 @@
 <h1 align="center">Lync</h1>
-<p align="center">Buffer networking for Roblox. Delta compression, XOR framing, built-in security.</p>
+<p align="center">Buffer networking for Roblox.</p>
 <p align="center">
   <a href="https://github.com/Axp3cter/Lync/releases/latest">Releases</a> ·
+  <a href="#install">Install</a> ·
   <a href="#example">Example</a> ·
-  <a href="#benchmarks">Benchmarks</a> ·
-  <a href="#limits--configuration">Limits</a>
+  <a href="#codecs">Codecs</a> ·
+  <a href="#benchmarks">Benchmarks</a>
 </p>
 
+Lync batches all sends into a single buffer per player per frame, applies XOR compression across frames, validates and rate-limits every incoming payload, and does it all without code generation.
+
 ## Install
 
-**Wally (Luau)**
+**Wally**
 
 ```toml
 [dependencies]
-Lync = "axp3cter/lync@2.0.0"
+Lync = "axp3cter/lync@2.1.1"
 ```
 
 **npm (roblox-ts)**
@@ -26,52 +29,46 @@ npm install @axpecter/lync
 import Lync from "@axpecter/lync";
 ```
 
-Or grab the `.rbxm` from [releases](https://github.com/Axp3cter/Lync/releases/latest) and drop it in `ReplicatedStorage`.
+Or grab the `.rbxm` from [Releases](https://github.com/Axp3cter/Lync/releases/latest).
 
 > [!IMPORTANT]
-> Define everything before calling `Lync.start()`. Packets, queries, namespaces, all of it.
+> Define all packets, queries, and groups before calling `Lync.start()`.
 
 ## Example
 
-**Shared**
+**Shared** (`ReplicatedStorage.Net`)
 
 ```luau
 local Lync = require(game.ReplicatedStorage.Lync)
 
 local Net = {}
 
-Net.State = Lync.definePacket("State", {
-    value = Lync.deltaStruct({
-        position = Lync.vec3,
-        health   = Lync.quantizedFloat(0, 100, 0.5),
-        shield   = Lync.quantizedFloat(0, 100, 0.5),
-        status   = Lync.enum("idle", "moving", "attacking", "dead"),
-        alive    = Lync.bool,
-    }),
-})
-
-Net.Hit = Lync.definePacket("Hit", {
-    value = Lync.struct({
-        targetId = Lync.u16,
-        damage   = Lync.quantizedFloat(0, 200, 0.1),
-        headshot = Lync.bool,
-    }),
-    rateLimit = { maxPerSecond = 30, burstAllowance = 5 },
+Net.State = Lync.packet("State", Lync.deltaStruct({
+    position = Lync.vec3,
+    health   = Lync.float(0, 100, 0.5),
+    shield   = Lync.float(0, 100, 0.5),
+    status   = Lync.enum("idle", "moving", "attacking", "dead"),
+    alive    = Lync.bool,
+}))
+
+Net.Hit = Lync.packet("Hit", Lync.struct({
+    targetId = Lync.int(0, 65535),
+    damage   = Lync.float(0, 200, 0.1),
+    headshot = Lync.bool,
+}), {
+    rateLimit = { maxPerSecond = 30, burst = 5 },
     validate = function(data, player)
         if data.damage > 200 then return false, "damage" end
         return true
     end,
 })
 
-Net.Chat = Lync.definePacket("Chat", {
-    value = Lync.struct({ msg = Lync.boundedString(200), channel = Lync.u8 }),
-})
+Net.Chat = Lync.packet("Chat", Lync.struct({
+    msg     = Lync.string(200),
+    channel = Lync.int(0, 255),
+}))
 
-Net.Ping = Lync.defineQuery("Ping", {
-    request  = Lync.nothing,
-    response = Lync.f64,
-    timeout  = 3,
-})
+Net.Ping = Lync.query("Ping", Lync.nothing, Lync.f64, { timeout = 3 })
 
 return table.freeze(Net)
 ```
@@ -83,22 +80,15 @@ local Lync    = require(game.ReplicatedStorage.Lync)
 local Net     = require(game.ReplicatedStorage.Net)
 local Players = game:GetService("Players")
 
-local alive = Lync.createGroup("alive")
+local alive = Lync.group("alive")
 
-Lync.onSend(function(data, name, player)
-    print("[out]", name)
-    return data
-end)
-
-Lync.onDrop(function(player, reason, name, data)
+Lync.onDrop(function(player, reason, name)
     warn(player.Name, "dropped", name, reason)
 end)
 
 Lync.start()
 
-Players.PlayerAdded:Connect(function(player)
-    alive:add(player)
-end)
+Players.PlayerAdded:Connect(function(player) alive:add(player) end)
 
 game:GetService("RunService").Heartbeat:Connect(function()
     Net.State:send({
@@ -110,24 +100,14 @@ game:GetService("RunService").Heartbeat:Connect(function()
     }, alive)
 end)
 
-Net.Hit:listen(function(data, player)
+Net.Hit:on(function(data, player)
     local target = Players:GetPlayerByUserId(data.targetId)
     if not target then return end
-
     alive:remove(target)
     Net.Chat:send({ msg = player.Name .. " eliminated " .. target.Name, channel = 0 }, Lync.all)
-    Net.State:send({
-        position = Vector3.zero,
-        health   = 0,
-        shield   = 0,
-        status   = "dead",
-        alive    = false,
-    }, Lync.except(target))
 end)
 
-Net.Ping:listen(function(request, player)
-    return os.clock()
-end)
+Net.Ping:handle(function(_, player) return os.clock() end)
 ```
 
 **Client**
@@ -140,474 +120,408 @@ Lync.start()
 
 local scope = Lync.scope()
 
-scope:listen(Net.State, function(state)
+scope:on(Net.State, function(state)
     local character = game.Players.LocalPlayer.Character
     if not character then return end
     character:PivotTo(CFrame.new(state.position))
 end)
 
-scope:listen(Net.Chat, function(data)
-    print("[chat]", data.msg)
-end)
+scope:on(Net.Chat, function(data) print("[chat]", data.msg) end)
 
 Net.Hit:send({ targetId = 123, damage = 45.5, headshot = true })
 
 local serverTime = Net.Ping:request(nil)
-if serverTime then
-    print("server clock:", serverTime)
-end
+if serverTime then print("server clock:", serverTime) end
 ```
 
-## Lifecycle
-
-| | What it does |
-|:---------|:------------|
-| `Lync.start()` | Sets up transport. Server creates remotes, client connects. Call once after all definitions. |
-| `Lync.VERSION` | `"2.0.0"` |
-
 ## Packets
 
-`Lync.definePacket(name, config)` returns a Packet.
-
-| Config | Type | Required | What it does |
-|:-------|:-----|:--------:|:-------------|
-| `value` | Codec | Yes | How to serialize the payload. |
-| `unreliable` | boolean | No | Sends over UnreliableRemoteEvent. Default `false`. Cant use with delta codecs. |
-| `rateLimit` | `{ maxPerSecond, burstAllowance? }` | No | Server-side token bucket. Burst defaults to maxPerSecond if you dont set it. |
-| `validate` | `(data, player) → (bool, string?)` | No | Server-side. Return `false, "reason"` to drop. Runs after NaN scan. |
-| `maxPayloadBytes` | number | No | Server-side. Max bytes a single batch of this packet can consume. Fires `onDrop` with reason `"size"` if exceeded. |
-| `timestamp` | `"frame" \| "offset" \| "full"` | No | Prepends a timestamp to each item. `"frame"` = u8 wrapping counter (1B), `"offset"` = u16 ms (2B), `"full"` = f64 clock (8B). Listeners receive it as a third argument. |
+`Lync.packet(name, codec, options?)`
 
-**Server, single `send` with targets:**
+### Options
 
-```luau
-packet:send(data, player)              -- one player
-packet:send(data, Lync.all)            -- everyone
-packet:send(data, Lync.except(player)) -- everyone except one
-packet:send(data, Lync.except(p1, p2)) -- everyone except multiple
-packet:send(data, { p1, p2 })          -- list of players
-packet:send(data, group)               -- group object
-```
+| Field | Type | Default | Description |
+|:------|:-----|:--------|:------------|
+| `unreliable` | `boolean` | `false` | Send over `UnreliableRemoteEvent`. Cannot use with delta codecs. |
+| `rateLimit` | `RateLimitConfig` | none | Server-side rate limiting. |
+| `validate` | `(data, player) → (bool, string?)` | none | Server-side validation. Return `false, "reason"` to drop. |
+| `maxPayloadBytes` | `number` | none | Max bytes per payload. |
+| `timestamp` | `"frame"`, `"offset"`, or `"full"` | none | Appends a timestamp. `"frame"` = 1B counter. `"offset"` = 2B ms. `"full"` = 8B clock. Received as third argument. |
 
-**Client:**
+### Sending
 
 ```luau
-packet:send(data)  -- send to server
+-- Server
+packet:send(data, player)
+packet:send(data, Lync.all)
+packet:send(data, Lync.except(p1, p2))
+packet:send(data, { p1, p2, p3 })
+packet:send(data, group)
+
+-- Client
+packet:send(data)
 ```
 
-**Shared (both contexts):**
+### Receiving
 
-| Method | What it does |
+| Method | Description |
 |:-------|:------------|
-| `packet:listen(fn(data, sender, timestamp?))` | Sender is `Player` on server, `nil` on client. `timestamp` is present when the packet has a `timestamp` config. Returns a Connection. |
-| `packet:once(fn(data, sender, timestamp?))` | Auto-disconnects after one fire. |
-| `packet:wait()` | Returns `(data, sender)`. |
-| `packet:disconnectAll()` | Kills all listeners on this packet. |
+| `packet:on(fn)` | `fn(data, sender, timestamp?)`. Returns a Connection. |
+| `packet:once(fn)` | Fires once, then disconnects. |
+| `packet:wait()` | Yields until next fire. Returns `data, sender, timestamp?`. |
+| `packet:name()` | Returns the packet name. |
+| `packet:stats()` | Returns `{ bytesSent, bytesReceived, fires, recvFires, drops }`. Requires stats enabled. |
 
 ## Queries
 
-`Lync.defineQuery(name, config)` returns a Query. Basically RemoteFunctions but built on RemoteEvents. Returns `nil` if the other side times out or errors.
+`Lync.query(name, requestCodec, responseCodec, options?)`
 
-| Config | Type | Required | What it does |
-|:-------|:-----|:--------:|:-------------|
-| `request` | Codec | Yes | How to serialize the request. |
-| `response` | Codec | Yes | How to serialize the response. |
-| `timeout` | number | No | Seconds before giving up. Default `5`. |
-| `rateLimit` | `{ maxPerSecond, burstAllowance? }` | No | Server-side token bucket on incoming requests. |
-| `validate` | `(data, player) → (bool, string?)` | No | Server-side validation on incoming requests. |
+Request-response built on packets. Returns `nil` on timeout.
 
-| Method | Where | What it does |
-|:-------|:------|:-------------|
-| `query:listen(fn)` | Both | Register a handler. Server gets `fn(request, player) → response`. Client gets `fn(request) → response`. |
-| `query:request(data)` | Client | Send request to server, yield until response or timeout. |
-| `query:requestFrom(player, data)` | Server | Send request to a specific client, yield until response or timeout. |
-| `query:requestAll(data)` | Server | Send request to all players. Returns `{ [Player]: response? }`. |
-| `query:requestList(players, data)` | Server | Send request to a list of players. Returns `{ [Player]: response? }`. |
-| `query:requestGroup(group, data)` | Server | Send request to all players in a group. Returns `{ [Player]: response? }`. |
+### Options
 
-## Namespaces
+| Field | Type | Default | Description |
+|:------|:-----|:--------|:------------|
+| `timeout` | `number` | 5 | Seconds before yielding `nil`. |
+| `rateLimit` | `RateLimitConfig` | `{ maxPerSecond = 30 }` | Server-side rate limiting. |
+| `validate` | `(data, player) → (bool, string?)` | none | Server-side validation. |
 
-`Lync.defineNamespace(name, config)` returns a Namespace. Takes a `packets` table and/or a `queries` table. All names get auto-prefixed with `"YourNamespace."` so nothing collides.
+### Methods
 
-The config takes `PacketConfig` and `QueryConfig` objects (same shape you'd pass to `definePacket` / `defineQuery`). The namespace creates and owns the packets/queries internally.
+| Method | Context | Description |
+|:-------|:--------|:------------|
+| `query:handle(fn)` | Both | Register handler. Server: `fn(request, player) → response`. Client: `fn(request) → response`. |
+| `query:request(data)` | Client | Send to server, yield for response. |
+| `query:request(data, player)` | Server | Send to one client. |
+| `query:request(data, target)` | Server | Send to multiple. Returns `{ [Player]: response? }`. |
+| `query:name()` | Both | Returns the query name. |
+| `query:stats()` | Both | Combined stats for request and response channels. |
 
-```luau
-local Combat = Lync.defineNamespace("Combat", {
-    packets = {
-        Hit = {
-            value = Lync.struct({ targetId = Lync.u16, damage = Lync.f32, headshot = Lync.bool }),
-            rateLimit = { maxPerSecond = 30, burstAllowance = 5 },
-            validate = function(data, player)
-                if data.damage > 200 then return false, "damage" end
-                return true
-            end,
-        },
-        Death = { value = Lync.u16 },
-    },
-    queries = {
-        Stats = {
-            request  = Lync.nothing,
-            response = Lync.struct({ kills = Lync.u16, deaths = Lync.u16 }),
-            timeout  = 3,
-        },
-    },
-})
-
--- Access by short name directly on the namespace
-Combat.Hit:send(data, player)
-Combat.Death:listen(function(targetId, sender) end)
-Combat.Stats:listen(function(request, player) return { kills = 10, deaths = 2 } end)
-
--- Or via the typed sub-tables
-Combat.packets.Hit:send(data, player)
-Combat.queries.Stats:request(nil)
-```
+Each query consumes two packet IDs internally.
 
-| Config field | Type | What it does |
-|:-------------|:-----|:-------------|
-| `packets` | `{ [string]: PacketConfig }?` | Map of short name → packet config. Each entry becomes a Packet on the namespace. |
-| `queries` | `{ [string]: QueryConfig }?` | Map of short name → query config. Each entry becomes a Query on the namespace. |
-
-Access packets and queries by their short name on the returned object: `ns.PacketName`, `ns.QueryName`. Or use the typed sub-tables: `ns.packets.PacketName`, `ns.queries.QueryName`.
-
-| Method | What it does |
-|:-------|:------------|
-| `ns:listenAll(fn(name, data, sender, timestamp?))` | Listens to every packet in the namespace. `name` is the short name without prefix. Returns a Connection. |
-| `ns:onSend(fn(data, name, player) → data?)` | Send middleware that only runs for this namespace. Returns a remover. |
-| `ns:onReceive(fn(data, name, player) → data?)` | Receive middleware that only runs for this namespace. Returns a remover. |
-| `ns:disconnectAll()` | Kills all listeners made through `listenAll`. |
-| `ns:destroy()` | Kills listeners and removes scoped middleware. Full cleanup. |
-| `ns:packetNames()` | Sorted list of packet short names. |
-| `ns:queryNames()` | Sorted list of query short names. |
-| `ns.packets` | Frozen table mapping short name → Packet object. |
-| `ns.queries` | Frozen table mapping short name → Query object. |
+## Groups
 
-## Connection
+`Lync.group(name)`
 
-Returned by `packet:listen()`, `packet:once()`, `query:listen()`, and `ns:listenAll()`.
+Named player sets. Members auto-removed on `PlayerRemoving`. Iterable with `for player in group do`.
 
-| | What it does |
-|:-------|:------------|
-| `connection.connected` | `boolean` |
-| `connection:disconnect()` | Stops the listener. |
+| Method | Returns | Description |
+|:-------|:--------|:------------|
+| `group:add(player)` | `boolean` | `true` if added. |
+| `group:remove(player)` | `boolean` | `true` if removed. |
+| `group:has(player)` | `boolean` | Membership check. |
+| `group:count()` | `number` | Member count. |
+| `group:destroy()` | — | Clears members, frees name. |
 
 ## Scope
 
-Batches connections for lifecycle-aligned cleanup.
+`Lync.scope()`
+
+Batches connections for cleanup.
 
 ```luau
 local scope = Lync.scope()
-
-scope:listen(packetA, fnA)
-scope:listen(packetB, fnB)
-scope:listenAll(namespace, fnC)
-
+scope:on(packetA, fnA)
+scope:on(packetB, fnB)
+scope:add(someRBXScriptConnection)
 scope:destroy()  -- disconnects everything
 ```
 
-| Method | What it does |
+| Method | Description |
 |:-------|:------------|
-| `scope:listen(source, fn)` | Calls `source:listen(fn)` and tracks the connection. |
-| `scope:once(source, fn)` | Calls `source:once(fn)` and tracks the connection. |
-| `scope:listenAll(namespace, fn)` | Calls `namespace:listenAll(fn)` and tracks the connection. |
-| `scope:add(connection)` | Also accepts RBXScriptConnection. |
-| `scope:destroy()` | Safe to call multiple times. |
-
-## Groups
-
-Named player sets. Members get removed automatically on `PlayerRemoving`. `Lync.createGroup(name)` returns a Group object.
-
-```luau
-local vips = Lync.createGroup("vips")
+| `scope:on(source, fn)` | Connect and track. |
+| `scope:once(source, fn)` | Connect once and track. |
+| `scope:add(connection)` | Track an existing connection. |
+| `scope:destroy()` | Disconnect all. Safe to call multiple times. |
 
-vips:add(player)
-vips:remove(player)
-vips:has(player)
+## Connection
 
-packet:send(data, vips)
-```
+Returned by `packet:on()`, `packet:once()`, `query:handle()`, and middleware functions.
 
-| Method | Returns | What it does |
-|:-------|:--------|:-------------|
-| `group:add(player)` | `boolean` | `true` if added, `false` if already in. |
-| `group:remove(player)` | `boolean` | `true` if removed, `false` if wasnt in there. |
-| `group:has(player)` | `boolean` | Whether the player is in the group. |
-| `group:count()` | `number` | Number of members. |
-| `group:getSet()` | `{ [Player]: true }` | Snapshot of the internal set. |
-| `group:forEach(fn)` | `()` | Calls `fn(player)` for each member. |
-| `group:destroy()` | `()` | Removes the group and all memberships. |
+| Field / Method | Description |
+|:---------------|:------------|
+| `connection.connected` | `boolean` |
+| `connection:disconnect()` | Stops the listener. Safe mid-fire, safe to call multiple times. |
 
 ## Middleware
 
-Global intercept on all packets. Handlers run in the order you registered them. Return `Lync.DROP` from a handler to drop the packet. Return the data to pass it through.
-
 ```luau
 Lync.onSend(function(data, name, player)
-    if shouldDrop(data) then
-        return Lync.DROP
-    end
-    data.timestamp = os.clock()
+    return data  -- or return Lync.DROP to discard
+end)
+
+Lync.onReceive(function(data, name, player)
     return data
 end)
-```
 
-| Function | What it does |
-|:---------|:------------|
-| `Lync.onSend(fn(data, name, player) → data \| Lync.DROP)` | Runs before a packet goes out. Returns a remover function. |
-| `Lync.onReceive(fn(data, name, player) → data \| Lync.DROP)` | Runs when a packet comes in. Returns a remover function. |
-| `Lync.onDrop(fn(player, reason, name, data))` | Fires when a packet gets rejected. Returns a remover function. Supports multiple handlers. Reason is `"nan"`, `"rate"`, `"validate"`, `"size"`, or whatever string your validate function returned. |
-| `Lync.DROP` | Frozen sentinel. Return from middleware to drop the packet. |
+Lync.onDrop(function(player, reason, name, data)
+    warn(player.Name, "dropped", name, reason)
+end)
+```
 
-Packets that fail validation are dropped individually. Other packets in the same frame from the same player are unaffected.
+All three return a Connection.
 
-## Target Descriptors
+## Targets
 
-Used as the second argument to `packet:send()` on the server.
+Server-side second argument to `packet:send()`.
 
-| Target | What it does |
+| Target | Description |
 |:-------|:------------|
-| `player` | Send to one player. |
-| `Lync.all` | Send to all connected players. |
-| `Lync.except(player, ...)` | Send to everyone except the specified players. |
-| `{ p1, p2, ... }` | Send to a list of players. |
-| `group` | Send to all members of a Group object. |
-
-## Types
-
-### Primitives
-
-| Type | Bytes | Range |
-|:-----|------:|:------|
-| `Lync.u8` | 1 | 0 to 255 |
-| `Lync.u16` | 2 | 0 to 65,535 |
-| `Lync.u32` | 4 | 0 to 4,294,967,295 |
-| `Lync.i8` | 1 | -128 to 127 |
-| `Lync.i16` | 2 | -32,768 to 32,767 |
-| `Lync.i32` | 4 | -2,147,483,648 to 2,147,483,647 |
-| `Lync.f16` | 2 | ±65,504, roughly 3 digits of precision |
-| `Lync.f32` | 4 | IEEE 754 single |
-| `Lync.f64` | 8 | IEEE 754 double |
-| `Lync.bool` | 1 | true/false. Gets packed into bitfields when inside structs, and 8-per-byte when inside arrays. |
-
-### Datatypes
-
-| Type | Bytes | What it is |
-|:-----|------:|:-----------|
-| `Lync.string` | varint + N | Varint length prefix then raw bytes. |
-| `Lync.vec2` | 8 | 2x f32. |
-| `Lync.vec3` | 12 | 3x f32. |
-| `Lync.cframe` | 24 | Position as 3x f32, rotation as axis-angle 3x f32. |
-| `Lync.color3` | 3 | RGB 0-255 per channel, clamped. |
-| `Lync.inst` | 2 | Instance ref through sidecar array. Requires refs on read, throws without them. |
-| `Lync.buff` | varint + N | Varint length prefix then raw bytes. |
-| `Lync.udim` | 8 | Scale f32 + Offset i32. |
-| `Lync.udim2` | 16 | 2x UDim (X then Y). |
-| `Lync.numberRange` | 8 | Min f32 + Max f32. |
-| `Lync.rect` | 16 | Min.X f32 + Min.Y f32 + Max.X f32 + Max.Y f32. |
-| `Lync.vec2int16` | 4 | 2x i16. |
-| `Lync.vec3int16` | 6 | 3x i16. |
-| `Lync.region3` | 24 | Min Vec3 + Max Vec3 as 6x f32. |
-| `Lync.region3int16` | 12 | Min Vec3int16 + Max Vec3int16 as 6x i16. |
-| `Lync.ray` | 24 | Origin Vec3 + Direction Vec3 as 6x f32. |
-| `Lync.numberSequence` | varint + N×12 | Varint count then (time f32 + value f32 + envelope f32) per keypoint. |
-| `Lync.colorSequence` | varint + N×7 | Varint count then (time f32 + R u8 + G u8 + B u8) per keypoint. |
-| `Lync.boundedString(maxLength)` | varint + N | Same wire format as `Lync.string` but rejects on read if length exceeds `maxLength`. |
+| `player` | Single player. |
+| `Lync.all` | All connected players. |
+| `Lync.except(...)` | Everyone except specified players or groups. |
+| `{ p1, p2, ... }` | Array of players. |
+| `group` | All members of a group. |
+
+## Codecs
+
+### Numbers
+
+`Lync.int(min, max)` picks the smallest wire type for your range.
+
+| Codec | Bytes | Description |
+|:------|------:|:------------|
+| `Lync.int(0, 255)` | 1 | u8 |
+| `Lync.int(0, 65535)` | 2 | u16 |
+| `Lync.int(0, 4294967295)` | 4 | u32 |
+| `Lync.int(-128, 127)` | 1 | i8 |
+| `Lync.int(-32768, 32767)` | 2 | i16 |
+| `Lync.int(-2147483648, 2147483647)` | 4 | i32 |
+| `Lync.f16` | 2 | Half-precision float. ~3 digits. ±65504. |
+| `Lync.f32` | 4 | Single-precision float. |
+| `Lync.f64` | 8 | Double-precision float. |
+| `Lync.bool` | 1 | Bitpacked inside structs and arrays (8 per byte). |
+| `Lync.float(min, max, precision)` | 1–4 | Quantized float. Clamped to range. |
+
+### Strings & Buffers
+
+| Codec | Description |
+|:------|:------------|
+| `Lync.string` | Variable length. Binary-safe. |
+| `Lync.string(maxLength)` | Same, but rejects on read if length exceeds `maxLength`. |
+| `Lync.buff` | Variable-length buffer. |
+
+### Roblox Types
+
+| Codec | Bytes |
+|:------|------:|
+| `Lync.vec2` | 8 |
+| `Lync.vec3` | 12 |
+| `Lync.cframe` | 24 |
+| `Lync.color3` | 3 |
+| `Lync.inst` | 2 |
+| `Lync.udim` | 8 |
+| `Lync.udim2` | 16 |
+| `Lync.numberRange` | 8 |
+| `Lync.rect` | 16 |
+| `Lync.ray` | 24 |
+| `Lync.vec2int16` | 4 |
+| `Lync.vec3int16` | 6 |
+| `Lync.region3` | 24 |
+| `Lync.region3int16` | 12 |
+| `Lync.numberSequence` | variable |
+| `Lync.colorSequence` | variable |
+
+### Quantized Variants
+
+Call the codec to get a quantized version.
+
+| Codec | Bytes | Description |
+|:------|------:|:------------|
+| `Lync.vec2(min, max, precision)` | 2–8 | Per-component quantization. |
+| `Lync.vec3(min, max, precision)` | 3–12 | Per-component quantization. |
+| `Lync.cframe()` | 16 | Compressed rotation. ≤0.16° angular error. Saves 8B vs lossless. |
 
 ### Composites
 
-| Constructor | What it does |
-|:------------|:------------|
-| `Lync.struct({ key = codec })` | Named fields. Bools get packed into bitfields automatically. |
-| `Lync.array(codec, maxCount?)` | Variable length list with varint count. Optional `maxCount` rejects on read if exceeded. Bool arrays are bitpacked (8 per byte). |
-| `Lync.map(keyCodec, valueCodec, maxCount?)` | Key-value pairs with varint count. Optional `maxCount` rejects on read if exceeded. |
-| `Lync.optional(codec)` | 1 byte flag, value only if present. |
-| `Lync.tuple(codec, codec, ...)` | Ordered positional values, no keys. |
-| `Lync.tagged(tagField, { name = codec })` | Discriminated union with a u8 variant tag. Puts `tagField` into the decoded table so you know which variant it is. |
+| Codec | Description |
+|:------|:------------|
+| `Lync.struct({ key = codec })` | Named fields. Bools are automatically bitpacked. |
+| `Lync.array(codec, maxCount?)` | Variable-length list. Bool arrays are bitpacked. |
+| `Lync.map(keyCodec, valueCodec, maxCount?)` | Key-value pairs. |
+| `Lync.optional(codec)` | 1-byte nil flag + value if present. |
+| `Lync.tuple(...)` | Ordered positional values. |
+| `Lync.tagged(tagField, { name = codec })` | Discriminated union with 1-byte tag. |
 
 ### Delta
 
-Reliable only. Lync will error if you try to use these with `unreliable = true`.
+Only works with reliable transport. Sends 1 byte when data hasn't changed.
 
-| Constructor | What it does |
-|:------------|:------------|
-| `Lync.deltaStruct({ key = codec })` | First frame sends everything. After that only dirty fields get sent via bitmask. If nothing changed it costs 1 byte. |
-| `Lync.deltaArray(codec, maxCount?)` | Same idea but for arrays. Dirty elements get sent with varint indices. Optional `maxCount` rejects on read if exceeded. |
-| `Lync.deltaMap(keyCodec, valueCodec, maxCount?)` | Delta compression for key-value maps. Sends only upserted and removed entries after the first frame. Optional `maxCount` rejects on read if exceeded. |
+| Codec | Description |
+|:------|:------------|
+| `Lync.deltaStruct(schema)` | Delta-compressed struct. |
+| `Lync.deltaArray(codec, maxCount?)` | Delta-compressed array. |
+| `Lync.deltaMap(keyCodec, valueCodec, maxCount?)` | Delta-compressed map. |
 
 ### Meta
 
-| Constructor | What it does |
-|:------------|:------------|
-| `Lync.enum(value, value, ...)` | u8 index, up to 256 variants. |
-| `Lync.quantizedFloat(min, max, precision)` | Fixed-point compression. Picks u8/u16/u32 based on your range and precision. |
-| `Lync.quantizedVec3(min, max, precision)` | Same thing but for all 3 components. |
-| `Lync.bitfield({ key = spec })` | Sub-byte packing, 1 to 32 bits total. Spec is `{ type = "bool" }` or `{ type = "uint", width = N }` or `{ type = "int", width = N }`. |
-| `Lync.custom(size, write, read)` | User-defined fixed-size codec. `write` is `(b, offset, value) → ()`, `read` is `(b, offset) → value`. Plugs into struct/array/delta specialization automatically. |
-| `Lync.nothing` | Zero bytes. Reads nil. Good for fire-and-forget signals. |
-| `Lync.unknown` | Skips serialization entirely, goes through Roblox's sidecar. Requires refs array on read (same as `Lync.inst`). Use when you dont have a codec for the value. |
-| `Lync.auto` | Self-describing. Writes a u8 type tag then the value. Handles nil, bool, all number types, string, vec2, vec3, color3, cframe, buffer, udim, udim2, numberRange, rect, vec2int16, vec3int16, region3, region3int16, ray, numberSequence, colorSequence. |
-
-## Benchmarks
-
-### Lync Tests
-
-1,000 packets/frame, 10 seconds, one player.
-
-| Scenario | Without Lync | With Lync | FPS |
-|:---------|------------:|---------:|----:|
-| Static booleans (1B) | 480 Kbps | **2.34 Kbps** | 60.00 |
-| Static entities (34B) | 16,320 Kbps | **2.62 Kbps** | 60.00 |
-| Moving entities | 16,320 Kbps | **3.14 Kbps** | 60.00 |
-| Chaotic entities | 16,320 Kbps | **4.76 Kbps** | 59.99 |
-
-### Cross-Library Comparison
-
-Same data shapes and methodology as [Blink's benchmark suite](https://github.com/1Axen/blink/blob/main/benchmark/Benchmarks.md). 1,000 fires/frame, 10 seconds, same data every frame. Kbps scaled by 60/FPS.
-
-**Entities** (100x struct of 6x u8, fired 1000 times/frame)
-
-| Tool (FPS) | Median | P0 | P80 | P90 | P95 | P100 |
-|:-----------|-------:|---:|----:|----:|----:|-----:|
-| roblox | 16.00 | 16.00 | 15.00 | 15.00 | 15.00 | 15.00 |
-| **lync** | **60.00** | 61.00 | 60.00 | 60.00 | 60.00 | 59.00 |
-| blink | 42.00 | 45.00 | 42.00 | 42.00 | 42.00 | 42.00 |
-| zap | 39.00 | 40.00 | 38.00 | 38.00 | 38.00 | 38.00 |
-| bytenet | 32.00 | 34.00 | 32.00 | 32.00 | 32.00 | 31.00 |
-
-| Tool (Kbps) | Median | P0 | P80 | P90 | P95 | P100 |
-|:------------|-------:|---:|----:|----:|----:|-----:|
-| roblox | 559,364 | 559,364 | 676,715 | 676,715 | 676,715 | 784,081 |
-| **lync** | **3.61** | 3.53 | 3.63 | 3.64 | 3.64 | 4.64 |
-| blink | 41.81 | 26.30 | 42.40 | 42.48 | 42.48 | 42.62 |
-| zap | 41.71 | 25.46 | 42.19 | 42.32 | 42.32 | 42.93 |
-| bytenet | 41.64 | 22.84 | 42.36 | 42.82 | 42.82 | 43.24 |
-
-**Booleans** (1000x bool, fired 1000 times/frame)
-
-| Tool (FPS) | Median | P0 | P80 | P90 | P95 | P100 |
-|:-----------|-------:|---:|----:|----:|----:|-----:|
-| roblox | 21.00 | 22.00 | 20.00 | 19.00 | 19.00 | 19.00 |
-| **lync** | **60.00** | 61.00 | 60.00 | 60.00 | 60.00 | 59.00 |
-| blink | 97.00 | 98.00 | 97.00 | 96.00 | 96.00 | 96.00 |
-| zap | 52.00 | 53.00 | 51.00 | 51.00 | 51.00 | 49.00 |
-| bytenet | 35.00 | 37.00 | 35.00 | 35.00 | 35.00 | 34.00 |
-
-| Tool (Kbps) | Median | P0 | P80 | P90 | P95 | P100 |
-|:------------|-------:|---:|----:|----:|----:|-----:|
-| roblox | 353,107 | 196,826 | 690,747 | 842,240 | 842,240 | 1,124,176 |
-| **lync** | **4.31** | 3.85 | 4.36 | 4.38 | 4.38 | 4.44 |
-| blink | 7.91 | 7.41 | 7.93 | 7.99 | 7.99 | 8.00 |
-| zap | 8.10 | 5.75 | 8.17 | 8.22 | 8.22 | 8.27 |
-| bytenet | 8.11 | 5.07 | 8.35 | 8.46 | 8.46 | 8.47 |
+| Codec | Description |
+|:------|:------------|
+| `Lync.enum(...)` | String enum. Up to 256 variants. 1 byte. |
+| `Lync.bitfield(schema)` | Sub-byte packing. 1–32 bits. |
+| `Lync.custom(size, write, read)` | User-defined fixed-size codec. |
+| `Lync.nothing` | Zero bytes. Reads `nil`. |
+| `Lync.unknown` | Bypasses serialization entirely. Use with `validate`. |
+| `Lync.auto` | Self-describing. Supports nil, bool, numbers, strings, buffers, and Roblox types. |
 
-> [!NOTE]
-> Lync benchmarks run on Ryzen 7 7800X3D, 32GB DDR5-4800. Other tool numbers are from [Blink's published benchmarks](https://github.com/1Axen/blink/blob/main/benchmark/Benchmarks.md) (v0.17.1, Ryzen 9 7900X, 34GB DDR5-4800). Different CPUs so FPS numbers arent directly comparable but bandwidth numbers are since Kbps is scaled by 60/FPS. Lync hits the 60 FPS frame cap in both tests.
-
-## Stats
-
-Off by default. Call `Lync.enableStats()` before `Lync.start()` to activate. When disabled, zero overhead on send and receive paths.
+## Rate Limiting
 
-Per-packet counters are available directly on the Packet object. Per-player counters are available via `Lync.getPlayerStats()`.
-
-```luau
-Lync.enableStats()
-Lync.start()
+Two modes (pick one per packet):
 
--- Per-packet (both sides)
-print(Net.State:getBytesSent(), Net.State:getFires(), Net.State:getDrops())
+**Token bucket:** `{ maxPerSecond = N, burst = M }`
 
--- Per-player (server only)
-local stats = Lync.getPlayerStats(player)
-if stats then
-    print(stats.bytesSent, stats.bytesReceived)
-end
+**Cooldown:** `{ cooldown = seconds }`
 
-Lync.resetStats()  -- zeros everything in-place
-```
+Global limit across all packets: `Lync.configure({ globalRateLimit = { maxPerSecond = N } })`
 
-| Function / Method | What it does |
-|:-------|:----------------|
-| `Lync.enableStats()` | Activates stat counters. Call before `start()`. |
-| `packet:getBytesSent()` | Wire bytes produced (includes batch header overhead). |
-| `packet:getBytesReceived()` | Wire bytes consumed on receive. |
-| `packet:getFires()` | Send fire count. |
-| `packet:getRecvFires()` | Receive fire count. |
-| `packet:getDrops()` | Gate rejections (rate limit, NaN, validate). |
-| `Lync.getPlayerStats(player)` | Returns `{ bytesSent, bytesReceived }` or nil. Server only. |
-| `Lync.resetStats()` | Zeros all counters in-place. |
+## Configuration
 
-## Flush Control
+`Lync.configure(options)` — call before `Lync.start()`.
 
-By default Lync flushes at 60hz (every Heartbeat). You can change this at runtime.
+| Option | Default | Description |
+|:-------|--------:|:------------|
+| `channelMaxSize` | 262,144 | Max buffer bytes per frame (4,096–1,048,576). |
+| `validationDepth` | 16 | Max recursion depth for input validation (4–32). |
+| `poolSize` | 16 | Buffer pool size (2–128). |
+| `bandwidthLimit` | none | `{ softLimit, maxStrikes }`. Per-player bandwidth throttle. |
+| `globalRateLimit` | none | `{ maxPerSecond }`. Global per-player rate limit. |
+| `stats` | `false` | Enables `packet:stats()` and `Lync.stats.player()`. |
 
-```luau
-Lync.setFlushRate(30)  -- flush every ~33ms instead of ~16ms
-Lync.flush()           -- force an immediate flush, resets the accumulator
-```
+### Lifecycle
 
-| Function | What it does |
+| Function | Description |
 |:---------|:------------|
-| `Lync.setFlushRate(hz)` | 1 to 60. Default 60. Callable at runtime. At 60hz, flushes every Heartbeat directly (no accumulator). Below 60, uses an elapsed-time accumulator with drift correction. |
-| `Lync.flush()` | Immediate flush. Skips the next scheduled Heartbeat flush to prevent double-sending and XOR chain desync. |
-
-## Security
+| `Lync.configure(options)` | Set options before start. |
+| `Lync.start()` | Initialize transport. Call once after all definitions. |
+| `Lync.started` | Read-only boolean. `true` after `start()`. |
+| `Lync.flush()` | Force an immediate send. |
+| `Lync.flushRate(hz)` | Set flush rate. 1–60. Default 60. |
 
-### Bandwidth Throttle
+### Stats
 
-Server-side per-player bandwidth strike counter. Counts consecutive oversized frames with decay. Protects against clients flooding the server.
+Enable with `Lync.configure({ stats = true })`.
 
-```luau
-Lync.setBandwidthLimit(16384, 10)  -- 16KB soft limit, 10 strikes before drop
-```
+| Function | Description |
+|:---------|:------------|
+| `packet:stats()` | `{ bytesSent, bytesReceived, fires, recvFires, drops }` |
+| `Lync.stats.player(player)` | `{ bytesSent, bytesReceived }` — server only. |
+| `Lync.stats.reset()` | Zeros all counters. |
 
-Fires `onDrop` with reason `"bandwidth"` when a player exceeds the threshold. Read failures (corrupted buffers, XOR desync) also count as strikes.
+### Debug
 
-### Unknown Codec Warning
+| Function | Description |
+|:---------|:------------|
+| `Lync.debug.pending()` | Number of in-flight query requests. Useful for detecting leaks. |
+| `Lync.debug.registrations()` | Frozen array of `{ name, id, kind, isUnreliable }` for all registered packets and queries. |
 
-If a packet uses `Lync.unknown` anywhere in its codec tree without a `validate` callback, Lync prints a warning at define time. The `unknown` codec bypasses schema validation entirely; client data goes through Roblox's sidecar without type checking. Adding `validate` suppresses the warning.
+## Limits
 
-## Packet Capture
+| Constraint | Limit |
+|:-----------|------:|
+| Packet + query registrations | 127 |
+| Buffer per frame | 256 KB default, 1 MB max |
+| Concurrent query requests | 65,536 |
+| Enum variants | 256 |
+| Bitfield bits | 32 |
+| Tagged variants | 256 |
 
-Server-only debug tool. Records raw and XOR'd buffer hex for analysis.
+## Benchmarks
 
-```luau
-Lync.startCapture("My test")
--- fire packets...
-Lync.flush()
-Lync.stopCapture()
+Run `rojo serve bench.project.json` with one server + one client.
+
+### Wire Sizes
+
+| Codec | Bytes |
+|:------|------:|
+| `bool` | 1 |
+| `int(0, 255)` | 1 |
+| `int(0, 65535)` | 2 |
+| `f16` | 2 |
+| `f32` | 4 |
+| `f64` | 8 |
+| `string` (5 chars) | 6 |
+| `string` (1000 chars) | 1002 |
+| `vec3` | 12 |
+| `vec3(0, 100, 1)` | 3 |
+| `cframe` | 24 |
+| `cframe()` | 16 |
+| `color3` | 3 |
+| entity struct (6 fields) | 34 |
+| entity compact (quantized) | 13 |
+| bitfield | 2 |
+| 100× entities | 601 |
+| 1000× bools (bitpacked) | 127 |
+
+### Codec Throughput
+
+100k iterations, isolated CPU. No networking.
+
+| Codec | Encode | Decode | Round-trips/sec |
+|:------|-------:|-------:|----------------:|
+| `bool` | 44ns | 29ns | 13.9M |
+| `int(0, 255)` | 42ns | 28ns | 14.4M |
+| `f32` | 41ns | 25ns | 15.0M |
+| `f64` | 41ns | 26ns | 14.8M |
+| `string` (10 chars) | 46ns | 60ns | 9.4M |
+| `string` (1000 chars) | 76ns | 238ns | 3.2M |
+| `vec3` | 53ns | 27ns | 12.4M |
+| `cframe` | 92ns | 144ns | 4.2M |
+| `cframe()` | 123ns | 170ns | 3.4M |
+| entity struct | 239ns | 395ns | 1.6M |
+| 100× entities | 15.2µs | 34.1µs | 20K |
+| 1000× bools | 4.3µs | 5.1µs | 107K |
+
+### Delta Savings
+
+| Codec | Full | Unchanged | Savings |
+|:------|-----:|----------:|--------:|
+| `deltaStruct` (entity) | 35B | 1B | 97% |
+| `deltaStruct` (compact) | 14B | 1B | 93% |
+| `deltaArray` (100× entity) | 602B | 1B | 100% |
+| `deltaArray` (1000× bool) | 128B | 1B | 99% |
+| `deltaMap` (string → u8) | 19B | 1B | 95% |
+
+### Network Throughput
+
+1000 fires/frame, 8 seconds, one player.
+
+| Packet | FPS | Kbps |
+|:-------|----:|-----:|
+| booleans | 60 | 2.5 |
+| entity struct | 60 | 2.3 |
+| entity compact | 60 | 2.4 |
+| bitfield flags | 60 | 2.4 |
+| cframe lossless | 60 | 2.5 |
+| cframe compressed | 60 | 2.3 |
 
-Lync.startCapture("Another test")
--- fire packets...
-Lync.flush()
-Lync.stopCapture()
+### Cross-Library Comparison
 
-Lync.dumpCaptures()  -- writes JSON to ServerStorage.LyncCapture
-```
+Same methodology as [Blink's benchmarks](https://github.com/1Axen/blink/blob/main/benchmark/Benchmarks.md): 1,000 fires/frame, same data every frame, 10 seconds.
 
-Each entry contains the label, frame number, raw hex (pre-XOR), XOR'd hex (post-XOR, nil for unreliable), byte count, and refs count. Hex is capped at 512 bytes per buffer to keep the output manageable.
+Other tool numbers from [Blink v0.17.1](https://github.com/1Axen/blink/blob/main/benchmark/Benchmarks.md) (2025-04-30).
 
-| Function | What it does |
-|:---------|:------------|
-| `Lync.startCapture(label?)` | Start recording. Tags entries with the label. |
-| `Lync.stopCapture()` | Stop recording. |
-| `Lync.dumpCaptures()` | Writes all entries as JSON to a StringValue in ServerStorage, then clears. |
-
-## Limits & Configuration
-
-Call these before `Lync.start()` unless noted otherwise.
-
-| What | Default | How to change | Notes |
-|:-----|--------:|:--------------|:------|
-| Packet types | 255 | Cant change | u8 on the wire. Each query eats 2 IDs. |
-| Buffer per channel per frame | 256 KB | `Lync.setChannelMaxSize(n)` | 4 KB to 1 MB. |
-| Concurrent queries | 65,536 | Cant change | Varint correlation IDs. Freed on response or timeout. `Lync.queryPendingCount()` returns in-flight count. Queries default to 30/s rate limit. |
-| Stats | Off | `Lync.enableStats()` | Zero overhead when off. Counters on packets and players. |
-| NaN/inf scan depth | 16 | `Lync.setValidationDepth(n)` | 4 to 32. |
-| Channel pool | 16 | `Lync.setPoolSize(n)` | 2 to 128. Extra gets GCd. |
-| Flush rate | 60 hz | `Lync.setFlushRate(n)` | 1 to 60. Runtime-safe. |
-| Bandwidth limit | 16 KB / 10 strikes | `Lync.setBandwidthLimit(n, m)` | Server-only. Per-player. |
-| Namespaces | 64 | Cant change | |
-| Delta + unreliable | Nope | Cant change | Errors at define time. |
+> [!NOTE]
+> Lync batches all sends into one buffer per frame. Other tools fire one RemoteEvent per send. Lync also includes server-side validation and bool bitpacking (1000 bools = 127B vs ~1002B). Delta compression is not exercised here — see [Delta Savings](#delta-savings).
+
+#### Entities — 100× struct(6× u8)
+
+| Tool | FPS | Kbps |
+|:-----|----:|-----:|
+| roblox | 16 | 559,364 |
+| **lync** | **60** | **3.68** |
+| blink | 42 | 41.81 |
+| zap | 39 | 41.71 |
+| bytenet | 32 | 41.64 |
+
+#### Booleans — 1000× bool
+
+| Tool | FPS | Kbps |
+|:-----|----:|-----:|
+| roblox | 21 | 353,107 |
+| **lync** | **60** | **2.49** |
+| blink | 97 | 7.91 |
+| zap | 52 | 8.10 |
+| bytenet | 35 | 8.11 |
 
 ## License