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.

50.7 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    PhysicsSystem.ts
 * @brief   Per-frame physics driver: entity tracking, shape/joint create,
 *          step, transform readback, event collection.
 *
 * `registerPhysics2DSystem` owns all closure state (tracked bodies, joint
 * cache, cached RigidBody2D props). `Physics2DPlugin.build()` calls it once
 * the wasm module finishes loading.
 */

import type { App } from '../app/app';
import type { Entity } from '../types';
import type { TransformData, ParentData, CanvasData } from '../ecs/component';
import { Transform, Parent, Children, Disabled, Canvas } from '../ecs/component';
import { Res, Time, type TimeData } from '../ecs/resource';
import { Schedule, defineSystem } from '../ecs/system';
import { playModeOnly } from '../ecs/env';
import type { PhysicsWasmModule } from './PhysicsModuleLoader';
import { Physics2D } from './Physics2D';
import {
    RigidBody2D, BoxCollider2D, CircleCollider2D, CapsuleCollider2D,
    SegmentCollider2D, PolygonCollider2D, ChainCollider2D, OneWayPlatform2D,
    HingeJoint2D, DistanceJoint2D, SliderJoint2D, FixedJoint2D, WheelJoint2D, MotorJoint2D,
    BodyType, activeCollider,
    type RigidBody2DData, type BoxCollider2DData, type CircleCollider2DData,
    type CapsuleCollider2DData, type SegmentCollider2DData, type PolygonCollider2DData,
    type ChainCollider2DData, type OneWayPlatform2DData, type HingeJoint2DData,
    type DistanceJoint2DData, type SliderJoint2DData, type FixedJoint2DData, type WheelJoint2DData,
    type MotorJoint2DData,
} from './PhysicsComponents';
import { decomposePolygon2D } from './polygonDecompose2D';
import { MIN_CHAIN_POINTS } from './ColliderShape2D';
import {
    Physics2DEvents,
    COLLISION_EVENT_STRIDE,
    HIT_EVENT_STRIDE,
    quatToAngleZ,
    type ResolvedPhysics2DConfig,
    type CollisionEnterEvent,
    type CollisionHitEvent,
    type SensorEvent,
} from './PhysicsTypes';
import { withMalloc } from '../wasm/wasmScratch';
import { engineApi, type EngineApi } from '../ecs/bridge/engineApi';
import { StaticBodyPoses2D } from './StaticBodyPoses2D';
import { ComponentMutationReader } from '../ecs/ComponentMutationReader';
import { ENTITY_POSE_2D_WORDS } from '../wasm/constants.generated';

/**
 * The engine surface this file drives. `getTransformPtr` is the web module's own
 * (it hands back a pointer into wasm memory); a native host answers the batched
 * entry instead, which is the path every unparented body takes.
 */
type PhysicsEngineApi = EngineApi & {
    getTransformPtr?(registry: unknown, entity: number): number;
};

// =============================================================================
// Canvas pixelsPerUnit live read
// =============================================================================

/** The scene's live pixels-per-unit — the one reader of Canvas.pixelsPerUnit. @internal */
export function readPixelsPerUnit(app: App): number {
    const entities = app.world.getEntitiesWithComponents([Canvas]);
    for (const entity of entities) {
        const canvas = app.world.get(entity, Canvas) as CanvasData;
        if (canvas && canvas.pixelsPerUnit) {
            return canvas.pixelsPerUnit;
        }
    }
    return 100;
}

// =============================================================================
// Collision filter resolution
// =============================================================================

const MAX_COLLISION_LAYERS = 16;

/**
 * What a collider on `categoryBits` may touch: the project's layer table when it
 * names that layer, the collider's own mask otherwise. A table is saved at the
 * length a project has named, so reading past its end is a layer nobody set —
 * not a layer that touches nothing, which is what `undefined` reaches wasm as.
 */
function resolveCollisionMask(categoryBits: number, maskBits: number, layerMasks?: number[]): number {
    if (!layerMasks) return maskBits;
    for (let i = 0; i < MAX_COLLISION_LAYERS; i++) {
        if (categoryBits === (1 << i)) return layerMasks[i] ?? maskBits;
    }
    return maskBits;
}

// =============================================================================
// Shape attachment (one collider component per body)
// =============================================================================

