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