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(scene): a graph can change the scene, through the door every surface holds
esenginebe8c81edc4a1
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7659a5892..b67140912 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -74,6 +74,25 @@ published separately; it ships inside the editor.player moves, releases it and they stop, dodges and the score rises, chases ablock and the run ends, presses Space and it begins again on a clear board.+- **A graph can change the scene.** It is the one thing gameplay needs that no+ component can express — the write would retire the world the component lives+ in — so an authored surface could reach everything about a game except its+ shape: a menu that starts the level, a death that restarts it. `scene.load`+ and `scene.reload` close that, with the fade as a declared parameter.+ `reload` is its own verb rather than loading the active scene by name: asked+ for the scene already running, a switch does nothing, which is the right+ answer for a gate and the wrong one for every retry there is.++ What they reach through is the door every authored surface already holds.+ `Commands` carries the world's services as well as its structural edits, so+ `commands.resource(SceneManager)` is how an FSM hook, a behaviour-tree leaf,+ a graph node AND a `defineBehavior` reach one — the last of those could not+ reach a service at all before, which is why "switch scene" was a `defineSystem`+ holding `Res(SceneManager)` and nothing else. A service nobody installed+ answers `null` rather than materialising its default, so a verb in an app+ assembled without that plugin says so instead of acting on a value no plugin+ put there.+- **A sound anything authored can start.** An `AudioSource` could only ever beplayed by `playOnAwake`. Once the entity existed, nothing an author can reach— a state machine's hook, a behaviour tree's leaf, an event wire, a graphdiff --git a/desktop b/desktopindex 0a12d1587..ba6df0552 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 0a12d1587a0ec3621b20f100a1fa94077e7d7752+Subproject commit ba6df055252c0b57d7620cf524c03e939d1dd84bdiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex f4648667d..ac1c24220 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -2495,6 +2495,7 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstancequeueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => voidqueueRemove: (entity: Entity, component: AnyComponentDef) => voidqueueSetParent: (entity: Entity, parent: Entity) => void+resource: <T>(def: ResourceDef<T>) => T | nullspawn: (name?: string) => EntityCommandsstatic new (world: World, resources: ResourceStorage): CommandsInstancestatic prototype: CommandsInstancediff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 1e8173363..92d0bd77c 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -2495,6 +2495,7 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstancequeueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => voidqueueRemove: (entity: Entity, component: AnyComponentDef) => voidqueueSetParent: (entity: Entity, parent: Entity) => void+resource: <T>(def: ResourceDef<T>) => T | nullspawn: (name?: string) => EntityCommandsstatic new (world: World, resources: ResourceStorage): CommandsInstancestatic prototype: CommandsInstancediff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex a74ec0fd4..2d9b5828c 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -2490,6 +2490,7 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstancequeueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => voidqueueRemove: (entity: Entity, component: AnyComponentDef) => voidqueueSetParent: (entity: Entity, parent: Entity) => void+resource: <T>(def: ResourceDef<T>) => T | nullspawn: (name?: string) => EntityCommandsstatic new (world: World, resources: ResourceStorage): CommandsInstancestatic prototype: CommandsInstancediff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex d2564eef1..097e128b3 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -2490,6 +2490,7 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstancequeueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => voidqueueRemove: (entity: Entity, component: AnyComponentDef) => voidqueueSetParent: (entity: Entity, parent: Entity) => void+resource: <T>(def: ResourceDef<T>) => T | nullspawn: (name?: string) => EntityCommandsstatic new (world: World, resources: ResourceStorage): CommandsInstancestatic prototype: CommandsInstancediff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 4a774e03a..8d9cbe55e 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -2490,6 +2490,7 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstancequeueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => voidqueueRemove: (entity: Entity, component: AnyComponentDef) => voidqueueSetParent: (entity: Entity, parent: Entity) => void+resource: <T>(def: ResourceDef<T>) => T | nullspawn: (name?: string) => EntityCommandsstatic new (world: World, resources: ResourceStorage): CommandsInstancestatic prototype: CommandsInstancediff --git a/sdk/src/ecs/commands.ts b/sdk/src/ecs/commands.tsindex 324a21cf6..1735e9107 100644--- a/sdk/src/ecs/commands.ts+++ b/sdk/src/ecs/commands.ts@@ -228,6 +228,16 @@ export class CommandsInstance {return this;}+ /**+ * A world-level service, for the work no component write can express.+ * Null where nothing installed it — an app assembled without that plugin+ * is a fact to report, not a crash. Here rather than on each context+ * because this is the one door every authored surface already holds.+ */+ resource<T>(def: ResourceDef<T>): T | null {+ return this.resources_.has(def) ? this.resources_.get(def) : null;+ }+insertResource<T>(resource: ResourceDef<T>, value: T): this {this.pending_.push({type: 'insert_resource',diff --git a/sdk/src/scene/ai-builtins.ts b/sdk/src/scene/ai-builtins.tsnew file mode 100644index 000000000..2139f4bcb--- /dev/null+++ b/sdk/src/scene/ai-builtins.ts@@ -0,0 +1,70 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file scene/ai-builtins.ts+ * @brief The `.esfsm` / `.esbt` / `.esgraph` → SceneManager bridge.+ *+ * Changing scene is the one thing gameplay needs that no component can express:+ * it retires the world those components live in. Registered from the scene side+ * (scene → ai, one direction) so the `ai` module never learns about scenes;+ * idempotent and namespaced, so game-registered names win.+ */++import { aiRegistry, type AiContext } from '../ai/fsm/AiContext';+import type { AiParamDef, AiParamValue, AiParams } from '../ai/fsm/registry';+import { SceneManager, type SceneManagerState, type TransitionOptions } from './sceneManager';+import { log } from '../util/logger';++const FADE: AiParamDef = {+ name: 'fade',+ type: 'number',+ tooltip: 'Seconds to fade through; 0 cuts straight over',+};++/**+ * Register the scene verbs. Idempotent (and safe after an `aiRegistry.clear()`):+ * each name registers only if absent.+ */+export function ensureSceneAiRegistrations(): void {+ verb('scene.load', [{ name: 'scene', type: 'string' }, FADE], (scenes, params) => {+ const name = typeof params?.scene === 'string' ? params.scene.trim() : '';+ if (!name) return;+ void scenes.switchTo(name, transitionOf(params?.fade));+ });++ // Not `scene.load` of the scene already running: asked for that, switchTo+ // does nothing — the right answer for a gate and the wrong one for every+ // death, retry and restart there is.+ verb('scene.reload', [FADE], (scenes, params) => {+ void scenes.reload(transitionOf(params?.fade));+ });+}++function verb(+ name: string,+ params: readonly AiParamDef[],+ run: (scenes: SceneManagerState, params: AiParams | undefined) => void,+): void {+ if (aiRegistry.hasAction(name)) return;+ aiRegistry.registerAction(name, {+ params,+ // It retires every entity there is; nothing narrower would be honest.+ touches: { opaque: true },+ run: (ctx: AiContext, _bb, _arg, given) => {+ // An event can fire before the first frame has handed the interpreter+ // its commands, and a verb reached that early has no door yet.+ const scenes = ctx.commands?.resource(SceneManager) ?? null;+ if (!scenes) {+ log.warn('scene', `${name}: no SceneManager to reach`);+ return;+ }+ run(scenes, given);+ },+ });+}++/** A fade of `seconds`, or an immediate cut when there is none to speak of. */+function transitionOf(seconds: AiParamValue | undefined): TransitionOptions | undefined {+ const duration = Number(seconds ?? 0);+ return duration > 0 ? { transition: 'fade', duration } : undefined;+}diff --git a/sdk/src/scene/scenePlugin.ts b/sdk/src/scene/scenePlugin.tsindex f41768e44..7ee47d45f 100644--- a/sdk/src/scene/scenePlugin.ts+++ b/sdk/src/scene/scenePlugin.ts@@ -16,6 +16,7 @@ import { playModeOnly } from '../ecs/env';import type { SystemDef } from '../ecs/system';import type { World } from '../ecs/world';import { log } from '../util/logger';+import { ensureSceneAiRegistrations } from './ai-builtins';const sceneTransitionSystem = defineSystem([ResMut(SceneManager), Res(Time)],@@ -49,6 +50,7 @@ export const sceneManagerPlugin: Plugin = {name: 'sceneManager',profileDomain: 'scene',build(app: App): void {+ ensureSceneAiRegistrations();const state = new SceneManagerState(app);app.insertResource(SceneManager, state);app.insertResource(SceneStreaming, new SceneStreamingController(state));diff --git a/sdk/tests/scene-verbs.test.ts b/sdk/tests/scene-verbs.test.tsnew file mode 100644index 000000000..73757eebd--- /dev/null+++ b/sdk/tests/scene-verbs.test.ts@@ -0,0 +1,83 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file scene-verbs.test.ts+ * @brief Changing scene from an authored surface — the one thing gameplay+ * needs that no component write can express.+ */+import { describe, it, expect, vi, beforeEach } from 'vitest';+import { aiRegistry } from '../src/ai/fsm/AiContext';+import { Blackboard } from '../src/ai/fsm/Blackboard';+import { ensureSceneAiRegistrations } from '../src/scene/ai-builtins';+import { SceneManager, type SceneManagerState } from '../src/scene/sceneManager';+import { CommandsInstance } from '../src/ecs/commands';+import { ResourceStorage, defineResource } from '../src/ecs/resource';+import type { World } from '../src/ecs/world';++function sceneManager() {+ return {+ switchTo: vi.fn().mockResolvedValue(undefined),+ reload: vi.fn().mockResolvedValue(undefined),+ } as unknown as SceneManagerState;+}++/** A context carrying only what these verbs reach for: the commands door. */+function ctxWith(scenes: SceneManagerState | null) {+ const resources = new ResourceStorage();+ if (scenes) resources.insert(SceneManager, scenes);+ const commands = new CommandsInstance({} as World, resources);+ return { commands } as never;+}++beforeEach(() => {+ aiRegistry.clear();+ ensureSceneAiRegistrations();+});++describe('the scene verbs', () => {+ it('switches to the scene it names, cutting straight over by default', () => {+ const scenes = sceneManager();+ aiRegistry.getAction('scene.load')!(ctxWith(scenes), new Blackboard(), 'level-2');+ expect(scenes.switchTo).toHaveBeenCalledWith('level-2', undefined);+ });++ it('fades for the seconds it is given', () => {+ const scenes = sceneManager();+ aiRegistry.getAction('scene.load')!(ctxWith(scenes), new Blackboard(), undefined, { scene: 'menu', fade: 0.6 });+ expect(scenes.switchTo).toHaveBeenCalledWith('menu', { transition: 'fade', duration: 0.6 });+ });++ it('reloads the running scene, which switchTo cannot express', () => {+ const scenes = sceneManager();+ aiRegistry.getAction('scene.reload')!(ctxWith(scenes), new Blackboard());+ expect(scenes.reload).toHaveBeenCalledWith(undefined);+ });++ it('says so, instead of throwing, in an app with no scene manager', () => {+ expect(() => aiRegistry.getAction('scene.load')!(ctxWith(null), new Blackboard(), 'level-2')).not.toThrow();+ });++ it('does nothing when no scene is named', () => {+ const scenes = sceneManager();+ aiRegistry.getAction('scene.load')!(ctxWith(scenes), new Blackboard(), ' ');+ expect(scenes.switchTo).not.toHaveBeenCalled();+ });+});++describe('the commands door to a service', () => {+ const Clock = defineResource({ hour: 9 }, 'TestClock');++ it('hands back what a plugin installed', () => {+ const resources = new ResourceStorage();+ resources.insert(Clock, { hour: 11 });+ expect(new CommandsInstance({} as World, resources).resource(Clock)).toEqual({ hour: 11 });+ });++ it('answers null for a service nobody installed, not its default', () => {+ // Reading through `get` would MATERIALISE the default and report the+ // service present — so a verb would act on a value no plugin ever put+ // there instead of saying the app has none.+ const resources = new ResourceStorage();+ expect(new CommandsInstance({} as World, resources).resource(Clock)).toBeNull();+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex c2a041dbf..c99cf3342 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,12 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'feat(scene): a graph can change the scene, through the door every surface holds':+ { note: 'A graph can change the scene.' },++ 'feat(scene): the scene verbs describe themselves in the palettes':+ { note: 'A graph can change the scene.' },+'feat(audio): a sound anything authored can start':{ note: 'A sound anything authored can start.' },