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): the scene loader asks for Spine and DragonBones, and does not name them

esenginef79a25ea3da4
diff --git a/sdk/src/runtime/optionalPlugins.ts b/sdk/src/runtime/optionalPlugins.ts
index 9407f974a..1aff76208 100644
--- a/sdk/src/runtime/optionalPlugins.ts
+++ b/sdk/src/runtime/optionalPlugins.ts
@@ -14,6 +14,26 @@
*/
import { SpinePlugin } from '../spine';
import { DragonBonesPlugin } from '../dragonbones';
+import { loadSpineAssets, applySpineEntities } from '../spine/loadSpineScene';
+import {
+ loadDragonBonesAssets, applyDragonBonesEntities,
+} from '../dragonbones/loadDragonBonesScene';
import { setEntryPlugins } from './entryPlugins';
+import { setSceneOptionals } from './sceneOptionals';
setEntryPlugins(() => [new SpinePlugin(), new DragonBonesPlugin()]);
+
+// The scene-load half: the loader reaches these only when a scene actually holds
+// a skeleton, so shipping them was always about bytes rather than behaviour.
+setSceneOptionals({
+ spine: {
+ manager: (app) => app.getPlugin(SpinePlugin)?.spineManager ?? null,
+ load: loadSpineAssets,
+ apply: applySpineEntities,
+ },
+ dragonBones: {
+ acquire: async (app) => (await app.getPlugin(DragonBonesPlugin)?.acquire()) ?? null,
+ load: loadDragonBonesAssets,
+ apply: applyDragonBonesEntities,
+ },
+});
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index d667b9944..9fb63ccb2 100644
--- a/sdk/src/runtime/runtimeLoader.ts
+++ b/sdk/src/runtime/runtimeLoader.ts
@@ -15,13 +15,12 @@ import { switchTheme, resolveThemeTokens, type ThemeOverrides } from '../ui';
import { discoverSceneAssets } from '../asset/discoverAssets';
import type { ESEngineModule } from '../wasm';
import type { SpineWasmModule } from '../spine/SpineModuleLoader';
-import { SpineManager } from '../spine/SpineManager';
+import type { SpineManager } from '../spine/SpineManager';
import type { PhysicsWasmModule } from '../physics/PhysicsModuleLoader';
import { Physics2DPlugin, type Physics2DPluginConfig } from '../physics/Physics2DPlugin';
import type { Physics3DWasmModule } from '../physics3d/Physics3DModule';
import { Physics3DPlugin } from '../physics3d/Physics3DPlugin';
import { applyAudioProjectConfig, type AudioProjectConfig } from '../audio/AudioProjectConfig';
-import { SpinePlugin } from '../spine/SpinePlugin';
import type { App } from '../app/app';
import { Assets as AssetsClass } from '../asset/Assets';
import { Assets as AssetsResource } from '../asset/AssetPlugin';
@@ -49,11 +48,11 @@ import { requireResourceManager } from '../wasm/resourceManager';
import { log } from '../util/logger';
import type { AotManifest } from '../ecs/aot/AotSystems';
import { type RuntimeAssetSource, type TextureParams } from './runtimeAssets';
-import { loadSpineAssets, applySpineEntities, type SpineAssetInfo } from '../spine/loadSpineScene';
+import type { SpineAssetInfo } from '../spine/loadSpineScene';
import type { SceneAssetResult } from '../asset/Assets';
-import { DragonBonesPlugin } from '../dragonbones/DragonBonesPlugin';
import type { DragonBonesManager } from '../dragonbones/DragonBonesManager';
-import { loadDragonBonesAssets, applyDragonBonesEntities, type DragonBonesAssetInfo } from '../dragonbones/loadDragonBonesScene';
+import { spineSupport, dragonBonesSupport } from './sceneOptionals';
+import type { DragonBonesAssetInfo } from '../dragonbones/loadDragonBonesScene';
import type { AddressableManifest, ManifestModel } from '../asset/AddressableManifest';
import type { Catalog } from '../asset/Catalog';
@@ -350,7 +349,8 @@ export async function prepareRuntimeScene(
// app.sideModules host); read it from there so every realm — play / playable /
// wechat — loads spine assets through one manager. An explicit option still
// wins for headless/tests.
- const spineManager = options.spineManager ?? app.getPlugin(SpinePlugin)?.spineManager ?? null;
+ const spine = spineSupport();
+ const spineManager = options.spineManager ?? spine?.manager(app) ?? null;
// Expand prefab instances up front: an exported scene keeps them as a prefab
// ref + overrides (the cook does not flatten them), and the rest of this
@@ -426,9 +426,9 @@ export async function prepareRuntimeScene(
// Prepared by the realm, owned by the scene: the receipts join the scope
// this scene gives back, and a second scene of one spine asset joins its era
// instead of uploading its pages again.
- const spineAssetInfo = app.sideModules
- ? await loadSpineAssets(module, source, spineManager, discovered.spines, transcoderProvider,
- { assets: sceneAssets, scope: assetResult.scope })
+ const spineAssetInfo = app.sideModules && spine
+ ? await spine.load(module, source, spineManager, discovered.spines, transcoderProvider,
+ { assets: sceneAssets, scope: assetResult.scope })
: new Map<string, SpineAssetInfo>();
// DragonBones, the same two phases. The manager is acquired only when the
@@ -441,11 +441,11 @@ export async function prepareRuntimeScene(
log.warn('scene', `${discovered.dragonBones.length} DragonBones asset(s) skipped — `
+ 'this realm has no optional-module host to load the DragonBones runtime from');
} else {
- dragonBonesManager = (await app.getPlugin(DragonBonesPlugin)?.acquire()) ?? null;
+ dragonBonesManager = (await dragonBonesSupport()?.acquire(app)) ?? null;
if (!dragonBonesManager) {
log.warn('scene', 'DragonBones assets present but the runtime could not be loaded');
} else {
- dragonBonesAssetInfo = await loadDragonBonesAssets(
+ dragonBonesAssetInfo = await dragonBonesSupport()!.load(
module, source, discovered.dragonBones, transcoderProvider);
}
}
@@ -617,12 +617,13 @@ export async function publishRuntimeScene(
mark('transform', () => module.transform_update(cppRegistry));
}
- if (spineManager && cppRegistry) {
- await timed('spine', () => applySpineEntities({ spineManager, sceneData, entityMap, registry: cppRegistry, assetInfo: spineAssetInfo }));
+ const spine = spineSupport();
+ if (spineManager && cppRegistry && spine) {
+ await timed('spine', () => spine.apply({ spineManager, sceneData, entityMap, registry: cppRegistry, assetInfo: spineAssetInfo }));
}
if (dragonBonesManager) {
- mark('dragonbones', () => applyDragonBonesEntities({
+ mark('dragonbones', () => dragonBonesSupport()!.apply({
manager: dragonBonesManager, sceneData, entityMap, assetInfo: dragonBonesAssetInfo,
}));
}
diff --git a/sdk/src/runtime/sceneOptionals.ts b/sdk/src/runtime/sceneOptionals.ts
new file mode 100644
index 000000000..f755ec36c
--- /dev/null
+++ b/sdk/src/runtime/sceneOptionals.ts
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file sceneOptionals.ts — the optional subsystems a scene load reaches, held
+ * behind a seam so the loader does not name them.
+ *
+ * `runtimeLoader` is in every package, so a subsystem it imports by value is in
+ * every package too — 110KB of Spine and DragonBones in a project with neither,
+ * measured on examples/hello-world. Every use of them here is already behind a
+ * test (`discovered.spines.length > 0`), so the code was never RUN; it was only
+ * ever shipped.
+ *
+ * The signatures are `Parameters<typeof …>` rather than spelled out: this is a
+ * seam over the real functions, and a seam that restates their arguments is the
+ * second declaration that drifts.
+ */
+import type { App } from '../app/app';
+import type { SpineManager } from '../spine/SpineManager';
+import type { loadSpineAssets, applySpineEntities } from '../spine/loadSpineScene';
+import type { DragonBonesManager } from '../dragonbones/DragonBonesManager';
+import type {
+ loadDragonBonesAssets, applyDragonBonesEntities,
+} from '../dragonbones/loadDragonBonesScene';
+
+/** What a scene load needs from Spine, when the build ships it. */
+export interface SpineSupport {
+ /** The realm's manager, owned by SpinePlugin — null when it is not installed. */
+ manager(app: App): SpineManager | null;
+ load(...args: Parameters<typeof loadSpineAssets>): ReturnType<typeof loadSpineAssets>;
+ apply(...args: Parameters<typeof applySpineEntities>): ReturnType<typeof applySpineEntities>;
+}
+
+/** What a scene load needs from DragonBones, when the build ships it. */
+export interface DragonBonesSupport {
+ acquire(app: App): Promise<DragonBonesManager | null>;
+ load(...args: Parameters<typeof loadDragonBonesAssets>): ReturnType<typeof loadDragonBonesAssets>;
+ apply(...args: Parameters<typeof applyDragonBonesEntities>): ReturnType<typeof applyDragonBonesEntities>;
+}
+
+let spine: SpineSupport | null = null;
+let dragonBones: DragonBonesSupport | null = null;
+
+/** Called once by `runtime/optionalPlugins`, for its side effect. */
+export function setSceneOptionals(
+ support: { spine?: SpineSupport; dragonBones?: DragonBonesSupport },
+): void {
+ if (support.spine) spine = support.spine;
+ if (support.dragonBones) dragonBones = support.dragonBones;
+}
+
+/** Null in a build that does not ship Spine — a scene holding one then loads
+ * without it rather than failing, which is what a lean build IS. */
+export const spineSupport = (): SpineSupport | null => spine;
+
+/** Null in a build that does not ship DragonBones. */
+export const dragonBonesSupport = (): DragonBonesSupport | null => dragonBones;
diff --git a/sdk/tests/entry-installs-optionals.test.ts b/sdk/tests/entry-installs-optionals.test.ts
new file mode 100644
index 000000000..367655f7e
--- /dev/null
+++ b/sdk/tests/entry-installs-optionals.test.ts
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+
+// Removing Spine support left all 560 test files green, and the failure is
+// silent: the scene loads and Spine entities simply never animate.
+import { describe, it, expect } from 'vitest';
+import { spineSupport, dragonBonesSupport } from '../src/runtime/sceneOptionals';
+import '../src/index';
+
+describe('an SDK entry installs the optional subsystems', () => {
+ it('gives the scene loader a way to load and apply Spine', () => {
+ const spine = spineSupport();
+ expect(spine, 'importing the entry must install Spine support').not.toBeNull();
+ expect(typeof spine!.manager).toBe('function');
+ expect(typeof spine!.load).toBe('function');
+ expect(typeof spine!.apply).toBe('function');
+ });
+
+ it('gives the scene loader a way to acquire and apply DragonBones', () => {
+ const db = dragonBonesSupport();
+ expect(db, 'importing the entry must install DragonBones support').not.toBeNull();
+ expect(typeof db!.acquire).toBe('function');
+ expect(typeof db!.load).toBe('function');
+ expect(typeof db!.apply).toBe('function');
+ });
+
+ it('installs the plugins createWebApp used to name itself', async () => {
+ const { entryPlugins } = await import('../src/runtime/entryPlugins');
+ const names = entryPlugins().map((p) => p.constructor.name);
+ expect(names).toContain('SpinePlugin');
+ expect(names).toContain('DragonBonesPlugin');
+ });
+
+ it('builds a fresh plugin instance per app, since a plugin carries app state', async () => {
+ const { entryPlugins } = await import('../src/runtime/entryPlugins');
+ expect(entryPlugins()[0]).not.toBe(entryPlugins()[0]);
+ });
+});
diff --git a/tools/baselines/core-carries-options.json b/tools/baselines/core-carries-options.json
index a8c1435d3..276cc3c13 100644
--- a/tools/baselines/core-carries-options.json
+++ b/tools/baselines/core-carries-options.json
@@ -1,12 +1,7 @@
{
"edges": [
- "sdk/src/runtime/runtimeLoader.ts -> ../dragonbones/DragonBonesPlugin",
- "sdk/src/runtime/runtimeLoader.ts -> ../dragonbones/loadDragonBonesScene",
"sdk/src/runtime/runtimeLoader.ts -> ../physics/Physics2DPlugin",
"sdk/src/runtime/runtimeLoader.ts -> ../physics3d/Physics3DPlugin",
- "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"
]
}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index a7088d714..0b41a674a 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): the scene loader asks for Spine and DragonBones, and does not name them':
+ { internal: 'Same subsystems, same behaviour; only which file reaches them changed.' },
+
'refactor(sdk): an entry point decides which optional subsystems it ships':
{ internal: 'The same plugins are installed; only which file names them changed.' },