ye

Author: Axp3cter

README.md

@@ -387,7 +387,7 @@ Used as the second argument to `packet:send()` on the server.
 | `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. |
+| `Lync.bool` | 1 | true/false. Gets packed into bitfields when inside structs, and 8-per-byte when inside arrays. |
 
 ### Datatypes
 
@@ -418,7 +418,7 @@ Used as the second argument to `packet:send()` on the server.
 | 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. |
+| `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. |
@@ -505,9 +505,14 @@ Same data shapes and methodology as [Blink's benchmark suite](https://github.com
 
 ## Stats
 
+Off by default. Call `Lync.enableStats()` before `Lync.start()` to activate. When disabled, zero overhead on send and receive paths.
+
 Per-packet counters are available directly on the Packet object. Per-player counters are available via `Lync.getPlayerStats()`.
 
 ```luau
+Lync.enableStats()
+Lync.start()
+
 -- Per-packet (both sides)
 print(Net.State:getBytesSent(), Net.State:getFires(), Net.State:getDrops())
 
@@ -520,13 +525,16 @@ end
 Lync.resetStats()  -- zeros everything in-place
 ```
 
-| Method | What it returns |
+| 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. |
 
 ## Flush Control
 
@@ -539,8 +547,8 @@ Lync.flush()           -- force an immediate flush, resets the accumulator
 
 | Function | What it does |
 |:---------|:------------|
-| `Lync.setFlushRate(hz)` | 1 to 60. Default 60. Callable at runtime. |
-| `Lync.flush()` | Immediate flush. Resets the timer so you dont double-send at frame end. |
+| `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
 
@@ -558,6 +566,32 @@ Fires `onDrop` with reason `"bandwidth"` when a player exceeds the threshold. Re
 
 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.
 
+## Packet Capture
+
+Server-only debug tool. Records raw and XOR'd buffer hex for analysis.
+
+```luau
+Lync.startCapture("My test")
+-- fire packets...
+Lync.flush()
+Lync.stopCapture()
+
+Lync.startCapture("Another test")
+-- fire packets...
+Lync.flush()
+Lync.stopCapture()
+
+Lync.dumpCaptures()  -- writes JSON to ServerStorage.LyncCapture
+```
+
+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.
+
+| 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.
@@ -567,6 +601,7 @@ Call these before `Lync.start()` unless noted otherwise.
 | 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. |

bench/Run.server.luau

@@ -194,9 +194,73 @@ end
 local player = getPlayer()
 Scenarios.Ready:wait()
 
+-- Capture helper: wraps a test with startCapture/stopCapture
+local CAPTURE_FRAMES = 5
+local CAPTURE_FIRES = 100 -- keep frames under MAX_INCOMING (65536 bytes)
+
+local function captureTest(label: string, packet: any, getData: () -> any, target: Player): ()
+    Lync.startCapture(label)
+    for _ = 1, CAPTURE_FRAMES do
+        for _ = 1, CAPTURE_FIRES do
+            packet:send(getData(), target)
+        end
+        Lync.flush()
+    end
+    Lync.stopCapture()
+end
+
 -- Section 1: Lync-specific benchmarks
 print(`\n  Lync Bench  {FIRES_PER_FRAME}/frame  {DURATION}s per test\n`)
 
+-- Capture a few frames of each test before the full run
+captureTest("Static booleans", Scenarios.Booleans, function(): any
+    return true
+end, player)
+
+captureTest("Static entities", Scenarios.Entities, function(): any
+    return Scenarios.STATIC_ENTITY
+end, player)
+
+local capFrame = 0
+captureTest("Moving entities", Scenarios.Entities, function(): any
+    capFrame += 1
+    return {
+        position = Vector3.new(100.5 + capFrame * 0.1, 50.25, -200.75 + capFrame * 0.05),
+        velocity = Vector3.new(10.1, 0, -5.3),
+        health = 87.5,
+        shield = 42.0,
+        alive = true,
+        team = 2,
+    }
+end, player)
+
+local captureRandom = Random.new(42)
+captureTest("Chaotic entities", Scenarios.Entities, function(): any
+    return {
+        position = Vector3.new(
+            captureRandom:NextNumber(-500, 500),
+            captureRandom:NextNumber(0, 200),
+            captureRandom:NextNumber(-500, 500)
+        ),
+        velocity = Vector3.new(
+            captureRandom:NextNumber(-50, 50),
+            captureRandom:NextNumber(-10, 10),
+            captureRandom:NextNumber(-50, 50)
+        ),
+        health = captureRandom:NextNumber(0, 100),
+        shield = captureRandom:NextNumber(0, 100),
+        alive = captureRandom:NextNumber(0, 1) > 0.5,
+        team = captureRandom:NextInteger(1, 4),
+    }
+end, player)
+
+-- Blink tests skipped from capture: 1000 fires produce ~600KB frames
+-- which exceed MAX_INCOMING (65536) on the client and break XOR chain.
+
+Lync.dumpCaptures()
+print("  [Capture saved to ServerStorage.LyncCapture]\n")
+
+-- Full benchmarks
 runTest({
     name = "Static booleans",
     player = player,

src/Types.luau

@@ -78,6 +78,7 @@ export type Registration = {
     needsGate: boolean,
     maxPayloadBytes: number?,
     timestampMode: number,
+    _openFn: (ch: ChannelState, id: number, name: string) -> (), -- resolved at define time (#2)
 
     -- Stats counters (mutable, incremented at runtime)
     bytesSent: number,

src/api/Packet.luau

@@ -214,6 +214,9 @@ function PacketModule.define(name: string, config: PacketConfig<any>): Packet
         timestampMode
     )
 
+    -- Resolve batch opener at define time: zero branching on hot path (#2)
+    reg._openFn = Channel.resolveOpenFn(reg.timestampMode)
+
     local isDelta = (config.value :: InternalCodec<any>)._isDelta == true
 
     local fields: PacketFields = {

src/api/Query.luau

@@ -318,6 +318,8 @@ function QueryModule.define(name: string, config: QueryConfig<any, any>): Query
 
     local rateLimit = config.rateLimit or { maxPerSecond = 30 }
 
+    local Channel = require(script.Parent.Parent.internal.Channel)
+
     local reqReg, respReg = Registry.registerQueryPair(
         name,
         config.request,
@@ -328,6 +330,11 @@ function QueryModule.define(name: string, config: QueryConfig<any, any>): Query
         config.validate
     )
 
+    -- Queries use writeQuery, not writeBatch, but _openFn must be set
+    local openFn = Channel.resolveOpenFn(0)
+    reqReg._openFn = openFn
+    respReg._openFn = openFn
+
     respSignal:connect(function(resp: any, source: Player?, correlation: number): ()
         completeQuery(correlation, resp, source)
     end)

src/codec/composite/Array.luau

@@ -206,6 +206,75 @@ function Array.array(element: Codec<any>, maxCount: number?): Codec<{ any }>
     local directWrite = internal._directWrite
     local directRead = internal._directRead
 
+    local band = bit32.band
+    local bor = bit32.bor
+    local lshift = bit32.lshift
+    local rshift = bit32.rshift
+    local ceil = math.ceil
+
+    -- Bitpacked bool array: 8 bools per byte
+    if internal._isBool then
+        return table.freeze({
+            _hasUnknown = nil,
+            write = function(ch: ChannelState, value: { any }): ()
+                local len = #value
+                Varint.write(ch, len)
+                if len == 0 then
+                    return
+                end
+
+                local byteCount = ceil(len / 8)
+                local c = ch.cursor
+                if c + byteCount > ch.size then
+                    alloc(ch, byteCount)
+                end
+
+                local b = ch.buff
+                local byteIdx = 0
+                local acc = 0
+                for i = 1, len do
+                    local bit = (i - 1) % 8
+                    if value[i] then
+                        acc = bor(acc, lshift(1, bit))
+                    end
+                    if bit == 7 then
+                        buffer.writeu8(b, c + byteIdx, acc)
+                        byteIdx += 1
+                        acc = 0
+                    end
+                end
+                -- Flush remaining bits
+                if len % 8 ~= 0 then
+                    buffer.writeu8(b, c + byteIdx, acc)
+                end
+                ch.cursor = c + byteCount
+            end,
+            read = function(src: buffer, pos: number, _refs: { Instance }?): ({ boolean }, number)
+                local len, lenBytes = Varint.read(src, pos)
+
+                if maxCount and len > maxCount then
+                    error(`[Lync] Array count {len} exceeds max {maxCount}`)
+                end
+
+                local result = table.create(len)
+                if len == 0 then
+                    return result, lenBytes
+                end
+
+                local byteCount = ceil(len / 8)
+                local c = pos + lenBytes
+                for i = 1, len do
+                    local byteIdx = rshift(i - 1, 3)
+                    local bit = (i - 1) % 8
+                    local byte = buffer.readu8(src, c + byteIdx)
+                    result[i] = band(byte, lshift(1, bit)) ~= 0
+                end
+
+                return result, lenBytes + byteCount
+            end,
+        })
+    end
+
     if elementSize and directWrite and directRead then
         return table.freeze({
             _hasUnknown = (element :: any)._hasUnknown or nil,

src/index.d.ts

@@ -327,7 +327,8 @@ declare namespace Lync {
     export function flush(): void;
     export function setFlushRate(hz: number): void;
 
-    // Stats (server-only for per-player)
+    // Stats (default off; call enableStats() to activate)
+    export function enableStats(): void;
     export function getPlayerStats(player: Player): PlayerStats | undefined;
     export function resetStats(): void;
 
@@ -336,6 +337,11 @@ declare namespace Lync {
 
     // Introspection
     export function queryPendingCount(): number;
+
+    // Packet capture (server-only, debug)
+    export function startCapture(label?: string): void;
+    export function stopCapture(): void;
+    export function dumpCaptures(): void;
 }
 
 export default Lync;

src/init.luau

@@ -226,7 +226,8 @@ local Lync = {
     flush = flush,
     setFlushRate = setFlushRate,
 
-    -- Stats (server-only for per-player)
+    -- Stats (default off; call enableStats() to activate)
+    enableStats = Channel.enableStats,
     getPlayerStats = getPlayerStats,
     resetStats = resetStats,
 
@@ -235,6 +236,11 @@ local Lync = {
 
     -- Introspection
     queryPendingCount = QueryModule.pendingCount,
+
+    -- Packet capture (server-only, debug)
+    startCapture = if IS_SERVER then Server.startCapture else nil,
+    stopCapture = if IS_SERVER then Server.stopCapture else nil,
+    dumpCaptures = if IS_SERVER then Server.dumpCaptures else nil,
 }
 
 Lync.default = Lync