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(sdk): a subsystem registers by being called, not by being imported
esengine211abb7b42b2
diff --git a/sdk/package.json b/sdk/package.jsonindex 046b44fbb..3fc8f61b5 100644--- a/sdk/package.json+++ b/sdk/package.json@@ -6,10 +6,17 @@"description": "Estella SDK - A fast 2D/3D game engine for Web, WeChat MiniGames and native platforms","sideEffects": ["./dist/index.js",+ "./dist/wasm.js","./dist/index.wechat.js",- "./dist/index.wechat.cjs.js",+ "./dist/index.minigame.js","./dist/index.node.js",- "./dist/index.native.js"+ "./dist/index.native.js",+ "./dist/dragonbones/index.js",+ "./dist/spine/index.js",+ "./dist/physics/index.js",+ "./dist/physics3d/index.js",+ "./dist/douyin/index.js",+ "./dist/index.wechat.cjs.js"],"main": "./dist/index.js","types": "./dist/index.d.ts",diff --git a/sdk/src/dragonbones/index.ts b/sdk/src/dragonbones/index.tsindex 480991541..e9b07919a 100644--- a/sdk/src/dragonbones/index.ts+++ b/sdk/src/dragonbones/index.ts@@ -24,16 +24,6 @@ export type { DragonBonesAssetInfo } from './loadDragonBonesScene';export type { RuntimeAssetSource } from '../runtime/runtimeAssets';// Importing this subpath INSTALLS DragonBones — see spine/index.ts.-import { addEntryPlugin } from '../runtime/entryPlugins';-import { setSceneOptionals } from '../runtime/sceneOptionals';-import { DragonBonesPlugin as DragonBonesPluginCtor } from './DragonBonesPlugin';-import { loadDragonBonesAssets, applyDragonBonesEntities } from './loadDragonBonesScene';+import { registerDragonBonesSupport } from './support';-addEntryPlugin(() => new DragonBonesPluginCtor());-setSceneOptionals({- dragonBones: {- acquire: async (app) => (await app.getPlugin(DragonBonesPluginCtor)?.acquire()) ?? null,- load: loadDragonBonesAssets,- apply: applyDragonBonesEntities,- },-});+registerDragonBonesSupport();diff --git a/sdk/src/dragonbones/support.ts b/sdk/src/dragonbones/support.tsnew file mode 100644index 000000000..59aaabca6--- /dev/null+++ b/sdk/src/dragonbones/support.ts@@ -0,0 +1,19 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/** @file support.ts — what a build that ships DragonBones tells the core about+ * it. A call, not a file's side effect — see spine/support.ts. */+import { addEntryPlugin } from '../runtime/entryPlugins';+import { setSceneOptionals } from '../runtime/sceneOptionals';+import { DragonBonesPlugin as DragonBonesPluginCtor } from './DragonBonesPlugin';+import { loadDragonBonesAssets, applyDragonBonesEntities } from './loadDragonBonesScene';++export function registerDragonBonesSupport(): void {+ addEntryPlugin(() => new DragonBonesPluginCtor());+ setSceneOptionals({+ dragonBones: {+ acquire: async (app) => (await app.getPlugin(DragonBonesPluginCtor)?.acquire()) ?? null,+ load: loadDragonBonesAssets,+ apply: applyDragonBonesEntities,+ },+ });+}diff --git a/sdk/src/index.minigame.ts b/sdk/src/index.minigame.tsindex 92043dfbd..dfca8df3f 100644--- a/sdk/src/index.minigame.ts+++ b/sdk/src/index.minigame.ts@@ -43,9 +43,11 @@ ensureBuiltinAiRegistrations();markEngineComponentBaseline();export * from './core';-// Installs Spine + DragonBones on every app this entry builds; a lean entry-// omits this import and ships without their code.-import './runtime/optionalPlugins';+// Installs every optional subsystem on the apps this entry builds; a lean entry+// does not call it and ships without their code.+import { installOptionalPlugins } from './runtime/optionalPlugins';++installOptionalPlugins();export * from './runtime/webAppFactory';// The family platform: describe the host as data, install, done.diff --git a/sdk/src/index.native.ts b/sdk/src/index.native.tsindex 80ea9ead6..fbfb3ad4b 100644--- a/sdk/src/index.native.ts+++ b/sdk/src/index.native.ts@@ -38,9 +38,11 @@ markEngineComponentBaseline();installNativeModuleRegistry();export * from './core';-// Installs Spine + DragonBones on every app this entry builds; a lean entry-// omits this import and ships without their code.-import './runtime/optionalPlugins';+// Installs every optional subsystem on the apps this entry builds; a lean entry+// does not call it and ships without their code.+import { installOptionalPlugins } from './runtime/optionalPlugins';++installOptionalPlugins();export * from './runtime/webAppFactory';export { NativePlatformAdapter, installNativePlatform, createHostBridge, assertHostEnvironment, assertNativeHost } from './platform/native';diff --git a/sdk/src/index.node.ts b/sdk/src/index.node.tsindex 01d893e5f..b793105d7 100644--- a/sdk/src/index.node.ts+++ b/sdk/src/index.node.ts@@ -28,9 +28,11 @@ ensureBuiltinAiRegistrations();markEngineComponentBaseline();export * from './core';-// Installs Spine + DragonBones on every app this entry builds; a lean entry-// omits this import and ships without their code.-import './runtime/optionalPlugins';+// Installs every optional subsystem on the apps this entry builds; a lean entry+// does not call it and ships without their code.+import { installOptionalPlugins } from './runtime/optionalPlugins';++installOptionalPlugins();export * from './runtime/webAppFactory';export { nodeAdapter } from './platform/node';diff --git a/sdk/src/index.ts b/sdk/src/index.tsindex 2f7f5319e..bfe712b1a 100644--- a/sdk/src/index.ts+++ b/sdk/src/index.ts@@ -22,9 +22,11 @@ ensureBuiltinAiRegistrations();markEngineComponentBaseline();export * from './core';-// Installs Spine + DragonBones on every app this entry builds; a lean entry-// omits this import and ships without their code.-import './runtime/optionalPlugins';+// Installs every optional subsystem on the apps this entry builds; a lean entry+// does not call it and ships without their code.+import { installOptionalPlugins } from './runtime/optionalPlugins';++installOptionalPlugins();export * from './runtime/webAppFactory';// ABI layout hash of the component schema this SDK bundle was generated from.diff --git a/sdk/src/index.wechat.ts b/sdk/src/index.wechat.tsindex 9ec684231..36bd46203 100644--- a/sdk/src/index.wechat.ts+++ b/sdk/src/index.wechat.ts@@ -8,6 +8,8 @@* subsystem. `index.wechat.lean` is the same base with none of them, for a* package that imports back only what its project uses.*/-import './runtime/optionalPlugins';+import { installOptionalPlugins } from './runtime/optionalPlugins';++installOptionalPlugins();export * from './index.wechat.base';diff --git a/sdk/src/physics/index.ts b/sdk/src/physics/index.tsindex 8bbd9df97..eb4df3b68 100644--- a/sdk/src/physics/index.ts+++ b/sdk/src/physics/index.ts@@ -114,15 +114,7 @@ export {} from './CharacterController2D';export { registerCharacterController2DSystem } from './CharacterController2DSystem';-// Importing this subpath INSTALLS 2D physics — see spine/index.ts. No entry-// plugin: the scene load builds it with the world config the project declared.-import { setSceneOptionals } from '../runtime/sceneOptionals';-import { Physics2DPlugin as Physics2DPluginCtor } from './Physics2DPlugin';+// Importing this subpath INSTALLS 2D physics — see spine/index.ts.+import { registerPhysics2DSupport } from './support';-setSceneOptionals({- physics: {- installed: (app) => !!app.getPlugin(Physics2DPluginCtor),- install: (app, config, module) =>- app.addPlugin(new Physics2DPluginCtor('', config, () => Promise.resolve(module))),- },-});+registerPhysics2DSupport();diff --git a/sdk/src/physics/support.ts b/sdk/src/physics/support.tsnew file mode 100644index 000000000..41e15b7c4--- /dev/null+++ b/sdk/src/physics/support.ts@@ -0,0 +1,19 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/** @file support.ts — what a build that ships 2D physics tells the core about+ * it. A call, not a file's side effect — see spine/support.ts.+ *+ * No entry plugin: the scene load builds it with the world config the+ * project declared. */+import { setSceneOptionals } from '../runtime/sceneOptionals';+import { Physics2DPlugin as Physics2DPluginCtor } from './Physics2DPlugin';++export function registerPhysics2DSupport(): void {+ setSceneOptionals({+ physics: {+ installed: (app) => !!app.getPlugin(Physics2DPluginCtor),+ install: (app, config, module) =>+ app.addPlugin(new Physics2DPluginCtor('', config, () => Promise.resolve(module))),+ },+ });+}diff --git a/sdk/src/physics3d/index.ts b/sdk/src/physics3d/index.tsindex 6a6165ad9..80822c9b9 100644--- a/sdk/src/physics3d/index.ts+++ b/sdk/src/physics3d/index.ts@@ -104,13 +104,6 @@ export {} from './ColliderShape3D';// Importing this subpath INSTALLS 3D physics — see spine/index.ts.-import { setSceneOptionals } from '../runtime/sceneOptionals';-import { Physics3DPlugin as Physics3DPluginCtor } from './Physics3DPlugin';+import { registerPhysics3DSupport } from './support';-setSceneOptionals({- physics3d: {- installed: (app) => !!app.getPlugin(Physics3DPluginCtor),- install: (app, module) =>- app.addPlugin(new Physics3DPluginCtor('', {}, () => Promise.resolve(module))),- },-});+registerPhysics3DSupport();diff --git a/sdk/src/physics3d/support.ts b/sdk/src/physics3d/support.tsnew file mode 100644index 000000000..6443552bc--- /dev/null+++ b/sdk/src/physics3d/support.ts@@ -0,0 +1,16 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/** @file support.ts — what a build that ships 3D physics tells the core about+ * it. A call, not a file's side effect — see spine/support.ts. */+import { setSceneOptionals } from '../runtime/sceneOptionals';+import { Physics3DPlugin as Physics3DPluginCtor } from './Physics3DPlugin';++export function registerPhysics3DSupport(): void {+ setSceneOptionals({+ physics3d: {+ installed: (app) => !!app.getPlugin(Physics3DPluginCtor),+ install: (app, module) =>+ app.addPlugin(new Physics3DPluginCtor('', {}, () => Promise.resolve(module))),+ },+ });+}diff --git a/sdk/src/runtime/optionalPlugins.ts b/sdk/src/runtime/optionalPlugins.tsindex 1c9bb0709..2d5324cd9 100644--- a/sdk/src/runtime/optionalPlugins.ts+++ b/sdk/src/runtime/optionalPlugins.ts@@ -3,25 +3,36 @@/*** @file optionalPlugins.ts — everything optional, for an entry that wants all of it.*- * Each subsystem installs itself when its own subpath is imported, so this file- * is only the list. An entry importing it ships them all; a lean entry imports- * the ones its project uses and carries no more — measured on- * examples/hello-world, that is none of them.+ * Each subsystem's support is a function, and this calls every one. It used to be+ * a list of `import '../spine'` lines reached by `import './runtime/optionalPlugins'`,+ * which reads as "importing this ships them" and is not what a bundler sees: a+ * bare side-effect import survives only where every layer has been told the file+ * is impure, and no layer had been. The code shipped and the registrations never+ * ran — the editor's play realm loaded a scene with 3D physics and no solver.+ *+ * An entry calling this ships them all; a lean entry calls the ones its project+ * uses and carries no more — measured on examples/hello-world, that is none.*/-import '../spine';-import '../dragonbones';-import '../physics';-import '../physics3d';import { VideoPlayer } from '../video/VideoAPI';import { setSceneOptionals } from './sceneOptionals';+import { registerSpineSupport } from '../spine/support';+import { registerDragonBonesSupport } from '../dragonbones/support';+import { registerPhysics2DSupport } from '../physics/support';+import { registerPhysics3DSupport } from '../physics3d/support';-// Video has no subpath of its own to be installed from, so it installs here.-setSceneOptionals({- video: {- setRefResolver: (app, resolve) => {- if (!app.hasResource(VideoPlayer)) return false;- app.getResource(VideoPlayer).setRefResolver(resolve);- return true;+export function installOptionalPlugins(): void {+ registerSpineSupport();+ registerDragonBonesSupport();+ registerPhysics2DSupport();+ registerPhysics3DSupport();+ // Video has no subpath of its own to be installed from, so it registers here.+ setSceneOptionals({+ video: {+ setRefResolver: (app, resolve) => {+ if (!app.hasResource(VideoPlayer)) return false;+ app.getResource(VideoPlayer).setRefResolver(resolve);+ return true;+ },},- },-});+ });+}diff --git a/sdk/src/runtime/sceneOptionals.ts b/sdk/src/runtime/sceneOptionals.tsindex a2a18c957..f3413909c 100644--- a/sdk/src/runtime/sceneOptionals.ts+++ b/sdk/src/runtime/sceneOptionals.ts@@ -64,7 +64,7 @@ let physics3d: Physics3DSupport | null = null;let video: VideoSupport | null = null;let dragonBones: DragonBonesSupport | null = null;-/** Called once by `runtime/optionalPlugins`, for its side effect. */+/** Called by each subsystem's `support.ts`, which an entry or a subpath calls. */export function setSceneOptionals(support: {spine?: SpineSupport;dragonBones?: DragonBonesSupport;diff --git a/sdk/src/spine/index.ts b/sdk/src/spine/index.tsindex 84f1fc679..0aa549c54 100644--- a/sdk/src/spine/index.ts+++ b/sdk/src/spine/index.ts@@ -34,16 +34,6 @@ export type { RuntimeAssetSource } from '../runtime/runtimeAssets';// Importing this subpath INSTALLS Spine: the core runtime names no optional// subsystem, so this is what puts it back, and a build that never imports it// ships none of the code below.-import { addEntryPlugin } from '../runtime/entryPlugins';-import { setSceneOptionals } from '../runtime/sceneOptionals';-import { SpinePlugin as SpinePluginCtor } from './SpinePlugin';-import { loadSpineAssets, applySpineEntities } from './loadSpineScene';+import { registerSpineSupport } from './support';-addEntryPlugin(() => new SpinePluginCtor());-setSceneOptionals({- spine: {- manager: (app) => app.getPlugin(SpinePluginCtor)?.spineManager ?? null,- load: loadSpineAssets,- apply: applySpineEntities,- },-});+registerSpineSupport();diff --git a/sdk/src/spine/support.ts b/sdk/src/spine/support.tsnew file mode 100644index 000000000..f099ff606--- /dev/null+++ b/sdk/src/spine/support.ts@@ -0,0 +1,33 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file support.ts — what a build that ships Spine tells the core about it.+ *+ * A CALL rather than this module's own side effect. The registration used to sit+ * at the top of `spine/index.ts` and was reached by `import '../spine'` — and a+ * bare side-effect import is invisible to a bundler unless every layer is told+ * the file is impure. Neither layer was: the SDK's own tree-shake declares every+ * non-entry module pure, and the package's `sideEffects` names only the entry+ * files, not the chunks they are built into. So the editor's play realm shipped+ * the code and never ran it, and a scene with 3D physics loaded without a solver.+ *+ * A function that someone calls is a value dependency, which no tree-shake in any+ * layer may drop.+ */+import { addEntryPlugin } from '../runtime/entryPlugins';+import { setSceneOptionals } from '../runtime/sceneOptionals';+import { SpinePlugin as SpinePluginCtor } from './SpinePlugin';+import { loadSpineAssets, applySpineEntities } from './loadSpineScene';++/** Idempotent: both the `esengine/spine` subpath and an entry that ships+ * everything call it, and a host may evaluate the bundle more than once. */+export function registerSpineSupport(): void {+ addEntryPlugin(() => new SpinePluginCtor());+ setSceneOptionals({+ spine: {+ manager: (app) => app.getPlugin(SpinePluginCtor)?.spineManager ?? null,+ load: loadSpineAssets,+ apply: applySpineEntities,+ },+ });+}diff --git a/sdk/tests/concurrent-scene-subsystems.test.ts b/sdk/tests/concurrent-scene-subsystems.test.tsindex 736975622..9a9e0fdca 100644--- a/sdk/tests/concurrent-scene-subsystems.test.ts+++ b/sdk/tests/concurrent-scene-subsystems.test.ts@@ -16,7 +16,9 @@ import { loadRuntimeScene } from '../src/runtime/runtimeLoader';// The optional subsystems are installed by an ENTRY, and this imports the loader// directly — so it says which environment it is testing rather than relying on// another test having imported one first.-import '../src/runtime/optionalPlugins';+import { installOptionalPlugins } from '../src/runtime/optionalPlugins';++installOptionalPlugins();import { Physics3DPlugin } from '../src/physics3d/Physics3DPlugin';import { World } from '../src/ecs/world';import type { App } from '../src/app/app';diff --git a/sdk/tests/video-ref-resolution.test.ts b/sdk/tests/video-ref-resolution.test.tsindex 2a9c68eb8..72f671932 100644--- a/sdk/tests/video-ref-resolution.test.ts+++ b/sdk/tests/video-ref-resolution.test.ts@@ -13,7 +13,9 @@ import { loadRuntimeScene } from '../src/runtime/runtimeLoader';// The optional subsystems are installed by an ENTRY, and this imports the loader// directly — so it says which environment it is testing rather than relying on// another test having imported one first.-import '../src/runtime/optionalPlugins';+import { installOptionalPlugins } from '../src/runtime/optionalPlugins';++installOptionalPlugins();import { VideoPlayer } from '../src/video/VideoAPI';import { World } from '../src/ecs/world';import type { App } from '../src/app/app';diff --git a/tools/check-entries-install-options.mjs b/tools/check-entries-install-options.mjsindex 9525fc69e..e8b629ac2 100644--- a/tools/check-entries-install-options.mjs+++ b/tools/check-entries-install-options.mjs@@ -5,11 +5,22 @@* the optional subsystems, and never leaves it to chance.** `createWebApp` no longer names Spine or DragonBones; an entry installs them by- * importing `runtime/optionalPlugins`. That is what makes them droppable — and- * also what makes forgetting the import silent: the app builds, the scene loads,- * and the Spine entities simply never animate.+ * CALLING `installOptionalPlugins()`. That is what makes them droppable — and+ * also what makes forgetting it silent: the app builds, the scene loads, and the+ * Spine entities simply never animate.*- * So every entry either imports it or is listed here as lean, with a reason.+ * The call is what counts, not the import. This gate read the import, and was+ * green through the whole time the registrations were being tree-shaken away:+ * `import './runtime/optionalPlugins'` was there in every entry and ran in none+ * of the built bundles, because a bare side-effect import is a file's private+ * business and a bundler is entitled to drop it.+ *+ * So every entry either calls it or is listed here as lean, with a reason.+ *+ * And every entry the package PUBLISHES is declared side-effectful, for the same+ * reason one layer down: `esengine/physics3d` registers 3D physics by being+ * imported, and a consumer's bundler drops an import whose bindings go unused+ * unless the package says that file is impure. Five of the eleven were not said.** node tools/check-entries-install-options.mjs*/@@ -20,6 +31,7 @@ import { fileURLToPath } from 'node:url';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');const SRC = path.join(ROOT, 'sdk', 'src');const INSTALLER = './runtime/optionalPlugins';+const CALL = 'installOptionalPlugins()';/** Entries that deliberately ship without the optional subsystems, and why. */const LEAN = {@@ -42,15 +54,35 @@ const missing = [];for (const file of entries) {if (file in LEAN) continue;const src = readFileSync(path.join(SRC, file), 'utf8');- if (!src.includes(`'${INSTALLER}'`) && !src.includes(`"${INSTALLER}"`)) missing.push(file);+ const imports = src.includes(`'${INSTALLER}'`) || src.includes(`"${INSTALLER}"`);+ if (!imports || !src.includes(CALL)) missing.push(file);}if (missing.length > 0) {console.error(`check-entries-install-options: ${missing.length} entry(ies) install no optional`+ ` subsystems and are not declared lean:\n`);for (const f of missing) console.error(` sdk/src/${f}`);- console.error(`\nAdd \`import '${INSTALLER}';\` so apps built from it carry Spine and`- + ' DragonBones, or list it in LEAN with the reason it ships without them.');+ console.error(`\nImport ${CALL.slice(0, -2)} from '${INSTALLER}' AND call it, so apps built`+ + ' from it carry Spine and DragonBones, or list it in LEAN with the reason it'+ + ' ships without them.');+ process.exit(1);+}++/**+ * An entry a consumer can import must be declared impure. Conservative on+ * purpose: an entry is the thing that initializes, and a consumer pays for one+ * only by importing it, so the question "does THIS entry have a side effect+ * today" is one the package should not have to keep answering correctly.+ */+const pkg = JSON.parse(readFileSync(path.join(ROOT, 'sdk', 'package.json'), 'utf8'));+const published = [...new Set(Object.values(pkg.exports ?? {})+ .map((e) => (typeof e === 'string' ? e : e?.import))+ .filter(Boolean))];+const undeclared = published.filter((e) => !(pkg.sideEffects ?? []).includes(e));+if (undeclared.length > 0) {+ console.error(`check-entries-install-options: ${undeclared.length} published entry(ies) are not`+ + ' in sdk/package.json "sideEffects", so a consumer\'s bundler may drop them whole:\n');+ for (const e of undeclared) console.error(` ${e}`);process.exit(1);}@@ -63,4 +95,5 @@ if (stale.length > 0) {process.exit(1);}console.log(`check-entries-install-options: ${entries.length} entry(ies) — ${entries.length - lean}`- + ` install the optional subsystems${lean > 0 ? `, ${lean} declared lean` : ''}.`);+ + ` install the optional subsystems${lean > 0 ? `, ${lean} declared lean` : ''};`+ + ` ${published.length} published entry(ies), all declared side-effectful.`);diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 2ec29784c..193fb131d 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,25 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'fix(sdk): a subsystem registers by being called, not by being imported':+ { note: 'A scene with 3D physics, Spine or DragonBones gets its runtime again in'+ + ' builds where a bundler had been dropping the registration.' },++ 'fix(api): a new component field is optional, so a frozen promise holds':+ { note: 'Sprite.drawMode is optional, so existing code that builds a SpriteData'+ + ' still compiles.' },++ 'feat(gates): a colour that names a thing only colours that thing':+ { internal: "A repository gate over the editor's own palette; no creator runs it." },++ 'fix(editor): a viewport colour names a thing, and four panels borrowed one':+ { note: 'Record, mute, delete, unsaved and a refused licence each read as what they'+ + ' are, instead of borrowing the viewport\'s colours.' },++ 'feat(editor): the build dialog offers Douyin, because the registry says it exists':+ { note: 'Douyin is selectable in the build dialog and has its own texture Import'+ + ' Settings tab.' },+"feat(gates): the visual layer's drift is measured, not just its contrast":{ internal: "A repository gate over the editor's own stylesheets and icons; no creator runs it." },