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(physics): physics produces transform inputs, and stops authoring the output
esenginee48515d5df80
diff --git a/bench/replication-interest/README.md b/bench/replication-interest/README.mdindex 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 staytiny 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 returnsomething 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.mdindex 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; theshipped `ensureComposed` path collects nothing and pays one predictable branchper entity, which the A column is what says is affordable.diff --git a/sdk/src/physics/PhysicsSystem.ts b/sdk/src/physics/PhysicsSystem.tsindex 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.tsnew file mode 100644index 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.cppindex 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 bufftransform.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.mjsindex 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.`);