@axpecter/lync 1.3.0

package/src/codec/meta/Nothing.luau

@@ -0,0 +1,9 @@
+--!strict
+--!native
+-- Zero-byte codec. Reads nil. Good for fire-and-forget signals.
+
+local Base = require (script.Parent.Parent.Base)
+
+return table.freeze ({
+    nothing = Base.zero (),
+})

package/src/codec/meta/Quantized.luau

@@ -0,0 +1,170 @@
+--!strict
+--!native
+-- Fixed-point compression. Maps float ranges to integer ranges.
+
+local Channel = require (script.Parent.Parent.Parent.internal.Channel)
+local alloc = Channel.alloc
+local Types = require (script.Parent.Parent.Parent.Types)
+
+type ChannelState = Types.ChannelState
+type Codec<T> = Types.Codec<T>
+
+-- Constants --------------------------------------------------------------
+
+local clamp = math.clamp
+local round = math.round
+local ceil = math.ceil
+local min = math.min
+local max = math.max
+
+local U32_MAX = 4294967295
+
+-- Private ----------------------------------------------------------------
+
+local function selectIO (bytes: number): ((b: buffer, offset: number, v: number) -> (), (
+    b: buffer,
+    offset: number
+) -> number)
+    if bytes == 1 then
+        return buffer.writeu8, buffer.readu8
+    end
+    if bytes == 2 then
+        return buffer.writeu16, buffer.readu16
+    end
+    return buffer.writeu32, buffer.readu32
+end
+
+local function selectWidth (maxInt: number): number
+    if maxInt <= 255 then
+        return 1
+    end
+    if maxInt <= 65535 then
+        return 2
+    end
+    return 4
+end
+
+-- Public -----------------------------------------------------------------
+
+local Quantized = {}
+
+-- Shared validation and precomputation for both float and vec3 quantizers.
+local function setup (minVal: number, maxVal: number, precision: number)
+    if minVal > maxVal then
+        error (`[Lync] Quantized min > max: {minVal} > {maxVal}`)
+    end
+    if precision <= 0 then
+        error (`[Lync] Quantized precision must be positive: {precision}`)
+    end
+
+    local delta = maxVal - minVal
+    if delta == 0 then
+        return nil
+    end
+
+    local maxInt = min (U32_MAX, max (1, ceil (delta / precision)))
+    local bytes = selectWidth (maxInt)
+    local wfn, rfn = selectIO (bytes)
+    local invDelta = 1 / delta
+    local invMaxInt = delta / maxInt
+
+    return delta, maxInt, bytes, wfn, rfn, invDelta, invMaxInt
+end
+
+function Quantized.float (minVal: number, maxVal: number, precision: number): Codec<number>
+    local delta, maxInt, bytes, wfn, rfn, invDelta, invMaxInt = setup (minVal, maxVal, precision)
+    if not delta then
+        return table.freeze ({
+            _size = 0,
+            _directWrite = function (_b: buffer, _offset: number, _value: number): () end,
+            _directRead = function (_b: buffer, _offset: number): number
+                return minVal
+            end,
+            write = function (_ch: ChannelState, _value: number): () end,
+            read = function (_src: buffer, _pos: number, _refs: { Instance }?): (number, number)
+                return minVal, 0
+            end,
+        })
+    end
+
+    return table.freeze ({
+        _size = bytes,
+        _directWrite = function (b: buffer, offset: number, value: number): ()
+            wfn (b, offset, round (clamp ((value - minVal) * invDelta, 0, 1) * maxInt))
+        end,
+        _directRead = function (b: buffer, offset: number): number
+            return rfn (b, offset) * invMaxInt + minVal
+        end,
+        write = function (ch: ChannelState, value: number): ()
+            local c = ch.cursor
+            if c + bytes > ch.size then
+                alloc (ch, bytes)
+            end
+            wfn (ch.buff, c, round (clamp ((value - minVal) * invDelta, 0, 1) * maxInt))
+            ch.cursor = c + bytes
+        end,
+        read = function (src: buffer, pos: number, _refs: { Instance }?): (number, number)
+            return rfn (src, pos) * invMaxInt + minVal, bytes
+        end,
+    })
+end
+
+function Quantized.vec3 (minVal: number, maxVal: number, precision: number): Codec<Vector3>
+    local delta, maxInt, compBytes, wfn, rfn, invDelta, invMaxInt =
+        setup (minVal, maxVal, precision)
+    if not delta then
+        local val = Vector3.new (minVal, minVal, minVal)
+        return table.freeze ({
+            _size = 0,
+            _directWrite = function (_b: buffer, _offset: number, _value: Vector3): () end,
+            _directRead = function (_b: buffer, _offset: number): Vector3
+                return val
+            end,
+            write = function (_ch: ChannelState, _value: Vector3): () end,
+            read = function (_src: buffer, _pos: number, _refs: { Instance }?): (Vector3, number)
+                return val, 0
+            end,
+        })
+    end
+
+    local totalBytes = compBytes * 3
+    local stride = compBytes
+    local stride2 = compBytes * 2
+
+    return table.freeze ({
+        _size = totalBytes,
+        _directWrite = function (b: buffer, offset: number, value: Vector3): ()
+            wfn (b, offset, round (clamp ((value.X - minVal) * invDelta, 0, 1) * maxInt))
+            wfn (b, offset + stride, round (clamp ((value.Y - minVal) * invDelta, 0, 1) * maxInt))
+            wfn (b, offset + stride2, round (clamp ((value.Z - minVal) * invDelta, 0, 1) * maxInt))
+        end,
+        _directRead = function (b: buffer, offset: number): Vector3
+            return Vector3.new (
+                rfn (b, offset) * invMaxInt + minVal,
+                rfn (b, offset + stride) * invMaxInt + minVal,
+                rfn (b, offset + stride2) * invMaxInt + minVal
+            )
+        end,
+        write = function (ch: ChannelState, value: Vector3): ()
+            local c = ch.cursor
+            if c + totalBytes > ch.size then
+                alloc (ch, totalBytes)
+            end
+            local b = ch.buff
+            wfn (b, c, round (clamp ((value.X - minVal) * invDelta, 0, 1) * maxInt))
+            wfn (b, c + stride, round (clamp ((value.Y - minVal) * invDelta, 0, 1) * maxInt))
+            wfn (b, c + stride2, round (clamp ((value.Z - minVal) * invDelta, 0, 1) * maxInt))
+            ch.cursor = c + totalBytes
+        end,
+        read = function (src: buffer, pos: number, _refs: { Instance }?): (Vector3, number)
+            return Vector3.new (
+                rfn (src, pos) * invMaxInt + minVal,
+                rfn (src, pos + stride) * invMaxInt + minVal,
+                rfn (src, pos + stride2) * invMaxInt + minVal
+            ),
+                totalBytes
+        end,
+    })
+end
+
+return table.freeze (Quantized)

