@axpecter/lync 2.2.1 → 2.3.2

package/src/util/Buffer.luau

@@ -0,0 +1,90 @@
+--!strict
+--!native
+-- Word-aligned XOR and equality helpers for Channel and composite deltas.
+
+-- Private ----------------------------------------------------------------
+
+local band = bit32.band
+local bxor = bit32.bxor
+local readu8 = buffer.readu8
+local readu32 = buffer.readu32
+local writeu8 = buffer.writeu8
+local writeu32 = buffer.writeu32
+local bufCopy = buffer.copy
+local bufCreate = buffer.create
+local minN = math.min
+
+-- Public -----------------------------------------------------------------
+
+local Buf = {}
+
+-- 8-byte unrolled compare; 4-byte step then byte tail for remainder.
+function Buf.rangeEqual(a: buffer, offA: number, b: buffer, offB: number, len: number): boolean
+    local aligned8 = band(len, -8)
+    local i = 0
+    while i < aligned8 do
+        if
+            readu32(a, offA + i) ~= readu32(b, offB + i)
+            or readu32(a, offA + i + 4) ~= readu32(b, offB + i + 4)
+        then
+            return false
+        end
+        i += 8
+    end
+    if i + 4 <= len then
+        if readu32(a, offA + i) ~= readu32(b, offB + i) then
+            return false
+        end
+        i += 4
+    end
+    while i < len do
+        if readu8(a, offA + i) ~= readu8(b, offB + i) then
+            return false
+        end
+        i += 1
+    end
+    return true
+end
+
+function Buf.snapshot(src: buffer, len: number, srcOff: number?): buffer
+    local out = bufCreate(len)
+    bufCopy(out, 0, src, srcOff or 0, len)
+    return out
+end
+
+--[[
+    XOR `current` against `previous` into a fresh curLen buffer. Returns
+    `current` unchanged when previous is nil so first-frame callers don't
+    branch. Overlap is 8-byte unrolled; tail is bulk-copied.
+]]
+function Buf.xorApply(current: buffer, curLen: number, previous: buffer?, prevLen: number?): buffer
+    if not previous then
+        return current
+    end
+    local pLen = prevLen or 0
+
+    local result = bufCreate(curLen)
+    local overlap = minN(curLen, pLen)
+
+    local aligned8 = band(overlap, -8)
+    local i = 0
+    while i < aligned8 do
+        writeu32(result, i, bxor(readu32(current, i), readu32(previous, i)))
+        writeu32(result, i + 4, bxor(readu32(current, i + 4), readu32(previous, i + 4)))
+        i += 8
+    end
+    if i + 4 <= overlap then
+        writeu32(result, i, bxor(readu32(current, i), readu32(previous, i)))
+        i += 4
+    end
+    while i < overlap do
+        writeu8(result, i, bxor(readu8(current, i), readu8(previous, i)))
+        i += 1
+    end
+    if curLen > overlap then
+        bufCopy(result, overlap, current, overlap, curLen - overlap)
+    end
+    return result
+end
+
+return table.freeze(Buf)

package/src/util/Constants.luau

@@ -0,0 +1,30 @@
+--!strict
+--!optimize 2
+-- Wire-format constants and integer limits shared across codecs.
+
+-- Public -----------------------------------------------------------------
+
+local Constants = {}
+
+Constants.U8_MAX = 0xFF
+Constants.U16_MAX = 0xFFFF
+Constants.U32_MAX = 0xFFFFFFFF
+
+Constants.I8_MIN = -0x80
+Constants.I8_MAX = 0x7F
+Constants.I16_MIN = -0x8000
+Constants.I16_MAX = 0x7FFF
+Constants.I32_MIN = -0x80000000
+Constants.I32_MAX = 0x7FFFFFFF
+
+--[[
+    Frame header byte: MSB = single-item (no count cell); cleared = multi-item
+    (u16 count follows). Low 7 bits = registration id (caps registry at 128).
+]]
+Constants.FRAME_MSB = 0x80
+Constants.FRAME_ID_MASK = 0x7F
+
+-- u16 count cell.
+Constants.MAX_BATCH_ITEMS = 0xFFFF
+
+return table.freeze(Constants)

package/src/util/Log.luau

