@axpecter/lync 1.5.1 → 2.0.0

package/src/codec/composite/Array.luau

@@ -38,6 +38,7 @@ function Array.deltaArray(element: Codec<any>, maxCount: number?): Codec<{ any }
 
     return table.freeze({
         _isDelta = true,
+        _hasUnknown = (element :: any)._hasUnknown or nil,
 
         write = function(ch: ChannelState, value: { any }): ()
             local len = #value
@@ -110,12 +111,14 @@ function Array.deltaArray(element: Codec<any>, maxCount: number?): Codec<{ any }
                 ch.cursor += 1
                 Varint.write(ch, dirtyN)
 
+                local prevIdx = 0
                 for j = 1, dirtyN do
                     local i = dirty[j]
                     local newOff = bounds[i]
                     local newLen = bounds[i + 1] - newOff
 
-                    Varint.write(ch, i - 1)
+                    Varint.write(ch, (i - 1) - prevIdx)
+                    prevIdx = i - 1
                     alloc(ch, newLen)
                     buffer.copy(ch.buff, ch.cursor, scratch.buff, newOff, newLen)
                     ch.cursor += newLen
@@ -167,21 +170,26 @@ function Array.deltaArray(element: Codec<any>, maxCount: number?): Codec<{ any }
             end
 
             local cache = Baseline.getCache(deltaId) :: { any }?
-            local result = if cache then table.clone(cache) else {}
+            if not cache then
+                error("[Lync] Delta frame without baseline")
+            end
+            local result = table.clone(cache)
 
             local dirtyN, dnBytes = Varint.read(src, absPos)
             absPos += dnBytes
 
+            local runningIdx = 0
             for _ = 1, dirtyN do
-                local idx, idxBytes = Varint.read(src, absPos)
-                absPos += idxBytes
+                local delta, deltaBytes = Varint.read(src, absPos)
+                absPos += deltaBytes
+                runningIdx += delta
 
                 if elemRead and elemSize then
-                    result[idx + 1] = elemRead(src, absPos)
+                    result[runningIdx + 1] = elemRead(src, absPos)
                     absPos += elemSize
                 else
                     local val, n = readElement(src, absPos, refs)
-                    result[idx + 1] = val
+                    result[runningIdx + 1] = val
                     absPos += n
                 end
             end
@@ -198,8 +206,78 @@ function Array.array(element: Codec<any>, maxCount: number?): Codec<{ any }>
     local directWrite = internal._directWrite
     local directRead = internal._directRead
 
+    local band = bit32.band
+    local bor = bit32.bor
+    local lshift = bit32.lshift
+    local rshift = bit32.rshift
+    local ceil = math.ceil
+
+    -- Bitpacked bool array: 8 bools per byte
+    if internal._isBool then
+        return table.freeze({
+            _hasUnknown = nil,
+            write = function(ch: ChannelState, value: { any }): ()
+                local len = #value
+                Varint.write(ch, len)
+                if len == 0 then
+                    return
+                end
+
+                local byteCount = ceil(len / 8)
+                local c = ch.cursor
+                if c + byteCount > ch.size then
+                    alloc(ch, byteCount)
+                end
+
+                local b = ch.buff
+                local byteIdx = 0
+                local acc = 0
+                for i = 1, len do
+                    local bit = (i - 1) % 8
+                    if value[i] then
+                        acc = bor(acc, lshift(1, bit))
+                    end
+                    if bit == 7 then
+                        buffer.writeu8(b, c + byteIdx, acc)
+                        byteIdx += 1
+                        acc = 0
+                    end
+                end
+                -- Flush remaining bits
+                if len % 8 ~= 0 then
+                    buffer.writeu8(b, c + byteIdx, acc)
+                end
+                ch.cursor = c + byteCount
+            end,
+            read = function(src: buffer, pos: number, _refs: { Instance }?): ({ boolean }, number)
+                local len, lenBytes = Varint.read(src, pos)
+
+                if maxCount and len > maxCount then
+                    error(`[Lync] Array count {len} exceeds max {maxCount}`)
+                end
+
+                local result = table.create(len)
+                if len == 0 then
+                    return result, lenBytes
+                end
+
+                local byteCount = ceil(len / 8)
+                local c = pos + lenBytes
+                for i = 1, len do
+                    local byteIdx = rshift(i - 1, 3)
+                    local bit = (i - 1) % 8
+                    local byte = buffer.readu8(src, c + byteIdx)
+                    result[i] = band(byte, lshift(1, bit)) ~= 0
+                end
+
+                return result, lenBytes + byteCount
+            end,
+        })
+    end
+
     if elementSize and directWrite and directRead then
         return table.freeze({
+            _hasUnknown = (element :: any)._hasUnknown or nil,
             write = function(ch: ChannelState, value: { any }): ()
                 local len = #value
                 Varint.write(ch, len)
@@ -244,6 +322,7 @@ function Array.array(element: Codec<any>, maxCount: number?): Codec<{ any }>
     local readElement = element.read
 
     return table.freeze({
+        _hasUnknown = (element :: any)._hasUnknown or nil,
         write = function(ch: ChannelState, value: { any }): ()
             local len = #value
             Varint.write(ch, len)

package/src/codec/composite/Map.luau

@@ -44,6 +44,7 @@ function Map.map(
         local entrySize = keySize + valSize
 
         return table.freeze({
+            _hasUnknown = (keyCodec :: any)._hasUnknown or (valueCodec :: any)._hasUnknown or nil,
             write = function(ch: ChannelState, value: { [any]: any }): ()
                 local count = 0
                 for _ in value do
@@ -100,6 +101,7 @@ function Map.map(
     local readVal = valueCodec.read
 
     return table.freeze({
+        _hasUnknown = (keyCodec :: any)._hasUnknown or (valueCodec :: any)._hasUnknown or nil,
         write = function(ch: ChannelState, value: { [any]: any }): ()
             local count = 0
             for _ in value do
@@ -185,6 +187,7 @@ function Map.deltaMap(
 
     return table.freeze({
         _isDelta = true,
+        _hasUnknown = (keyCodec :: any)._hasUnknown or (valueCodec :: any)._hasUnknown or nil,
 
         write = function(ch: ChannelState, value: { [any]: any }): ()
             local scratch = acquireScratch()
@@ -378,7 +381,10 @@ function Map.deltaMap(
             end
 
             local cache = Baseline.getCache(deltaId) :: { [any]: any }?
-            local result = if cache then table.clone(cache) else {}
+            if not cache then
+                error("[Lync] Delta frame without baseline")
+            end
+            local result = table.clone(cache)
 
             local upsertN, unBytes = Varint.read(src, absPos)
             absPos += unBytes

package/src/codec/composite/Optional.luau

@@ -19,6 +19,7 @@ function Optional.optional(inner: Codec<any>): Codec<any>
     local innerRead = inner.read
 
     return table.freeze({
+        _hasUnknown = (inner :: any)._hasUnknown or nil,
         write = function(ch: ChannelState, value: any): ()
             local c = ch.cursor
             if c + 1 > ch.size then

package/src/codec/composite/Struct.luau

@@ -47,6 +47,14 @@ function Struct.struct(schema: { [string]: Codec<any> }): Codec<any>
     local boolByteCount = ceil(boolCount / 8)
     local hasBools = boolCount > 0
 
+    local hasUnknown = false
+    for _, fieldCodec in schema do
+        if (fieldCodec :: any)._hasUnknown then
+            hasUnknown = true
+            break
+        end
+    end
+
     local canDirect = true
     local fixedSize = boolByteCount
     local isAllFixed = true
@@ -126,6 +134,7 @@ function Struct.struct(schema: { [string]: Codec<any> }): Codec<any>
             _size = fixedSize,
             _directWrite = directWriteBody,
             _directRead = directReadBody,
+            _hasUnknown = hasUnknown or nil,
 
             write = function(ch: ChannelState, value: any): ()
                 local c = ch.cursor
@@ -152,6 +161,7 @@ function Struct.struct(schema: { [string]: Codec<any> }): Codec<any>
 
     return table.freeze({
         _size = if isAllFixed then fixedSize else nil,
+        _hasUnknown = hasUnknown or nil,
 
         write = function(ch: ChannelState, value: any): ()
             if isAllFixed then
@@ -195,6 +205,14 @@ function Struct.deltaStruct(schema: { [string]: Codec<any> }): Codec<any>
     local bitmaskBytes = ceil(segCount / 8)
     local deltaId = Shared.allocDeltaId()
 
+    local hasUnknown = false
+    for _, fieldCodec in schema do
+        if (fieldCodec :: any)._hasUnknown then
+            hasUnknown = true
+            break
+        end
+    end
+
     -- Scratch bounds reused every frame(only cloned into cache)
     local _scratchBounds = table.create(segCount + 1) :: { number }
     _scratchBounds[1] = 0
@@ -237,6 +255,7 @@ function Struct.deltaStruct(schema: { [string]: Codec<any> }): Codec<any>
 
     return table.freeze({
         _isDelta = true,
+        _hasUnknown = hasUnknown or nil,
 
         write = function(ch: ChannelState, value: any): ()
             local cache = ch.deltas[deltaId] :: DeltaCache?
@@ -413,7 +432,10 @@ function Struct.deltaStruct(schema: { [string]: Codec<any> }): Codec<any>
             end
 
             local cache = Baseline.getCache(deltaId) :: any
-            local result = if cache then table.clone(cache) else {}
+            if not cache then
+                error("[Lync] Delta frame without baseline")
+            end
+            local result = table.clone(cache)
 
             local maskStart = absPos
             absPos += bitmaskBytes

package/src/codec/composite/Tagged.luau

@@ -71,6 +71,14 @@ function Tagged.define(tagField: string, variants: { [string]: Codec<any> }): Co
         end
     end
 
+    local hasUnknown = false
+    for i = 1, count do
+        if (tagCodecs[i] :: any)._hasUnknown then
+            hasUnknown = true
+            break
+        end
+    end
+
     table.freeze(nameToTag)
     table.freeze(tagCodecs)
     table.freeze(tagNames)
@@ -86,6 +94,7 @@ function Tagged.define(tagField: string, variants: { [string]: Codec<any> }): Co
         if fixedSize then
             return table.freeze({
                 _size = fixedSize,
+                _hasUnknown = hasUnknown or nil,
                 _directWrite = function(b: buffer, offset: number, value: any): ()
                     local tag = nameToTag[value[tagField]]
                     if not tag then
@@ -141,6 +150,7 @@ function Tagged.define(tagField: string, variants: { [string]: Codec<any> }): Co
 
         return table.freeze({
             _size = nil,
+            _hasUnknown = hasUnknown or nil,
             write = function(ch: ChannelState, value: any): ()
                 local tag = nameToTag[value[tagField]]
                 if not tag then
@@ -183,6 +193,7 @@ function Tagged.define(tagField: string, variants: { [string]: Codec<any> }): Co
 
     return table.freeze({
         _size = fixedSize,
+        _hasUnknown = hasUnknown or nil,
         write = function(ch: ChannelState, value: any): ()
             local tag = nameToTag[value[tagField]]
             if not tag then

package/src/codec/composite/Tuple.luau

@@ -24,6 +24,14 @@ function Tuple.define(...: Codec<any>): Codec<{ any }>
 
     table.freeze(codecs)
 
+    local hasUnknown = false
+    for i = 1, count do
+        if (codecs[i] :: any)._hasUnknown then
+            hasUnknown = true
+            break
+        end
+    end
+
     local canDirect = true
     local totalSize: number = 0
     local directWrites = table.create(count) :: { any }
@@ -92,6 +100,7 @@ function Tuple.define(...: Codec<any>): Codec<{ any }>
             _size = totalSize,
             _directWrite = directWriteBody,
             _directRead = directReadBody,
+            _hasUnknown = hasUnknown or nil,
             write = function(ch: ChannelState, value: { any }): ()
                 local c = ch.cursor
                 if c + totalSize > ch.size then
@@ -119,6 +128,7 @@ function Tuple.define(...: Codec<any>): Codec<{ any }>
 
     return table.freeze({
         _size = totalSize,
+        _hasUnknown = hasUnknown or nil,
         write = function(ch: ChannelState, value: { any }): ()
             if hasFixedTotal then
                 alloc(ch, totalSize :: number)

package/src/codec/datatype/Instance.luau

@@ -41,6 +41,9 @@ InstanceCodec.inst = table.freeze({
         if not inst then
             error(`[Lync] Instance ref index out of bounds: {idx}`)
         end
+        if typeof(inst) ~= "Instance" then
+            error("[Lync] Invalid ref: expected Instance")
+        end
 
         return inst, 2
     end,

package/src/codec/meta/Unknown.luau

@@ -11,6 +11,7 @@ local alloc = Channel.alloc
 
 return table.freeze({
     unknown = table.freeze({
+        _hasUnknown = true,
         write = function(ch: ChannelState, value: any): ()
             local refs = ch.refs
             local idx = #refs + 1

package/src/index.d.ts

@@ -100,9 +100,9 @@ export type Target = Player | AllTarget | ExceptTarget | GroupObject | Player[];
 
 export interface Scope {
     add(this: Scope, conn: Connection | RBXScriptConnection): void;
-    listen<T>(this: Scope, source: Packet<T>, callback: (data: T, sender: Player | undefined) => void): void;
-    once<T>(this: Scope, source: Packet<T>, callback: (data: T, sender: Player | undefined) => void): void;
-    listenAll(this: Scope, namespace: Namespace, callback: (name: string, data: unknown, sender: Player | undefined) => void): void;
+    listen<T>(this: Scope, source: Packet<T>, callback: (data: T, sender: Player | undefined, timestamp: number | undefined) => void): void;
+    once<T>(this: Scope, source: Packet<T>, callback: (data: T, sender: Player | undefined, timestamp: number | undefined) => void): void;
+    listenAll(this: Scope, namespace: Namespace, callback: (name: string, data: unknown, sender: Player | undefined, timestamp: number | undefined) => void): void;
     destroy(this: Scope): void;
 }
 
@@ -120,14 +120,26 @@ export interface PacketConfig<T> {
     rateLimit?: RateLimitConfig;
     validate?: (data: T, player: Player) => LuaTuple<[boolean, string?]>;
     maxPayloadBytes?: number;
+    timestamp?: "frame" | "offset" | "full";
+}
+
+export interface PlayerStats {
+    bytesSent: number;
+    bytesReceived: number;
 }
 
 export interface Packet<T> {
     send(this: Packet<T>, data: T, target?: Target): void;
-    listen(this: Packet<T>, callback: (data: T, sender: Player | undefined) => void): Connection;
-    once(this: Packet<T>, callback: (data: T, sender: Player | undefined) => void): Connection;
+    listen(this: Packet<T>, callback: (data: T, sender: Player | undefined, timestamp: number | undefined) => void): Connection;
+    once(this: Packet<T>, callback: (data: T, sender: Player | undefined, timestamp: number | undefined) => void): Connection;
     wait(this: Packet<T>): LuaTuple<[T, Player | undefined]>;
     disconnectAll(this: Packet<T>): void;
+
+    getBytesSent(this: Packet<T>): number;
+    getBytesReceived(this: Packet<T>): number;
+    getFires(this: Packet<T>): number;
+    getRecvFires(this: Packet<T>): number;
+    getDrops(this: Packet<T>): number;
 }
 
 // -- Query -------------------------------------------------------------
@@ -182,7 +194,7 @@ export interface Namespace {
     readonly queries: Record<string, Query<unknown, unknown>>;
     listenAll(
         this: Namespace,
-        callback: (name: string, data: unknown, sender: Player | undefined) => void,
+        callback: (name: string, data: unknown, sender: Player | undefined, timestamp: number | undefined) => void,
     ): Connection;
     onSend(
         this: Namespace,
@@ -306,13 +318,30 @@ declare namespace Lync {
     // Scope
     export function scope(): Scope;
 
-    // Configuration
+    // Configuration (call before start)
     export function setChannelMaxSize(bytes: number): void;
     export function setValidationDepth(depth: number): void;
     export function setPoolSize(count: number): void;
 
+    // Runtime configuration
+    export function flush(): void;
+    export function setFlushRate(hz: number): void;
+
+    // Stats (default off; call enableStats() to activate)
+    export function enableStats(): void;
+    export function getPlayerStats(player: Player): PlayerStats | undefined;
+    export function resetStats(): void;
+
+    // Security (server-only)
+    export function setBandwidthLimit(softLimit: number, maxStrikes: number): void;
+
     // Introspection
     export function queryPendingCount(): number;
+
+    // Packet capture (server-only, debug)
+    export function startCapture(label?: string): void;
+    export function stopCapture(): void;
+    export function dumpCaptures(): void;
 }
 
 export default Lync;

package/src/init.luau

@@ -103,8 +103,38 @@ end
 
 -- Public --------------------------------------------------------------
 
+local IS_SERVER = RunService:IsServer()
+
+local function flush(): ()
+    if IS_SERVER then
+        Server.flush()
+    else
+        Client.flush()
+    end
+end
+
+local function setFlushRate(hz: number): ()
+    if IS_SERVER then
+        Server.setFlushRate(hz)
+    else
+        Client.setFlushRate(hz)
+    end
+end
+
+local function getPlayerStats(player: Player): any?
+    return Server.getPlayerStats(player)
+end
+
+local function resetStats(): ()
+    Server.resetStats()
+end
+
+local function setBandwidthLimit(softLimit: number, maxStrikes: number): ()
+    Server.setBandwidthLimit(softLimit, maxStrikes)
+end
+
 local Lync = {
-    VERSION = "1.5.1",
+    VERSION = "2.0.0",
 
     -- Lifecycle
     start = start,
@@ -187,13 +217,30 @@ local Lync = {
     -- Scope
     scope = ScopeModule.create,
 
-    -- Configuration(call before start)
+    -- Configuration (call before start)
     setChannelMaxSize = Channel.setMaxSize,
     setValidationDepth = Gate.setMaxDepth,
     setPoolSize = Pool.setMaxSize,
 
+    -- Runtime configuration
+    flush = flush,
+    setFlushRate = setFlushRate,
+
+    -- Stats (default off; call enableStats() to activate)
+    enableStats = Channel.enableStats,
+    getPlayerStats = getPlayerStats,
+    resetStats = resetStats,
+
+    -- Security (server-only)
+    setBandwidthLimit = setBandwidthLimit,
+
     -- Introspection
     queryPendingCount = QueryModule.pendingCount,
+
+    -- Packet capture (server-only, debug)
+    startCapture = if IS_SERVER then Server.startCapture else nil,
+    stopCapture = if IS_SERVER then Server.stopCapture else nil,
+    dumpCaptures = if IS_SERVER then Server.dumpCaptures else nil,
 }
 
 Lync.default = Lync