/** Attach a Box2D shape for each enabled collider on the entity. @internal */
export function addShapeForEntity(
    world: App['world'], module: PhysicsWasmModule, entity: Entity, layerMasks?: number[],
): void {
    const box = activeCollider(world, entity, BoxCollider2D) as BoxCollider2DData | null;
    if (box) {
        const category = box.categoryBits ?? 0x0001;
        const mask = resolveCollisionMask(category, box.maskBits ?? 0xFFFF, layerMasks);
        module._physics_addBoxShape(
            entity, box.halfExtents.x, box.halfExtents.y,
            box.offset.x, box.offset.y, box.radius ?? 0.05,
            box.density, box.friction, box.restitution, box.isSensor ? 1 : 0,
            category, mask
        );
    }

    const circle = activeCollider(world, entity, CircleCollider2D) as CircleCollider2DData | null;
    if (circle) {
        const category = circle.categoryBits ?? 0x0001;
        const mask = resolveCollisionMask(category, circle.maskBits ?? 0xFFFF, layerMasks);
        module._physics_addCircleShape(
            entity, circle.radius,
            circle.offset.x, circle.offset.y,
            circle.density, circle.friction, circle.restitution, circle.isSensor ? 1 : 0,
            category, mask
        );
    }

    const capsule = activeCollider(world, entity, CapsuleCollider2D) as CapsuleCollider2DData | null;
    if (capsule) {
        const category = capsule.categoryBits ?? 0x0001;
        const mask = resolveCollisionMask(category, capsule.maskBits ?? 0xFFFF, layerMasks);
        module._physics_addCapsuleShape(
            entity, capsule.radius, capsule.halfHeight,
            capsule.offset.x, capsule.offset.y,
            capsule.density, capsule.friction, capsule.restitution, capsule.isSensor ? 1 : 0,
            category, mask
        );
    }

    const seg = activeCollider(world, entity, SegmentCollider2D) as SegmentCollider2DData | null;
    if (seg) {
        const category = seg.categoryBits ?? 0x0001;
        const mask = resolveCollisionMask(category, seg.maskBits ?? 0xFFFF, layerMasks);
        module._physics_addSegmentShape(
            entity, seg.point1.x, seg.point1.y, seg.point2.x, seg.point2.y,
            seg.density, seg.friction, seg.restitution, seg.isSensor ? 1 : 0,
            category, mask
        );
    }

    const poly = activeCollider(world, entity, PolygonCollider2D) as PolygonCollider2DData | null;
    if (poly) {
        const category = poly.categoryBits ?? 0x0001;
        const mask = resolveCollisionMask(category, poly.maskBits ?? 0xFFFF, layerMasks);
        // Box2D takes only convex polygons, and only eight vertices of one, so an
        // authored ring becomes as many shapes as it needs. They share the body,
        // and density sums over them the way it does over any two colliders.
        const { pieces } = decomposePolygon2D(poly.vertices);
        // A corner radius rounds the BOUNDARY, and a cut between two pieces is not
        // boundary: rounding each piece would bulge the shape outward along every
        // seam. Only an undivided polygon can carry it.
        const radius = pieces.length === 1 ? (poly.radius ?? 0) : 0;
        for (const piece of pieces) {
            const byteSize = piece.length * 2 * 4;
            withMalloc(module, byteSize, ptr => {
                const base = ptr >> 2;
                for (let i = 0; i < piece.length; i++) {
                    module.HEAPF32[base + i * 2] = piece[i].x;
                    module.HEAPF32[base + i * 2 + 1] = piece[i].y;
                }
                module._physics_addPolygonShape(
                    entity, ptr, piece.length, radius,
                    poly.density, poly.friction, poly.restitution, poly.isSensor ? 1 : 0,
                    category, mask
                );
            });
        }
    }

    const chain = activeCollider(world, entity, ChainCollider2D) as ChainCollider2DData | null;
    if (chain) {
        const pts = chain.points;
        if (pts.length < MIN_CHAIN_POINTS) return;
        const byteSize = pts.length * 2 * 4;
        withMalloc(module, byteSize, ptr => {
            const base = ptr >> 2;
            for (let i = 0; i < pts.length; i++) {
                module.HEAPF32[base + i * 2] = pts[i].x;
                module.HEAPF32[base + i * 2 + 1] = pts[i].y;
            }
            module._physics_addChainShape(
                entity, ptr, pts.length, chain.isLoop ? 1 : 0,
                chain.friction, chain.restitution,
                chain.categoryBits ?? 0x0001, chain.maskBits ?? 0xFFFF
            );
        });
    }
}

// =============================================================================
// Joint pending-list drain
// =============================================================================

