Constella documentation
Reference pages for every module in Constella v0.3.7.
Architecture
| Page |
Covers |
| Core / App |
Services and controllers, dependency order, Init/Start/Stop, injection, client/server boundaries |
| Architecture |
Design principles, module dependencies, naming conventions, testing approach |
| Game layout |
Where a game’s services, controllers, shared code and server-only config go, with a starter template |
Utilities
| Page |
Covers |
| Signal |
Custom events with deterministic dispatch and error isolation |
| Cleanup |
Owning and disposing connections, instances, threads and objects |
| State |
Reactive values, computed state, batching and UI bindings |
| Promise |
Async chaining, cancellation, timeouts and retries |
| Random |
Weighted rolls, loot tables and luck, with the math written out |
| Debug |
Structured logging and metrics |
Game systems
| Page |
Covers |
| Network |
Server-owned remotes: validation, rate limits, payload caps and authorization. Includes client vs server API differences |
| Replication |
Sending State from server to client, with explicit authorization |
| Component |
Behaviour attached to CollectionService tags |
| Pool |
Bounded object reuse |
| Zone |
Enter/exit detection for players and parts |
| Data |
Player profiles on ProfileStore |
Project
- Benchmarks: measured results against sleitnick/signal, sleitnick/trove and plain Roblox approaches.
- Roadmap: what’s done and what comes next.
- Changelog
- Contributing: setup, tests and conventions.
Known limitations
- Data needs ProfileStore in production. Every CI run tests it on real DataStores on real Roblox servers, including a player moving to a second server, but it hasn’t yet run in a live game under heavy load.
MemoryAdapter isn’t persistent.
- The Play-mode integration tests run in Studio only. They need a real client. The rest of the suite runs on a Roblox server in CI on every push.
- State dependencies are explicit. Use
State.computed({ a, b }, fn); there’s no automatic tracking. Compute functions and batches must not yield.
- Network payload sizes are estimates, not Roblox’s exact wire sizes. Validation checks the shape of a request; your handlers still decide what’s allowed in the game.
- Zone checks points, not volumes. Each zone has its own Heartbeat connection.
- Real clients are tested up to 8 at once, in Studio on one machine: load phases with engine-measured traffic (Benchmarks). A soak harness for multi-hour runs is included, but no multi-hour result is published yet. 50 real clients, rejoins and live-game network conditions (latency, packet loss) have not been measured; larger player counts are tested with stand-in players.
- The Promise unhandled-rejection reporter applies to every promise (
Promise.setUnhandledRejectionHandler).
- Performance is measured, not assumed. Benchmarks cover every module plus a 50-player server tick, against sleitnick/signal, LemonSignal, Trove, Janitor, evaera’s Promise and hand-written baselines. Every pull request reruns them on a Roblox server against the code it changes and fails if a case gets measurably slower. Where Constella loses (Signal against sleitnick/signal, Replication’s extra CPU over a plain RemoteEvent), the numbers say so. All results so far come from Constella’s author; reproducing them takes one command. No comparisons have been made with Knit, Fusion or other frameworks.