@axpecter/lync 2.3.2 → 3.0.0

package/src/codec/meta/DeltaScalar.luau

@@ -1,390 +0,0 @@
---!strict
---!native
--- Delta scalars: zigzag-varint diff against previous frame for ints, floats, vec3, CFrame.
-
-local Base = require(script.Parent.Parent.Base)
-local Baseline = require(script.Parent.Parent.Parent.internal.Baseline)
-local Log = require(script.Parent.Parent.Parent.util.Log)
-local Quantize = require(script.Parent.Parent.Parent.util.Quantize)
-local Quat = require(script.Parent.Parent.Parent.util.Quat)
-local Shared = require(script.Parent.Parent.composite.Shared)
-local Types = require(script.Parent.Parent.Parent.Types)
-local Varint = require(script.Parent.Parent.primitive.Varint)
-local Zint = require(script.Parent.Parent.primitive.Zint)
-
--- Constants --------------------------------------------------------------
-
-local I32_MIN = -0x80000000
-local I32_MAX = 0x7FFFFFFF
-
--- deltaCFrame header bits: which components changed since the last frame.
-local CF_X = 0x01
-local CF_Y = 0x02
-local CF_Z = 0x04
-local CF_ROT = 0x08
-local CF_ALL = 0x0F
-
--- Private ----------------------------------------------------------------
-
-local ensure = Base.ensure
-local allocDeltaId = Shared.allocDeltaId
-local floor = math.floor
-local clamp = math.clamp
-local round = math.round
-local band = bit32.band
-local bor = bit32.bor
-local readu8 = buffer.readu8
-local writeu8 = buffer.writeu8
-local readu32 = buffer.readu32
-local writeu32 = buffer.writeu32
-local bufLen = buffer.len
-local varintWrite = Varint.write
-local varintRead = Varint.read
-local zigzagEncode = Zint.encode
-local zigzagDecode = Zint.decode
-local quatPack = Quat.pack
-local quatUnpack = Quat.unpack
-local quatFromCFrame = Quat.fromCFrame
-
-local function quantizeVec3(
-    v: Vector3,
-    min: number,
-    delta: number,
-    scale: number
-): (number, number, number)
-    return round(clamp(v.X - min, 0, delta) * scale),
-        round(clamp(v.Y - min, 0, delta) * scale),
-        round(clamp(v.Z - min, 0, delta) * scale)
-end
-
--- Reject out-of-range components rather than silently snapping via clamp().
-local function validateVec3(v: Vector3, min: number, max: number, label: string): ()
-    if v.X < min or v.X > max or v.Y < min or v.Y > max or v.Z < min or v.Z > max then
-        Log.error(`{label} ({v.X}, {v.Y}, {v.Z}) has component out of range [{min}, {max}]`)
-    end
-end
-
-local function getScalarPrev(ch: Types.ChannelState, id: number, fallback: number): number
-    local cache = ch.deltas[id] :: any
-    return if cache then cache.scalar :: number else fallback
-end
-
-local function setScalarCache(ch: Types.ChannelState, id: number, value: number): ()
-    local cache = ch.deltas[id] :: any
-    if cache then
-        cache.scalar = value
-    else
-        ch.deltas[id] = { scalar = value } :: any
-    end
-end
-
--- Public -----------------------------------------------------------------
-
-local DeltaScalar = {}
-
---[[
-    Variable-length integer that emits zigzag varint of (current - previous).
-    First frame uses `min` as the implicit prev so the initial value encodes
-    as (value - min). Reliable transport only — a dropped frame desyncs prev.
-
-    Wire: 1 byte for unchanged or [-96, 95] mutations; up to 5 bytes for full i32.
-]]
-function DeltaScalar.deltaInt(min: number, max: number): Types.InternalCodec<number>
-    if min > max then
-        Log.error(`min ({min}) must be <= max ({max})`)
-    end
-    if floor(min) ~= min or floor(max) ~= max then
-        Log.error("bounds must be integers")
-    end
-    if max - min > I32_MAX then
-        Log.error(`range too wide; (max - min) must fit in i32, got {max - min}`)
-    end
-
-    local deltaId = allocDeltaId()
-
-    return table.freeze({
-        _isDelta = true,
-        _typeCheck = "number",
-        _isInteger = true,
-        _min = min,
-        _max = max,
-
-        write = function(ch: Types.ChannelState, value: number): ()
-            if value < min or value > max then
-                Log.error(`value {value} out of range [{min}, {max}]`)
-            end
-            if floor(value) ~= value then
-                Log.error(`value {value} must be an integer`)
-            end
-            varintWrite(ch, zigzagEncode(value - getScalarPrev(ch, deltaId, min)))
-            setScalarCache(ch, deltaId, 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 deltaInt")
-            end
-            local cached = Baseline.getCache(deltaId)
-            local value = (if cached ~= nil then cached :: number else min) + zigzagDecode(raw)
-            if value < min or value > max then
-                Log.error(`deltaInt decoded value {value} out of range [{min}, {max}]`)
-            end
-            Baseline.setCache(deltaId, value)
-            return value, consumed
-        end,
-    }) :: Types.InternalCodec<number>
-end
-
---[[
-    Quantized float with diffs in integer wire space (post-quantize). Storing
-    the quantized representative — not the float — across frames means
-    accumulating diffs over thousands of frames cannot drift past the grid.
-]]
-function DeltaScalar.deltaFloat(
-    min: number,
-    max: number,
-    precision: number
-): Types.InternalCodec<number>
-    if max - min == 0 then
-        return Base.constant(min)
-    end
-
-    local _, _, _, scale, invScale, delta = Quantize.setup("Lync.deltaFloat", min, max, precision)
-    local deltaId = allocDeltaId()
-
-    return table.freeze({
-        _isDelta = true,
-        _typeCheck = "number",
-        _min = min,
-        _max = max,
-
-        write = function(ch: Types.ChannelState, value: number): ()
-            local q = round(clamp(value - min, 0, delta) * scale)
-            varintWrite(ch, zigzagEncode(q - getScalarPrev(ch, deltaId, 0)))
-            setScalarCache(ch, deltaId, q)
-        end,
-
-        read = function(src: buffer, pos: number, _refs: { Instance }?): (number, number)
-            local raw, consumed = varintRead(src, pos)
-            if consumed == 0 then
-                Log.error("truncated deltaFloat")
-            end
-            local cached = Baseline.getCache(deltaId)
-            local q = (if cached ~= nil then cached :: number else 0) + zigzagDecode(raw)
-            Baseline.setCache(deltaId, q)
-            return q * invScale + min, consumed
-        end,
-    }) :: Types.InternalCodec<number>
-end
-
---[[
-    Quantized Vector3 with per-axis zigzag varint diffs. Static value: 3 bytes
-    (three zero zigzags); typical < 1 stud motion at 0.01-stud precision: 3-6
-    bytes. Baseline vec3 = 12 bytes, so 4x reduction at the static end.
-]]
-function DeltaScalar.deltaVec3(
-    min: number,
-    max: number,
-    precision: number
-): Types.InternalCodec<Vector3>
-    if max - min == 0 then
-        return Base.constant(Vector3.new(min, min, min)) :: Types.InternalCodec<Vector3>
-    end
-
-    local _, _, _, scale, invScale, delta = Quantize.setup("Lync.deltaVec3", min, max, precision)
-    local deltaId = allocDeltaId()
-
-    return table.freeze({
-        _isDelta = true,
-        _typeCheck = "Vector3",
-        _min = min,
-        _max = max,
-
-        write = function(ch: Types.ChannelState, value: Vector3): ()
-            validateVec3(value, min, max, "Vector3")
-            local qx, qy, qz = quantizeVec3(value, min, delta, scale)
-            local cache = ch.deltas[deltaId] :: any
-            local px, py, pz = 0, 0, 0
-            if cache then
-                px, py, pz = cache.qx :: number, cache.qy :: number, cache.qz :: number
-            end
-
-            varintWrite(ch, zigzagEncode(qx - px))
-            varintWrite(ch, zigzagEncode(qy - py))
-            varintWrite(ch, zigzagEncode(qz - pz))
-
-            if cache then
-                cache.qx, cache.qy, cache.qz = qx, qy, qz
-            else
-                ch.deltas[deltaId] = { qx = qx, qy = qy, qz = qz } :: any
-            end
-        end,
-
-        read = function(src: buffer, pos: number, _refs: { Instance }?): (Vector3, number)
-            local rx, cx = varintRead(src, pos)
-            if cx == 0 then
-                Log.error("truncated deltaVec3 X")
-            end
-            local ry, cy = varintRead(src, pos + cx)
-            if cy == 0 then
-                Log.error("truncated deltaVec3 Y")
-            end
-            local rz, cz = varintRead(src, pos + cx + cy)
-            if cz == 0 then
-                Log.error("truncated deltaVec3 Z")
-            end
-
-            local cached = Baseline.getCache(deltaId) :: any
-            local px, py, pz = 0, 0, 0
-            if cached then
-                px, py, pz = cached.qx, cached.qy, cached.qz
-            end
-            local qx = px + zigzagDecode(rx)
-            local qy = py + zigzagDecode(ry)
-            local qz = pz + zigzagDecode(rz)
-            Baseline.setCache(deltaId, { qx = qx, qy = qy, qz = qz })
-
-            return Vector3.new(qx * invScale + min, qy * invScale + min, qz * invScale + min),
-                cx + cy + cz
-        end,
-    }) :: Types.InternalCodec<Vector3>
-end
-
---[[
-    Quantized position + smallest-three quaternion rotation. Wire layout:
-      byte 0   header bits: bit0=Δx, bit1=Δy, bit2=Δz, bit3=Δrot
-      For each set position bit: zigzag varint of quantized diff
-      If rotation bit set: 4-byte packed quat
-
-    Static CFrame: 1 byte. Pos-only motion: 1 + 3 zint bytes (~4-7).
-    Full update: 1 + 3 zint + 4 quat (~8-13). Baseline lossless: 24 bytes.
-]]
-function DeltaScalar.deltaCFrame(
-    posMin: number,
-    posMax: number,
-    posPrecision: number
-): Types.InternalCodec<CFrame>
-    -- Quantize.setup itself rejects min == max; the redundant guard is gone.
-    local _, _, _, scale, invScale, delta =
-        Quantize.setup("Lync.deltaCFrame", posMin, posMax, posPrecision)
-    local deltaId = allocDeltaId()
-
-    return table.freeze({
-        _isDelta = true,
-        _typeCheck = "CFrame",
-
-        write = function(ch: Types.ChannelState, value: CFrame): ()
-            local pos = value.Position
-            validateVec3(pos, posMin, posMax, "CFrame position")
-            local qx, qy, qz = quantizeVec3(pos, posMin, delta, scale)
-            local packed = quatPack(quatFromCFrame(value))
-
-            -- prev = 0 so the first frame writes absolute values; receiver also defaults to 0.
-            local cache = ch.deltas[deltaId] :: any
-            local flag: number
-            local px, py, pz = 0, 0, 0
-            if cache then
-                px = cache.qx :: number
-                py = cache.qy :: number
-                pz = cache.qz :: number
-                local ppacked = cache.qrot :: number
-                flag = 0
-                if qx ~= px then
-                    flag = bor(flag, CF_X)
-                end
-                if qy ~= py then
-                    flag = bor(flag, CF_Y)
-                end
-                if qz ~= pz then
-                    flag = bor(flag, CF_Z)
-                end
-                if packed ~= ppacked then
-                    flag = bor(flag, CF_ROT)
-                end
-            else
-                -- First frame: emit everything so the receiver has a baseline.
-                flag = CF_ALL
-            end
-
-            ensure(ch, 1)
-            writeu8(ch.buff, ch.cursor, flag)
-            ch.cursor += 1
-
-            if band(flag, CF_X) ~= 0 then
-                varintWrite(ch, zigzagEncode(qx - px))
-            end
-            if band(flag, CF_Y) ~= 0 then
-                varintWrite(ch, zigzagEncode(qy - py))
-            end
-            if band(flag, CF_Z) ~= 0 then
-                varintWrite(ch, zigzagEncode(qz - pz))
-            end
-            if band(flag, CF_ROT) ~= 0 then
-                ensure(ch, 4)
-                writeu32(ch.buff, ch.cursor, packed)
-                ch.cursor += 4
-            end
-
-            if cache then
-                cache.qx, cache.qy, cache.qz, cache.qrot = qx, qy, qz, packed
-            else
-                ch.deltas[deltaId] = { qx = qx, qy = qy, qz = qz, qrot = packed } :: any
-            end
-        end,
-
-        read = function(src: buffer, pos: number, _refs: { Instance }?): (CFrame, number)
-            if pos >= bufLen(src) then
-                Log.error("truncated deltaCFrame header")
-            end
-            local flag = readu8(src, pos)
-            local total = 1
-
-            local cached = Baseline.getCache(deltaId) :: any
-            local qx, qy, qz, packed = 0, 0, 0, 0
-            if cached then
-                qx, qy, qz, packed = cached.qx, cached.qy, cached.qz, cached.qrot
-            end
-
-            if band(flag, CF_X) ~= 0 then
-                local r, c = varintRead(src, pos + total)
-                if c == 0 then
-                    Log.error("truncated deltaCFrame X")
-                end
-                qx += zigzagDecode(r)
-                total += c
-            end
-            if band(flag, CF_Y) ~= 0 then
-                local r, c = varintRead(src, pos + total)
-                if c == 0 then
-                    Log.error("truncated deltaCFrame Y")
-                end
-                qy += zigzagDecode(r)
-                total += c
-            end
-            if band(flag, CF_Z) ~= 0 then
-                local r, c = varintRead(src, pos + total)
-                if c == 0 then
-                    Log.error("truncated deltaCFrame Z")
-                end
-                qz += zigzagDecode(r)
-                total += c
-            end
-            if band(flag, CF_ROT) ~= 0 then
-                if pos + total + 4 > bufLen(src) then
-                    Log.error("truncated deltaCFrame rotation")
-                end
-                packed = readu32(src, pos + total)
-                total += 4
-            end
-
-            Baseline.setCache(deltaId, { qx = qx, qy = qy, qz = qz, qrot = packed })
-
-            local position =
-                Vector3.new(qx * invScale + posMin, qy * invScale + posMin, qz * invScale + posMin)
-            return CFrame.new(position) * quatUnpack(packed), total
-        end,
-    }) :: Types.InternalCodec<CFrame>
-end
-
-return table.freeze(DeltaScalar)

package/src/codec/meta/Enum.luau

@@ -1,50 +0,0 @@
---!strict
---!native
--- String-keyed enum codec. Maps values to u8 indices at definition time.
-
-local Base = require(script.Parent.Parent.Base)
-local Log = require(script.Parent.Parent.Parent.util.Log)
-local Types = require(script.Parent.Parent.Parent.Types)
-
--- Public -----------------------------------------------------------------
-
-local EnumCodec = {}
-
-function EnumCodec.define(...: string): Types.InternalCodec<string>
-    local values = { ... }
-    local count = #values
-    Log.assert(count > 0, "requires at least one variant")
-    if count > 256 then
-        Log.error(`exceeds 256 variants ({count})`)
-    end
-
-    local toIndex: { [string]: number } = {}
-    local toValue = table.create(count)
-    for i = 1, count do
-        local val = values[i]
-        if toIndex[val] then
-            Log.error(`duplicate value "{val}"`)
-        end
-        toIndex[val] = i - 1
-        toValue[i] = val
-    end
-    table.freeze(toIndex)
-    table.freeze(toValue)
-
-    return Base.define(1, function(b: buffer, off: number, value: string): ()
-        local idx = toIndex[value]
-        if idx == nil then
-            Log.error(`invalid value "{value}"`)
-        end
-        buffer.writeu8(b, off, idx)
-    end, function(b: buffer, off: number): string
-        local raw = buffer.readu8(b, off)
-        local val = toValue[raw + 1]
-        if val == nil then
-            Log.error(`invalid index {raw}`)
-        end
-        return val
-    end, { _typeCheck = "string", _isEnum = true, _enumValues = toIndex })
-end
-
-return table.freeze(EnumCodec)

package/src/codec/meta/Float.luau

@@ -1,38 +0,0 @@
---!strict
---!native
--- Fixed-point float quantizer. Maps a float range to u8/u16/u32.
-
-local Base = require(script.Parent.Parent.Base)
-local Quantize = require(script.Parent.Parent.Parent.util.Quantize)
-local Types = require(script.Parent.Parent.Parent.Types)
-
--- Private ----------------------------------------------------------------
-
-local clamp = math.clamp
-local round = math.round
-
--- Public -----------------------------------------------------------------
-
-local Float = {}
-
-function Float.float(
-    rangeMin: number,
-    rangeMax: number,
-    precision: number
-): Types.InternalCodec<number>
-    -- Degenerate range: emit nothing, decode to the constant.
-    if rangeMax - rangeMin == 0 then
-        return Base.constant(rangeMin)
-    end
-
-    local compBytes, wfn, rfn, scale, invScale, delta =
-        Quantize.setup("Lync.float", rangeMin, rangeMax, precision)
-
-    return Base.define(compBytes, function(b: buffer, off: number, value: number): ()
-        wfn(b, off, round(clamp(value - rangeMin, 0, delta) * scale))
-    end, function(b: buffer, off: number): number
-        return rfn(b, off) * invScale + rangeMin
-    end, { _min = rangeMin, _max = rangeMax, _typeCheck = "number" })
-end
-
-return table.freeze(Float)

package/src/codec/meta/Nothing.luau

@@ -1,13 +0,0 @@
---!strict
---!optimize 2
--- 0-byte codec. Reads nil. For fire-and-forget signals.
-
-local Base = require(script.Parent.Parent.Base)
-
--- Public -----------------------------------------------------------------
-
-local Nothing = {}
-
-Nothing.nothing = Base.constant(nil :: nil)
-
-return table.freeze(Nothing)

package/src/codec/meta/Unknown.luau

@@ -1,41 +0,0 @@
---!strict
---!native
--- Bypass codec. Stashes the value in the channel sidecar refs (no schema).
-
-local Channel = require(script.Parent.Parent.Parent.internal.Channel)
-local Log = require(script.Parent.Parent.Parent.util.Log)
-local Types = require(script.Parent.Parent.Parent.Types)
-
--- Private ----------------------------------------------------------------
-
-local pushRef = Channel.pushRef
-local readu16 = buffer.readu16
-
-local function writeUnknown(ch: Types.ChannelState, value: any): ()
-    pushRef(ch, value)
-end
-
-local function readUnknown(src: buffer, pos: number, refs: { Instance }?): (any, number)
-    local r = refs
-    if not r then
-        Log.error("refs array is required")
-    end
-    local idx = readu16(src, pos)
-    if idx < 1 or idx > #r then
-        Log.error(`ref index {idx} out of bounds`)
-    end
-    return r[idx], 2
-end
-
--- Public -----------------------------------------------------------------
-
-local Unknown = {}
-
--- _hasUnknown propagates upward so containers warn when used without validate.
-Unknown.unknown = table.freeze({
-    _hasUnknown = true,
-    write = writeUnknown,
-    read = readUnknown,
-})
-
-return table.freeze(Unknown)

package/src/codec/primitive/Bool.luau

@@ -1,26 +0,0 @@
---!strict
---!optimize 2
--- 1-byte boolean codec. _isBool flag opts struct/array into bit packing.
-
-local Base = require(script.Parent.Parent.Base)
-
--- Private ----------------------------------------------------------------
-
-local function writeBool(b: buffer, off: number, value: boolean): ()
-    buffer.writeu8(b, off, if value then 1 else 0)
-end
-
-local function readBool(b: buffer, off: number): boolean
-    return buffer.readu8(b, off) ~= 0
-end
-
--- Public -----------------------------------------------------------------
-
-local Bool = {}
-
-Bool.bool = Base.define(1, writeBool, readBool, {
-    _isBool = true,
-    _typeCheck = "boolean",
-})
-
-return table.freeze(Bool)

package/src/codec/primitive/Float16.luau

@@ -1,99 +0,0 @@
---!strict
---!native
--- IEEE 754 binary16 codec. 2 bytes, +/-65504 finite range, ~3 decimal digits.
-
-local Base = require(script.Parent.Parent.Base)
-
--- Constants --------------------------------------------------------------
-
-local MAX_FINITE = 65504
-local NAN_BITS = 0x7E00
-local INF_BITS = 0x7C00
-
--- Private ----------------------------------------------------------------
-
-local band = bit32.band
-local bor = bit32.bor
-local lshift = bit32.lshift
-local rshift = bit32.rshift
-local frexp = math.frexp
-local ldexp = math.ldexp
-local round = math.round
-local huge = math.huge
-local isnan = math.isnan
-
-local function encode(value: number): number
-    if isnan(value) then
-        return NAN_BITS
-    end
-    if value == 0 then
-        return 0
-    end
-
-    local sign = 0
-    if value < 0 then
-        sign = 0x8000
-        value = -value
-    end
-
-    if value > MAX_FINITE then
-        return bor(sign, INF_BITS)
-    end
-
-    local mantissa, exponent = frexp(value)
-    local biasedExp = exponent + 14
-
-    -- Subnormal: shift mantissa into the 10-bit fraction with the implicit bit gone.
-    if biasedExp <= 0 then
-        local frac = round(ldexp(mantissa, biasedExp + 10))
-        if frac >= 1024 then
-            return bor(sign, 0x0400)
-        end
-        if frac <= 0 then
-            return sign
-        end
-        return bor(sign, frac)
-    end
-
-    local frac = round((mantissa * 2 - 1) * 1024)
-    -- Rounding can carry into the exponent; absorb it.
-    if frac >= 1024 then
-        frac = 0
-        biasedExp += 1
-    end
-
-    if biasedExp >= 31 then
-        return bor(sign, INF_BITS)
-    end
-
-    return bor(sign, lshift(biasedExp, 10), frac)
-end
-
-local function decode(raw: number): number
-    local sign = band(raw, 0x8000)
-    local exp = band(rshift(raw, 10), 0x1F)
-    local frac = band(raw, 0x03FF)
-
-    local value: number
-    if exp == 0 then
-        value = if frac == 0 then 0 else ldexp(frac, -24)
-    elseif exp == 31 then
-        value = if frac == 0 then huge else 0 / 0
-    else
-        value = ldexp(frac + 1024, exp - 25)
-    end
-
-    return if sign ~= 0 then -value else value
-end
-
--- Public -----------------------------------------------------------------
-
-local Float16 = {}
-
-Float16.f16 = Base.define(2, function(b: buffer, off: number, value: number): ()
-    buffer.writeu16(b, off, encode(value))
-end, function(b: buffer, off: number): number
-    return decode(buffer.readu16(b, off))
-end, { _typeCheck = "number" })
-
-return table.freeze(Float16)