function createPendingJoints(
    world: App['world'],
    module: PhysicsWasmModule,
    trackedEntities: Set<Entity>,
    trackedJoints: Map<Entity, string>,
    invPpu: number,
): void {
    const jointEntities = world.getEntitiesWithComponents([HingeJoint2D, RigidBody2D]);
    for (const entity of jointEntities) {
        if (trackedJoints.has(entity)) continue;
        if (!trackedEntities.has(entity)) continue;
        const joint = world.get(entity, HingeJoint2D) as HingeJoint2DData;
        if (!joint.enabled) continue;
        const connected = joint.connectedEntity as Entity;
        if (!trackedEntities.has(connected)) continue;
        module._physics_createRevoluteJoint(
            connected, entity,
            joint.anchorA.x * invPpu, joint.anchorA.y * invPpu,
            joint.anchorB.x * invPpu, joint.anchorB.y * invPpu,
            joint.enableMotor ? 1 : 0, joint.motorSpeed, joint.maxMotorTorque,
            joint.enableLimit ? 1 : 0, joint.lowerAngle, joint.upperAngle,
            joint.collideConnected ? 1 : 0,
        );
        if (module._physics_hasJoint(entity)) trackedJoints.set(entity, jointState(world, entity, invPpu)!);
    }

    for (const entity of world.getEntitiesWithComponents([DistanceJoint2D, RigidBody2D])) {
        if (trackedJoints.has(entity)) continue;
        if (!trackedEntities.has(entity)) continue;
        const j = world.get(entity, DistanceJoint2D) as DistanceJoint2DData;
        if (!j.enabled) continue;
        const connected = j.connectedEntity as Entity;
        if (!trackedEntities.has(connected)) continue;
        module._physics_createDistanceJoint(
            connected, entity,
            j.anchorA.x * invPpu, j.anchorA.y * invPpu,
            j.anchorB.x * invPpu, j.anchorB.y * invPpu,
            j.length * invPpu,
            j.enableSpring ? 1 : 0, j.hertz, j.dampingRatio,
            j.enableLimit ? 1 : 0, j.minLength * invPpu, j.maxLength * invPpu,
            j.enableMotor ? 1 : 0, j.maxMotorForce, j.motorSpeed,
            j.collideConnected ? 1 : 0,
        );
        if (module._physics_hasJoint(entity)) trackedJoints.set(entity, jointState(world, entity, invPpu)!);
    }

    for (const entity of world.getEntitiesWithComponents([SliderJoint2D, RigidBody2D])) {
        if (trackedJoints.has(entity)) continue;
        if (!trackedEntities.has(entity)) continue;
        const j = world.get(entity, SliderJoint2D) as SliderJoint2DData;
        if (!j.enabled) continue;
        const connected = j.connectedEntity as Entity;
        if (!trackedEntities.has(connected)) continue;
        module._physics_createPrismaticJoint(
            connected, entity,
            j.anchorA.x * invPpu, j.anchorA.y * invPpu,
            j.anchorB.x * invPpu, j.anchorB.y * invPpu,
            j.axis.x, j.axis.y,
            j.enableSpring ? 1 : 0, j.hertz, j.dampingRatio,
            j.enableLimit ? 1 : 0, j.lowerTranslation * invPpu, j.upperTranslation * invPpu,
            j.enableMotor ? 1 : 0, j.maxMotorForce, j.motorSpeed,
            j.collideConnected ? 1 : 0,
        );
        if (module._physics_hasJoint(entity)) trackedJoints.set(entity, jointState(world, entity, invPpu)!);
    }

    for (const entity of world.getEntitiesWithComponents([FixedJoint2D, RigidBody2D])) {
        if (trackedJoints.has(entity)) continue;
        if (!trackedEntities.has(entity)) continue;
        const j = world.get(entity, FixedJoint2D) as FixedJoint2DData;
        if (!j.enabled) continue;
        const connected = j.connectedEntity as Entity;
        if (!trackedEntities.has(connected)) continue;
        module._physics_createWeldJoint(
            connected, entity,
            j.anchorA.x * invPpu, j.anchorA.y * invPpu,
            j.anchorB.x * invPpu, j.anchorB.y * invPpu,
            j.linearHertz, j.angularHertz,
            j.linearDampingRatio, j.angularDampingRatio,
            j.collideConnected ? 1 : 0,
        );
        if (module._physics_hasJoint(entity)) trackedJoints.set(entity, jointState(world, entity, invPpu)!);
    }

    for (const entity of world.getEntitiesWithComponents([WheelJoint2D, RigidBody2D])) {
        if (trackedJoints.has(entity)) continue;
        if (!trackedEntities.has(entity)) continue;
        const j = world.get(entity, WheelJoint2D) as WheelJoint2DData;
        if (!j.enabled) continue;
        const connected = j.connectedEntity as Entity;
        if (!trackedEntities.has(connected)) continue;
        module._physics_createWheelJoint(
            connected, entity,
            j.anchorA.x * invPpu, j.anchorA.y * invPpu,
            j.anchorB.x * invPpu, j.anchorB.y * invPpu,
            j.axis.x, j.axis.y,
            j.enableSpring ? 1 : 0, j.hertz, j.dampingRatio,
            j.enableLimit ? 1 : 0, j.lowerTranslation * invPpu, j.upperTranslation * invPpu,
            j.enableMotor ? 1 : 0, j.maxMotorTorque, j.motorSpeed,
            j.collideConnected ? 1 : 0,
        );
        if (module._physics_hasJoint(entity)) trackedJoints.set(entity, jointState(world, entity, invPpu)!);
    }

    for (const entity of world.getEntitiesWithComponents([MotorJoint2D, RigidBody2D])) {
        if (trackedJoints.has(entity)) continue;
        if (!trackedEntities.has(entity)) continue;
        const j = world.get(entity, MotorJoint2D) as MotorJoint2DData;
        if (!j.enabled) continue;
        const connected = j.connectedEntity as Entity;
        if (!trackedEntities.has(connected)) continue;
        module._physics_createMotorJoint(
            connected, entity,
            j.linearVelocity.x * invPpu, j.linearVelocity.y * invPpu, j.maxVelocityForce,
            j.angularVelocity, j.maxVelocityTorque,
            j.linearHertz, j.linearDampingRatio, j.maxSpringForce,
            j.angularHertz, j.angularDampingRatio, j.maxSpringTorque,
            j.collideConnected ? 1 : 0,
        );
        if (module._physics_hasJoint(entity)) trackedJoints.set(entity, jointState(world, entity, invPpu)!);
    }
}

// =============================================================================
// One-way platform sync
// =============================================================================

// Re-applied every reconcile (idempotent): pushes each one-way platform's normal +
// enabled flag to the native pre-solve state and re-arms pre-solve events on shapes
// the collider reconcile may have just rebuilt. Entities that lost the component are
// cleared. `trackedOneWay` mirrors the native state so despawn can tear it down.
function syncOneWayPlatforms(
    world: App['world'],
    module: PhysicsWasmModule,
    trackedEntities: Set<Entity>,
    trackedOneWay: Set<Entity>,
    candidates?: Iterable<Entity>,
): void {
    const selected = candidates ?? new Set([...world.getEntitiesWithComponents([OneWayPlatform2D, RigidBody2D]), ...trackedOneWay]);
    for (const entity of selected) {
        if (!trackedEntities.has(entity) || !world.isEntityActive(entity) || !world.has(entity, OneWayPlatform2D)) {
            if (trackedOneWay.delete(entity)) module._physics_setOneWayPlatform(entity, 0, 0, 0);
            continue;
        }
        const ow = world.get(entity, OneWayPlatform2D) as OneWayPlatform2DData;
        if (ow.localSpace) {
            module._physics_setOneWayPlatformLocal(entity, ow.normal.x, ow.normal.y, ow.enabled ? 1 : 0);
        } else {
            module._physics_setOneWayPlatform(entity, ow.normal.x, ow.normal.y, ow.enabled ? 1 : 0);
        }
        trackedOneWay.add(entity);
    }
}

// =============================================================================
// Dynamic transform readback (wasm -> ECS Transform components)
// =============================================================================


const PHYSICS_BODY_STRIDE = ENTITY_POSE_2D_WORDS;
const PHYSICS_BODY_BYTES = PHYSICS_BODY_STRIDE * 4;

