@axpecter/lync 1.3.0

package/src/codec/composite/Tuple.luau

@@ -0,0 +1,143 @@
+--!strict
+--!native
+-- Positional ordered codec. Like struct but indexed, not keyed.
+
+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>
+
+-- Public -----------------------------------------------------------------
+
+local Tuple = {}
+
+function Tuple.define (...: Codec<any>): Codec<{ any }>
+    local codecs = { ... }
+    local count = #codecs
+    if count == 0 then
+        error ("[Lync] Tuple requires at least one codec")
+    end
+
+    table.freeze (codecs)
+
+    local canDirect = true
+    local totalSize: number = 0
+    local directWrites = table.create (count) :: { any }
+    local directReads = table.create (count) :: { any }
+    local fieldSizes = table.create (count) :: { number }
+
+    for i = 1, count do
+        local codec = codecs[i] :: any
+        local size = codec._size
+        local dw = codec._directWrite
+        local dr = codec._directRead
+
+        if size and dw and dr then
+            fieldSizes[i] = size
+            directWrites[i] = dw
+            directReads[i] = dr
+            totalSize += size
+        else
+            canDirect = false
+            if size then
+                totalSize += size
+            else
+                totalSize = nil :: any
+            end
+            break
+        end
+    end
+
+    -- Recompute totalSize for generic path if direct failed partway
+    if not canDirect then
+        totalSize = 0 :: any
+        for i = 1, count do
+            local size = (codecs[i] :: any)._size
+            if size then
+                totalSize = (totalSize :: number) + size
+            else
+                totalSize = nil :: any
+                break
+            end
+        end
+    end
+
+    if canDirect then
+        table.freeze (directWrites)
+        table.freeze (directReads)
+        table.freeze (fieldSizes)
+
+        local function directWriteBody (b: buffer, c: number, value: { any }): ()
+            for i = 1, count do
+                directWrites[i] (b, c, value[i])
+                c += fieldSizes[i]
+            end
+        end
+
+        local function directReadBody (b: buffer, pos: number): { any }
+            local result = table.create (count)
+            local c = pos
+            for i = 1, count do
+                result[i] = directReads[i] (b, c)
+                c += fieldSizes[i]
+            end
+            return result
+        end
+
+        return table.freeze ({
+            _size = totalSize,
+            _directWrite = directWriteBody,
+            _directRead = directReadBody,
+            write = function (ch: ChannelState, value: { any }): ()
+                local c = ch.cursor
+                if c + totalSize > ch.size then
+                    alloc (ch, totalSize)
+                end
+                directWriteBody (ch.buff, c, value)
+                ch.cursor = c + totalSize
+            end,
+            read = function (src: buffer, pos: number, _refs: { Instance }?): ({ any }, number)
+                return directReadBody (src, pos), totalSize
+            end,
+        })
+    end
+
+    local writeFns = table.create (count) :: { any }
+    local readFns = table.create (count) :: { any }
+    for i = 1, count do
+        writeFns[i] = codecs[i].write
+        readFns[i] = codecs[i].read
+    end
+    table.freeze (writeFns)
+    table.freeze (readFns)
+
+    local hasFixedTotal = totalSize ~= nil
+
+    return table.freeze ({
+        _size = totalSize,
+        write = function (ch: ChannelState, value: { any }): ()
+            if hasFixedTotal then
+                alloc (ch, totalSize :: number)
+            end
+            for i = 1, count do
+                writeFns[i] (ch, value[i])
+            end
+        end,
+        read = function (src: buffer, pos: number, refs: { Instance }?): ({ any }, number)
+            local result = table.create (count)
+            local absPos = pos
+
+            for i = 1, count do
+                local value, n = readFns[i] (src, absPos, refs)
+                result[i] = value
+                absPos += n
+            end
+
+            return result, absPos - pos
+        end,
+    })
+end
+
+return table.freeze (Tuple)

package/src/codec/datatype/Buffer.luau

