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.

fix(physics): query ppu defaults to the live Canvas, not 100 (P4)

esenginef900c69ba594
diff --git a/docs/REARCH_PHYSICS.md b/docs/REARCH_PHYSICS.md
index 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 perf
optimization that interacts with the P1 interpolation snapshots, so it's grouped with the
other 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.ts
index 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.ts
index 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>();