Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(app): the loop every golden project registers through is frozen

esengine80c1b264f70f
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index d46fae243..49ea7c4c2 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -1,9 +1,9 @@
{
"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.",
"counts": {
- "public": 54,
+ "public": 64,
"beta": 24,
- "experimental": 1547,
+ "experimental": 1537,
"deprecated": 3
},
"total": 1625,
@@ -524,6 +524,18 @@
"minigame"
]
},
+ {
+ "name": "RunCondition",
+ "kind": "type",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "RuntimeOnly",
"kind": "const",
@@ -536,6 +548,18 @@
"minigame"
]
},
+ {
+ "name": "Schedule",
+ "kind": "enum",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "SystemDef",
"kind": "interface",
@@ -572,6 +596,54 @@
"minigame"
]
},
+ {
+ "name": "SystemSet",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "SystemSetOptions",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "Time",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "TimeData",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "Transform",
"kind": "const",
@@ -632,6 +704,42 @@
"minigame"
]
},
+ {
+ "name": "addStartupSystem",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "addSystemSetToSchedule",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "addSystemToSchedule",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "defineComponent",
"kind": "function",
@@ -655,6 +763,18 @@
"wechat",
"minigame"
]
+ },
+ {
+ "name": "defineSystemSet",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
}
],
"beta": [
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 4e11aa642..36ea2a4ba 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 54 public · 17 beta · 1432 experimental · 3 deprecated
+Symbols: 64 public · 17 beta · 1422 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -5685,7 +5685,7 @@ gravityScale: number
linearDamping: number
```
-## RunCondition — type @experimental
+## RunCondition — type @public
```
() => boolean
```
@@ -6048,7 +6048,7 @@ static new (host: SceneStreamHost, config?: SceneStreamingConfig): SceneStreamin
static prototype: SceneStreamingController
```
-## Schedule — enum @experimental
+## Schedule — enum @public
```
First = 1
FixedPostUpdate = 12
@@ -6748,17 +6748,17 @@ static new (world: World, resources: ResourceStorage, eventRegistry?: EventRegis
static prototype: SystemRunner
```
-## SystemSet — interface @experimental
+## SystemSet — interface @public
```
-_kind: "set"
-_name: string
-_runAfter: readonly string[] | undefined
-_runBefore: readonly string[] | undefined
-_runIf: RunCondition | undefined
-_systems: readonly SystemDef[]
+@internal _kind: "set"
+@internal _name: string
+@internal _runAfter: readonly string[] | undefined
+@internal _runBefore: readonly string[] | undefined
+@internal _runIf: RunCondition | undefined
+@internal _systems: readonly SystemDef[]
```
-## SystemSetOptions — interface @experimental
+## SystemSetOptions — interface @public
```
runAfter: string[] | undefined
runBefore: string[] | undefined
@@ -7367,12 +7367,12 @@ mask: number | undefined
set: number
```
-## Time — const @experimental
+## Time — const @public
```
ResourceDef<TimeData>
```
-## TimeData — interface @experimental
+## TimeData — interface @public
```
delta: number
elapsed: number
@@ -8428,7 +8428,7 @@ TransformData
(g: MaterialGraph, type: GraphNodeType, x: number, y: number): { graph: MaterialGraph; id: string; }
```
-## addStartupSystem — function @experimental
+## addStartupSystem — function @public
```
(system: SystemDef): void
```
@@ -8443,12 +8443,12 @@ TransformData
(system: SystemDef): void
```
-## addSystemSetToSchedule — function @experimental
+## addSystemSetToSchedule — function @public
```
(schedule: Schedule, set: SystemSet): void
```
-## addSystemToSchedule — function @experimental
+## addSystemToSchedule — function @public
```
(schedule: Schedule, system: SystemDef): void
```
@@ -9053,7 +9053,7 @@ PluralSelector
<P extends readonly SystemParam[]>(params: [...P], fn: (...args: InferParams<P>) => void | Promise<void>, options?: SystemOptions): SystemDef
```
-## defineSystemSet — function @experimental
+## defineSystemSet — function @public
```
(name: string, options: SystemSetOptions): SystemSet
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index ecd7258cd..94efbbe2d 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 54 public · 22 beta · 1451 experimental · 3 deprecated
+Symbols: 64 public · 22 beta · 1441 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -5878,7 +5878,7 @@ gravityScale: number
linearDamping: number
```
-## RunCondition — type @experimental
+## RunCondition — type @public
```
() => boolean
```
@@ -6241,7 +6241,7 @@ static new (host: SceneStreamHost, config?: SceneStreamingConfig): SceneStreamin
static prototype: SceneStreamingController
```
-## Schedule — enum @experimental
+## Schedule — enum @public
```
First = 1
FixedPostUpdate = 12
@@ -6941,17 +6941,17 @@ static new (world: World, resources: ResourceStorage, eventRegistry?: EventRegis
static prototype: SystemRunner
```
-## SystemSet — interface @experimental
+## SystemSet — interface @public
```
-_kind: "set"
-_name: string
-_runAfter: readonly string[] | undefined
-_runBefore: readonly string[] | undefined
-_runIf: RunCondition | undefined
-_systems: readonly SystemDef[]
+@internal _kind: "set"
+@internal _name: string
+@internal _runAfter: readonly string[] | undefined
+@internal _runBefore: readonly string[] | undefined
+@internal _runIf: RunCondition | undefined
+@internal _systems: readonly SystemDef[]
```
-## SystemSetOptions — interface @experimental
+## SystemSetOptions — interface @public
```
runAfter: string[] | undefined
runBefore: string[] | undefined
@@ -7560,12 +7560,12 @@ mask: number | undefined
set: number
```
-## Time — const @experimental
+## Time — const @public
```
ResourceDef<TimeData>
```
-## TimeData — interface @experimental
+## TimeData — interface @public
```
delta: number
elapsed: number
@@ -8621,7 +8621,7 @@ TransformData
(g: MaterialGraph, type: GraphNodeType, x: number, y: number): { graph: MaterialGraph; id: string; }
```
-## addStartupSystem — function @experimental
+## addStartupSystem — function @public
```
(system: SystemDef): void
```
@@ -8636,12 +8636,12 @@ TransformData
(system: SystemDef): void
```
-## addSystemSetToSchedule — function @experimental
+## addSystemSetToSchedule — function @public
```
(schedule: Schedule, set: SystemSet): void
```
-## addSystemToSchedule — function @experimental
+## addSystemToSchedule — function @public
```
(schedule: Schedule, system: SystemDef): void
```
@@ -9286,7 +9286,7 @@ PluralSelector
<P extends readonly SystemParam[]>(params: [...P], fn: (...args: InferParams<P>) => void | Promise<void>, options?: SystemOptions): SystemDef
```
-## defineSystemSet — function @experimental
+## defineSystemSet — function @public
```
(name: string, options: SystemSetOptions): SystemSet
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index ab119002c..5a5b25c46 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 54 public · 19 beta · 1431 experimental · 3 deprecated
+Symbols: 64 public · 19 beta · 1421 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -5680,7 +5680,7 @@ gravityScale: number
linearDamping: number
```
-## RunCondition — type @experimental
+## RunCondition — type @public
```
() => boolean
```
@@ -6043,7 +6043,7 @@ static new (host: SceneStreamHost, config?: SceneStreamingConfig): SceneStreamin
static prototype: SceneStreamingController
```
-## Schedule — enum @experimental
+## Schedule — enum @public
```
First = 1
FixedPostUpdate = 12
@@ -6743,17 +6743,17 @@ static new (world: World, resources: ResourceStorage, eventRegistry?: EventRegis
static prototype: SystemRunner
```
-## SystemSet — interface @experimental
+## SystemSet — interface @public
```
-_kind: "set"
-_name: string
-_runAfter: readonly string[] | undefined
-_runBefore: readonly string[] | undefined
-_runIf: RunCondition | undefined
-_systems: readonly SystemDef[]
+@internal _kind: "set"
+@internal _name: string
+@internal _runAfter: readonly string[] | undefined
+@internal _runBefore: readonly string[] | undefined
+@internal _runIf: RunCondition | undefined
+@internal _systems: readonly SystemDef[]
```
-## SystemSetOptions — interface @experimental
+## SystemSetOptions — interface @public
```
runAfter: string[] | undefined
runBefore: string[] | undefined
@@ -7362,12 +7362,12 @@ mask: number | undefined
set: number
```
-## Time — const @experimental
+## Time — const @public
```
ResourceDef<TimeData>
```
-## TimeData — interface @experimental
+## TimeData — interface @public
```
delta: number
elapsed: number
@@ -8423,7 +8423,7 @@ TransformData
(g: MaterialGraph, type: GraphNodeType, x: number, y: number): { graph: MaterialGraph; id: string; }
```
-## addStartupSystem — function @experimental
+## addStartupSystem — function @public
```
(system: SystemDef): void
```
@@ -8438,12 +8438,12 @@ TransformData
(system: SystemDef): void
```
-## addSystemSetToSchedule — function @experimental
+## addSystemSetToSchedule — function @public
```
(schedule: Schedule, set: SystemSet): void
```
-## addSystemToSchedule — function @experimental
+## addSystemToSchedule — function @public
```
(schedule: Schedule, system: SystemDef): void
```
@@ -9048,7 +9048,7 @@ PluralSelector
<P extends readonly SystemParam[]>(params: [...P], fn: (...args: InferParams<P>) => void | Promise<void>, options?: SystemOptions): SystemDef
```
-## defineSystemSet — function @experimental
+## defineSystemSet — function @public
```
(name: string, options: SystemSetOptions): SystemSet
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 9deec97c9..a5b139a57 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 54 public · 17 beta · 1452 experimental · 3 deprecated
+Symbols: 64 public · 17 beta · 1442 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -5925,7 +5925,7 @@ gravityScale: number
linearDamping: number
```
-## RunCondition — type @experimental
+## RunCondition — type @public
```
() => boolean
```
@@ -6288,7 +6288,7 @@ static new (host: SceneStreamHost, config?: SceneStreamingConfig): SceneStreamin
static prototype: SceneStreamingController
```
-## Schedule — enum @experimental
+## Schedule — enum @public
```
First = 1
FixedPostUpdate = 12
@@ -6988,17 +6988,17 @@ static new (world: World, resources: ResourceStorage, eventRegistry?: EventRegis
static prototype: SystemRunner
```
-## SystemSet — interface @experimental
+## SystemSet — interface @public
```
-_kind: "set"
-_name: string
-_runAfter: readonly string[] | undefined
-_runBefore: readonly string[] | undefined
-_runIf: RunCondition | undefined
-_systems: readonly SystemDef[]
+@internal _kind: "set"
+@internal _name: string
+@internal _runAfter: readonly string[] | undefined
+@internal _runBefore: readonly string[] | undefined
+@internal _runIf: RunCondition | undefined
+@internal _systems: readonly SystemDef[]
```
-## SystemSetOptions — interface @experimental
+## SystemSetOptions — interface @public
```
runAfter: string[] | undefined
runBefore: string[] | undefined
@@ -7607,12 +7607,12 @@ mask: number | undefined
set: number
```
-## Time — const @experimental
+## Time — const @public
```
ResourceDef<TimeData>
```
-## TimeData — interface @experimental
+## TimeData — interface @public
```
delta: number
elapsed: number
@@ -8668,7 +8668,7 @@ TransformData
(g: MaterialGraph, type: GraphNodeType, x: number, y: number): { graph: MaterialGraph; id: string; }
```
-## addStartupSystem — function @experimental
+## addStartupSystem — function @public
```
(system: SystemDef): void
```
@@ -8683,12 +8683,12 @@ TransformData
(system: SystemDef): void
```
-## addSystemSetToSchedule — function @experimental
+## addSystemSetToSchedule — function @public
```
(schedule: Schedule, set: SystemSet): void
```
-## addSystemToSchedule — function @experimental
+## addSystemToSchedule — function @public
```
(schedule: Schedule, system: SystemDef): void
```
@@ -9298,7 +9298,7 @@ PluralSelector
<P extends readonly SystemParam[]>(params: [...P], fn: (...args: InferParams<P>) => void | Promise<void>, options?: SystemOptions): SystemDef
```
-## defineSystemSet — function @experimental
+## defineSystemSet — function @public
```
(name: string, options: SystemSetOptions): SystemSet
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index d0e8903b7..03f9db3c8 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 54 public · 17 beta · 1442 experimental · 3 deprecated
+Symbols: 64 public · 17 beta · 1432 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -5687,7 +5687,7 @@ gravityScale: number
linearDamping: number
```
-## RunCondition — type @experimental
+## RunCondition — type @public
```
() => boolean
```
@@ -6050,7 +6050,7 @@ static new (host: SceneStreamHost, config?: SceneStreamingConfig): SceneStreamin
static prototype: SceneStreamingController
```
-## Schedule — enum @experimental
+## Schedule — enum @public
```
First = 1
FixedPostUpdate = 12
@@ -6750,17 +6750,17 @@ static new (world: World, resources: ResourceStorage, eventRegistry?: EventRegis
static prototype: SystemRunner
```
-## SystemSet — interface @experimental
+## SystemSet — interface @public
```
-_kind: "set"
-_name: string
-_runAfter: readonly string[] | undefined
-_runBefore: readonly string[] | undefined
-_runIf: RunCondition | undefined
-_systems: readonly SystemDef[]
+@internal _kind: "set"
+@internal _name: string
+@internal _runAfter: readonly string[] | undefined
+@internal _runBefore: readonly string[] | undefined
+@internal _runIf: RunCondition | undefined
+@internal _systems: readonly SystemDef[]
```
-## SystemSetOptions — interface @experimental
+## SystemSetOptions — interface @public
```
runAfter: string[] | undefined
runBefore: string[] | undefined
@@ -7369,12 +7369,12 @@ mask: number | undefined
set: number
```
-## Time — const @experimental
+## Time — const @public
```
ResourceDef<TimeData>
```
-## TimeData — interface @experimental
+## TimeData — interface @public
```
delta: number
elapsed: number
@@ -8450,7 +8450,7 @@ TransformData
(g: MaterialGraph, type: GraphNodeType, x: number, y: number): { graph: MaterialGraph; id: string; }
```
-## addStartupSystem — function @experimental
+## addStartupSystem — function @public
```
(system: SystemDef): void
```
@@ -8465,12 +8465,12 @@ TransformData
(system: SystemDef): void
```
-## addSystemSetToSchedule — function @experimental
+## addSystemSetToSchedule — function @public
```
(schedule: Schedule, set: SystemSet): void
```
-## addSystemToSchedule — function @experimental
+## addSystemToSchedule — function @public
```
(schedule: Schedule, system: SystemDef): void
```
@@ -9075,7 +9075,7 @@ PluralSelector
<P extends readonly SystemParam[]>(params: [...P], fn: (...args: InferParams<P>) => void | Promise<void>, options?: SystemOptions): SystemDef
```
-## defineSystemSet — function @experimental
+## defineSystemSet — function @public
```
(name: string, options: SystemSetOptions): SystemSet
```
diff --git a/sdk/src/ecs/resource.ts b/sdk/src/ecs/resource.ts
index 8dd7531f8..378917669 100644
--- a/sdk/src/ecs/resource.ts
+++ b/sdk/src/ecs/resource.ts
@@ -212,9 +212,19 @@ export class ResourceStorage {
// Builtin Resources
// =============================================================================
+/**
+ * The frame's clock, as {@link Time} carries it. `delta` is what almost
+ * everything integrates by — it is already multiplied by `scale`, so honouring a
+ * pause costs a system nothing.
+ *
+ * @public
+ */
export interface TimeData {
+ /** Seconds since the previous frame, scaled by `scale`. */
delta: number;
+ /** Seconds since the app started. */
elapsed: number;
+ /** Render frames completed — machine-dependent; see `fixedTick`. */
frameCount: number;
/** Fixed-update timestep in seconds — the FixedUpdate / physics cadence. */
fixedDelta: number;
@@ -236,12 +246,22 @@ export interface TimeData {
* to 0. At 0 the frame still runs — systems tick and a menu draws — while
* everything advancing by `delta` (movement, navigation, behaviour trees,
* the physics step) advances by nothing.
+ *
+ * Read once at the top of the frame, before any system runs, so a write
+ * takes effect from the next frame: a game that pauses in `Update`
+ * integrates that frame in full and freezes from the one after.
*/
scale: number;
/** Real frame time, unaffected by `scale`, for whatever must keep moving. */
unscaledDelta: number;
}
+/**
+ * The frame clock, as `Res(Time)`. The engine writes it once per frame before
+ * any system runs; `scale` is the one field a project sets.
+ *
+ * @public
+ */
export const Time = defineResource<TimeData>({
delta: 0,
elapsed: 0,
diff --git a/sdk/src/ecs/system.ts b/sdk/src/ecs/system.ts
index 6678053c3..6233369a2 100644
--- a/sdk/src/ecs/system.ts
+++ b/sdk/src/ecs/system.ts
@@ -21,6 +21,14 @@ import type { World } from './world';
// Schedule Phases
// =============================================================================
+/**
+ * When in a frame a system runs, in the order listed; `Startup` runs once before
+ * the first frame. The `Fixed*` three are the simulation's cadence, running zero
+ * or more times per frame as `Time.fixedDelta` accumulates — where anything that
+ * must be deterministic belongs.
+ *
+ * @public
+ */
export enum Schedule {
Startup = 0,
First = 1,
@@ -111,7 +119,13 @@ export type InferParams<P extends readonly SystemParam[]> = {
// System Definition
// =============================================================================
-/** Predicate evaluated per-frame; returning false skips the system for that tick. */
+/**
+ * Predicate evaluated per-frame; returning false skips the system for that tick.
+ * It is asked once per schedule run, so a set of nine systems gated on one pause
+ * flag reads it once and either all nine run or none do.
+ *
+ * @public
+ */
export type RunCondition = () => boolean;
/**
@@ -208,16 +222,30 @@ export function mergeOrderingEdges(
*
* Build one with {@link defineSystemSet}; the underscore-prefixed fields are
* the scheduler's, not an authoring surface.
+ *
+ * @public
*/
export interface SystemSet {
+ /** @internal */
readonly _kind: 'set';
+ /** @internal */
readonly _name: string;
+ /** @internal */
readonly _systems: readonly SystemDef[];
+ /** @internal */
readonly _runIf?: RunCondition;
+ /** @internal */
readonly _runBefore?: readonly string[];
+ /** @internal */
readonly _runAfter?: readonly string[];
}
+/**
+ * What a {@link SystemSet} is built out of. `systems` keeps the order it is
+ * written in; `runIf` and the two edge lists apply to every member.
+ *
+ * @public
+ */
export interface SystemSetOptions {
/** Systems contained in the set. */
systems: SystemDef[];
@@ -243,6 +271,8 @@ export interface SystemSetOptions {
*
* Members keep the order they are listed in; anything constraining `'physics'`
* constrains all of them.
+ *
+ * @public
*/
export function defineSystemSet(name: string, options: SystemSetOptions): SystemSet {
if (!name) throw new Error('SystemSet requires a name');
@@ -268,10 +298,25 @@ export function addSystem(system: SystemDef): void {
getPendingSystems().push({ schedule: Schedule.Update, system });
}
+/**
+ * Register a system to run once, before the first frame — where a project spawns
+ * its world. Startup runs after the engine's own startup, so the components and
+ * resources a system asks for are there.
+ *
+ * @public
+ */
export function addStartupSystem(system: SystemDef): void {
getPendingSystems().push({ schedule: Schedule.Startup, system });
}
+/**
+ * Register a system in a {@link Schedule}. This is how a project bundle's
+ * systems reach the loop: the call records them, and the app drains what was
+ * recorded when it starts, so module-level registration works before an `App`
+ * exists.
+ *
+ * @public
+ */
export function addSystemToSchedule(schedule: Schedule, system: SystemDef): void {
getPendingSystems().push({ schedule, system });
}
@@ -280,6 +325,8 @@ export function addSystemToSchedule(schedule: Schedule, system: SystemDef): void
* Register a {@link SystemSet} from a project bundle, the module-level twin of
* `App.addSystemSetToSchedule`. Without it a project can define a set — the run
* condition a pause is written as — and have no door to register it through.
+ *
+ * @public
*/
export function addSystemSetToSchedule(schedule: Schedule, set: SystemSet): void {
getPendingSystems().push({ schedule, system: set });
diff --git a/sdk/tests/app-lifecycle-vocabulary.test.ts b/sdk/tests/app-lifecycle-vocabulary.test.ts
new file mode 100644
index 000000000..760c3e959
--- /dev/null
+++ b/sdk/tests/app-lifecycle-vocabulary.test.ts
@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file app-lifecycle-vocabulary.test.ts — the frozen surface a game's loop is
+ * registered through.
+ *
+ * Every golden project imports Schedule and addSystemToSchedule; nine of eleven
+ * import Time. Freezing those freezes claims about *when* a system runs and what
+ * the clock says, so each claim is asserted here rather than left to the phase
+ * numbers looking sensible.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { App, flushPendingSystems } from '../src/app/app';
+import {
+ Schedule, defineSystem, defineSystemSet, addStartupSystem,
+ addSystemToSchedule, addSystemSetToSchedule,
+} from '../src/ecs/system';
+import { Res, ResMut, Time } from '../src/core';
+import { getDefaultContext } from '../src/ecs/context';
+import type { RunCondition, SystemSet, SystemSetOptions, TimeData } from '../src/core';
+
+function trace(name: string, into: string[]) {
+ return defineSystem([], () => { into.push(name); }, { name });
+}
+
+beforeEach(() => {
+ // Module-level registration is app-scoped state, so a leftover from one test
+ // would run inside the next one's app.
+ getDefaultContext().drainPendingSystems();
+});
+
+describe('schedule vocabulary', () => {
+ it('the per-frame phases run in the order the enum lists them', async () => {
+ const app = App.new();
+ const order: string[] = [];
+ // Registered back to front, so passing cannot come from insertion order.
+ for (const phase of [Schedule.Last, Schedule.PostUpdate, Schedule.Update, Schedule.PreUpdate, Schedule.First]) {
+ app.addSystemToSchedule(phase, trace(Schedule[phase], order));
+ }
+
+ await app.tick(1 / 60);
+ expect(order).toEqual(['First', 'PreUpdate', 'Update', 'PostUpdate', 'Last']);
+ });
+
+ it('Startup runs once, before the first frame, however many frames follow', async () => {
+ const app = App.new();
+ const order: string[] = [];
+ app.addSystemToSchedule(Schedule.Update, trace('update', order));
+ app.addSystemToSchedule(Schedule.Startup, trace('startup', order));
+
+ await app.tick(1 / 60);
+ await app.tick(1 / 60);
+ expect(order).toEqual(['startup', 'update', 'update']);
+ });
+
+ it('a Fixed phase runs as many times as the accumulated step allows', async () => {
+ const app = App.new();
+ const steps: string[] = [];
+ app.addSystemToSchedule(Schedule.FixedUpdate, trace('fixed', steps));
+
+ // Three steps' worth of time in one frame; the frame runs once.
+ await app.tick(3 / 60);
+ expect(steps.length).toBe(3);
+ });
+});
+
+describe('module-level registration', () => {
+ it('carries a project bundle\'s systems into the app that flushes them', async () => {
+ const order: string[] = [];
+ addStartupSystem(trace('bundle-startup', order));
+ addSystemToSchedule(Schedule.PostUpdate, trace('bundle-post', order));
+
+ const app = App.new();
+ flushPendingSystems(app);
+ await app.tick(1 / 60);
+
+ expect(order).toEqual(['bundle-startup', 'bundle-post']);
+ });
+
+ it('registers a set, so one runIf gates every member', async () => {
+ const order: string[] = [];
+ let running = false;
+ const gate: RunCondition = () => running;
+ const options: SystemSetOptions = {
+ systems: [trace('a', order), trace('b', order)],
+ runIf: gate,
+ };
+ const set: SystemSet = defineSystemSet('vocab-gated', options);
+ addSystemSetToSchedule(Schedule.Update, set);
+
+ const app = App.new();
+ flushPendingSystems(app);
+ await app.tick(1 / 60);
+ expect(order).toEqual([]);
+
+ running = true;
+ await app.tick(1 / 60);
+ expect(order).toEqual(['a', 'b']);
+ });
+
+ it('drains, so a second app does not inherit the first one\'s systems', async () => {
+ const order: string[] = [];
+ addSystemToSchedule(Schedule.Update, trace('once', order));
+
+ const first = App.new();
+ flushPendingSystems(first);
+ const second = App.new();
+ flushPendingSystems(second);
+
+ await first.tick(1 / 60);
+ await second.tick(1 / 60);
+ expect(order).toEqual(['once']);
+ });
+});
+
+/** Sets `Time.scale` once, on the frame whose number it is given. */
+function scaleOnFrame(app: App, frame: number, to: number) {
+ app.addSystemToSchedule(Schedule.Update, defineSystem([ResMut(Time)], (time) => {
+ time.modify((t) => { if (t.frameCount === frame) t.scale = to; });
+ }));
+}
+
+describe('Time vocabulary', () => {
+ it('delta arrives scaled and unscaledDelta does not', async () => {
+ const app = App.new();
+ const seen: Array<Pick<TimeData, 'delta' | 'unscaledDelta'>> = [];
+ scaleOnFrame(app, 1, 0.5);
+ app.addSystemToSchedule(Schedule.Last, defineSystem([Res(Time)], (time) => {
+ seen.push({ delta: time.delta, unscaledDelta: time.unscaledDelta });
+ }));
+
+ await app.tick(1 / 30);
+ await app.tick(1 / 30);
+ expect(seen[1].delta).toBeCloseTo(1 / 60, 6);
+ expect(seen[1].unscaledDelta).toBeCloseTo(1 / 30, 6);
+ });
+
+ it('a write to scale lands on the next frame, because the clock is read before any system runs', async () => {
+ const app = App.new();
+ const deltas: number[] = [];
+ scaleOnFrame(app, 1, 0);
+ app.addSystemToSchedule(Schedule.Last, defineSystem([Res(Time)], (time) => {
+ deltas.push(time.delta);
+ }));
+
+ await app.tick(1 / 60);
+ await app.tick(1 / 60);
+ // The frame that asked for the pause still integrates fully; the next one
+ // does not. A game pausing in Update overshoots by exactly one frame.
+ expect(deltas[0]).toBeCloseTo(1 / 60, 6);
+ expect(deltas[1]).toBe(0);
+ });
+
+ it('scale 0 still runs the frame, and advances nothing that integrates delta', async () => {
+ const app = App.new();
+ let frames = 0;
+ let advanced = 0;
+ scaleOnFrame(app, 1, 0);
+ app.addSystemToSchedule(Schedule.PostUpdate, defineSystem([Res(Time)], (time) => {
+ if (time.frameCount > 1) { frames += 1; advanced += time.delta; }
+ }));
+ app.addSystemToSchedule(Schedule.FixedUpdate, defineSystem([Res(Time)], (time) => {
+ if (time.frameCount > 1) advanced += 1;
+ }));
+
+ await app.tick(1 / 60);
+ await app.tick(1 / 60);
+ await app.tick(1 / 60);
+ expect(frames).toBe(2);
+ expect(advanced).toBe(0);
+ });
+
+ it('fixedTick counts simulation steps where frameCount counts frames', async () => {
+ const app = App.new();
+ let ticks = 0;
+ let frameCount = 0;
+ app.addSystemToSchedule(Schedule.Last, defineSystem([Res(Time)], (time) => {
+ ticks = time.fixedTick;
+ frameCount = time.frameCount;
+ }));
+
+ await app.tick(3 / 60);
+ expect(ticks).toBe(3);
+ expect(frameCount).toBe(1);
+ });
+});