/**
 * Write interpolated body poses into ECS Transforms. The snapshot pair and the
 * lerp itself belong to the physics module (`physics_capturePoses` /
 * `physics_getInterpolatedTransforms`): they run over every dynamic body every
 * frame, and the no-JIT budget bars that loop from the JS path
 * (docs/REARCH_NATIVE.md §3.2). What is left here is routing the finished buffer
 * to the engine. With `alpha = 1` this reproduces a direct post-step sync.
 * @internal exported for testing
 */
export function applyPhysics2DTransforms(
    app: App,
    ppu: number,
    parentedBodies: Set<Entity>,
    module: PhysicsWasmModule,
    alpha: number,
): void {
    const count = module._physics_getInterpolatedCount();
    if (count === 0) return;

    const registry = app.world.getCppRegistry();
    if (!registry) return;
    // Through engineApi, not app.wasmModule: a device has no wasm module, so
    // reaching for one left the batched path web-only and every body on a native
    // host fell back to one addTransform call apiece (see ecs/engineApi.ts).
    const engineMod = engineApi(app) as PhysicsEngineApi | null;
    const hasParented = parentedBodies.size > 0;

    // Already lerped, in the module's memory: [u32 entity, f32 x, y, angle] (meters).
    const srcPtr = module._physics_getInterpolatedTransforms(alpha);

    // 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, read the module's per-step pose buffer, not
    // Changed(Transform).

    const batchSync = engineMod?.registry_batchSyncPhysicsTransforms;
    const engineHeap = engineMod?.HEAPU8;
    if (!hasParented && batchSync && engineHeap) {
        // A native host compiles the physics module into the engine's own binary, so
        // both address one heap and the module's buffer is already an engine pointer.
        if (engineHeap.buffer === module.HEAPU8.buffer) {
            batchSync.call(engineMod, registry, srcPtr, count, ppu);
            return;
        }
        // On the web a side module owns separate memory, so it is copied across —
        // one memcpy, not a per-body loop.
        if (engineMod?._malloc && engineMod._free) {
            const bytes = count * PHYSICS_BODY_BYTES;
            withMalloc(engineMod as Required<Pick<EngineApi, '_malloc' | '_free'>>, bytes, engineBuf => {
                engineHeap.set(module.HEAPU8.subarray(srcPtr, srcPtr + bytes), engineBuf);
                batchSync.call(engineMod, registry, engineBuf, count, ppu);
            });
            return;
        }
    }

    // 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)
        : null;
    // engF32 views the ENGINE heap, srcU32/srcF32 the PHYSICS heap. Caching them
    // across the loop is safe only because the loop allocates on neither: it
    // reads the transform buffer and reads/writes EXISTING Transform components.
    // ALLOW_MEMORY_GROWTH detaches a cached view on any allocation that grows
    // 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;

    // 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.
    const srcU32 = module.HEAPU32;
    const srcF32 = module.HEAPF32;
    const srcBase = srcPtr >> 2;

    for (let i = 0; i < count; i++) {
        const o = srcBase + i * PHYSICS_BODY_STRIDE;
        const entityId = srcU32[o] as Entity;
        let localX = srcF32[o + 1] * ppu;
        let localY = srcF32[o + 2] * ppu;
        let localAngle = srcF32[o + 3];

        if (hasParented && parentedBodies.has(entityId)) {
            const parentData = app.world.get(entityId, Parent) as ParentData;
            if (parentData && app.world.valid(parentData.entity) && app.world.has(parentData.entity, Transform)) {
                const pwt = app.world.get(parentData.entity, Transform) as TransformData;
                const parentAngleZ = quatToAngleZ(pwt.worldRotation);
                const dx = localX - pwt.worldPosition.x;
                const dy = localY - pwt.worldPosition.y;
                const cos = Math.cos(-parentAngleZ);
                const sin = Math.sin(-parentAngleZ);
                const sx = pwt.worldScale.x !== 0 ? pwt.worldScale.x : 1;
                const sy = pwt.worldScale.y !== 0 ? pwt.worldScale.y : 1;
                localX = (dx * cos - dy * sin) / sx;
                localY = (dx * sin + dy * cos) / sy;
                localAngle = localAngle - parentAngleZ;
            }
        }

        const half = localAngle * 0.5;
        const cosH = Math.cos(half);
        const sinH = Math.sin(half);

        if (getTransformPtr && engF32) {
            const tPtr = getTransformPtr(entityId);
            if (tPtr) {
                const fi = tPtr >> 2;
                // The engine's readers of changes (the renderer) see a body that moved, and only one that did; Changed()
                // queries stay out of it, as the note at the top of this function says. Compared as the f32s they will be.
                if (engF32[fi] !== Math.fround(localX) || engF32[fi + 1] !== Math.fround(localY)
                    || engF32[fi + 5] !== Math.fround(sinH) || engF32[fi + 6] !== Math.fround(cosH)) {
                    app.world.stampEngineWrite(entityId as Entity, Transform);
                }
                // 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;
                engF32[fi + 3]  = 0;
                engF32[fi + 4]  = 0;
                engF32[fi + 5]  = sinH;
                engF32[fi + 6]  = cosH;
                continue;
            }
        }

        // 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 ride
        // along as they stand rather than being authored here. Copied, because
        // editing what `get` answered is a write nothing observes.
        const current = app.world.get(entityId, Transform) as TransformData;
        addFn!(entityId, {
            ...current,
            position: { x: localX, y: localY, z: 0 },
            rotation: { w: cosH, x: 0, y: 0, z: sinH },
        });
    }
}

// =============================================================================
// Collision event drain
// =============================================================================

interface EventAccum {
    collisionEnters: CollisionEnterEvent[];
    collisionExits: Array<{ entityA: Entity; entityB: Entity }>;
    collisionHits: CollisionHitEvent[];
    sensorEnters: SensorEvent[];
    sensorExits: SensorEvent[];
}

