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): physics produces transform inputs, and stops authoring the output

esenginee48515d5df80
diff --git a/bench/replication-interest/README.md b/bench/replication-interest/README.md
index 5b51832cb..25a3d1b11 100644
--- a/bench/replication-interest/README.md
+++ b/bench/replication-interest/README.md
@@ -202,14 +202,12 @@ Three things are asserted rather than assumed:
- The per-connection dirty and removal filters are timed and counted but stay
tiny at these rates. If a provider removes the interest query, `C × (D + R)`
is the next thing to look at — measured, not guessed.
-- **The composed output has a second author, and an incremental provider is not
- production-complete until that is resolved.** `registry_batchSyncPhysics-
- Transforms` writes `worldPosition`/`worldRotation`/`worldScale` itself, marks
- the transform decomposed, and bypasses `TransformSystem` — so a provider fed by
- what the COMPOSITION says changed would silently not contain any physics-driven
- entity. Composition has a canonical author now, which is what turns that into a
- question with an answer; it is not this one. See
- `bench/transform-composition/README.md` for what the composition can hand over.
+- ~~The composed output has a second author.~~ **Closed.** The 2D physics
+ writeback wrote the world fields itself and bypassed `TransformSystem`, so a
+ provider fed by the composed delta would not have contained one physics-driven
+ entity. It writes the local input now and says the composition is stale; a
+ parented body's solver pose is solved back through its parent. This workload
+ runs no physics, so what it measures is unchanged.
- Custom `position()` readers are why a provider cannot simply index everything:
the server has no way to know when a caller's arbitrary function would return
something new. That is a design constraint on any provider, not a cost measured here.
diff --git a/bench/transform-composition/README.md b/bench/transform-composition/README.md
index f99dd5b15..42b1869db 100644
--- a/bench/transform-composition/README.md
+++ b/bench/transform-composition/README.md
@@ -93,12 +93,11 @@ never move their probe, so the check is live where movement is.
## What this does not cover
-- **Physics is a second author of the composed output.** `registry_batchSync-
- PhysicsTransforms` writes the world fields itself, `decomposed_ = true`,
- without going through `TransformSystem`. A journal built on this collection
- would not contain those entities. **Not production-complete until that
- ownership is resolved** — the composition has a canonical author now, which is
- what makes it a question with an answer, but it is not this one.
+- ~~Physics is a second author of the composed output.~~ **Closed**: the 2D
+ writeback produces local inputs and announces staleness, so physics-driven
+ entities arrive in this set like any other. 3D physics already wrote only
+ local inputs — but it treats the solver pose as local unconditionally, which
+ is a parented-body bug of its own and not an authorship one.
- Nothing ships. `composeCollecting` has one caller and it is this bench; the
shipped `ensureComposed` path collects nothing and pays one predictable branch
per entity, which the A column is what says is affordable.
diff --git a/sdk/src/physics/PhysicsSystem.ts b/sdk/src/physics/PhysicsSystem.ts
index c1588d8f1..46b7de4fc 100644
--- a/sdk/src/physics/PhysicsSystem.ts
+++ b/sdk/src/physics/PhysicsSystem.ts
@@ -345,14 +345,6 @@ function syncOneWayPlatforms(
// Dynamic transform readback (wasm -> ECS Transform components)
// =============================================================================
-const syncTransformBuf_ = {
- position: { x: 0, y: 0, z: 0 },
- rotation: { w: 1, x: 0, y: 0, z: 0 },
- scale: { x: 1, y: 1, z: 1 },
- worldPosition: { x: 0, y: 0, z: 0 },
- worldRotation: { w: 1, x: 0, y: 0, z: 0 },
- worldScale: { x: 1, y: 1, z: 1 },
-};
const PHYSICS_BODY_STRIDE = 4; // u32 entity + 3x f32 (x, y, angle)
const PHYSICS_BODY_BYTES = PHYSICS_BODY_STRIDE * 4;
@@ -418,6 +410,11 @@ export function applyPhysics2DTransforms(
}
}
+ // The per-body loop writes the component heap directly and calls no C++, so
+ // the composition is told here. The batch path above says so itself, and one
+ // parented body sends EVERY body down this one.
+ app.world.invalidateTransformComposition();
+
const transformPtrFn = engineMod?.getTransformPtr;
const getTransformPtr = transformPtrFn
? (e: Entity) => transformPtrFn.call(engineMod, registry!, e as number)
@@ -429,7 +426,6 @@ export function applyPhysics2DTransforms(
// the heap — add one to this loop and these must be re-read per iteration.
const engF32 = engineMod?.HEAPF32;
const addFn = (!getTransformPtr || !engF32) ? registry.addTransform.bind(registry) : null;
- const t = syncTransformBuf_;
// A parented body's pose has to be expressed in its parent's space, which only
// the registry can answer — so these go one at a time, over the same buffer.
@@ -469,10 +465,9 @@ export function applyPhysics2DTransforms(
const tPtr = getTransformPtr(entityId);
if (tPtr) {
const fi = tPtr >> 2;
- // Physics owns position + rotation only; scale (fi+7..9 local,
- // fi+17..19 world) is left untouched, matching the batch path —
- // clobbering it to 1 shrank a scaled dynamic body the moment any
- // physics body gained a Parent (which routes all bodies here).
+ // The local INPUT fields and nothing else. Scale (fi+7..9) is the
+ // scene's — clobbering it to 1 shrank a scaled dynamic body — and
+ // the composed world fields (fi+10..19) are TransformSystem's.
engF32[fi] = localX;
engF32[fi + 1] = localY;
engF32[fi + 2] = 0;
@@ -480,31 +475,25 @@ export function applyPhysics2DTransforms(
engF32[fi + 4] = 0;
engF32[fi + 5] = sinH;
engF32[fi + 6] = cosH;
- engF32[fi + 10] = localX;
- engF32[fi + 11] = localY;
- engF32[fi + 12] = 0;
- engF32[fi + 13] = 0;
- engF32[fi + 14] = 0;
- engF32[fi + 15] = sinH;
- engF32[fi + 16] = cosH;
continue;
}
}
- t.position.x = localX;
- t.position.y = localY;
- t.rotation.w = cosH;
- t.rotation.x = 0;
- t.rotation.y = 0;
- t.rotation.z = sinH;
- t.worldPosition.x = localX;
- t.worldPosition.y = localY;
- t.worldRotation.w = cosH;
- t.worldRotation.x = 0;
- t.worldRotation.y = 0;
- t.worldRotation.z = sinH;
-
- addFn!(entityId, t);
+ // Reading first means this path has to ask what the batch and pointer
+ // paths get from the registry for free: the body may name an entity that
+ // is gone, or one that never carried a Transform.
+ if (!app.world.valid(entityId) || !app.world.has(entityId, Transform)) continue;
+ // This path REPLACES the whole component, so the composed fields have to
+ // be carried across as they stand: a value from this loop would be this
+ // path authoring them.
+ const current = app.world.get(entityId, Transform) as TransformData;
+ current.position.x = localX;
+ current.position.y = localY;
+ current.rotation.w = cosH;
+ current.rotation.x = 0;
+ current.rotation.y = 0;
+ current.rotation.z = sinH;
+ addFn!(entityId, current);
}
}
diff --git a/sdk/tests/physics-transform-authority.test.ts b/sdk/tests/physics-transform-authority.test.ts
new file mode 100644
index 000000000..026f4bdd8
--- /dev/null
+++ b/sdk/tests/physics-transform-authority.test.ts
@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Who authors a physics body's composed world transform.
+ *
+ * `position`/`rotation`/`scale` are the composition's input and `worldPosition`
+ * and friends are its output, which one system authors. So these run against the
+ * real composer and check that physics moves the world fields only through it —
+ * including under a parent, where the solver's answer is not the local one.
+ */
+import { describe, it, expect, beforeAll, vi } from 'vitest';
+import { App } from '../src/app/app';
+import { Transform } from '../src/ecs/component';
+import type { TransformData } from '../src/ecs/component';
+import type { Entity } from '../src/types';
+import type { PhysicsWasmModule } from '../src/physics/PhysicsModuleLoader';
+import { applyPhysics2DTransforms } from '../src/physics/PhysicsSystem';
+import type { CppRegistry, ESEngineModule } from '../src/wasm';
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
+
+const PPU = 100;
+
+/** The solver's answer, in the layout the module hands over: [entity, x, y, angle]. */
+function poseBuffer(bodies: Array<{ entity: number; x: number; y: number; angle: number }>) {
+ const ptr = 256;
+ const buffer = new ArrayBuffer(ptr + bodies.length * 16);
+ const f32 = new Float32Array(buffer);
+ const u32 = new Uint32Array(buffer);
+ bodies.forEach((b, i) => {
+ const base = (ptr >> 2) + i * 4;
+ u32[base] = b.entity;
+ f32[base + 1] = b.x;
+ f32[base + 2] = b.y;
+ f32[base + 3] = b.angle;
+ });
+ return { ptr, count: bodies.length, f32, u32, buffer };
+}
+
+function mockPhysics(buf: ReturnType<typeof poseBuffer>): PhysicsWasmModule {
+ return {
+ _physics_capturePoses: vi.fn(),
+ _physics_getInterpolatedCount: () => buf.count,
+ _physics_getInterpolatedTransforms: () => buf.ptr,
+ HEAPF32: buf.f32,
+ HEAPU32: buf.u32,
+ HEAPU8: new Uint8Array(buf.buffer),
+ _malloc: vi.fn(),
+ _free: vi.fn(),
+ } as unknown as PhysicsWasmModule;
+}
+
+describe.skipIf(!HAS_WASM)('physics writes transform inputs, not composed outputs', () => {
+ let module: ESEngineModule;
+ beforeAll(async () => { module = await loadWasmModule(); });
+
+ function scene() {
+ const app = App.new();
+ app.connectCpp(new module.Registry() as unknown as CppRegistry, module);
+ const world = app.world;
+ return { app, world };
+ }
+ const local = (world: App['world'], e: Entity) =>
+ (world.get(e, Transform) as TransformData).position;
+ const composed = (world: App['world'], e: Entity) =>
+ (world.get(e, Transform) as TransformData).worldPosition;
+
+ it('a root body: the solver pose becomes the local input, the composer the output', () => {
+ const { app, world } = scene();
+ const body = world.spawn('body');
+ world.insert(body, Transform, { position: { x: 0, y: 0, z: 0 } });
+ world.ensureTransformsComposed();
+
+ applyPhysics2DTransforms(app, PPU, new Set(),
+ mockPhysics(poseBuffer([{ entity: body as number, x: 2.5, y: 0, angle: 0 }])), 1);
+
+ expect(local(world, body).x).toBeCloseTo(250);
+ world.ensureTransformsComposed();
+ expect(composed(world, body).x).toBeCloseTo(250);
+ world.disconnectCpp();
+ });
+
+ it('a parented body: the solver pose is world, and the local input is solved for', () => {
+ const { app, world } = scene();
+ const parent = world.spawn('parent');
+ world.insert(parent, Transform, { position: { x: 100, y: 0, z: 0 } });
+ const child = world.spawn('child');
+ world.insert(child, Transform, { position: { x: 5, y: 0, z: 0 } });
+ world.setParent(child, parent);
+ world.ensureTransformsComposed();
+ expect(composed(world, child).x).toBeCloseTo(105);
+
+ // The solver knows only world space: this body is at 130, whoever its
+ // parent is. What has to reach the Transform is 30.
+ applyPhysics2DTransforms(app, PPU, new Set([child]),
+ mockPhysics(poseBuffer([{ entity: child as number, x: 1.3, y: 0, angle: 0 }])), 1);
+
+ expect(local(world, child).x).toBeCloseTo(30);
+ world.ensureTransformsComposed();
+ expect(composed(world, child).x).toBeCloseTo(130);
+ world.disconnectCpp();
+ });
+
+ it('a parented body under a rotated parent round-trips through the composer', () => {
+ const { app, world } = scene();
+ const parent = world.spawn('parent');
+ // A quarter turn about Z, at world (100, 0).
+ const h = Math.PI / 4;
+ world.insert(parent, Transform, {
+ position: { x: 100, y: 0, z: 0 },
+ rotation: { w: Math.cos(h), x: 0, y: 0, z: Math.sin(h) },
+ });
+ const child = world.spawn('child');
+ world.insert(child, Transform, { position: { x: 0, y: 0, z: 0 } });
+ world.setParent(child, parent);
+ world.ensureTransformsComposed();
+
+ applyPhysics2DTransforms(app, PPU, new Set([child]),
+ mockPhysics(poseBuffer([{ entity: child as number, x: 1.3, y: 0, angle: 0 }])), 1);
+
+ // Rotating the offset back through the parent puts it on the parent's
+ // local -Y, and composing turns it into world +X again.
+ expect(local(world, child).x).toBeCloseTo(0);
+ expect(local(world, child).y).toBeCloseTo(-30);
+ world.ensureTransformsComposed();
+ expect(composed(world, child).x).toBeCloseTo(130);
+ expect(composed(world, child).y).toBeCloseTo(0, 3);
+ world.disconnectCpp();
+ });
+
+ it('a physics step says the composition is stale, on either write path', () => {
+ for (const parented of [false, true]) {
+ const { app, world } = scene();
+ const body = world.spawn('body');
+ world.insert(body, Transform, { position: { x: 0, y: 0, z: 0 } });
+ world.ensureTransformsComposed();
+
+ const before = world.transformEpoch();
+ applyPhysics2DTransforms(app, PPU, parented ? new Set([body]) : new Set(),
+ mockPhysics(poseBuffer([{ entity: body as number, x: 1, y: 0, angle: 0 }])), 1);
+ expect(world.transformEpoch(), parented ? 'per-body path' : 'batch path')
+ .not.toBe(before);
+ world.disconnectCpp();
+ }
+ });
+
+ // Both paths, because one parented body sends EVERY body down the per-body
+ // loop — so a scene without one never reaches the batched C++ write at all,
+ // and a criterion that only builds parented scenes cannot see it author.
+ it.each(['batch', 'per-body'] as const)(
+ 'the world fields do not move until the composer moves them (%s)', (path) => {
+ const { app, world } = scene();
+ const root = world.spawn('root');
+ world.insert(root, Transform, { position: { x: 7, y: 0, z: 0 } });
+ const parent = world.spawn('parent');
+ world.insert(parent, Transform, { position: { x: 100, y: 0, z: 0 } });
+ const child = world.spawn('child');
+ world.insert(child, Transform, { position: { x: 5, y: 0, z: 0 } });
+ world.setParent(child, parent);
+ world.ensureTransformsComposed();
+
+ const perBody = path === 'per-body';
+ const bodies = [{ entity: root as number, x: 9, y: 0, angle: 0 }];
+ if (perBody) bodies.push({ entity: child as number, x: 1.3, y: 0, angle: 0 });
+ applyPhysics2DTransforms(app, PPU, perBody ? new Set([child]) : new Set(),
+ mockPhysics(poseBuffer(bodies)), 1);
+
+ // Physics has written its inputs and nothing else, so a reader that
+ // has not composed still gets the answer from before the step.
+ expect(composed(world, root).x).toBeCloseTo(7);
+ if (perBody) expect(composed(world, child).x).toBeCloseTo(105);
+ world.ensureTransformsComposed();
+ expect(composed(world, root).x).toBeCloseTo(900);
+ if (perBody) expect(composed(world, child).x).toBeCloseTo(130);
+ world.disconnectCpp();
+ });
+});
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index db42d4722..c52ce6204 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -833,9 +833,8 @@ u32 registry_getGeneration(ecs::Registry& registry, u32 entity) {
}
void registry_batchSyncPhysicsTransforms(ecs::Registry& registry, uintptr_t bufferPtr, int count, float ppu) {
- // Writes local position and rotation for every synced body. It also writes
- // the world fields itself — a second author for those, tracked separately —
- // but the local write alone is what makes the composition stale.
+ // Physics is a producer of transform INPUTS. The composed world fields are
+ // TransformSystem's, and writing them here made this a second author of them.
ecs::invalidateTransformComposition();
if (count < 0) return;
const float* buffer = boundarySpan<f32>(bufferPtr, static_cast<u64>(count) * 4, "registry_batchSyncPhysicsTransforms");
@@ -858,11 +857,6 @@ void registry_batchSyncPhysicsTransforms(ecs::Registry& registry, uintptr_t buff
transform.position.x = px;
transform.position.y = py;
transform.rotation = rot;
-
- transform.worldPosition.x = px;
- transform.worldPosition.y = py;
- transform.worldRotation = rot;
- transform.decomposed_ = true;
}
}
diff --git a/tools/census-transform-writers.mjs b/tools/census-transform-writers.mjs
index 773493eaf..a91300046 100644
--- a/tools/census-transform-writers.mjs
+++ b/tools/census-transform-writers.mjs
@@ -65,6 +65,21 @@ const SEAMS = [
},
];
+/**
+ * Who may write the composition's OUTPUT. A second author is invisible to
+ * anything fed by what the composition reports: a spatial index built on the
+ * composed delta would not contain one physics-driven entity.
+ */
+const OUTPUT_AUTHORS = new Map([
+ ['src/esengine/ecs/TransformSystem.hpp', 'the canonical composer'],
+ ['src/esengine/ecs/components/Transform.hpp', '`ensureDecomposed`, the composer\'s own lazy half'],
+]);
+const OUTPUT_FIELDS = ['worldPosition', 'worldRotation', 'worldScale', 'cachedMatrix_', 'decomposed_'];
+/** A write to one, through anything or through nothing. No binding heuristic:
+ * a struct with these field names IS a Transform, and the point is to leave no
+ * spelling of the write that the scan does not see. */
+const OUTPUT_WRITE = new RegExp(String.raw`(?:(?:\.|->)\s*|^\s*)(${OUTPUT_FIELDS.join('|')})\s*(?:\.\w+\s*)?=[^=]`);
+
/** The hierarchy is the composition's other input, and one function writes it. */
const HIERARCHY_WRITER = { file: 'src/esengine/ecs/TransformSystem.hpp', fn: 'setParent' };
@@ -79,6 +94,10 @@ const TS_PRODUCERS = [
['Query(Mut(Transform)) write-back', 'ptr setter → wasm heap'],
['Web AOT Mut(Transform)', 'compiled code → component address'],
['Native AOT Mut(Transform)', 'compiled code → component address'],
+ // Deliberately outside recordComponentWrite_: it rewrites every dynamic body
+ // every step, so reporting Changed(Transform) would drown that signal. It
+ // announces staleness directly instead.
+ ['2D physics writeback', 'resolved Transform pointer, by word index'],
];
const FIELDS = String.raw`(position|rotation|scale)`;
@@ -129,9 +148,25 @@ function depths(lines) {
return out;
}
-const { files, missing } = listTrackedSources(['src']);
+const { files, missing } = listTrackedSources(['src', 'sdk/src']);
const cpp = files.filter((f) => /\.(cpp|hpp)$/.test(f));
+/**
+ * The composed output's word range in the Transform pointer layout, read from
+ * the generated table rather than counted here: a TS producer writes those slots
+ * by index, and a number in this file would be the one that went stale.
+ */
+function composedOutputWords() {
+ const text = readFileSync(path.join(ROOT, 'sdk/src/wasm/ptrLayouts.generated.ts'), 'utf8');
+ const block = /Transform:\s*\{[\s\S]*?fields:\s*\[([\s\S]*?)\]/.exec(text);
+ if (!block) return null;
+ const fields = [...block[1].matchAll(/name:\s*'(\w+)',\s*type:\s*'(\w+)',\s*offset:\s*(\d+)/g)]
+ .map((m) => ({ name: m[1], words: { vec3: 3, quat: 4, f32: 1 }[m[2]] ?? 1, word: Number(m[3]) / 4 }));
+ const out = fields.filter((f) => OUTPUT_FIELDS.includes(f.name));
+ if (out.length === 0) return null;
+ return new Set(out.flatMap((f) => Array.from({ length: f.words }, (_, i) => f.word + i)));
+}
+
const hits = [];
const bodies = new Map();
for (const rel of cpp) {
@@ -179,6 +214,49 @@ for (const seam of SEAMS) {
}
}
}
+// ── Who writes the composition's OUTPUT ──
+const outputWrites = [];
+for (const rel of cpp) {
+ if (OUTPUT_AUTHORS.has(rel)) continue;
+ const lines = readFileSync(path.join(ROOT, rel), 'utf8').split('\n');
+ lines.forEach((line, i) => {
+ if (COMMENT.test(line)) return;
+ const m = OUTPUT_WRITE.exec(line);
+ if (m) outputWrites.push({ file: rel, line: i + 1, field: m[1], code: line.trim().slice(0, 70) });
+ });
+}
+for (const w of outputWrites) {
+ errors.push(`${w.file}:${w.line} — writes ${w.field}, which only the composition may author`);
+}
+for (const [file] of OUTPUT_AUTHORS) {
+ const text = missing.some((m) => file.startsWith(m)) ? null : readFileSync(path.join(ROOT, file), 'utf8');
+ if (text && !OUTPUT_WRITE.test(text.split('\n').find((l) => OUTPUT_WRITE.test(l) && !COMMENT.test(l)) ?? '')) {
+ errors.push(`${file} — declared as an author of the composed output and writes none of it`);
+ }
+}
+
+// The TS producers reach the same fields by INDEX, through a resolved pointer:
+// `engF32[fi + 10] = x` is a worldPosition write that no search for the name
+// finds, and that is how the physics writeback stayed a second author.
+const outputWords = composedOutputWords();
+if (!outputWords) {
+ errors.push('the Transform pointer layout no longer says where the composed output lives');
+} else {
+ const INDEXED = /\[\s*(\w+)\s*\+\s*(\d+)\s*\]\s*=[^=]/g;
+ for (const rel of files.filter((f) => /^sdk\/src\/.*\.ts$/.test(f) && !f.includes('.generated.'))) {
+ const text = readFileSync(path.join(ROOT, rel), 'utf8');
+ if (!text.includes('getTransformPtr')) continue;
+ text.split('\n').forEach((line, i) => {
+ if (COMMENT.test(line)) return;
+ for (const m of line.matchAll(INDEXED)) {
+ if (outputWords.has(Number(m[2]))) {
+ errors.push(`${rel}:${i + 1} — writes word ${m[2]} of a Transform, which is composed output`);
+ }
+ }
+ });
+ }
+}
+
{
const text = readFileSync(path.join(ROOT, HIERARCHY_WRITER.file), 'utf8');
const i = text.split('\n').findIndex((l) => l.includes(`${HIERARCHY_WRITER.fn}(`) && l.includes('Registry&'));
@@ -204,6 +282,9 @@ say(` ${HIERARCHY_WRITER.fn.padEnd(w)} hierarchy announces`);
say(` ${' '.repeat(w)} ${HIERARCHY_WRITER.file}`);
say(` ${' '.repeat(w)} a reparent moves a subtree without touching one transform field`);
say('');
+say(' The composition\'s OUTPUT has one author:');
+for (const [file, why] of OUTPUT_AUTHORS) say(` ${file} — ${why}`);
+say('');
say(' From TypeScript, through a pointer setter that calls no C++:');
for (const [who, how] of TS_PRODUCERS) say(` ${who.padEnd(w)} ${how}`);
say('');
@@ -212,10 +293,11 @@ if (missing.length) say(` NOT scanned: ${missing.join(', ')}`);
say('');
if (errors.length) {
- console.error('Writers with no seam:\n');
+ console.error('Transform authorship is not what it says:\n');
for (const e of errors) console.error(` ${e}`);
- console.error('\nA new producer needs an entry in SEAMS saying how the composition learns of it.');
- console.error(`Either call ${SEAM_CALL}() once per pass, or compose the registry you wrote in place.`);
+ console.error('\nAn INPUT writer needs an entry in SEAMS saying how the composition learns of it:');
+ console.error(`call ${SEAM_CALL}() once per pass, or compose the registry you wrote in place.`);
+ console.error('The OUTPUT has one author. Write the local fields and let the composition run.');
if (GATE) process.exit(1);
} else if (GATE) {
console.log(`transform writers OK: ${hits.length} write site(s), every one under a declared seam.`);