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
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.jsonindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.' },