/**
 * Drain this fixed step's events into the per-frame accumulator. Physics2DAPI may step
 * several times per rendered frame; accumulating (rather than overwriting) keeps
 * every collision — the interpolation system publishes + clears once per frame.
 */
function collectEvents(module: PhysicsWasmModule, ppu: number, accum: EventAccum): void {
    module._physics_collectEvents();

    const enterCount = module._physics_getCollisionEnterCount();
    if (enterCount > 0) {
        const enterPtr = module._physics_getCollisionEnterBuffer() >> 2;
        for (let i = 0; i < enterCount; i++) {
            const base = enterPtr + i * COLLISION_EVENT_STRIDE;
            accum.collisionEnters.push({
                entityA: module.HEAPU32[base] as Entity,
                entityB: module.HEAPU32[base + 1] as Entity,
                normalX: module.HEAPF32[base + 2],
                normalY: module.HEAPF32[base + 3],
                contactX: module.HEAPF32[base + 4] * ppu,
                contactY: module.HEAPF32[base + 5] * ppu,
            });
        }
    }

    const exitCount = module._physics_getCollisionExitCount();
    if (exitCount > 0) {
        const exitPtr = module._physics_getCollisionExitBuffer() >> 2;
        for (let i = 0; i < exitCount; i++) {
            const base = exitPtr + i * 2;
            accum.collisionExits.push({
                entityA: module.HEAPU32[base] as Entity,
                entityB: module.HEAPU32[base + 1] as Entity,
            });
        }
    }

    const hitCount = module._physics_getHitEventCount();
    if (hitCount > 0) {
        const hitPtr = module._physics_getHitEventBuffer() >> 2;
        for (let i = 0; i < hitCount; i++) {
            const base = hitPtr + i * HIT_EVENT_STRIDE;
            accum.collisionHits.push({
                entityA: module.HEAPU32[base] as Entity,
                entityB: module.HEAPU32[base + 1] as Entity,
                pointX: module.HEAPF32[base + 2] * ppu,
                pointY: module.HEAPF32[base + 3] * ppu,
                normalX: module.HEAPF32[base + 4],
                normalY: module.HEAPF32[base + 5],
                approachSpeed: module.HEAPF32[base + 6] * ppu,
            });
        }
    }

    const sensorEnterCount = module._physics_getSensorEnterCount();
    if (sensorEnterCount > 0) {
        const sensorEnterPtr = module._physics_getSensorEnterBuffer() >> 2;
        for (let i = 0; i < sensorEnterCount; i++) {
            const base = sensorEnterPtr + i * 2;
            accum.sensorEnters.push({
                sensorEntity: module.HEAPU32[base] as Entity,
                visitorEntity: module.HEAPU32[base + 1] as Entity,
            });
        }
    }

    const sensorExitCount = module._physics_getSensorExitCount();
    if (sensorExitCount > 0) {
        const sensorExitPtr = module._physics_getSensorExitBuffer() >> 2;
        for (let i = 0; i < sensorExitCount; i++) {
            const base = sensorExitPtr + i * 2;
            accum.sensorExits.push({
                sensorEntity: module.HEAPU32[base] as Entity,
                visitorEntity: module.HEAPU32[base + 1] as Entity,
            });
        }
    }
}

// =============================================================================
// System registration (ownership of tracked sets + per-frame loop)
// =============================================================================

interface CachedBodyProps {
    bodyType: number;
    gravityScale: number;
    linearDamping: number;
    angularDamping: number;
    fixedRotation: boolean;
    bullet: boolean;
    /** Last-applied RigidBody2D.enabled — drives in-place enable/disable. */
    enabled: boolean;
    /** Bitmask of present collider components — drives shape rebuild on change. */
    colliderSig: number;
    colliderState: string;
    /** Last sync of this body; inactive entities retain edits until reactivation. */
    syncedTick: number;
}

// The collider component types, in shape-add order. Their index is a stable bit
// in the per-entity collider signature (presence) — a change in the set, or any
// present collider's fields, triggers an in-place shape rebuild.
const COLLIDER_TYPES = [
    BoxCollider2D, CircleCollider2D, CapsuleCollider2D, SegmentCollider2D, PolygonCollider2D, ChainCollider2D,
] as const;

const JOINT_TYPES = [HingeJoint2D, DistanceJoint2D, SliderJoint2D, FixedJoint2D, WheelJoint2D, MotorJoint2D] as const;

function jointState(world: App['world'], entity: Entity, invPpu: number): string | null {
    for (let i = 0; i < JOINT_TYPES.length; ++i) {
        const component = JOINT_TYPES[i];
        if (world.has(entity, component)) return JSON.stringify([i, invPpu, world.get(entity, component)]);
    }
    return null;
}

/** Bitmask of which collider components an entity currently has. @internal */
export function colliderSignature(world: App['world'], entity: Entity): number {
    let sig = 0;
    for (let i = 0; i < COLLIDER_TYPES.length; i++) {
        if (world.has(entity, COLLIDER_TYPES[i])) sig |= 1 << i;
    }
    return sig;
}

function colliderState(world: App['world'], entity: Entity): string {
    return JSON.stringify(COLLIDER_TYPES.map(component => activeCollider(world, entity, component)));
}

/** True if any present collider component changed since `sinceTick`. @internal */
export function collidersChangedSince(world: App['world'], entity: Entity, sinceTick: number): boolean {
    for (const C of COLLIDER_TYPES) {
        if (world.has(entity, C) && world.isChangedSince(entity, C, sinceTick)) return true;
    }
    return false;
}

/**
 * For a tracked joint entity (invariant: ≤1 joint component): whether its joint
 * was removed, or its definition changed since `sinceTick` — either way the old
 * Box2D joint must be destroyed (createPendingJoints re-adds it if still present).
 * @internal
 */
