@axpecter/lync 2.3.1 → 2.3.2

package/src/codec/primitive/Zint.luau

@@ -0,0 +1,99 @@
+--!strict
+--!native
+-- Signed varint via zigzag mapping. Small magnitudes pack in 1 byte.
+
+local Log = require(script.Parent.Parent.Parent.util.Log)
+local Types = require(script.Parent.Parent.Parent.Types)
+local Varint = require(script.Parent.Parent.primitive.Varint)
+
+-- Constants --------------------------------------------------------------
+
+--[[
+    Zigzag fold maps signed values onto unsigned varint space:
+      n >= 0  -> 2n
+      n < 0   -> -2n - 1
+    Inverse: low bit selects sign, shift down 1 bit.
+
+    Wire ranges (using Varint dense form):
+      1 byte: [-96, 95]
+      2 bytes: [-4192, 4191]
+      3 bytes: [-528480, 528479]
+      5 bytes: full i32
+]]
+local I32_MIN = -0x80000000
+local I32_MAX = 0x7FFFFFFF
+
+-- Private ----------------------------------------------------------------
+
+local floor = math.floor
+local band = bit32.band
+local varintWrite = Varint.write
+local varintRead = Varint.read
+
+-- Signed -> unsigned. Hot path; called per write of every delta scalar.
+local function encode(value: number): number
+    if value >= 0 then
+        return value * 2
+    end
+    return value * -2 - 1
+end
+
+-- Inverse of encode. Even -> n/2; odd -> -((n+1)/2). Branchless on the half.
+local function decode(raw: number): number
+    local low = band(raw, 1)
+    local half = (raw - low) / 2
+    return if low == 1 then -half - 1 else half
+end
+
+-- Public -----------------------------------------------------------------
+
+local Zint = {}
+
+Zint.encode = encode
+Zint.decode = decode
+
+--[[
+    Variable-length signed integer in [I32_MIN, I32_MAX]. Optional [min, max]
+    bounds gate input at write time so out-of-range payloads error early
+    rather than corrupting downstream decoders.
+]]
+function Zint.zint(min: number?, max: number?): Types.InternalCodec<number>
+    local lo = min or I32_MIN
+    local hi = max or I32_MAX
+    if lo > hi then
+        Log.error(`min ({lo}) must be <= max ({hi})`)
+    end
+    if floor(lo) ~= lo or floor(hi) ~= hi then
+        Log.error("bounds must be integers")
+    end
+    if lo < I32_MIN or hi > I32_MAX then
+        Log.error(`range [{lo}, {hi}] exceeds i32 bounds`)
+    end
+
+    return table.freeze({
+        _typeCheck = "number",
+        _isInteger = true,
+        _min = lo,
+        _max = hi,
+
+        write = function(ch: Types.ChannelState, value: number): ()
+            if value < lo or value > hi then
+                Log.error(`value {value} out of range [{lo}, {hi}]`)
+            end
+            if floor(value) ~= value then
+                Log.error(`value {value} must be an integer`)
+            end
+            varintWrite(ch, encode(value))
+        end,
+
+        read = function(src: buffer, pos: number, _refs: { Instance }?): (number, number)
+            local raw, consumed = varintRead(src, pos)
+            if consumed == 0 then
+                Log.error("truncated zint")
+            end
+            return decode(raw), consumed
+        end,
+    }) :: Types.InternalCodec<number>
+end
+
+return table.freeze(Zint)

package/src/index.d.ts

