Lync

Buffer networking for Roblox.

Releases · Install · Example · Codecs · Wire Protocol · Benchmarks

Lync serializes structured data into flat buffers, batches all sends into a single RemoteEvent:FireClient per player per frame, and applies XOR framing so Roblox's internal deflate compressor can eliminate redundancy across frames. On the server, every incoming payload is schema-validated and rate-limited before any listener fires.

All codecs are defined at runtime. No code generation, no build step, no external CLI. Packets, queries, groups, and middleware are configured in shared modules and resolved at Lync.start().

Install

Wally

[dependencies]
Lync = "axp3cter/lync@2.1.0"

npm (roblox-ts)

npm install @axpecter/lync

import Lync from "@axpecter/lync";

Or grab the .rbxm from Releases and drop it into ReplicatedStorage.

[!IMPORTANT] All packets, queries, and groups must be defined before calling Lync.start(). The registry assigns sequential IDs at define time. Defining packets after start() will cause ID mismatches between server and client.

Example

Shared (ReplicatedStorage.Net)

local Lync = require(game.ReplicatedStorage.Lync)

local Net = {}

Net.State = Lync.packet("State", Lync.deltaStruct({
    position = Lync.vec3,
    health   = Lync.float(0, 100, 0.5),
    shield   = Lync.float(0, 100, 0.5),
    status   = Lync.enum("idle", "moving", "attacking", "dead"),
    alive    = Lync.bool,
}))

Net.Hit = Lync.packet("Hit", Lync.struct({
    targetId = Lync.int(0, 65535),
    damage   = Lync.float(0, 200, 0.1),
    headshot = Lync.bool,
}), {
    rateLimit = { maxPerSecond = 30, burst = 5 },
    validate = function(data, player)
        if data.damage > 200 then return false, "damage" end
        return true
    end,
})

Net.Chat = Lync.packet("Chat", Lync.struct({
    msg     = Lync.string(200),
    channel = Lync.int(0, 255),
}))

Net.Ping = Lync.query("Ping", Lync.nothing, Lync.f64, { timeout = 3 })

return table.freeze(Net)

Server

local Lync    = require(game.ReplicatedStorage.Lync)
local Net     = require(game.ReplicatedStorage.Net)
local Players = game:GetService("Players")

local alive = Lync.group("alive")

Lync.onDrop(function(player, reason, name)
    warn(player.Name, "dropped", name, reason)
end)

Lync.start()

Players.PlayerAdded:Connect(function(player) alive:add(player) end)

game:GetService("RunService").Heartbeat:Connect(function()
    Net.State:send({
        position = Vector3.new(0, 5, 0),
        health   = 100,
        shield   = 50,
        status   = "idle",
        alive    = true,
    }, alive)
end)

Net.Hit:on(function(data, player)
    local target = Players:GetPlayerByUserId(data.targetId)
    if not target then return end
    alive:remove(target)
    Net.Chat:send({ msg = player.Name .. " eliminated " .. target.Name, channel = 0 }, Lync.all)
end)

Net.Ping:handle(function(_, player) return os.clock() end)

Client

local Lync = require(game.ReplicatedStorage.Lync)
local Net  = require(game.ReplicatedStorage.Net)

Lync.start()

local scope = Lync.scope()

scope:on(Net.State, function(state)
    local character = game.Players.LocalPlayer.Character
    if not character then return end
    character:PivotTo(CFrame.new(state.position))
end)

scope:on(Net.Chat, function(data) print("[chat]", data.msg) end)

Net.Hit:send({ targetId = 123, damage = 45.5, headshot = true })

local serverTime = Net.Ping:request(nil)
if serverTime then print("server clock:", serverTime) end

Lifecycle

Packets

Lync.packet(name, codec, options?) returns a Packet handle. The second argument is any codec. Options go in the optional third argument.

Packet Options

Packet Methods

Sending (server):

packet:send(data, player)              -- single player
packet:send(data, Lync.all)            -- all connected players
packet:send(data, Lync.except(p1, p2)) -- all except specified
packet:send(data, { p1, p2, p3 })      -- array of players
packet:send(data, group)               -- group members

Sending (client):

packet:send(data)  -- to server

Receiving (both):

Queries

Lync.query(name, requestCodec, responseCodec, options?) returns a Query handle. Built on RemoteEvents with varint correlation IDs. Returns nil on timeout or handler error.

Query Options

Query Methods

Each query consumes two packet IDs internally (one for requests, one for responses).

Groups

Lync.group(name) returns a Group. Members are removed automatically on PlayerRemoving. Names must be unique (duplicate errors). Destroyed groups free their name for reuse.

Groups implement __iter, so for player in group do works directly.

Scope

Lync.scope() batches connections for lifecycle-aligned cleanup.

local scope = Lync.scope()
scope:on(packetA, fnA)
scope:on(packetB, fnB)
scope:add(someRBXScriptConnection)
scope:destroy()

Connection

Returned by packet:on(), packet:once(), query:handle(), scope:on(), and middleware functions.

Middleware

Global intercept chains on all packets. Handlers run in registration order. Return a transformed value to pass it downstream. Return nil to pass through unchanged. Return Lync.DROP from onSend to silently drop the packet.

All three functions return a Connection.

Targets

Server-side second argument to packet:send() and query:request().

Codecs

Numbers

Lync.int(min, max) selects the smallest wire type that fits the range:

