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
fix(physics): query ppu defaults to the live Canvas, not 100 (P4)
esenginef900c69ba594
diff --git a/docs/REARCH_PHYSICS.md b/docs/REARCH_PHYSICS.mdindex 92a415426..490ae0602 100644--- a/docs/REARCH_PHYSICS.md+++ b/docs/REARCH_PHYSICS.md@@ -1,10 +1,12 @@# Physics Architecture — Audit & Rearchitecture-**Status (2026-06-21):** audit complete; **P1 DONE** (FixedUpdate determinism + render-interpolation); **P2 DONE** (unified reconciler — runtime collider/joint/enabled-mutability). Physics core = **Box2D 3.2.0** (the v3 rewrite) in a side wasm module-(`third_party/box2d`, C++ bindings `src/esengine/bindings/Physics*.cpp`), wrapped by the-TS SDK (`sdk/src/physics/*`).+**Status (2026-06-21):** audit complete; **P1–P3 DONE**, **P4 partial** (the safe query+`ppu` fix landed; the perf opts that need live profiling/render verification are deferred).+P1 = FixedUpdate determinism + render interpolation; P2 = unified reconciler (runtime+collider/joint/enabled mutability); P3 = contact hit events + world-toggle config surface.+Physics core = **Box2D 3.2.0** (the v3 rewrite) in a side wasm module (`third_party/box2d`,+C++ bindings `src/esengine/bindings/Physics*.cpp`), wrapped by the TS SDK+(`sdk/src/physics/*`).## Verdict@@ -90,8 +92,17 @@ in the integration layer.gameplay. The **`b2World_GetBodyEvents` moved-only readback moved to P4** — it's a perfoptimization that interacts with the P1 interpolation snapshots, so it's grouped with theother perf items rather than risked here.-- **P4 — `b2World_GetBodyEvents` moved-only readback + batched writeback + identity-leak- fixes + query `ppu` from live Canvas.**+- **P4 — partial.** **DONE: query `ppu` from the live Canvas** — `Physics` queries+ (`raycast`/`overlap*`/`shapeCast*`) defaulted `ppu = 100` (a silent wrong-scale footgun);+ they now default to a live `ppu_` that `PhysicsSystem` pushes from the Canvas each step+ (SDK-only, no wasm rebuild). **DEFERRED (perf / completeness, need live profiling ++ render verification this environment can't do):** `b2World_GetBodyEvents` moved-only+ readback (interacts with the P1 interpolation snapshots — a body must snap on+ `fellAsleep` to avoid a sub-step rest offset); batched writeback (mirror the batched+ readback for kinematic/prop writes — marginal, few kinematic bodies); chain-collider+ runtime rebuild (track `b2ChainId` so `clearShapes` covers chains — chains are static+ level geometry, rarely rebuilt); the `entityToJoint`-keyed-by-`entityB` overwrite is a+ non-issue under the one-joint-per-entity invariant.## P1 — design (SDK-only)diff --git a/sdk/src/physics/Physics.ts b/sdk/src/physics/Physics.tsindex e887bcf1f..27aa8ae0e 100644--- a/sdk/src/physics/Physics.ts+++ b/sdk/src/physics/Physics.ts@@ -27,6 +27,14 @@ import {export class Physics {private module_: PhysicsWasmModule;+ // Live pixels-per-unit, pushed each frame by PhysicsSystem from the Canvas, so+ // a query that omits `ppu` is scaled correctly instead of silently assuming 100.+ private ppu_ = 100;++ /** @internal Update the pixels-per-unit used to scale queries by default. */+ setPixelsPerUnit(ppu: number): void {+ if (ppu > 0) this.ppu_ = ppu;+ }constructor(app: App) {const module = app.hasResource(PhysicsRuntime)@@ -142,7 +150,7 @@ export class Physics {raycast(origin: Vec2, direction: Vec2, maxDistance: number,- maskBits = 0xFFFF, ppu = 100,+ maskBits = 0xFFFF, ppu = this.ppu_,): RaycastHit[] {const invPpu = 1 / ppu;const count = this.module_._physics_raycast(@@ -167,7 +175,7 @@ export class Physics {return results;}- overlapCircle(center: Vec2, radius: number, maskBits = 0xFFFF, ppu = 100): Entity[] {+ overlapCircle(center: Vec2, radius: number, maskBits = 0xFFFF, ppu = this.ppu_): Entity[] {const invPpu = 1 / ppu;const count = this.module_._physics_overlapCircle(center.x * invPpu, center.y * invPpu,@@ -186,7 +194,7 @@ export class Physics {shapeCastCircle(center: Vec2, radius: number, translation: Vec2,- maskBits = 0xFFFF, ppu = 100,+ maskBits = 0xFFFF, ppu = this.ppu_,): ShapeCastHit[] {const invPpu = 1 / ppu;const count = this.module_._physics_shapeCastCircle(@@ -198,7 +206,7 @@ export class Physics {shapeCastBox(center: Vec2, halfExtents: Vec2, angle: number, translation: Vec2,- maskBits = 0xFFFF, ppu = 100,+ maskBits = 0xFFFF, ppu = this.ppu_,): ShapeCastHit[] {const invPpu = 1 / ppu;const count = this.module_._physics_shapeCastBox(@@ -211,7 +219,7 @@ export class Physics {shapeCastCapsule(center1: Vec2, center2: Vec2, radius: number, translation: Vec2,- maskBits = 0xFFFF, ppu = 100,+ maskBits = 0xFFFF, ppu = this.ppu_,): ShapeCastHit[] {const invPpu = 1 / ppu;const count = this.module_._physics_shapeCastCapsule(@@ -223,7 +231,7 @@ export class Physics {return this.readShapeCastBuffer_(count, ppu);}- overlapAABB(min: Vec2, max: Vec2, maskBits = 0xFFFF, ppu = 100): Entity[] {+ overlapAABB(min: Vec2, max: Vec2, maskBits = 0xFFFF, ppu = this.ppu_): Entity[] {const invPpu = 1 / ppu;const count = this.module_._physics_overlapAABB(min.x * invPpu, min.y * invPpu,@@ -240,7 +248,7 @@ export class Physics {return this.module_._physics_getBodyInertia(entity);}- getCenterOfMass(entity: Entity, ppu = 100): Vec2 {+ getCenterOfMass(entity: Entity, ppu = this.ppu_): Vec2 {const ptr = this.module_._physics_getBodyCenterOfMass(entity);const base = ptr >> 2;return {@@ -249,7 +257,7 @@ export class Physics {};}- getMassData(entity: Entity, ppu = 100): MassData {+ getMassData(entity: Entity, ppu = this.ppu_): MassData {return {mass: this.getMass(entity),inertia: this.getInertia(entity),@@ -257,15 +265,15 @@ export class Physics {};}- getDistanceJointLength(entity: Entity, ppu = 100): number {+ getDistanceJointLength(entity: Entity, ppu = this.ppu_): number {return this.module_._physics_getDistanceJointLength(entity) * ppu;}- getDistanceJointCurrentLength(entity: Entity, ppu = 100): number {+ getDistanceJointCurrentLength(entity: Entity, ppu = this.ppu_): number {return this.module_._physics_getDistanceJointCurrentLength(entity) * ppu;}- setDistanceJointLength(entity: Entity, length: number, ppu = 100): void {+ setDistanceJointLength(entity: Entity, length: number, ppu = this.ppu_): void {this.module_._physics_setDistanceJointLength(entity, length / ppu);}@@ -277,7 +285,7 @@ export class Physics {this.module_._physics_enableDistanceJointLimit(entity, enable ? 1 : 0);}- setDistanceJointLimits(entity: Entity, minLength: number, maxLength: number, ppu = 100): void {+ setDistanceJointLimits(entity: Entity, minLength: number, maxLength: number, ppu = this.ppu_): void {this.module_._physics_setDistanceJointLimits(entity, minLength / ppu, maxLength / ppu);}@@ -297,11 +305,11 @@ export class Physics {return this.module_._physics_getDistanceJointMotorForce(entity);}- getPrismaticJointTranslation(entity: Entity, ppu = 100): number {+ getPrismaticJointTranslation(entity: Entity, ppu = this.ppu_): number {return this.module_._physics_getPrismaticJointTranslation(entity) * ppu;}- getPrismaticJointSpeed(entity: Entity, ppu = 100): number {+ getPrismaticJointSpeed(entity: Entity, ppu = this.ppu_): number {return this.module_._physics_getPrismaticJointSpeed(entity) * ppu;}@@ -313,7 +321,7 @@ export class Physics {this.module_._physics_enablePrismaticJointLimit(entity, enable ? 1 : 0);}- setPrismaticJointLimits(entity: Entity, lower: number, upper: number, ppu = 100): void {+ setPrismaticJointLimits(entity: Entity, lower: number, upper: number, ppu = this.ppu_): void {this.module_._physics_setPrismaticJointLimits(entity, lower / ppu, upper / ppu);}@@ -341,7 +349,7 @@ export class Physics {this.module_._physics_enableWheelJointLimit(entity, enable ? 1 : 0);}- setWheelJointLimits(entity: Entity, lower: number, upper: number, ppu = 100): void {+ setWheelJointLimits(entity: Entity, lower: number, upper: number, ppu = this.ppu_): void {this.module_._physics_setWheelJointLimits(entity, lower / ppu, upper / ppu);}diff --git a/sdk/src/physics/PhysicsSystem.ts b/sdk/src/physics/PhysicsSystem.tsindex b08c2d1ea..9a31841d3 100644--- a/sdk/src/physics/PhysicsSystem.ts+++ b/sdk/src/physics/PhysicsSystem.ts@@ -16,6 +16,7 @@ import { Res, Time, type TimeData } from '../resource';import { Schedule, defineSystem } from '../system';import { playModeOnly } from '../env';import type { PhysicsWasmModule } from './PhysicsModuleLoader';+import { PhysicsAPI } from './Physics';import {RigidBody, BoxCollider, CircleCollider, CapsuleCollider,SegmentCollider, PolygonCollider, ChainCollider,@@ -650,6 +651,9 @@ export function registerPhysicsSystem(// value captured when the wasm module first loaded.const ppu = readPixelsPerUnit(app);const invPpu = 1 / ppu;+ // Keep the query API's default scale in sync with the live Canvas,+ // so raycast/overlap that omit `ppu` aren't silently scaled to 100.+ if (app.hasResource(PhysicsAPI)) app.getResource(PhysicsAPI).setPixelsPerUnit(ppu);const entities = world.getEntitiesWithComponents([RigidBody, Transform]);const currentEntities = new Set<Entity>();