ye

Author: Axp3cter

README.md

@@ -250,8 +250,9 @@ Enable with `Lync.configure({ stats = true })`.
 | Codec | Bytes | Notes |
 |:---|---:|:---|
 | `int(min, max)` | 1 / 2 / 4 | Picks narrowest u8/u16/u32/i8/i16/i32. |
+| `zint(min?, max?)` | 1 – 5 | Variable-length signed via zigzag varint. 1 byte for [-96, 95]. |
 | `f16` / `f32` / `f64` | 2 / 4 / 8 | `f16` ≈ ±65504, ~3 digits. |
-| `float(min, max, precision)` | 1 / 2 / 4 | Quantized; clamped to range. |
+| `float(min, max, precision)` | 1 / 2 / 3 / 4 | Quantized; picks u8 / u16 / u24 / u32 wire form. |
 | `bool` | 1 | Auto-bitpacked inside `struct` and `array`. |
 
 ### Strings & buffers
@@ -284,8 +285,8 @@ Call as a function for compression.
 
 | Codec | Bytes | Notes |
 |:---|---:|:---|
-| `vec2(min, max, precision)` | 2 / 4 / 8 | Per-component quantization. |
-| `vec3(min, max, precision)` | 3 / 6 / 12 | Per-component quantization. |
+| `vec2(min, max, precision)` | 2 / 4 / 6 / 8 | Per-component, narrowest fitting width. |
+| `vec3(min, max, precision)` | 3 / 6 / 9 / 12 | Per-component, narrowest fitting width. |
 | `cframe()` | 16 | Smallest-three quaternion. ≤ 0.16° rotation error. |
 
 ### Composites
@@ -301,13 +302,17 @@ Call as a function for compression.
 
 ### Delta — reliable transport only
 
-Sends 1 byte when the value is byte-equal to the cached previous frame.
+Tracks the previous frame's value and ships only what changed. Rejected on `unreliable = true`.
 
-| Codec | Notes |
-|:---|:---|
-| `deltaStruct(schema)` | Per-segment dirty bitmap; single-segment fast path. |
-| `deltaArray(c, max?)` | Whole-array byte-equality. |
-| `deltaMap(k, v, max?)` | Whole-map byte-equality. |
+| Codec | Static | Mutation |
+|:---|:---:|:---:|
+| `deltaStruct(schema)` | 1 B | per-field |
+| `deltaArray(c, max?)` | 1 B | per-changed-index |
+| `deltaMap(k, v, max?)` | 1 B | per-changed-key |
+| `deltaInt(min, max)` | 1 B | 1–5 B |
+| `deltaFloat(min, max, precision)` | 1 B | 1–5 B |
+| `deltaVec3(min, max, precision)` | 3 B | 3–15 B |
+| `deltaCFrame(posMin, posMax, precision)` | 1 B | 4–13 B |
 
 ### Meta
 
