ye

Author: Axp3cter

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.2"
 ```
 
 npm (roblox-ts):
@@ -314,6 +314,9 @@ Tracks the previous frame's value and ships only what changed. Rejected on `unre
 | `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
 
 | Codec | Notes |

bench/Scenarios.luau

@@ -399,14 +399,14 @@ local blinkCases: { NetCase } = table.freeze({
     of POOL_SIZE values forming a realistic mutation stream so the bench
     measures steady-state cache behavior, not first-frame FULL cost.
 ]]
-local function poolEntityArrSparseMut(): { { any } }
+local function poolEntityArrSparseMut(count: number): { { any } }
     -- Stable array shape; 3 random indices flip per frame to exercise PATCH.
-    local current = entityArr(ENT_COUNT)
+    local current = entityArr(count)
     local p = table.create(POOL_SIZE)
     p[1] = table.clone(current)
     for frame = 2, POOL_SIZE do
         for _ = 1, 3 do
-            local idx = rng:NextInteger(1, ENT_COUNT)
+            local idx = rng:NextInteger(1, count)
             current[idx] = entity()
         end
         p[frame] = table.clone(current)
@@ -462,7 +462,25 @@ local function poolCFrameStream(): { CFrame }
 end
 
 local positionsCodec = Lync.deltaVec3(-1000, 1000, 0.01)
+local positionsBaseline = Lync.vec3(-1000, 1000, 0.01)
 local cframeStreamCodec = Lync.deltaCFrame(-1000, 1000, 0.01)
+local cframeStreamBaseline = Lync.cframe()
+local counterCodec = Lync.deltaInt(0, 1000000)
+local counterBaseline = Lync.int(0, 1000000)
+
+local function poolCounterStream(): { number }
+    local p = table.create(POOL_SIZE)
+    for i = 1, POOL_SIZE do
+        p[i] = i
+    end
+    return table.freeze(p) :: { number }
+end
+
+-- Shared pools so each delta/full pair drives the same input stream.
+local sharedPositionMap = poolPositionMap()
+local sharedPositionStream = poolPositionStream()
+local sharedCFrameStream = poolCFrameStream()
+local sharedCounterStream = poolCounterStream()
 
 --[[
     Extended workloads at 100 fires/frame. Pairs vary/stable cases on the
@@ -484,7 +502,29 @@ local extendedCases: { NetCase } = table.freeze({
             return entityArr(ENT_COUNT)
         end)
     ),
-    defCase("entity_deltaArr_100__3mut", entityDeltaArray, poolEntityArrSparseMut()),
+    defCase(
+        "entity_arr_400__vary",
+        entityArray,
+        poolVarying(function()
+            return entityArr(400)
+        end)
+    ),
+    defCase("entity_deltaArr_400__3mut", entityDeltaArray, poolEntityArrSparseMut(400)),
+    defCase(
+        "entity_deltaArr_400__stable",
+        entityDeltaArray,
+        poolShared(function()
+            return entityArr(400)
+        end)
+    ),
+    defCase("entity_deltaArr_100__3mut", entityDeltaArray, poolEntityArrSparseMut(ENT_COUNT)),
+    defCase(
+        "entity_deltaArr_100__stable",
+        entityDeltaArray,
+        poolShared(function()
+            return entityArr(ENT_COUNT)
+        end)
+    ),
     defCase(
         "bool_arr_1000__vary",
         boolArray,
@@ -502,10 +542,25 @@ local extendedCases: { NetCase } = table.freeze({
     ),
     defCase("state_full__vary", stateCodec, poolVarying(stateOne)),
     defCase("state_delta__1mut", stateDelta, poolStateOneMut()),
-    defCase("position_map_200__5mut", positionMap, poolPositionMap()),
-    defCase("position_deltaMap_200__5mut", positionDeltaMap, poolPositionMap()),
-    defCase("vec3_walking_motion", positionsCodec, poolPositionStream()),
-    defCase("cframe_walking_pose", cframeStreamCodec, poolCFrameStream()),
+    defCase("position_map_200__5mut", positionMap, sharedPositionMap),
+    defCase("position_deltaMap_200__5mut", positionDeltaMap, sharedPositionMap),
+    defCase(
+        "position_deltaMap_200__stable",
+        positionDeltaMap,
+        poolShared(function(): { [number]: Vector3 }
+            local m: { [number]: Vector3 } = {}
+            for i = 1, 200 do
+                m[i] = Vector3.new(rng:NextNumber(-100, 100), 0, rng:NextNumber(-100, 100))
+            end
+            return m
+        end)
+    ),
+    defCase("vec3_walking__full", positionsBaseline, sharedPositionStream),
+    defCase("vec3_walking__delta", positionsCodec, sharedPositionStream),
+    defCase("cframe_walking__full", cframeStreamBaseline, sharedCFrameStream),
+    defCase("cframe_walking__delta", cframeStreamCodec, sharedCFrameStream),
+    defCase("counter_int__full", counterBaseline, sharedCounterStream),
+    defCase("counter_int__delta", counterCodec, sharedCounterStream),
 })
 
 -- Handshake --------------------------------------------------------------

package.json

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

src/api/Packet.luau

@@ -130,18 +130,10 @@ function Packet.define<T>(
         return false, sendData
     end
 
-    --[[
-        Encode-once fanout. For non-delta codecs the wire bytes are stateless
-        (same input -> same bytes), so we encode into a scratch channel once
-        and bufCopy the payload into each player's channel. Falls through to
-        the per-player path when the encode emitted Instance refs — renumbering
-        refs across channels needs per-ref offset tracking that no codec
-        exposes today.
-
-        Channel.writeBatchEncoded is hot-swapped at startup by enableStats,
-        so it MUST be re-read per call — capturing at packet-define time
-        would leave broadcast on the plain variant after a stats flip.
-    ]]
+    -- 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): ()
@@ -153,15 +145,22 @@ function Packet.define<T>(
 
         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()
+                -- Channel.writeBatchEncoded is hot-swapped by enableStats; re-read per call.
                 local writeBatchEncoded = Channel.writeBatchEncoded
                 for i = 1, count do
-                    local ch = server.getChannel(players[i], isUnreliable)
-                    writeBatchEncoded(ch, reg, payload, payloadLen)
+                    writeBatchEncoded(
+                        server.getChannel(players[i], isUnreliable),
+                        reg,
+                        payload,
+                        payloadLen
+                    )
                 end
                 Shared.releaseScratch()
                 bumpFires()

src/codec/Base.luau

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

src/codec/composite/Array.luau

@@ -19,29 +19,27 @@ local DA_PATCH = 2
 -- Private ----------------------------------------------------------------
 
 local alloc = Base.alloc
+local ensure = Base.ensure
 local allocDeltaId = Shared.allocDeltaId
 local acquireScratch = Shared.acquireScratch
 local releaseScratch = Shared.releaseScratch
 local rangeEqual = Shared.rangeEqual
 local copyToBuf = Shared.copyToBuf
+local containsDelta = Shared.containsDelta
+local enforceMaxCount = Shared.enforceMaxCount
 local boolBytes = Shared.boolBytes
 local packBoolArray = Shared.packBoolArray
 local unpackBoolArray = Shared.unpackBoolArray
 local varintRead = Varint.read
 local varintWrite = Varint.write
+local varintLength = Varint.length
 local writeu8 = buffer.writeu8
 local readu8 = buffer.readu8
 local bufCopy = buffer.copy
 local bufLen = buffer.len
 
 type DeltaArrayEntry = { eBuf: buffer, eLen: number }
 
-local function ensure(ch: Types.ChannelState, n: number): ()
-    if ch.cursor + n > ch.size then
-        alloc(ch, n)
-    end
-end
-
 -- Bit-packed bool element fast path: 1 bit per entry instead of 1 byte.
 local function makeBoolArray(
     element: Types.InternalCodec<any>,
@@ -60,9 +58,7 @@ local function makeBoolArray(
 
         read = function(src: buffer, pos: number, _refs: { Instance }?): ({ boolean }, number)
             local len, lenBytes = varintRead(src, pos)
-            if maxCount and len > maxCount then
-                Log.error(`count {len} exceeds max {maxCount}`)
-            end
+            enforceMaxCount(len, maxCount)
             if len == 0 then
                 return {}, lenBytes
             end
@@ -115,9 +111,7 @@ local function makeDirectArray(
 
         read = function(src: buffer, pos: number, _refs: { Instance }?): ({ any }, number)
             local len, lenBytes = varintRead(src, pos)
-            if maxCount and len > maxCount then
-                Log.error(`count {len} exceeds max {maxCount}`)
-            end
+            enforceMaxCount(len, maxCount)
             if len == 0 then
                 return {}, lenBytes
             end
@@ -159,9 +153,7 @@ local function makeGenericArray(
 
         read = function(src: buffer, pos: number, refs: { Instance }?): ({ any }, number)
             local len, lenBytes = varintRead(src, pos)
-            if maxCount and len > maxCount then
-                Log.error(`count {len} exceeds max {maxCount}`)
-            end
+            enforceMaxCount(len, maxCount)
             if len == 0 then
                 return {}, lenBytes
             end
@@ -202,7 +194,7 @@ function Array.array(element: Types.InternalCodec<any>, maxCount: number?): Type
     if element._hasUnknown then
         codec._hasUnknown = true
     end
-    if element._isDelta or element._hasDelta then
+    if containsDelta(element) then
         codec._hasDelta = true
     end
     return table.freeze(codec)
@@ -225,6 +217,11 @@ function Array.deltaArray(
     element: Types.InternalCodec<any>,
     maxCount: number?
 ): Types.InternalCodec<any>
+    -- Inner delta would chain-diff across elements within a frame, not across frames.
+    if containsDelta(element) then
+        Log.error("deltaArray element cannot contain delta state")
+    end
+
     local deltaId = allocDeltaId()
     local inner = Array.array(element, maxCount)
 
@@ -238,9 +235,7 @@ function Array.deltaArray(
         value: { any }
     ): (number, { number }, { number })
         local len = #value
-        if maxCount and len > maxCount then
-            Log.error(`count {len} exceeds max {maxCount}`)
-        end
+        enforceMaxCount(len, maxCount)
         local off = table.create(len)
         local elen = table.create(len)
         for i = 1, len do
@@ -275,11 +270,9 @@ function Array.deltaArray(
                 ch.cursor += 1
                 varintWrite(ch, len)
                 local payloadLen = scratch.cursor
-                if payloadLen > 0 then
-                    ensure(ch, payloadLen)
-                    bufCopy(ch.buff, ch.cursor, scratchBuf, 0, payloadLen)
-                    ch.cursor += payloadLen
-                end
+                ensure(ch, payloadLen)
+                bufCopy(ch.buff, ch.cursor, scratchBuf, 0, payloadLen)
+                ch.cursor += payloadLen
 
                 local perIdx: { [number]: DeltaArrayEntry } = {}
                 for i = 1, len do
@@ -323,20 +316,17 @@ function Array.deltaArray(
                 return
             end
 
-            -- PATCH cost vs FULL: every changed index pays an index varint.
-            -- When index headers approach the count cost, FULL wins outright.
-            if changedCount * 2 >= len then
-                ensure(ch, 1)
-                writeu8(ch.buff, ch.cursor, DA_FULL)
-                ch.cursor += 1
-                varintWrite(ch, len)
-                local payloadLen = scratch.cursor
-                if payloadLen > 0 then
-                    ensure(ch, payloadLen)
-                    bufCopy(ch.buff, ch.cursor, scratchBuf, 0, payloadLen)
-                    ch.cursor += payloadLen
-                end
-            else
+            -- Pick FULL vs PATCH on actual byte cost. Both share `1 + varintLength(len)`
+            -- so it cancels: compare PATCH's index-header overhead + changed payload
+            -- against FULL's full payload.
+            local fullPayload = scratch.cursor
+            local patchPayload = varintLength(changedCount)
+            for i = 1, changedCount do
+                local idx = changed[i]
+                patchPayload += varintLength(idx) + elen[idx]
+            end
+
+            if patchPayload < fullPayload then
                 ensure(ch, 1)
                 writeu8(ch.buff, ch.cursor, DA_PATCH)
                 ch.cursor += 1
@@ -346,12 +336,18 @@ function Array.deltaArray(
                     local idx = changed[i]
                     varintWrite(ch, idx)
                     local n = elen[idx]
-                    if n > 0 then
-                        ensure(ch, n)
-                        bufCopy(ch.buff, ch.cursor, scratchBuf, off[idx], n)
-                        ch.cursor += n
-                    end
+                    ensure(ch, n)
+                    bufCopy(ch.buff, ch.cursor, scratchBuf, off[idx], n)
+                    ch.cursor += n
                 end
+            else
+                ensure(ch, 1)
+                writeu8(ch.buff, ch.cursor, DA_FULL)
+                ch.cursor += 1
+                varintWrite(ch, len)
+                ensure(ch, fullPayload)
+                bufCopy(ch.buff, ch.cursor, scratchBuf, 0, fullPayload)
+                ch.cursor += fullPayload
             end
 
             -- Update cache: refresh changed (and appended), drop truncated.
@@ -412,19 +408,29 @@ function Array.deltaArray(
                 if lLen == 0 then
                     Log.error("truncated deltaArray length")
                 end
+                enforceMaxCount(newLen, maxCount, "newLen")
                 total += lLen
 
                 local changeCount, cLen = varintRead(src, pos + total)
                 if cLen == 0 then
                     Log.error("truncated deltaArray change count")
                 end
+                -- changeCount is also bounded by newLen: every index appears at most once.
+                if changeCount > newLen then
+                    Log.error(`deltaArray changeCount {changeCount} exceeds newLen {newLen}`)
+                end
                 total += cLen
 
                 for _ = 1, changeCount do
                     local idx, iLen = varintRead(src, pos + total)
                     if iLen == 0 then
                         Log.error("truncated deltaArray index")
                     end
+                    -- Reject out-of-range idx so the wire can't poison the cache with
+                    -- arbitrary keys that survive truncation.
+                    if idx < 1 or idx > newLen then
+                        Log.error(`deltaArray index {idx} out of range [1, {newLen}]`)
+                    end
                     total += iLen
                     local v, vc = element.read(src, pos + total, refs)
                     if vc == 0 then