package/src/codec/meta/Unknown.luau

@@ -0,0 +1,35 @@
+--!strict
+--!native
+-- Sidecar codec. Bypasses buffer serialization, uses Roblox remote refs.
+
+local Channel = require (script.Parent.Parent.Parent.internal.Channel)
+local alloc = Channel.alloc
+
+return table.freeze ({
+    unknown = table.freeze ({
+        write = function (ch: any, value: any): ()
+            local refs = ch.refs
+            local idx = #refs + 1
+            if idx > 65535 then
+                error (`[Lync] Unknown ref overflow: {idx} exceeds u16 max`)
+            end
+
+            refs[idx] = value
+
+            local c = ch.cursor
+            if c + 2 > ch.size then
+                alloc (ch, 2)
+            end
+            buffer.writeu16 (ch.buff, c, idx)
+            ch.cursor = c + 2
+        end,
+        read = function (src: buffer, pos: number, refs: { Instance }?): (any, number)
+            if not refs then
+                error ("[Lync] Unknown read requires refs array")
+            end
+
+            local idx = buffer.readu16 (src, pos)
+            return refs[idx], 2
+        end,
+    }),
+})

package/src/codec/primitive/Bool.luau

@@ -0,0 +1,30 @@
+--!strict
+--!native
+-- Boolean codec. _isBool tells struct to pack into bitfields.
+
+local Channel = require (script.Parent.Parent.Parent.internal.Channel)
+local alloc = Channel.alloc
+
+return table.freeze ({
+    bool = table.freeze ({
+        _size = 1,
+        _isBool = true,
+        _directWrite = function (b: buffer, offset: number, value: boolean): ()
+            buffer.writeu8 (b, offset, if value then 1 else 0)
+        end,
+        _directRead = function (b: buffer, offset: number): boolean
+            return buffer.readu8 (b, offset) ~= 0
+        end,
+        write = function (ch: any, value: boolean): ()
+            local c = ch.cursor
+            if c + 1 > ch.size then
+                alloc (ch, 1)
+            end
+            buffer.writeu8 (ch.buff, c, if value then 1 else 0)
+            ch.cursor = c + 1
+        end,
+        read = function (src: buffer, pos: number, _refs: { Instance }?): (boolean, number)
+            return buffer.readu8 (src, pos) ~= 0, 1
+        end,
+    }),
+})