Signed integers use unsigned buffer writes (writeu8/writeu16/writeu32) with two's complement conversion because writei8/writei16/writei32 are not FASTCALL-optimized in Luau.

Lync.float(min, max, precision) quantizes a float range to an integer range. Wire type is selected by ceil((max - min) / precision): u8 if ≤ 255, u16 if ≤ 65535, u32 otherwise. Values outside [min, max] are clamped.

Strings and Buffers

Roblox Types

All fixed-size types expose _directWrite and _directRead for struct fast-path optimization, except Lync.inst (requires the channel's ref array).

Quantized Variants

These codecs are callable. The bare name gives the lossless version; calling with arguments gives the quantized version.

Composites

Delta Codecs

Reliable transport only. Errors at define time if combined with unreliable = true.

Delta codecs serialize into a scratch buffer and compare byte-for-byte against a cached baseline. Identical bytes produce a 1-byte UNCHANGED flag. Any difference triggers a full re-send prefixed with a FULL flag byte.

Meta Codecs

Wire Protocol

Dense Prefix-Varint

Variable-length unsigned integer encoding. 1-byte range covers 0–191 (LEB128 only covers 0–127).

MSB Batch Framing

All sends within one Heartbeat are batched into a single buffer per player per reliability channel.

Single-item: [1IIIIIII] [payload] — MSB set, 7-bit packet ID, no count byte. 1-byte header.

Multi-item: [0IIIIIII] [u16 count] [payload₁] ... — MSB clear, u16 item count follows. Used when ≥2 sends to the same packet occur in one frame.

The single-item path saves 2 bytes per packet per frame vs always writing a count. Maximum 127 packet IDs (7 bits).

XOR Framing

Reliable channels XOR the current frame against the previous before sending. The receiver XOR's against its previous decoded frame to recover the original. Produces long zero runs that compress well under Roblox's internal deflate.

XOR operates in u32-aligned chunks with u8 remainder. Mismatched frame sizes are handled: excess bytes in a longer frame are copied directly.

Unreliable channels skip XOR (no guaranteed frame ordering).

Security

Schema Validation

Every incoming packet on the server passes through Gate before listeners fire:

• _typeCheck: Rejects wrong typeof.
• _isInteger + _min/_max: Rejects non-integers, NaN, inf, out-of-range.
• _schema (struct codecs): Recursive per-field validation.
• Fallback: NaN/inf scan up to validationDepth levels for codecs without metadata.

Rejected packets fire onDrop and are silently discarded. Other packets in the same frame from the same player are unaffected.

Rate Limiting

Two modes (mutually exclusive):

Token bucket: { maxPerSecond = N, burst = M }. Tokens refill at N/sec. Burst defaults to 1. Each fire costs one token.

Cooldown: { cooldown = seconds }. Rejects fires within cooldown seconds of the last accepted fire.

Global rate limit: Lync.configure({ globalRateLimit = { maxPerSecond = N } }). Checked before per-packet limits.

Bandwidth Throttle

Lync.configure({ bandwidthLimit = { softLimit = bytes, maxStrikes = N } }). Per-player. Oversized frames increment strikes. Small frames decrement (decay). Exceeding maxStrikes drops the entire frame.

Stats

Disabled by default. Zero overhead when off. Enable via Lync.configure({ stats = true }).

Debug

Configuration

Lync.configure(options) — call before Lync.start().

Limits

Benchmarks

Run rojo serve bench.project.json, open in Studio with one local server + one client.

See bench/Run.server.luau for full configuration and methodology.

Wire Sizes

Exact byte count per codec write. Raw payload only — no batch framing overhead included.

Codec Throughput

Isolated CPU cost. No networking. Encode + decode measured independently. 100k iterations with warmup.

Delta Savings

Byte cost across three consecutive writes: initial (full), identical repeat (unchanged), and single-field mutation (changed).

Batch Framing

MSB single-item batches use a 1-byte header. Multi-item batches add a u16 count after the header.

Network Throughput

Live sends to one player. Measured over 8 seconds. FPS and Kbps at median and tail.

Cross-Library Comparison

The tables below use the same data shapes and methodology as Blink's published benchmarks: 1,000 fires/frame, same data every frame, 10 seconds, Kbps scaled by 60/FPS.

Numbers for blink, zap, bytenet, and roblox are copied directly from Blink v0.17.1 results (2025-04-30).

[!NOTE] Architectural differences that affect these numbers:

• Lync batches all sends into one buffer per Heartbeat frame. Other tools fire one RemoteEvent per send(), paying ~40 bytes of Roblox overhead per call.
• Lync includes server-side schema validation and rate limiting. Other tools do not.
• Lync bitpacks bool arrays (1,000 bools ≈ 127 bytes vs ~1,002 bytes for 1-byte-per-bool).
• Lync uses runtime codecs. Blink and Zap use code generation with zero runtime schema.
• Delta compression is not exercised here (same data every frame). See Delta Savings for the real-world impact.
• FPS is hardware-dependent. Kbps is FPS-scaled, making it comparable across machines.

Tool versions: blink v0.17.1 · zap v0.6.20 · bytenet v0.4.3 · lync v2.1.0

Data shapes: Entities = 100× struct { id u8, x u8, y u8, z u8, orientation u8, animation u8 }. Booleans = 1000× bool. Source.

Entities — FPS

Entities — Kbps

Booleans — FPS

Booleans — Kbps

Wire Size Comparison

License

MIT