Core Concepts

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 execution model from service registration through dependency ordering, remote binding, initialization, startup, client readiness, and reverse-order shutdown.
Thread completes each startup phase in dependency order. Clients can wait for a published service manifest while 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 via Thread.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 during Thread.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.

Works identically on the client
The exact same 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

  1. Collects every registered service and computes a dependency order (topological sort).
  2. For every service with a Client table, calls Channel.WrapService(...) to bind it to real Remote instances (server-only).
  3. Calls ThreadInit on every service, in dependency order.
  4. Calls ThreadStart on every healthy service, in dependency order, after the initialization phase finishes.
  5. 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()
The most important thing to internalize
The server and the client each run their own separate copy of 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.