@axpecter/lync 2.3.1 → 2.3.3

package/README.md

@@ -16,7 +16,7 @@ Schemas, packets, queries, groups, validation, rate limiting. Every send batches
 Wally — add to your `wally.toml`:
 
 ```toml
-Lync = "axp3cter/lync@2.3.1"
+Lync = "axp3cter/lync@2.3.3"
 ```
 
 npm (roblox-ts):
@@ -250,8 +250,9 @@ Enable with `Lync.configure({ stats = true })`.
 | Codec | Bytes | Notes |
 |:---|---:|:---|
 | `int(min, max)` | 1 / 2 / 4 | Picks narrowest u8/u16/u32/i8/i16/i32. |
+| `zint(min?, max?)` | 1 – 5 | Variable-length signed via zigzag varint. 1 byte for [-96, 95]. |
 | `f16` / `f32` / `f64` | 2 / 4 / 8 | `f16` ≈ ±65504, ~3 digits. |
-| `float(min, max, precision)` | 1 / 2 / 4 | Quantized; clamped to range. |
+| `float(min, max, precision)` | 1 / 2 / 3 / 4 | Quantized; picks u8 / u16 / u24 / u32 wire form. |
 | `bool` | 1 | Auto-bitpacked inside `struct` and `array`. |
 
 ### Strings & buffers
@@ -284,8 +285,8 @@ Call as a function for compression.
 
 | Codec | Bytes | Notes |
 |:---|---:|:---|
-| `vec2(min, max, precision)` | 2 / 4 / 8 | Per-component quantization. |
-| `vec3(min, max, precision)` | 3 / 6 / 12 | Per-component quantization. |
+| `vec2(min, max, precision)` | 2 / 4 / 6 / 8 | Per-component, narrowest fitting width. |
+| `vec3(min, max, precision)` | 3 / 6 / 9 / 12 | Per-component, narrowest fitting width. |
 | `cframe()` | 16 | Smallest-three quaternion. ≤ 0.16° rotation error. |
 
 ### Composites
@@ -301,13 +302,20 @@ Call as a function for compression.
 
 ### Delta — reliable transport only
 
-Sends 1 byte when the value is byte-equal to the cached previous frame.
+Tracks the previous frame's value and ships only what changed. Rejected on `unreliable = true`.
 
-| Codec | Notes |
-|:---|:---|
-| `deltaStruct(schema)` | Per-segment dirty bitmap; single-segment fast path. |
-| `deltaArray(c, max?)` | Whole-array byte-equality. |
-| `deltaMap(k, v, max?)` | Whole-map byte-equality. |
+| Codec | Static | Mutation |
+|:---|:---:|:---:|
+| `deltaStruct(schema)` | 1 B | per-field |
+| `deltaArray(c, max?)` | 1 B | per-changed-index |
+| `deltaMap(k, v, max?)` | 1 B | per-changed-key |
+| `deltaInt(min, max)` | 1 B | 1–5 B |
+| `deltaFloat(min, max, precision)` | 1 B | 1–5 B |
+| `deltaVec3(min, max, precision)` | 3 B | 3–15 B |
+| `deltaCFrame(posMin, posMax, precision)` | 1 B | 4–13 B |
+
+- `deltaArray` element / `deltaMap` key+value cannot themselves contain delta state. Use `deltaStruct` for per-field deltas inside.
+- `deltaVec3` and `deltaCFrame` error on out-of-range components.
 
 ### Meta
 
