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.

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.json
index 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.ts
index 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.ts
index 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 playback
diff --git a/pipeline/src/export/exportPlayable.ts b/pipeline/src/export/exportPlayable.ts
index 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 via
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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: App
module: ESEngineModule | null
+physics3dModule: Physics3DWasmModule | undefined
physicsConfig: PhysicsPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: App
module: ESEngineModule | null
+physics3dModule: Physics3DWasmModule | undefined
physicsConfig: PhysicsPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: App
module: ESEngineModule | null
+physics3dModule: Physics3DWasmModule | undefined
physicsConfig: PhysicsPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: App
module: ESEngineModule | null
+physics3dModule: Physics3DWasmModule | undefined
physicsConfig: PhysicsPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: App
module: ESEngineModule | null
+physics3dModule: Physics3DWasmModule | undefined
physicsConfig: PhysicsPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index 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's
diff --git a/sdk/src/sideModules/registry.ts b/sdk/src/sideModules/registry.ts
index 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.ts
index 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/Physic
import 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);
+ });
+});