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(ecs): a project can register a system set, and a pause is one condition
esenginec3a4c25eaebc
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 theboot guard reads, the census `resource_census` reads, the log the consolediff --git a/examples/celestial-heights/assets/i18n/en.eslocale b/examples/celestial-heights/assets/i18n/en.eslocaleindex 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.eslocaleindex 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.essceneindex 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.essceneindex 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.mjsindex 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.tsindex 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 fromdiff --git a/examples/celestial-heights/src/main.ts b/examples/celestial-heights/src/main.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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; }>) => AppaddEvent: <T>(event: EventDef<T>) => AppaddPlugin: (plugin: Plugin) => AppaddPlugins: (plugins: Plugin[]) => App@@ -8795,6 +8795,11 @@ TransformData(system: SystemDef): void```+## addSystemSetToSchedule — function+```+(schedule: Schedule, set: SystemSet): void+```+## addSystemToSchedule — function```(schedule: Schedule, system: SystemDef): voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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; }>) => AppaddEvent: <T>(event: EventDef<T>) => AppaddPlugin: (plugin: Plugin) => AppaddPlugins: (plugins: Plugin[]) => App@@ -8988,6 +8988,11 @@ TransformData(system: SystemDef): void```+## addSystemSetToSchedule — function+```+(schedule: Schedule, set: SystemSet): void+```+## addSystemToSchedule — function```(schedule: Schedule, system: SystemDef): voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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; }>) => AppaddEvent: <T>(event: EventDef<T>) => AppaddPlugin: (plugin: Plugin) => AppaddPlugins: (plugins: Plugin[]) => App@@ -8790,6 +8790,11 @@ TransformData(system: SystemDef): void```+## addSystemSetToSchedule — function+```+(schedule: Schedule, set: SystemSet): void+```+## addSystemToSchedule — function```(schedule: Schedule, system: SystemDef): voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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; }>) => AppaddEvent: <T>(event: EventDef<T>) => AppaddPlugin: (plugin: Plugin) => AppaddPlugins: (plugins: Plugin[]) => App@@ -9035,6 +9035,11 @@ TransformData(system: SystemDef): void```+## addSystemSetToSchedule — function+```+(schedule: Schedule, set: SystemSet): void+```+## addSystemToSchedule — function```(schedule: Schedule, system: SystemDef): voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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; }>) => AppaddEvent: <T>(event: EventDef<T>) => AppaddPlugin: (plugin: Plugin) => AppaddPlugins: (plugins: Plugin[]) => App@@ -8817,6 +8817,11 @@ TransformData(system: SystemDef): void```+## addSystemSetToSchedule — function+```+(schedule: Schedule, set: SystemSet): void+```+## addSystemToSchedule — function```(schedule: Schedule, system: SystemDef): voiddiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 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.tsindex 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.tsindex 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): voidgetPendingSystems().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// =============================================================================