{"id":"xopoiii/blinkblox","name":"blinkblox","scope":"xopoiii","platform":"roblox","description":"The BlinkBlox compiler as a library: a schema in, the generated network modules out","version":"1.4.0","latest":"1.4.0","versions":["1.0.1","1.0.2","1.0.3","1.1.1","1.1.2","1.1.3","1.1.4","1.1.5","1.1.6","1.1.7","1.1.8","1.2.0","1.2.1","1.3.0","1.3.1","1.3.2","1.3.3","1.3.4","1.3.5","1.3.6","1.3.9","1.3.10","1.4.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"8eb8740e8755f16c3eec2c898e86569ee7f699f3fc79b53bdf5e7cefccf91fff","likes":0,"downloads":0,"install":"forest install xopoiii/blinkblox","url":"https://forest.dev/p/roblox/xopoiii/blinkblox","files":"https://api.forest.dev/ai/package/roblox/xopoiii/blinkblox/files","readme":"<div align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/XopoIII/BlinkBlox/main/docs/src/assets/logo.png\" alt=\"BlinkBlox logo\" width=\"160\">\n\n# BlinkBlox\n\n**An IDL compiler for Roblox buffer networking whose generated server is safe to point at the open internet.**\n\n[![License](https://img.shields.io/github/license/XopoIII/BlinkBlox?style=flat-square&color=%23a350af)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/XopoIII/BlinkBlox?style=flat-square&color=%23a350af)](https://github.com/XopoIII/BlinkBlox/releases/latest)\n[![Docs](https://img.shields.io/badge/docs-xopoiii.github.io-a350af?style=flat-square)](https://xopoiii.github.io/BlinkBlox/)\n\n[Documentation](https://xopoiii.github.io/BlinkBlox/) ·\n[Quick start](https://xopoiii.github.io/BlinkBlox/getting-started/quick-start/) ·\n[Changelog](CHANGELOG.md)\n\n</div>\n\nYou describe your events and functions, and what they carry, in a `.blink` schema. The compiler\ngenerates a server module and a client module in plain Luau: functions and `buffer` calls, with no\nmetatables and no runtime library beside them. They pack every call into one buffer per frame, check\neverything a client sends before your code sees it, and keep working when a client is hostile.\n\n```blink\nevent Damage {\n\tFrom: Client,\n\tType: Reliable,\n\tCall: SingleSync,\n\tRate: 10,\n\tData: struct { Target: Instance(Humanoid), Amount: u8(1..100) }\n}\n```\n\n```luau\n-- Server: the listener runs only after the rate limit has passed and Amount is 1..100.\nNet.Damage.On(function(Player, Hit)\n\tCombat.Apply(Player, Hit.Target, Hit.Amount)\nend)\n\n-- Client\nNet.Damage.Fire({ Target = Humanoid, Amount = 25 })\n```\n\n## Why BlinkBlox\n\n- **Bounded inbound traffic.** Packet size, the number of events in a packet and the number of\n  instance references are capped before anything is parsed. Each player also gets a byte budget.\n- **Rate limits per player and per event.** Set `Rate` and `Burst` on an event, or a default for\n  the whole schema, and `Concurrency` on a function to bound the calls still running. Refused events\n  go to a handler you provide, and nobody is kicked automatically.\n- **Hostile input costs the attacker, not the server.** Every length is checked before the read and\n  the allocation it pays for. A malformed event ends its packet without throwing: the events\n  before it are delivered, and the failure goes to a handler you provide.\n- **A missing Instance costs one event, not the packet.** Under StreamingEnabled an Instance the\n  sender had often is not there on arrival. That event alone is refused and reported; the rest of the\n  packet is still read, at no cost to decoding when everything arrives.\n- **Mistakes other libraries leave silent are named.** A second copy of the module in an Actor errors\n  at require, a send made with `:` instead of `.` says so, a function's listener replaced by a second\n  `.On` warns, a client left waiting for a server that never started says why, and a file of events\n  imported twice warns at compile time. The client's queues are capped as the server's are.\n- **Mismatched builds refuse each other.** A client and a server built from different schemas stop\n  at startup instead of decoding one event as another.\n- **The Roblox types games send.** `Vector2`, `UDim`, `UDim2`, `NumberRange`, `ColorSequence`,\n  `NumberSequence`, `TweenInfo`, `PhysicalProperties`, `Rect`, `Region3`, `Ray`, and a Roblox\n  enum's items as `Enum(Material)` -- sent by `Value`, never by list position, which can differ\n  between client and server during an engine rollout. What a constructor would throw on, or let a\n  NaN through, is refused on arrival.\n- **Small on the wire.** Booleans, optional flags, enum values and tags share a bitfield, and\n  `boolean[]` packs eight to a byte. A length is sent relative to its range, a short one in a single\n  varint byte, `CFrame<quat>` fits a rotation in 7 bytes, and\n  `u24`, `i24` and `f24` fill the gap between 16 and 32 bits, so `vector<f24>` is 9 bytes instead of\n  12. A float with a step and a range is quantized: `f32<0.01>(-1..1)` is one byte. An unreliable event\n  that cannot fit is refused at compile time.\n- **Few remote calls.** A `FireAll` goes to every player in one `FireAllClients`, streams to\n  everyone share one packet a frame, and `BatchUnreliable` gathers a frame's unreliable events the\n  same way. A client cuts its batch to fit the server's limits, so an honest player is never refused,\n  and sends at most 60 times a second, since every remote call costs about 11 bytes of its own.\n- **An outbound budget.** Give each player a byte budget for what the server sends, and mark the\n  events and streams that may wait with `Priority: Low`; nothing else is ever held back.\n- **Tooling.** The CLI has watch mode and `@profile` builds that keep debug remotes out of release,\n  `--check --json` reports every diagnostic as JSON for editors and AI assistants, and `--verify`\n  fails a pre-commit hook or CI step when the committed modules no longer match the schema. The generated\n  modules pass their own `--!strict`, and keep their types under the new type solver however many\n  events the schema has. You also get TypeScript definitions and a Studio plugin with\n  live diagnostics.\n\n## Performance\n\nSpeed is not the reason to choose BlinkBlox. A reader written by hand for one event can be as fast as\nanything generated for it, and\n[Compared with hand-written buffers](https://xopoiii.github.io/BlinkBlox/guides/hand-written-buffers/)\nsays when that is the better choice. The numbers are here to compare tools that do the same job, and\nto hold each release to the one before it: nothing may get slower.\n\nEach tool fires 1000 events a frame from client to server, on\n[LuneBlox](https://github.com/XopoIII/LuneBlox) -- the Luau version and flags Roblox runs, without\nRoblox -- on an Intel Core i7-13700K with BlinkBlox 1.4.0, on 2026-11-14. Each figure is the median\nof three runs, every tool in a process of its own. Blink is the original project BlinkBlox forked\nfrom, at its last release, 0.18.9. \"Send\" is a frame's thousand fires and the flush into a packet,\ninterpreted, as most players' clients run it; \"decode\" is the server decoding them, natively\ncompiled, as a Roblox server runs it; bytes are one event before compression.\n\n| Tool | 1000 booleans: send / decode | 100 entities: send / decode | Bytes, booleans / entities |\n|---|---|---|---|\n| **BlinkBlox** | **16.8** / **6.0 ms** | **12.6** / **3.2 ms** | **127** / **601** |\n| Blink | 30.1 / 10.9 ms | 13.1 / 22.9 ms | 1003 / 603 |\n| zap | 69.1 / 11.7 ms | 34.7 / 22.5 ms | 1003 / 603 |\n| ByteNet | 58.3 / 51.7 ms | 43.9 / 44.6 ms | 1003 / 603 |\n| Packet | 56.8 / 52.4 ms | 41.6 / 57.0 ms | 1003 / 603 |\n| QuickNet | 17.1 / 6.7 ms | 17.9 / 9.8 ms | 128 / 603 |\n| Warp | 40.8 / 11.9 ms | 72.8 / 28.7 ms | 128 / 602 |\n| Satset | 38.0 / 9.3 ms | 47.7 / 38.7 ms | **127** / 602 |\n\nBlinkBlox packs a frame's consecutive events of one id under a shared three-byte header instead of a\nbyte of index each, which is where the smallest packets' last spare byte was going: a thousand\nbooleans cost 127.01 bytes an event to Satset's 127.01, a hundred entities 601.01 where every other\ntool pays 602 or 603, and a run of events carrying Instances costs three bytes of header where Blink,\nzap, Packet and Warp pay a byte of index each.\n\nTwo of those rows read faster than they are, each for a stated reason. **Blink and zap generate\ntheir client modules with `--!native`**, and a client that can compile natively runs them that way;\nBlinkBlox's generated client asks for no such thing, because Roblox compiles client code natively on\nAndroid alone, and every other device logs `Native code generation is not supported on this device`\nonce per module that asks. Most players' clients run code interpreted, so BlinkBlox's client figures\nare what a player's device actually pays, while Blink's and zap's native rows assume an Android\nclient -- and even interpreted, BlinkBlox's client is the fastest sender on every bench. Its server\nmodule does ask for native compilation, as every Roblox server supports it, which is what the decode\ncolumn runs. **Warp encodes nothing when an event is fired** -- it queues the value and serialises\nthe whole queue at its flush, so its send cost is in the flush column the table folds in, and its\nnear-zero fire time is not a faster encoder.\n\nThe gap depends on the payload: against zap the server decodes 1.9 times faster on booleans and 7.1\ntimes on entities, and QuickNet is close behind on booleans.\n\nThe frame rates in Studio, a server sending to fifty players, unreliable inputs, a schema of 128\nevents, the bandwidth and the methodology are in\n[Benchmarks](https://xopoiii.github.io/BlinkBlox/guides/benchmarks/) and\n[`benchmark/Benchmarks.md`](benchmark/Benchmarks.md). What 1.0.0 changed is in\n[What's new in 1.0](https://xopoiii.github.io/BlinkBlox/guides/whats-new/).\n\n## Where it comes from\n\nBlinkBlox is a maintained fork of [Blink](https://github.com/1Axen/blink). Upstream froze this line\nof the compiler and began a rewrite. It left reported defects open, including an unbounded parse of\na hostile client buffer. This fork fixes them and continues from `v0.18.8`. See\n[Migrating from Blink](https://xopoiii.github.io/BlinkBlox/guides/migrating-from-blink/).\n\n## Install\n\n```sh\nrokit add XopoIII/BlinkBlox blinkblox             # CLI through Rokit\npesde add xopoiii/blinkblox --dev --target lune   # or through pesde\n```\n\nBinaries for every platform, and the Studio plugin (`blinkblox-plugin.rbxm`), are attached to each\n[release](https://github.com/XopoIII/BlinkBlox/releases/latest). The plugin is also on the Creator\nStore as **BlinkBlox Editor**. Code that runs the compiler inside Roblox -- a plugin, an in-Studio\nbuild step -- can take it from Wally as `xopoiii/blinkblox`. See [Installation](https://xopoiii.github.io/BlinkBlox/getting-started/installation/).\n\n## Contributing\n\n```sh\nrokit install              # toolchain\nsh scripts/run-tests.sh    # test suite\ncd docs && npm install && npm run dev   # documentation site\n```\n\n`CLAUDE.md` describes the architecture and the gates that CI and the git hooks run.\n\n## License\n\nMIT. See [LICENSE](LICENSE). Originally written by [Axen](https://github.com/1Axen); this fork\ncontinues from v0.18.8 and keeps the upstream copyright.\n","readmeTruncated":false}