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
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.tsindex 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. Adiff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.tsindex 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): Promisif (!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): Promisapp.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 needsdiff --git a/sdk/tests/concurrent-scene-subsystems.test.ts b/sdk/tests/concurrent-scene-subsystems.test.tsnew file mode 100644index 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.mjsindex 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