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 core runtime names no optional subsystem at all
esengined23d3145b2ef
diff --git a/sdk/src/runtime/optionalPlugins.ts b/sdk/src/runtime/optionalPlugins.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.jsonindex 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.mjsindex 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.' },