A service owns one server domain; a controller owns client behaviour. Both are plain strict Luau modules loaded from their folder, with init() and start() when needed. There is no service registry, dependency injection or base class. Extend an existing owner before adding another one.
Where a service and its rules go
- The server owner
src/core/server/Services/<Domain>Service.luau, orsrc/<place>/server/Services/when only one place runs it.- The client owner
src/core/client/Controllers/<Domain>Controller.luau, or the place's matching Controllers folder.- Values and formulas
Tunable numbers and ids in
shared/Config/<Domain>.luau; pure formulas inshared/Rules/<Domain>.luau, with a spec intests/core/shared/Rules/<Domain>.spec.luau. Config and rules use string requires and never callgame.- Its spec
tests/core/server/Services/<Name>.spec.luau(a controller's undertests/core/client/Controllers/), running the real source over thetests/libsubstitutes: its start with the feature on and off, its main path, at least one refusal that writes nothing, and cleanup when a player leaves. A controller with logic needs at least a smoke spec.lune run lint-specs, part oflune run check, fails while a service or controller is neither loaded by a spec nor listed in itsUNTESTEDtable with the reason.- Private configuration
Secrets and unreleased redeem codes belong in
src/core/server/Config/. Require them throughscript.Parent.Parent.Config, never from shared or client code.
The Template's add-service skill and CurrencyService.luau are the full procedure and example. A service that outgrows one file becomes a folder, Services/<Name>/init.luau with private parts and a README.md naming them; requires of it do not change.
Some Roblox APIs have one owner, and lint-boundaries fails any other caller: saves go through DataService, Robux through MonetizationService, analytics through AnalyticsService, other places through TravelService, and the engine wrappers in src/core/server/Roblox/ (not services: no lifecycle) hold the rest: MessagingBus for other servers, MemoryStore and Http for the web and secrets. From a service, require them as script.Parent.Parent.Roblox.Http. For the platform's HTTP caller, see Inside PlatformService.
MessagingBus.subscribe(topic, handler) registers the handler at once and subscribes the server in its own thread; a failed subscription is warned and tried again every 60 seconds until Roblox accepts it. It returns a function that removes the handler, and once a topic's last handler is gone the server unsubscribes from the topic.
A service that pays a player anything (currency, an item, a boost or a title) goes through RewardService: fits(player, rewards) checks without writing, and grant(player, reason, rewards, change?) applies the rewards and the caller's own record in one save write, or refuses and writes nothing. A reward paid once per account goes through ClaimService.claim, which refuses what fits refuses and pays through RewardService. The shape and the refusals are on Economy and monetization.
init and start
Loader.luau requires the core and place modules, reads their metadata, then runs every enabled init() alphabetically before starting anything. init() connects remotes, signals and player events without yielding. The Loader warns if it yields or takes more than 50 ms. Each start() then runs in its own thread, where waiting is allowed. An init() that errors prevents that module's start(); other modules continue.
Requiring script.Parent.OtherService is normal. Keep dependencies in one direction; when two owners need to react to each other, expose a Signal and listen to it. Alphabetical loading does not establish dependency order.
Adding a service
Check the owner
Read
docs/systems/Systems Index.mdand the nearest service. Start from a card with an observable Done when.Scaffold the module
Run
lune run new -- service <Name>orlune run new -- controller <Name>. Keep the generated house shape: strict header, services and requires, module state, private helpers, public functions, lifecycle.Separate decisions from Roblox glue
Put values in Config and rules in pure modules with specs. Connect handlers in
init()and recheck their meaning on the server. Use the existing owner for saves, currency, purchases and analytics.Own player cleanup
Use
DataService.onLoadedfor work needing saves, orObservers.observePlayersotherwise. Return cleanup or destroy a per-player Trove. Clear cooldown and limiter entries on unload; also handle PlayerRemoving when calls can arrive before data loads. ARateLimiterkeyed by something that outlives its player callslimiter:prune()now and then to forget buckets that have refilled.Document and verify
Add the service's spec, the system note from
docs/templates/System.md, its Systems Index row and any new folder README. Follow the verify and playtest skills.
Use DataService.watch(player, fn) to react to one player's data, rather than selecting the all-players atom. A watcher sees the newest state once per frame; compare values instead of counting callbacks.
Optional services must be harmless while off
An optional module exports feature = "<switch>", matching Config/Features. The Loader skips its lifecycle while off, but still requires the module to read metadata. Public functions must also check the switch and return a harmless value or refusal; another service may still require and call them.
Its screens, admin tabs, commands and asset preload follow the same switch. A module may also export places = { "arena" } to restrict its lifecycle to named places. See Config and features.
Expected refusals use Result
shared/Util/Result.luau describes success as { ok = true, value = ... } and refusal as { ok = false, reason = "...", detail = ... }. detail is optional. Insufficient funds and unloaded data are normal answers; throwing is for programmer mistakes.
local result = CurrencyService.spend(player, "coins", 50)if not result.ok then return resultendprint(result.value)The helpers are Result.ok, err, toMessage, unwrapOr, map and try. toMessage adapts a Result to an answered remote's { ok, message } shape. Pass a refusal up unchanged when the caller can handle the same reason.
Add a guarded intent and its meaning checks.
Choose the right state owner and write path.
Updated