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
feat(physics): a scene that uses the 3D world gets it
esenginea1abe9644a63
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex daabb316b..c8ec28902 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -770,20 +770,21 @@"key": "maxSlope","type": "number","default": "0.87",- "range": "0–1.5708"+ "doc": "Steepest ground it can stand on",+ "range": "0–1.5708, step 0.01"},{"key": "stepHeight","type": "number","default": "0.4",- "range": "≥ 0",+ "range": "≥ 0, step 0.05","advanced": true},{"key": "snapDown","type": "number","default": "0.5",- "range": "≥ 0",+ "range": "≥ 0, step 0.05","advanced": true},{@@ -2593,18 +2594,21 @@"key": "linearDamping","type": "number","default": "0.05",- "range": "≥ 0"+ "range": "≥ 0",+ "advanced": true},{"key": "angularDamping","type": "number","default": "0.05",- "range": "≥ 0"+ "range": "≥ 0",+ "advanced": true},{"key": "fixedRotation","type": "boolean",- "default": "false"+ "default": "false",+ "advanced": true},{"key": "enabled",diff --git a/pipeline/src/bundle/sideModuleScan.ts b/pipeline/src/bundle/sideModuleScan.tsindex ce7452539..a14be1587 100644--- a/pipeline/src/bundle/sideModuleScan.ts+++ b/pipeline/src/bundle/sideModuleScan.ts@@ -16,6 +16,11 @@ const PHYSICS_COMPONENT_TYPES = new Set(['SegmentCollider', 'PolygonCollider', 'ChainCollider',]);+const PHYSICS3D_COMPONENT_TYPES = new Set([+ 'RigidBody3D', 'BoxCollider3D', 'SphereCollider3D', 'CapsuleCollider3D',+ 'CharacterController3D',+]);+interface SceneLike {entities?: Array<{ components?: Array<{ type?: string; data?: unknown }> }>;}@@ -35,6 +40,17 @@ export function sceneUsesPhysics(scene: SceneLike): boolean {return false;}+/** The same question for the 3D world, which ships as its own module. Mirrors+ * runtimeLoader.sceneUses3DPhysics. */+export function sceneUses3DPhysics(scene: SceneLike): boolean {+ for (const entity of scene.entities ?? []) {+ for (const comp of entity.components ?? []) {+ if (comp.type && PHYSICS3D_COMPONENT_TYPES.has(comp.type)) return true;+ }+ }+ return false;+}+/** True if any entity carries a DragonBonesAnimation. Unlike Spine there is no* version to detect: the format is frozen and one module reads all of it, so the* presence of the component IS the answer. */diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.tsindex 4d857da08..4d05058b5 100644--- a/pipeline/src/export/exportMiniGame.ts+++ b/pipeline/src/export/exportMiniGame.ts@@ -42,7 +42,7 @@ import type { OnExportProgress } from './exportProgress';import { esengineAlias } from '../bundle/esengineResolve';import { explainBundleErrors, type BundleMessage } from '../bundle/bundleDiagnostics';import {- sceneUsesPhysics, sceneUsesVideo, sceneUsesDragonBones, detectSpineVersion, detectSpineVersionJson,+ sceneUsesPhysics, sceneUses3DPhysics, sceneUsesVideo, sceneUsesDragonBones, detectSpineVersion, detectSpineVersionJson,spineModuleId, SIDE_MODULE_FILE,} from '../bundle/sideModuleScan';import { OPEN_DATA_DIR } from './miniGameExportProfile';@@ -123,6 +123,11 @@ async function scanSideModules(// would fail at the first spawn instead of at build time.if (physicsEnabled|| sceneDatas.some((s) => s && sceneUsesPhysics(s as Parameters<typeof sceneUsesPhysics>[0]))) ids.add('physics');+ // Never implied by the 2D flag: that declares the solver 2D scenes use, and+ // this is a different module.+ if (sceneDatas.some((s) => s && sceneUses3DPhysics(s as Parameters<typeof sceneUses3DPhysics>[0]))) {+ ids.add('physics3d');+ }if (sceneDatas.some((s) => s && sceneUsesVideo(s as Parameters<typeof sceneUsesVideo>[0]))) ids.add('videodec');if (sceneDatas.some((s) => s && sceneUsesDragonBones(s as Parameters<typeof sceneUsesDragonBones>[0]))) ids.add('dragonbones');// Any staged .esv also needs the decoder: script-driven playbackdiff --git a/pipeline/src/export/exportPlayable.ts b/pipeline/src/export/exportPlayable.tsindex b7920c9b3..e682317aa 100644--- a/pipeline/src/export/exportPlayable.ts+++ b/pipeline/src/export/exportPlayable.ts@@ -31,7 +31,7 @@ import type { ScreenOrientation } from './orientationHtml';import { genericPlayableProfile, playableAdInjection, type PlayableAdProfile } from './playableAdProfile';import { makeZip } from '../../../build-tools/utils/zip.js';import {- sceneUsesPhysics, sceneUsesDragonBones, detectSpineVersion, detectSpineVersionJson,+ sceneUsesPhysics, sceneUses3DPhysics, sceneUsesDragonBones, detectSpineVersion, detectSpineVersionJson,spineModuleId, SIDE_MODULE_FILE, type SpineVersion,} from '../bundle/sideModuleScan';@@ -130,6 +130,11 @@ async function collectSideModules(// it spawns them from script, and the flag is worthless without the binary.if (physicsEnabled|| (sceneData && sceneUsesPhysics(sceneData as Parameters<typeof sceneUsesPhysics>[0]))) ids.add('physics');+ // The 3D world is never implied by the 2D flag: a project declaring `physics`+ // is declaring the solver its 2D scenes use, and this module is a different one.+ if (sceneData && sceneUses3DPhysics(sceneData as Parameters<typeof sceneUses3DPhysics>[0])) {+ ids.add('physics3d');+ }if (sceneData && sceneUsesDragonBones(sceneData as Parameters<typeof sceneUsesDragonBones>[0])) ids.add('dragonbones');// Spine: the skeleton carries the version. Skeleton + atlas share the authored// meta type `spine`, so we discriminate by extension (as the runtime does viadiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 6819fc8d5..6588bafe8 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1358,7 +1358,7 @@ source: string## BuiltinSideModuleId — type @experimental```-'physics' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}`+'physics' | 'physics3d' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}````## BundleMode — type @experimental@@ -3921,6 +3921,7 @@ mouse: boolean | undefined```app: Appmodule: ESEngineModule | null+physics3dModule: Physics3DWasmModule | undefinedphysicsConfig: PhysicsPluginConfig | undefinedphysicsEnabled: boolean | undefinedphysicsModule: PhysicsWasmModule | null | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 21f52ecf8..4fa922e0e 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1358,7 +1358,7 @@ source: string## BuiltinSideModuleId — type @experimental```-'physics' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}`+'physics' | 'physics3d' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}````## BundleMode — type @experimental@@ -3929,6 +3929,7 @@ mouse: boolean | undefined```app: Appmodule: ESEngineModule | null+physics3dModule: Physics3DWasmModule | undefinedphysicsConfig: PhysicsPluginConfig | undefinedphysicsEnabled: boolean | undefinedphysicsModule: PhysicsWasmModule | null | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 5da47c16a..49ae4501b 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1353,7 +1353,7 @@ source: string## BuiltinSideModuleId — type @experimental```-'physics' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}`+'physics' | 'physics3d' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}````## BundleMode — type @experimental@@ -3916,6 +3916,7 @@ mouse: boolean | undefined```app: Appmodule: ESEngineModule | null+physics3dModule: Physics3DWasmModule | undefinedphysicsConfig: PhysicsPluginConfig | undefinedphysicsEnabled: boolean | undefinedphysicsModule: PhysicsWasmModule | null | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 739e6a5b9..7039808e4 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1353,7 +1353,7 @@ source: string## BuiltinSideModuleId — type @experimental```-'physics' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}`+'physics' | 'physics3d' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}````## BundleMode — type @experimental@@ -3916,6 +3916,7 @@ mouse: boolean | undefined```app: Appmodule: ESEngineModule | null+physics3dModule: Physics3DWasmModule | undefinedphysicsConfig: PhysicsPluginConfig | undefinedphysicsEnabled: boolean | undefinedphysicsModule: PhysicsWasmModule | null | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex a419488f9..d01776a04 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1353,7 +1353,7 @@ source: string## BuiltinSideModuleId — type @experimental```-'physics' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}`+'physics' | 'physics3d' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}````## BundleMode — type @experimental@@ -3923,6 +3923,7 @@ mouse: boolean | undefined```app: Appmodule: ESEngineModule | null+physics3dModule: Physics3DWasmModule | undefinedphysicsConfig: PhysicsPluginConfig | undefinedphysicsEnabled: boolean | undefinedphysicsModule: PhysicsWasmModule | null | undefineddiff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.tsindex 8f4d19d82..3af70ba5c 100644--- a/sdk/src/runtime/runtimeLoader.ts+++ b/sdk/src/runtime/runtimeLoader.ts@@ -16,6 +16,8 @@ import type { SpineWasmModule } from '../spine/SpineModuleLoader';import { SpineManager } from '../spine/SpineManager';import type { PhysicsWasmModule } from '../physics/PhysicsModuleLoader';import { PhysicsPlugin, type PhysicsPluginConfig } from '../physics/PhysicsPlugin';+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';@@ -194,6 +196,8 @@ export interface LoadRuntimeSceneOptions {* physics even for runtime-spawned bodies the static scene doesn't show.* OR-combined with a content scan. */physicsEnabled?: boolean;+ /** An already-resolved 3D physics module, for tests and headless hosts. */+ physics3dModule?: Physics3DWasmModule;/** Project-declared UI theme (Project Settings → UI). Dark is the default;* 'light' switches the token set AND re-resolves already-instantiated* ThemeStyle-tagged widgets (prefab instances carry dark baked values). */@@ -210,6 +214,22 @@ const PHYSICS_COMPONENT_TYPES = new Set(['SegmentCollider', 'PolygonCollider', 'ChainCollider',]);+/** The same question for the 3D world, which is a different module entirely. */+const PHYSICS3D_COMPONENT_TYPES = new Set([+ 'RigidBody3D', 'BoxCollider3D', 'SphereCollider3D', 'CapsuleCollider3D',+ 'CharacterController3D',+]);++/** True if any entity carries a 3D physics component. */+export function sceneUses3DPhysics(sceneData: SceneData): boolean {+ for (const entity of sceneData.entities ?? []) {+ for (const comp of entity.components ?? []) {+ if (PHYSICS3D_COMPONENT_TYPES.has(comp.type)) return true;+ }+ }+ return false;+}+/** True if any Text binds its content to a localization key — the scene needs* the Localization resource + the project's `.eslocale` tables to render as* authored (an unbound key would show as the raw key string). */@@ -377,6 +397,24 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis}}+ // The 3D world gates itself the same way, on its own components and its own+ // module: the two never share a solver, so a scene wanting one is not asking+ // for the other.+ if (sceneUses3DPhysics(sceneData) && !app.getPlugin(Physics3DPlugin)) {+ const module3d = options.physics3dModule+ ?? (app.sideModules+ ? (await app.sideModules.acquire('physics3d')) as Physics3DWasmModule | null+ : null);+ if (!module3d) {+ log.warn('physics3d', 'scene has 3D physics components but no module loaded —'+ + ' this realm has no side-module host or physics3d.wasm failed to load');+ } else {+ const mod = module3d;+ app.addPlugin(new Physics3DPlugin('', {}, () => Promise.resolve(mod)));+ log.info('physics3d', 'installed');+ }+ }+// Self-gating i18n, mirroring physics: a scene that binds Text.i18nKey needs// the Localization resource + the shipped `.eslocale` tables — installed and// loaded here so no runtime entry can forget. Tables come from the realm'sdiff --git a/sdk/src/sideModules/registry.ts b/sdk/src/sideModules/registry.tsindex 4ac81a599..2d020dd41 100644--- a/sdk/src/sideModules/registry.ts+++ b/sdk/src/sideModules/registry.ts@@ -20,7 +20,7 @@ export type SpineVersion = '2.1' | '3.8' | '4.1' | '4.2' | '4.3';/** The modules the engine itself builds and ships. */export type BuiltinSideModuleId =- 'physics' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}`;+ 'physics' | 'physics3d' | 'basis' | 'videodec' | 'dragonbones' | `spine:${SpineVersion}`;/*** Identifies an optional native module across every realm and transport.@@ -53,6 +53,9 @@ export interface SideModuleDescriptor {export const SIDE_MODULES: Record<BuiltinSideModuleId, SideModuleDescriptor> = {physics: { file: 'physics' },+ // The 3D world (Jolt). A separate module from the 2D one on purpose: the two+ // never share a solver, and a 2D project should not carry a 3D one's weight.+ physics3d: { file: 'physics3d', globalName: 'ESPhysics3DModule' },// Basis Universal KTX2 transcoder — compressed textures decode to a// GPU format on demand. MODULARIZE glue with a named EXPORT_NAME, like spine.basis: { file: 'basis', globalName: 'ESBasisModule' },diff --git a/sdk/tests/physics3d-ecs.test.ts b/sdk/tests/physics3d-ecs.test.tsindex 3646cfc0e..b731b7037 100644--- a/sdk/tests/physics3d-ecs.test.ts+++ b/sdk/tests/physics3d-ecs.test.ts@@ -19,6 +19,7 @@ import { stepPhysics3D, DEFAULT_PHYSICS3D_CONFIG } from '../src/physics3d/Physicimport type { Physics3DWasmModule } from '../src/physics3d/Physics3DModule';import type { App } from '../src/app/app';import type { Entity } from '../src/types';+import { sceneUses3DPhysics, sceneUsesPhysics } from '../src/runtime/runtimeLoader';/** A module that records what it was told, and can be made to answer a readback.* The two readbacks are separate buffers, as they are in the module: sharing one@@ -255,3 +256,23 @@ describe('the 3D world and the ECS', () => {expect(bodies.size).toBe(0);});});++describe('a scene asks for the world it needs', () => {+ const sceneWith = (...types: string[]) => ({+ entities: [{ components: types.map((type) => ({ type, data: {} })) }],+ });++ it('sees every 3D component as wanting the 3D world', () => {+ for (const type of ['RigidBody3D', 'BoxCollider3D', 'SphereCollider3D',+ 'CapsuleCollider3D', 'CharacterController3D']) {+ expect(sceneUses3DPhysics(sceneWith(type) as never)).toBe(true);+ }+ });++ it('does not confuse the two worlds', () => {+ // A 2D scene must not drag in a 1.2MB module it has no use for, and a 3D+ // scene must not be served the solver that cannot move it.+ expect(sceneUses3DPhysics(sceneWith('RigidBody', 'BoxCollider') as never)).toBe(false);+ expect(sceneUsesPhysics(sceneWith('RigidBody3D', 'BoxCollider3D') as never)).toBe(false);+ });+});