Core Concepts

Dependencies, Middleware & Startup Failure

Three related mechanisms for controlling startup order, validating requests, and deciding what happens when a service can't start.

Dependencies Between Services

Thread.CreateService({
    Name = "InventoryService",
    Dependencies = { "DataService" }, -- DataService's ThreadInit is guaranteed to run first
    ThreadInit = function(self)
        self.Data = Thread.GetService("DataService")
    end,
})

Internally, Thread.Start() builds a dependency graph from every service's Dependencies list and runs a topological sort (depth-first, tracking a "visiting" state per node) before calling any ThreadInit. Two failure modes are caught before any service code runs at all, with a precise error message:

  • Unknown dependency: a service lists a name that was never registered.
  • Circular dependency: e.g. A depends on B, B depends on A. The error message includes the exact cycle (A -> B -> A).

Either failure rejects Thread.OnStart() the same way a critical failure does (below) — it does not crash your script by default.

You only need Dependencies when a service reads another service's state during ThreadInit. If two services only reference each other from ThreadStart (which always runs after every ThreadInit) or later, you don't need to declare anything.

Middleware

Middleware runs for everything in a service's Client table — Methods, Signals, and Properties — either transforming or rejecting the call before it reaches your code (Inbound) or before it goes out to the client (Outbound).

Thread.CreateService({
    Name = "ShopService",
    Client = {
        Purchase = function(self, player, itemId)
            -- ... itemId is guaranteed to be a string by the time we get here
        end,
    },
    Middleware = {
        Inbound = {
            function(player, args)
                if typeof(args[1]) ~= "string" then
                    return false -- returning false drops the call entirely
                end
                return true
            end,
        },
    },
})

A middleware function receives (player, args) where args is a plain array of the call's arguments (inbound) or its return value(s)/broadcast payload (outbound). It can mutate args in place to transform them, and returns false to stop the chain. Multiple middleware functions run in the order given, each seeing the previous one's mutations.

On a...Inbound runs when...Outbound runs when...
Method the client calls it, before your handler runs. Returning false means your handler never executes and the client gets nil back. your handler returns, before the result is sent back. Returning false sends nil instead.
Signal the client fires it (received via :Connect on the server), before your handler runs. the server calls :Fire/:FireAll/:FireExcept, before the event goes out. Returning false silently drops that send.
Property — (there's no "inbound" for a Property; the client never pushes data through one) the server calls :Set/:SetFor, before the new value is stored and broadcast. Returning false leaves the value unchanged.

For Outbound on Signal:FireAll/:FireExcept and Property:Set, there's no single target player yet (it's going to everyone), so middleware there is called with player = nil — write your middleware to handle that if you use those.

Use middleware for validation/logging/transformation that applies across multiple methods/signals/properties on a service. For a check that only applies to one specific method, a plain if/assert at the top of that method is simpler and easier to read.

Critical Services & Startup Failure

Thread.CreateService({
    Name = "DataService",
    Critical = true, -- a failed ThreadInit/ThreadStart here rejects the whole Thread.Start()
})

Thread.Start():catch(function(err)
    warn("Startup failed:", err)
    -- e.g. kick all players, since data can't load
end)

If a service marked Critical = true throws inside ThreadInit or ThreadStart, Thread.Start() stops processing further services and the Promise returned by Thread.Start()/Thread.OnStart() rejects with a descriptive message. By default this does not crash the script that called Thread.Start() — you decide what to do via :catch().

If you'd rather have the old, harder failure mode (immediately error(), killing the calling script), opt in explicitly:

Thread.Configure({ HaltOnCriticalFailure = true })

Non-critical services that throw during ThreadInit/ThreadStart log a warning and are skipped, along with services that depend on them. Unrelated services continue normally. Only mark a service Critical if the game genuinely can't function without it (typically: your data-persistence service).