@@ -0,0 +1,44 @@
+--!strict
+--!native
+-- Raw buffer codec with varint length prefix.
+
+local Channel = require (script.Parent.Parent.Parent.internal.Channel)
+local alloc = Channel.alloc
+local Types = require (script.Parent.Parent.Parent.Types)
+local Varint = require (script.Parent.Parent.primitive.Varint)
+
+type ChannelState = Types.ChannelState
+
+-- Public -----------------------------------------------------------------
+
+local Buffer = {}
+
+Buffer.buff = table.freeze ({
+    write = function (ch: ChannelState, value: buffer): ()
+        local len = buffer.len (value)
+        Varint.write (ch, len)
+        local c = ch.cursor
+        if c + len > ch.size then
+            alloc (ch, len)
+        end
+        buffer.copy (ch.buff, c, value, 0, len)
+        ch.cursor = c + len
+    end,
+    read = function (src: buffer, pos: number, _refs: { Instance }?): (buffer, number)
+        local len, lenBytes = Varint.read (src, pos)
+        if len == 0 then
+            return buffer.create (0), lenBytes
+        end
+
+        local remaining = buffer.len (src) - pos - lenBytes
+        if len > remaining then
+            error (`[Lync] Buffer length exceeds remaining: {len} > {remaining}`)
+        end
+
+        local out = buffer.create (len)
+        buffer.copy (out, 0, src, pos + lenBytes, len)
+        return out, lenBytes + len
+    end,
+})
+
+return table.freeze (Buffer)

package/src/codec/datatype/CFrame.luau

@@ -0,0 +1,51 @@
+--!strict
+--!native
+-- Axis-angle CFrame codec. Zero axis at identity for clean deltas.
+
+local Base = require (script.Parent.Parent.Base)
+
+-- f32 machine epsilon * 2 to absorb round-trip noise.
+local EPSILON = 2.4e-7
+local sqrt = math.sqrt
+
+local function writeCFrame (b: buffer, c: number, value: CFrame): ()
+    local position = value.Position
+    local axis, angle = value:ToAxisAngle ()
+
+    buffer.writef32 (b, c, position.X)
+    buffer.writef32 (b, c + 4, position.Y)
+    buffer.writef32 (b, c + 8, position.Z)
+
+    if angle < EPSILON then
+        buffer.writef32 (b, c + 12, 0)
+        buffer.writef32 (b, c + 16, 0)
+        buffer.writef32 (b, c + 20, 0)
+    else
+        buffer.writef32 (b, c + 12, axis.X * angle)
+        buffer.writef32 (b, c + 16, axis.Y * angle)
+        buffer.writef32 (b, c + 20, axis.Z * angle)
+    end
+end
+
+local function readCFrame (b: buffer, pos: number): CFrame
+    local px = buffer.readf32 (b, pos)
+    local py = buffer.readf32 (b, pos + 4)
+    local pz = buffer.readf32 (b, pos + 8)
+    local rx = buffer.readf32 (b, pos + 12)
+    local ry = buffer.readf32 (b, pos + 16)
+    local rz = buffer.readf32 (b, pos + 20)
+
+    local angle = sqrt (rx * rx + ry * ry + rz * rz)
+    local origin = CFrame.new (px, py, pz)
+
+    if angle < EPSILON then
+        return origin
+    end
+
+    local inv = 1 / angle
+    return origin * CFrame.fromAxisAngle (Vector3.new (rx * inv, ry * inv, rz * inv), angle)
+end
+
+return table.freeze ({
+    cframe = Base.define (24, writeCFrame, readCFrame),
+})

package/src/codec/datatype/Color.luau

@@ -0,0 +1,22 @@
+--!strict
+--!native
+-- Color3 codec. 3 bytes, 0-255 per channel, clamped.
+
+local Base = require (script.Parent.Parent.Base)
+
+local round = math.round
+local clamp = math.clamp
+
+return table.freeze ({
+    color3 = Base.define (3, function (b: buffer, o: number, v: Color3): ()
+        buffer.writeu8 (b, o, round (clamp (v.R, 0, 1) * 255))
+        buffer.writeu8 (b, o + 1, round (clamp (v.G, 0, 1) * 255))
+        buffer.writeu8 (b, o + 2, round (clamp (v.B, 0, 1) * 255))
+    end, function (b: buffer, o: number): Color3
+        return Color3.fromRGB (
+            buffer.readu8 (b, o),
+            buffer.readu8 (b, o + 1),
+            buffer.readu8 (b, o + 2)
+        )
+    end),
+})

package/src/codec/datatype/Instance.luau