@@ -351,21 +359,23 @@ Global per-player cap: `Lync.configure({ globalRateLimit = { maxPerSecond = N }
 | Tool | `array<entity>[100]` | `array<bool>[1000]` |
 |:---|:---|:---|
 | roblox | 16 fps · 559,364 Kbps | 21 fps · 353,107 Kbps |
-| **lync** | **60 fps · 3.44 Kbps** | **60 fps · 2.46 Kbps** |
+| **lync** | **59 fps · 3.37 Kbps** | **61 fps · 2.45 Kbps** |
 | blink | 42 fps · 41.81 Kbps | 97 fps · 7.91 Kbps |
 | zap | 39 fps · 41.71 Kbps | 52 fps · 8.10 Kbps |
 | bytenet | 32 fps · 41.64 Kbps | 35 fps · 8.11 Kbps |
 
 ### Network bandwidth — 100 fires/frame, 8 s
 
-| Workload | Kbps |
-|:---|---:|
-| `array<entity>[100]` randomised | 3,608 |
-| `array<entity>[100]` reused | **2.4** |
-| `array<bool>[1000]` randomised | 763 |
-| `array<bool>[1000]` 1 bit flipped | **20.5** |
-| `struct(state)` randomised | 201 |
-| `deltaStruct(state)` 1 field mutated | **29.2** |
+| Workload | Naive Kbps | Optimized | Savings |
+|:---|---:|:---|---:|
+| `array<entity>[100]` random | 3,607 | `deltaArray` 3 of 100 mutated | **154** (–96%) |
+| `array<entity>[100]` reused | 3,607 | XOR baseline (identical frames) | **2.4** (–99.9%) |
+| `array<bool>[1000]` random | 762 | XOR baseline (1 bit flipped) | **20.4** (–97%) |
+| `struct(state)` random | 201 | `deltaStruct` 1 field mutated | **29.0** (–86%) |
+| `map<id, vec3>[200]` 5 keys mutated | 657 | `deltaMap` 5 keys mutated | **393** (–40%) |
+| `array<cframe>[50]` random | 4,585 | — | — |
+| `vec3` walking motion (continuous diff) | — | `deltaVec3` | **19.5** |
+| `CFrame` walking pose (pos + rot) | — | `deltaCFrame` | **41.1** |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@axpecter/lync",
-    "version": "2.3.1",
+    "version": "2.3.3",
     "description": "Buffer networking for Roblox. Delta compression, XOR framing, built-in security",
     "main": "src/init.luau",
     "types": "src/index.d.ts",

package/src/Types.luau

@@ -12,17 +12,18 @@ export type ChannelState = {
     itemCount: number,
     singleMode: boolean,
     singlePos: number,
-    deltas: { [number]: DeltaCacheEntry },
+    --[[
+        Per-codec write-side delta state, keyed by deltaId. Shape is opaque
+        and codec-internal: deltaStruct stores `{raw, len, segOff, segLen}`,
+        deltaArray stores `{perIdx, length}`, deltaMap stores `{perKey}`,
+        delta scalars store quantized previous values.
+    ]]
+    deltas: { [number]: any },
     prevDump: buffer?,
     prevDumpLen: number,
     currentPacket: string?,
 }
 
-export type DeltaCacheEntry = {
-    raw: buffer,
-    len: number,
-}
-
 export type Codec<T> = {
     write: (ch: ChannelState, value: T) -> (),
     read: (src: buffer, pos: number, refs: { Instance }?) -> (T, number),
@@ -39,6 +40,11 @@ export type InternalCodec<T> = {
     _directWrite: ((b: buffer, offset: number, value: T) -> ())?,
     _directRead: ((b: buffer, offset: number) -> T)?,
     _isDelta: boolean?,
+    --[[
+        True if any nested codec is delta. Lets the broadcast hot path skip
+        encode-once when delta state would diverge per-receiver.
+    ]]
+    _hasDelta: boolean?,
     _isBool: boolean?,
     _hasUnknown: boolean?,
     _min: number?,

package/src/api/Packet.luau

@@ -11,6 +11,7 @@ local Log = require(script.Parent.Parent.util.Log)
 local Middleware = require(script.Parent.Parent.internal.Middleware)
 local Player = require(script.Parent.Parent.util.Player)
 local Registry = require(script.Parent.Parent.internal.Registry)
+local Shared = require(script.Parent.Parent.codec.composite.Shared)
 local Transport = require(script.Parent.Parent.internal.Transport)
 local Types = require(script.Parent.Parent.Types)
 
@@ -129,14 +130,100 @@ function Packet.define<T>(
         return false, sendData
     end
 
-    -- Caller has already run send middleware once for the broadcast.
+    -- Non-delta codecs are stateless wire-encoders, so broadcast can encode
+    -- once and bufCopy the payload to every player. Falls through if the
+    -- encoded payload includes ref indices (the indices would need rewriting
+    -- per channel, which no codec exposes).
+    local canEncodeOnce = not codec._isDelta and not codec._hasDelta
+
     local function broadcast(players: { Player }, data: any): ()
-        for _, p in players do
-            sendToPlayer(p, data)
+        local count = #players
+        if count == 0 then
+            bumpFires()
+            return
+        end
+
+        if canEncodeOnce then
+            local scratch = Shared.acquireScratch()
+            scratch.currentPacket = name
+            codec.write(scratch, data)
+            scratch.currentPacket = nil
+            if scratch.refCount == 0 then
+                local payload = scratch.buff
+                local payloadLen = scratch.cursor
+                local server = Transport.server()
+                local getChannel = if isUnreliable
+                    then server.getUnreliableChannel
+                    else server.getReliableChannel
+                -- Channel.writeBatchEncoded is hot-swapped by enableStats; re-read per call.
+                local writeBatchEncoded = Channel.writeBatchEncoded
+                for i = 1, count do
+                    writeBatchEncoded(getChannel(players[i]), reg, payload, payloadLen)
+                end
+                Shared.releaseScratch()
+                bumpFires()
+                return
+            end
+            Shared.releaseScratch()
+        end
+
+        for i = 1, count do
+            sendToPlayer(players[i], data)
         end
         bumpFires()
     end
 
+    --[[
+        Resolve a target table into a { Player } list. Returns nil for unknown
+        sentinel kinds; the caller errors with the original target type.
+    ]]
+    local function resolveAudience(target: any): { Player }?
+        local kind = target._lyncKind
+        if kind == "all" then
+            return Players:GetPlayers()
+        end
+
+        if kind == "except" then
+            local excluded = target._excluded :: { [Player]: boolean }
+            local all = Players:GetPlayers()
+            local list = table.create(#all)
+            local n = 0
+            for _, player in all do
+                if not excluded[player] then
+                    n += 1
+                    list[n] = player
+                end
+            end
+            return list
+        end
+
+        if kind == "group" then
+            local members = target._members :: { [Player]: boolean }
+            local list: { Player } = {}
+            local n = 0
+            for player in members do
+                n += 1
+                list[n] = player
+            end
+            return list
+        end
+
+        if kind == nil then
+            -- Plain { Player } array. Validate entries on the way to a clean list.
+            local list: { Player } = {}
+            local n = 0
+            for _, player in target do
+                if isPlayer(player) then
+                    n += 1
+                    list[n] = player :: Player
+                end
+            end
+            return list
+        end
+
+        return nil
+    end
+
     local function sendToTarget(data: any, target: any): ()
         if isPlayer(target) then
             local dropped, sendData = applySend(data, target :: Player)
@@ -153,40 +240,11 @@ function Packet.define<T>(
             if dropped then
                 return
             end
-
-            local kind = target._lyncKind
-            if kind == "all" then
-                broadcast(Players:GetPlayers(), sendData)
-                return
-            end
-
-            if kind == "except" then
-                local excluded = target._excluded :: { [Player]: boolean }
-                for _, p in Players:GetPlayers() do
-                    if not excluded[p] then
-                        sendToPlayer(p, sendData)
-                    end
-                end
-                bumpFires()
-                return
-            end
-
-            if kind == "group" then
-                for p in target._members :: { [Player]: boolean } do
-                    sendToPlayer(p, sendData)
-                end
-                bumpFires()
+            local audience = resolveAudience(target)
+            if audience then
+                broadcast(audience, sendData)
                 return
             end
-
-            -- Plain { Player } array.
-            for _, p in target do
-                if isPlayer(p) then
-                    sendToPlayer(p :: Player, sendData)
-                end
-            end
-            bumpFires()
-            return
         end
 
         Log.error(`"{name}" expected Player, table, Group, or Lync.all, got {typeof(target)}`)

package/src/api/Query.luau

@@ -44,10 +44,10 @@ local function writeQueryTracked(
 ): ()
     if Channel.statsEnabled() then
         local before = ch.cursor
-        Channel.writeQuery(ch, reg.id, corrId, codec, data)
+        Channel.writeQuery(ch, reg.id, corrId, codec, data, reg.name)
         reg.bytesSent += ch.cursor - before
     else
-        Channel.writeQuery(ch, reg.id, corrId, codec, data)
+        Channel.writeQuery(ch, reg.id, corrId, codec, data, reg.name)
     end
 end
 

package/src/api/Signal.luau

@@ -17,11 +17,16 @@ local _freeThread: thread? = nil
 
 -- Private ----------------------------------------------------------------
 
+-- pcall wrapper: a handler error must not consume the recycled thread, otherwise
+-- every subsequent fire pays a coroutine.create until process restart.
 local function passer(fn: (...any) -> (), ...): ()
     local thread = _freeThread
     _freeThread = nil
-    fn(...)
+    local ok, err = pcall(fn, ...)
     _freeThread = thread
+    if not ok then
+        task.spawn(error, err)
+    end
 end
 
 local function yielder(): ()

package/src/codec/Base.luau

@@ -7,7 +7,7 @@ local Types = require(script.Parent.Parent.Types)
 
 -- Constants --------------------------------------------------------------
 
-local DEFAULT_MAX = 262144
+local DEFAULT_MAX = 1048576
 local INITIAL_BUF = 1024
 
 -- State ------------------------------------------------------------------
@@ -56,6 +56,13 @@ local Base = {}
 Base.INITIAL_BUF = INITIAL_BUF
 Base.alloc = alloc
 
+-- Cheap inline guard hoisted into every codec that grows a channel directly.
+function Base.ensure(ch: Types.ChannelState, n: number): ()
+    if ch.cursor + n > ch.size then
+        alloc(ch, n)
+    end
+end
+
 -- Floor is INITIAL_BUF: anything smaller errors on the very first write.
 function Base.setMaxSize(bytes: number): ()
     if bytes < INITIAL_BUF then