@axpecter/lync 1.3.1 → 1.4.0

package/README.md

@@ -2,6 +2,7 @@
 <p align="center">Buffer networking for Roblox. Delta compression, XOR framing, built-in security.</p>
 <p align="center">
   <a href="https://github.com/Axp3cter/Lync/releases/latest">Releases</a> ·
+  <a href="#example">Example</a> ·
   <a href="#benchmarks">Benchmarks</a> ·
   <a href="#limits--configuration">Limits</a>
 </p>
@@ -12,17 +13,17 @@
 
 ```toml
 [dependencies]
-Lync = "axp3cter/lync@1.3.1"
+Lync = "axp3cter/lync@1.4.0"
 ```
 
 **npm (roblox-ts)**
 
 ```bash
-npm install @rbxts/lync
+npm install @axpecter/lync
 ```
 
 ```typescript
-import Lync from "@rbxts/lync";
+import Lync from "@axpecter/lync";
 ```
 
 Or grab the `.rbxm` from [releases](https://github.com/Axp3cter/Lync/releases/latest) and drop it in `ReplicatedStorage`.
@@ -30,13 +31,139 @@ Or grab the `.rbxm` from [releases](https://github.com/Axp3cter/Lync/releases/la
 > [!IMPORTANT]
 > Define everything before calling `Lync.start()`. Packets, queries, namespaces, all of it.
 
+## Example
+
+**Shared** (ReplicatedStorage, required by both)
+
+```luau
+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**
+
+```luau
+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**
+
+```luau
+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
 
 | | What it does |
 |:---------|:------------|
 | `Lync.start()` | Sets up transport. Server creates remotes, client connects. Call once after all definitions. |
-| `Lync.version` | `"1.3.1"` |
-| `Lync.VERSION` | `"1.3.1"` |
+| `Lync.VERSION` | `"1.4.0"` |
 
 ## Packets
 
@@ -50,23 +177,24 @@ Or grab the `.rbxm` from [releases](https://github.com/Axp3cter/Lync/releases/la
 | `validate` | `(data, player) → (bool, string?)` | No | Server-side. Return `false, "reason"` to drop. Runs after NaN scan. |
 | `maxPayloadBytes` | number | No | Server-side. Max bytes a single batch of this packet can consume. Fires `onDrop` with reason `"size"` if exceeded. |
 
-**Server methods:**
+**Server, single `send` with targets:**
 
-| Method | What it does |
-|:-------|:------------|
-| `packet:sendTo(data, player)` | Send to one player. |
-| `packet:sendToAll(data)` | Send to everyone. |
-| `packet:sendToAllExcept(data, except)` | Send to everyone except one. |
-| `packet:sendToList(data, players)` | Send to a list. |
-| `packet:sendToGroup(data, groupName)` | Send to a named group. |
+```luau
+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 methods:**
+**Client:**
 
-| Method | What it does |
-|:-------|:------------|
-| `packet:send(data)` | Send to server. |
+```luau
+packet:send(data)  -- send to server
+```
 
-**Shared methods:**
+**Shared (both contexts):**
 
 | Method | What it does |
 |:-------|:------------|
@@ -90,17 +218,17 @@ Or grab the `.rbxm` from [releases](https://github.com/Axp3cter/Lync/releases/la
 | Method | Where | What it does |
 |:-------|:------|:-------------|
 | `query:listen(fn)` | Both | Register a handler. Server gets `fn(request, player) → response`. Client gets `fn(request) → response`. |
-| `query:invoke(request)` | Client | Send request to server, yield until response comes back or timeout. |
-| `query:invoke(request, player)` | Server | Send request to a specific client, yield until response or timeout. |
-| `query:invokeAll(request)` | Server | Send request to all players, yield until all respond or timeout. Returns `{ [Player]: response? }`. |
-| `query:invokeList(request, players)` | Server | Send request to a list of players, yield until all respond or timeout. Returns `{ [Player]: response? }`. |
-| `query:invokeGroup(request, groupName)` | Server | Send request to all players in a named group. Returns `{ [Player]: response? }`. |
+| `query:request(data)` | Client | Send request to server, yield until response or timeout. |
+| `query:requestFrom(player, data)` | Server | Send request to a specific client, yield until response or timeout. |
+| `query:requestAll(data)` | Server | Send request to all players. Returns `{ [Player]: response? }`. |
+| `query:requestList(players, data)` | Server | Send request to a list of players. Returns `{ [Player]: response? }`. |
+| `query:requestGroup(group, data)` | Server | Send request to all players in a group. Returns `{ [Player]: response? }`. |
 
 ## 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.
 
-Access packets and queries by their short name on the returned object: `ns.PacketName`, `ns.QueryName`.
+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`.
 
 | Method | What it does |
 |:-------|:------------|
@@ -111,6 +239,8 @@ Access packets and queries by their short name on the returned object: `ns.Packe
 | `ns:destroy()` | Kills listeners and removes scoped middleware. Full cleanup. |
 | `ns:packetNames()` | Sorted list of packet short names. |
 | `ns:queryNames()` | Sorted list of query short names. |
+| `ns.packets` | Frozen table mapping short name → Packet object. |
+| `ns.queries` | Frozen table mapping short name → Query object. |
 
 ## Connection
 
@@ -121,6 +251,87 @@ Returned by `packet:listen()`, `packet:once()`, `query:listen()`, and `ns:listen
 | `connection.connected` | `true` if still connected, `false` after disconnect. |
 | `connection:disconnect()` | Stops the listener. |
 
+## Scope
+
+Batches connections for lifecycle-aligned cleanup.
+
+```luau
+local scope = Lync.scope()
+
+scope:listen(packetA, fnA)
+scope:listen(packetB, fnB)
+scope:listenAll(namespace, fnC)
+
+scope:destroy()  -- disconnects everything
+```
+
+| Method | What it does |
+|:-------|:------------|
+| `scope:listen(source, fn)` | Calls source:listen(fn) and tracks the connection. |
+| `scope:once(source, fn)` | Calls source:once(fn) and tracks the connection. |
+| `scope:listenAll(namespace, fn)` | Calls namespace:listenAll(fn) and tracks the connection. |
+| `scope:add(connection)` | Track a raw Connection or RBXScriptConnection. |
+| `scope:destroy()` | Disconnects all tracked connections. Safe to call multiple times. |
+
+## Groups
+
+Named player sets. Members get removed automatically on `PlayerRemoving`. `Lync.createGroup(name)` returns a Group object.
+
+```luau
+local vips = Lync.createGroup("vips")
+
+vips:add(player)
+vips:remove(player)
+vips:has(player)
+
+packet:send(data, vips)
+```
+
+| Method | Returns | What it does |
+|:-------|:--------|:-------------|
+| `group:add(player)` | `boolean` | `true` if added, `false` if already in. |
+| `group:remove(player)` | `boolean` | `true` if removed, `false` if wasnt in there. |
+| `group:has(player)` | `boolean` | |
+| `group:count()` | `number` | |
+| `group:getSet()` | `{ [Player]: true }` | |
+| `group:forEach(fn)` | | Calls `fn(player)` for each member. |
+| `group:destroy()` | | Removes the group and all memberships. |
+
+## 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.
+
+```luau
+Lync.onSend(function(data, name, player)
+    if shouldDrop(data) then
+        return Lync.DROP
+    end
+    data.timestamp = os.clock()
+    return data
+end)
+```
+
+| Function | What it does |
+|:---------|:------------|
+| `Lync.onSend(fn(data, name, player) → data \| Lync.DROP)` | Runs before a packet goes out. Returns a remover function. |
+| `Lync.onReceive(fn(data, name, player) → data \| Lync.DROP)` | Runs when a packet comes in. Returns a remover function. |
+| `Lync.onDrop(fn(player, reason, name, data))` | Fires when a packet gets rejected. Returns a remover function. Supports multiple handlers. Reason is `"nan"`, `"rate"`, `"validate"`, `"size"`, or whatever string your validate function returned. |
+| `Lync.DROP` | Frozen sentinel. Return from middleware to drop the packet. |
+
+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.
+
+| Target | What it does |
+|:-------|:------------|
+| `player` | Send to one player. |
+| `Lync.all` | Send to all connected players. |
+| `Lync.except(player, ...)` | Send to everyone except the specified players. |
+| `{ p1, p2, ... }` | Send to a list of players. |
+| `group` | Send to all members of a Group object. |
+
 ## Types
 
 ### Primitives
@@ -138,7 +349,7 @@ Returned by `packet:listen()`, `packet:once()`, `query:listen()`, and `ns:listen
 | `Lync.f64` | 8 | IEEE 754 double |
 | `Lync.bool` | 1 | true/false. Gets packed into bitfields when inside structs. |
 
-### Complex
+### Datatypes
 
 | Type | Bytes | What it is |
 |:-----|------:|:-----------|
@@ -160,6 +371,7 @@ Returned by `packet:listen()`, `packet:once()`, `query:listen()`, and `ns:listen
 | `Lync.ray` | 24 | Origin Vec3 + Direction Vec3 as 6x f32. |
 | `Lync.numberSequence` | varint + N×12 | Varint count then (time f32 + value f32 + envelope f32) per keypoint. |
 | `Lync.colorSequence` | varint + N×7 | Varint count then (time f32 + R u8 + G u8 + B u8) per keypoint. |
+| `Lync.boundedString(maxLength)` | varint + N | Same wire format as `Lync.string` but rejects on read if length exceeds `maxLength`. |
 
 ### Composites
 
@@ -170,7 +382,7 @@ Returned by `packet:listen()`, `packet:once()`, `query:listen()`, and `ns:listen
 | `Lync.map(keyCodec, valueCodec, maxCount?)` | Key-value pairs with varint count. Optional `maxCount` rejects on read if exceeded. |
 | `Lync.optional(codec)` | 1 byte flag, value only if present. |
 | `Lync.tuple(codec, codec, ...)` | Ordered positional values, no keys. |
-| `Lync.boundedString(maxLength)` | Same wire format as `Lync.string` but rejects on read if length exceeds `maxLength`. |
+| `Lync.tagged(tagField, { name = codec })` | Discriminated union with a u8 variant tag. Puts `tagField` into the decoded table so you know which variant it is. |
 
 ### Delta
 
@@ -182,7 +394,7 @@ Reliable only. Lync will error if you try to use these with `unreliable = true`.
 | `Lync.deltaArray(codec, maxCount?)` | Same idea but for arrays. Dirty elements get sent with varint indices. Optional `maxCount` rejects on read if exceeded. |
 | `Lync.deltaMap(keyCodec, valueCodec, maxCount?)` | Delta compression for key-value maps. Sends only upserted and removed entries after the first frame. Optional `maxCount` rejects on read if exceeded. |
 
-### Specialized
+### Meta
 
 | Constructor | What it does |
 |:------------|:------------|
@@ -190,41 +402,11 @@ Reliable only. Lync will error if you try to use these with `unreliable = true`.
 | `Lync.quantizedFloat(min, max, precision)` | Fixed-point compression. Picks u8/u16/u32 based on your range and precision. |
 | `Lync.quantizedVec3(min, max, precision)` | Same thing but for all 3 components. |
 | `Lync.bitfield({ key = spec })` | Sub-byte packing, 1 to 32 bits total. Spec is `{ type = "bool" }` or `{ type = "uint", width = N }` or `{ type = "int", width = N }`. |
-| `Lync.tagged(tagField, { name = codec })` | Discriminated union with a u8 variant tag. Puts `tagField` into the decoded table so you know which variant it is. |
 | `Lync.custom(size, write, read)` | User-defined fixed-size codec. `write` is `(b, offset, value) → ()`, `read` is `(b, offset) → value`. Plugs into struct/array/delta specialization automatically. |
 | `Lync.nothing` | Zero bytes. Reads nil. Good for fire-and-forget signals. |
 | `Lync.unknown` | Skips serialization entirely, goes through Roblox's sidecar. Requires refs array on read (same as `Lync.inst`). Use when you dont have a codec for the value. |
 | `Lync.auto` | Self-describing. Writes a u8 type tag then the value. Handles nil, bool, all number types, string, vec2, vec3, color3, cframe, buffer, udim, udim2, numberRange, rect, vec2int16, vec3int16, region3, region3int16, ray, numberSequence, colorSequence. |
 
-## Groups
-
-Named player sets. Members get removed automatically on `PlayerRemoving`.
-
-| Function | Returns | What it does |
-|:---------|:--------|:-------------|
-| `Lync.createGroup(name)` | | Makes a new group. Errors if it already exists. |
-| `Lync.destroyGroup(name)` | | Removes the group and all memberships. |
-| `Lync.addToGroup(name, player)` | `boolean` | `true` if added, `false` if already in. |
-| `Lync.removeFromGroup(name, player)` | `boolean` | `true` if removed, `false` if wasnt in there. |
-| `Lync.hasInGroup(name, player)` | `boolean` | |
-| `Lync.groupCount(name)` | `number` | |
-| `Lync.getGroupSet(name)` | `{ [Player]: true }` | |
-| `Lync.forEachInGroup(name, fn)` | | Calls `fn(player)` for each member. |
-
-Send to a group with `packet:sendToGroup(data, groupName)`.
-
-## Middleware
-
-Global intercept on all packets. Handlers run in the order you registered them. Return `nil` from a handler to drop the packet.
-
-| Function | What it does |
-|:---------|:------------|
-| `Lync.onSend(fn(data, name, player) → data?)` | Runs before a packet goes out. Returns a remover function. |
-| `Lync.onReceive(fn(data, name, player) → data?)` | Runs when a packet comes in. Returns a remover function. |
-| `Lync.onDrop(fn(player, reason, name, data))` | Fires when a packet gets rejected. Returns a remover function. Supports multiple handlers. Reason is `"nan"`, `"rate"`, `"validate"`, `"size"`, or whatever string your validate function returned. |
-
-Packets that fail validation are dropped individually. Other packets in the same frame from the same player are unaffected.
-
 ## Benchmarks
 
 ### Lync Tests

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@axpecter/lync",
-    "version": "1.3.1",
+    "version": "1.4.0",
     "description": "Buffer networking for Roblox. Delta compression, XOR framing, built-in security.",
     "main": "src/init.luau",
     "types": "src/index.d.ts",

package/src/api/Group.luau

@@ -31,43 +31,18 @@ end
 
 Players.PlayerRemoving:Connect (onPlayerRemoving)
 
-local function getSetOrError (name: string): { [Player]: true }
-    local set = _groups[name]
-    if not set then
-        error (`[Lync] Group does not exist: \"{name}\"`)
-    end
-    return set
-end
-
--- Public -----------------------------------------------------------------
-
-local Group = {}
+-- GroupImpl ---------------------------------------------------------------
 
-function Group.create (name: string): ()
-    if _groups[name] then
-        error (`[Lync] Group already exists: \"{name}\"`)
-    end
-    _groups[name] = {}
-    _counts[name] = 0
-end
+local GroupImpl = {}
+GroupImpl.__index = GroupImpl
 
-function Group.destroy (name: string): ()
-    local set = getSetOrError (name)
-
-    for player in set do
-        local memberships = _playerGroups[player]
-        if memberships then
-            memberships[name] = nil
-        end
+function GroupImpl.add (self: any, player: Player): boolean
+    local name = self._name
+    local set = _groups[name]
+    if not set then
+        error (`[Lync] Group has been destroyed: "{name}"`)
     end
 
-    _groups[name] = nil
-    _counts[name] = nil
-end
-
-function Group.add (name: string, player: Player): boolean
-    local set = getSetOrError (name)
-
     if set[player] then
         return false
     end
@@ -85,8 +60,12 @@ function Group.add (name: string, player: Player): boolean
     return true
 end
 
-function Group.remove (name: string, player: Player): boolean
-    local set = getSetOrError (name)
+function GroupImpl.remove (self: any, player: Player): boolean
+    local name = self._name
+    local set = _groups[name]
+    if not set then
+        error (`[Lync] Group has been destroyed: "{name}"`)
+    end
 
     if not set[player] then
         return false
@@ -103,24 +82,78 @@ function Group.remove (name: string, player: Player): boolean
     return true
 end
 
-function Group.has (name: string, player: Player): boolean
-    local set = getSetOrError (name)
+function GroupImpl.has (self: any, player: Player): boolean
+    local name = self._name
+    local set = _groups[name]
+    if not set then
+        error (`[Lync] Group has been destroyed: "{name}"`)
+    end
     return set[player] == true
 end
 
-function Group.count (name: string): number
-    getSetOrError (name)
+function GroupImpl.count (self: any): number
+    local name = self._name
+    if not _groups[name] then
+        error (`[Lync] Group has been destroyed: "{name}"`)
+    end
     return _counts[name]
 end
 
-function Group.getSet (name: string): { [Player]: true }
-    return getSetOrError (name)
+function GroupImpl.forEach (self: any, fn: (player: Player) -> ()): ()
+    local name = self._name
+    local set = _groups[name]
+    if not set then
+        error (`[Lync] Group has been destroyed: "{name}"`)
+    end
+    for player in set do
+        fn (player)
+    end
 end
 
-function Group.forEach (name: string, fn: (player: Player) -> ()): ()
-    for player in getSetOrError (name) do
-        fn (player)
+function GroupImpl.getSet (self: any): { [Player]: true }
+    local name = self._name
+    local set = _groups[name]
+    if not set then
+        error (`[Lync] Group has been destroyed: "{name}"`)
+    end
+    return set
+end
+
+function GroupImpl.destroy (self: any): ()
+    local name = self._name
+    local set = _groups[name]
+    if not set then
+        error (`[Lync] Group has been destroyed: "{name}"`)
     end
+
+    for player in set do
+        local memberships = _playerGroups[player]
+        if memberships then
+            memberships[name] = nil
+        end
+    end
+
+    _groups[name] = nil
+    _counts[name] = nil
+end
+
+table.freeze (GroupImpl)
+
+-- Public -----------------------------------------------------------------
+
+local Group = {}
+
+function Group.create (name: string): any
+    if _groups[name] then
+        error (`[Lync] Group already exists: "{name}"`)
+    end
+    _groups[name] = {}
+    _counts[name] = 0
+
+    return setmetatable ({
+        _tag = "group",
+        _name = name,
+    }, GroupImpl)
 end
 
 return table.freeze (Group)

package/src/api/Namespace.luau

@@ -194,6 +194,8 @@ function Namespace.define (name: string, config: NamespaceConfig): any
 
     local packets = {} :: { [string]: any }
     local queries = {} :: { [string]: any }
+    local packetsByShort = {} :: { [string]: any }
+    local queriesByShort = {} :: { [string]: any }
     local fields = {} :: { [string]: any }
 
     fields._name = name
@@ -207,6 +209,7 @@ function Namespace.define (name: string, config: NamespaceConfig): any
             local fullName = prefixName (name, shortName)
             local packet = Packet.define (fullName, packetConfig)
             packets[fullName] = packet
+            packetsByShort[shortName] = packet
             fields[shortName] = packet
         end
     end
@@ -216,10 +219,14 @@ function Namespace.define (name: string, config: NamespaceConfig): any
             local fullName = prefixName (name, shortName)
             local query = Query.define (fullName, queryConfig)
             queries[fullName] = query
+            queriesByShort[shortName] = query
             fields[shortName] = query
         end
     end
 
+    fields.packets = table.freeze (packetsByShort)
+    fields.queries = table.freeze (queriesByShort)
+
     return setmetatable (fields, NamespaceImpl)
 end
 

package/src/api/Packet.luau

@@ -21,7 +21,7 @@ local serverWriteTo = Server.writeTo
 local serverWriteToAll = Server.writeToAll
 local serverWriteToList = Server.writeToList
 local serverWriteToAllExcept = Server.writeToAllExcept
-local serverWriteToGroup = Server.writeToGroup
+local serverWriteToSet = Server.writeToSet
 local clientWrite = Client.write
 
 -- Private ----------------------------------------------------------------
@@ -45,7 +45,7 @@ function SharedImpl.disconnectAll (self: any): ()
     self._signal:disconnectAll ()
 end
 
--- Server-only metatable . Has sendTo/sendToAll, no send().
+-- Server-only metatable. Single send() dispatches on target type.
 local ServerImpl = setmetatable ({}, { __index = SharedImpl })
 ServerImpl.__index = ServerImpl
 
@@ -64,34 +64,55 @@ local function checkDeltaMode (self: any, mode: number): ()
     end
 end
 
-function ServerImpl.sendTo (self: any, data: any, player: Player): ()
-    checkDeltaMode (self, DELTA_TARGETED)
-    serverWriteTo (player, self._id, self._name, self._codec, data, self._isUnreliable)
-end
+function ServerImpl.send (self: any, data: any, target: any?): ()
+    if target == nil then
+        error ("[Lync] Server packet:send requires a target")
+    end
 
-function ServerImpl.sendToAll (self: any, data: any): ()
-    checkDeltaMode (self, DELTA_BROADCAST)
-    serverWriteToAll (self._id, self._name, self._codec, data, self._isUnreliable)
-end
+    local id = self._id
+    local name = self._name
+    local codec = self._codec
+    local isUnreliable = self._isUnreliable
 
-function ServerImpl.sendToList (self: any, data: any, players: { Player }): ()
-    checkDeltaMode (self, DELTA_TARGETED)
-    serverWriteToList (players, self._id, self._name, self._codec, data, self._isUnreliable)
-end
+    -- Single player
+    if typeof (target) == "Instance" then
+        checkDeltaMode (self, DELTA_TARGETED)
+        serverWriteTo (target :: Player, id, name, codec, data, isUnreliable)
+        return
+    end
 
-function ServerImpl.sendToAllExcept (self: any, data: any, except: Player): ()
-    checkDeltaMode (self, DELTA_BROADCAST)
-    serverWriteToAllExcept (except, self._id, self._name, self._codec, data, self._isUnreliable)
-end
+    -- Must be a table from here
+    local tag = target._tag
 
-function ServerImpl.sendToGroup (self: any, data: any, groupName: string): ()
-    checkDeltaMode (self, DELTA_BROADCAST)
-    serverWriteToGroup (groupName, self._id, self._name, self._codec, data, self._isUnreliable)
+    -- Lync.all sentinel
+    if tag == "all" then
+        checkDeltaMode (self, DELTA_BROADCAST)
+        serverWriteToAll (id, name, codec, data, isUnreliable)
+        return
+    end
+
+    -- Lync.except(player, ...) descriptor
+    if tag == "except" then
+        checkDeltaMode (self, DELTA_BROADCAST)
+        serverWriteToAllExcept (target._set, id, name, codec, data, isUnreliable)
+        return
+    end
+
+    -- Group object
+    if tag == "group" then
+        checkDeltaMode (self, DELTA_BROADCAST)
+        serverWriteToSet (target:getSet (), id, name, codec, data, isUnreliable)
+        return
+    end
+
+    -- Player list (array)
+    checkDeltaMode (self, DELTA_TARGETED)
+    serverWriteToList (target :: { Player }, id, name, codec, data, isUnreliable)
 end
 
 table.freeze (ServerImpl)
 
--- Client-only metatable . Has send(), no sendTo/sendToAll
+-- Client-only metatable. Has send(), no target needed.
 local ClientImpl = setmetatable ({}, { __index = SharedImpl })
 ClientImpl.__index = ClientImpl
 

package/src/api/Query.luau

@@ -6,7 +6,6 @@ local Players = game:GetService ("Players")
 local RunService = game:GetService ("RunService")
 
 local Client = require (script.Parent.Parent.transport.Client)
-local Group = require (script.Parent.Group)
 local Registry = require (script.Parent.Parent.internal.Registry)
 local Server = require (script.Parent.Parent.transport.Server)
 local Signal = require (script.Parent.Signal)
@@ -82,90 +81,35 @@ local function onTimeout (correlation: number): ()
     completeQuery (correlation, nil)
 end
 
--- Query ------------------------------------------------------------------
-
-local QueryImpl = {}
-QueryImpl.__index = QueryImpl
-
-function QueryImpl.listen (self: any, callback: (...any) -> any): Connection
-    local respId = self._respReg.id
-    local respName = self._name
-    local respCodec = self._respReg.codec
-
-    if IS_SERVER then
-        return self._reqReg.signal:connect (
-            function (request: any, player: Player, correlation: number): ()
-                local ok, response = pcall (callback, request, player)
-                if not ok then
-                    warn (`[Lync] Query handler error on "{respName}": {response}`)
-                end
-
-                if ok and response ~= nil then
-                    Server.writeQuery (player, respId, respName, correlation, respCodec, response)
-                else
-                    Server.writeQueryNil (player, respId, respName, correlation)
-                end
-            end
-        )
-    else
-        return self._reqReg.signal:connect (
-            function (request: any, _player: Player?, correlation: number): ()
-                local ok, response = pcall (callback, request)
-                if not ok then
-                    warn (`[Lync] Query handler error on "{respName}": {response}`)
-                end
-
-                if ok and response ~= nil then
-                    Client.writeQuery (respId, respName, correlation, respCodec, response)
-                else
-                    Client.writeQueryNil (respId, respName, correlation)
-                end
-            end
-        )
+-- Send a query to multiple players and yield. Returns { [Player]: response? }.
+local function requestMulti (self: any, players: { Player }, data: any): { [Player]: any? }
+    if not IS_SERVER then
+        error ("[Lync] Multi-request is server-only")
     end
-end
 
-function QueryImpl.invoke (self: any, request: any, player: Player?): any
-    if IS_SERVER and not player then
-        error ("[Lync] Query:invoke on server requires a player argument")
+    local count = #players
+    if count == 0 then
+        return {}
     end
 
-    local correlation = allocCorrelation ()
-    local thread = coroutine.running ()
-
-    local entry: PendingQuery = { thread = thread, timeout = nil }
-    _pending[correlation] = entry
+    if count == 1 then
+        -- Delegate to single-player path
+        local correlation = allocCorrelation ()
+        local thread = coroutine.running ()
+        local entry: PendingQuery = { thread = thread, timeout = nil }
+        _pending[correlation] = entry
 
-    if IS_SERVER then
         Server.writeQuery (
-            player :: Player,
+            players[1],
             self._reqReg.id,
             self._name,
             correlation,
             self._reqReg.codec,
-            request
+            data
         )
-    else
-        Client.writeQuery (self._reqReg.id, self._name, correlation, self._reqReg.codec, request)
-    end
-
-    entry.timeout = task.delay (self._timeout, onTimeout, correlation)
-    return coroutine.yield ()
-end
-
--- Send a query to multiple players and yield. Returns { [Player]: response? }.
-local function invokeMulti (self: any, players: { Player }, request: any): { [Player]: any? }
-    if not IS_SERVER then
-        error ("[Lync] Multi-invoke is server-only")
-    end
-
-    local count = #players
-    if count == 0 then
-        return {}
-    end
 
-    if count == 1 then
-        local result = QueryImpl.invoke (self, request, players[1])
+        entry.timeout = task.delay (self._timeout, onTimeout, correlation)
+        local result = coroutine.yield ()
         return { [players[1]] = result }
     end
 
@@ -187,8 +131,8 @@ local function invokeMulti (self: any, players: { Player }, request: any): { [Pl
 
         local entry: PendingQuery = {
             thread = nil,
-            callback = function (data: any): ()
-                results[player] = data
+            callback = function (resp: any): ()
+                results[player] = resp
                 remaining -= 1
                 if remaining == 0 and not finished then
                     finished = true
@@ -200,7 +144,7 @@ local function invokeMulti (self: any, players: { Player }, request: any): { [Pl
 
         _pending[correlation] = entry
 
-        Server.writeQuery (player, reqId, reqName, correlation, reqCodec, request)
+        Server.writeQuery (player, reqId, reqName, correlation, reqCodec, data)
     end
 
     local timeoutThread = task.delay (timeout, function (): ()
@@ -232,22 +176,102 @@ local function invokeMulti (self: any, players: { Player }, request: any): { [Pl
     return coroutine.yield ()
 end
 
-function QueryImpl.invokeAll (self: any, request: any): { [Player]: any? }
+-- Query ------------------------------------------------------------------
+
+local QueryImpl = {}
+QueryImpl.__index = QueryImpl
+
+function QueryImpl.listen (self: any, callback: (...any) -> any): Connection
+    local respId = self._respReg.id
+    local respName = self._name
+    local respCodec = self._respReg.codec
+
+    if IS_SERVER then
+        return self._reqReg.signal:connect (
+            function (request: any, player: Player, correlation: number): ()
+                local ok, response = pcall (callback, request, player)
+                if not ok then
+                    warn (`[Lync] Query handler error on "{respName}": {response}`)
+                end
+
+                if ok and response ~= nil then
+                    Server.writeQuery (player, respId, respName, correlation, respCodec, response)
+                else
+                    Server.writeQueryNil (player, respId, respName, correlation)
+                end
+            end
+        )
+    else
+        return self._reqReg.signal:connect (
+            function (request: any, _player: Player?, correlation: number): ()
+                local ok, response = pcall (callback, request)
+                if not ok then
+                    warn (`[Lync] Query handler error on "{respName}": {response}`)
+                end
+
+                if ok and response ~= nil then
+                    Client.writeQuery (respId, respName, correlation, respCodec, response)
+                else
+                    Client.writeQueryNil (respId, respName, correlation)
+                end
+            end
+        )
+    end
+end
+
+-- Client: send request to server, yield until response.
+function QueryImpl.request (self: any, data: any): any
+    if IS_SERVER then
+        error ("[Lync] query:request is client-only. Use query:requestFrom on server")
+    end
+
+    local correlation = allocCorrelation ()
+    local thread = coroutine.running ()
+    local entry: PendingQuery = { thread = thread, timeout = nil }
+    _pending[correlation] = entry
+
+    Client.writeQuery (self._reqReg.id, self._name, correlation, self._reqReg.codec, data)
+
+    entry.timeout = task.delay (self._timeout, onTimeout, correlation)
+    return coroutine.yield ()
+end
+
+-- Server: send request to one player, yield until response.
+function QueryImpl.requestFrom (self: any, player: Player, data: any): any
+    if not IS_SERVER then
+        error ("[Lync] query:requestFrom is server-only. Use query:request on client")
+    end
+
+    local correlation = allocCorrelation ()
+    local thread = coroutine.running ()
+    local entry: PendingQuery = { thread = thread, timeout = nil }
+    _pending[correlation] = entry
+
+    Server.writeQuery (player, self._reqReg.id, self._name, correlation, self._reqReg.codec, data)
+
+    entry.timeout = task.delay (self._timeout, onTimeout, correlation)
+    return coroutine.yield ()
+end
+
+-- Server: send request to all players, yield until all respond or timeout.
+function QueryImpl.requestAll (self: any, data: any): { [Player]: any? }
     local players = Players:GetPlayers ()
-    return invokeMulti (self, players, request)
+    return requestMulti (self, players, data)
 end
 
-function QueryImpl.invokeList (self: any, request: any, players: { Player }): { [Player]: any? }
-    return invokeMulti (self, players, request)
+-- Server: send request to a list of players.
+function QueryImpl.requestList (self: any, players: { Player }, data: any): { [Player]: any? }
+    return requestMulti (self, players, data)
 end
 
-function QueryImpl.invokeGroup (self: any, request: any, groupName: string): { [Player]: any? }
-    local set = Group.getSet (groupName)
+-- Server: send request to all players in a group.
+function QueryImpl.requestGroup (self: any, group: any, data: any): { [Player]: any? }
+    local set = group:getSet ()
     local players = {} :: { Player }
     for player in set do
         table.insert (players, player)
     end
-    return invokeMulti (self, players, request)
+    return requestMulti (self, players, data)
 end
 
 -- Public -----------------------------------------------------------------

package/src/api/Scope.luau

@@ -0,0 +1,73 @@
+--!strict
+--!optimize 2
+-- Batched connection lifecycle management.
+
+-- Private ----------------------------------------------------------------
+
+local ScopeImpl = {}
+ScopeImpl.__index = ScopeImpl
+
+function ScopeImpl.add (self: any, conn: any): ()
+    if not conn then
+        return
+    end
+
+    local entries = self._entries
+    local count = self._count + 1
+    self._count = count
+    entries[count] = conn
+end
+
+function ScopeImpl.listen (self: any, source: any, callback: (...any) -> ()): ()
+    local conn = source:listen (callback)
+    local entries = self._entries
+    local count = self._count + 1
+    self._count = count
+    entries[count] = conn
+end
+
+function ScopeImpl.once (self: any, source: any, callback: (...any) -> ()): ()
+    local conn = source:once (callback)
+    local entries = self._entries
+    local count = self._count + 1
+    self._count = count
+    entries[count] = conn
+end
+
+function ScopeImpl.listenAll (self: any, namespace: any, callback: (...any) -> ()): ()
+    local conn = namespace:listenAll (callback)
+    local entries = self._entries
+    local count = self._count + 1
+    self._count = count
+    entries[count] = conn
+end
+
+function ScopeImpl.destroy (self: any): ()
+    local entries = self._entries
+    local count = self._count
+
+    for i = 1, count do
+        local conn = entries[i]
+        entries[i] = nil
+
+        if typeof (conn) == "RBXScriptConnection" then
+            conn:Disconnect ()
+        elseif conn.disconnect then
+            conn:disconnect ()
+        end
+    end
+
+    self._count = 0
+end
+
+table.freeze (ScopeImpl)
+
+-- Public -----------------------------------------------------------------
+
+local Scope = {}
+
+function Scope.create (): any
+    return setmetatable ({ _entries = {}, _count = 0 }, ScopeImpl)
+end
+
+return table.freeze (Scope)

package/src/index.d.ts

@@ -72,6 +72,46 @@ type InferBitfield<S extends Record<string, FieldSpec>> = Prettify<{
     [K in keyof S]: InferFieldSpec<S[K]>;
 }>;
 
+// -- Target descriptors ------------------------------------------------
+
+export interface AllTarget {
+    readonly _tag: "all";
+}
+
+export interface ExceptTarget {
+    readonly _tag: "except";
+    readonly _set: ReadonlyMap<Player, true>;
+}
+
+export interface GroupObject {
+    readonly _tag: "group";
+    add(this: GroupObject, player: Player): boolean;
+    remove(this: GroupObject, player: Player): boolean;
+    has(this: GroupObject, player: Player): boolean;
+    count(this: GroupObject): number;
+    forEach(this: GroupObject, fn: (player: Player) => void): void;
+    getSet(this: GroupObject): ReadonlyMap<Player, true>;
+    destroy(this: GroupObject): void;
+}
+
+export type Target = Player | AllTarget | ExceptTarget | GroupObject | Player[];
+
+// -- Scope -------------------------------------------------------------
+
+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;
+    destroy(this: Scope): void;
+}
+
+// -- DROP sentinel -----------------------------------------------------
+
+export interface DropSentinel {
+    readonly _tag: "drop";
+}
+
 // -- Packet ------------------------------------------------------------
 
 export interface PacketConfig<T> {
@@ -82,14 +122,8 @@ export interface PacketConfig<T> {
     maxPayloadBytes?: number;
 }
 
-// Server methods throw on client and vice versa.
 export interface Packet<T> {
-    sendTo(this: Packet<T>, data: T, player: Player): void;
-    sendToAll(this: Packet<T>, data: T): void;
-    sendToAllExcept(this: Packet<T>, data: T, except: Player): void;
-    sendToList(this: Packet<T>, data: T, players: Player[]): void;
-    sendToGroup(this: Packet<T>, data: T, groupName: string): void;
-    send(this: Packet<T>, data: T): void;
+    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;
     wait(this: Packet<T>): LuaTuple<[T, Player | undefined]>;
@@ -111,17 +145,18 @@ export interface Query<Req, Resp> {
         this: Query<Req, Resp>,
         callback: (request: Req, player: Player) => Resp | undefined,
     ): Connection;
-    invoke(this: Query<Req, Resp>, request: Req, player?: Player): Resp | undefined;
-    invokeAll(this: Query<Req, Resp>, request: Req): Map<Player, Resp | undefined>;
-    invokeList(
+    request(this: Query<Req, Resp>, data: Req): Resp | undefined;
+    requestFrom(this: Query<Req, Resp>, player: Player, data: Req): Resp | undefined;
+    requestAll(this: Query<Req, Resp>, data: Req): Map<Player, Resp | undefined>;
+    requestList(
         this: Query<Req, Resp>,
-        request: Req,
         players: Player[],
+        data: Req,
     ): Map<Player, Resp | undefined>;
-    invokeGroup(
+    requestGroup(
         this: Query<Req, Resp>,
-        request: Req,
-        groupName: string,
+        group: GroupObject,
+        data: Req,
     ): Map<Player, Resp | undefined>;
 }
 
@@ -143,6 +178,8 @@ type InferQueries<Q extends Record<string, QueryConfig<unknown, unknown>>> = {
 };
 
 export interface Namespace {
+    readonly packets: Record<string, Packet<unknown>>;
+    readonly queries: Record<string, Query<unknown, unknown>>;
     listenAll(
         this: Namespace,
         callback: (name: string, data: unknown, sender: Player | undefined) => void,
@@ -166,7 +203,6 @@ export interface Namespace {
 declare namespace Lync {
     // Lifecycle
     export const VERSION: string;
-    export const version: string;
     export function start(): void;
 
     // Definition
@@ -251,21 +287,24 @@ declare namespace Lync {
         callback: (player: Player, reason: string, packetName: string, data: unknown) => void,
     ): () => void;
     export function onSend(
-        handler: (data: unknown, name: string, player: Player | undefined) => unknown | undefined,
+        handler: (data: unknown, name: string, player: Player | undefined) => unknown | DropSentinel | undefined,
     ): () => void;
     export function onReceive(
-        handler: (data: unknown, name: string, player: Player | undefined) => unknown | undefined,
+        handler: (data: unknown, name: string, player: Player | undefined) => unknown | DropSentinel | undefined,
     ): () => void;
 
+    // Target descriptors
+    export const all: AllTarget;
+    export function except(...players: Player[]): ExceptTarget;
+
+    // Middleware sentinel
+    export const DROP: DropSentinel;
+
     // Groups
-    export function createGroup(name: string): void;
-    export function destroyGroup(name: string): void;
-    export function addToGroup(name: string, player: Player): boolean;
-    export function removeFromGroup(name: string, player: Player): boolean;
-    export function hasInGroup(name: string, player: Player): boolean;
-    export function getGroupSet(name: string): ReadonlyMap<Player, true>;
-    export function groupCount(name: string): number;
-    export function forEachInGroup(name: string, fn: (player: Player) => void): void;
+    export function createGroup(name: string): GroupObject;
+
+    // Scope
+    export function scope(): Scope;
 
     // Configuration
     export function setChannelMaxSize(bytes: number): void;
@@ -276,4 +315,4 @@ declare namespace Lync {
     export function queryPendingCount(): number;
 }
 
-export default Lync;
+export default Lync;

package/src/init.luau

@@ -52,11 +52,25 @@ local Group = require (script.api.Group)
 local Namespace = require (script.api.Namespace)
 local Packet = require (script.api.Packet)
 local Query = require (script.api.Query)
+local Scope = require (script.api.Scope)
 
 -- Transport
 local Client = require (script.transport.Client)
 local Server = require (script.transport.Server)
 
+-- Sentinels --------------------------------------------------------------
+
+local ALL = table.freeze ({ _tag = "all" })
+
+local function except (...: any): any
+    local count = select ("#", ...)
+    local set = {} :: { [Player]: true }
+    for i = 1, count do
+        set[select (i, ...)] = true
+    end
+    return { _tag = "except", _set = set }
+end
+
 -- Public -----------------------------------------------------------------
 
 local function start (): ()
@@ -68,8 +82,7 @@ local function start (): ()
 end
 
 local Lync = {
-    VERSION = "1.3.1",
-    version = "1.3.1",
+    VERSION = "1.4.0",
 
     -- Lifecycle
     start = start,
@@ -139,15 +152,18 @@ local Lync = {
     onSend = Middleware.addSend,
     onReceive = Middleware.addReceive,
 
+    -- Target descriptors
+    all = ALL,
+    except = except,
+
+    -- Middleware sentinel
+    DROP = Middleware.DROP,
+
     -- Groups
     createGroup = Group.create,
-    destroyGroup = Group.destroy,
-    addToGroup = Group.add,
-    removeFromGroup = Group.remove,
-    hasInGroup = Group.has,
-    getGroupSet = Group.getSet,
-    groupCount = Group.count,
-    forEachInGroup = Group.forEach,
+
+    -- Scope
+    scope = Scope.create,
 
     -- Configuration (call before start)
     setChannelMaxSize = Channel.setMaxSize,

package/src/internal/Middleware.luau

@@ -14,13 +14,17 @@ type Chain = {
 local _send: Chain = { handlers = {}, snapshot = nil }
 local _receive: Chain = { handlers = {}, snapshot = nil }
 
+-- Constants --------------------------------------------------------------
+
+local DROP = table.freeze ({ _tag = "drop" })
+
 -- Private ----------------------------------------------------------------
 
 local function runChain (chain: { Handler }, data: any, name: string, player: Player?): any?
     local current = data
     for i = 1, #chain do
         local result = chain[i] (current, name, player)
-        if result == nil then
+        if result == nil or result == DROP then
             return nil
         end
         current = result
@@ -55,6 +59,10 @@ local function run (chain: Chain, data: any, name: string, player: Player?): any
         return nil
     end
 
+    if result == DROP then
+        return nil
+    end
+
     return result
 end
 
@@ -105,5 +113,6 @@ end
 
 Middleware.hasSend = false
 Middleware.hasReceive = false
+Middleware.DROP = DROP
 
 return Middleware

package/src/transport/Server.luau

@@ -14,7 +14,6 @@ local channelWriteBatchRaw = Channel.writeBatchRaw
 local channelSetPacket = Channel.setCurrentPacket
 
 local Gate = require (script.Parent.Gate)
-local Group = require (script.Parent.Parent.api.Group)
 local Middleware = require (script.Parent.Parent.internal.Middleware)
 local Pool = require (script.Parent.Parent.internal.Pool)
 local Reader = require (script.Parent.Reader)
@@ -161,7 +160,7 @@ local function broadcastToAll (
     codec: Codec<any>,
     data: any,
     isUnreliable: boolean,
-    except: Player?
+    exceptSet: { [Player]: true }?
 ): ()
     local final, snapLen, snapRefs = prepareBroadcast (name, codec, data)
     if final == nil and data ~= nil then
@@ -170,7 +169,7 @@ local function broadcastToAll (
 
     local scratchBuff = _broadScratch.buff
     for player, state in _players do
-        if except and player == except then
+        if exceptSet and exceptSet[player] then
             continue
         end
         local ch = if isUnreliable then state.unreliable else state.reliable
@@ -304,25 +303,25 @@ function Server.writeToList (
 end
 
 function Server.writeToAllExcept (
-    except: Player,
+    exceptSet: { [Player]: true },
     id: number,
     name: string,
     codec: Codec<any>,
     data: any,
     isUnreliable: boolean
 ): ()
-    broadcastToAll (id, name, codec, data, isUnreliable, except)
+    broadcastToAll (id, name, codec, data, isUnreliable, exceptSet)
 end
 
-function Server.writeToGroup (
-    groupName: string,
+function Server.writeToSet (
+    set: { [Player]: true },
     id: number,
     name: string,
     codec: Codec<any>,
     data: any,
     isUnreliable: boolean
 ): ()
-    broadcastToSet (Group.getSet (groupName), id, name, codec, data, isUnreliable)
+    broadcastToSet (set, id, name, codec, data, isUnreliable)
 end
 
 -- Shared for both query requests and responses (identical wire format).