@axpecter/lync 2.2.1 → 2.3.2

package/src/api/Group.luau

@@ -1,10 +1,11 @@
 --!strict
 --!optimize 2
--- Named player sets with __iter, auto-cleanup on PlayerRemoving.
+-- Named player sets with __iter and auto-cleanup on PlayerRemoving.
 
 local Players = game:GetService("Players")
 
-local Util = require(script.Parent.Parent.internal.Util)
+local Array = require(script.Parent.Parent.util.Array)
+local Log = require(script.Parent.Parent.util.Log)
 
 -- Public types -----------------------------------------------------------
 
@@ -14,22 +15,24 @@ export type GroupHandle = {
     has: (self: GroupHandle, player: Player) -> boolean,
     count: (self: GroupHandle) -> number,
     destroy: (self: GroupHandle) -> (),
-    _lyncGroup: boolean,
+    _lyncKind: "group",
     _members: { [Player]: boolean },
 }
 
-type Group = GroupHandle & { _count: number, _name: string }
+type GroupInternal = GroupHandle & { _count: number, _name: string }
 
 -- State ------------------------------------------------------------------
 
-local _groups: { [string]: Group } = {}
+local _groups: { [string]: GroupInternal } = {}
+-- Reverse index used by PlayerRemoving so we don't scan every group on disconnect.
 local _playerCleanup: { [Player]: { Group } } = {}
 local _cleanupConnected = false
 
 -- Private ----------------------------------------------------------------
 
-local swapRemove = Util.swapRemove
+local swapRemove = Array.swapRemove
 
+-- Connect once on the first Group.create; subsequent creates reuse the same connection.
 local function ensureCleanup(): ()
     if _cleanupConnected then
         return
@@ -49,6 +52,17 @@ local function ensureCleanup(): ()
     end)
 end
 
+local function untrackCleanup(player: Player, group: GroupInternal): ()
+    local cleanup = _playerCleanup[player]
+    if not cleanup then
+        return
+    end
+    local idx = table.find(cleanup, group)
+    if idx then
+        swapRemove(cleanup, idx)
+    end
+end
+
 -- Public -----------------------------------------------------------------
 
 local Group = {}
@@ -56,15 +70,12 @@ local Group = {}
 local GroupMeta = {}
 GroupMeta.__index = GroupMeta
 
---[[
-    __iter returns the standard 3-tuple iterator so `for player in group do`
-    uses Luau's builtin path (luaH_next) with zero closure allocation.
-]]
-function GroupMeta.__iter(self: Group): (any, any, any)
+-- __iter lets `for player in group do` skip the explicit :members() call.
+function GroupMeta.__iter(self: GroupInternal): (any, any, any)
     return next, self._members, nil
 end
 
-function GroupMeta.add(self: Group, player: Player): boolean
+function GroupMeta.add(self: GroupInternal, player: Player): boolean
     if self._members[player] then
         return false
     end
@@ -81,45 +92,32 @@ function GroupMeta.add(self: Group, player: Player): boolean
     return true
 end
 
-function GroupMeta.remove(self: Group, player: Player): boolean
+function GroupMeta.remove(self: GroupInternal, player: Player): boolean
     if not self._members[player] then
         return false
     end
 
     self._members[player] = nil
     self._count -= 1
-
-    local cleanup = _playerCleanup[player]
-    if cleanup then
-        local idx = table.find(cleanup, self)
-        if idx then
-            swapRemove(cleanup, idx)
-        end
-    end
+    untrackCleanup(player, self)
     return true
 end
 
-function GroupMeta.has(self: Group, player: Player): boolean
+function GroupMeta.has(self: GroupInternal, player: Player): boolean
     return self._members[player] == true
 end
 
-function GroupMeta.count(self: Group): number
+function GroupMeta.count(self: GroupInternal): number
     return self._count
 end
 
-function GroupMeta.destroy(self: Group): ()
+function GroupMeta.destroy(self: GroupInternal): ()
     if _groups[self._name] == self then
         _groups[self._name] = nil
     end
 
     for player in self._members do
-        local cleanup = _playerCleanup[player]
-        if cleanup then
-            local idx = table.find(cleanup, self)
-            if idx then
-                swapRemove(cleanup, idx)
-            end
-        end
+        untrackCleanup(player, self)
     end
 
     table.clear(self._members)
@@ -130,13 +128,13 @@ table.freeze(GroupMeta)
 
 function Group.create(name: string): GroupHandle
     if _groups[name] then
