Services & Lifecycle
A Service is a plain Lua table describing one feature of your game. This page covers
defining one, its asynchronous lifecycle, and how Thread.Register/Thread.Start
bring everything up.
Defining a Service
-- ServerScriptService/Services/MoneyService.luau
local Thread = require(game:GetService("ReplicatedStorage").Packages.Thread)
local MoneyService = Thread.CreateService({
Name = "MoneyService", -- required, must be unique
})
local balances = {}
function MoneyService:GetMoney(player)
return balances[player] or 0
end
function MoneyService:GiveMoney(player, amount)
balances[player] = self:GetMoney(player) + amount
end
return MoneyService
The Lifecycle
A service can define three lifecycle methods. Each may return a Promise, which Thread awaits before continuing:
Thread.OnStart() independently observes local startup.
-
ThreadInit(self)— runs first, for every service, in dependency order (see Dependencies). Use this to set up internal state and grab references to other services viaThread.GetService(...). Client remotes are already bound at this point, so it's safe to:Connect()your own signals here. -
ThreadStart(self)— runs after the initialization phase for services whose initialization and dependencies succeeded. Use this for logic that depends on other healthy services being fully initialized. ThreadStop(self)runs duringThread.Stop()in reverse dependency order.
This two-phase split exists specifically to avoid startup-order bugs: by the time any
ThreadStart runs, every healthy service has completed
ThreadInit. Failed services and their dependents are skipped.
Thread.CreateService({...}) call works on the client —
informally called a "controller" there, but it's the identical API. See the
Server vs. Client Cheat Sheet for the one field that differs.
Bootstrapping: Register + Start
Two calls, once per side (server and client each need their own):
-- ServerScriptService/Server.server.lua
local Thread = require(game:GetService("ReplicatedStorage").Packages.Thread)
Thread.Register(game:GetService("ServerScriptService").Services)
Thread.Start():catch(warn)
-- StarterPlayerScripts/Client.client.lua
local Thread = require(game:GetService("ReplicatedStorage").Packages.Thread)
Thread.Register(script.Parent.Controllers)
Thread.Start():catch(warn)
What Thread.Register(folder, recursive?) actually does
It walks every ModuleScript directly inside folder (pass
recursive = true to walk nested subfolders too) and calls
require() on each one. Since your service files call
Thread.CreateService({...}) at the top level, simply requiring
the module is what registers it — Thread.Register never has to know your
service names in advance. It returns a report array so you can inspect what loaded:
local results = Thread.Register(folder)
for _, r in ipairs(results) do
if not r.Success then
warn("Failed to load", r.Module.Name, ":", r.Error)
end
end
What Thread.Start() actually does, step by step
- Collects every registered service and computes a dependency order (topological sort).
- For every service with a
Clienttable, callsChannel.WrapService(...)to bind it to real Remote instances (server-only). - Calls
ThreadIniton every service, in dependency order. - Calls
ThreadStarton every healthy service, in dependency order, after the initialization phase finishes. - Publishes the exact client manifest and resolves the Promise returned by
Thread.OnStart().
If a service marked Critical = true fails at step 3 or 4, steps after it
are skipped and the start Promise rejects instead of
resolving — see Critical Services.
Thread.OnStart() returns an independent observer Promise
for the same result and can be called from anywhere, any number of times.
Cancelling one observer does not cancel startup or other observers:
Thread.OnStart():andThen(function()
local MoneyService = Thread.GetService("MoneyService") -- safe now, everything is started
end):catch(warn)
-- Dependents stop before their dependencies.
Thread.Stop():await()
Thread.
The server's Thread._Register, Thread.OnStart(), etc. are
entirely independent Lua state from the client's — they don't communicate with each
other automatically. That's what Channel is for.