@@ -351,21 +356,23 @@ Global per-player cap: `Lync.configure({ globalRateLimit = { maxPerSecond = N }
 | Tool | `array<entity>[100]` | `array<bool>[1000]` |
 |:---|:---|:---|
 | roblox | 16 fps · 559,364 Kbps | 21 fps · 353,107 Kbps |
-| **lync** | **60 fps · 3.44 Kbps** | **60 fps · 2.46 Kbps** |
+| **lync** | **59 fps · 3.37 Kbps** | **61 fps · 2.45 Kbps** |
 | blink | 42 fps · 41.81 Kbps | 97 fps · 7.91 Kbps |
 | zap | 39 fps · 41.71 Kbps | 52 fps · 8.10 Kbps |
 | bytenet | 32 fps · 41.64 Kbps | 35 fps · 8.11 Kbps |
 
 ### Network bandwidth — 100 fires/frame, 8 s
 
-| Workload | Kbps |
-|:---|---:|
-| `array<entity>[100]` randomised | 3,608 |
-| `array<entity>[100]` reused | **2.4** |
-| `array<bool>[1000]` randomised | 763 |
-| `array<bool>[1000]` 1 bit flipped | **20.5** |
-| `struct(state)` randomised | 201 |
-| `deltaStruct(state)` 1 field mutated | **29.2** |
+| Workload | Naive Kbps | Optimized | Savings |
+|:---|---:|:---|---:|
+| `array<entity>[100]` random | 3,607 | `deltaArray` 3 of 100 mutated | **154** (–96%) |
+| `array<entity>[100]` reused | 3,607 | XOR baseline (identical frames) | **2.4** (–99.9%) |
+| `array<bool>[1000]` random | 762 | XOR baseline (1 bit flipped) | **20.4** (–97%) |
+| `struct(state)` random | 201 | `deltaStruct` 1 field mutated | **29.0** (–86%) |
+| `map<id, vec3>[200]` 5 keys mutated | 657 | `deltaMap` 5 keys mutated | **393** (–40%) |
+| `array<cframe>[50]` random | 4,585 | — | — |
+| `vec3` walking motion (continuous diff) | — | `deltaVec3` | **19.5** |
+| `CFrame` walking pose (pos + rot) | — | `deltaCFrame` | **41.1** |
 
 ## License
 

bench/Run.server.luau

@@ -23,9 +23,9 @@ end
 
 -- Delta wire size --------------------------------------------------------
 
-Harness.header("Delta Wire Size (deltaStruct[12 fields], bytes)")
+Harness.header("Delta Wire Size (per-codec, bytes)")
 for _, c in Scenarios.deltaCases do
-    Harness.deltaSize(c.label, Scenarios.stateDelta, c.seed, c.value)
+    Harness.deltaSize(c.label, c.codec, c.seed, c.value)
 end
 
 -- CPU round-trip ---------------------------------------------------------

bench/Scenarios.luau

@@ -39,10 +39,13 @@ local stateSchema = {
 
 local entityCodec = Lync.struct(entitySchema)
 local entityArray = Lync.array(entityCodec)
+local entityDeltaArray = Lync.deltaArray(entityCodec)
 local boolArray = Lync.array(Lync.bool)
 local cframeArray = Lync.array(Lync.cframe())
 local stateCodec = Lync.struct(stateSchema)
 local stateDelta = Lync.deltaStruct(stateSchema)
+local positionMap = Lync.map(Lync.int(0, 1023), Lync.vec3)
+local positionDeltaMap = Lync.deltaMap(Lync.int(0, 1023), Lync.vec3)
 
 -- Generators -------------------------------------------------------------
 
@@ -242,6 +245,14 @@ local wireCases = table.freeze({
         }),
         value = { a = true, b = false, c = true, d = false, tier = 7, level = 99 },
     },
+    -- zint and delta scalars are stateful for the delta variants; the
+    -- single-value wire size below is the FIRST-frame size.
+    { label = "zint(0)", codec = Lync.zint(), value = 0 },
+    { label = "zint(95)", codec = Lync.zint(), value = 95 },
+    { label = "zint(-96)", codec = Lync.zint(), value = -96 },
+    { label = "zint(1000)", codec = Lync.zint(), value = 1000 },
+    { label = "zint(-1000)", codec = Lync.zint(), value = -1000 },
+    { label = "zint(i32_max)", codec = Lync.zint(), value = 0x7FFFFFFF },
 })
 
 -- Delta wire-size catalogue ----------------------------------------------
@@ -258,9 +269,67 @@ stateMultiMut.velY = 5
 stateMultiMut.velZ = 6
 
 local deltaCases = table.freeze({
-    { label = "delta unchanged", seed = stateBase, value = stateBase },
-    { label = "delta 1-field-mut", seed = stateBase, value = stateOneMut },
-    { label = "delta 6-fields-mut", seed = stateBase, value = stateMultiMut },
+    { label = "deltaStruct unchanged", codec = stateDelta, seed = stateBase, value = stateBase },
+    {
+        label = "deltaStruct 1-field-mut",
+        codec = stateDelta,
+        seed = stateBase,
+        value = stateOneMut,
+    },
+    {
+        label = "deltaStruct 6-fields-mut",
+        codec = stateDelta,
+        seed = stateBase,
+        value = stateMultiMut,
+    },
+    {
+        label = "deltaInt unchanged",
+        codec = Lync.deltaInt(0, 1000000),
+        seed = 12345,
+        value = 12345,
+    },
+    {
+        label = "deltaInt small-mut(+1)",
+        codec = Lync.deltaInt(0, 1000000),
+        seed = 12345,
+        value = 12346,
+    },
+    {
+        label = "deltaInt large-mut",
+        codec = Lync.deltaInt(0, 1000000),
+        seed = 12345,
+        value = 999999,
+    },
+    {
+        label = "deltaVec3 unchanged",
+        codec = Lync.deltaVec3(-1000, 1000, 0.01),
+        seed = Vector3.new(50, 60, 70),
+        value = Vector3.new(50, 60, 70),
+    },
+    {
+        label = "deltaVec3 small-mut(+0.1 stud)",
+        codec = Lync.deltaVec3(-1000, 1000, 0.01),
+        seed = Vector3.new(50, 60, 70),
+        value = Vector3.new(50.1, 60.1, 70.1),
+    },
+    {
+        label = "deltaCFrame static",
+        codec = Lync.deltaCFrame(-1000, 1000, 0.01),
+        seed = CFrame.new(10, 20, 30),
+        value = CFrame.new(10, 20, 30),
+    },
+    {
+        label = "deltaCFrame pos-only",
+        codec = Lync.deltaCFrame(-1000, 1000, 0.01),
+        seed = CFrame.new(10, 20, 30),
+        value = CFrame.new(10.5, 20, 30),
+    },
+    {
+        label = "deltaCFrame full pose",
+        codec = Lync.deltaCFrame(-1000, 1000, 0.01),
+        seed = CFrame.new(10, 20, 30),
+        value = CFrame.new(11, 21, 31) * CFrame.Angles(1, 0, 0),
+    },
 })
 
 -- Round-trip catalogue (CPU only) ----------------------------------------
@@ -325,10 +394,80 @@ local blinkCases: { NetCase } = table.freeze({
     ),
 })
 
+--[[
+    Pool builders for the new delta workloads. Each returns a frozen list
+    of POOL_SIZE values forming a realistic mutation stream so the bench
+    measures steady-state cache behavior, not first-frame FULL cost.
+]]
+local function poolEntityArrSparseMut(): { { any } }
+    -- Stable array shape; 3 random indices flip per frame to exercise PATCH.
+    local current = entityArr(ENT_COUNT)
+    local p = table.create(POOL_SIZE)
+    p[1] = table.clone(current)
+    for frame = 2, POOL_SIZE do
+        for _ = 1, 3 do
+            local idx = rng:NextInteger(1, ENT_COUNT)
+            current[idx] = entity()
+        end
+        p[frame] = table.clone(current)
+    end
+    return table.freeze(p) :: { { any } }
+end
+
+local function poolPositionMap(): { { [number]: Vector3 } }
+    -- 200-entry map; ~5 keys mutate per frame to exercise DIFF.
+    local current: { [number]: Vector3 } = {}
+    for i = 1, 200 do
+        current[i] = Vector3.new(rng:NextNumber(-100, 100), 0, rng:NextNumber(-100, 100))
+    end
+    local p = table.create(POOL_SIZE)
+    p[1] = table.clone(current)
+    for frame = 2, POOL_SIZE do
+        for _ = 1, 5 do
+            local k = rng:NextInteger(1, 200)
+            current[k] = Vector3.new(rng:NextNumber(-100, 100), 0, rng:NextNumber(-100, 100))
+        end
+        p[frame] = table.clone(current)
+    end
+    return table.freeze(p) :: { { [number]: Vector3 } }
+end
+
+local function poolPositionStream(): { Vector3 }
+    -- Continuous motion: + ~0.5 stud per axis per frame. Hot path for deltaVec3.
+    local current = Vector3.new(0, 0, 0)
+    local p = table.create(POOL_SIZE)
+    for frame = 1, POOL_SIZE do
+        p[frame] = current
+        current = current
+            + Vector3.new(
+                rng:NextNumber(-0.5, 0.5),
+                rng:NextNumber(-0.5, 0.5),
+                rng:NextNumber(-0.5, 0.5)
+            )
+    end
+    return table.freeze(p) :: { Vector3 }
+end
+
+local function poolCFrameStream(): { CFrame }
+    -- Walking-character pose: position drifts, rotation slowly turns.
+    local pos = Vector3.new(0, 0, 0)
+    local yaw = 0
+    local p = table.create(POOL_SIZE)
+    for frame = 1, POOL_SIZE do
+        p[frame] = CFrame.new(pos) * CFrame.Angles(0, yaw, 0)
+        pos = pos + Vector3.new(rng:NextNumber(-0.3, 0.3), 0, rng:NextNumber(-0.3, 0.3))
+        yaw = yaw + rng:NextNumber(-0.05, 0.05)
+    end
+    return table.freeze(p) :: { CFrame }
+end
+
+local positionsCodec = Lync.deltaVec3(-1000, 1000, 0.01)
+local cframeStreamCodec = Lync.deltaCFrame(-1000, 1000, 0.01)
+
 --[[
     Extended workloads at 100 fires/frame. Pairs vary/stable cases on the
     same codec to expose XOR + delta savings: vary = worst case, stable =
-    same array reused so XOR collapses, delta = single field flipping.
+    same array reused so XOR collapses, delta = sparse mutations.
 ]]
 local extendedCases: { NetCase } = table.freeze({
     defCase(
@@ -345,6 +484,7 @@ local extendedCases: { NetCase } = table.freeze({
             return entityArr(ENT_COUNT)
         end)
     ),
+    defCase("entity_deltaArr_100__3mut", entityDeltaArray, poolEntityArrSparseMut()),
     defCase(
         "bool_arr_1000__vary",
         boolArray,
@@ -362,6 +502,10 @@ local extendedCases: { NetCase } = table.freeze({
     ),
     defCase("state_full__vary", stateCodec, poolVarying(stateOne)),
     defCase("state_delta__1mut", stateDelta, poolStateOneMut()),
+    defCase("position_map_200__5mut", positionMap, poolPositionMap()),
+    defCase("position_deltaMap_200__5mut", positionDeltaMap, poolPositionMap()),
+    defCase("vec3_walking_motion", positionsCodec, poolPositionStream()),
+    defCase("cframe_walking_pose", cframeStreamCodec, poolCFrameStream()),
 })
 
 -- Handshake --------------------------------------------------------------

src/Types.luau

@@ -12,17 +12,18 @@ export type ChannelState = {
     itemCount: number,
     singleMode: boolean,
     singlePos: number,
-    deltas: { [number]: DeltaCacheEntry },
+    --[[
+        Per-codec write-side delta state, keyed by deltaId. Shape is opaque
+        and codec-internal: deltaStruct stores `{raw, len, segOff, segLen}`,
+        deltaArray stores `{perIdx, length}`, deltaMap stores `{perKey}`,
+        delta scalars store quantized previous values.
+    ]]
+    deltas: { [number]: any },
     prevDump: buffer?,
     prevDumpLen: number,
     currentPacket: string?,
 }
 
-export type DeltaCacheEntry = {
-    raw: buffer,
-    len: number,
-}
-
 export type Codec<T> = {
     write: (ch: ChannelState, value: T) -> (),
     read: (src: buffer, pos: number, refs: { Instance }?) -> (T, number),
@@ -39,6 +40,11 @@ export type InternalCodec<T> = {
     _directWrite: ((b: buffer, offset: number, value: T) -> ())?,
     _directRead: ((b: buffer, offset: number) -> T)?,
     _isDelta: boolean?,
+    --[[
+        True if any nested codec is delta. Lets the broadcast hot path skip
+        encode-once when delta state would diverge per-receiver.
+    ]]
+    _hasDelta: boolean?,
     _isBool: boolean?,
     _hasUnknown: boolean?,
     _min: number?,