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.

docs(sdk): mark physics Transform sync as the deliberate change-tracking boundary

yhhf9bf5740d415
diff --git a/sdk/src/physics/PhysicsSystem.ts b/sdk/src/physics/PhysicsSystem.ts
index 0f784cc07..856ef8a0a 100644
--- a/sdk/src/physics/PhysicsSystem.ts
+++ b/sdk/src/physics/PhysicsSystem.ts
@@ -401,6 +401,16 @@ export function applyPhysicsTransforms(
const engineMod = app.world.getWasmModule();
const hasParented = parentedBodies.size > 0;
+ // Change-tracking boundary (deliberate). Both write paths below sync Transform
+ // through a raw C++ / ptr fast path and do NOT record a Changed() tick — the one
+ // intentional exception to the unified write surface (Mut / set / insert / remove /
+ // Commands all record via world.*). Physics rewrites every dynamic body's transform
+ // every fixed step, so firing Changed(Transform) here would flood the changed-set
+ // with ~every moving body and make Changed(Transform) useless as a "gameplay wrote
+ // this" signal; the batched C++ path also can't record without an O(count) JS loop.
+ // To react to physics-driven motion, use the per-step moved set (snaps.cur), not
+ // Changed(Transform).
+
// Batched fast path: build [u32 entity, f32 x, y, angle] (meters) interpolated.
if (!hasParented && engineMod?.registry_batchSyncPhysicsTransforms) {
withMalloc(engineMod, count * PHYSICS_BODY_BYTES, engineBuf => {