package/src/codec/primitive/Float16.luau

@@ -0,0 +1,111 @@
+--!strict
+--!native
+-- Half-precision float codec. 2 bytes, ±65504, ~3 decimal digits.
+
+local Channel = require (script.Parent.Parent.Parent.internal.Channel)
+local alloc = Channel.alloc
+local Types = require (script.Parent.Parent.Parent.Types)
+
+type ChannelState = Types.ChannelState
+
+-- Constants --------------------------------------------------------------
+
+local MAX_HALF = 65504
+local BIAS = 15
+local EXP_MAX = 31
+local MANT_BITS = 10
+local MANT_SCALE = 1024
+local SIGN_BIT = 0x8000
+local INF_BITS = 0x7C00
+local NAN_BITS = 0x7E00
+
+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
+
+-- Private ----------------------------------------------------------------
+
+local function encode (value: number): number
+    if value ~= value then
+        return NAN_BITS
+    end
+    if value == 0 then
+        return 0
+    end
+
+    local sign = 0
+    if value < 0 then
+        sign = SIGN_BIT
+        value = -value
+    end
+
+    if value > MAX_HALF then
+        return bor (sign, INF_BITS)
+    end
+
+    local mantissa, exponent = frexp (value)
+    exponent += 14
+
+    local bits: number
+    if exponent <= 0 then
+        local shift = exponent + MANT_BITS - 1
+        if shift < 0 then
+            return sign
+        end
+        bits = round (mantissa * lshift (1, shift))
+    elseif exponent >= EXP_MAX then
+        bits = INF_BITS
+    else
+        bits = bor (lshift (exponent, MANT_BITS), round ((mantissa * 2 - 1) * MANT_SCALE))
+    end
+
+    return bor (sign, bits)
+end
+
+local function decode (packed: number): number
+    local exponent = band (rshift (packed, MANT_BITS), 0x1F)
+    local mantissa = band (packed, 0x03FF)
+
+    local result: number
+    if exponent == 0 then
+        result = if mantissa == 0 then 0 else ldexp (mantissa / MANT_SCALE, 1 - BIAS)
+    elseif exponent == EXP_MAX then
+        result = if mantissa == 0 then huge else 0 / 0
+    else
+        result = ldexp (mantissa / MANT_SCALE + 1, exponent - BIAS)
+    end
+
+    return if band (packed, SIGN_BIT) ~= 0 then -result else result
+end
+
+-- Public -----------------------------------------------------------------
+
+local Float16 = {}
+
+Float16.f16 = table.freeze ({
+    _size = 2,
+    _directWrite = function (b: buffer, offset: number, value: number): ()
+        buffer.writeu16 (b, offset, encode (value))
+    end,
+    _directRead = function (b: buffer, offset: number): number
+        return decode (buffer.readu16 (b, offset))
+    end,
+    write = function (ch: ChannelState, value: number): ()
+        local c = ch.cursor
+        if c + 2 > ch.size then
+            alloc (ch, 2)
+        end
+        buffer.writeu16 (ch.buff, c, encode (value))
+        ch.cursor = c + 2
+    end,
+    read = function (src: buffer, pos: number, _refs: { Instance }?): (number, number)
+        return decode (buffer.readu16 (src, pos)), 2
+    end,
+})
+
+return table.freeze (Float16)

package/src/codec/primitive/Number.luau

