Lync

Buffer networking for Roblox. Delta compression, XOR framing, built-in security.

Releases · Example · Benchmarks · Limits

Install

Wally (Luau)

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

npm (roblox-ts)

npm install @axpecter/lync

import Lync from "@axpecter/lync";

Or grab the .rbxm from releases and drop it in ReplicatedStorage.

[!IMPORTANT] Define everything before calling Lync.start(). Packets, queries, namespaces, all of it.

Example

Shared

local Lync = require(game.ReplicatedStorage.Lync)

local Net = {}

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

Net.Hit = Lync.definePacket("Hit", {
    value = Lync.struct({
        targetId = Lync.u16,
        damage   = Lync.quantizedFloat(0, 200, 0.1),
        headshot = Lync.bool,
    }),
    rateLimit = { maxPerSecond = 30, burstAllowance = 5 },
    validate = function(data, player)
        if data.damage > 200 then return false, "damage" end
        return true
    end,
})

Net.Chat = Lync.definePacket("Chat", {
    value = Lync.struct({ msg = Lync.boundedString(200), channel = Lync.u8 }),
})

Net.Ping = Lync.defineQuery("Ping", {
    request  = Lync.nothing,
    response = 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.createGroup("alive")

Lync.onSend(function(data, name)
    print("[out]", name)
    return data
end)

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:listen(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)
    Net.State:send({
        position = Vector3.zero,
        health   = 0,
        shield   = 0,
        status   = "dead",
        alive    = false,
    }, Lync.except(target))
end)

Net.Ping:listen(function()
    return os.clock()
end)

Client

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

Lync.start()

local scope = Lync.scope()

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

scope:listen(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.definePacket(name, config) returns a Packet.

Server, single send with targets:

packet:send(data, player)              -- one player
packet:send(data, Lync.all)            -- everyone
packet:send(data, Lync.except(player)) -- everyone except one
packet:send(data, Lync.except(p1, p2)) -- everyone except multiple
packet:send(data, { p1, p2 })          -- list of players
packet:send(data, group)               -- group object

Client:

packet:send(data)  -- send to server

Shared (both contexts):

Queries

Lync.defineQuery(name, config) returns a Query. Basically RemoteFunctions but built on RemoteEvents. Returns nil if the other side times out or errors.

Namespaces

Lync.defineNamespace(name, config) returns a Namespace. Takes a packets table and/or a queries table. All names get auto-prefixed with "YourNamespace." so nothing collides.

The config takes PacketConfig and QueryConfig objects (same shape you'd pass to definePacket / defineQuery). The namespace creates and owns the packets/queries internally.

local Combat = Lync.defineNamespace("Combat", {
    packets = {
        Hit = {
            value = Lync.struct({ targetId = Lync.u16, damage = Lync.f32, headshot = Lync.bool }),
            rateLimit = { maxPerSecond = 30, burstAllowance = 5 },
            validate = function(data, player)
                if data.damage > 200 then return false, "damage" end
                return true
            end,
        },
        Death = { value = Lync.u16 },
    },
    queries = {
        Stats = {
            request  = Lync.nothing,
            response = Lync.struct({ kills = Lync.u16, deaths = Lync.u16 }),
            timeout  = 3,
        },
    },
})

-- Access by short name directly on the namespace
Combat.Hit:send(data, player)
Combat.Death:listen(function(targetId, sender) end)
Combat.Stats:listen(function(request, player) return { kills = 10, deaths = 2 } end)

-- Or via the typed sub-tables
Combat.packets.Hit:send(data, player)
Combat.queries.Stats:request(nil)

Access packets and queries by their short name on the returned object: ns.PacketName, ns.QueryName. Or use the typed sub-tables: ns.packets.PacketName, ns.queries.QueryName.

Connection

Returned by packet:listen(), packet:once(), query:listen(), and ns:listenAll().

Scope

Batches connections for lifecycle-aligned cleanup.

local scope = Lync.scope()

scope:listen(packetA, fnA)
scope:listen(packetB, fnB)
scope:listenAll(namespace, fnC)

scope:destroy()  -- disconnects everything

Groups

Named player sets. Members get removed automatically on PlayerRemoving. Lync.createGroup(name) returns a Group object.

local vips = Lync.createGroup("vips")

vips:add(player)
vips:remove(player)
vips:has(player)

packet:send(data, vips)

Middleware

Global intercept on all packets. Handlers run in the order you registered them. Return Lync.DROP from a handler to drop the packet. Return the data to pass it through.

Lync.onSend(function(data, name, player)
    if shouldDrop(data) then
        return Lync.DROP
    end
    data.timestamp = os.clock()
    return data
end)

Packets that fail validation are dropped individually. Other packets in the same frame from the same player are unaffected.

Target Descriptors

Used as the second argument to packet:send() on the server.

Types

Primitives

Datatypes

Composites

Delta

Reliable only. Lync will error if you try to use these with unreliable = true.

Meta

Benchmarks

Lync Tests

1,000 packets/frame, 10 seconds, one player.

Cross-Library Comparison

Same data shapes and methodology as Blink's benchmark suite. 1,000 fires/frame, 10 seconds, same data every frame. Kbps scaled by 60/FPS.

Entities (100x struct of 6x u8, fired 1000 times/frame)

Booleans (1000x bool, fired 1000 times/frame)

[!NOTE] Lync benchmarks run on Ryzen 7 7800X3D, 32GB DDR5-4800. Other tool numbers are from Blink's published benchmarks (v0.17.1, Ryzen 9 7900X, 34GB DDR5-4800). Different CPUs so FPS numbers arent directly comparable but bandwidth numbers are since Kbps is scaled by 60/FPS. Lync hits the 60 FPS frame cap in both tests.

Limits & Configuration

Call these before Lync.start().

License

MIT