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.

fix(runtime): a subsystem several cells ask for at once is installed once

esenginef38e0768f7a6
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index e2b8c04f1..9ca34f060 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -455,6 +455,9 @@ async function boot(): Promise<void> {
}
return {
...report,
+ // Whether the 3D world is even up, so a zero body count cannot be read
+ // as "the cell brought none" when it means "physics never loaded".
+ physicsUp: physics !== undefined,
physicsBodies: physics?.bodies.size ?? 0,
physicsCharacters: physics?.characters.size ?? 0,
// Rows physics still keeps for entities the world no longer has. A
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index 50685a95f..f30b7f916 100644
--- a/sdk/src/runtime/runtimeLoader.ts
+++ b/sdk/src/runtime/runtimeLoader.ts
@@ -8,6 +8,7 @@
import { SceneOwner } from '../ecs/component';
import { loadSceneData, updateCameraAspectRatio, sceneHasPrefabEntries, expandScenePrefabs, type SceneData } from '../scene/scene';
import { recordSceneOrigins, enableSceneOrigins } from '../scene/sceneOrigins';
+import { defineResource } from '../ecs/resource';
import type { PrefabData } from '../prefab/types';
import { switchTheme, resolveThemeTokens, type ThemeOverrides } from '../ui';
import { discoverSceneAssets } from '../asset/discoverAssets';
@@ -249,6 +250,31 @@ export function sceneUsesI18n(sceneData: SceneData): boolean {
return false;
}
+/**
+ * Subsystem installs already in flight for this app.
+ *
+ * Every self-gating install below is a check, then an await for the module, then
+ * an addPlugin — and two scenes arriving in one tick both pass the check. World
+ * streaming makes that ordinary rather than rare.
+ */
+const SubsystemInstalls = defineResource<Map<string, Promise<void>>>(null!, 'SubsystemInstalls');
+
+/**
+ * Run `install` with no other caller for `key` inside it.
+ *
+ * The loop, rather than awaiting once: what finished was ANOTHER scene's
+ * install, and this one still has to decide against the world that left behind.
+ */
+async function installOnce(app: App, key: string, install: () => Promise<void>): Promise<void> {
+ if (!app.hasResource(SubsystemInstalls)) app.insertResource(SubsystemInstalls, new Map());
+ const inFlight = app.getResource(SubsystemInstalls);
+ let running = inFlight.get(key);
+ while (running) { await running; running = inFlight.get(key); }
+ const started = install().finally(() => { inFlight.delete(key); });
+ inFlight.set(key, started);
+ await started;
+}
+
/** True if any entity carries a physics component, or a TilemapLayer that may spawn
* colliders at runtime — either baked collidable tile ids (legacy scenes) or a
* `.estileset` reference, whose collision shapes derive live at load and are
@@ -380,6 +406,7 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis
if (!wantsPhysics) {
log.info('physics', 'not installed — not declared (features.physics) and scene has no physics components');
} else {
+ await installOnce(app, 'physics', async () => {
if (!physicsModule && app.sideModules) {
physicsModule = (await app.sideModules.acquire('physics')) as PhysicsWasmModule | null;
}
@@ -404,24 +431,28 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis
app.addPlugin(new Physics2DPlugin('', config, () => Promise.resolve(mod)));
log.info('physics', `installed (gravity ${gravity.x}, ${gravity.y})`);
}
+ });
}
// The 3D world gates itself the same way, on its own components and its own
// module: the two never share a solver, so a scene wanting one is not asking
// for the other.
- if (sceneUses3DPhysics(sceneData) && !app.getPlugin(Physics3DPlugin)) {
- const module3d = options.physics3dModule
- ?? (app.sideModules
- ? (await app.sideModules.acquire('physics3d')) as Physics3DWasmModule | null
- : null);
- if (!module3d) {
- log.warn('physics3d', 'scene has 3D physics components but no module loaded —'
- + ' this realm has no side-module host or physics3d.wasm failed to load');
- } else {
+ if (sceneUses3DPhysics(sceneData)) {
+ await installOnce(app, 'physics3d', async () => {
+ if (app.getPlugin(Physics3DPlugin)) return;
+ const module3d = options.physics3dModule
+ ?? (app.sideModules
+ ? (await app.sideModules.acquire('physics3d')) as Physics3DWasmModule | null
+ : null);
+ if (!module3d) {
+ log.warn('physics3d', 'scene has 3D physics components but no module loaded —'
+ + ' this realm has no side-module host or physics3d.wasm failed to load');
+ return;
+ }
const mod = module3d;
app.addPlugin(new Physics3DPlugin('', {}, () => Promise.resolve(mod)));
log.info('physics3d', 'installed');
- }
+ });
}
// Self-gating i18n, mirroring physics: a scene that binds Text.i18nKey needs
diff --git a/sdk/tests/concurrent-scene-subsystems.test.ts b/sdk/tests/concurrent-scene-subsystems.test.ts
new file mode 100644
index 000000000..5e0aa0d68
--- /dev/null
+++ b/sdk/tests/concurrent-scene-subsystems.test.ts
@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Two scenes arriving in one tick install one subsystem between them.
+ *
+ * Every self-gating install in the runtime loader is a check, an await for the
+ * module, then an addPlugin — and both scenes pass the check before either
+ * reaches the plugin. Scene switching made that rare; world streaming makes it
+ * ordinary, because a source stepping into a corner asks for several cells at
+ * once. Nine of them installed the 3D world nine times, and each install
+ * replaced the runtime resource the previous one's systems were writing into:
+ * 180 colliders live in the ECS and not one of them in the physics world.
+ */
+import { describe, it, expect } from 'vitest';
+import { loadRuntimeScene } from '../src/runtime/runtimeLoader';
+import { Physics3DPlugin } from '../src/physics3d/Physics3DPlugin';
+import { World } from '../src/ecs/world';
+import type { App } from '../src/app/app';
+import type { Backend } from '../src/asset/Backend';
+import type { ESEngineModule } from '../src/wasm';
+import type { SceneData } from '../src/scene/scene';
+
+const fakeModule = { _malloc: () => 0, _free: () => {} } as unknown as ESEngineModule;
+const fakeBackend = {
+ resolveUrl: (p: string) => p,
+ fetchText: async () => '',
+ fetchBinary: async () => new ArrayBuffer(0),
+} as unknown as Backend;
+
+/** A side-module host that takes a turn to answer — the window the race lives in. */
+function makeFakeApp(acquired: string[]) {
+ const resources = new Map<unknown, unknown>();
+ const plugins: object[] = [];
+ const app = {
+ world: new World(),
+ hasResource: (r: unknown) => resources.has(r),
+ getResource: (r: unknown) => resources.get(r),
+ insertResource: (r: unknown, v: unknown) => { resources.set(r, v); },
+ addPlugin: (p: object) => { plugins.push(p); },
+ getPlugin: (kind: abstract new (...args: never[]) => object) =>
+ plugins.find((p) => p instanceof kind) ?? null,
+ sideModules: {
+ acquire: async (id: string) => {
+ acquired.push(id);
+ await Promise.resolve();
+ await Promise.resolve();
+ return fakeModule;
+ },
+ },
+ } as unknown as App;
+ return { app, plugins };
+}
+
+/** A cell's worth of scene: one entity carrying a 3D body. */
+const cell = (name: string): SceneData => ({
+ version: '1.0',
+ name,
+ entities: [{
+ id: 1, name: 'Prop', parent: null, children: [], visible: true,
+ components: [{ type: 'RigidBody3D', data: { bodyType: 0 } }],
+ }],
+});
+
+const load = (app: App, sceneData: SceneData): Promise<void> => loadRuntimeScene({
+ app,
+ module: fakeModule,
+ sceneData,
+ source: {
+ backend: fakeBackend,
+ decodePixels: () => Promise.reject(new Error('no textures here')),
+ },
+ spineManager: null,
+});
+
+describe('subsystems a scene installs for itself', () => {
+ it('are installed once when several cells arrive together', async () => {
+ const acquired: string[] = [];
+ const { app, plugins } = makeFakeApp(acquired);
+
+ // Concurrently, which is what residency does: one reconciliation asks for
+ // every cell that came into range this frame.
+ await Promise.all([cell('c0'), cell('c1'), cell('c2'), cell('c3')].map((s) => load(app, s)));
+
+ const installed = plugins.filter((p) => p instanceof Physics3DPlugin);
+ expect(installed).toHaveLength(1);
+ expect(acquired.filter((id) => id === 'physics3d')).toHaveLength(1);
+ });
+
+ it('and a later cell reuses the one already there', async () => {
+ const acquired: string[] = [];
+ const { app, plugins } = makeFakeApp(acquired);
+ await load(app, cell('first'));
+ await load(app, cell('second'));
+ expect(plugins.filter((p) => p instanceof Physics3DPlugin)).toHaveLength(1);
+ });
+
+ it('installs for a cell that needs it even when the one before did not', async () => {
+ // The latch must not swallow a decision: the first scene has no bodies,
+ // so what it finished tells the second nothing about what IT needs.
+ const acquired: string[] = [];
+ const { app, plugins } = makeFakeApp(acquired);
+ const plain: SceneData = { version: '1.0', name: 'plain', entities: [] };
+ await Promise.all([load(app, plain), load(app, cell('withBodies'))]);
+ expect(plugins.filter((p) => p instanceof Physics3DPlugin)).toHaveLength(1);
+ });
+});
diff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjs
index 8a24c59ba..96fa15e45 100644
--- a/tools/launchers/residency-run.mjs
+++ b/tools/launchers/residency-run.mjs
@@ -238,6 +238,37 @@ async function main() {
continue;
}
if (step.do === 'tap') { await exec(tapScript(step.key, step.frames ?? 10)); continue; }
+ if (step.do === 'frames') {
+ // One frame at a time, timed INSIDE the page: a spike is a property of a
+ // frame, and measuring from outside adds a round trip to every sample.
+ // The key is tapped on the first one, so the profile starts at the gesture.
+ const profile = await exec(`(async () => {
+ const target = document.querySelector('canvas') ?? window;
+ const send = (type, code) => {
+ const e = new KeyboardEvent(type, { code, key: code, bubbles: true, cancelable: true });
+ target.dispatchEvent(e);
+ if (target !== window) window.dispatchEvent(new KeyboardEvent(type, { code, key: code, bubbles: true }));
+ };
+ ${step.key ? `send('keydown', ${JSON.stringify(step.key)});` : ''}
+ const out = [];
+ for (let i = 0; i < ${step.count ?? 120}; i++) {
+ const began = performance.now();
+ await window.__estellaCooked.step(1, 1 / 60);
+ const ms = Math.round((performance.now() - began) * 1000) / 1000;
+ ${step.key ? `if (i === 0) send('keyup', ${JSON.stringify(step.key)});` : ''}
+ const s = window.__estellaCooked.streaming();
+ out.push({ ms, resident: s.residentCells.length, loading: s.loadingCells.length,
+ entities: s.entities, bodies: s.physicsBodies, physicsUp: s.physicsUp });
+ // A macrotask turn between frames. Awaiting a step only drains
+ // MICROtasks, and a cell arrives over the network — so a loop without
+ // this starves the fetch and profiles a load that never lands.
+ await new Promise((settle) => setTimeout(settle, 0));
+ }
+ return out;
+ })()`);
+ console.log(`profile ${step.as}: ${JSON.stringify(profile)}`);
+ continue;
+ }
if (step.do === 'time') {
// Wall time for a batch of engine frames, with the clock already handed
// over: what a held world costs per frame, rather than what the runner had