@@ -265,12 +265,58 @@ interface LyncModule {
     // ── Number codecs ───────────────────────────────────────────────────
 
     int(this: void, min: number, max: number): Lync.Codec<number>;
+    /**
+     * Variable-length signed int via zigzag varint. 1 byte for values in
+     * [-96, 95]; up to 5 bytes for full i32. Optional bounds gate input.
+     */
+    zint(this: void, min?: number, max?: number): Lync.Codec<number>;
     float(this: void, min: number, max: number, precision: number): Lync.Codec<number>;
     readonly f16: Lync.Codec<number>;
     readonly f32: Lync.Codec<number>;
     readonly f64: Lync.Codec<number>;
     readonly bool: Lync.Codec<boolean>;
 
+    // ── Delta scalars (reliable transport only) ─────────────────────────
+
+    /**
+     * Integer that emits zigzag varint of (current - previous). Reliable
+     * transport only; a dropped frame desyncs the receiver. Best for ints
+     * mutating slowly across a wide range (saves vs fixed u16/u24/u32).
+     */
+    deltaInt(this: void, min: number, max: number): Lync.Codec<number>;
+    /**
+     * Quantized float with per-frame diff in integer wire space (no drift).
+     * Same wire-size profile as deltaInt. Reliable transport only.
+     */
+    deltaFloat(
+        this: void,
+        min: number,
+        max: number,
+        precision: number,
+    ): Lync.Codec<number>;
+    /**
+     * Quantized Vector3 with per-axis zigzag varint diffs. ~3 bytes for
+     * unchanged, 3-15 bytes for typical motion vs 12 bytes baseline.
+     * Reliable transport only.
+     */
+    deltaVec3(
+        this: void,
+        min: number,
+        max: number,
+        precision: number,
+    ): Lync.Codec<Vector3>;
+    /**
+     * Quantized position + smallest-three quaternion rotation. 1 byte for
+     * fully static; 4-7 bytes for position-only motion; up to 13 bytes
+     * for full pose changes vs 24 bytes baseline. Reliable transport only.
+     */
+    deltaCFrame(
+        this: void,
+        posMin: number,
+        posMax: number,
+        posPrecision: number,
+    ): Lync.Codec<CFrame>;
+
     // ── String & buffer ─────────────────────────────────────────────────
 
     readonly string: Lync.StringCodec;

package/src/init.luau

@@ -27,6 +27,7 @@ local BufferC = require(script.codec.datatype.Buffer)
 local CFrameC = require(script.codec.datatype.CFrame)
 local ColorC = require(script.codec.datatype.Color)
 local CustomC = require(script.codec.meta.Custom)
+local DeltaScalarC = require(script.codec.meta.DeltaScalar)
 local EnumC = require(script.codec.meta.Enum)
 local Float16C = require(script.codec.primitive.Float16)
 local FloatC = require(script.codec.meta.Float)
@@ -49,6 +50,7 @@ local TupleC = require(script.codec.composite.Tuple)
 local UDimC = require(script.codec.datatype.UDim)
 local UnknownC = require(script.codec.meta.Unknown)
 local VectorC = require(script.codec.datatype.Vector)
+local ZintC = require(script.codec.primitive.Zint)
 
 -- Public types -----------------------------------------------------------
 
@@ -313,7 +315,12 @@ Lync.debug = table.freeze({
 })
 
 Lync.int = IntC.int
+Lync.zint = ZintC.zint
 Lync.float = FloatC.float
+Lync.deltaInt = DeltaScalarC.deltaInt
+Lync.deltaFloat = DeltaScalarC.deltaFloat
+Lync.deltaVec3 = DeltaScalarC.deltaVec3
+Lync.deltaCFrame = DeltaScalarC.deltaCFrame
 Lync.f16 = Float16C.f16
 Lync.f32 = NumberC.f32
 Lync.f64 = NumberC.f64

package/src/internal/Channel.luau

@@ -48,6 +48,7 @@ local EMPTY_REFS = table.freeze({}) :: { Instance }
 -- Private ----------------------------------------------------------------
 
 local alloc = Base.alloc
+local ensure = Base.ensure
 local band = bit32.band
 local bor = bit32.bor
 local bufCopy = buffer.copy
@@ -57,12 +58,6 @@ local writef64 = buffer.writef64
 local round = math.round
 local osClock = os.clock
 
-local function ensure(ch: Types.ChannelState, n: number): ()
-    if ch.cursor + n > ch.size then
-        alloc(ch, n)
-    end
-end
-
 local function writeTimestamp(b: buffer, off: number, mode: number): ()
     if mode == TS_FRAME then
         writeu8(b, off, _frameCounter)
@@ -89,10 +84,7 @@ local function upgradeSingleToMulti(ch: Types.ChannelState, regId: number, heade
     ensure(ch, 2)
     -- Re-bind: ensure() may have realloced the buffer.
     local b = ch.buff
-
-    if payloadLen > 0 then
-        bufCopy(b, afterTs + 2, b, afterTs, payloadLen)
-    end
+    bufCopy(b, afterTs + 2, b, afterTs, payloadLen)
 
     ch.countPos = afterTs
     writeu16(b, afterTs, 0)
@@ -100,36 +92,76 @@ local function upgradeSingleToMulti(ch: Types.ChannelState, regId: number, heade
     ch.singleMode = false
 end
 
+-- itemCount bump is left to the caller, AFTER the body write succeeds.
+local function openOrUpgrade(ch: Types.ChannelState, reg: Types.Registration): ()
+    if reg.id ~= ch.lastId or ch.itemCount >= MAX_BATCH_ITEMS then
+        reg._openFn(ch, reg.id)
+    elseif ch.singleMode then
+        upgradeSingleToMulti(ch, reg.id, reg.headerSize)
+    end
+end
+
+local function spliceEncoded(ch: Types.ChannelState, payload: buffer, payloadLen: number): ()
+    local cursor = ch.cursor
+    if cursor + payloadLen > ch.size then
+        alloc(ch, payloadLen)
+    end
+    bufCopy(ch.buff, cursor, payload, 0, payloadLen)
+    ch.cursor = cursor + payloadLen
+end
+
 --[[
-    Two writeBatch implementations, swapped at startup by enableStats(). For
-    high-rate channels this saves ~1 register read + 1 compare + 1 jump per
-    item versus branching on `_statsEnabled` inside the loop.
+    Hot-swapped by enableStats() so the per-item dispatch avoids a runtime
+    branch on the stats flag. itemCount bumps AFTER codec.write so a
+    throwing codec leaves the count consistent with the buffer.
 ]]
 local writeBatchPlain: (Types.ChannelState, Types.Registration, any) -> ()
 local writeBatchStats: (Types.ChannelState, Types.Registration, any) -> ()
 
 writeBatchPlain = function(ch: Types.ChannelState, reg: Types.Registration, data: any): ()
-    if reg.id ~= ch.lastId or ch.itemCount >= MAX_BATCH_ITEMS then
-        reg._openFn(ch, reg.id)
-    elseif ch.singleMode then
-        upgradeSingleToMulti(ch, reg.id, reg.headerSize)
-    end
-    ch.itemCount += 1
+    openOrUpgrade(ch, reg)
     reg.codec.write(ch, data)
+    ch.itemCount += 1
 end
 
 writeBatchStats = function(ch: Types.ChannelState, reg: Types.Registration, data: any): ()
-    if reg.id ~= ch.lastId or ch.itemCount >= MAX_BATCH_ITEMS then
-        reg._openFn(ch, reg.id)
-    elseif ch.singleMode then
-        upgradeSingleToMulti(ch, reg.id, reg.headerSize)
-    end
-    ch.itemCount += 1
+    openOrUpgrade(ch, reg)
     local before = ch.cursor
     reg.codec.write(ch, data)
+    ch.itemCount += 1
     reg.bytesSent += ch.cursor - before
 end
 
+--[[
+    Splice a pre-encoded payload into the channel. Used by Packet.broadcast
+    to encode the codec output once per fanout instead of N times.
+]]
+local writeBatchEncodedPlain: (Types.ChannelState, Types.Registration, buffer, number) -> ()
+local writeBatchEncodedStats: (Types.ChannelState, Types.Registration, buffer, number) -> ()
+
+writeBatchEncodedPlain = function(
+    ch: Types.ChannelState,
+    reg: Types.Registration,
+    payload: buffer,
+    payloadLen: number
+): ()
+    openOrUpgrade(ch, reg)
+    spliceEncoded(ch, payload, payloadLen)
+    ch.itemCount += 1
+end
+
+writeBatchEncodedStats = function(
+    ch: Types.ChannelState,
+    reg: Types.Registration,
+    payload: buffer,
+    payloadLen: number
+): ()
+    openOrUpgrade(ch, reg)
+    spliceEncoded(ch, payload, payloadLen)
+    ch.itemCount += 1
+    reg.bytesSent += payloadLen
+end
+
 -- Public -----------------------------------------------------------------
 
 -- Module table is intentionally unfrozen: enableStats() hot-swaps writeBatch.
@@ -252,6 +284,7 @@ function Channel.resolveOpenFn(
 end
 
 Channel.writeBatch = writeBatchPlain
+Channel.writeBatchEncoded = writeBatchEncodedPlain
 
 --[[
     Every caller (Server.flushReliable / flushUnreliable, Client.flush)
@@ -335,6 +368,7 @@ end
 function Channel.enableStats(): ()
     _statsEnabled = true
     Channel.writeBatch = writeBatchStats
+    Channel.writeBatchEncoded = writeBatchEncodedStats
 end
 
 function Channel.statsEnabled(): boolean
@@ -350,6 +384,7 @@ function Channel.resetGlobals(): ()
     _offsetMs = 0
     _clock = 0.0
     Channel.writeBatch = writeBatchPlain
+    Channel.writeBatchEncoded = writeBatchEncodedPlain
 end
 
 return Channel

package/src/transport/Reader.luau

@@ -207,17 +207,26 @@ function Reader.process(
             local doGate = isServer and reg.needsGate and player ~= nil
             local regSignal = reg.signal
             local regName = reg.name
+            -- Lync.nothing reads zero bytes; bypass the pos/consumed gates that assume forward progress.
+            local isZeroSize = sizeMeta == 0
 
             for _ = 1, count do
-                if pos >= incomingLen then
+                if not isZeroSize and pos >= incomingLen then
                     Log.warn(`codec for "{regName}" ran past frame end; aborting`)
                     return false
                 end
                 local value, consumed = regCodec.read(incoming, pos, refs)
-                if consumed == 0 then
+                if not isZeroSize and consumed == 0 then
                     Log.warn(`codec for "{regName}" reported 0 bytes; aborting`)
                     return false
                 end
+                -- Fixed-size codecs MUST report consumed == _size or `pos` desyncs silently.
+                if sizeMeta and consumed ~= sizeMeta then
+                    Log.warn(
+                        `codec for "{regName}" consumed {consumed} bytes, expected {sizeMeta}; aborting`
+                    )
+                    return false
+                end
                 pos += consumed
                 if pos > incomingLen then
                     Log.warn(`codec for "{regName}" overran frame end; aborting`)
@@ -266,13 +275,15 @@ function Reader.process(
                 end
                 reg.signal:fire(nil, player, corrId)
             else
-                if pos >= incomingLen then
+                local regCodec = reg.codec
+                -- Mirror the packet path: 0-byte response codecs (Lync.nothing) bypass the gates.
+                local qIsZeroSize = regCodec._size == 0
+                if not qIsZeroSize and pos >= incomingLen then
                     Log.warn(`query "{reg.name}" body missing; aborting`)
                     return false
                 end
-                local regCodec = reg.codec
                 local value, consumed = regCodec.read(incoming, pos, refs)
-                if consumed == 0 then
+                if not qIsZeroSize and consumed == 0 then
                     Log.warn(`query codec for "{reg.name}" reported 0 bytes; aborting`)
                     return false
                 end

package/src/util/Buffer.luau

@@ -46,11 +46,9 @@ function Buf.rangeEqual(a: buffer, offA: number, b: buffer, offB: number, len: n
     return true
 end
 
-function Buf.snapshot(src: buffer, len: number): buffer
+function Buf.snapshot(src: buffer, len: number, srcOff: number?): buffer
     local out = bufCreate(len)
-    if len > 0 then
-        bufCopy(out, 0, src, 0, len)
-    end
+    bufCopy(out, 0, src, srcOff or 0, len)
     return out
 end
 

package/src/util/Quantize.luau

@@ -10,12 +10,34 @@ local ceil = math.ceil
 local maxN = math.max
 local minN = math.min
 
+local writeu8 = buffer.writeu8
+local writeu16 = buffer.writeu16
+local readu8 = buffer.readu8
+local readu16 = buffer.readu16
+local band = bit32.band
+local bor = bit32.bor
+local rshift = bit32.rshift
+local lshift = bit32.lshift
+
+--[[
+    24-bit wire form. Splits into u16 + u8 since the buffer API has no native
+    u24. Saves 1 byte over u32 for ranges needing 17–24 bits of precision.
+]]
+local function writeu24(b: buffer, off: number, value: number): ()
+    writeu16(b, off, band(value, 0xFFFF))
+    writeu8(b, off + 2, band(rshift(value, 16), 0xFF))
+end
+
+local function readu24(b: buffer, off: number): number
+    return bor(readu16(b, off), lshift(readu8(b, off + 2), 16))
+end
+
 -- Public -----------------------------------------------------------------
 
 local Quantize = {}
 
 --[[
-    Pick the narrowest u8/u16/u32 wire form for [rangeMin, rangeMax] at
+    Pick the narrowest u8/u16/u24/u32 wire form for [rangeMin, rangeMax] at
     `precision`. Returns (compBytes, wfn, rfn, scale, invScale, delta).
     `apiName` shows in error messages so callers see their public surface.
 ]]
@@ -32,8 +54,8 @@ function Quantize.setup(
     number,
     number
 )
-    if rangeMin > rangeMax then
-        Log.error(`{apiName}: min ({rangeMin}) must be <= max ({rangeMax})`)
+    if rangeMin >= rangeMax then
+        Log.error(`{apiName}: min ({rangeMin}) must be < max ({rangeMax})`)
     end
     if precision <= 0 then
         Log.error(`{apiName}: precision must be positive, got {precision}`)
@@ -50,6 +72,8 @@ function Quantize.setup(
         compBytes, wfn, rfn = 1, buffer.writeu8, buffer.readu8
     elseif maxInt <= 0xFFFF then
         compBytes, wfn, rfn = 2, buffer.writeu16, buffer.readu16
+    elseif maxInt <= 0xFFFFFF then
+        compBytes, wfn, rfn = 3, writeu24, readu24
     else
         compBytes, wfn, rfn = 4, buffer.writeu32, buffer.readu32
     end

package/src/util/Quat.luau

@@ -0,0 +1,124 @@
+--!strict
+--!native
+-- Smallest-three quaternion packing into a single u32 for rotation wire forms.
+
+-- Constants --------------------------------------------------------------
+
+local INV_SQRT2 = 1 / math.sqrt(2)
+local Q_SCALE = 1023 / (2 * INV_SQRT2)
+local Q_INV = (2 * INV_SQRT2) / 1023
+local EPSILON_SQ = 5.76e-14
+
+-- Private ----------------------------------------------------------------
+
+local abs = math.abs
+local clamp = math.clamp
+local round = math.round
+local sin = math.sin
+local cos = math.cos
+local acos = math.acos
+local sqrt = math.sqrt
+local band = bit32.band
+local bor = bit32.bor
+local lshift = bit32.lshift
+local rshift = bit32.rshift
+
+-- Public -----------------------------------------------------------------
+
+local Quat = {}
+
+--[[
+    Quaternion from a CFrame's rotation portion. Returns (qx, qy, qz, qw)
+    so callers can pack without rebuilding the conversion table.
+]]
+function Quat.fromCFrame(cf: CFrame): (number, number, number, number)
+    local axis, angle = cf:ToAxisAngle()
+    local h = angle * 0.5
+    local s = sin(h)
+    return axis.X * s, axis.Y * s, axis.Z * s, cos(h)
+end
+
+--[[
+    Pack a unit quaternion into a single u32:
+      [largest:2][a:10][b:10][c:10]
+    Drops the largest |component|; reconstructed from the other three with
+    the constraint qx²+qy²+qz²+qw² = 1. Forces the dropped value
+    non-negative so the +sqrt path on decode yields the correct sign.
+]]
+function Quat.pack(qx: number, qy: number, qz: number, qw: number): number
+    local ax, ay, az, aw = abs(qx), abs(qy), abs(qz), abs(qw)
+    local largest, maxVal = 3, aw
+    if ax > maxVal then
+        largest, maxVal = 0, ax
+    end
+    if ay > maxVal then
+        largest, maxVal = 1, ay
+    end
+    if az > maxVal then
+        largest, maxVal = 2, az
+    end
+
+    local a: number, b: number, c: number
+    if largest == 0 then
+        if qx < 0 then
+            qy, qz, qw = -qy, -qz, -qw
+        end
+        a, b, c = qy, qz, qw
+    elseif largest == 1 then
+        if qy < 0 then
+            qx, qz, qw = -qx, -qz, -qw
+        end
+        a, b, c = qx, qz, qw
+    elseif largest == 2 then
+        if qz < 0 then
+            qx, qy, qw = -qx, -qy, -qw
+        end
+        a, b, c = qx, qy, qw
+    else
+        if qw < 0 then
+            qx, qy, qz = -qx, -qy, -qz
+        end
+        a, b, c = qx, qy, qz
+    end
+
+    local qa = clamp(round((a + INV_SQRT2) * Q_SCALE), 0, 1023)
+    local qb = clamp(round((b + INV_SQRT2) * Q_SCALE), 0, 1023)
+    local qc = clamp(round((c + INV_SQRT2) * Q_SCALE), 0, 1023)
+    return bor(lshift(largest, 30), lshift(qa, 20), lshift(qb, 10), qc)
+end
+
+-- Reverse Quat.pack into a rotation-only CFrame. Identity for near-zero magnitudes.
+function Quat.unpack(packed: number): CFrame
+    local largest = rshift(packed, 30)
+    local qa = band(rshift(packed, 20), 0x3FF)
+    local qb = band(rshift(packed, 10), 0x3FF)
+    local qc = band(packed, 0x3FF)
+
+    local a = qa * Q_INV - INV_SQRT2
+    local b = qb * Q_INV - INV_SQRT2
+    local c = qc * Q_INV - INV_SQRT2
+
+    local sqSum = a * a + b * b + c * c
+    local d = sqrt(if sqSum < 1 then 1 - sqSum else 0)
+
+    local qx: number, qy: number, qz: number, qw: number
+    if largest == 0 then
+        qx, qy, qz, qw = d, a, b, c
+    elseif largest == 1 then
+        qx, qy, qz, qw = a, d, b, c
+    elseif largest == 2 then
+        qx, qy, qz, qw = a, b, d, c
+    else
+        qx, qy, qz, qw = a, b, c, d
+    end
+
+    local sqLen = qx * qx + qy * qy + qz * qz
+    if sqLen < EPSILON_SQ then
+        return CFrame.identity
+    end
+    local angle = 2 * acos(clamp(qw, -1, 1))
+    local inv = 1 / sqrt(sqLen)
+    return CFrame.fromAxisAngle(Vector3.new(qx * inv, qy * inv, qz * inv), angle)
+end
+
+return table.freeze(Quat)