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(scene): a graph can change the scene, through the door every surface holds

esenginebe8c81edc4a1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 a
block 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 be
played 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 graph
diff --git a/desktop b/desktop
index 0a12d1587..ba6df0552 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 0a12d1587a0ec3621b20f100a1fa94077e7d7752
+Subproject commit ba6df055252c0b57d7620cf524c03e939d1dd84b
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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) => CommandsInstance
queueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => void
queueRemove: (entity: Entity, component: AnyComponentDef) => void
queueSetParent: (entity: Entity, parent: Entity) => void
+resource: <T>(def: ResourceDef<T>) => T | null
spawn: (name?: string) => EntityCommands
static new (world: World, resources: ResourceStorage): CommandsInstance
static prototype: CommandsInstance
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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) => CommandsInstance
queueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => void
queueRemove: (entity: Entity, component: AnyComponentDef) => void
queueSetParent: (entity: Entity, parent: Entity) => void
+resource: <T>(def: ResourceDef<T>) => T | null
spawn: (name?: string) => EntityCommands
static new (world: World, resources: ResourceStorage): CommandsInstance
static prototype: CommandsInstance
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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) => CommandsInstance
queueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => void
queueRemove: (entity: Entity, component: AnyComponentDef) => void
queueSetParent: (entity: Entity, parent: Entity) => void
+resource: <T>(def: ResourceDef<T>) => T | null
spawn: (name?: string) => EntityCommands
static new (world: World, resources: ResourceStorage): CommandsInstance
static prototype: CommandsInstance
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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) => CommandsInstance
queueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => void
queueRemove: (entity: Entity, component: AnyComponentDef) => void
queueSetParent: (entity: Entity, parent: Entity) => void
+resource: <T>(def: ResourceDef<T>) => T | null
spawn: (name?: string) => EntityCommands
static new (world: World, resources: ResourceStorage): CommandsInstance
static prototype: CommandsInstance
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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) => CommandsInstance
queueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => void
queueRemove: (entity: Entity, component: AnyComponentDef) => void
queueSetParent: (entity: Entity, parent: Entity) => void
+resource: <T>(def: ResourceDef<T>) => T | null
spawn: (name?: string) => EntityCommands
static new (world: World, resources: ResourceStorage): CommandsInstance
static prototype: CommandsInstance
diff --git a/sdk/src/ecs/commands.ts b/sdk/src/ecs/commands.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.mjs
index 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.' },