Core / App
Constella.App (also available as Constella.Core.App) manages a set of definitions. On the server these are called services, and on a client they’re called controllers. The App runs their lifecycle in dependency order.
local app = Constella.App.new({ Name = "Server" })
app:Add(require(script.Services.DataService))
app:AddModules(script.Services) -- or add a whole folder explicitly
app:Start()
game:BindToClose(function() app:Stop() end)
Definitions
local InventoryService = {
Name = "InventoryService", -- required, unique per app
Dependencies = { "PlayerDataService" }, -- optional
Environment = "Server", -- optional: "Server" | "Client" | "Shared"
}
function InventoryService:Init(context) end -- optional, may yield
function InventoryService:Start(context) end -- optional, runs on its own thread
function InventoryService:Stop(context) end -- optional
return InventoryService
self is the definition table. context contains:
| Field | Description |
|---|---|
context.App |
The owning app |
context.Name |
The definition’s name |
context.Cleanup |
A Cleanup, destroyed after Stop |
context:Get(name) |
Returns a dependency. Raises if name isn’t in Dependencies |
Lifecycle
Addchecks the shape of the definition. It rejects duplicate names, self-dependencies and wrongEnvironmentvalues (a client app refusesEnvironment = "Server"). It only works beforeStart.Startfirst resolves the graph. Missing dependencies (all of them listed at once) and cycles (shown asA -> B -> C -> A) fail before any user code runs.- Init runs sequentially in dependency order, and each Init can yield. Connect to other services’ signals here. They begin emitting in their own
Start, which runs only after everyInithas finished. - Start also runs in dependency order, each one on its own thread. An error thrown before the first yield fails startup. An error thrown after a yield goes to
OnError(by default it’s raised on a new thread) and the app keeps running. For a critical service, see Readiness. - Failed startup:
Stopruns in reverse order for every definition whoseInitwas called, and each one’scontext.Cleanupis destroyed. ThenStartraises. The app’s state becomes"Failed"and it can’t be restarted. WriteStopso it copes withStartnever having run. StoprunsStopin reverse dependency order, then destroys each Cleanup. Errors are collected and raised together after everything has stopped. Calling it again does nothing.
A Start that is still running when its definition stops (it yielded and never returned, such as a while true do ... task.wait() end loop) is cancelled just before that definition’s Stop. This happens on app:Stop() and on a failed startup. Threads that Start spawns itself aren’t tracked, so add them to context.Cleanup, which cancels threads when it’s destroyed.
The order is deterministic. Definitions are visited in registration order and dependencies in the order they’re declared.
Readiness (WaitForStart)
Some services must be fully ready before anything else runs, such as a database connection or a config load. Mark them with WaitForStart = true:
local ConfigService = {
Name = "ConfigService",
WaitForStart = true,
StartTimeout = 10, -- seconds; default 30
}
function ConfigService:Start(context)
self.Config = fetchConfig() -- may yield
end
app:Start()yields until this definition’sStarthas finished, even if it yields. Only then do later definitions start, and only after every gatedStartfinishes does the app becomeRunning.- An error at any point in that
Start, including after a yield, fails startup with the usual rollback. - If
Startruns longer thanStartTimeout, it’s cancelled, startup fails with “did not finish within N seconds”, and the rollback runs. - Definitions without
WaitForStartbehave as before.
API
| Member | Description |
|---|---|
App.new(options?) |
options.Name, options.Environment ("Server"/"Client", auto-detected), options.OnError |
app:Add(definition) |
Registers a definition and returns it |
app:AddModules(container, { Recursive?, Filter? }?) |
Requires and adds the ModuleScripts in container, sorted by full name |
app:Start() |
Runs Init then Start. Can only be called once. Yields while a WaitForStart definition is starting |
app:AwaitStart() |
Yields until the app is running. Raises if startup failed |
app:Stop() |
Stops the app. Idempotent |
app:Get(name) / app:Has(name) |
Looks up a definition |
app:GetOrder() |
The resolved startup order (names) |
app:GetState() |
Idle, Starting, Running, Stopping, Stopped or Failed |
app.Started / app.Stopped |
Signals |
App.is(value) |
Type check |
Client vs server
Create one app per environment. A server app can’t contain Environment = "Client" definitions, and a client app can’t contain Environment = "Server" ones. Use "Shared" (or leave the field out) for code that runs on both. Keep server-only modules in ServerScriptService or ServerStorage so they never replicate to clients. The environment check catches mistakes; it doesn’t replace putting code in the right place.