@@ -0,0 +1,68 @@
+--!strict
+--!optimize 2
+-- Centralized warn/error/assert. Project name + caller source come from here.
+
+-- State ------------------------------------------------------------------
+
+-- Module-level so tests mute the whole library without threading a flag.
+local _silent = false
+
+-- Constants --------------------------------------------------------------
+
+local PREFIX = "[Lync]"
+
+-- Private ----------------------------------------------------------------
+
+--[[
+    Stack levels: 1=this fn, 2=Log.warn/error/assert, 3=user. We want #3 so
+    the source/line/name point at the actual caller, not at Log.
+
+    Source comes back as a dotted Roblox path (e.g. "ServerScriptService.
+    MainModule.Lync.codec.primitive.Int" or "...test.unit.api.Packet.spec").
+    `.spec` is a literal dot in test ModuleScript names, so split-on-dot
+    would yield the meaningless tail "spec"; check the .spec suffix first
+    and recover the meaningful segment, then fall back to the last segment.
+]]
+local function format(message: string): string
+    local source, line, name = debug.info(3, "sln")
+    local file = source:match("([^.]+)%.spec$") or source:match("[^./\\]+$") or source
+    if name and name ~= "" then
+        return `{PREFIX} {file}:{line} ({name}) {message}`
+    end
+    return `{PREFIX} {file}:{line} {message}`
+end
+
+-- Public -----------------------------------------------------------------
+
+local Log = {}
+
+function Log.warn(message: string): ()
+    if not _silent then
+        warn(format(message))
+    end
+end
+
+-- level 2 so the runtime traceback points at the caller, not at Log.
+function Log.error(message: string): never
+    error(format(message), 2)
+end
+
+--[[
+    NOTE: Luau evaluates args eagerly. `format(message)` runs even when cond
+    is true, paying one debug.info call per Log.assert call. Use only with
+    LITERAL strings (no interpolation). For interpolated messages prefer
+    `if cond then Log.error(...) end`.
+]]
+function Log.assert<T>(cond: T, message: string): T
+    return assert(cond, format(message))
+end
+
+function Log.setSilent(silent: boolean): ()
+    _silent = silent
+end
+
+function Log.reset(): ()
+    _silent = false
+end
+
+return table.freeze(Log)

package/src/util/Player.luau

@@ -0,0 +1,14 @@
+--!strict
+--!optimize 2
+-- Player Instance type guard.
+
+-- Public -----------------------------------------------------------------
+
+local Player = {}
+
+-- typeof first: :IsA errors on non-Instances.
+function Player.is(value: any): boolean
+    return typeof(value) == "Instance" and value:IsA("Player")
+end
+
+return table.freeze(Player)

package/src/util/Quantize.luau

@@ -0,0 +1,84 @@
+--!strict
+--!optimize 2
+-- Fixed-point range quantizer setup shared by float and vector codecs.
+
+local Log = require(script.Parent.Log)
+
+-- Private ----------------------------------------------------------------
+
+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/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.
+]]
+function Quantize.setup(
+    apiName: string,
+    rangeMin: number,
+    rangeMax: number,
+    precision: number
+): (
+    number,
+    (buffer, number, number) -> (),
+    (buffer, number) -> number,
+    number,
+    number,
+    number
+)
+    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}`)
+    end
+
+    local delta = rangeMax - rangeMin
+    -- Clamp to [1, U32_MAX] so wire-form selection has a valid value.
+    local maxInt = minN(0xFFFFFFFF, maxN(1, ceil(delta / precision)))
+
+    local compBytes: number
+    local wfn: (buffer, number, number) -> ()
+    local rfn: (buffer, number) -> number
+    if maxInt <= 0xFF then
+        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
+
+    return compBytes, wfn, rfn, maxInt / delta, delta / maxInt, delta
+end
+
+return table.freeze(Quantize)

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)

package/src/internal/Util.luau

@@ -1,26 +0,0 @@
---!strict
---!optimize 2
--- Cross-module utility helpers.
-
--- Public -----------------------------------------------------------------
-
-local Util = {}
-
-function Util.isPlayer(value: any): boolean
-    return typeof(value) == "Instance" and (value :: Instance):IsA("Player")
-end
-
---[[
-    O(1) array remove via swap with last element. The slot becomes nil
-    after this returns; callers that track an external count must
-    decrement it themselves.
-]]
-function Util.swapRemove<T>(arr: { T }, idx: number): ()
-    local last = #arr
-    if idx ~= last then
-        arr[idx] = arr[last]
-    end
-    arr[last] = nil
-end
-
-return table.freeze(Util)