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 core runtime names no optional subsystem at all

esengined23d3145b2ef
diff --git a/sdk/src/runtime/optionalPlugins.ts b/sdk/src/runtime/optionalPlugins.ts
index 1aff76208..03704c099 100644
--- a/sdk/src/runtime/optionalPlugins.ts
+++ b/sdk/src/runtime/optionalPlugins.ts
@@ -19,6 +19,9 @@ import {
loadDragonBonesAssets, applyDragonBonesEntities,
} from '../dragonbones/loadDragonBonesScene';
import { setEntryPlugins } from './entryPlugins';
+import { Physics2DPlugin } from '../physics/Physics2DPlugin';
+import { Physics3DPlugin } from '../physics3d/Physics3DPlugin';
+import { VideoPlayer } from '../video/VideoAPI';
import { setSceneOptionals } from './sceneOptionals';
setEntryPlugins(() => [new SpinePlugin(), new DragonBonesPlugin()]);
@@ -36,4 +39,21 @@ setSceneOptionals({
load: loadDragonBonesAssets,
apply: applyDragonBonesEntities,
},
+ physics: {
+ installed: (app) => !!app.getPlugin(Physics2DPlugin),
+ install: (app, config, module) =>
+ app.addPlugin(new Physics2DPlugin('', config, () => Promise.resolve(module))),
+ },
+ physics3d: {
+ installed: (app) => !!app.getPlugin(Physics3DPlugin),
+ install: (app, module) =>
+ app.addPlugin(new Physics3DPlugin('', {}, () => Promise.resolve(module))),
+ },
+ video: {
+ setRefResolver: (app, resolve) => {
+ if (!app.hasResource(VideoPlayer)) return false;
+ app.getResource(VideoPlayer).setRefResolver(resolve);
+ return true;
+ },
+ },
});
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index 9fb63ccb2..45ac8a286 100644
--- a/sdk/src/runtime/runtimeLoader.ts
+++ b/sdk/src/runtime/runtimeLoader.ts
@@ -17,9 +17,8 @@ import type { ESEngineModule } from '../wasm';
import type { SpineWasmModule } from '../spine/SpineModuleLoader';
import type { SpineManager } from '../spine/SpineManager';
import type { PhysicsWasmModule } from '../physics/PhysicsModuleLoader';
-import { Physics2DPlugin, type Physics2DPluginConfig } from '../physics/Physics2DPlugin';
+import type { Physics2DPluginConfig } from '../physics/Physics2DPlugin';
import type { Physics3DWasmModule } from '../physics3d/Physics3DModule';
-import { Physics3DPlugin } from '../physics3d/Physics3DPlugin';
import { applyAudioProjectConfig, type AudioProjectConfig } from '../audio/AudioProjectConfig';
import type { App } from '../app/app';
import { Assets as AssetsClass } from '../asset/Assets';
@@ -38,7 +37,6 @@ import { SpriteAnimation } from '../animation/SpriteAnimator';
import { Audio } from '../audio/Audio';
import { Achievements } from '../services/achievements';
import { getPlatform } from '../platform/base';
-import { VideoPlayer } from '../video/VideoAPI';
import { Localization, matchLocale } from '../i18n/Localization';
import { LocalizationPlugin } from '../i18n/LocalizationPlugin';
import { platformLanguage } from '../platform';
@@ -51,7 +49,9 @@ import { type RuntimeAssetSource, type TextureParams } from './runtimeAssets';
import type { SpineAssetInfo } from '../spine/loadSpineScene';
import type { SceneAssetResult } from '../asset/Assets';
import type { DragonBonesManager } from '../dragonbones/DragonBonesManager';
-import { spineSupport, dragonBonesSupport } from './sceneOptionals';
+import {
+ spineSupport, dragonBonesSupport, physicsSupport, physics3dSupport, videoSupport,
+} from './sceneOptionals';
import type { DragonBonesAssetInfo } from '../dragonbones/loadDragonBonesScene';
import type { AddressableManifest, ManifestModel } from '../asset/AddressableManifest';
import type { Catalog } from '../asset/Catalog';
@@ -391,10 +391,10 @@ export async function prepareRuntimeScene(
// then goes through the realm's backend, because what a video element needs is
// a URL it can open: identity for http/filesystem realms, the inlined data URL
// for the single-file playable (where there is no file to fetch at all).
- if (source.resolveRef && app.hasResource(VideoPlayer)) {
+ if (source.resolveRef) {
const resolveRef = source.resolveRef;
const backend = source.backend;
- app.getResource(VideoPlayer).setRefResolver((ref) => backend.resolveUrl(resolveRef(ref)));
+ videoSupport()?.setRefResolver(app, (ref) => backend.resolveUrl(resolveRef(ref)));
}
mergeSceneTextureImportSettings(sceneAssets, sceneData, source.resolveRef ?? ((r) => r));
// Two full walks of the document before a byte is fetched. Named because
@@ -426,6 +426,10 @@ 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.
+ if (discovered.spines.length > 0 && !spine) {
+ log.warn('scene', `${discovered.spines.length} Spine asset(s) skipped — this build ships`
+ + ' without the Spine runtime');
+ }
const spineAssetInfo = app.sideModules && spine
? await spine.load(module, source, spineManager, discovered.spines, transcoderProvider,
{ assets: sceneAssets, scope: assetResult.scope })
@@ -443,7 +447,9 @@ export async function prepareRuntimeScene(
} else {
dragonBonesManager = (await dragonBonesSupport()?.acquire(app)) ?? null;
if (!dragonBonesManager) {
- log.warn('scene', 'DragonBones assets present but the runtime could not be loaded');
+ log.warn('scene', dragonBonesSupport()
+ ? 'DragonBones assets present but the runtime could not be loaded'
+ : 'DragonBones assets present but this build ships without the runtime');
} else {
dragonBonesAssetInfo = await dragonBonesSupport()!.load(
module, source, discovered.dragonBones, transcoderProvider);
@@ -467,7 +473,9 @@ export async function prepareRuntimeScene(
}
if (!physicsModule) {
log.warn('physics', `wanted (declared=${!!physicsEnabled}) but no module loaded — this realm has no side-module host or physics.wasm failed to load`);
- } else if (!app.getPlugin(Physics2DPlugin)) {
+ } else if (!physicsSupport()) {
+ log.warn('physics', 'wanted, but this build ships without the 2D physics runtime');
+ } else if (!physicsSupport()!.installed(app)) {
const gravity = physicsConfig?.gravity ?? { ...DEFAULT_GRAVITY };
const config: Physics2DPluginConfig = {
gravity,
@@ -482,8 +490,7 @@ export async function prepareRuntimeScene(
if (physicsConfig?.collisionLayerMasks) config.collisionLayerMasks = physicsConfig.collisionLayerMasks;
if (physicsConfig?.enableSleep !== undefined) config.enableSleep = physicsConfig.enableSleep;
if (physicsConfig?.enableContinuous !== undefined) config.enableContinuous = physicsConfig.enableContinuous;
- const mod = physicsModule;
- app.addPlugin(new Physics2DPlugin('', config, () => Promise.resolve(mod)));
+ physicsSupport()!.install(app, config, physicsModule);
log.info('physics', `installed (gravity ${gravity.x}, ${gravity.y})`);
}
});
@@ -494,7 +501,13 @@ export async function prepareRuntimeScene(
// for the other.
if (sceneUses3DPhysics(sceneData)) {
await installOnce(app, 'physics3d', async () => {
- if (app.getPlugin(Physics3DPlugin)) return;
+ const p3d = physics3dSupport();
+ if (!p3d) {
+ log.warn('physics3d', 'scene has 3D physics components but this build ships'
+ + ' without the 3D physics runtime');
+ return;
+ }
+ if (p3d.installed(app)) return;
const module3d = options.physics3dModule
?? (app.sideModules
? (await app.sideModules.acquire('physics3d')) as Physics3DWasmModule | null
@@ -504,8 +517,7 @@ export async function prepareRuntimeScene(
+ ' this realm has no side-module host or physics3d.wasm failed to load');
return;
}
- const mod = module3d;
- app.addPlugin(new Physics3DPlugin('', {}, () => Promise.resolve(mod)));
+ p3d.install(app, module3d);
log.info('physics3d', 'installed');
});
}
diff --git a/sdk/src/runtime/sceneOptionals.ts b/sdk/src/runtime/sceneOptionals.ts
index f755ec36c..a2a18c957 100644
--- a/sdk/src/runtime/sceneOptionals.ts
+++ b/sdk/src/runtime/sceneOptionals.ts
@@ -21,6 +21,9 @@ import type { DragonBonesManager } from '../dragonbones/DragonBonesManager';
import type {
loadDragonBonesAssets, applyDragonBonesEntities,
} from '../dragonbones/loadDragonBonesScene';
+import type { Physics2DPluginConfig } from '../physics/Physics2DPlugin';
+import type { PhysicsWasmModule } from '../physics/PhysicsModuleLoader';
+import type { Physics3DWasmModule } from '../physics3d/Physics3DModule';
/** What a scene load needs from Spine, when the build ships it. */
export interface SpineSupport {
@@ -37,15 +40,43 @@ export interface DragonBonesSupport {
apply(...args: Parameters<typeof applyDragonBonesEntities>): ReturnType<typeof applyDragonBonesEntities>;
}
+/** What a scene load needs from 2D physics, when the build ships it. */
+export interface PhysicsSupport {
+ installed(app: App): boolean;
+ install(app: App, config: Physics2DPluginConfig, module: PhysicsWasmModule): void;
+}
+
+/** What a scene load needs from 3D physics, when the build ships it. */
+export interface Physics3DSupport {
+ installed(app: App): boolean;
+ install(app: App, module: Physics3DWasmModule): void;
+}
+
+/** What a scene load needs from video, when the build ships it. */
+export interface VideoSupport {
+ /** False when the realm has no VideoPlayer resource to point at the staged file. */
+ setRefResolver(app: App, resolve: (ref: string) => string): boolean;
+}
+
let spine: SpineSupport | null = null;
+let physics: PhysicsSupport | null = null;
+let physics3d: Physics3DSupport | null = null;
+let video: VideoSupport | 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 {
+export function setSceneOptionals(support: {
+ spine?: SpineSupport;
+ dragonBones?: DragonBonesSupport;
+ physics?: PhysicsSupport;
+ physics3d?: Physics3DSupport;
+ video?: VideoSupport;
+}): void {
if (support.spine) spine = support.spine;
if (support.dragonBones) dragonBones = support.dragonBones;
+ if (support.physics) physics = support.physics;
+ if (support.physics3d) physics3d = support.physics3d;
+ if (support.video) video = support.video;
}
/** Null in a build that does not ship Spine — a scene holding one then loads
@@ -54,3 +85,12 @@ export const spineSupport = (): SpineSupport | null => spine;
/** Null in a build that does not ship DragonBones. */
export const dragonBonesSupport = (): DragonBonesSupport | null => dragonBones;
+
+/** Null in a build that does not ship 2D physics. */
+export const physicsSupport = (): PhysicsSupport | null => physics;
+
+/** Null in a build that does not ship 3D physics. */
+export const physics3dSupport = (): Physics3DSupport | null => physics3d;
+
+/** Null in a build that does not ship video. */
+export const videoSupport = (): VideoSupport | null => video;
diff --git a/sdk/tests/concurrent-scene-subsystems.test.ts b/sdk/tests/concurrent-scene-subsystems.test.ts
index 5e0aa0d68..736975622 100644
--- a/sdk/tests/concurrent-scene-subsystems.test.ts
+++ b/sdk/tests/concurrent-scene-subsystems.test.ts
@@ -13,6 +13,10 @@
*/
import { describe, it, expect } from 'vitest';
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 { 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.ts
index 06ed4e6a3..2a9c68eb8 100644
--- a/sdk/tests/video-ref-resolution.test.ts
+++ b/sdk/tests/video-ref-resolution.test.ts
@@ -10,6 +10,10 @@
*/
import { describe, it, expect } from 'vitest';
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 { VideoPlayer } from '../src/video/VideoAPI';
import { World } from '../src/ecs/world';
import type { App } from '../src/app/app';
diff --git a/tools/baselines/core-carries-options.json b/tools/baselines/core-carries-options.json
index 276cc3c13..cab998b82 100644
--- a/tools/baselines/core-carries-options.json
+++ b/tools/baselines/core-carries-options.json
@@ -1,7 +1,3 @@
{
- "edges": [
- "sdk/src/runtime/runtimeLoader.ts -> ../physics/Physics2DPlugin",
- "sdk/src/runtime/runtimeLoader.ts -> ../physics3d/Physics3DPlugin",
- "sdk/src/runtime/runtimeLoader.ts -> ../video/VideoAPI"
- ]
+ "edges": []
}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 0b41a674a..20189e69f 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 core runtime names no optional subsystem at all':
+ { internal: 'Same subsystems, same behaviour; a lean build now says when it ships without one.' },
+
'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.' },