-        error(`[Lync] Lync.group: "{name}" already exists`)
+        Log.error(`"{name}" already exists`)
     end
 
     ensureCleanup()
 
     local group = setmetatable({
-        _lyncGroup = true,
+        _lyncKind = "group" :: "group",
         _members = {} :: { [Player]: boolean },
         _count = 0,
         _name = name,
@@ -146,4 +144,13 @@ function Group.create(name: string): GroupHandle
     return group
 end
 
+function Group.reset(): ()
+    for _, group in _groups do
+        table.clear(group._members)
+        group._count = 0
+    end
+    table.clear(_groups)
+    table.clear(_playerCleanup)
+end
+
 return table.freeze(Group)

package/src/api/Packet.luau

@@ -7,34 +7,38 @@ local RunService = game:GetService("RunService")
 
 local Baseline = require(script.Parent.Parent.internal.Baseline)
 local Channel = require(script.Parent.Parent.internal.Channel)
+local Log = require(script.Parent.Parent.util.Log)
 local Middleware = require(script.Parent.Parent.internal.Middleware)
+local Player = require(script.Parent.Parent.util.Player)
 local Registry = require(script.Parent.Parent.internal.Registry)
+local Shared = require(script.Parent.Parent.codec.composite.Shared)
 local Transport = require(script.Parent.Parent.internal.Transport)
 local Types = require(script.Parent.Parent.Types)
-local Util = require(script.Parent.Parent.internal.Util)
 
 -- Constants --------------------------------------------------------------
 
 local IS_SERVER = RunService:IsServer()
 
+-- mode: TS_* tag; headerSize: 1 (frame byte) + timestamp bytes (1, 2, or 8).
+local TS_MODES: { [string]: { mode: number, headerSize: number } } = table.freeze({
+    frame = table.freeze({ mode = Channel.TS_FRAME, headerSize = 2 }),
+    offset = table.freeze({ mode = Channel.TS_OFFSET, headerSize = 3 }),
+    full = table.freeze({ mode = Channel.TS_FULL, headerSize = 9 }),
+})
+
+local EMPTY_OPTIONS: Types.PacketOptions = table.freeze({})
+
 -- Private ----------------------------------------------------------------
 
-local isPlayer = Util.isPlayer
+local isPlayer = Player.is
 
 local function resolveTimestampMode(ts: ("frame" | "offset" | "full")?): (number, number)
-    if ts == "frame" then
-        Channel.enableTimestamps()
-        return Channel.TS_FRAME, 2
-    end
-    if ts == "offset" then
-        Channel.enableTimestamps()
-        return Channel.TS_OFFSET, 3
-    end
-    if ts == "full" then
-        Channel.enableTimestamps()
-        return Channel.TS_FULL, 9
+    if ts == nil then
+        return Channel.TS_NONE, 1
     end
-    return Channel.TS_NONE, 1
+    local entry = TS_MODES[ts]
+    Channel.enableTimestamps()
+    return entry.mode, entry.headerSize
 end
 
 -- Public types -----------------------------------------------------------
@@ -63,17 +67,18 @@ function Packet.define<T>(
     codec: Types.InternalCodec<T>,
     options: Types.PacketOptions?
 ): PacketHandle<T>
-    local opts = options or ({} :: Types.PacketOptions)
+    local opts = options or EMPTY_OPTIONS
     local isUnreliable = opts.unreliable or false
 
+    -- Delta + unreliable is unsafe: a dropped frame permanently desyncs the receiver baseline.
     if isUnreliable and codec._isDelta then
-        error(`[Lync] Lync.packet: "{name}" cannot use delta codecs with unreliable transport`)
+        Log.error(
+            `"{name}" delta codecs need reliable transport (lost packets desync the baseline)`
+        )
     end
 
     if codec._hasUnknown and not opts.validate then
-        warn(
-            `[Lync] Lync.packet: "{name}" uses unknown codec without validate; data bypasses schema validation`
-        )
+        Log.warn(`"{name}" uses unknown codec without validate; data bypasses schema validation`)
     end
 
     if codec._isDelta then
@@ -109,85 +114,154 @@ function Packet.define<T>(
         end
     end
 
-    local function applySend(data: any, player: Player?): any?
+    --[[
+        Run the send middleware chain. Returns (dropped, value). A nil value
+        is a legitimate payload (Lync.nothing); only the explicit Lync.DROP
+        sentinel or a hook returning DROP triggers the drop branch.
+    ]]
+    local function applySend(data: any, player: Player?): (boolean, any)
         if not Middleware.hasSendHooks() then
-            return data
+            return false, data
         end
-
         local sendData = Middleware.runSend(data, name, player)
-        if typeof(sendData) == "table" and sendData._lyncDrop then
-            return nil
+        if typeof(sendData) == "table" and sendData._lyncKind == "drop" then
+            return true, nil
         end
-        return sendData
+        return false, sendData
     end
 
-    local function sendFromServer(data: any, target: any): ()
-        if target == nil then
-            error(`[Lync] Packet.send: "{name}" server send requires a target`)
-        end
+    -- Non-delta codecs are stateless wire-encoders, so broadcast can encode
+    -- once and bufCopy the payload to every player. Falls through if the
+    -- encoded payload includes ref indices (the indices would need rewriting
+    -- per channel, which no codec exposes).
+    local canEncodeOnce = not codec._isDelta and not codec._hasDelta
 
-        if isPlayer(target) then
-            local sendData = applySend(data, target :: Player)
-            if sendData == nil then
-                return
-            end
-            sendToPlayer(target :: Player, sendData)
+    local function broadcast(players: { Player }, data: any): ()
+        local count = #players
+        if count == 0 then
             bumpFires()
             return
         end
 
-        if typeof(target) == "table" then
-            local sendData = applySend(data, nil)
-            if sendData == nil then
-                return
-            end
-
-            if target._lyncAll then
-                for _, player in Players:GetPlayers() do
-                    sendToPlayer(player, sendData)
+        if canEncodeOnce then
+            local scratch = Shared.acquireScratch()
+            scratch.currentPacket = name
+            codec.write(scratch, data)
+            scratch.currentPacket = nil
+            if scratch.refCount == 0 then
+                local payload = scratch.buff
+                local payloadLen = scratch.cursor
+                local server = Transport.server()
+                -- Channel.writeBatchEncoded is hot-swapped by enableStats; re-read per call.
+                local writeBatchEncoded = Channel.writeBatchEncoded
+                for i = 1, count do
+                    writeBatchEncoded(
+                        server.getChannel(players[i], isUnreliable),
+                        reg,
+                        payload,
+                        payloadLen
+                    )
                 end
+                Shared.releaseScratch()
                 bumpFires()
                 return
             end
+            Shared.releaseScratch()
+        end
 
-            if target._lyncExcept then
-                local excluded = target._excluded :: { [Player]: boolean }
-                for _, player in Players:GetPlayers() do
-                    if not excluded[player] then
-                        sendToPlayer(player, sendData)
-                    end
+        for i = 1, count do
+            sendToPlayer(players[i], data)
+        end
+        bumpFires()
+    end
+
+    --[[
+        Resolve a target table into a { Player } list. Returns nil for unknown
+        sentinel kinds; the caller errors with the original target type.
+    ]]
+    local function resolveAudience(target: any): { Player }?
+        local kind = target._lyncKind
+        if kind == "all" then
+            return Players:GetPlayers()
+        end
+
+        if kind == "except" then
+            local excluded = target._excluded :: { [Player]: boolean }
+            local all = Players:GetPlayers()
+            local list = table.create(#all)
+            local n = 0
+            for _, player in all do
+                if not excluded[player] then
+                    n += 1
+                    list[n] = player
                 end
-                bumpFires()
-                return
             end
+            return list
+        end
 
-            if target._lyncGroup then
-                for player in target._members :: { [Player]: boolean } do
-                    sendToPlayer(player, sendData)
-                end
-                bumpFires()
-                return
+        if kind == "group" then
+            local members = target._members :: { [Player]: boolean }
+            local list: { Player } = {}
+            local n = 0
+            for player in members do
+                n += 1
+                list[n] = player
             end
+            return list
+        end
 
+        if kind == nil then
+            -- Plain { Player } array. Validate entries on the way to a clean list.
+            local list: { Player } = {}
+            local n = 0
             for _, player in target do
                 if isPlayer(player) then
-                    sendToPlayer(player :: Player, sendData)
+                    n += 1
+                    list[n] = player :: Player
                 end
             end
+            return list
+        end
+
+        return nil
+    end
+
+    local function sendToTarget(data: any, target: any): ()
+        if isPlayer(target) then
+            local dropped, sendData = applySend(data, target :: Player)
+            if dropped then
+                return
+            end
+            sendToPlayer(target :: Player, sendData)
             bumpFires()
             return
         end
 
-        error(
-            `[Lync] Packet.send: "{name}" expected Player, table, Group, or Lync.all as target, got {typeof(
-                target
-            )}`
-        )
+        if typeof(target) == "table" then
+            local dropped, sendData = applySend(data, nil)
+            if dropped then
+                return
+            end
+            local audience = resolveAudience(target)
+            if audience then
+                broadcast(audience, sendData)
+                return
+            end
+        end
+
+        Log.error(`"{name}" expected Player, table, Group, or Lync.all, got {typeof(target)}`)
+    end
+
+    local function sendFromServer(data: any, target: any): ()
+        if target == nil then
+            Log.error(`"{name}" server send requires a target`)
+        end
+        sendToTarget(data, target)
     end
 
     local function sendFromClient(data: any): ()
-        local sendData = applySend(data, nil)
-        if sendData == nil then
+        local dropped, sendData = applySend(data, nil)
+        if dropped then
             return
         end
         local ch = Transport.client().getChannel(isUnreliable)