@@ -0,0 +1,48 @@
+--!strict
+--!native
+-- u8, u16, u32, i8, i16, i32, f32, f64 codecs.
+
+local Base = require (script.Parent.Parent.Base)
+
+return table.freeze ({
+    u8 = Base.define (1, function (b: buffer, o: number, v: number): ()
+        buffer.writeu8 (b, o, v)
+    end, function (b: buffer, o: number): number
+        return buffer.readu8 (b, o)
+    end),
+    u16 = Base.define (2, function (b: buffer, o: number, v: number): ()
+        buffer.writeu16 (b, o, v)
+    end, function (b: buffer, o: number): number
+        return buffer.readu16 (b, o)
+    end),
+    u32 = Base.define (4, function (b: buffer, o: number, v: number): ()
+        buffer.writeu32 (b, o, v)
+    end, function (b: buffer, o: number): number
+        return buffer.readu32 (b, o)
+    end),
+    i8 = Base.define (1, function (b: buffer, o: number, v: number): ()
+        buffer.writei8 (b, o, v)
+    end, function (b: buffer, o: number): number
+        return buffer.readi8 (b, o)
+    end),
+    i16 = Base.define (2, function (b: buffer, o: number, v: number): ()
+        buffer.writei16 (b, o, v)
+    end, function (b: buffer, o: number): number
+        return buffer.readi16 (b, o)
+    end),
+    i32 = Base.define (4, function (b: buffer, o: number, v: number): ()
+        buffer.writei32 (b, o, v)
+    end, function (b: buffer, o: number): number
+        return buffer.readi32 (b, o)
+    end),
+    f32 = Base.define (4, function (b: buffer, o: number, v: number): ()
+        buffer.writef32 (b, o, v)
+    end, function (b: buffer, o: number): number
+        return buffer.readf32 (b, o)
+    end),
+    f64 = Base.define (8, function (b: buffer, o: number, v: number): ()
+        buffer.writef64 (b, o, v)
+    end, function (b: buffer, o: number): number
+        return buffer.readf64 (b, o)
+    end),
+})

package/src/codec/primitive/Varint.luau

@@ -0,0 +1,76 @@
+--!strict
+--!native
+-- LEB128 variable-length integer encoding and decoding.
+
+local Channel = require (script.Parent.Parent.Parent.internal.Channel)
+local Types = require (script.Parent.Parent.Parent.Types)
+
+type ChannelState = Types.ChannelState
+
+local alloc = Channel.alloc
+
+-- Constants --------------------------------------------------------------
+
+local CONT = 0x80
+local MASK = 0x7F
+local MAX_BYTES = 5
+local MAX_VALUE = 4294967295
+
+local band = bit32.band
+local bor = bit32.bor
+local rshift = bit32.rshift
+local lshift = bit32.lshift
+
+-- Public -----------------------------------------------------------------
+
+local Varint = {}
+
+function Varint.write (ch: ChannelState, value: number): ()
+    if value < 0 or value > MAX_VALUE then
+        error (`[Lync] Varint value out of range: {value}`)
+    end
+
+    -- Fast path: ~80%+ of real-world varints are single-byte (lengths, counts)
+    if value < CONT then
+        local c = ch.cursor
+        if c + 1 > ch.size then
+            alloc (ch, 1)
+        end
+        buffer.writeu8 (ch.buff, c, value)
+        ch.cursor = c + 1
+        return
+    end
+
+    local c = ch.cursor
+    if c + MAX_BYTES > ch.size then
+        alloc (ch, MAX_BYTES)
+    end
+    local b = ch.buff
+
+    while value >= CONT do
+        buffer.writeu8 (b, c, bor (band (value, MASK), CONT))
+        value = rshift (value, 7)
+        c += 1
+    end
+
+    buffer.writeu8 (b, c, value)
+    ch.cursor = c + 1
+end
+
+-- Reads rely on buffer.readu8 throwing on OOB. MAX_BYTES rejects malformed loops.
+function Varint.read (src: buffer, pos: number): (number, number)
+    local result = 0
+
+    for offset = 0, MAX_BYTES - 1 do
+        local byte = buffer.readu8 (src, pos + offset)
+        result = bor (result, lshift (band (byte, MASK), offset * 7))
+
+        if band (byte, CONT) == 0 then
+            return result, offset + 1
+        end
+    end
+
+    error (`[Lync] Varint exceeds {MAX_BYTES} bytes at position {pos}`)
+end
+
+return table.freeze (Varint)