export function jointChangedOrGone(world: App['world'], entity: Entity, sinceTick: number): boolean {
    for (const J of JOINT_TYPES) {
        if (world.has(entity, J)) return world.isChangedSince(entity, J, sinceTick);
    }
    return true; // no joint component left → gone
}

/**
 * For a tracked joint entity: whether its connected partner body is no longer
 * tracked (despawned, or its RigidBody2D removed). Box2D auto-destroys a joint
 * when either connected body dies, but the owner keeps its unchanged joint
 * component and stays in `trackedJoints` — so without re-establishing it here the
 * joint is silently dead forever, even after the partner respawns.
 * @internal
 */
export function jointPartnerGone(world: App['world'], entity: Entity, trackedEntities: Set<Entity>): boolean {
    for (const J of JOINT_TYPES) {
        if (world.has(entity, J)) {
            const connected = (world.get(entity, J) as { connectedEntity: number }).connectedEntity as Entity;
            return !trackedEntities.has(connected);
        }
    }
    return false;
}

/**
 * Wire the per-frame physics system into the app. Owns tracked-entity
 * / tracked-joint / parented sets via the enclosing closure so the
 * plugin doesn't need to thread them through.
 */
export function registerPhysics2DSystem(
    app: App,
    module: PhysicsWasmModule,
    config: ResolvedPhysics2DConfig,
): () => void {
    const trackedEntities = new Set<Entity>();
    const trackedJoints = new Map<Entity, string>();
    const trackedOneWay = new Set<Entity>();
    const parentedBodies = new Set<Entity>();
    const cachedProps = new Map<Entity, CachedBodyProps>();
    // Equal authored shapes share one snapshot; unchanged full refreshes retain contacts.
    const colliderStates = new Map<string, { value: string; references: number }>();
    const retainState = (value: string): string => {
        let state = colliderStates.get(value);
        if (!state) { state = { value, references: 0 }; colliderStates.set(value, state); }
        state.references++;
        return state.value;
    };
    const releaseState = (value: string) => {
        const state = colliderStates.get(value);
        if (state && --state.references === 0) colliderStates.delete(value);
    };
    let lastEntitySyncTick = -1;
    let lastJointInvPpu = NaN;
    let lastJointWriteRevisions: number[] = [];
    // Events accumulated across this frame's fixed steps; published once per frame.
    const events: EventAccum = {
        collisionEnters: [], collisionExits: [], collisionHits: [], sensorEnters: [], sensorExits: [],
    };
    const fixedDt = config.fixedTimestep;

    // Mutation cursors select authoring edits. Change stamps gate full scans on
    // older hosts. Kinematic targets remain driven every fixed step.
    const physicsComponents = [RigidBody2D, ...COLLIDER_TYPES, ...JOINT_TYPES, OneWayPlatform2D];
    for (const c of physicsComponents) app.world.enableChangeTracking(c);
    const kinematicEntities = new Set<Entity>();
    const staticPoses = new StaticBodyPoses2D(app.world);
    let lastStructuralVersion = -1;

    const world = app.world;
    world.enableChangeTracking(Transform);
    const mutations = new ComponentMutationReader(world, physicsComponents, [Transform, Children], [Parent, Disabled]);

    const destroyBody = (entity: Entity) => {
        if (!trackedEntities.delete(entity)) return;
        module._physics_destroyBody(entity);
        releaseState(cachedProps.get(entity)!.colliderState);
        cachedProps.delete(entity); parentedBodies.delete(entity); kinematicEntities.delete(entity); staticPoses.delete(entity);
    };

    const offDespawn = world.onDespawn((entity: Entity) => {
        if (trackedJoints.has(entity)) {
            module._physics_destroyJoint(entity);
            trackedJoints.delete(entity);
        }
        if (trackedOneWay.has(entity)) {
            module._physics_setOneWayPlatform(entity, 0, 0, 0);
            trackedOneWay.delete(entity);
        }
        if (trackedEntities.has(entity)) {
            destroyBody(entity);
            // The module's pose snapshots need no cleanup: destroying the body drops
            // it from the dynamic set the next capture rebuilds from, and the lerp is
            // driven by the current snapshot, so a stale `prev` entry is never read.
        }
    });

    // ── Step + capture (fixed cadence) ──────────────────────────────────────
    // Runs in FixedUpdate (fixed dt, framerate-independent → deterministic step
    // count). Reconciles bodies, steps Box2D once, drains events, snapshots poses.
    app.addSystemToSchedule(
        Schedule.FixedUpdate,
        defineSystem(
            [],
            () => {
                // Liveness is now auto-reported by the scheduler (this system is tagged
                // 'physics' and gated by playModeOnly, so it only beats while stepping).
                // Read pixelsPerUnit live each tick so a Canvas property
                // change at runtime (editor: user edits Canvas.pixelsPerUnit)
                // propagates to physics transforms instead of staying at the
                // value captured when the wasm module first loaded.
                const ppu = readPixelsPerUnit(app);
                const invPpu = 1 / ppu;
                const jointScaleChanged = invPpu !== lastJointInvPpu;
                // 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(Physics2D)) app.getResource(Physics2D).setPixelsPerUnit(ppu);
                // Native and SDK mutations share the sparse path; structural and
                // component stamps retain the full-scan fallback for older hosts.
                const structuralVersion = world.getWorldVersion();
                const mutationBatch = mutations.read();
                const jointWriteRevisions = mutationBatch ? null
                    : JOINT_TYPES.map(component => world.mutationRevision(component, 'write'));
                const jointWritesChanged = !!jointWriteRevisions
                    && jointWriteRevisions.some((revision, i) => revision !== lastJointWriteRevisions[i]);
                let needReconcile = structuralVersion !== lastStructuralVersion;
                if (mutationBatch) needReconcile = mutationBatch.full || mutationBatch.entities.size > 0;
                else if (!needReconcile) {
                    for (let i = 0; i < physicsComponents.length; i++) {
                        if (world.anyChangedSince(physicsComponents[i], lastEntitySyncTick)) {
                            needReconcile = true;
                            break;
                        }
                    }
                }
                needReconcile ||= jointScaleChanged || jointWritesChanged;
                if (mutationBatch) {
                    for (const entity of mutationBatch.changed.get(Transform) ?? []) staticPoses.invalidate(entity);
                    if (mutationBatch.reset) {
                        for (const entity of trackedJoints.keys()) module._physics_destroyJoint(entity);
                        trackedJoints.clear();
                        for (const entity of trackedOneWay) module._physics_setOneWayPlatform(entity, 0, 0, 0);
                        trackedOneWay.clear();
                        for (const entity of trackedEntities) destroyBody(entity);
                    }
                }
                if (needReconcile) {
                world.ensureTransformsComposed();
                const entities = mutationBatch?.entities ?? world.getEntitiesWithComponents([RigidBody2D, Transform]);
                const currentEntities = new Set<Entity>();

                // ── Unified body + collider reconcile ───────────────────────
                // Each entity's Box2D body is a reconciled projection of its
                // components: create on first enable, then bring the body in line
                // (enable/disable, props, shapes) with minimal in-place ops that
                // preserve simulation state — never destroy-and-rebuild.
                for (const entity of entities) {
                    if (mutationBatch && (!world.valid(entity) || !world.has(entity, RigidBody2D)
                        || !world.has(entity, Transform) || !world.isEntityActive(entity))) continue;
                    currentEntities.add(entity);
                    const rb = world.get(entity, RigidBody2D) as RigidBody2DData;

                    if (!trackedEntities.has(entity)) {
                        if (!rb.enabled) continue; // lazy-create on first enable
                        const wt = world.get(entity, Transform) as TransformData;
                        const hasParent = world.has(entity, Parent);
                        const posX = hasParent ? wt.worldPosition.x : wt.position.x;
                        const posY = hasParent ? wt.worldPosition.y : wt.position.y;
                        const rot = hasParent ? wt.worldRotation : wt.rotation;

                        module._physics_createBody(
                            entity, rb.bodyType,
                            posX * invPpu, posY * invPpu, quatToAngleZ(rot),
                            rb.gravityScale, rb.linearDamping, rb.angularDamping,
                            rb.fixedRotation ? 1 : 0, rb.bullet ? 1 : 0,
                        );
                        addShapeForEntity(world, module, entity, config.collisionLayerMasks);
                        trackedEntities.add(entity);
                        if (hasParent && rb.bodyType !== BodyType.Static) parentedBodies.add(entity);
                        cachedProps.set(entity, {
                            bodyType: rb.bodyType,
                            gravityScale: rb.gravityScale,
                            linearDamping: rb.linearDamping,
                            angularDamping: rb.angularDamping,
                            fixedRotation: rb.fixedRotation,
                            bullet: rb.bullet,
                            enabled: true,
                            colliderSig: colliderSignature(world, entity),
                            colliderState: retainState(colliderState(world, entity)),
                            syncedTick: world.getWorldTick(),
                        });
                        if (rb.bodyType === BodyType.Kinematic) kinematicEntities.add(entity);
                        if (rb.bodyType === BodyType.Static) {
                            staticPoses.set(entity, { x: posX * invPpu, y: posY * invPpu,
                                angle: quatToAngleZ(rot), parent: hasParent ? world.get(entity, Parent).entity : null });
                        }
                        continue;
                    }

                    const cached = cachedProps.get(entity)!;
                    const reenabled = rb.enabled && !cached.enabled;

                    // 1. enabled toggle — in place (keeps shapes/velocity/joints).
                    if (rb.enabled !== cached.enabled) {
                        module._physics_setBodyEnabled(entity, rb.enabled ? 1 : 0);
                        cached.enabled = rb.enabled;
                        if (rb.enabled) staticPoses.invalidate(entity);
                    }

                    // 2. body properties.
                    if (cached.bodyType !== rb.bodyType ||
                         cached.gravityScale !== rb.gravityScale ||
                         cached.linearDamping !== rb.linearDamping ||
                         cached.angularDamping !== rb.angularDamping ||
                         cached.fixedRotation !== rb.fixedRotation ||
                         cached.bullet !== rb.bullet) {
                        module._physics_updateBodyProperties(
                            entity, rb.bodyType,
                            rb.gravityScale, rb.linearDamping, rb.angularDamping,
                            rb.fixedRotation ? 1 : 0, rb.bullet ? 1 : 0,
                        );
                        cached.bodyType = rb.bodyType;
                        cached.gravityScale = rb.gravityScale;
                        cached.linearDamping = rb.linearDamping;
                        cached.angularDamping = rb.angularDamping;
                        cached.fixedRotation = rb.fixedRotation;
                        cached.bullet = rb.bullet;
                    }

                    // 3. colliders — rebuild shapes in place when the collider set
                    //    or any collider's fields change (body + velocity preserved).
                    const sig = colliderSignature(world, entity);
                    if (sig !== cached.colliderSig ||
                        (mutationBatch ? reenabled || mutationBatch.full || COLLIDER_TYPES.some(component => mutationBatch.changed.get(component)?.has(entity))
                            : collidersChangedSince(world, entity, cached.syncedTick))) {
                        const state = colliderState(world, entity);
                        if (state !== cached.colliderState) {
                            module._physics_clearShapes(entity);
                            addShapeForEntity(world, module, entity, config.collisionLayerMasks);
                            releaseState(cached.colliderState);
                            cached.colliderState = retainState(state);
                        }
                        cached.colliderSig = sig;
                    }

                    // 4. kinematic bodies: maintain the set; the Transform→body push
                    //    runs every step outside the (gated) reconcile so it survives
                    //    skipped frames.
                    if (cached.bodyType === BodyType.Kinematic) kinematicEntities.add(entity);
                    else kinematicEntities.delete(entity);
                    if (cached.bodyType === BodyType.Static) {
                        const parent = world.has(entity, Parent) ? world.get(entity, Parent).entity : null;
                        staticPoses.track(entity, parent);
                        parentedBodies.delete(entity);
                    } else {
                        staticPoses.delete(entity);
                        if (world.has(entity, Parent)) parentedBodies.add(entity); else parentedBodies.delete(entity);
                    }
                    cached.syncedTick = world.getWorldTick();
                }

                // Activity filtering removes descendants from the query too.
                // Freeze those bodies in place so reactivation keeps velocity,
                // shapes and joints; only component removal destroys the body.
                for (const entity of mutationBatch?.entities ?? trackedEntities) {
                    if (!trackedEntities.has(entity)) continue;
                    if (!currentEntities.has(entity)) {
                        if (world.has(entity, RigidBody2D) && world.has(entity, Transform)) {
                            const cached = cachedProps.get(entity)!;
                            if (cached.enabled) {
                                module._physics_setBodyEnabled(entity, 0);
                                cached.enabled = false;
                            }
                            continue;
                        }
                        destroyBody(entity);
                    }
                }

                // ── Joint reconcile ─────────────────────────────────────────
                // Definition snapshots preserve solver state across full refreshes
                // and identical writes. Missing solver joints must be recreated.
                for (const [entity, state] of trackedJoints) {
                    const changed = jointScaleChanged || (mutationBatch ? mutationBatch.full
                        || JOINT_TYPES.some(component => mutationBatch.changed.get(component)?.has(entity))
                        : jointWritesChanged || jointChangedOrGone(world, entity, lastEntitySyncTick));
                    if (!trackedEntities.has(entity) || !module._physics_hasJoint(entity)
                        || (changed && jointState(world, entity, invPpu) !== state)
                        || jointPartnerGone(world, entity, trackedEntities)) {
                        module._physics_destroyJoint(entity);
                        trackedJoints.delete(entity);
                    }
                }
                createPendingJoints(world, module, trackedEntities, trackedJoints, invPpu);
                syncOneWayPlatforms(world, module, trackedEntities, trackedOneWay, mutationBatch?.entities);

                lastEntitySyncTick = world.getWorldTick();
                lastJointInvPpu = invPpu;
                if (jointWriteRevisions) lastJointWriteRevisions = jointWriteRevisions;
                lastStructuralVersion = structuralVersion;
                } // end if (needReconcile)

                staticPoses.sync(module, ppu, mutationBatch ? mutationBatch.full || mutationBatch.refreshPoses : needReconcile,
                    entity => !!cachedProps.get(entity)?.enabled);

                // Kinematic bodies are driven by their Transform (changed via gameplay,
                // not tracked as a physics edit) — push every step, even when the
                // reconcile above was skipped. Drive them toward the target over the
                // fixed step so Box2D derives their velocity from the delta: that
                // velocity is what carries/pushes resting dynamic bodies (a plain
                // teleport reports zero velocity, so platforms wouldn't move riders).
                if (kinematicEntities.size) world.ensureTransformsComposed();
                for (const entity of kinematicEntities) {
                    if (!cachedProps.get(entity)?.enabled) continue;
                    const wt = world.get(entity, Transform) as TransformData;
                    module._physics_setBodyTargetTransform(
                        entity,
                        wt.worldPosition.x * invPpu, wt.worldPosition.y * invPpu,
                        quatToAngleZ(wt.worldRotation),
                        fixedDt,
                    );
                }

                if (trackedEntities.size > 0) {
                    module._physics_step(fixedDt);
                }

                collectEvents(module, ppu, events);
                module._physics_capturePoses();

                // Acknowledge the sampled boundaries; later same-frame writes remain pending.
                if (mutationBatch) mutations.commit(mutationBatch);
            },
            { name: 'PhysicsStepSystem' }
        ),
        { runIf: playModeOnly, profileDomain: 'physics' }
    );

    // ── Interpolate + publish (render cadence) ──────────────────────────────
    // Runs once per rendered frame in PostUpdate: publishes the frame's events,
    // then writes interpolated (prev→cur by Time.fixedAlpha) poses to Transforms.
    app.addSystemToSchedule(
        Schedule.PostUpdate,
        defineSystem(
            [Res(Time)],
            (time: TimeData) => {
                app.insertResource(Physics2DEvents, {
                    collisionEnters: events.collisionEnters,
                    collisionExits: events.collisionExits,
                    collisionHits: events.collisionHits,
                    sensorEnters: events.sensorEnters,
                    sensorExits: events.sensorExits,
                });
                // Fresh arrays for next frame; the published ones stay live on the resource.
                events.collisionEnters = [];
                events.collisionExits = [];
                events.collisionHits = [];
                events.sensorEnters = [];
                events.sensorExits = [];

                const ppu = readPixelsPerUnit(app);
                applyPhysics2DTransforms(app, ppu, parentedBodies, module, time.fixedAlpha);
            },
            { name: 'PhysicsInterpolateSystem' }
        ),
        { runIf: playModeOnly, profileDomain: 'physics' }
    );
    const offFrameEnd = app.onFrameEnd(() => {
        if (app.isPaused() || !playModeOnly() || app.getResource(Time).scale <= 0) {
            staticPoses.pause(); mutations.pause();
        }
    });
    return () => {
        offFrameEnd(); offDespawn(); staticPoses.dispose(); mutations.dispose();
        colliderStates.clear(); cachedProps.clear(); trackedJoints.clear();
    };
}