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(physics3d): the 3D world is made from project settings, not constants
yhh644663a9d5fa
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0fa8d48a3..db0edd321 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -25,9 +25,11 @@ published separately; it ships inside the editor.- **The sky lights the scene.** Sky Atmosphere's **Light the Scene** makes the sky the scene's environment: every Ambient light that names no environment of its own lights with it, its diffuse light from the dome and the clouds and its reflection on metal and wet ground, scaled by the light's colour and intensity as an imported one is. The sky is worked out again as it changes (the sun moving, a weather coming in, clouds drifting), at most once a second; with clouds that takes about 20 ms on a desktop. The sun's disc is left out, since the directional light the sky follows is its direct light. Off by default, so a scene already lit by hand looks as it did.- **Rooms stay dark under a sky that changes (sky occlusion).** With **Sky occlusion** on in the Lighting settings (`BakedLighting.skyOcclusion`), a probe bake keeps how much of the sky each probe sees instead of the sky itself: the probes hold the lights and their bounces, and the sky the frame has now (a live Sky Atmosphere, a weather, an environment) is added through what each probe sees of it, to the diffuse light and to the sky's reflection. A ball inside a roofed room measured 119 where the baked sky gave it 150, and a ball outside kept its light. A `.esprobes` baked this way carries `skyVisibility`; one without it lights as before. Probes are read per object, as Unity's light probes are: one large mesh spanning indoors and out takes one value.+- **The 3D physics world is set in Project Settings, not in code.** **Physics → 3D Physics** sets what a scene unit is to the solver (**Units per metre**: 100, a centimetre, as before; 1 for a metre scene such as imported glTF), gravity in m/s², collision steps, velocity and position iterations, the bounce threshold, sleep and the body budget. Iterations and the bounce threshold left at 0 keep each solver's own (Jolt's, or Unity's for PhysX). The 3D world also takes the project's fixed step and collision-layer matrix, which only 2D did. A metre scene used to get gravity 100 times too strong, since everything was read as centimetres. Settings left at their defaults write nothing, so an existing project and its builds are unchanged. In `project.esproject` they are `features.physics.world3d`.### Fixed+- **A scene whose only 3D physics is a compound collider or a ragdoll gets a physics world.** The scene loader did not count `CompoundCollider3D` or `Ragdoll` as 3D physics, so a scene with nothing else ran with neither moving.- **Geometry with no lightmap UV set still stands in a bake's light.** It was left out of the bake altogether, so it cast no shadow on the baked surfaces and the probes saw straight through it. It now shadows them and hides the sky from the probes, while receiving no baked light itself (the import still says to generate lightmap UVs for that).- **An opaque surface no longer lets the sky through where its map's alpha is below 1.** An unblended draw wrote its base colour's alpha into the frame, and Sky Atmosphere reads a pixel's alpha as how much of it geometry covers, so wherever a texture used its alpha for something else (glTF's OPAQUE ignores it) the clouds showed through the wall. An opaque Model surface now writes 1, except a cut-out's coverage and the subsurface mark.- **The sky no longer shows through everything when water or glass and a blended surface are both in view.** The frame keeps the opaque scene aside and puts it back around the blended draws; it was put back through the copy made for refraction, which marks its alpha 0.5, so every pixel came back half covered and the sky showed through half of the picture.diff --git a/desktop b/desktopindex 860430181..8424e1c32 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 860430181fc15a6abca144d49e087d213c5e47ba+Subproject commit 8424e1c322aad957f60249da46c00a3dd15ed0d1diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.tsindex 213635006..6d8bd0325 100644--- a/pipeline/src/project/format.ts+++ b/pipeline/src/project/format.ts@@ -19,8 +19,8 @@*/import {- parseAudioProjectConfig, parseQualityConfig, parseRuntimeBuildConfig, THEME_COLOR_ROLES,- type AudioProjectConfig, type QualityConfig, type RuntimeBuildConfig,+ parseAudioProjectConfig, parseQualityConfig, parseRuntimeBuildConfig, physics3DPluginConfigOf, THEME_COLOR_ROLES,+ type AudioProjectConfig, type Physics3DWorldConfig, type QualityConfig, type RuntimeBuildConfig,} from 'esengine';import { normalizePlatform, type ExportPlatform } from './platforms';import { cspConnectSources } from '../export/cspConnect';@@ -162,6 +162,9 @@ export interface ProjectFeatures {collisionLayers?: string[];/** The solver behind 3D physics: Jolt (default) or PhysX, the one Unity runs. */backend3d?: 'jolt' | 'physx';+ /** The 3D world (Project Settings → Physics → 3D): units per metre, gravity, solver. Only what differs from+ * the engine's own values is written; the fixed step and the collision matrix are the ones above, shared with 2D. */+ world3d?: Partial<Physics3DWorldConfig>;/** Per-layer collision masks (the UE/Unity collision matrix): masks[i] bit j set ⇒* layer i collides with layer j. 16 entries; absent ⇒ all-collide. */collisionLayerMasks?: number[];@@ -849,6 +852,16 @@ export function parseManifest(raw: unknown): ProjectManifest {if (typeof p.enableSleep === 'boolean') physics.enableSleep = p.enableSleep;if (p.backend3d === 'jolt' || p.backend3d === 'physx') physics.backend3d = p.backend3d;if (typeof p.enableContinuous === 'boolean') physics.enableContinuous = p.enableContinuous;+ if (p.world3d && typeof p.world3d === 'object') {+ // The SDK's own reader decides what is valid, so a value the runtime would refuse is not kept here either.+ const valid = physics3DPluginConfigOf(p.world3d as Partial<Physics3DWorldConfig>);+ const world3d: Partial<Physics3DWorldConfig> = {};+ if (valid.pixelsPerUnit !== undefined) world3d.unitsPerMeter = valid.pixelsPerUnit;+ for (const k of ['gravity', 'collisionSteps', 'maxBodies', 'velocityIterations', 'positionIterations', 'enableSleep', 'bounceThreshold'] as const) {+ if (valid[k] !== undefined) (world3d as Record<string, unknown>)[k] = valid[k];+ }+ if (Object.keys(world3d).length > 0) physics.world3d = world3d;+ }features.physics = physics;}if (f.rendering && typeof f.rendering === 'object') {diff --git a/pipeline/src/project/runtimeConfig.ts b/pipeline/src/project/runtimeConfig.tsindex d04a9898a..c3460bd2b 100644--- a/pipeline/src/project/runtimeConfig.ts+++ b/pipeline/src/project/runtimeConfig.ts@@ -26,9 +26,9 @@* fails the build when a field in this shape is not carried by every consumer —* or is not listed there as a declared, reasoned gap.*/-import { parseQualityConfig, parseRuntimeBuildConfig } from 'esengine';+import { DEFAULT_PHYSICS3D_WORLD, parseQualityConfig, parseRuntimeBuildConfig } from 'esengine';import type {- AudioProjectConfig, PackagedGameConfig, Physics2DPluginConfig, QualityConfig, RuntimeBuildConfig,+ AudioProjectConfig, PackagedGameConfig, Physics2DPluginConfig, Physics3DWorldConfig, QualityConfig, RuntimeBuildConfig,} from 'esengine';import { resolveScreenFit, SORTING_LAYER_COUNT, type ProjectFeatures, type ProjectManifest, type ProjectPackaging } from './format';@@ -62,6 +62,8 @@ export interface RuntimeProjectConfig {physicsConfig: Physics2DPluginConfig;/** The 3D physics backend; 'jolt' is the default. */physics3dBackend: 'jolt' | 'physx';+ /** The 3D world: scene units per metre and gravity, defaults folded in. */+ physics3dWorld: Physics3DWorldConfig;/** Mixer state: bus volumes, custom buses, effects, duck rules. */audioConfig: AudioProjectConfig;/** Runtime tuning the project declared — only what differs from the engine's own values, so `{}` is the default. */@@ -159,6 +161,7 @@ export function runtimeConfigOf(physicsEnabled: f?.physics?.enabled ?? false,physicsConfig: physicsConfigOf(f),physics3dBackend: f?.physics?.backend3d === 'physx' ? 'physx' : 'jolt',+ physics3dWorld: { ...DEFAULT_PHYSICS3D_WORLD, ...f?.physics?.world3d },audioConfig: f?.audio ?? {},runtime: parseRuntimeBuildConfig(f?.runtime),uiTheme: f?.ui?.theme === 'light' ? 'light' : 'dark',@@ -193,7 +196,7 @@ export type PackagedRuntimeFields = Pick<'ySortLayers' | 'depthLayers' | 'colorSpace' | 'outputTransform' | 'renderBackend' | 'screenFit'| 'msaaSamples' | 'quality'| 'uiTheme' | 'uiThemeColors'- | 'physicsEnabled' | 'physicsConfig' | 'physics3dBackend' | 'audioConfig' | 'achievements' | 'steamAppId' | 'runtime'+ | 'physicsEnabled' | 'physicsConfig' | 'physics3dBackend' | 'physics3dWorld' | 'audioConfig' | 'achievements' | 'steamAppId' | 'runtime'>;/**@@ -230,6 +233,7 @@ export function packagedRuntimeFields(rc: RuntimeProjectConfig): PackagedRuntime...(rc.physicsEnabled ? { physicsEnabled: true } : {}),...(isDefaultPhysics(rc.physicsConfig) ? {} : { physicsConfig: rc.physicsConfig }),...(rc.physics3dBackend === 'physx' ? { physics3dBackend: rc.physics3dBackend } : {}),+ ...(isDefaultPhysics3dWorld(rc.physics3dWorld) ? {} : { physics3dWorld: rc.physics3dWorld }),...(rc.audioConfig.buses?.length || rc.audioConfig.maxVoices !== undefined|| Object.keys(rc.audioConfig.loadTypes ?? {}).length > 0? { audioConfig: rc.audioConfig } : {}),@@ -251,6 +255,10 @@ export function qualityShips(quality: QualityConfig): boolean {}/** Whether the world config is exactly what a runtime would default to anyway. */+function isDefaultPhysics3dWorld(world: Physics3DWorldConfig): boolean {+ return JSON.stringify(world) === JSON.stringify(DEFAULT_PHYSICS3D_WORLD);+}+function isDefaultPhysics(config: Physics2DPluginConfig): boolean {return JSON.stringify(config) === JSON.stringify(DEFAULT_PHYSICS_CONFIG);}diff --git a/pipeline/tests/physics3d-world.test.ts b/pipeline/tests/physics3d-world.test.tsnew file mode 100644index 000000000..9ad8275c9--- /dev/null+++ b/pipeline/tests/physics3d-world.test.ts@@ -0,0 +1,47 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file A project says how its 3D world is made — what a scene unit is, gravity, the solver — in Project Settings,+ * not in code. The settings are read from the project, carried into every packaged build, and become the+ * config the 3D world is installed with, together with the fixed step and collision matrix 2D also uses.+ */+import { describe, it, expect } from 'vitest';+import { DEFAULT_PHYSICS3D_WORLD, physics3DInstallConfig } from 'esengine';+import { parseManifest } from '../src/project/format';+import { packagedRuntimeFields, runtimeConfigOf } from '../src/project/runtimeConfig';++const manifest = (physics: Record<string, unknown>) => parseManifest({ formatVersion: '1', name: 'g', features: { physics } });++describe('3D physics world settings', () => {+ it('are the engine\'s own values when the project says nothing, and an untouched project ships no block', () => {+ const rc = runtimeConfigOf(manifest({}));+ expect(rc.physics3dWorld).toEqual(DEFAULT_PHYSICS3D_WORLD);+ expect(packagedRuntimeFields(rc)).not.toHaveProperty('physics3dWorld');+ expect(physics3DInstallConfig(packagedRuntimeFields(rc).physics3dWorld, undefined)).toEqual({});+ });++ it('reach a packaged build and the installed world, a metre scene included', () => {+ const m = manifest({+ fixedTimestep: 1 / 120,+ collisionLayerMasks: [0xfffe, ...Array(15).fill(0xffff)],+ world3d: { unitsPerMeter: 1, gravity: { x: 0, y: -3.7, z: 0 }, collisionSteps: 2, maxBodies: 4096,+ velocityIterations: 12, positionIterations: 4, enableSleep: false, bounceThreshold: 0.5 },+ });+ const rc = runtimeConfigOf(m);+ const shipped = packagedRuntimeFields(rc);+ expect(shipped.physics3dWorld?.unitsPerMeter).toBe(1);+ const installed = physics3DInstallConfig(shipped.physics3dWorld, shipped.physicsConfig);+ expect(installed).toMatchObject({+ pixelsPerUnit: 1, gravity: { x: 0, y: -3.7, z: 0 }, collisionSteps: 2, maxBodies: 4096,+ velocityIterations: 12, positionIterations: 4, enableSleep: false, bounceThreshold: 0.5,+ fixedTimestep: 1 / 120,+ });+ expect(installed.layerMasks?.[0]).toBe(0xfffe);+ });++ it('drops what the runtime would refuse rather than keep it in the project', () => {+ const m = manifest({ world3d: { unitsPerMeter: 0, gravity: { x: 0, y: 'down', z: 0 }, collisionSteps: 1.5, maxBodies: -4 } });+ expect(m.features?.physics?.world3d).toBeUndefined();+ expect(runtimeConfigOf(m).physics3dWorld).toEqual(DEFAULT_PHYSICS3D_WORLD);+ });+});diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.tsindex 51944497f..caa7cdef6 100644--- a/sdk/src/core-sys.ts+++ b/sdk/src/core-sys.ts@@ -330,6 +330,7 @@ export {type EmbeddedSideModuleRegistry,type WeChatSideModuleFactories,} from './sideModules';+export { DEFAULT_PHYSICS3D_WORLD, physics3DPluginConfigOf, physics3DInstallConfig, type Physics3DWorldConfig } from './physics3d/worldConfig';// =============================================================================// Playable Runtimediff --git a/sdk/src/physics3d/Physics3DModule.ts b/sdk/src/physics3d/Physics3DModule.tsindex 4efcaf089..ed14d56d2 100644--- a/sdk/src/physics3d/Physics3DModule.ts+++ b/sdk/src/physics3d/Physics3DModule.ts@@ -19,6 +19,9 @@ export interface Physics3DWasmModule {_physics3d_step(dt: number, collisionSteps: number): void;_physics3d_optimize(): void;_physics3d_setLayerMask(layer: number, mask: number): void;+ /** Each value <= 0 keeps the backend's own default; after init, before bodies. */+ _physics3d_setSolver(velocityIterations: number, positionIterations: number, allowSleep: number,+ bounceThreshold: number): void;_physics3d_addBox(entity: number, hx: number, hy: number, hz: number,px: number, py: number, pz: number,@@ -158,7 +161,7 @@ export type Physics3DModuleFactory =export const PHYSICS3D_TRANSFORM_STRIDE = 8;const REQUIRED_EXPORTS = [- '_physics3d_init', '_physics3d_shutdown', '_physics3d_isReady', '_physics3d_step',+ '_physics3d_init', '_physics3d_shutdown', '_physics3d_isReady', '_physics3d_step', '_physics3d_setSolver','_physics3d_addBox', '_physics3d_addSphere', '_physics3d_addCapsule','_physics3d_removeBody', '_physics3d_setTransform', '_physics3d_raycast','_physics3d_transforms', '_physics3d_transformsBytes',diff --git a/sdk/src/physics3d/Physics3DPlugin.ts b/sdk/src/physics3d/Physics3DPlugin.tsindex 7961b465c..14563b72b 100644--- a/sdk/src/physics3d/Physics3DPlugin.ts+++ b/sdk/src/physics3d/Physics3DPlugin.ts@@ -63,6 +63,9 @@ export class Physics3DPlugin implements Plugin {this.module_ = module;const { gravity, maxBodies } = this.config_;module._physics3d_init(gravity.x, gravity.y, gravity.z, maxBodies);+ const solver = this.config_;+ module._physics3d_setSolver(solver.velocityIterations, solver.positionIterations,+ solver.enableSleep ? 1 : 0, solver.bounceThreshold);// Before any body: an ObjectLayer is fixed when a body is created, so a// matrix installed later would not reach what is already in the world.this.config_.layerMasks?.forEach((mask, layer) => {diff --git a/sdk/src/physics3d/Physics3DSystem.ts b/sdk/src/physics3d/Physics3DSystem.tsindex 03b1b2537..eadc48941 100644--- a/sdk/src/physics3d/Physics3DSystem.ts+++ b/sdk/src/physics3d/Physics3DSystem.ts@@ -44,6 +44,14 @@ export interface Physics3DConfig {collisionSteps: number;pixelsPerUnit: number;maxBodies: number;+ /** Solver passes; 0 keeps the backend's own (Jolt 10 / PhysX 1). */+ velocityIterations: number;+ /** 0 keeps the backend's own (Jolt 2 / PhysX 6). */+ positionIterations: number;+ /** Resting bodies stop being simulated until something touches them. */+ enableSleep: boolean;+ /** Slower impacts than this (m/s) do not bounce; 0 keeps the backend's own (Jolt 1 / PhysX 2). */+ bounceThreshold: number;}export const DEFAULT_PHYSICS3D_CONFIG: Physics3DConfig = {@@ -52,6 +60,10 @@ export const DEFAULT_PHYSICS3D_CONFIG: Physics3DConfig = {collisionSteps: 1,pixelsPerUnit: 100,maxBodies: 1024,+ velocityIterations: 0,+ positionIterations: 0,+ enableSleep: true,+ bounceThreshold: 0,};/** Which body an entity owns, so a removed component takes its body with it. */diff --git a/sdk/src/physics3d/physics3dSupport.ts b/sdk/src/physics3d/physics3dSupport.tsindex 6443552bc..584afc1fa 100644--- a/sdk/src/physics3d/physics3dSupport.ts+++ b/sdk/src/physics3d/physics3dSupport.ts@@ -9,8 +9,8 @@ export function registerPhysics3DSupport(): void {setSceneOptionals({physics3d: {installed: (app) => !!app.getPlugin(Physics3DPluginCtor),- install: (app, module) =>- app.addPlugin(new Physics3DPluginCtor('', {}, () => Promise.resolve(module))),+ install: (app, module, config) =>+ app.addPlugin(new Physics3DPluginCtor('', config ?? {}, () => Promise.resolve(module))),},});}diff --git a/sdk/src/physics3d/worldConfig.ts b/sdk/src/physics3d/worldConfig.tsnew file mode 100644index 000000000..8a70d59fc--- /dev/null+++ b/sdk/src/physics3d/worldConfig.ts@@ -0,0 +1,75 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file worldConfig.ts+ * @brief The project's say in how its 3D physics world is made (Project Settings → Physics → 3D).+ *+ * Types and one pure function only: the scene loader reads this without pulling the 3D physics code in.+ */+import type { Vec3 } from '../types';+import type { Physics3DConfig } from './Physics3DSystem';++export interface Physics3DWorldConfig {+ /**+ * Scene units in one metre. 100 (the default): a unit is a centimetre. 1: a unit is a metre, as glTF and most imported+ * 3D scenes are. The solver works in metres, so this is what makes a 1.8-unit character in a metre scene 1.8 m tall+ * rather than 1.8 cm, and keeps its gravity at 9.81 m/s² rather than 9.81 units/s².+ */+ unitsPerMeter: number;+ /** Metres per second squared, whatever the scene unit is. */+ gravity: Vec3;+ /** Collision passes per fixed step: more keeps fast bodies from tunnelling, at their cost. */+ collisionSteps: number;+ /** Bodies the world is sized for; the solver refuses one past it. */+ maxBodies: number;+ /** 0 = the backend's own (Jolt 10 / PhysX 1). */+ velocityIterations: number;+ /** 0 = the backend's own (Jolt 2 / PhysX 6). */+ positionIterations: number;+ enableSleep: boolean;+ /** m/s; slower impacts do not bounce. 0 = the backend's own (Jolt 1 / PhysX 2). */+ bounceThreshold: number;+}++export const DEFAULT_PHYSICS3D_WORLD: Physics3DWorldConfig = {+ unitsPerMeter: 100,+ gravity: { x: 0, y: -9.81, z: 0 },+ collisionSteps: 1,+ maxBodies: 1024,+ velocityIterations: 0,+ positionIterations: 0,+ enableSleep: true,+ bounceThreshold: 0,+};++/** The plugin config a project's 3D world settings ask for; only what is valid and set. */+export function physics3DPluginConfigOf(world: Partial<Physics3DWorldConfig> | undefined): Partial<Physics3DConfig> {+ const out: Partial<Physics3DConfig> = {};+ if (!world) return out;+ const u = world.unitsPerMeter;+ if (typeof u === 'number' && Number.isFinite(u) && u > 0) out.pixelsPerUnit = u;+ const g = world.gravity;+ if (g && [g.x, g.y, g.z].every((v) => typeof v === 'number' && Number.isFinite(v))) out.gravity = { x: g.x, y: g.y, z: g.z };+ const count = (v: unknown, min: number): v is number => typeof v === 'number' && Number.isInteger(v) && v >= min;+ if (count(world.collisionSteps, 1)) out.collisionSteps = world.collisionSteps;+ if (count(world.maxBodies, 1)) out.maxBodies = world.maxBodies;+ if (count(world.velocityIterations, 0)) out.velocityIterations = world.velocityIterations;+ if (count(world.positionIterations, 0)) out.positionIterations = world.positionIterations;+ if (typeof world.enableSleep === 'boolean') out.enableSleep = world.enableSleep;+ const b = world.bounceThreshold;+ if (typeof b === 'number' && Number.isFinite(b) && b >= 0) out.bounceThreshold = b;+ return out;+}++/**+ * Everything the 3D world is made with: the project's 3D world settings, plus the two a game has only one of —+ * the fixed step and the collision matrix — taken from the project's physics settings, as 2D takes them.+ */+export function physics3DInstallConfig(world: Partial<Physics3DWorldConfig> | undefined,+ shared: { fixedTimestep?: number; collisionLayerMasks?: number[] } | undefined): Partial<Physics3DConfig> {+ const out = physics3DPluginConfigOf(world);+ const step = shared?.fixedTimestep;+ if (typeof step === 'number' && Number.isFinite(step) && step > 0) out.fixedTimestep = step;+ if (Array.isArray(shared?.collisionLayerMasks)) out.layerMasks = shared.collisionLayerMasks.slice(0, 16);+ return out;+}diff --git a/sdk/src/runtime/miniGameRuntime.ts b/sdk/src/runtime/miniGameRuntime.tsindex b7bc169c4..08ff9c5da 100644--- a/sdk/src/runtime/miniGameRuntime.ts+++ b/sdk/src/runtime/miniGameRuntime.ts@@ -38,6 +38,7 @@ import { log } from '../util/logger';import { Schedule, defineSystem } from '../ecs/system';import type { App } from '../app/app';import type { Physics3DBackend } from '../sideModules/registry';+import type { Physics3DWorldConfig } from '../physics3d/worldConfig';// =============================================================================// Emscripten WASM Instantiation@@ -126,6 +127,8 @@ export interface MiniGameRuntimeConfig {physicsConfig?: Physics2DPluginConfig;/** The 3D physics backend the project chose; absent ⇒ Jolt. */physics3dBackend?: Physics3DBackend;+ /** The project's 3D world: scene units per metre and gravity (Project Settings → Physics → 3D). Absent ⇒ centimetre units, Earth gravity. */+ physics3dWorld?: Partial<Physics3DWorldConfig>;/** Project-declared UI theme; 'light' re-skins ThemeStyle-tagged widgets at boot. */uiTheme?: 'dark' | 'light';/** Project-declared theme token overrides (partial re-skin over the base). */@@ -348,6 +351,7 @@ export async function initMiniGameRuntime(config: MiniGameRuntimeConfig): PromisphysicsEnabled: config.physicsEnabled,physicsConfig: config.physicsConfig,physics3dBackend: config.physics3dBackend,+ physics3dWorld: config.physics3dWorld,uiTheme: config.uiTheme,uiThemeOverrides: config.uiThemeOverrides,audioConfig: config.audioConfig,diff --git a/sdk/src/runtime/packagedRuntime.ts b/sdk/src/runtime/packagedRuntime.tsindex 632e44b4d..7e51bb14c 100644--- a/sdk/src/runtime/packagedRuntime.ts+++ b/sdk/src/runtime/packagedRuntime.ts@@ -30,6 +30,7 @@ import { VideoPlayer } from '../video/VideoAPI';import type { App } from '../app/app';import type { RuntimeAssetSource } from './runtimeAssets';import { registerSideModule, type Physics3DBackend } from '../sideModules/registry';+import type { Physics3DWorldConfig } from '../physics3d/worldConfig';import type { AotManifest } from '../ecs/aot/AotSystems';/**@@ -107,6 +108,8 @@ export interface PackagedGameConfig {physicsConfig?: Physics2DPluginConfig;/** The 3D physics backend the project chose; absent ⇒ Jolt. */physics3dBackend?: Physics3DBackend;+ /** The project's 3D world: scene units per metre and gravity (Project Settings → Physics → 3D). Absent ⇒ centimetre units, Earth gravity. */+ physics3dWorld?: Partial<Physics3DWorldConfig>;/** Project mixer state: bus volumes, custom buses, effects, duck rules.* Absent ⇒ the default mix. */audioConfig?: AudioProjectConfig;@@ -242,12 +245,14 @@ export function packagedAppOptions(*/export function packagedRuntimeInit(config: Pick<PackagedGameConfig,- 'physicsEnabled' | 'physicsConfig' | 'physics3dBackend' | 'audioConfig' | 'uiTheme' | 'uiThemeColors'+ 'physicsEnabled' | 'physicsConfig' | 'physics3dBackend' | 'physics3dWorld' | 'audioConfig' | 'uiTheme' | 'uiThemeColors'| 'achievements' | 'steamAppId' | 'screenFit' | 'aot' | 'debugChannel' | 'runtime'>,): {physicsEnabled?: boolean;physicsConfig?: Physics2DPluginConfig;physics3dBackend?: Physics3DBackend;+ /** The project's 3D world: scene units per metre and gravity (Project Settings → Physics → 3D). Absent ⇒ centimetre units, Earth gravity. */+ physics3dWorld?: Partial<Physics3DWorldConfig>;audioConfig?: AudioProjectConfig;runtime?: RuntimeBuildConfig;uiTheme?: 'light';@@ -262,6 +267,7 @@ export function packagedRuntimeInit(physicsEnabled: config.physicsEnabled,physicsConfig: config.physicsConfig,physics3dBackend: config.physics3dBackend,+ physics3dWorld: config.physics3dWorld,audioConfig: config.audioConfig,runtime: config.runtime,uiTheme: config.uiTheme,diff --git a/sdk/src/runtime/playRealmRuntime.ts b/sdk/src/runtime/playRealmRuntime.tsindex 9ace76a6e..6c489dbff 100644--- a/sdk/src/runtime/playRealmRuntime.ts+++ b/sdk/src/runtime/playRealmRuntime.ts@@ -36,6 +36,7 @@ import { fetchDecodePixels } from '../asset/imageDecode';import { applyAssetRefResolvers } from './packagedRuntime';import { extractUuid, UUID_REF_PREFIX } from '../asset/AssetRegistry';import type { Physics3DBackend } from '../sideModules/registry';+import type { Physics3DWorldConfig } from '../physics3d/worldConfig';export interface PlayRealmRuntimeConfig {app: App;@@ -88,6 +89,8 @@ export interface PlayRealmRuntimeConfig {physicsConfig?: Physics2DPluginConfig;/** The 3D physics backend the project chose; absent ⇒ Jolt. */physics3dBackend?: Physics3DBackend;+ /** The project's 3D world: scene units per metre and gravity (Project Settings → Physics → 3D). Absent ⇒ centimetre units, Earth gravity. */+ physics3dWorld?: Partial<Physics3DWorldConfig>;/** Project-declared UI theme; 'light' re-skins ThemeStyle-tagged widgets at boot. */uiTheme?: 'dark' | 'light';/** Project-declared theme token overrides (partial re-skin over the base). */@@ -283,6 +286,7 @@ export async function initPlayRealmRuntime(config: PlayRealmRuntimeConfig): PromphysicsEnabled: config.physicsEnabled,physicsConfig: config.physicsConfig,physics3dBackend: config.physics3dBackend,+ physics3dWorld: config.physics3dWorld,uiTheme: config.uiTheme,uiThemeOverrides: config.uiThemeOverrides,audioConfig: config.audioConfig,diff --git a/sdk/src/runtime/playableRuntime.ts b/sdk/src/runtime/playableRuntime.tsindex bce9fbb42..386833dc5 100644--- a/sdk/src/runtime/playableRuntime.ts+++ b/sdk/src/runtime/playableRuntime.ts@@ -27,6 +27,7 @@ import { Input, inputEventCallbacks } from '../input/input';import { playableAdBridge } from './playableCta';import { VideoPlayer } from '../video/VideoAPI';import type { Physics3DBackend } from '../sideModules/registry';+import type { Physics3DWorldConfig } from '../physics3d/worldConfig';export interface PlayableRuntimeConfig {app: App;@@ -52,6 +53,8 @@ export interface PlayableRuntimeConfig {physicsConfig?: Physics2DPluginConfig;/** The 3D physics backend the project chose; absent ⇒ Jolt. */physics3dBackend?: Physics3DBackend;+ /** The project's 3D world: scene units per metre and gravity (Project Settings → Physics → 3D). Absent ⇒ centimetre units, Earth gravity. */+ physics3dWorld?: Partial<Physics3DWorldConfig>;/** Project-declared UI theme; 'light' re-skins ThemeStyle-tagged widgets at boot. */uiTheme?: 'dark' | 'light';/** Project-declared theme token overrides (partial re-skin over the base). */@@ -164,6 +167,7 @@ export async function initPlayableRuntime(config: PlayableRuntimeConfig): PromisphysicsEnabled: config.physicsEnabled,physicsConfig: config.physicsConfig,physics3dBackend: config.physics3dBackend,+ physics3dWorld: config.physics3dWorld,uiTheme: config.uiTheme,uiThemeOverrides: config.uiThemeOverrides,audioConfig: config.audioConfig,diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.tsindex 28e71bc83..2fc151bc5 100644--- a/sdk/src/runtime/runtimeLoader.ts+++ b/sdk/src/runtime/runtimeLoader.ts@@ -61,6 +61,7 @@ import type { DragonBonesAssetInfo } from '../dragonbones/loadDragonBonesScene';import type { AddressableManifest, ManifestModel } from '../asset/AddressableManifest';import type { Catalog } from '../asset/Catalog';import { physics3dModuleId, type Physics3DBackend } from '../sideModules/registry';+import { physics3DInstallConfig, type Physics3DWorldConfig } from '../physics3d/worldConfig';// =============================================================================// Public Interface@@ -211,6 +212,8 @@ export interface LoadRuntimeSceneOptions {physicsConfig?: Physics2DPluginConfig;/** The 3D physics backend; selects the side module the 3D world is acquired from. Absent ⇒ Jolt. */physics3dBackend?: Physics3DBackend;+ /** The project's 3D world: scene units per metre and gravity (Project Settings → Physics → 3D). Absent ⇒ centimetre units, Earth gravity. */+ physics3dWorld?: Partial<Physics3DWorldConfig>;/** Project-declared physics enable (`.uproject` features analog) — installs* physics even for runtime-spawned bodies the static scene doesn't show.* OR-combined with a content scan. */@@ -237,6 +240,7 @@ const PHYSICS_COMPONENT_TYPES = new Set([const PHYSICS3D_COMPONENT_TYPES = new Set(['RigidBody3D', 'BoxCollider3D', 'SphereCollider3D', 'CapsuleCollider3D','MeshCollider3D', 'ConvexCollider3D', 'CharacterController3D',+ 'CompoundCollider3D', 'Ragdoll','PointJoint3D', 'HingeJoint3D', 'SliderJoint3D', 'DistanceJoint3D', 'FixedJoint3D', 'SwingTwistJoint3D', 'SixDOFJoint3D',]);@@ -523,8 +527,9 @@ export async function prepareRuntimeScene(+ ` this realm has no side-module host or the ${options.physics3dBackend ?? 'jolt'} module failed to load`);return;}- p3d.install(app, module3d);- log.info('physics3d', 'installed');+ const config3d = physics3DInstallConfig(options.physics3dWorld, physicsConfig);+ p3d.install(app, module3d, config3d);+ log.info('physics3d', `installed (${config3d.pixelsPerUnit ?? 100} units per metre)`);});}@@ -786,6 +791,8 @@ export interface RuntimeInitConfig {physicsConfig?: Physics2DPluginConfig;/** The 3D physics backend; selects the side module the 3D world is acquired from. Absent ⇒ Jolt. */physics3dBackend?: Physics3DBackend;+ /** The project's 3D world: scene units per metre and gravity (Project Settings → Physics → 3D). Absent ⇒ centimetre units, Earth gravity. */+ physics3dWorld?: Partial<Physics3DWorldConfig>;/** Project-declared physics enable; see {@link LoadRuntimeSceneOptions.physicsEnabled}. */physicsEnabled?: boolean;/** Project-declared mixer state (bus volumes / custom buses / effects / duck@@ -882,6 +889,7 @@ export async function initRuntime(config: RuntimeInitConfig): Promise<void> {physicsModule: config.physicsModule,physicsConfig: config.physicsConfig,physics3dBackend: config.physics3dBackend,+ physics3dWorld: config.physics3dWorld,physicsEnabled: config.physicsEnabled,uiTheme: config.uiTheme,uiThemeOverrides: config.uiThemeOverrides,diff --git a/sdk/src/runtime/sceneOptionals.ts b/sdk/src/runtime/sceneOptionals.tsindex 1219a47d9..76da0e814 100644--- a/sdk/src/runtime/sceneOptionals.ts+++ b/sdk/src/runtime/sceneOptionals.ts@@ -24,6 +24,7 @@ import type {import type { Physics2DPluginConfig } from '../physics/Physics2DPlugin';import type { PhysicsWasmModule } from '../physics/PhysicsModuleLoader';import type { Physics3DWasmModule } from '../physics3d/Physics3DModule';+import type { Physics3DConfig } from '../physics3d/Physics3DSystem';/** What a scene load needs from Spine, when the build ships it. */export interface SpineSupport {@@ -49,7 +50,8 @@ export interface PhysicsSupport {/** 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;+ /** `config`: what the scene's PhysicsWorld3D asked for, already turned into plugin config. */+ install(app: App, module: Physics3DWasmModule, config?: Partial<Physics3DConfig>): void;}/** What a scene load needs from video, when the build ships it. */diff --git a/sdk/tests/physics3d-smoke.mjs b/sdk/tests/physics3d-smoke.mjsindex cde7535ac..08f26ef35 100644--- a/sdk/tests/physics3d-smoke.mjs+++ b/sdk/tests/physics3d-smoke.mjs@@ -787,6 +787,31 @@ step(1);check('compound sensor reports overlap', m._physics3d_sensorEntersBytes() > 0);m._physics3d_removeBody(visitor); m._physics3d_removeBody(sensorCompound);+// ── The project's solver settings reach the solver ─────────────────────────+// A fully elastic ball dropped 1 m meets the floor at ~4.4 m/s. Under a bounce threshold of 10 m/s+// that impact is too slow to bounce; with the backend's own threshold (Jolt 1, PhysX 2) it bounces+// most of the way back. The same drop, one number changed: what differs is the setting.+const peakAfterImpact = (entity, x) => {+ const id = m._physics3d_addSphere(entity, 0.5, x, 1.5, 0, ...IDENTITY, ...FREE(DYNAMIC), 0, 1, 0, 0, 0, 0);+ let touched = false, peak = -Infinity;+ for (let i = 0; i < 120; i++) {+ step(1);+ const y = bodyState(id)?.y ?? NaN;+ if (y < 0.56) touched = true;+ else if (touched) peak = Math.max(peak, y);+ }+ m._physics3d_removeBody(id);+ return touched ? peak : NaN;+};+const solverFloor = m._physics3d_addBox(9300, 5, 0.5, 5, 9000, -0.5, 0, ...IDENTITY, ...FREE(STATIC), 0.5, 1, 0, 0, 0, 0);+m._physics3d_setSolver(0, 0, 1, 10);+const dead = peakAfterImpact(9301, 9000);+check('under a 10 m/s bounce threshold a 4.4 m/s impact does not bounce', !(dead > 0.6), `peak=${dead}`);+m._physics3d_setSolver(0, 0, 1, 0);+const live = peakAfterImpact(9302, 9002);+check('with the backend\'s own threshold the same impact bounces', live > 1.0, `peak=${live}`);+m._physics3d_removeBody(solverFloor);+m._physics3d_shutdown();check('the world reports itself gone', m._physics3d_isReady() === 0);diff --git a/src/esengine/bindings/modules/physics3d/Physics3DBindings.hpp b/src/esengine/bindings/modules/physics3d/Physics3DBindings.hppindex a624be1a2..05cd060d9 100644--- a/src/esengine/bindings/modules/physics3d/Physics3DBindings.hpp+++ b/src/esengine/bindings/modules/physics3d/Physics3DBindings.hpp@@ -36,6 +36,10 @@ int physics3d_isReady();void physics3d_step(float dt, int collisionSteps);void physics3d_optimize();void physics3d_setLayerMask(uint32_t layer, uint32_t mask);+/// The project's solver settings. Each value <= 0 keeps the backend's own default+/// (Jolt's for Jolt, Unity's for PhysX); allowSleep is 0 or 1. After init, before bodies.+void physics3d_setSolver(int velocityIterations, int positionIterations, int allowSleep,+ float bounceThreshold);// Bodiesuint32_t physics3d_addCompound(uint32_t entity, uintptr_t partsPtr, uint32_t count,diff --git a/src/esengine/bindings/modules/physics3d/Physics3DModuleEntry.cpp b/src/esengine/bindings/modules/physics3d/Physics3DModuleEntry.cppindex 7bdcf0bbf..dcd4722b0 100644--- a/src/esengine/bindings/modules/physics3d/Physics3DModuleEntry.cpp+++ b/src/esengine/bindings/modules/physics3d/Physics3DModuleEntry.cpp@@ -267,6 +267,21 @@ void physics3d_setLayerMask(uint32_t layer, uint32_t mask) {}}+EMSCRIPTEN_KEEPALIVE+void physics3d_setSolver(int velocityIterations, int positionIterations, int allowSleep,+ float bounceThreshold) {+ if (!g().isValid()) return;+ // From Jolt's own defaults, not from what is set now: 0 means "Jolt's value", so a+ // setting cleared after being changed goes back rather than staying where it was.+ const PhysicsSettings jolt;+ PhysicsSettings settings = g().system->GetPhysicsSettings();+ settings.mNumVelocitySteps = velocityIterations > 0 ? static_cast<JPH::uint>(velocityIterations) : jolt.mNumVelocitySteps;+ settings.mNumPositionSteps = positionIterations > 0 ? static_cast<JPH::uint>(positionIterations) : jolt.mNumPositionSteps;+ settings.mAllowSleeping = allowSleep != 0;+ settings.mMinVelocityForRestitution = bounceThreshold > 0.0f ? bounceThreshold : jolt.mMinVelocityForRestitution;+ g().system->SetPhysicsSettings(settings);+}+/// Advance the world, then refill the transform buffer with every active body.EMSCRIPTEN_KEEPALIVEvoid physics3d_step(float dt, int collisionSteps) {diff --git a/src/esengine/bindings/modules/physics3d_physx/PhysXModuleEntry.cpp b/src/esengine/bindings/modules/physics3d_physx/PhysXModuleEntry.cppindex d062a3a94..179b513ab 100644--- a/src/esengine/bindings/modules/physics3d_physx/PhysXModuleEntry.cpp+++ b/src/esengine/bindings/modules/physics3d_physx/PhysXModuleEntry.cpp@@ -46,6 +46,10 @@ constexpr float MAX_ANGULAR_VELOCITY = 50.0f;constexpr float MAX_DEPENETRATION_VELOCITY = 10.0f;constexpr uint32_t POSITION_ITERATIONS = 6;constexpr uint32_t VELOCITY_ITERATIONS = 1;+/// What the project asked for (physics3d_setSolver), the constants above until it asks.+uint32_t gPositionIterations = POSITION_ITERATIONS;+uint32_t gVelocityIterations = VELOCITY_ITERATIONS;+bool gAllowSleep = true;constexpr float BOUNCE_THRESHOLD = 2.0f;/// The ABI names no mass, so a body weighs what its volume of water would: the/// density the Jolt backend uses, so switching backend does not change a scene.@@ -222,8 +226,9 @@ uint32_t addBody(uint32_t entity, const PxGeometry& geometry, const PxTransform&dynamic->setAngularDamping(how.angularDamping);dynamic->setMaxAngularVelocity(MAX_ANGULAR_VELOCITY);dynamic->setMaxDepenetrationVelocity(MAX_DEPENETRATION_VELOCITY);- dynamic->setSleepThreshold(SLEEP_THRESHOLD);- dynamic->setSolverIterationCounts(POSITION_ITERATIONS, VELOCITY_ITERATIONS);+ // A threshold of 0 is energy no body falls below: it never sleeps.+ dynamic->setSleepThreshold(gAllowSleep ? SLEEP_THRESHOLD : 0.0f);+ dynamic->setSolverIterationCounts(gPositionIterations, gVelocityIterations);if (how.fixedRotation != 0) {dynamic->setRigidDynamicLockFlags(PxRigidDynamicLockFlag::eLOCK_ANGULAR_X| PxRigidDynamicLockFlag::eLOCK_ANGULAR_Y | PxRigidDynamicLockFlag::eLOCK_ANGULAR_Z);@@ -356,6 +361,15 @@ void physics3d_setLayerMask(uint32_t layer, uint32_t mask) {if (layer < px3::LAYER_COUNT) g().masks[layer] = mask;}+EMSCRIPTEN_KEEPALIVE+void physics3d_setSolver(int velocityIterations, int positionIterations, int allowSleep,+ float bounceThreshold) {+ gVelocityIterations = velocityIterations > 0 ? static_cast<uint32_t>(velocityIterations) : VELOCITY_ITERATIONS;+ gPositionIterations = positionIterations > 0 ? static_cast<uint32_t>(positionIterations) : POSITION_ITERATIONS;+ gAllowSleep = allowSleep != 0;+ if (g().isValid()) g().scene->setBounceThresholdVelocity(bounceThreshold > 0.0f ? bounceThreshold : BOUNCE_THRESHOLD);+}+EMSCRIPTEN_KEEPALIVEvoid physics3d_step(float dt, int collisionSteps) {if (!g().isValid() || dt <= 0.0f) return;diff --git a/tools/check-project-settings.mjs b/tools/check-project-settings.mjsindex 71c284f35..b3bdcd262 100644--- a/tools/check-project-settings.mjs+++ b/tools/check-project-settings.mjs@@ -87,6 +87,9 @@ const DECLARED_GAPS = {physicsConfig: {editor: 'edit mode does not simulate — see physicsEnabled',},+ physics3dWorld: {+ editor: 'edit mode does not simulate — see physicsEnabled',+ },colorSpace: {editor: 'boot-fixed — shaders compile against it, so the settings page asks '+ 'for a reload rather than applying live (EngineHost.resolveColorSpace)',@@ -123,6 +126,7 @@ const PARSE_KEY = {physicsEnabled: 'p.enabled',physicsConfig: 'physics',physics3dBackend: 'backend3d',+ physics3dWorld: 'world3d',audioConfig: 'parseAudioProjectConfig',runtime: 'parseRuntimeBuildConfig',uiTheme: 'u.theme',@@ -148,6 +152,7 @@ const AUTHORING = {steamAppId: { ui: 'project.packaging.desktop.steam.appId' },physicsEnabled: { ui: 'project.physics.enabled' },physics3dBackend: { ui: 'project.physics.backend3d' },+ physics3dWorld: { ui: ['project.physics.world3d.'] },physicsConfig: { ui: ['project.physics.gravityX', 'project.physics.gravityY', 'project.physics.fixedTimestep'] },audioConfig: { ui: ['project.audio.maxVoices', 'project.audio.buses', 'project.audio.effects'] },runtime: { ui: ['project.runtime.'] },