@axpecter/lync 1.3.0

package/src/codec/composite/Struct.luau

@@ -0,0 +1,440 @@
+--!strict
+--!native
+-- struct and deltaStruct codecs.
+
+local Baseline = require (script.Parent.Parent.Parent.internal.Baseline)
+local Channel = require (script.Parent.Parent.Parent.internal.Channel)
+local alloc = Channel.alloc
+local Shared = require (script.Parent.Shared)
+local Types = require (script.Parent.Parent.Parent.Types)
+
+type ChannelState = Types.ChannelState
+type Codec<T> = Types.Codec<T>
+
+local extractFields = Shared.extractFields
+local packBools = Shared.packBools
+local unpackBools = Shared.unpackBools
+local rangeEqual = Shared.rangeEqual
+local acquireScratch = Shared.acquireScratch
+local releaseScratch = Shared.releaseScratch
+
+local FLAG_DELTA = Shared.FLAG_DELTA
+local FLAG_FULL = Shared.FLAG_FULL
+local FLAG_UNCHANGED = Shared.FLAG_UNCHANGED
+
+local band = bit32.band
+local bor = bit32.bor
+local lshift = bit32.lshift
+local ceil = math.ceil
+local min = math.min
+
+type DeltaCache = {
+    raw: buffer,
+    bounds: { number },
+    total: number,
+}
+
+-- Public -----------------------------------------------------------------
+
+local Struct = {}
+
+function Struct.struct (schema: { [string]: Codec<any> }): Codec<any>
+    local dataKeys, dataCodecs, boolKeys = extractFields (schema)
+
+    local dataCount = #dataKeys
+    local boolCount = #boolKeys
+    local boolByteCount = ceil (boolCount / 8)
+    local hasBools = boolCount > 0
+
+    local canDirect = true
+    local fixedSize = boolByteCount
+    local isAllFixed = true
+
+    local directWrites = table.create (dataCount) :: { any }
+    local directReads = table.create (dataCount) :: { any }
+    local fieldSizes = table.create (dataCount) :: { number }
+
+    for i = 1, dataCount do
+        local codec = dataCodecs[i] :: any
+        local size = codec._size
+        local dw = codec._directWrite
+        local dr = codec._directRead
+
+        if size then
+            fixedSize += size
+            fieldSizes[i] = size
+        else
+            isAllFixed = false
+            canDirect = false
+        end
+
+        if not (dw and dr and size) then
+            canDirect = false
+        else
+            directWrites[i] = dw
+            directReads[i] = dr
+        end
+    end
+
+    if canDirect and isAllFixed then
+        table.freeze (directWrites)
+        table.freeze (directReads)
+        table.freeze (fieldSizes)
+
+        local function directWriteBody (b: buffer, c: number, value: any): ()
+            for i = 1, dataCount do
+                directWrites[i] (b, c, value[dataKeys[i]])
+                c += fieldSizes[i]
+            end
+            if hasBools then
+                for byteIdx = 0, boolByteCount - 1 do
+                    local packed = 0
+                    local base = byteIdx * 8
+                    local limit = min (8, boolCount - base)
+                    for bit = 0, limit - 1 do
+                        if value[boolKeys[base + bit + 1]] then
+                            packed = bor (packed, lshift (1, bit))
+                        end
+                    end
+                    buffer.writeu8 (b, c + byteIdx, packed)
+                end
+            end
+        end
+
+        local function directReadBody (b: buffer, pos: number): any
+            local result = {}
+            local c = pos
+            for i = 1, dataCount do
+                result[dataKeys[i]] = directReads[i] (b, c)
+                c += fieldSizes[i]
+            end
+            if hasBools then
+                for byteIdx = 0, boolByteCount - 1 do
+                    local byte = buffer.readu8 (b, c + byteIdx)
+                    local base = byteIdx * 8
+                    local limit = min (8, boolCount - base)
+                    for bit = 0, limit - 1 do
+                        result[boolKeys[base + bit + 1]] = band (byte, lshift (1, bit)) ~= 0
+                    end
+                end
+            end
+            return result
+        end
+
+        return table.freeze ({
+            _size = fixedSize,
+            _directWrite = directWriteBody,
+            _directRead = directReadBody,
+
+            write = function (ch: ChannelState, value: any): ()
+                local c = ch.cursor
+                if c + fixedSize > ch.size then
+                    alloc (ch, fixedSize)
+                end
+                directWriteBody (ch.buff, c, value)
+                ch.cursor = c + fixedSize
+            end,
+            read = function (src: buffer, pos: number, _refs: { Instance }?): (any, number)
+                return directReadBody (src, pos), fixedSize
+            end,
+        })
+    end
+
+    local writeFns = table.create (dataCount) :: { any }
+    local readFns = table.create (dataCount) :: { any }
+    for i = 1, dataCount do
+        writeFns[i] = dataCodecs[i].write
+        readFns[i] = dataCodecs[i].read
+    end
+    table.freeze (writeFns)
+    table.freeze (readFns)
+
+    return table.freeze ({
+        _size = if isAllFixed then fixedSize else nil,
+
+        write = function (ch: ChannelState, value: any): ()
+            if isAllFixed then
+                alloc (ch, fixedSize)
+            end
+
+            for i = 1, dataCount do
+                writeFns[i] (ch, value[dataKeys[i]])
+            end
+
+            if hasBools then
+                packBools (ch, boolKeys, boolCount, value)
+            end
+        end,
+        read = function (src: buffer, pos: number, refs: { Instance }?): (any, number)
+            local result = {}
+            local absPos = pos
+
+            for i = 1, dataCount do
+                local value, n = readFns[i] (src, absPos, refs)
+                result[dataKeys[i]] = value
+                absPos += n
+            end
+
+            if hasBools then
+                absPos += unpackBools (src, absPos, boolKeys, boolCount, result)
+            end
+
+            return result, absPos - pos
+        end,
+    })
+end
+function Struct.deltaStruct (schema: { [string]: Codec<any> }): Codec<any>
+    local dataKeys, dataCodecs, boolKeys = extractFields (schema)
+
+    local dataCount = #dataKeys
+    local boolCount = #boolKeys
+    local boolByteCount = ceil (boolCount / 8)
+    local segCount = dataCount + (if boolCount > 0 then 1 else 0)
+    local bitmaskBytes = ceil (segCount / 8)
+    local deltaId = Shared.allocDeltaId ()
+
+    -- Scratch bounds reused every frame (only cloned into cache)
+    local _scratchBounds = table.create (segCount + 1) :: { number }
+    _scratchBounds[1] = 0
+
+    local writeFns = table.create (dataCount) :: { any }
+    local readFns = table.create (dataCount) :: { any }
+    for i = 1, dataCount do
+        writeFns[i] = dataCodecs[i].write
+        readFns[i] = dataCodecs[i].read
+    end
+    table.freeze (writeFns)
+    table.freeze (readFns)
+
+    local scratchDirect = true
+    local scratchDirectWrites = table.create (dataCount) :: { any }
+    local scratchFieldSizes = table.create (dataCount) :: { number }
+    local scratchFieldOffsets = table.create (dataCount) :: { number }
+    local scratchDataTotal = 0
+
+    for i = 1, dataCount do
+        local codec = dataCodecs[i] :: any
+        local size = codec._size
+        local dw = codec._directWrite
+        if size and dw then
+            scratchDirectWrites[i] = dw
+            scratchFieldSizes[i] = size
+            scratchFieldOffsets[i] = scratchDataTotal
+            scratchDataTotal += size
+        else
+            scratchDirect = false
+            break
+        end
+    end
+
+    local scratchTotalFixed = scratchDataTotal + boolByteCount
+
+    -- Skip scratch alloc at runtime when the total fits in the initial
+    -- 1024-byte scratch buffer.
+    local scratchSkipAlloc = scratchDirect and scratchTotalFixed <= 1024
+
+    return table.freeze ({
+        _isDelta = true,
+
+        write = function (ch: ChannelState, value: any): ()
+            local cache = ch.deltas[deltaId] :: DeltaCache?
+            local scratch = acquireScratch ()
+
+            local bounds = _scratchBounds
+            bounds[1] = 0
+
+            if scratchDirect then
+                if not scratchSkipAlloc then
+                    alloc (scratch, scratchTotalFixed)
+                end
+                local b = scratch.buff
+
+                for i = 1, dataCount do
+                    scratchDirectWrites[i] (b, scratchFieldOffsets[i], value[dataKeys[i]])
+                    bounds[i + 1] = scratchFieldOffsets[i] + scratchFieldSizes[i]
+                end
+                scratch.cursor = scratchDataTotal
+
+                if boolCount > 0 then
+                    packBools (scratch, boolKeys, boolCount, value)
+                    bounds[segCount + 1] = scratch.cursor
+                end
+            else
+                for i = 1, dataCount do
+                    writeFns[i] (scratch, value[dataKeys[i]])
+                    bounds[i + 1] = scratch.cursor
+                end
+
+                if boolCount > 0 then
+                    packBools (scratch, boolKeys, boolCount, value)
+                    bounds[segCount + 1] = scratch.cursor
+                end
+            end
+
+            local scratchTotal = scratch.cursor
+
+            -- FLAG_FULL: first frame, no cache exists yet
+            if not cache then
+                alloc (ch, 1 + scratchTotal)
+                buffer.writeu8 (ch.buff, ch.cursor, FLAG_FULL)
+                ch.cursor += 1
+                buffer.copy (ch.buff, ch.cursor, scratch.buff, 0, scratchTotal)
+                ch.cursor += scratchTotal
+
+            -- FLAG_UNCHANGED: entire buffer is byte-identical to cache
+            elseif
+                scratchTotal == cache.total
+                and rangeEqual (scratch.buff, 0, cache.raw, 0, scratchTotal)
+            then
+                alloc (ch, 1)
+                buffer.writeu8 (ch.buff, ch.cursor, FLAG_UNCHANGED)
+                ch.cursor += 1
+                releaseScratch ()
+                return
+
+            -- FLAG_DELTA: per-segment dirty mask + dirty payloads
+            elseif bitmaskBytes == 1 then
+                local mask = 0
+                local cacheRaw = cache.raw
+                local cacheBds = cache.bounds
+
+                for i = 1, segCount do
+                    local newOff = bounds[i]
+                    local newLen = bounds[i + 1] - newOff
+                    local oldOff = cacheBds[i]
+                    local oldLen = cacheBds[i + 1] - oldOff
+
+                    if
+                        newLen ~= oldLen
+                        or not rangeEqual (scratch.buff, newOff, cacheRaw, oldOff, newLen)
+                    then
+                        mask = bor (mask, lshift (1, i - 1))
+                    end
+                end
+
+                alloc (ch, 2)
+                buffer.writeu8 (ch.buff, ch.cursor, FLAG_DELTA)
+                buffer.writeu8 (ch.buff, ch.cursor + 1, mask)
+                ch.cursor += 2
+
+                for i = 1, segCount do
+                    if band (mask, lshift (1, i - 1)) ~= 0 then
+                        local newOff = bounds[i]
+                        local newLen = bounds[i + 1] - newOff
+                        alloc (ch, newLen)
+                        buffer.copy (ch.buff, ch.cursor, scratch.buff, newOff, newLen)
+                        ch.cursor += newLen
+                    end
+                end
+            else
+                local maskBuf = table.create (bitmaskBytes, 0)
+                local cacheRaw = cache.raw
+                local cacheBds = cache.bounds
+
+                for i = 1, segCount do
+                    local newOff = bounds[i]
+                    local newLen = bounds[i + 1] - newOff
+                    local oldOff = cacheBds[i]
+                    local oldLen = cacheBds[i + 1] - oldOff
+
+                    if
+                        newLen ~= oldLen
+                        or not rangeEqual (scratch.buff, newOff, cacheRaw, oldOff, newLen)
+                    then
+                        local bitIdx = i - 1
+                        local byteIdx = bitIdx // 8 + 1
+                        maskBuf[byteIdx] = bor (maskBuf[byteIdx], lshift (1, bitIdx % 8))
+                    end
+                end
+
+                alloc (ch, 1 + bitmaskBytes)
+                buffer.writeu8 (ch.buff, ch.cursor, FLAG_DELTA)
+                ch.cursor += 1
+
+                local maskStart = ch.cursor
+                for byteIdx = 1, bitmaskBytes do
+                    buffer.writeu8 (ch.buff, maskStart + byteIdx - 1, maskBuf[byteIdx])
+                end
+                ch.cursor = maskStart + bitmaskBytes
+
+                for i = 1, segCount do
+                    local bitIdx = i - 1
+                    local byteIdx = bitIdx // 8 + 1
+                    if band (maskBuf[byteIdx], lshift (1, bitIdx % 8)) ~= 0 then
+                        local newOff = bounds[i]
+                        local newLen = bounds[i + 1] - newOff
+                        alloc (ch, newLen)
+                        buffer.copy (ch.buff, ch.cursor, scratch.buff, newOff, newLen)
+                        ch.cursor += newLen
+                    end
+                end
+            end
+
+            local rawBuf = buffer.create (scratchTotal)
+            buffer.copy (rawBuf, 0, scratch.buff, 0, scratchTotal)
+
+            local cacheBounds = table.clone (bounds)
+            table.freeze (cacheBounds)
+            ch.deltas[deltaId] = {
+                raw = rawBuf,
+                bounds = cacheBounds,
+                total = scratchTotal,
+            } :: DeltaCache
+
+            releaseScratch ()
+        end,
+
+        read = function (src: buffer, pos: number, refs: { Instance }?): (any, number)
+            local flag = buffer.readu8 (src, pos)
+            local absPos = pos + 1
+
+            if flag == FLAG_UNCHANGED then
+                local cache = Baseline.getCache (deltaId) :: any
+                return if cache then table.clone (cache) else {}, 1
+            end
+
+            if flag == FLAG_FULL then
+                local result = {}
+
+                for i = 1, dataCount do
+                    local val, n = readFns[i] (src, absPos, refs)
+                    result[dataKeys[i]] = val
+                    absPos += n
+                end
+
+                if boolCount > 0 then
+                    absPos += unpackBools (src, absPos, boolKeys, boolCount, result)
+                end
+
+                Baseline.setCache (deltaId, result)
+                return result, absPos - pos
+            end
+
+            local cache = Baseline.getCache (deltaId) :: any
+            local result = if cache then table.clone (cache) else {}
+
+            local maskStart = absPos
+            absPos += bitmaskBytes
+
+            for i = 1, segCount do
+                local bitIdx = i - 1
+                local byte = buffer.readu8 (src, maskStart + (bitIdx // 8))
+
+                if band (byte, lshift (1, bitIdx % 8)) ~= 0 then
+                    if i <= dataCount then
+                        local val, n = readFns[i] (src, absPos, refs)
+                        result[dataKeys[i]] = val
+                        absPos += n
+                    else
+                        absPos += unpackBools (src, absPos, boolKeys, boolCount, result)
+                    end
+                end
+            end
+
+            Baseline.setCache (deltaId, result)
+            return result, absPos - pos
+        end,
+    })
+end
+
+return table.freeze (Struct)

package/src/codec/composite/Tagged.luau

@@ -0,0 +1,222 @@
+--!strict
+--!native
+-- Discriminated union codec. u8 variant tag + variant payload.
+
+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 Tagged = {}
+
+-- Read injects tagField into the decoded table. Variant codecs must return mutable tables.
+function Tagged.define (tagField: string, variants: { [string]: Codec<any> }): Codec<any>
+    if #tagField == 0 then
+        error ("[Lync] Tagged union tagField must not be empty")
+    end
+
+    local names = {} :: { string }
+    for name in variants do
+        if #name == 0 then
+            error ("[Lync] Tagged union variant name must not be empty")
+        end
+        table.insert (names, name)
+    end
+    table.sort (names)
+
+    local count = #names
+    if count == 0 then
+        error ("[Lync] Tagged union requires at least one variant")
+    end
+    if count > 256 then
+        error (`[Lync] Tagged union exceeds 256 variants: {count}`)
+    end
+
+    local nameToTag = {} :: { [string]: number }
+    local tagCodecs = table.create (count) :: { Codec<any> }
+    local tagNames = table.create (count) :: { string }
+    local tagSizes = table.create (count) :: { number? }
+
+    local allDirect = true
+    local uniformSize: number? = (variants[names[1]] :: any)._size
+    local directWrites = table.create (count) :: { any }
+    local directReads = table.create (count) :: { any }
+
+    for i, name in names do
+        local codec = variants[name] :: any
+        nameToTag[name] = i
+        tagCodecs[i] = codec
+        tagNames[i] = name
+
+        local size = codec._size
+        tagSizes[i] = size
+
+        if size ~= uniformSize then
+            uniformSize = nil
+        end
+
+        local dw = codec._directWrite
+        local dr = codec._directRead
+        if dw and dr and size then
+            directWrites[i] = dw
+            directReads[i] = dr
+        else
+            allDirect = false
+        end
+    end
+
+    table.freeze (nameToTag)
+    table.freeze (tagCodecs)
+    table.freeze (tagNames)
+    table.freeze (tagSizes)
+
+    local fixedSize: number? = if uniformSize then 1 + uniformSize else nil
+
+    if allDirect then
+        table.freeze (directWrites)
+        table.freeze (directReads)
+
+        -- If uniform size, expose _directWrite/_directRead for parent struct/array
+        if fixedSize then
+            local variantBytes = uniformSize :: number
+
+            return table.freeze ({
+                _size = fixedSize,
+                _directWrite = function (b: buffer, offset: number, value: any): ()
+                    local tag = nameToTag[value[tagField]]
+                    if not tag then
+                        error (`[Lync] Unknown variant: {value[tagField]}`)
+                    end
+                    buffer.writeu8 (b, offset, tag - 1)
+                    directWrites[tag] (b, offset + 1, value)
+                end,
+                _directRead = function (b: buffer, offset: number): any
+                    local tag = buffer.readu8 (b, offset) + 1
+                    local name = tagNames[tag]
+                    if not name then
+                        error (`[Lync] Unknown variant index: {tag - 1}`)
+                    end
+                    local data = directReads[tag] (b, offset + 1)
+                    if type (data) == "table" then
+                        data[tagField] = name
+                    end
+                    return data
+                end,
+                write = function (ch: ChannelState, value: any): ()
+                    local tag = nameToTag[value[tagField]]
+                    if not tag then
+                        error (`[Lync] Unknown variant: {value[tagField]}`)
+                    end
+                    local c = ch.cursor
+                    if c + (fixedSize :: number) > ch.size then
+                        alloc (ch, fixedSize :: number)
+                    end
+                    local b = ch.buff
+                    buffer.writeu8 (b, c, tag - 1)
+                    directWrites[tag] (b, c + 1, value)
+                    ch.cursor = c + (fixedSize :: number)
+                end,
+                read = function (src: buffer, pos: number, _refs: { Instance }?): (any, number)
+                    local tag = buffer.readu8 (src, pos) + 1
+                    local name = tagNames[tag]
+                    if not name then
+                        error (`[Lync] Unknown variant index: {tag - 1}`)
+                    end
+                    local data = directReads[tag] (src, pos + 1)
+                    if type (data) == "table" then
+                        data[tagField] = name
+                    end
+                    return data, fixedSize :: number
+                end,
+            })
+        end
+
+        -- Non-uniform sizes but all have direct: use direct dispatch internally
+        local fieldSizes = table.clone (tagSizes) :: { number }
+        table.freeze (fieldSizes)
+
+        return table.freeze ({
+            _size = nil,
+            write = function (ch: ChannelState, value: any): ()
+                local tag = nameToTag[value[tagField]]
+                if not tag then
+                    error (`[Lync] Unknown variant: {value[tagField]}`)
+                end
+                local varSize = fieldSizes[tag]
+                local totalNeeded = 1 + varSize
+                local c = ch.cursor
+                if c + totalNeeded > ch.size then
+                    alloc (ch, totalNeeded)
+                end
+                local b = ch.buff
+                buffer.writeu8 (b, c, tag - 1)
+                directWrites[tag] (b, c + 1, value)
+                ch.cursor = c + totalNeeded
+            end,
+            read = function (src: buffer, pos: number, _refs: { Instance }?): (any, number)
+                local tag = buffer.readu8 (src, pos) + 1
+                local name = tagNames[tag]
+                if not name then
+                    error (`[Lync] Unknown variant index: {tag - 1}`)
+                end
+                local data = directReads[tag] (src, pos + 1)
+                if type (data) == "table" then
+                    data[tagField] = name
+                end
+                return data, 1 + fieldSizes[tag]
+            end,
+        })
+    end
+
+    local writeFns = table.create (count) :: { any }
+    local readFns = table.create (count) :: { any }
+    for i = 1, count do
+        writeFns[i] = tagCodecs[i].write
+        readFns[i] = tagCodecs[i].read
+    end
+    table.freeze (writeFns)
+    table.freeze (readFns)
+
+    return table.freeze ({
+        _size = fixedSize,
+        write = function (ch: ChannelState, value: any): ()
+            local tag = nameToTag[value[tagField]]
+            if not tag then
+                error (`[Lync] Unknown variant: {value[tagField]}`)
+            end
+
+            local variantSize = tagSizes[tag]
+            if variantSize then
+                alloc (ch, 1 + variantSize)
+            else
+                alloc (ch, 1)
+            end
+
+            local c = ch.cursor
+            buffer.writeu8 (ch.buff, c, tag - 1)
+            ch.cursor = c + 1
+            writeFns[tag] (ch, value)
+        end,
+        read = function (src: buffer, pos: number, refs: { Instance }?): (any, number)
+            local tag = buffer.readu8 (src, pos) + 1
+            local name = tagNames[tag]
+            if not name then
+                error (`[Lync] Unknown variant index: {tag - 1}`)
+            end
+
+            local data, bytes = readFns[tag] (src, pos + 1, refs)
+
+            if type (data) == "table" then
+                data[tagField] = name
+            end
+
+            return data, 1 + bytes
+        end,
+    })
+end
+
+return table.freeze (Tagged)