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.

refactor(sdk): an entry point decides which optional subsystems it ships

esengine579c54db93ef
diff --git a/sdk/src/index.minigame.ts b/sdk/src/index.minigame.ts
index f7cf006b3..92043dfbd 100644
--- a/sdk/src/index.minigame.ts
+++ b/sdk/src/index.minigame.ts
@@ -43,6 +43,9 @@ 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';
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.ts
index e0f245efc..80ea9ead6 100644
--- a/sdk/src/index.native.ts
+++ b/sdk/src/index.native.ts
@@ -38,6 +38,9 @@ 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';
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.ts
index 526bc85eb..01d893e5f 100644
--- a/sdk/src/index.node.ts
+++ b/sdk/src/index.node.ts
@@ -28,6 +28,9 @@ 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';
export * from './runtime/webAppFactory';
export { nodeAdapter } from './platform/node';
diff --git a/sdk/src/index.ts b/sdk/src/index.ts
index ab01f7636..2f7f5319e 100644
--- a/sdk/src/index.ts
+++ b/sdk/src/index.ts
@@ -22,6 +22,9 @@ 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';
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.ts
index c218a2adf..2d988c4bf 100644
--- a/sdk/src/index.wechat.ts
+++ b/sdk/src/index.wechat.ts
@@ -20,6 +20,9 @@ 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';
export * from './runtime/webAppFactory';
export {
diff --git a/sdk/src/runtime/entryPlugins.ts b/sdk/src/runtime/entryPlugins.ts
new file mode 100644
index 000000000..5557eea37
--- /dev/null
+++ b/sdk/src/runtime/entryPlugins.ts
@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file entryPlugins.ts — what an entry point installs, held apart from the
+ * factory that reads it.
+ *
+ * Its own module because `webAppFactory` is re-exported wholesale by every SDK
+ * entry: a setter living there would be public API, and this is a seam between
+ * an entry and the factory, not something a game calls.
+ */
+import type { Plugin } from '../app/app';
+
+let make: () => Plugin[] = () => [];
+
+/** Called once, by `runtime/optionalPlugins`, for its side effect. */
+export function setEntryPlugins(fn: () => Plugin[]): void {
+ make = fn;
+}
+
+/** Fresh instances per app: a plugin carries per-app state once built. */
+export function entryPlugins(): Plugin[] {
+ return make();
+}
diff --git a/sdk/src/runtime/optionalPlugins.ts b/sdk/src/runtime/optionalPlugins.ts
new file mode 100644
index 000000000..9407f974a
--- /dev/null
+++ b/sdk/src/runtime/optionalPlugins.ts
@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file optionalPlugins.ts — the entry-point side of the optional subsystems.
+ *
+ * Importing this file IS the decision to ship Spine and DragonBones: it is the
+ * only place that reaches them from the runtime, so a build that leaves it out
+ * leaves their code out too. A mini-game inlines the SDK, and measured on
+ * examples/hello-world these two are 110KB of a package using neither.
+ *
+ * Every entry point imports it for its side effect. One that deliberately does
+ * not is a lean entry, and `check-entries-install-options` is what keeps the
+ * difference from being an accident.
+ */
+import { SpinePlugin } from '../spine';
+import { DragonBonesPlugin } from '../dragonbones';
+import { setEntryPlugins } from './entryPlugins';
+
+setEntryPlugins(() => [new SpinePlugin(), new DragonBonesPlugin()]);
diff --git a/sdk/src/runtime/webAppFactory.ts b/sdk/src/runtime/webAppFactory.ts
index a3af1a0c1..5685ce357 100644
--- a/sdk/src/runtime/webAppFactory.ts
+++ b/sdk/src/runtime/webAppFactory.ts
@@ -8,9 +8,11 @@ import { sceneManagerPlugin } from '../scene/scenePlugin';
import { seedEngineComponents } from '../ecs/component';
import { uiPlugins } from '../app/uiPlugins';
import { simulationBasePlugins, webBasePlugins } from '../app/pluginSets';
-import { SpinePlugin } from '../spine';
-import { DragonBonesPlugin } from '../dragonbones';
import { createFetchSideModuleHost, type SideModuleHost } from '../sideModules';
+// The optional subsystems an ENTRY installs. A mini-game inlines the SDK, so a
+// subsystem reached from here is in every package whether a project uses it or
+// not — 259KB of it, measured. See tools/check-core-carries-options.mjs.
+import { entryPlugins } from './entryPlugins';
export interface CreateWebAppOptions extends WebAppOptions {
@@ -28,16 +30,15 @@ export interface CreateWebAppOptions extends WebAppOptions {
// so the headless and native factories cannot drift from this one).
const basePlugins = webBasePlugins();
+
+
export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptions): App {
const sideModules: SideModuleHost | undefined = options?.sideModules
?? (options?.wasmBaseUrl ? createFetchSideModuleHost(options.wasmBaseUrl) : undefined);
- // SpinePlugin builds its per-version SpineManager from app.sideModules in build().
- const spinePlugin = new SpinePlugin();
- // DragonBones is beside it and costs nothing to install: it fetches its wasm
- // only when something asks for the manager, so a project with no DragonBones in
- // it never touches the side module.
- const dragonBonesPlugin = new DragonBonesPlugin();
- const plugins = [...uiPlugins, ...basePlugins, spinePlugin, dragonBonesPlugin, ...(options?.plugins ?? [])];
+ // Spine and DragonBones each fetch their wasm only when asked, so installing
+ // them costs nothing at RUN time. BUILD time is what they cost, which is why
+ // the entry decides and this does not.
+ const plugins = [...uiPlugins, ...basePlugins, ...entryPlugins(), ...(options?.plugins ?? [])];
return _createWebApp(module, { ...options, sideModules, plugins });
}
diff --git a/tools/baselines/core-carries-options.json b/tools/baselines/core-carries-options.json
index 37bc64edb..a8c1435d3 100644
--- a/tools/baselines/core-carries-options.json
+++ b/tools/baselines/core-carries-options.json
@@ -7,8 +7,6 @@
"sdk/src/runtime/runtimeLoader.ts -> ../spine/SpineManager",
"sdk/src/runtime/runtimeLoader.ts -> ../spine/SpinePlugin",
"sdk/src/runtime/runtimeLoader.ts -> ../spine/loadSpineScene",
- "sdk/src/runtime/runtimeLoader.ts -> ../video/VideoAPI",
- "sdk/src/runtime/webAppFactory.ts -> ../dragonbones",
- "sdk/src/runtime/webAppFactory.ts -> ../spine"
+ "sdk/src/runtime/runtimeLoader.ts -> ../video/VideoAPI"
]
}
diff --git a/tools/check-entries-install-options.mjs b/tools/check-entries-install-options.mjs
new file mode 100644
index 000000000..21903a789
--- /dev/null
+++ b/tools/check-entries-install-options.mjs
@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-entries-install-options.mjs — an SDK entry says whether it ships
+ * 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.
+ *
+ * So every entry either imports it or is listed here as lean, with a reason.
+ *
+ * node tools/check-entries-install-options.mjs
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+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';
+
+/** Entries that deliberately ship without the optional subsystems, and why. */
+const LEAN = {
+ // (none yet — the export-side lean entry lands with the runtimeLoader half)
+};
+
+const entries = readdirSync(SRC).filter((f) => /^index(\.[a-z0-9]+)?\.ts$/.test(f));
+if (entries.length === 0) {
+ console.error('check-entries-install-options: no sdk/src/index*.ts — the entries moved.');
+ process.exit(1);
+}
+
+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);
+}
+
+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.');
+ process.exit(1);
+}
+
+const lean = Object.keys(LEAN).length;
+console.log(`check-entries-install-options: ${entries.length} entry(ies) — ${entries.length - lean}`
+ + ` install the optional subsystems${lean > 0 ? `, ${lean} declared lean` : ''}.`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 79d33f338..426bba76a 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -138,6 +138,9 @@ export const GATES = [
// Every mini-game package carries the core runtime, so a subsystem the core
// imports is in every package whether the project uses it or not.
{ id: 'core-carries-options', run: 'node tools/check-core-carries-options.mjs' },
+ // …and the other half: an entry that forgets to install them ships an app whose
+ // Spine entities silently never animate.
+ { id: 'entries-install-options', run: 'node tools/check-entries-install-options.mjs' },
// Replication applies its inbox in arrival order, so reliable+ordered is a
// correctness condition. This compiles the claim: a transport that does not
// make it cannot reach replication.
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 4f5bce13e..a7088d714 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'refactor(sdk): an entry point decides which optional subsystems it ships':
+ { internal: 'The same plugins are installed; only which file names them changed.' },
+
"feat(gates): the core runtime's pull on optional subsystems is a ratchet":
{ internal: 'A repository gate over the SDK\'s own imports; no creator runs it.' },