@skating/swiftpacket 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skaterstudios (skaterstudios.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# SwiftPacket
+
+[![CI](https://github.com/skatingii/SwiftPacket/actions/workflows/ci.yml/badge.svg)](https://github.com/skatingii/SwiftPacket/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/skatingii/SwiftPacket)](LICENSE)
+
+A fast, fully typed, buffer-batched networking library for Roblox.
+
+Describe each packet once, with the types of the values it carries, then fire it
+like a function. SwiftPacket writes every message into one buffer per player,
+sends it once per frame, and checks everything a client sends before your code
+sees it.
+
+- **Typed**: `Fire()`, handlers and responses are checked by the Luau type
+  checker, without a single cast.
+- **Small**: every value is written in the fewest bytes its type allows, with no
+  type tags on the wire.
+- **Batched**: one remote call per player per frame, for reliable and unreliable
+  packets.
+- **Ordered**: messages to a player arrive in the order they were fired, events
+  and requests alike.
+- **Hardened**: bounds checks, rejection of NaN and infinity, a per-player byte
+  budget, rate limits and validators.
+
+## Installation
+
+With [Wally](https://wally.run), add SwiftPacket to your `wally.toml`:
+
+```toml
+[dependencies]
+SwiftPacket = "skatingii/swiftpacket@0.1.4"
+```
+
+With [roblox-ts](https://roblox-ts.com), install it from npm:
+
+```sh
+npm install @skating/swiftpacket
+```
+
+Add the `@skating` scope to your project so roblox-ts can find it. In
+`tsconfig.json`:
+
+```json
+"typeRoots": ["node_modules/@rbxts", "node_modules/@skating"]
+```
+
+And in `default.project.json`, next to `@rbxts` under `node_modules`:
+
+```json
+"@skating": { "$path": "node_modules/@skating" }
+```
+
+Then import it:
+
+```ts
+import SwiftPacket from "@skating/swiftpacket";
+
+const Chat = SwiftPacket("Chat", SwiftPacket.String);
+const GetCoins = SwiftPacket("GetCoins").Response(SwiftPacket.U32);
+```
+
+Or download `SwiftPacket.rbxm` from the
+[latest release](https://github.com/skatingii/SwiftPacket/releases/latest) and put
+it in `ReplicatedStorage`.
+
+## Example
+
+Define your packets in one module that both the server and the client require:
+
+```luau
+const SwiftPacket = require("@game/ReplicatedStorage/Packages/SwiftPacket")
+
+return {
+    Chat = SwiftPacket("Chat", SwiftPacket.String):RateLimit(5, 1),
+    Move = SwiftPacket("Move", SwiftPacket.Vector3F24):Unreliable(),
+    GetCoins = SwiftPacket("GetCoins"):Response(SwiftPacket.U32),
+    Inventory = SwiftPacket("Inventory", {
+        Coins = SwiftPacket.U32,
+        Items = { SwiftPacket.String },
+    }),
+}
+```
+
+On the server:
+
+```luau
+const Packets = require("@game/ReplicatedStorage/Packets")
+
+Packets.Chat.OnServerEvent:Connect(function(Player, Message)
+    Packets.Chat:FireExcept(Player, `{Player.Name}: {Message}`)
+end)
+
+Packets.GetCoins:SetServerInvoke(function(Player)
+    return 100
+end)
+```
+
+On the client:
+
+```luau
+const Packets = require("@game/ReplicatedStorage/Packets")
+
+Packets.Chat:Fire("hello")
+
+const Coins = Packets.GetCoins:Fire()
+```
+
+## Documentation
+
+- [Crash course](docs/tut/crash-course/1-introduction.md): packets, events,
+  requests, types and security, one page each.
+- [API reference](docs/api/swiftpacket.md): every function and type.
+- [Migrating from Packet](docs/tut/crash-course/8-migrating-from-packet.md):
+  what changes if you are coming from Packet.
+
+## Security
+
+Please do not report a vulnerability in a public issue. See
+[SECURITY.md](SECURITY.md) for how to report one privately.
+
+---
+
+SwiftPacket is released under the [MIT License](LICENSE) by
+[skaterstudios](https://skaterstudios.com).

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@skating/swiftpacket",
+	"version": "0.1.4",
+	"description": "A fast, fully typed, buffer-batched networking library for Roblox",
+	"main": "src/init.luau",
+	"types": "src/index.d.ts",
+	"files": [
+		"src"
+	],
+	"keywords": [
+		"roblox",
+		"roblox-ts",
+		"luau",
+		"networking",
+		"remote",
+		"buffer"
+	],
+	"author": "skaterstudios",
+	"license": "MIT",
+	"homepage": "https://github.com/skatingii/SwiftPacket#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/skatingii/SwiftPacket.git"
+	},
+	"bugs": {
+		"url": "https://github.com/skatingii/SwiftPacket/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/client.luau

@@ -0,0 +1,472 @@
+--!strict
+--!optimize 2
+
+--[[
+	Author: @skaterstudios
+	Website: skaterstudios.com
+	GitHub: github.com/skatingii/SwiftPacket
+	Discord Server: discord.gg/skaterstudios
+
+	Licensed under the MIT License. You may use, modify, redistribute and sell
+	this system freely, as long as this notice and the LICENSE file stay with it.
+]]
+
+const RunService = game:GetService("RunService")
+
+const Configuration = require("./configuration")
+const Cursor = require("./cursor")
+const Registry = require("./registry")
+const Schema = require("./schema")
+const ThreadPool = require("./thread_pool")
+const Wire = require("./wire")
+
+type Definition = Registry.Definition
+type Arguments = Schema.Arguments
+
+type PendingCall = {
+	Thread: thread,
+	Deadline: number,
+	Definition: Definition,
+}
+
+type Held = {
+	Source: buffer,
+	Instances: { any },
+	Offset: number,
+	InstancesOffset: number,
+	MissingId: number,
+	ReceivedAt: number,
+}
+
+const Client = {}
+
+const Reliable = Cursor.New()
+const Unreliable: { Cursor.Cursor } = { Cursor.New(Configuration.UnreliableByteLimit) }
+const PendingCalls: { [number]: PendingCall } = {}
+const Definitions: { [string]: Definition } = {}
+const Queued: { [Definition]: { Cursor.Cursor } } = {}
+const Waiting: { [Definition]: { thread } } = {}
+const HeldBatches: { Held } = {}
+const Scratch = Cursor.New()
+const Incoming = Wire.NewBatch()
+const NoInstances: { any } = {}
+const ResponseFlag = Wire.ResponseFlag
+const EventIndex = Wire.EventIndex
+
+local ReliableRemote: RemoteEvent? = nil
+local UnreliableRemote: UnreliableRemoteEvent? = nil
+local UnreliableCount = 1
+local NextCallIndex = 0
+local Elapsed = 0
+local RetryScheduled = false
+
+const function Deliver(Definition: Definition, Id: number, Body: Cursor.Cursor)
+	if Definition.Reliable then
+		Wire.Deliver(Reliable, Id, nil, nil, Body)
+
+		return
+	end
+
+	const Size = Wire.Size(Id, nil, Body)
+
+	if Size > Configuration.UnreliableByteLimit then
+		error(
+			`[swiftpacket] {Definition.Name} is {Size} bytes, over the unreliable limit of {Configuration.UnreliableByteLimit}`,
+			0
+		)
+	end
+
+	local Segment = Unreliable[UnreliableCount]
+
+	if Segment.Offset > 0 and Segment.Offset + Size > Configuration.UnreliableByteLimit then
+		UnreliableCount += 1
+
+		const Next = Unreliable[UnreliableCount]
+
+		if Next then
+			Segment = Next
+		else
+			Segment = Cursor.New(Configuration.UnreliableByteLimit)
+			Unreliable[UnreliableCount] = Segment
+		end
+	end
+
+	Wire.Deliver(Segment, Id, nil, nil, Body)
+end
+
+function Client.Send(Definition: Definition, ...: any)
+	const Id = Definition.Id
+
+	if Id == nil then
+		const Body = Cursor.New()
+		Schema.WriteBody(Body, Definition.Name, Definition.Arguments, ...)
+
+		const Bodies = Queued[Definition] or {}
+		table.insert(Bodies, Body)
+		Queued[Definition] = Bodies
+
+		return
+	end
+
+	if Definition.Reliable then
+		Schema.WriteEvent(Reliable, Id, Definition.Name, Definition.Arguments, ...)
+
+		return
+	end
+
+	Schema.WriteBody(Scratch, Definition.Name, Definition.Arguments, ...)
+	Deliver(Definition, Id, Scratch)
+end
+
+const function FindCallIndex(): number
+	local CallIndex = NextCallIndex
+
+	for Attempt = 1, Configuration.CallCapacity do
+		if PendingCalls[CallIndex] == nil then
+			return CallIndex
+		end
+
+		CallIndex = (CallIndex + 1) % Configuration.CallCapacity
+	end
+
+	error("[swiftpacket] too many calls are waiting on a response", 0)
+end
+
+function Client.Invoke(Definition: Definition, ...: any): ...any
+	local CallIndex = 0
+
+	if Definition.Id == nil then
+		const Body = Cursor.New()
+		Schema.WriteBody(Body, Definition.Name, Definition.Arguments, ...)
+
+		const Threads = Waiting[Definition] or {}
+		table.insert(Threads, coroutine.running())
+		Waiting[Definition] = Threads
+
+		coroutine.yield()
+
+		const Id = Definition.Id
+
+		if Id == nil then
+			error(`[swiftpacket] {Definition.Name} has no id`, 0)
+		end
+
+		CallIndex = FindCallIndex()
+		Wire.Deliver(Reliable, Id, CallIndex, nil, Body)
+	else
+		CallIndex = FindCallIndex()
+		Schema.WriteRequest(Reliable, Definition.Id, CallIndex, Definition.Name, Definition.Arguments, ...)
+	end
+
+	NextCallIndex = (CallIndex + 1) % Configuration.CallCapacity
+	PendingCalls[CallIndex] = {
+		Thread = coroutine.running(),
+		Deadline = os.clock() + Definition.TimeoutSeconds,
+		Definition = Definition,
+	}
+
+	return coroutine.yield()
+end
+
+const function Respond(Definition: Definition, CallIndex: number, ...: any)
+	const Handler = Definition.OnClientInvoke
+	local Results: Arguments = { n = 0 }
+
+	if Handler then
+		Results = table.pack(pcall(Handler, ...))
+	else
+		Results = { n = 2, false, "no OnClientInvoke was set" }
+	end
+
+	const Id = Definition.Id
+
+	if Id == nil then
+		return
+	end
+
+	const Ok, Problem = Wire.EncodeResults(Scratch, Definition, Results)
+
+	if not Ok then
+		warn(`[swiftpacket] call from the server failed: {Problem}`)
+	end
+
+	Wire.DeliverResponse(Reliable, Id, CallIndex, if Ok then Scratch else nil)
+end
+
+const function Resolve(Definition: Definition, CallIndex: number, Success: boolean, ...: any)
+	const Call = PendingCalls[CallIndex]
+
+	if Call == nil or Call.Definition ~= Definition then
+		Configuration.Warn(`[swiftpacket] ignored an unexpected response to {Definition.Name}`)
+
+		return
+	end
+
+	PendingCalls[CallIndex] = nil
+
+	if Success then
+		task.defer(Call.Thread, ...)
+	else
+		task.defer(Call.Thread, Wire.Unpack(Definition.TimeoutValues))
+	end
+end
+
+const function Dispatch()
+	const Values = Incoming.Values
+
+	for Index = 1, Incoming.Count do
+		const Definition = Incoming.Definitions[Index]
+		const CallIndex = Incoming.CallIndices[Index]
+		const First = Incoming.Starts[Index]
+		const Last = First + Incoming.Counts[Index] - 1
+
+		if CallIndex >= ResponseFlag then
+			Resolve(Definition, CallIndex - ResponseFlag, Incoming.Successes[Index], table.unpack(Values, First, Last))
+		elseif CallIndex ~= EventIndex then
+			ThreadPool.Defer(Respond, Definition, CallIndex, table.unpack(Values, First, Last))
+		elseif First == Last then
+			Definition.OnClientEvent:Fire(Values[First])
+		else
+			Definition.OnClientEvent:Fire(table.unpack(Values, First, Last))
+		end
+	end
+end
+
+const function Process(Source: buffer, Attached: { any }, Offset: number, StartInstances: number): number?
+	const Ok, Result = pcall(Wire.Decode, Incoming, Source, Attached, false, Offset, StartInstances)
+
+	if not Ok then
+		Wire.Release(Incoming)
+		warn(`[swiftpacket] could not read a batch from the server: {tostring(Result)}`)
+
+		return nil
+	end
+
+	Dispatch()
+	Wire.Release(Incoming)
+
+	return Result
+end
+
+const function Retry()
+	RetryScheduled = false
+
+	local Index = 1
+
+	while Index <= #HeldBatches do
+		const Entry = HeldBatches[Index]
+
+		if Registry.ById[Entry.MissingId] == nil then
+			Index += 1
+
+			continue
+		end
+
+		const MissingId = Process(Entry.Source, Entry.Instances, Entry.Offset, Entry.InstancesOffset)
+
+		if MissingId then
+			Entry.Offset = Incoming.StopOffset
+			Entry.InstancesOffset = Incoming.StopInstances
+			Entry.MissingId = MissingId
+			Index += 1
+		else
+			table.remove(HeldBatches, Index)
+		end
+	end
+end
+
+const function ScheduleRetry()
+	if RetryScheduled or HeldBatches[1] == nil then
+		return
+	end
+
+	RetryScheduled = true
+	task.defer(Retry)
+end
+
+const function Assign(Definition: Definition, Id: number)
+	const Previous = Definition.Id
+
+	if Previous and Registry.ById[Previous] == Definition then
+		Registry.ById[Previous] = nil
+	end
+
+	Definition.Id = Id
+	Registry.ById[Id] = Definition
+
+	const Bodies = Queued[Definition]
+	Queued[Definition] = nil
+
+	if Bodies then
+		for Index, Body in Bodies do
+			Deliver(Definition, Id, Body)
+		end
+	end
+
+	const Threads = Waiting[Definition]
+	Waiting[Definition] = nil
+
+	if Threads then
+		for Index, Thread in Threads do
+			task.spawn(Thread)
+		end
+	end
+
+	ScheduleRetry()
+end
+
+function Client.Register(Definition: Definition)
+	const Remote = ReliableRemote
+
+	if Remote == nil then
+		error("[swiftpacket] the client transport has not started", 0)
+	end
+
+	Definitions[Definition.Name] = Definition
+
+	const Id = Remote:GetAttribute(Definition.Name)
+
+	if type(Id) == "number" then
+		Assign(Definition, Id)
+
+		return
+	end
+
+	task.delay(5, function()
+		if Definition.Id == nil then
+			warn(`[swiftpacket] {Definition.Name} has no id after 5 seconds, define it on the server too`)
+		end
+	end)
+end
+
+const function Receive(Source: any, Instances: any)
+	if typeof(Source) ~= "buffer" then
+		return
+	end
+
+	const Attached = if type(Instances) == "table" then Instances else NoInstances
+	const MissingId = Process(Source, Attached, 0, 0)
+
+	if MissingId then
+		table.insert(HeldBatches, {
+			Source = Source,
+			Instances = Attached,
+			Offset = Incoming.StopOffset,
+			InstancesOffset = Incoming.StopInstances,
+			MissingId = MissingId,
+			ReceivedAt = os.clock(),
+		})
+	end
+end
+
+const function FireSegment(Remote: RemoteEvent | UnreliableRemoteEvent, Segment: Cursor.Cursor)
+	if Segment.Offset == 0 then
+		return
+	end
+
+	const Data, Attached = Cursor.Take(Segment)
+	Cursor.Reset(Segment)
+
+	if Remote:IsA("RemoteEvent") then
+		if Attached then
+			Remote:FireServer(Data, Attached)
+		else
+			Remote:FireServer(Data)
+		end
+	elseif Remote:IsA("UnreliableRemoteEvent") then
+		if Attached then
+			Remote:FireServer(Data, Attached)
+		else
+			Remote:FireServer(Data)
+		end
+	end
+end
+
+const function Flush()
+	const ReliableTarget = ReliableRemote
+	const UnreliableTarget = UnreliableRemote
+
+	if ReliableTarget == nil or UnreliableTarget == nil then
+		return
+	end
+
+	FireSegment(ReliableTarget, Reliable)
+
+	for Index = 1, UnreliableCount do
+		FireSegment(UnreliableTarget, Unreliable[Index])
+	end
+
+	UnreliableCount = 1
+end
+
+const function Expire()
+	const Now = os.clock()
+
+	for CallIndex, Call in PendingCalls do
+		if Now >= Call.Deadline then
+			PendingCalls[CallIndex] = nil
+			task.defer(Call.Thread, Wire.Unpack(Call.Definition.TimeoutValues))
+		end
+	end
+
+	for Index = #HeldBatches, 1, -1 do
+		const Entry = HeldBatches[Index]
+
+		if Now - Entry.ReceivedAt >= Configuration.HoldSeconds then
+			table.remove(HeldBatches, Index)
+			warn(
+				`[swiftpacket] dropped messages after the unknown packet id {Entry.MissingId}, define it on the client too`
+			)
+		end
+	end
+end
+
+const function FindRemote(Root: Instance, Name: string): Instance
+	const Remote = Root:WaitForChild(Name, 10)
+
+	if Remote == nil then
+		error(`[swiftpacket] could not find {Root:GetFullName()}.{Name}, require swiftpacket on the server first`, 0)
+	end
+
+	return Remote
+end
+
+function Client.Start(Root: Instance)
+	if ReliableRemote then
+		return
+	end
+
+	const ReliableInstance = FindRemote(Root, "Reliable")
+	const UnreliableInstance = FindRemote(Root, "Unreliable")
+
+	if not ReliableInstance:IsA("RemoteEvent") or not UnreliableInstance:IsA("UnreliableRemoteEvent") then
+		error(`[swiftpacket] the remotes under {Root:GetFullName()} have the wrong classes`, 0)
+	end
+
+	ReliableRemote = ReliableInstance
+	UnreliableRemote = UnreliableInstance
+
+	ReliableInstance.OnClientEvent:Connect(Receive)
+	UnreliableInstance.OnClientEvent:Connect(Receive)
+
+	ReliableInstance.AttributeChanged:Connect(function(Name: string)
+		const Definition = Definitions[Name]
+		const Id = ReliableInstance:GetAttribute(Name)
+
+		if Definition and type(Id) == "number" then
+			Assign(Definition, Id)
+		end
+	end)
+
+	RunService.Heartbeat:Connect(function(DeltaTime: number)
+		Expire()
+		Elapsed += DeltaTime
+
+		if Elapsed >= Configuration.FlushRate then
+			Elapsed %= Configuration.FlushRate
+			task.defer(Flush)
+		end
+	end)
+end
+
+return Client

package/src/configuration.luau

@@ -0,0 +1,74 @@
+--!strict
+--!optimize 2
+
+--[[
+	Author: @skaterstudios
+	Website: skaterstudios.com
+	GitHub: github.com/skatingii/SwiftPacket
+	Discord Server: discord.gg/skaterstudios
+
+	Licensed under the MIT License. You may use, modify, redistribute and sell
+	this system freely, as long as this notice and the LICENSE file stay with it.
+]]
+
+const RunService = game:GetService("RunService")
+
+export type Options = {
+	Logging: boolean?,
+	IncomingBytesPerSecond: number?,
+	UnreliableByteLimit: number?,
+}
+
+const Configuration = {
+	Logging = RunService:IsStudio(),
+	IncomingBytesPerSecond = 64000,
+	UnreliableByteLimit = 900,
+	FlushRate = 1 / 60,
+	MessageCost = 8,
+	HoldSeconds = 10,
+	CallCapacity = 32768,
+}
+
+const OptionTypes: { [string]: string } = {
+	Logging = "boolean",
+	IncomingBytesPerSecond = "number",
+	UnreliableByteLimit = "number",
+}
+
+function Configuration.Configure(Options: { [string]: any })
+	for Key, Value in Options do
+		const Expected = OptionTypes[Key]
+
+		if Expected == nil then
+			error(`[swiftpacket] unknown option {Key}`, 2)
+		end
+
+		if type(Value) ~= Expected then
+			error(`[swiftpacket] option {Key} must be a {Expected}, got {typeof(Value)}`, 2)
+		end
+	end
+
+	const Logging = Options.Logging
+	const IncomingBytesPerSecond = Options.IncomingBytesPerSecond
+	const UnreliableByteLimit = Options.UnreliableByteLimit
+
+	if Logging ~= nil then
+		Configuration.Logging = Logging
+	end
+
+	if IncomingBytesPerSecond ~= nil then
+		Configuration.IncomingBytesPerSecond = math.max(IncomingBytesPerSecond, 1000)
+	end
+
+	if UnreliableByteLimit ~= nil then
+		Configuration.UnreliableByteLimit = math.clamp(UnreliableByteLimit, 64, 900)
+	end
+end
+
+function Configuration.Warn(Message: string)
+	if Configuration.Logging then
+		warn(Message)
+	end
+end
+
+return Configuration