{"id":"minecoiii2/bitnet","name":"bitnet","scope":"minecoiii2","platform":"roblox","description":"Lightning-fast buffer-based networking library for Roblox","version":"3.3.0","latest":"3.3.0","versions":["3.0.0","3.0.1","3.2.0","3.3.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"410b52e9985552b387347c028e04ecefa6a48ae1efa55f2aff529f3ab024d455","likes":0,"downloads":0,"install":"forest install minecoiii2/bitnet","url":"https://forest.dev/p/roblox/minecoiii2/bitnet","files":"https://api.forest.dev/ai/package/roblox/minecoiii2/bitnet/files","readme":"# BitNet\n\nLightning-fast, buffer-based networking library for Roblox.\n\nBitNet replaces your RemoteEvents and RemoteFunctions with events and functions that you define in a single shared `Networking` module. They work like the Roblox ones you already know (`FireServer`, `OnServerEvent`, `InvokeServer`...), except each one is locked to a **schema**: a description of exactly what it sends.\n\n```lua\nHit = RemoteEvent({\n\tArgs = args(struct({ target = player, damage = u16, critical = bool })),\n})\n```\n\nBecause the server and client both know that schema, only the values go over the network. The keys and type information are never sent. This `Hit` fire costs 3 bytes and 1 bit, plus a 1-byte event id.\n\n## Why BitNet\n\n- **Smaller packets.** Values are written into a buffer at the exact size you choose: a `u8` is 1 byte, a `bool` is 1 bit\n- **Speed.** Encoding and decoding are among the fastest out there (see [Benchmark](#benchmark))\n- **Exploit-resistant by default.** The server strictly decodes everything clients send. Malformed or out-of-bounds data is rejected before it reaches your handlers, and `OnRejected` tells you who sent it.\n- **Typed in Luau.** Types come straight from the schema, so `FireServer` arguments and `OnServerEvent` parameters are type-checked in your editor with no extra steps.\n- **Built-in extras.** Rate limiting, unreliable events, type-validation, sending only to nearby players, Zstd compression and more.\n\n## Benchmark\n\n**BitNet offers the best balance of speed and payload size:** only 2 bytes behind *Lync* payloads, while running up to 2.4x faster.\n\n- Primitive: A single u8\n- Medium: Struct containing integers, strings and an array\n- Complex: Struct containing integers, strings, nested structs, nested arrays\n\n| Module | Round trip: primitive / medium / complex | Payload: primitive / medium / complex |\n|---|---:|---:|\n| **BitNet** | 272 / **781** / **1,542 ns** | 1 / 36 / 79 B |\n| Packet | 413 / 978 / 2,797 ns | 1 / 37 / 81 B |\n| Lync | 211 / 1,119 / 3,659 ns | **1 / 34 / 77 B** |\n| Jolt | 356 / 1,109 / 3,797 ns | 2 / 64 / 230 B |\n| ByteNet | **178** / 2,332 / 7,162 ns | 1 / 41 / 83 B |\n| NetRay | 1,067 / 4,462 / 18,907 ns | 2 / 67 / 306 B |\n| BridgeNet2 | — | 9 / 89 / 468 B |\n\n## Installation\n\nBitNet comes with a **Networking** template module. It already has every BitNet type, function and helper set up, ready for your remotes.\n\n**Manual:** download `BitNet.rbxm` and `Networking.rbxm` from [Releases](https://github.com/minecoiii2/bitnet/releases) and insert both into `ReplicatedStorage`.\n\n**Wally**\n```toml\n[dependencies]\nBitNet = \"minecoiii2/bitnet@3.2.0\"\n```\nThen copy [`Networking.luau`](Networking.luau) into your project and change its require to point at your packages folder, e.g. `ReplicatedStorage.Packages.BitNet`.\n\n## Quick start\n\nEvery event and function goes in the table that `Networking` returns. The server and client both require this one module, so everything registers in the same order on both sides.\n\n```lua\n-- ReplicatedStorage.Networking\nconst BitNet = require(ReplicatedStorage.BitNet)({})\n...\n\nlocal Islands = enumFromKeys(IslandDictionary)\n\nreturn {\n\tChat = {\n\t\tSend = RemoteEvent({\n\t\t\tArgs = args(string, u16),\n\t\t}),\n\t\tReceive = RemoteEvent({\n\t\t\tArgs = args(player, string, u16),\n\t\t}),\n\n\t\tGetAllChats = RemoteFunction({\n\t\t\tArgs = args(nothing),\n\t\t\tReturns = args(\n\t\t\t\tcompress(array(\n\t\t\t\t\tstruct({\n\t\t\t\t\t\tSender = player,\n\t\t\t\t\t\tAt = u48,\n\t\t\t\t\t\tMessage = string,\n\t\t\t\t\t\tWasFiltered = bool,\n\t\t\t\t\t})\n\t\t\t\t))\n\t\t\t)\n\t\t}),\n\t},\n\n\tTeleportToIsland = RemoteEvent({\n\t\tArgs = args(Islands, uuid, u32),\n\t}),\n}\n```\n\n```lua\n-- Server\nconst Networking = require(ReplicatedStorage.Networking)\n\nNetworking.Chat.Send.OnServerEvent:Connect(function(player, message, channel)\n\tNetworking.Chat.Receive:FireAllClients(player, message, channel)\nend)\n\nNetworking.Chat.GetAllChats:SetServerCallback(function(player)\n\treturn AllReceivedChats\nend)\n```\n\n```lua\n-- Client\nconst Networking = require(ReplicatedStorage.Networking)\n\nNetworking.Chat.Receive.OnClientEvent:Connect(function(player, message, channel)\n\tprint(message, 'sent by', player, 'in channel', channel)\nend)\n\nNetworking.Chat.Send:FireServer(\"hello\", 1)\n```\n\n## Types\n\n| Type | Bytes | Notes |\n| ---- | ----- | ----- |\n| `u8` `u16` `u24` `u32` `u48` | 1–6 | Unsigned integers |\n| `i8` `i16` `i24` `i32` `i48` | 1–6 | Signed integers |\n| `f24` `f32` `f64` | 3, 4, 8 | `number` is `f64` |\n| `bool` | 1 bit | Packed |\n| `string` `buffer` | 1–5 + length | |\n| `uuid` | 16 | Canonical 36-character lowercase form |\n| `vec2` `vec3` | 8, 12 | |\n| `vec2i16(scale?)` `vec3i16(scale?)` | 4, 6 | Fixed point, ±327 studs at the default scale of 100 |\n| `cframe` `cframelong` | 18, 24 | `cframe` is lossy while `cframelong` isn't |\n| `color3` | 3 | 8 bits per channel |\n| `brickcolor` `numberrange` `udim` `udim2` | 2, 8, 4, 8 | |\n| `numbersequence` `colorsequence` | varies | |\n| `player` | 1 | Sent as u8. A player who left more than 5 seconds ago arrives as nil |\n| `ref` `unknown` | 0 | Sent next to the buffer as normal Roblox values |\n| `auto` | 1 + value | Picks an encoding at runtime |\n| `nothing` | 0 | Always nil |\n\nThe narrow types (`u24`, `i24`, `f24`, `u48`, `i48`, `vec*i16`, `cframe`) save bytes but cost a bit of CPU. In the Networking template, `any` is `ref`.\n\n**Combinators**\n- `struct(format)`: table with fixed keys\n- `array(value)`: array of one type\n- `map(key, value)`: dictionary (up to 16,383 entries)\n- `optional(value)`: value or nil\n- `instance(...className)`: an Instance. `instance()` accepts any class, `instance(\"BasePart\", \"Model\")` only those. Always call it, even with no classes\n- `tuple(...)`: multiple arguments\n- `enum(Enum.X)`: a Roblox EnumItem\n- `enumFromKeys(t)` / `enumFromValues(t)`: string from a known set, sent as an index\n- `compress(value, level?)`: Zstd-compresses the value when that makes it smaller\n\n## Events\n\n`RemoteEvent(options)` in the template, `BitNet.event(options)` without it.\n\n| Option | Default | Description |\n| ------ | ------- | ----------- |\n| `Args` | required | Payload schema |\n| `Reliable` | `true` | Use the reliable or unreliable channel |\n| `RateLimit` | `nil` | `{ calls, per }` limit on fires per client |\n| `ValidateOutgoing` | `Constants.VALIDATE_OUTGOING_TYPES` | Check values against the schema before sending |\n| `ValidateAcceptNonFinite` | `Constants.VALIDATE_DEFAULT_REJECT_NON_FINITE` | Let NaN and inf through incoming validation |\n\n**Methods:**\n- `:FireServer(...)`\n- `:FireClient(player, ...)`\n- `:FireAllClients(...)`\n- `:FireClientsStreamed(position, range, ...)`: Send to players within range\n- `:FireClientsStreamedWithExclusion(position, range, player, ...)`: Same, excluding one player\n\n**Listening:**\n- `.OnServerEvent` gives `(player, ...)`\n- `.OnClientEvent` gives `(...)`\n\nOn the client, fires that arrive before anything is connected are queued (up to 256) and delivered once something connects.\n\n## Funcs\n\n`RemoteFunction(options)` in the template, `BitNet.func(options)` without it.\n\n| Option | Default | Description |\n| ------ | ------- | ----------- |\n| `Args` | required | Request schema |\n| `Returns` | required | Response schema |\n| `Timeout` | `Constants.DEFAULT_FUNC_TIMEOUT` | Yield timeout. `0` or `math.huge` waits forever |\n| `RateLimit` | `nil` | `{ calls, per }` limit on invokes per client |\n| `ValidateOutgoing` | `Constants.VALIDATE_OUTGOING_TYPES` | Check values against the schema before sending |\n| `ValidateAcceptNonFinite` | `Constants.VALIDATE_DEFAULT_REJECT_NON_FINITE` | Let NaN and inf through incoming validation |\n\n**Methods:**\n- `:InvokeServer(...)`\n- `:InvokeClient(player, ...)`\n- `:SetServerCallback(fn)`\n- `:SetClientCallback(fn)`\n\nIf the other side can't answer (its callback errors, it has no callback, or `RateLimit` refused the call), the invoke errors right away with the reason instead of waiting for `Timeout`.\n\n## Configuration\n\n`require(BitNet)` returns a function that starts BitNet. Call it once, at the top of `Networking`, with a table of overrides, or `{}` to keep the defaults:\n\n```lua\n-- ReplicatedStorage.Networking\nconst BitNet = require(ReplicatedStorage.BitNet)({\n\tDEFAULT_FUNC_TIMEOUT = 10,\n\tVALIDATE_OUTGOING_TYPES = true,\n})\n```\n\nOther scripts get the same BitNet by calling it with no config: `require(ReplicatedStorage.BitNet)()`. Require `Networking` before doing that, otherwise BitNet starts with the defaults and `Networking`'s own call errors.\n\n| Constant | Default | Description |\n| -------- | ------- | ----------- |\n| `DEFAULT_FUNC_TIMEOUT` | `7` | Seconds a RemoteFunction waits for a response. Overridden per function by `Timeout` |\n| `VALIDATE_OUTGOING_TYPES` | Studio only | Check values against their schema before sending. Overridden per endpoint by `ValidateOutgoing` |\n| `VALIDATE_INCOMING_TYPES` | Server only | Strictly decode incoming data and reject malformed / malicious frames |\n| `VALIDATE_DEFAULT_REJECT_NON_FINITE` | `true` | Reject NaN and inf in incoming data. Overridden per endpoint by `ValidateAcceptNonFinite` |\n\nEvery other value in BitNet's `constants` module can be overridden the same way.\n\n## Important Notes\n\n- **Reliable and unreliable events aren't ordered relative to each other.** If a reliable event is fired after an unreliable one, either one can be received first.\n- **`:FireAllClients` and `:FireClient` are batched separately.** Within a frame, order is only kept between fires sent the same way, so a `:FireAllClients` can be received before a `:FireClient` that was called earlier. If two fires must arrive in order, send them the same way.\n\n## Trivia\n\n- BitNet was originally meant to be a ByteNet fork, but it ended up turning into a full rewrite.\n\n## License\n\nMIT\n","readmeTruncated":false}