Services and controllers

How to add a plain-module Template service, use its lifecycle, keep rules pure, handle refusals and make optional systems safe when disabled.

Roblox Template / The Roblox Template

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, or src/<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 in shared/Rules/<Domain>.luau, with a spec in tests/core/shared/Rules/<Domain>.spec.luau. Config and rules use string requires and never call game.

Its spec

tests/core/server/Services/<Name>.spec.luau (a controller's under tests/core/client/Controllers/), running the real source over the tests/lib substitutes: 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 of lune run check, fails while a service or controller is neither loaded by a spec nor listed in its UNTESTED table with the reason.

Private configuration

Secrets and unreleased redeem codes belong in src/core/server/Config/. Require them through script.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.

A service's lifecycle. The Loader requires core and place modules and checks feature and place metadata. Enabled modules run init in alphabetical order without yielding. After every init has finished, each start runs in its own thread. Player-specific work starts when data loads and cleans up on unload or leave.

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

  1. Check the owner

    Read docs/systems/Systems Index.md and the nearest service. Start from a card with an observable Done when.

  2. Scaffold the module

    Run lune run new -- service <Name> or lune run new -- controller <Name>. Keep the generated house shape: strict header, services and requires, module state, private helpers, public functions, lifecycle.

  3. 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.

  4. Own player cleanup

    Use DataService.onLoaded for work needing saves, or Observers.observePlayers otherwise. 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. A RateLimiter keyed by something that outlives its player calls limiter:prune() now and then to forget buckets that have refilled.

  5. 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.

Luau
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.

Updated