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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.jsonindex 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.mdindex 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: numberlinearDamping: number```-## RunCondition — type @experimental+## RunCondition — type @public```() => boolean```@@ -6048,7 +6048,7 @@ static new (host: SceneStreamHost, config?: SceneStreamingConfig): SceneStreaminstatic prototype: SceneStreamingController```-## Schedule — enum @experimental+## Schedule — enum @public```First = 1FixedPostUpdate = 12@@ -6748,17 +6748,17 @@ static new (world: World, resources: ResourceStorage, eventRegistry?: EventRegisstatic 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[] | undefinedrunBefore: string[] | undefined@@ -7367,12 +7367,12 @@ mask: number | undefinedset: number```-## Time — const @experimental+## Time — const @public```ResourceDef<TimeData>```-## TimeData — interface @experimental+## TimeData — interface @public```delta: numberelapsed: 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.mdindex 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: numberlinearDamping: number```-## RunCondition — type @experimental+## RunCondition — type @public```() => boolean```@@ -6241,7 +6241,7 @@ static new (host: SceneStreamHost, config?: SceneStreamingConfig): SceneStreaminstatic prototype: SceneStreamingController```-## Schedule — enum @experimental+## Schedule — enum @public```First = 1FixedPostUpdate = 12@@ -6941,17 +6941,17 @@ static new (world: World, resources: ResourceStorage, eventRegistry?: EventRegisstatic 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[] | undefinedrunBefore: string[] | undefined@@ -7560,12 +7560,12 @@ mask: number | undefinedset: number```-## Time — const @experimental+## Time — const @public```ResourceDef<TimeData>```-## TimeData — interface @experimental+## TimeData — interface @public```delta: numberelapsed: 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.mdindex 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: numberlinearDamping: number```-## RunCondition — type @experimental+## RunCondition — type @public```() => boolean```@@ -6043,7 +6043,7 @@ static new (host: SceneStreamHost, config?: SceneStreamingConfig): SceneStreaminstatic prototype: SceneStreamingController```-## Schedule — enum @experimental+## Schedule — enum @public```First = 1FixedPostUpdate = 12@@ -6743,17 +6743,17 @@ static new (world: World, resources: ResourceStorage, eventRegistry?: EventRegisstatic 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[] | undefinedrunBefore: string[] | undefined@@ -7362,12 +7362,12 @@ mask: number | undefinedset: number```-## Time — const @experimental+## Time — const @public```ResourceDef<TimeData>```-## TimeData — interface @experimental+## TimeData — interface @public```delta: numberelapsed: 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.mdindex 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: numberlinearDamping: number```-## RunCondition — type @experimental+## RunCondition — type @public```() => boolean```@@ -6288,7 +6288,7 @@ static new (host: SceneStreamHost, config?: SceneStreamingConfig): SceneStreaminstatic prototype: SceneStreamingController```-## Schedule — enum @experimental+## Schedule — enum @public```First = 1FixedPostUpdate = 12@@ -6988,17 +6988,17 @@ static new (world: World, resources: ResourceStorage, eventRegistry?: EventRegisstatic 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[] | undefinedrunBefore: string[] | undefined@@ -7607,12 +7607,12 @@ mask: number | undefinedset: number```-## Time — const @experimental+## Time — const @public```ResourceDef<TimeData>```-## TimeData — interface @experimental+## TimeData — interface @public```delta: numberelapsed: 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.mdindex 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: numberlinearDamping: number```-## RunCondition — type @experimental+## RunCondition — type @public```() => boolean```@@ -6050,7 +6050,7 @@ static new (host: SceneStreamHost, config?: SceneStreamingConfig): SceneStreaminstatic prototype: SceneStreamingController```-## Schedule — enum @experimental+## Schedule — enum @public```First = 1FixedPostUpdate = 12@@ -6750,17 +6750,17 @@ static new (world: World, resources: ResourceStorage, eventRegistry?: EventRegisstatic 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[] | undefinedrunBefore: string[] | undefined@@ -7369,12 +7369,12 @@ mask: number | undefinedset: number```-## Time — const @experimental+## Time — const @public```ResourceDef<TimeData>```-## TimeData — interface @experimental+## TimeData — interface @public```delta: numberelapsed: 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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);+ });+});