@@ -0,0 +1,48 @@
+--!strict
+--!native
+-- Instance codec via sidecar reference array.
+
+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
+
+-- Public -----------------------------------------------------------------
+
+local InstanceCodec = {}
+
+InstanceCodec.inst = table.freeze ({
+    _size = 2,
+    write = function (ch: ChannelState, value: Instance): ()
+        local refs = ch.refs
+        local idx = #refs + 1
+        if idx > 65535 then
+            error (`[Lync] Instance 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 }?): (Instance, number)
+        local idx = buffer.readu16 (src, pos)
+        if not refs then
+            error ("[Lync] Instance read requires refs array")
+        end
+
+        local inst = refs[idx]
+        if not inst then
+            error (`[Lync] Instance ref index out of bounds: {idx}`)
+        end
+
+        return inst, 2
+    end,
+})
+
+return table.freeze (InstanceCodec)

package/src/codec/datatype/IntVector.luau

@@ -0,0 +1,25 @@
+--!strict
+--!native
+-- Vector2int16 (4B) and Vector3int16 (6B) codecs.
+
+local Base = require (script.Parent.Parent.Base)
+
+return table.freeze ({
+    vec2int16 = Base.define (4, function (b: buffer, o: number, v: Vector2int16): ()
+        buffer.writei16 (b, o, v.X)
+        buffer.writei16 (b, o + 2, v.Y)
+    end, function (b: buffer, o: number): Vector2int16
+        return Vector2int16.new (buffer.readi16 (b, o), buffer.readi16 (b, o + 2))
+    end),
+    vec3int16 = Base.define (6, function (b: buffer, o: number, v: Vector3int16): ()
+        buffer.writei16 (b, o, v.X)
+        buffer.writei16 (b, o + 2, v.Y)
+        buffer.writei16 (b, o + 4, v.Z)
+    end, function (b: buffer, o: number): Vector3int16
+        return Vector3int16.new (
+            buffer.readi16 (b, o),
+            buffer.readi16 (b, o + 2),
+            buffer.readi16 (b, o + 4)
+        )
+    end),
+})

package/src/codec/datatype/NumberRange.luau

@@ -0,0 +1,14 @@
+--!strict
+--!native
+-- NumberRange codec. 8 bytes: min f32 + max f32.
+
+local Base = require (script.Parent.Parent.Base)
+
+return table.freeze ({
+    numberRange = Base.define (8, function (b: buffer, o: number, v: NumberRange): ()
+        buffer.writef32 (b, o, v.Min)
+        buffer.writef32 (b, o + 4, v.Max)
+    end, function (b: buffer, o: number): NumberRange
+        return NumberRange.new (buffer.readf32 (b, o), buffer.readf32 (b, o + 4))
+    end),
+})

package/src/codec/datatype/Ray.luau

@@ -0,0 +1,27 @@
+--!strict
+--!native
+-- Ray codec. 24 bytes: origin vec3 + direction vec3.
+
+local Base = require (script.Parent.Parent.Base)
+
+return table.freeze ({
+    ray = Base.define (24, function (b: buffer, o: number, v: Ray): ()
+        local origin = v.Origin
+        local direction = v.Direction
+        buffer.writef32 (b, o, origin.X)
+        buffer.writef32 (b, o + 4, origin.Y)
+        buffer.writef32 (b, o + 8, origin.Z)
+        buffer.writef32 (b, o + 12, direction.X)
+        buffer.writef32 (b, o + 16, direction.Y)
+        buffer.writef32 (b, o + 20, direction.Z)
+    end, function (b: buffer, o: number): Ray
+        return Ray.new (
+            Vector3.new (buffer.readf32 (b, o), buffer.readf32 (b, o + 4), buffer.readf32 (b, o + 8)),
+            Vector3.new (
+                buffer.readf32 (b, o + 12),
+                buffer.readf32 (b, o + 16),
+                buffer.readf32 (b, o + 20)
+            )
+        )
+    end),
+})

package/src/codec/datatype/Rect.luau

@@ -0,0 +1,21 @@
+--!strict
+--!native
+-- Rect codec. 16 bytes: 4x f32.
+
+local Base = require (script.Parent.Parent.Base)
+
+return table.freeze ({
+    rect = Base.define (16, function (b: buffer, o: number, v: Rect): ()
+        buffer.writef32 (b, o, v.Min.X)
+        buffer.writef32 (b, o + 4, v.Min.Y)
+        buffer.writef32 (b, o + 8, v.Max.X)
+        buffer.writef32 (b, o + 12, v.Max.Y)
+    end, function (b: buffer, o: number): Rect
+        return Rect.new (
+            buffer.readf32 (b, o),
+            buffer.readf32 (b, o + 4),
+            buffer.readf32 (b, o + 8),
+            buffer.readf32 (b, o + 12)
+        )
+    end),
+})

package/src/codec/datatype/Region.luau

@@ -0,0 +1,58 @@
+--!strict
+--!native
+-- Region3 (24B) and Region3int16 (12B) codecs.
+
+local Base = require (script.Parent.Parent.Base)
+
+local function writeRegion3 (b: buffer, o: number, v: Region3): ()
+    local cf = v.CFrame
+    local size = v.Size
+    local halfSize = size * 0.5
+    local pos = cf.Position
+    local minV = pos - halfSize
+    local maxV = pos + halfSize
+    buffer.writef32 (b, o, minV.X)
+    buffer.writef32 (b, o + 4, minV.Y)
+    buffer.writef32 (b, o + 8, minV.Z)
+    buffer.writef32 (b, o + 12, maxV.X)
+    buffer.writef32 (b, o + 16, maxV.Y)
+    buffer.writef32 (b, o + 20, maxV.Z)
+end
+
+local function readRegion3 (b: buffer, o: number): Region3
+    return Region3.new (
+        Vector3.new (buffer.readf32 (b, o), buffer.readf32 (b, o + 4), buffer.readf32 (b, o + 8)),
+        Vector3.new (
+            buffer.readf32 (b, o + 12),
+            buffer.readf32 (b, o + 16),
+            buffer.readf32 (b, o + 20)
+        )
+    )
+end
+
+return table.freeze ({
+    region3 = Base.define (24, writeRegion3, readRegion3),
+    region3int16 = Base.define (12, function (b: buffer, o: number, v: Region3int16): ()
+        local minV = v.Min
+        local maxV = v.Max
+        buffer.writei16 (b, o, minV.X)
+        buffer.writei16 (b, o + 2, minV.Y)
+        buffer.writei16 (b, o + 4, minV.Z)
+        buffer.writei16 (b, o + 6, maxV.X)
+        buffer.writei16 (b, o + 8, maxV.Y)
+        buffer.writei16 (b, o + 10, maxV.Z)
+    end, function (b: buffer, o: number): Region3int16
+        return Region3int16.new (
+            Vector3int16.new (
+                buffer.readi16 (b, o),
+                buffer.readi16 (b, o + 2),
+                buffer.readi16 (b, o + 4)
+            ),
+            Vector3int16.new (
+                buffer.readi16 (b, o + 6),
+                buffer.readi16 (b, o + 8),
+                buffer.readi16 (b, o + 10)
+            )
+        )
+    end),
+})

package/src/codec/datatype/Sequence.luau

@@ -0,0 +1,129 @@
+--!strict
+--!native
+-- NumberSequence and ColorSequence codecs with varint length prefix.
+
+local Channel = require (script.Parent.Parent.Parent.internal.Channel)
+local alloc = Channel.alloc
+local Types = require (script.Parent.Parent.Parent.Types)
+local Varint = require (script.Parent.Parent.primitive.Varint)
+
+type ChannelState = Types.ChannelState
+
+type ChannelState = Types.ChannelState
+
+-- Constants --------------------------------------------------------------
+
+local NS_STRIDE = 12
+local CS_STRIDE = 7
+
+local round = math.round
+local clamp = math.clamp
+
+-- Public -----------------------------------------------------------------
+
+local Sequence = {}
+
+Sequence.numberSequence = table.freeze ({
+    write = function (ch: ChannelState, value: NumberSequence): ()
+        local keypoints = value.Keypoints
+        local count = #keypoints
+        Varint.write (ch, count)
+
+        if count == 0 then
+            return
+        end
+
+        local totalBytes = count * NS_STRIDE
+        local c = ch.cursor
+        if c + totalBytes > ch.size then
+            alloc (ch, totalBytes)
+        end
+
+        local b = ch.buff
+        for i = 1, count do
+            local kp = keypoints[i]
+            buffer.writef32 (b, c, kp.Time)
+            buffer.writef32 (b, c + 4, kp.Value)
+            buffer.writef32 (b, c + 8, kp.Envelope)
+            c += NS_STRIDE
+        end
+
+        ch.cursor = c
+    end,
+    read = function (src: buffer, pos: number, _refs: { Instance }?): (NumberSequence, number)
+        local count, lenBytes = Varint.read (src, pos)
+        local absPos = pos + lenBytes
+
+        if count == 0 then
+            return NumberSequence.new (0), lenBytes
+        end
+
+        local keypoints = table.create (count)
+        for i = 1, count do
+            keypoints[i] = NumberSequenceKeypoint.new (
+                buffer.readf32 (src, absPos),
+                buffer.readf32 (src, absPos + 4),
+                buffer.readf32 (src, absPos + 8)
+            )
+            absPos += NS_STRIDE
+        end
+
+        return NumberSequence.new (keypoints), absPos - pos
+    end,
+})
+
+Sequence.colorSequence = table.freeze ({
+    write = function (ch: ChannelState, value: ColorSequence): ()
+        local keypoints = value.Keypoints
+        local count = #keypoints
+        Varint.write (ch, count)
+
+        if count == 0 then
+            return
+        end
+
+        local totalBytes = count * CS_STRIDE
+        local c = ch.cursor
+        if c + totalBytes > ch.size then
+            alloc (ch, totalBytes)
+        end
+
+        local b = ch.buff
+        for i = 1, count do
+            local kp = keypoints[i]
+            local color = kp.Value
+            buffer.writef32 (b, c, kp.Time)
+            buffer.writeu8 (b, c + 4, round (clamp (color.R, 0, 1) * 255))
+            buffer.writeu8 (b, c + 5, round (clamp (color.G, 0, 1) * 255))
+            buffer.writeu8 (b, c + 6, round (clamp (color.B, 0, 1) * 255))
+            c += CS_STRIDE
+        end
+
+        ch.cursor = c
+    end,
+    read = function (src: buffer, pos: number, _refs: { Instance }?): (ColorSequence, number)
+        local count, lenBytes = Varint.read (src, pos)
+        local absPos = pos + lenBytes
+
+        if count == 0 then
+            return ColorSequence.new (Color3.new ()), lenBytes
+        end
+
+        local keypoints = table.create (count)
+        for i = 1, count do
+            keypoints[i] = ColorSequenceKeypoint.new (
+                buffer.readf32 (src, absPos),
+                Color3.fromRGB (
+                    buffer.readu8 (src, absPos + 4),
+                    buffer.readu8 (src, absPos + 5),
+                    buffer.readu8 (src, absPos + 6)
+                )
+            )
+            absPos += CS_STRIDE
+        end
+
+        return ColorSequence.new (keypoints), absPos - pos
+    end,
+})
+
+return table.freeze (Sequence)

package/src/codec/datatype/String.luau

@@ -0,0 +1,87 @@
+--!strict
+--!native
+-- Variable-length string codec with varint length prefix.
+
+local Channel = require (script.Parent.Parent.Parent.internal.Channel)
+local alloc = Channel.alloc
+local Types = require (script.Parent.Parent.Parent.Types)
+local Varint = require (script.Parent.Parent.primitive.Varint)
+
+type ChannelState = Types.ChannelState
+
+-- Constants --------------------------------------------------------------
+
+local floor = math.floor
+
+-- Public -----------------------------------------------------------------
+
+local String = {}
+
+String.string = table.freeze ({
+    write = function (ch: ChannelState, value: string): ()
+        local len = #value
+
+        if len < 128 then
+            local total = 1 + len
+            local c = ch.cursor
+            if c + total > ch.size then
+                alloc (ch, total)
+            end
+            local b = ch.buff
+            buffer.writeu8 (b, c, len)
+            if len > 0 then
+                buffer.writestring (b, c + 1, value)
+            end
+            ch.cursor = c + total
+        else
+            Varint.write (ch, len)
+            local c = ch.cursor
+            if c + len > ch.size then
+                alloc (ch, len)
+            end
+            buffer.writestring (ch.buff, c, value)
+            ch.cursor = c + len
+        end
+    end,
+    read = function (src: buffer, pos: number, _refs: { Instance }?): (string, number)
+        local len, lenBytes = Varint.read (src, pos)
+        if len == 0 then
+            return "", lenBytes
+        end
+
+        local remaining = buffer.len (src) - pos - lenBytes
+        if len > remaining then
+            error (`[Lync] String length exceeds buffer: {len} > {remaining}`)
+        end
+
+        return buffer.readstring (src, pos + lenBytes, len), lenBytes + len
+    end,
+})
+
+function String.bounded (maxLength: number): any
+    if maxLength <= 0 or maxLength ~= floor (maxLength) then
+        error (`[Lync] boundedString maxLength must be a positive integer, got {maxLength}`)
+    end
+
+    return table.freeze ({
+        write = String.string.write,
+        read = function (src: buffer, pos: number, _refs: { Instance }?): (string, number)
+            local len, lenBytes = Varint.read (src, pos)
+            if len > maxLength then
+                error (`[Lync] String length {len} exceeds max {maxLength}`)
+            end
+            if len == 0 then
+                return "", lenBytes
+            end
+
+            local remaining = buffer.len (src) - pos - lenBytes
+            if len > remaining then
+                error (`[Lync] String length exceeds buffer: {len} > {remaining}`)
+            end
+
+            return buffer.readstring (src, pos + lenBytes, len), lenBytes + len
+        end,
+    })
+end
+
+return table.freeze (String)