{"id":"layfate/constella","name":"constella","scope":"layfate","platform":"roblox","description":"A modular Luau toolkit for Roblox: app lifecycle, signals, cleanup, reactive state, secure networking, components, pools, zones, promises, player data and replication.","version":"0.4.0","latest":"0.4.0","versions":["0.3.0","0.3.1","0.3.2","0.3.3","0.3.4","0.3.5","0.3.6","0.3.7","0.4.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"2381add87d9a51dccf00dbd7f27ab4e0eb2b8740353b2afbb139d354a5f2628a","likes":0,"downloads":0,"install":"forest install layfate/constella","url":"https://forest.dev/p/roblox/layfate/constella","files":"https://api.forest.dev/ai/package/roblox/layfate/constella/files","readme":"<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/Layfate/Constella/main/assets/logo-512.png\">\n    <img src=\"https://raw.githubusercontent.com/Layfate/Constella/main/assets/logo-512-panel.png\" alt=\"Constella logo\" width=\"160\">\n  </picture>\n</p>\n\n<h1 align=\"center\">Constella</h1>\n\n<p align=\"center\">\n  <b>A modular, strictly typed Luau toolkit for Roblox.</b><br>\n  Use one utility on its own, or build your whole game on it.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/Layfate/Constella/actions/workflows/ci.yml\"><img alt=\"CI\" src=\"https://github.com/Layfate/Constella/actions/workflows/ci.yml/badge.svg?branch=main\"></a>\n  <a href=\"https://github.com/Layfate/Constella/blob/main/LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-7c6cf0\"></a>\n  <a href=\"https://github.com/Layfate/Constella/blob/main/CHANGELOG.md\"><img alt=\"Latest release\" src=\"https://img.shields.io/github/v/release/Layfate/Constella?label=version&color=4fb4f0\"></a>\n  <img alt=\"Luau: strict\" src=\"https://img.shields.io/badge/luau-strict-5b7cfa\">\n  <img alt=\"Platform: Roblox\" src=\"https://img.shields.io/badge/platform-Roblox-3b3f63\">\n</p>\n\n<p align=\"center\">Made by <b>Zense</b></p>\n\n📖 **[Documentation → docs/](https://github.com/Layfate/Constella/blob/main/docs/README.md)**<br>\n🧪 **[Examples → one script per module](https://github.com/Layfate/Constella/tree/main/examples)**<br>\n🗺️ **[Roadmap](https://github.com/Layfate/Constella/blob/main/docs/Roadmap.md)**\n\n```toml\n# wally.toml\n[dependencies]\nConstella = \"layfate/constella@0.4.0\"\n```\n\nAlso available as a ready-to-insert model file (**[download `Constella.rbxm`](https://github.com/Layfate/Constella/releases/latest)**) or with pesde (`pesde add zense/constella`). See [Installation](#installation).\n\n- **Use only what you need.** Every module loads on first use. `require(Constella.Signal)` loads Signal and nothing else, and no system starts unless you start it.\n- **Safe networking by default.** Every client request passes rate limiting, payload caps, schema validation and your authorization check before your code runs. Clients only ever see generic error codes; the details stay on the server.\n- **An explicit architecture.** Apps start services in dependency order, catch duplicates, missing dependencies and cycles before any code runs, keep client and server code apart, and roll back cleanly if startup fails. No globals, no singletons, no auto-discovery.\n- **Player data that fails closed.** Migrations, template reconciliation and session-loss handling sit on top of ProfileStore's session locking. A failed load never overwrites saved data.\n- **Tested and measured.** Unit tests, Data failure simulations, tests against real ProfileStore, Play-mode integration tests with a hostile client against real remotes, load tests with real clients and engine-measured traffic, a soak harness for multi-hour runs, and published [benchmarks](https://github.com/Layfate/Constella/blob/main/docs/Benchmarks.md) against other libraries and hand-written baselines, including where Constella is slower. One script reproduces them on your machine.\n\n> [!NOTE]\n> `Constella.Data` runs on [ProfileStore](https://github.com/MadStudioRoblox/ProfileStore), which you install separately. Every CI run tests it on real DataStores on real Roblox servers, including a player moving to a second server. See [Data](https://github.com/Layfate/Constella/blob/main/docs/Data.md) for exactly what's verified.\n\n## Modules\n\n| | Module | What it does |\n| --- | --- | --- |\n| **Architecture** | [Core / App](https://github.com/Layfate/Constella/blob/main/docs/Core.md) | Services and controllers with dependency-ordered Init/Start/Stop and injection |\n| **Utilities** | [Signal](https://github.com/Layfate/Constella/blob/main/docs/Signal.md) | Custom events with deterministic dispatch and error isolation |\n| | [Cleanup](https://github.com/Layfate/Constella/blob/main/docs/Cleanup.md) | Owns connections, instances, threads and promises, and disposes them together |\n| | [State](https://github.com/Layfate/Constella/blob/main/docs/State.md) | Reactive values, computed state, batching and UI bindings |\n| | [Promise](https://github.com/Layfate/Constella/blob/main/docs/Promise.md) | Async chaining, cancellation, timeouts and retries |\n| | [Random](https://github.com/Layfate/Constella/blob/main/docs/Random.md) | Weighted rolls, loot tables and luck, with the math documented |\n| | [Debug](https://github.com/Layfate/Constella/blob/main/docs/Debug.md) | Structured logging and metrics, with almost no cost when switched off |\n| **Game systems** | [Network](https://github.com/Layfate/Constella/blob/main/docs/Network.md) | Server-owned remotes with validation, rate limits and payload caps; typed contracts shared by server and client |\n| | [Replication](https://github.com/Layfate/Constella/blob/main/docs/Replication.md) | Server→client State, only when the server explicitly shares it |\n| | [Component](https://github.com/Layfate/Constella/blob/main/docs/Component.md) | Behaviour attached to CollectionService tags |\n| | [Pool](https://github.com/Layfate/Constella/blob/main/docs/Pool.md) | Bounded object reuse for projectiles and effects |\n| | [Zone](https://github.com/Layfate/Constella/blob/main/docs/Zone.md) | Enter/exit detection for players and parts |\n| | [Data](https://github.com/Layfate/Constella/blob/main/docs/Data.md) | Player profiles on ProfileStore *(server only)* |\n\n## Compared with other libraries\n\nEach module has a well-known alternative. Constella's case is that all 13 share one set of rules (strict types, explicit lifetimes, loud errors, no globals) and are tested together on real Roblox servers. If you only need one piece, the specialist library is often the right pick.\n\n| Job | Common choice | Constella | Main difference |\n| --- | --- | --- | --- |\n| **Secure remotes** | Plain RemoteEvents; Zap, ByteNet or Blink | [Network](https://github.com/Layfate/Constella/blob/main/docs/Network.md) | **Security first:** every client request is rate limited, size capped, schema checked and authorized before your handler runs, and clients only see generic error codes. Zap, ByteNet and Blink focus on compact serialization and bandwidth instead. The two approaches can be combined |\n| Player data | ProfileStore directly | [Data](https://github.com/Layfate/Constella/blob/main/docs/Data.md) | Built **on** ProfileStore: adds migrations, template reconciliation, `Changed` signals, kick-on-session-loss and a shutdown budget that waits for every save |\n| App structure | Knit | [Core](https://github.com/Layfate/Constella/blob/main/docs/Core.md) | Explicit apps instead of global singletons: dependency order, cycle and environment checks before any code runs, and rollback when startup fails |\n| Cleanup | Trove, Janitor, Maid | [Cleanup](https://github.com/Layfate/Constella/blob/main/docs/Cleanup.md) | Level with Janitor and about 6× faster than Trove for functions on a Roblox server, with half of Trove's memory ([benchmarks](https://github.com/Layfate/Constella/blob/main/docs/Benchmarks.md)) |\n| Signals | GoodSignal, sleitnick/signal | [Signal](https://github.com/Layfate/Constella/blob/main/docs/Signal.md) | Catches each listener's errors, calls listeners in order and survives cancelled threads. With the same error catching, sleitnick/signal is faster (`Fire` 6–24%, `Connect`+`Disconnect` about 1.2×); Signal uses the least memory per connection of the three |\n| Promises | evaera/promise | [Promise](https://github.com/Layfate/Constella/blob/main/docs/Promise.md) | A smaller, strictly typed core: cancellation, timeouts, `all`/`race`/`allSettled`, retry with backoff. About 6× faster than evaera/promise for a `resolve`+`Then`+`Await` and a tenth of the memory per promise; evaera/promise has a larger API and a long track record |\n| Reactive state | Fusion | [State](https://github.com/Layfate/Constella/blob/main/docs/State.md) | Small reactive values with property bindings, not a UI framework. For building whole interfaces declaratively, Fusion does far more |\n| Zones | ZonePlus | [Zone](https://github.com/Layfate/Constella/blob/main/docs/Zone.md) | Simple point tests against boxes and spheres, with hysteresis at the edges, at about 0.3 µs per tracked item per step. ZonePlus supports more shapes and features |\n| Tagged components | sleitnick/component | [Component](https://github.com/Layfate/Constella/blob/main/docs/Component.md) | Each component gets its own Cleanup and an ancestor filter |\n| Object reuse | PartCache | [Pool](https://github.com/Layfate/Constella/blob/main/docs/Pool.md) | Pools any object, not only Parts, with limits on idle and active counts |\n\n## Quick start\n\nUtilities work on their own, with no setup:\n\n```lua\n-- Any Script or LocalScript\nlocal Constella = require(game:GetService(\"ReplicatedStorage\").Packages.Constella)\n\nlocal cleanup = Constella.Cleanup.new()\nlocal health = Constella.State.new(100)\ncleanup:Add(health:Subscribe(function(new, old)\n\tprint(\"Health\", old, \"->\", new)\nend))\nhealth:Set(80)\n\nlocal rarity = Constella.Random.choose({\n\t{ Value = \"Common\", Weight = 75 },\n\t{ Value = \"Rare\", Weight = 20 },\n\t{ Value = \"Legendary\", Weight = 5 },\n}, Random.new(1234)) -- seeded: the same roll every time\n\ncleanup:Destroy() -- disconnects everything it owns\n```\n\nFor a whole game, write services and start them with an app. This service keeps each player's coins on the server, shows them to that player only, and sells items through a validated, rate-limited remote:\n\n```lua\n-- ServerScriptService/Services/CoinService.luau\nlocal Players = game:GetService(\"Players\")\nlocal Constella = require(game:GetService(\"ReplicatedStorage\").Packages.Constella)\nlocal Check = Constella.Network.Check\n\nlocal PRICES = { Sword = 10, Shield = 50 }\n\nlocal CoinService = { Name = \"CoinService\", Environment = \"Server\" }\n\nfunction CoinService:Init(context)\n\tlocal replicator = context.Cleanup:Add(Constella.Replication.Server.new(\"Coins\"))\n\tlocal network = context.Cleanup:Add(Constella.Network.Server.new(\"Shop\"))\n\tlocal coins = {}\n\n\tcontext.Cleanup:Connect(Players.PlayerAdded, function(player)\n\t\tcoins[player] = Constella.State.new(100)\n\t\treplicator:ShareWith(player, \"Coins\", coins[player]) -- visible to this player only\n\tend)\n\tcontext.Cleanup:Connect(Players.PlayerRemoving, function(player)\n\t\tlocal balance = coins[player]\n\t\tcoins[player] = nil\n\t\tif balance then\n\t\t\tbalance:Destroy()\n\t\tend\n\tend)\n\n\t-- Clients may only send \"Sword\" or \"Shield\", at most twice per second.\n\tnetwork:Function(\"Buy\", {\n\t\tSchema = { Check.literal(\"Sword\", \"Shield\") },\n\t\tRateLimit = { Count = 2, Per = 1 },\n\t}):SetHandler(function(player, item)\n\t\tlocal balance, price = coins[player], PRICES[item]\n\t\tif not balance or balance:Get() < price then\n\t\t\treturn false\n\t\tend\n\t\tbalance:Update(function(current)\n\t\t\treturn current - price\n\t\tend)\n\t\treturn true\n\tend)\nend\n\nreturn CoinService\n```\n\n```lua\n-- ServerScriptService/Main.server.luau\nlocal Constella = require(game:GetService(\"ReplicatedStorage\").Packages.Constella)\n\nlocal app = Constella.App.new()\napp:AddModules(script.Parent.Services) -- only this folder, never auto-discovered\napp:Start()\ngame:BindToClose(function()\n\tapp:Stop()\nend)\n```\n\n```lua\n-- StarterPlayer/StarterPlayerScripts/Shop.client.luau\nlocal Constella = require(game:GetService(\"ReplicatedStorage\").Packages.Constella)\n\nlocal coins = Constella.Replication.Client.new(\"Coins\"):Get(\"Coins\") -- read-only\ncoins:Observe(function(value)\n\tprint(\"Coins:\", value)\nend)\n\nlocal buy = Constella.Network.Client.new(\"Shop\"):Function(\"Buy\", { Timeout = 5 })\nlocal ok, bought = buy:Invoke(\"Sword\") -- ok is false on a rejection, rate limit or timeout\nprint(\"Bought a sword:\", ok and bought)\n```\n\nTo type a remote on both sides, declare it once in a shared [Network contract](https://github.com/Layfate/Constella/blob/main/docs/Network.md#contracts-typed-endpoints): the server's handler and the client's call are then checked against the same argument and result types.\n\nA complete demo game, with saved data, a coins UI and a shop, lives in [`src/server`](https://github.com/Layfate/Constella/tree/main/src/server) and [`src/client`](https://github.com/Layfate/Constella/tree/main/src/client). Each module also has a short example in [`examples/`](https://github.com/Layfate/Constella/tree/main/examples). To start a new game, copy the [starter template](https://github.com/Layfate/Constella/tree/main/template); [Game layout](https://github.com/Layfate/Constella/blob/main/docs/GameLayout.md) explains where everything goes.\n\n## Installation\n\n**Download (easiest).** Get `Constella.rbxm` from the [latest release](https://github.com/Layfate/Constella/releases/latest). In Studio, right-click `ReplicatedStorage` → **Insert from File…** and choose the file. Then move the inserted `Constella` module into a Folder named `Packages`, so the path is `ReplicatedStorage.Packages.Constella`.\n\n> [!TIP]\n> The package is named `layfate/constella` on Wally and `zense/constella` on pesde. The release download, the Wally package and the pesde package are built from the same tagged source.\n\n**Wally.** Add Constella to `wally.toml`, then run `wally install`:\n\n```toml\n[dependencies]\nConstella = \"layfate/constella@0.4.0\"\n```\n\nAutocomplete works through Wally's `Packages/Constella` link file as installed. Every public type is exported from the root module (`Constella.Context`, `Constella.Store<T>`, `Constella.Value<T>` and so on). To use those type names in your own annotations, re-export them into the link files with [wally-package-types](https://github.com/JohnnyMorganz/wally-package-types) after every `wally install`:\n\n```bash\nrojo sourcemap default.project.json --output sourcemap.json\nwally-package-types --sourcemap sourcemap.json Packages/\n```\n\n**pesde.**\n\n```bash\npesde add zense/constella\n```\n\n**Build from source.** Build the model file with Rojo, then insert `Constella.rbxm` into `ReplicatedStorage.Packages`:\n\n```bash\nrojo build default.project.json -o Constella.rbxm\n```\n\n<details>\n<summary><b>Manual install (no tools)</b></summary>\n\n1. In Studio, create a Folder named `Packages` in `ReplicatedStorage`.\n2. Inside it, create a ModuleScript named `Constella` and paste in [`src/shared/Constella/init.luau`](https://github.com/Layfate/Constella/blob/main/src/shared/Constella/init.luau).\n3. For every other file in [`src/shared/Constella`](https://github.com/Layfate/Constella/tree/main/src/shared/Constella), add a child ModuleScript with the same name (without `.luau`).\n4. `Network` and `Data` are folders: give each one a ModuleScript holding its `init.luau`, with the rest of its files as children.\n\n</details>\n\n## Development\n\n```bash\nrokit install                  # rojo, wally, selene, stylua\nrojo serve dev.project.json    # dev place: package, demo, examples and tests\nselene src tests examples benchmarks     # lint\nstylua src tests examples benchmarks     # format\n```\n\nPress **Play** in the dev place to run the full test suite and both integration tests. On every push and pull request, GitHub Actions checks formatting (StyLua), lint (selene) and strict Roblox types (luau-lsp), then runs the whole test suite on a real Roblox server through Open Cloud, including the live DataStore tests. See [CONTRIBUTING.md](https://github.com/Layfate/Constella/blob/main/CONTRIBUTING.md) for how tests are structured and what a pull request needs.\n\n## License\n\nMIT © 2026 Zense. See [LICENSE](https://github.com/Layfate/Constella/blob/main/LICENSE).\n","readmeTruncated":false}