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(ecs): a project can register a system set, and a pause is one condition

esenginec3a4c25eaebc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 72e0e5770..bca2f90f7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,15 @@ published separately; it ships inside the editor.
### Added
+- **A project can register a system set, so a pause is one condition instead of
+ a flag checked in nine systems.** `defineSystemSet` takes a `runIf` and its own
+ documentation shows a pause as the example, but the only door to register one
+ was `App.addSystemSetToSchedule` — and a project's systems arrive through the
+ module-level `addSystemToSchedule`, which takes a single system. There is now a
+ module-level `addSystemSetToSchedule`, and the bundle drain expands a set into
+ its members, so everything downstream (hot reload included) still sees a flat
+ list of user systems.
+
- **Export Diagnostics: one document that answers "the editor crashed yesterday".**
Everything a reproduction needs was already in the process — the build stamp the
boot guard reads, the census `resource_census` reads, the log the console
diff --git a/examples/celestial-heights/assets/i18n/en.eslocale b/examples/celestial-heights/assets/i18n/en.eslocale
index b09ab9784..364460362 100644
--- a/examples/celestial-heights/assets/i18n/en.eslocale
+++ b/examples/celestial-heights/assets/i18n/en.eslocale
@@ -4,6 +4,7 @@
"entries": {
"area.main": "Cherry Blossom Landing",
"area.moonlit-gallery": "Moonlit Gallery",
- "hud.vitality": "Vitality"
+ "hud.vitality": "Vitality",
+ "menu.paused": "Paused"
}
}
diff --git a/examples/celestial-heights/assets/i18n/zh-CN.eslocale b/examples/celestial-heights/assets/i18n/zh-CN.eslocale
index a6e60a27a..0069ddbb0 100644
--- a/examples/celestial-heights/assets/i18n/zh-CN.eslocale
+++ b/examples/celestial-heights/assets/i18n/zh-CN.eslocale
@@ -4,6 +4,7 @@
"entries": {
"area.main": "樱林渡口",
"area.moonlit-gallery": "孤月回廊",
- "hud.vitality": "生命"
+ "hud.vitality": "生命",
+ "menu.paused": "已暂停"
}
}
diff --git a/examples/celestial-heights/assets/scenes/main.esscene b/examples/celestial-heights/assets/scenes/main.esscene
index 9e53ba2b3..10423e11c 100644
--- a/examples/celestial-heights/assets/scenes/main.esscene
+++ b/examples/celestial-heights/assets/scenes/main.esscene
@@ -798,7 +798,8 @@
"name": "Canvas",
"parent": null,
"children": [
- 51
+ 51,
+ 60
],
"visible": true,
"components": [
@@ -1010,6 +1011,116 @@
"data": {}
}
]
+ },
+ {
+ "id": 60,
+ "name": "PauseOverlay",
+ "parent": 50,
+ "children": [
+ 61
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "display": 1,
+ "insetLeft": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetRight": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetBottom": {
+ "value": 0,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "FlexContainer",
+ "data": {
+ "direction": 1,
+ "justifyContent": 1,
+ "alignItems": 1,
+ "gap": {
+ "x": 0,
+ "y": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.02,
+ "g": 0.016,
+ "b": 0.04,
+ "a": 0.62
+ },
+ "enabled": true
+ }
+ },
+ {
+ "type": "PauseOverlay",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 61,
+ "name": "PauseLabel",
+ "parent": 60,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "height": {
+ "value": 64,
+ "unit": 0
+ },
+ "width": {
+ "value": 600,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "",
+ "i18nKey": "menu.paused",
+ "fontSize": 56,
+ "bold": true,
+ "color": {
+ "r": 0.925,
+ "g": 0.906,
+ "b": 0.98,
+ "a": 1
+ },
+ "align": 1,
+ "verticalAlign": 1
+ }
+ }
+ ]
}
]
}
diff --git a/examples/celestial-heights/assets/scenes/moonlit-gallery.esscene b/examples/celestial-heights/assets/scenes/moonlit-gallery.esscene
index 1731881ca..161d0baa6 100644
--- a/examples/celestial-heights/assets/scenes/moonlit-gallery.esscene
+++ b/examples/celestial-heights/assets/scenes/moonlit-gallery.esscene
@@ -610,7 +610,8 @@
"name": "Canvas",
"parent": null,
"children": [
- 51
+ 51,
+ 60
],
"visible": true,
"components": [
@@ -822,6 +823,116 @@
"data": {}
}
]
+ },
+ {
+ "id": 60,
+ "name": "PauseOverlay",
+ "parent": 50,
+ "children": [
+ 61
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "display": 1,
+ "insetLeft": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetRight": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetBottom": {
+ "value": 0,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "FlexContainer",
+ "data": {
+ "direction": 1,
+ "justifyContent": 1,
+ "alignItems": 1,
+ "gap": {
+ "x": 0,
+ "y": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.02,
+ "g": 0.016,
+ "b": 0.04,
+ "a": 0.62
+ },
+ "enabled": true
+ }
+ },
+ {
+ "type": "PauseOverlay",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 61,
+ "name": "PauseLabel",
+ "parent": 60,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "height": {
+ "value": 64,
+ "unit": 0
+ },
+ "width": {
+ "value": 600,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "",
+ "i18nKey": "menu.paused",
+ "fontSize": 56,
+ "bold": true,
+ "color": {
+ "r": 0.925,
+ "g": 0.906,
+ "b": 0.98,
+ "a": 1
+ },
+ "align": 1,
+ "verticalAlign": 1
+ }
+ }
+ ]
}
]
}
diff --git a/examples/celestial-heights/engine-gaps.mjs b/examples/celestial-heights/engine-gaps.mjs
index 2afd07e36..dd1d6985e 100644
--- a/examples/celestial-heights/engine-gaps.mjs
+++ b/examples/celestial-heights/engine-gaps.mjs
@@ -31,4 +31,23 @@
*/
/** @type {Array<{id: string, hurts: string, workaround: string, fix: string, issue?: string, allows?: string[]}>} */
-export const GAPS = [];
+export const GAPS = [
+ {
+ id: 'no-simulation-pause',
+ hurts:
+ 'A pause stops only the project\'s own systems. Measured: with the overlay up, two '
+ + 'captures 80 frames apart differ across the WHOLE frame — the character controller '
+ + 'keeps integrating the velocity the player system last wrote, so Lyra walks on, and '
+ + 'the wisps keep pathing because perception, navigation and behaviour trees are '
+ + 'engine plugins outside any set a project can gate. A run condition reaches half '
+ + 'the loop, and the half it cannot reach is the simulation.',
+ workaround:
+ 'Gate the project\'s systems with a SystemSet runIf and show the overlay. Everything '
+ + 'the engine drives keeps running behind it.',
+ fix:
+ 'The runtime needs a paused simulation its own plugin systems honour — a Time scale '
+ + 'that everything integrating dt reads would do it, and Time has no scale today. '
+ + 'App.setPaused exists but runs only Schedule.Last, which stops UI layout too, so a '
+ + 'menu cannot be drawn while it is on.',
+ },
+];
diff --git a/examples/celestial-heights/src/components.ts b/examples/celestial-heights/src/components.ts
index d81f7dc09..c6e397c4b 100644
--- a/examples/celestial-heights/src/components.ts
+++ b/examples/celestial-heights/src/components.ts
@@ -24,6 +24,9 @@ export const NavGridBuilt = defineTag('NavGridBuilt');
/** The HUD bar that reports Lyra's health; its `UIVisual` fill follows her. */
export const VitalityMeter = defineTag('VitalityMeter');
+/** The panel shown while the game is paused. */
+export const PauseOverlay = defineTag('PauseOverlay');
+
/**
* Where the actor is facing, as a unit vector. Melee arcs and animation both
* read it, so it is written once per actor rather than derived twice from
diff --git a/examples/celestial-heights/src/main.ts b/examples/celestial-heights/src/main.ts
index f69cc4dff..ce212a9a0 100644
--- a/examples/celestial-heights/src/main.ts
+++ b/examples/celestial-heights/src/main.ts
@@ -1,12 +1,16 @@
-import { addSystemToSchedule, Schedule } from 'esengine';
+import {
+ addSystemToSchedule, addSystemSetToSchedule, defineSystemSet, Schedule,
+} from 'esengine';
import './components';
+import { session } from './state';
import { playerMoveSystem, playerAttackSystem } from './systems/player';
import {
meleeResolveSystem, damageSystem, invulnerabilitySystem, deathSystem,
} from './systems/combat';
import { healthBarSystem, hitFlashSystem, vitalityMeterSystem } from './systems/feedback';
import { cameraBindSystem, navFromTerrainSystem, gateSystem } from './systems/world';
+import { pauseInputSystem, pauseOverlaySystem } from './systems/pause';
import { cycleLanguageSystem } from './systems/settings';
import { perceiverFacingSystem } from './ai/wisp';
@@ -19,18 +23,25 @@ import { perceiverFacingSystem } from './ai/wisp';
addSystemToSchedule(Schedule.PreUpdate, navFromTerrainSystem);
addSystemToSchedule(Schedule.PreUpdate, cameraBindSystem);
-addSystemToSchedule(Schedule.Update, playerMoveSystem);
-addSystemToSchedule(Schedule.Update, playerAttackSystem);
-addSystemToSchedule(Schedule.Update, perceiverFacingSystem);
-addSystemToSchedule(Schedule.Update, gateSystem);
-addSystemToSchedule(Schedule.Update, cycleLanguageSystem);
+// Everything the pause freezes says so once, as a set with one run condition,
+// rather than the same paused check written into eight systems.
+addSystemSetToSchedule(Schedule.Update, defineSystemSet('gameplay', {
+ systems: [playerMoveSystem, playerAttackSystem, perceiverFacingSystem, gateSystem],
+ runIf: () => !session.paused,
+}));
// Damage resolves after everyone has decided to swing, and death after damage,
// so a hit lands in the frame it was thrown rather than the next one.
-addSystemToSchedule(Schedule.PostUpdate, meleeResolveSystem);
-addSystemToSchedule(Schedule.PostUpdate, damageSystem);
-addSystemToSchedule(Schedule.PostUpdate, deathSystem);
-addSystemToSchedule(Schedule.PostUpdate, invulnerabilitySystem);
+addSystemSetToSchedule(Schedule.PostUpdate, defineSystemSet('combat', {
+ systems: [meleeResolveSystem, damageSystem, deathSystem, invulnerabilitySystem],
+ runIf: () => !session.paused,
+}));
+
+// The pause itself and everything that reports state keep running: one has to be
+// able to lift the pause, the rest have to be able to show it.
+addSystemToSchedule(Schedule.Update, pauseInputSystem);
+addSystemToSchedule(Schedule.Update, cycleLanguageSystem);
+addSystemToSchedule(Schedule.PostUpdate, pauseOverlaySystem);
addSystemToSchedule(Schedule.PostUpdate, healthBarSystem);
addSystemToSchedule(Schedule.PostUpdate, vitalityMeterSystem);
addSystemToSchedule(Schedule.PostUpdate, hitFlashSystem);
diff --git a/examples/celestial-heights/src/state.ts b/examples/celestial-heights/src/state.ts
new file mode 100644
index 000000000..2c9a57df7
--- /dev/null
+++ b/examples/celestial-heights/src/state.ts
@@ -0,0 +1,7 @@
+/**
+ * Session state that is not a component: things a run condition asks about,
+ * which by definition cannot take a `World`.
+ */
+export const session = {
+ paused: false,
+};
diff --git a/examples/celestial-heights/src/systems/pause.ts b/examples/celestial-heights/src/systems/pause.ts
new file mode 100644
index 000000000..886d932e3
--- /dev/null
+++ b/examples/celestial-heights/src/systems/pause.ts
@@ -0,0 +1,28 @@
+import { defineSystem, Query, Mut, Res, Input, UINode, UIDisplay } from 'esengine';
+import { PauseOverlay } from '../components';
+import { session } from '../state';
+
+// Both systems stay OUT of the gameplay set: one has to be able to lift the
+// pause, and the other has to be able to draw it.
+
+// ENGINE-GAP(no-simulation-pause): this pause reaches the project's systems and
+// nothing the engine drives, so the world keeps moving behind the overlay.
+
+export const pauseInputSystem = defineSystem(
+ [Res(Input)],
+ (input) => {
+ if (input.isKeyPressed('Escape')) session.paused = !session.paused;
+ },
+ { name: 'PauseInputSystem' },
+);
+
+export const pauseOverlaySystem = defineSystem(
+ [Query(Mut(UINode), PauseOverlay)],
+ (overlays) => {
+ const display = session.paused ? UIDisplay.Flex : UIDisplay.None;
+ for (const [, node] of overlays) {
+ if (node.display !== display) node.display = display;
+ }
+ },
+ { name: 'PauseOverlaySystem' },
+);
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 30f7f5bc2..b73c371d8 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: 1480 stable · 17 beta · 1 deprecated
+Symbols: 1481 stable · 17 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -498,7 +498,7 @@ ComponentDef<any> | BuiltinComponentDef<any>
## App — class
```
-addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => App
+addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet; }>) => App
addEvent: <T>(event: EventDef<T>) => App
addPlugin: (plugin: Plugin) => App
addPlugins: (plugins: Plugin[]) => App
@@ -8795,6 +8795,11 @@ TransformData
(system: SystemDef): void
```
+## addSystemSetToSchedule — function
+```
+(schedule: Schedule, set: SystemSet): void
+```
+
## addSystemToSchedule — function
```
(schedule: Schedule, system: SystemDef): void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 523accf24..4680f8ed0 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: 1499 stable · 22 beta · 1 deprecated
+Symbols: 1500 stable · 22 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -498,7 +498,7 @@ ComponentDef<any> | BuiltinComponentDef<any>
## App — class
```
-addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => App
+addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet; }>) => App
addEvent: <T>(event: EventDef<T>) => App
addPlugin: (plugin: Plugin) => App
addPlugins: (plugins: Plugin[]) => App
@@ -8988,6 +8988,11 @@ TransformData
(system: SystemDef): void
```
+## addSystemSetToSchedule — function
+```
+(schedule: Schedule, set: SystemSet): void
+```
+
## addSystemToSchedule — function
```
(schedule: Schedule, system: SystemDef): void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 5a352b29d..060091b10 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: 1479 stable · 19 beta · 1 deprecated
+Symbols: 1480 stable · 19 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -493,7 +493,7 @@ ComponentDef<any> | BuiltinComponentDef<any>
## App — class
```
-addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => App
+addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet; }>) => App
addEvent: <T>(event: EventDef<T>) => App
addPlugin: (plugin: Plugin) => App
addPlugins: (plugins: Plugin[]) => App
@@ -8790,6 +8790,11 @@ TransformData
(system: SystemDef): void
```
+## addSystemSetToSchedule — function
+```
+(schedule: Schedule, set: SystemSet): void
+```
+
## addSystemToSchedule — function
```
(schedule: Schedule, system: SystemDef): void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 3f6d51834..57f60a765 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: 1500 stable · 17 beta · 1 deprecated
+Symbols: 1501 stable · 17 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -493,7 +493,7 @@ ComponentDef<any> | BuiltinComponentDef<any>
## App — class
```
-addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => App
+addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet; }>) => App
addEvent: <T>(event: EventDef<T>) => App
addPlugin: (plugin: Plugin) => App
addPlugins: (plugins: Plugin[]) => App
@@ -9035,6 +9035,11 @@ TransformData
(system: SystemDef): void
```
+## addSystemSetToSchedule — function
+```
+(schedule: Schedule, set: SystemSet): void
+```
+
## addSystemToSchedule — function
```
(schedule: Schedule, system: SystemDef): void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index e60b4768e..d748aa89d 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: 1490 stable · 17 beta · 1 deprecated
+Symbols: 1491 stable · 17 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -493,7 +493,7 @@ ComponentDef<any> | BuiltinComponentDef<any>
## App — class
```
-addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => App
+addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet; }>) => App
addEvent: <T>(event: EventDef<T>) => App
addPlugin: (plugin: Plugin) => App
addPlugins: (plugins: Plugin[]) => App
@@ -8817,6 +8817,11 @@ TransformData
(system: SystemDef): void
```
+## addSystemSetToSchedule — function
+```
+(schedule: Schedule, set: SystemSet): void
+```
+
## addSystemToSchedule — function
```
(schedule: Schedule, system: SystemDef): void
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index f410804f8..48e5f64c3 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -331,10 +331,18 @@ export class App {
* from user code only by which door they came through.
* @internal
*/
- addBundleSystems(entries: ReadonlyArray<{ schedule: number; system: SystemDef }>): this {
+ addBundleSystems(entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet }>): this {
this.addingBundleSystems_ = true;
try {
- for (const e of entries) this.addSystemToSchedule(e.schedule as Schedule, e.system);
+ for (const e of entries) {
+ // A set expands to its members here, so everything downstream —
+ // hot reload included — still sees a flat list of user systems.
+ if ((e.system as SystemSet)._kind === 'set') {
+ this.addSystemSetToSchedule(e.schedule as Schedule, e.system as SystemSet);
+ } else {
+ this.addSystemToSchedule(e.schedule as Schedule, e.system as SystemDef);
+ }
+ }
} finally {
this.addingBundleSystems_ = false;
}
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index fdf98a865..99eef62cf 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -344,6 +344,7 @@ export {
addSystem,
addStartupSystem,
addSystemToSchedule,
+ addSystemSetToSchedule,
GetWorld,
SystemRunner,
type GetWorldDescriptor,
diff --git a/sdk/src/ecs/system.ts b/sdk/src/ecs/system.ts
index 33dc28c7f..264060834 100644
--- a/sdk/src/ecs/system.ts
+++ b/sdk/src/ecs/system.ts
@@ -225,6 +225,15 @@ export function addSystemToSchedule(schedule: Schedule, system: SystemDef): void
getPendingSystems().push({ schedule, system });
}
+/**
+ * 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.
+ */
+export function addSystemSetToSchedule(schedule: Schedule, set: SystemSet): void {
+ getPendingSystems().push({ schedule, system: set });
+}
+
// =============================================================================
// System Runner
// =============================================================================