@downdraft/engine 0.1.1 → 0.2.0

package/dist/libraries/physics-rapier/src/bulk-ops.js

@@ -0,0 +1,46 @@
+/**
+ * Bulk transform reader/writer for efficient FFI/WASM boundary crossing.
+ *
+ * Reads/writes pos+rot for all bodies in a realm in a single pass over
+ * the raw body set, avoiding per-entity object creation.
+ *
+ * The transform buffer layout is `entityCount × 8` floats:
+ *   [pos.x, pos.y, pos.z, rot.x, rot.y, rot.z, rot.w, pad]
+ */
+/**
+ * Read all body transforms from a realm into a Float32Array in one pass.
+ * Delegates to `PhysicsBackend.readTransforms` (one FFI call per realm).
+ */
+export function bulkReadTransforms(backend, realmId, buffer, entityCount) {
+    backend.readTransforms(realmId, buffer, entityCount);
+}
+/**
+ * Write transforms from a Float32Array into all bodies in a realm in one pass.
+ * Delegates to `PhysicsBackend.syncTransforms` (one FFI call per realm).
+ */
+export function bulkWriteTransforms(backend, realmId, buffer, entityCount) {
+    backend.syncTransforms(realmId, buffer, entityCount);
+}
+/**
+ * Bulk read transforms for multiple realms into a shared buffer.
+ * Each realm gets a contiguous slice of the buffer.
+ *
+ * Returns an array of { realmId, offset, count } for each realm read.
+ */
+export function bulkReadMultiRealm(backend, realmIds, buffer, maxEntitiesPerRealm) {
+    const results = [];
+    let offset = 0;
+    realmIds.forEach((realmId) => {
+        const slice = buffer.subarray(offset, offset + maxEntitiesPerRealm * 8);
+        // readTransforms writes into the buffer at the slice's offset;
+        // but since it writes by entity index, we need a separate buffer per realm
+        // or the backend must support offset-based writes.
+        // For now, use a per-realm temp buffer and copy.
+        const tempBuf = new Float32Array(maxEntitiesPerRealm * 8);
+        backend.readTransforms(realmId, tempBuf, maxEntitiesPerRealm);
+        buffer.set(tempBuf, offset);
+        results.push({ realmId, offset, count: maxEntitiesPerRealm });
+        offset += maxEntitiesPerRealm * 8;
+    });
+    return results;
+}

package/dist/libraries/physics-rapier/src/ffi-backend.js

@@ -0,0 +1,17 @@
+// ============================================================================
+// ffi-backend.ts — RapierFfiBackend: RapierPhysicsBackend driven by the
+// native Rapier cdylib (bun:ffi) instead of the WASM bundle.
+//
+// All JS-side bookkeeping (BodyState, contacts caching, PhysicsBody handles)
+// is inherited unchanged — only the PhysicsLib transport differs.
+// ============================================================================
+import { RapierPhysicsBackend } from "./backend.js";
+import { loadFfiPhysicsLib } from "./ffi-lib.js";
+export { loadFfiPhysicsLib };
+export class RapierFfiBackend extends RapierPhysicsBackend {
+    name = "rapier-ffi";
+    version = "0.1.0";
+    constructor() {
+        super(loadFfiPhysicsLib);
+    }
+}

package/dist/libraries/physics-rapier/src/ffi-lib.js

@@ -0,0 +1,605 @@
+// ============================================================================
+// ffi-lib.ts — PhysicsLib implementation backed by the native Rapier cdylib
+// (packages/engine/libraries/physics-native/native) via the cross-runtime
+// FFI adapter (bun:ffi / koffi / Deno.dlopen).
+//
+// Replaces the WASM @dimforge/rapier3d-compat path on the native runtime.
+// Same PhysicsLib contract as rapier-backend.ts — RapierPhysicsBackend keeps
+// all JS-side bookkeeping (BodyState cache, contacts extraction) unchanged.
+//
+// Semantic parity notes vs the WASM lib:
+//  - Entity resolution is done JS-side: native code returns game bodyIds,
+//    we map them back to Entity via a per-realm map populated in createBody.
+//  - Contact points are WORLD-space (Rapier SolverContact), whereas the WASM
+//    path returns manifold.localContactPoint1 (collider1-local). Callers that
+//    render contact markers should treat these as world positions.
+//  - raycast() returns the real surface normal (WASM hardcodes [0,1,0]).
+//  - serializeRealm/deserializeRealm are stubs — the cdylib builds without
+//    Rapier's serde feature. Snapshots need a serde-enabled build.
+// ============================================================================
+import { dlopen, ptr, resolveNativeLibrary } from "@downdraft/platform-native";
+import { findPackageRoot } from "@downdraft/engine/platform/pkg-root";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const _dirname = typeof globalThis.__dirname !== "undefined"
+    ? globalThis.__dirname
+    : dirname(fileURLToPath(import.meta.url));
+function findPhysicsLibrary() {
+    return resolveNativeLibrary("downdraft_physics", {
+        envVars: ["DOWNDRAFT_PHYSICS_LIB", "PHYSICS_NATIVE_PATH"],
+        crateDir: join(findPackageRoot(_dirname), "libraries", "physics-native", "native"),
+        buildHint: 'run "bun run build:native" from the repo root',
+    });
+}
+// ── FFI symbol table ──
+const PHYSICS_SPEC = {
+    dd_create_realm: { args: ["i32", "f32", "f32", "f32"], returns: "i32" },
+    dd_destroy_realm: { args: ["i32"], returns: "i32" },
+    dd_create_body: { args: ["i32", "i32", "ptr", "ptr"], returns: "i32" },
+    dd_destroy_body: { args: ["i32", "i32"], returns: "i32" },
+    dd_set_body_type: { args: ["i32", "i32", "i32"], returns: "i32" },
+    dd_set_translation: { args: ["i32", "i32", "f32", "f32", "f32", "i32"], returns: "i32" },
+    dd_set_rotation: { args: ["i32", "i32", "f32", "f32", "f32", "f32", "i32"], returns: "i32" },
+    dd_get_translation: { args: ["i32", "i32", "ptr"], returns: "i32" },
+    dd_get_rotation: { args: ["i32", "i32", "ptr"], returns: "i32" },
+    dd_set_linvel: { args: ["i32", "i32", "f32", "f32", "f32", "i32"], returns: "i32" },
+    dd_set_angvel: { args: ["i32", "i32", "f32", "f32", "f32", "i32"], returns: "i32" },
+    dd_get_linvel: { args: ["i32", "i32", "ptr"], returns: "i32" },
+    dd_get_angvel: { args: ["i32", "i32", "ptr"], returns: "i32" },
+    dd_get_body_transform: { args: ["i32", "i32", "ptr"], returns: "i32" },
+    dd_is_sleeping: { args: ["i32", "i32"], returns: "i32" },
+    dd_wake_up: { args: ["i32", "i32"], returns: "i32" },
+    dd_set_ccd: { args: ["i32", "i32", "i32"], returns: "i32" },
+    dd_apply_force: { args: ["i32", "i32", "f32", "f32", "f32"], returns: "i32" },
+    dd_apply_torque: { args: ["i32", "i32", "f32", "f32", "f32"], returns: "i32" },
+    dd_apply_impulse: { args: ["i32", "i32", "f32", "f32", "f32"], returns: "i32" },
+    dd_apply_torque_impulse: { args: ["i32", "i32", "f32", "f32", "f32"], returns: "i32" },
+    dd_apply_impulse_at_point: { args: ["i32", "i32", "f32", "f32", "f32", "f32", "f32", "f32"], returns: "i32" },
+    dd_apply_body_writes: { args: ["i32", "ptr", "ptr", "usize", "i32"], returns: "i32" },
+    dd_apply_impulses: { args: ["i32", "ptr", "ptr", "usize"], returns: "i32" },
+    dd_add_collider: { args: ["i32", "i32", "i32", "ptr", "ptr", "ptr", "ptr"], returns: "i32" },
+    dd_remove_collider: { args: ["i32", "i32"], returns: "i32" },
+    dd_swap_collider_shape: { args: ["i32", "i32", "ptr", "usize", "ptr", "usize"], returns: "i32" },
+    dd_set_collider_position: { args: ["i32", "i32", "f32", "f32", "f32"], returns: "i32" },
+    dd_get_collider_position: { args: ["i32", "i32", "ptr"], returns: "i32" },
+    dd_collider_shape_type: { args: ["i32", "i32"], returns: "i32" },
+    dd_collider_count: { args: ["i32", "i32"], returns: "i32" },
+    dd_test_convex_hull: { args: ["ptr", "usize"], returns: "i32" },
+    dd_step: { args: ["i32", "f32"], returns: "i32" },
+    dd_set_integration_dt: { args: ["i32", "f32"], returns: "i32" },
+    dd_set_solver_iterations: { args: ["i32", "i32"], returns: "i32" },
+    dd_set_min_island_size: { args: ["i32", "i32"], returns: "i32" },
+    dd_step_and_read_awake: { args: ["i32", "f32", "ptr", "ptr", "usize"], returns: "i32" },
+    dd_read_awake: { args: ["i32", "ptr", "ptr", "usize"], returns: "i32" },
+    dd_raycast: { args: ["i32", "f32", "f32", "f32", "f32", "f32", "f32", "f32", "u32", "i32", "ptr"], returns: "i32" },
+    dd_shape_cast: { args: ["i32", "i32", "ptr", "f32", "u32", "i32", "ptr"], returns: "i32" },
+    dd_get_contacts: { args: ["i32", "ptr", "ptr", "ptr", "usize"], returns: "i32" },
+    dd_get_intersections: { args: ["i32", "ptr", "usize"], returns: "i32" },
+    dd_char_create: { args: ["i32", "i32", "ptr", "ptr"], returns: "i32" },
+    dd_char_destroy: { args: ["i32", "i32"], returns: "i32" },
+    dd_char_set_collider_pos: { args: ["i32", "i32", "f32", "f32", "f32"], returns: "i32" },
+    dd_char_move: { args: ["i32", "i32", "f32", "f32", "f32", "f32", "ptr", "ptr", "usize"], returns: "i32" },
+    dd_create_joint: { args: ["i32", "i32", "i32", "i32", "i32", "ptr"], returns: "i32" },
+    dd_destroy_joint: { args: ["i32", "i32"], returns: "i32" },
+    dd_destroy: { args: [], returns: "i32" },
+};
+// ── Descriptor packing (layouts must match native/src/*.rs) ──
+const BODY_F32_LEN = 17;
+const BODY_I32_LEN = 2;
+const COLLIDER_I32_LEN = 9;
+const COLLIDER_F32_LEN = 14;
+const CHAR_F32_LEN = 11;
+const CHAR_I32_LEN = 6;
+const JOINT_F32_LEN = 19;
+const BODY_TYPE = { static: 0, kinematic: 1, dynamic: 2 };
+const SHAPE_TYPE = { sphere: 0, box: 1, capsule: 2, convex: 3, mesh: 4, heightfield: 5 };
+const JOINT_TYPE = { fixed: 0, "cone-twist": 1, revolute: 2, prismatic: 3 };
+let cachedLib = null;
+export function loadFfiPhysicsLib() {
+    if (cachedLib)
+        return Promise.resolve(cachedLib);
+    cachedLib = buildLib();
+    return Promise.resolve(cachedLib);
+}
+function buildLib() {
+    const lib = dlopen(findPhysicsLibrary(), PHYSICS_SPEC);
+    const s = lib.symbols;
+    // Per-realm game-bodyId → Entity (native returns bodyIds; entities never
+    // cross the FFI boundary).
+    const entityByBodyId = new Map();
+    // Reverse: entity.index → bodyId (O(1) excludeEntity lookup in queries).
+    const bodyIdByEntityIndex = new Map();
+    // Scratch descriptor buffers — reused across calls (FFI calls are
+    // synchronous; no reentrancy hazard).
+    const bodyF = new Float32Array(BODY_F32_LEN);
+    const bodyI = new Int32Array(BODY_I32_LEN);
+    const collMeta = new Int32Array(COLLIDER_I32_LEN);
+    const collF = new Float32Array(COLLIDER_F32_LEN);
+    const charF = new Float32Array(CHAR_F32_LEN);
+    const charI = new Int32Array(CHAR_I32_LEN);
+    const jointF = new Float32Array(JOINT_F32_LEN);
+    const out3 = new Float32Array(3);
+    const out4 = new Float32Array(4);
+    const out7 = new Float32Array(7);
+    const rayOut = new Float32Array(8);
+    const charOutF = new Float32Array(5);
+    const charOutI = new Int32Array(17); // groundBodyId + up to 16 collision bodyIds
+    // Contacts/intersections extraction buffers — grow on demand.
+    let contactsI = new Int32Array(4096 * 3);
+    let contactsF = new Float32Array(4096 * 4);
+    let contactsPts = new Float32Array(4096 * 12);
+    let intersectI = new Int32Array(2048 * 2);
+    function entities(realmId) {
+        let m = entityByBodyId.get(realmId);
+        if (!m) {
+            m = new Map();
+            entityByBodyId.set(realmId, m);
+        }
+        return m;
+    }
+    function entityFor(realmId, bodyId) {
+        return entityByBodyId.get(realmId)?.get(bodyId) ?? { index: 0, generation: 0 };
+    }
+    function excludeBodyId(realmId, entity) {
+        if (!entity)
+            return -1;
+        return bodyIdByEntityIndex.get(realmId)?.get(entity.index) ?? -1;
+    }
+    const ffiLib = {
+        createRealm(id, gravity) {
+            s.dd_create_realm(id, gravity[0], gravity[1], gravity[2]);
+            entityByBodyId.set(id, new Map());
+            bodyIdByEntityIndex.set(id, new Map());
+        },
+        destroyRealm(id) {
+            s.dd_destroy_realm(id);
+            entityByBodyId.delete(id);
+            bodyIdByEntityIndex.delete(id);
+        },
+        createBody(realmId, bodyId, desc, entity) {
+            bodyF[0] = desc.position[0];
+            bodyF[1] = desc.position[1];
+            bodyF[2] = desc.position[2];
+            bodyF[3] = desc.rotation[0];
+            bodyF[4] = desc.rotation[1];
+            bodyF[5] = desc.rotation[2];
+            bodyF[6] = desc.rotation[3];
+            const lv = desc.linearVelocity ?? [0, 0, 0];
+            const av = desc.angularVelocity ?? [0, 0, 0];
+            bodyF[7] = lv[0];
+            bodyF[8] = lv[1];
+            bodyF[9] = lv[2];
+            bodyF[10] = av[0];
+            bodyF[11] = av[1];
+            bodyF[12] = av[2];
+            bodyF[13] = desc.mass ?? 0;
+            bodyF[14] = desc.linearDamping ?? 0;
+            bodyF[15] = desc.angularDamping ?? 0;
+            bodyF[16] = desc.gravityScale ?? 1;
+            let flags = 0;
+            if (desc.ccdEnabled)
+                flags |= 1 << 0;
+            if (desc.canSleep !== false)
+                flags |= 1 << 1;
+            if (desc.sleeping)
+                flags |= 1 << 2;
+            const lt = desc.lockedAxes?.translation;
+            if (lt?.[0])
+                flags |= 1 << 3;
+            if (lt?.[1])
+                flags |= 1 << 4;
+            if (lt?.[2])
+                flags |= 1 << 5;
+            const lr = desc.lockedAxes?.rotation;
+            if (lr?.[0])
+                flags |= 1 << 6;
+            if (lr?.[1])
+                flags |= 1 << 7;
+            if (lr?.[2])
+                flags |= 1 << 8;
+            if (desc.mass)
+                flags |= 1 << 9;
+            if (desc.linearDamping)
+                flags |= 1 << 10;
+            if (desc.angularDamping)
+                flags |= 1 << 11;
+            if (desc.gravityScale !== undefined)
+                flags |= 1 << 12;
+            bodyI[0] = BODY_TYPE[desc.type] ?? 2;
+            bodyI[1] = flags;
+            s.dd_create_body(realmId, bodyId, ptr(bodyF), ptr(bodyI));
+            entities(realmId).set(bodyId, entity);
+            bodyIdByEntityIndex.get(realmId)?.set(entity.index, bodyId);
+        },
+        destroyBody(realmId, bodyId) {
+            s.dd_destroy_body(realmId, bodyId);
+            const ent = entityByBodyId.get(realmId)?.get(bodyId);
+            if (ent)
+                bodyIdByEntityIndex.get(realmId)?.delete(ent.index);
+            entityByBodyId.get(realmId)?.delete(bodyId);
+        },
+        setBodyType(realmId, bodyId, type) {
+            s.dd_set_body_type(realmId, bodyId, BODY_TYPE[type] ?? 2);
+        },
+        addCollider(realmId, bodyId, colliderId, desc) {
+            const shape = desc.shape;
+            collMeta.fill(0);
+            collF.fill(0);
+            collMeta[0] = SHAPE_TYPE[shape.type] ?? 0;
+            collMeta[1] = desc.sensor ? 1 : 0;
+            collMeta[2] = desc.collisionGroups ?? 0;
+            collMeta[3] = desc.solverGroups ?? 0;
+            let flags = 0;
+            let verts = null;
+            let indices = null;
+            if (shape.type === "sphere") {
+                collF[0] = shape.radius;
+            }
+            else if (shape.type === "box") {
+                collF[0] = shape.halfExtents[0];
+                collF[1] = shape.halfExtents[1];
+                collF[2] = shape.halfExtents[2];
+            }
+            else if (shape.type === "capsule") {
+                collF[0] = shape.halfHeight;
+                collF[1] = shape.radius;
+            }
+            else if (shape.type === "convex") {
+                verts = shape.vertices;
+                collMeta[4] = shape.vertices.length / 3;
+            }
+            else if (shape.type === "mesh") {
+                verts = shape.vertices;
+                indices = shape.indices;
+                collMeta[4] = shape.vertices.length / 3;
+                collMeta[5] = shape.indices.length;
+            }
+            else if (shape.type === "heightfield") {
+                // Native heightfield works (unlike WASM rapier 0.19 which panics).
+                verts = shape.heights;
+                collMeta[4] = shape.nrows * shape.ncols;
+                collMeta[7] = shape.nrows;
+                collMeta[8] = shape.ncols;
+                collF[0] = shape.scale[0];
+                collF[1] = shape.scale[1];
+                collF[2] = shape.scale[2];
+            }
+            if (desc.friction !== undefined) {
+                flags |= 1 << 0;
+                collF[4] = desc.friction;
+            }
+            if (desc.restitution !== undefined) {
+                flags |= 1 << 1;
+                collF[5] = desc.restitution;
+            }
+            if (desc.density !== undefined) {
+                flags |= 1 << 2;
+                collF[6] = desc.density;
+            }
+            if (desc.translation) {
+                flags |= 1 << 3;
+                collF[7] = desc.translation[0];
+                collF[8] = desc.translation[1];
+                collF[9] = desc.translation[2];
+            }
+            if (desc.rotation) {
+                flags |= 1 << 4;
+                collF[10] = desc.rotation[0];
+                collF[11] = desc.rotation[1];
+                collF[12] = desc.rotation[2];
+                collF[13] = desc.rotation[3];
+            }
+            if (desc.collisionGroups !== undefined)
+                flags |= 1 << 5;
+            if (desc.solverGroups !== undefined)
+                flags |= 1 << 6;
+            collMeta[6] = flags;
+            s.dd_add_collider(realmId, bodyId, colliderId, ptr(collMeta), ptr(collF), verts ? ptr(verts) : 0, indices ? ptr(indices) : 0);
+        },
+        removeCollider(realmId, _bodyId, colliderId) {
+            s.dd_remove_collider(realmId, colliderId);
+        },
+        setColliderPosition(realmId, colliderId, pos) {
+            s.dd_set_collider_position(realmId, colliderId, pos[0], pos[1], pos[2]);
+        },
+        getColliderPosition(realmId, colliderId) {
+            if (s.dd_get_collider_position(realmId, colliderId, ptr(out3)) !== 1)
+                return [0, 0, 0];
+            return [out3[0], out3[1], out3[2]];
+        },
+        swapColliderShapeRaw(realmId, colliderId, vertices, indices) {
+            return s.dd_swap_collider_shape(realmId, colliderId, ptr(vertices), vertices.length / 3, ptr(indices), indices.length) === 1;
+        },
+        testConvexHull(vertices) {
+            return s.dd_test_convex_hull(ptr(vertices), vertices.length / 3) === 1;
+        },
+        getColliderShapeType(realmId, colliderId) {
+            return s.dd_collider_shape_type(realmId, colliderId);
+        },
+        getColliderCount(realmId, bodyId) {
+            return s.dd_collider_count(realmId, bodyId);
+        },
+        applyForce(realmId, bodyId, f) { s.dd_apply_force(realmId, bodyId, f[0], f[1], f[2]); },
+        applyImpulse(realmId, bodyId, f) { s.dd_apply_impulse(realmId, bodyId, f[0], f[1], f[2]); },
+        applyTorque(realmId, bodyId, f) { s.dd_apply_torque(realmId, bodyId, f[0], f[1], f[2]); },
+        applyTorqueImpulse(realmId, bodyId, f) { s.dd_apply_torque_impulse(realmId, bodyId, f[0], f[1], f[2]); },
+        applyImpulseAtPoint(realmId, bodyId, imp, pt) {
+            s.dd_apply_impulse_at_point(realmId, bodyId, imp[0], imp[1], imp[2], pt[0], pt[1], pt[2]);
+        },
+        setLinearVelocity(realmId, bodyId, v) { s.dd_set_linvel(realmId, bodyId, v[0], v[1], v[2], 1); },
+        setAngularVelocity(realmId, bodyId, v) { s.dd_set_angvel(realmId, bodyId, v[0], v[1], v[2], 1); },
+        setPosition(realmId, bodyId, p) { s.dd_set_translation(realmId, bodyId, p[0], p[1], p[2], 1); },
+        setRotation(realmId, bodyId, r) { s.dd_set_rotation(realmId, bodyId, r[0], r[1], r[2], r[3], 1); },
+        wakeUp(realmId, bodyId) { s.dd_wake_up(realmId, bodyId); },
+        setTranslationRaw(realmId, bodyId, x, y, z, wake) {
+            s.dd_set_translation(realmId, bodyId, x, y, z, wake ? 1 : 0);
+        },
+        setRotationRaw(realmId, bodyId, x, y, z, w, wake) {
+            s.dd_set_rotation(realmId, bodyId, x, y, z, w, wake ? 1 : 0);
+        },
+        getTranslationRaw(realmId, bodyId, out) {
+            s.dd_get_translation(realmId, bodyId, ptr(out3));
+            out[0] = out3[0];
+            out[1] = out3[1];
+            out[2] = out3[2];
+        },
+        getRotationRaw(realmId, bodyId, out) {
+            s.dd_get_rotation(realmId, bodyId, ptr(out4));
+            out[0] = out4[0];
+            out[1] = out4[1];
+            out[2] = out4[2];
+            out[3] = out4[3];
+        },
+        getLinearVelocityRaw(realmId, bodyId, out) {
+            s.dd_get_linvel(realmId, bodyId, ptr(out3));
+            out[0] = out3[0];
+            out[1] = out3[1];
+            out[2] = out3[2];
+        },
+        setLinearVelocityRaw(realmId, bodyId, x, y, z, wake) {
+            s.dd_set_linvel(realmId, bodyId, x, y, z, wake ? 1 : 0);
+        },
+        setAngularVelocityRaw(realmId, bodyId, x, y, z, wake) {
+            s.dd_set_angvel(realmId, bodyId, x, y, z, wake ? 1 : 0);
+        },
+        isSleepingRaw(realmId, bodyId) {
+            return s.dd_is_sleeping(realmId, bodyId) === 1;
+        },
+        readAwakeBodyStates(realmId, idsOut, out, maxCount) {
+            return s.dd_read_awake(realmId, ptr(idsOut), ptr(out), maxCount);
+        },
+        stepAndReadAwake(realmId, dt, idsOut, out, maxCount) {
+            return s.dd_step_and_read_awake(realmId, dt, ptr(idsOut), ptr(out), maxCount);
+        },
+        applyBodyWrites(realmId, ids, states, count, wake) {
+            s.dd_apply_body_writes(realmId, ptr(ids), ptr(states), count, wake ? 1 : 0);
+        },
+        applyImpulses(realmId, ids, impulses, count) {
+            s.dd_apply_impulses(realmId, ptr(ids), ptr(impulses), count);
+        },
+        reserveMemory() { },
+        setIntegrationDt(realmId, dt) { s.dd_set_integration_dt(realmId, dt); },
+        setSleepThresholds() { },
+        setSolverIterations(realmId, n) { s.dd_set_solver_iterations(realmId, n); },
+        setMinIslandSize(realmId, size) { s.dd_set_min_island_size(realmId, size); },
+        setCCDEnabled(realmId, bodyId, enabled) { s.dd_set_ccd(realmId, bodyId, enabled ? 1 : 0); },
+        // WASM parity: step() uses the stored integration dt (setIntegrationDt),
+        // so pass 0 to avoid overriding it.
+        step(realmId, _dt) { s.dd_step(realmId, 0); },
+        getBodyTransform(realmId, bodyId) {
+            if (s.dd_get_body_transform(realmId, bodyId, ptr(out7)) !== 1)
+                return null;
+            return {
+                position: [out7[0], out7[1], out7[2]],
+                rotation: [out7[3], out7[4], out7[5], out7[6]],
+            };
+        },
+        raycast(realmId, origin, direction, maxDistance, filter) {
+            const groups = filter?.collisionGroups ?? 0;
+            const excl = excludeBodyId(realmId, filter?.excludeEntity);
+            if (s.dd_raycast(realmId, origin[0], origin[1], origin[2], direction[0], direction[1], direction[2], maxDistance, groups, excl, ptr(rayOut)) !== 1) {
+                return null;
+            }
+            return {
+                entity: entityFor(realmId, rayOut[7] | 0),
+                point: [rayOut[0], rayOut[1], rayOut[2]],
+                normal: [rayOut[3], rayOut[4], rayOut[5]],
+                distance: rayOut[6],
+            };
+        },
+        raycastMulti(realmId, origin, direction, maxDistance, filter) {
+            // WASM parity: the WASM raycastMulti returns only the single closest hit.
+            const hit = this.raycast(realmId, origin, direction, maxDistance, filter);
+            return hit ? [hit] : [];
+        },
+        shapeCast(realmId, shape, origin, rotation, direction, maxDistance, filter) {
+            // f: [shape params (3), origin3, quat4, dir3]
+            const f = new Float32Array(13);
+            const st = SHAPE_TYPE[shape.type] ?? 0;
+            if (shape.type === "sphere") {
+                f[0] = shape.radius;
+            }
+            else if (shape.type === "box") {
+                f[0] = shape.halfExtents[0];
+                f[1] = shape.halfExtents[1];
+                f[2] = shape.halfExtents[2];
+            }
+            else if (shape.type === "capsule") {
+                f[0] = shape.halfHeight;
+                f[1] = shape.radius;
+            }
+            else {
+                f[0] = 0.5; // fallback ball (WASM parity)
+            }
+            const nativeType = st <= 2 ? st : 0;
+            f[3] = origin[0];
+            f[4] = origin[1];
+            f[5] = origin[2];
+            f[6] = rotation[0];
+            f[7] = rotation[1];
+            f[8] = rotation[2];
+            f[9] = rotation[3];
+            f[10] = direction[0];
+            f[11] = direction[1];
+            f[12] = direction[2];
+            const groups = filter?.collisionGroups ?? 0;
+            const excl = excludeBodyId(realmId, filter?.excludeEntity);
+            if (s.dd_shape_cast(realmId, nativeType, ptr(f), maxDistance, groups, excl, ptr(rayOut)) !== 1) {
+                return null;
+            }
+            return {
+                entity: entityFor(realmId, rayOut[7] | 0),
+                point: [rayOut[0], rayOut[1], rayOut[2]],
+                normal: [rayOut[3], rayOut[4], rayOut[5]],
+                distance: rayOut[6],
+                hitFraction: rayOut[6],
+            };
+        },
+        getContacts(realmId) {
+            let n = s.dd_get_contacts(realmId, ptr(contactsI), ptr(contactsF), ptr(contactsPts), contactsI.length / 3);
+            if (n >= contactsI.length / 3) {
+                contactsI = new Int32Array(n * 2 * 3);
+                contactsF = new Float32Array(n * 2 * 4);
+                contactsPts = new Float32Array(n * 2 * 12);
+                n = s.dd_get_contacts(realmId, ptr(contactsI), ptr(contactsF), ptr(contactsPts), n * 2);
+            }
+            const contacts = [];
+            for (let k = 0; k < n; k++) {
+                const nPts = contactsI[k * 3 + 2];
+                const points = [];
+                for (let p = 0; p < nPts; p++) {
+                    const base = k * 12 + p * 3;
+                    points.push([contactsPts[base], contactsPts[base + 1], contactsPts[base + 2]]);
+                }
+                contacts.push({
+                    entityA: entityFor(realmId, contactsI[k * 3]),
+                    entityB: entityFor(realmId, contactsI[k * 3 + 1]),
+                    normal: [contactsF[k * 4], contactsF[k * 4 + 1], contactsF[k * 4 + 2]],
+                    points,
+                    penetrationDepth: contactsF[k * 4 + 3],
+                });
+            }
+            return contacts;
+        },
+        getIntersections(realmId) {
+            let n = s.dd_get_intersections(realmId, ptr(intersectI), intersectI.length / 2);
+            if (n >= intersectI.length / 2) {
+                intersectI = new Int32Array(n * 2 * 2);
+                n = s.dd_get_intersections(realmId, ptr(intersectI), n * 2);
+            }
+            const pairs = [];
+            for (let k = 0; k < n; k++) {
+                pairs.push({
+                    entityA: entityFor(realmId, intersectI[k * 2]),
+                    entityB: entityFor(realmId, intersectI[k * 2 + 1]),
+                });
+            }
+            return pairs;
+        },
+        createCharacterController(realmId, desc, handle) {
+            charF[0] = desc.offset[1]; // WASM parity: offset[1] is the absolute gap
+            charF[1] = desc.radius;
+            charF[2] = desc.halfHeight;
+            charF[3] = desc.maxSlope;
+            charF[4] = desc.minSlopeSlide;
+            charF[5] = desc.snapToGround;
+            charF[6] = desc.autostep.minWidth;
+            charF[7] = desc.autostep.maxHeight;
+            const p = desc.parentless?.position ?? [0, 0, 0];
+            charF[8] = p[0];
+            charF[9] = p[1];
+            charF[10] = p[2];
+            charI[0] = desc.slide ? 1 : 0;
+            charI[1] = desc.autostep.enabled ? 1 : 0;
+            charI[2] = desc.applyImpulsesToDynamicBodies ? 1 : 0;
+            charI[3] = desc.parentless ? 1 : 0;
+            charI[4] = desc.parentless?.collisionGroups ?? desc.collisionGroups ?? 0;
+            // WASM parity: non-parentless controllers look up the body by
+            // handle.entity.index (bodyId === entity.index for those callers).
+            charI[5] = handle.entity.index;
+            s.dd_char_create(realmId, handle.controllerId, ptr(charF), ptr(charI));
+        },
+        destroyCharacterController(realmId, controllerId) {
+            s.dd_char_destroy(realmId, controllerId);
+        },
+        setCharacterColliderPosition(realmId, controllerId, pos) {
+            s.dd_char_set_collider_pos(realmId, controllerId, pos[0], pos[1], pos[2]);
+        },
+        characterMove(realmId, controllerId, desiredMovement, dt) {
+            const maxColl = charOutI.length - 1;
+            const n = s.dd_char_move(realmId, controllerId, desiredMovement[0], desiredMovement[1], desiredMovement[2], dt, ptr(charOutF), ptr(charOutI), maxColl);
+            if (n < 0) {
+                return {
+                    grounded: false, groundNormal: [0, 1, 0], groundEntity: null,
+                    slid: false, stepped: false, effectiveMovement: [0, 0, 0], collisions: [],
+                };
+            }
+            const grounded = charOutF[0] !== 0;
+            const collisions = [];
+            for (let k = 0; k < n; k++) {
+                const bid = charOutI[1 + k];
+                collisions.push({ entity: bid >= 0 ? entityFor(realmId, bid) : null });
+            }
+            const groundId = charOutI[0];
+            return {
+                grounded,
+                groundNormal: [0, 1, 0],
+                groundEntity: groundId >= 0 ? entityFor(realmId, groundId) : null,
+                slid: charOutF[4] !== 0,
+                stepped: false,
+                effectiveMovement: [charOutF[1], charOutF[2], charOutF[3]],
+                collisions,
+            };
+        },
+        createJoint(realmId, parentBodyId, childBodyId, jointId, desc) {
+            jointF.fill(0);
+            jointF[0] = desc.anchorA[0];
+            jointF[1] = desc.anchorA[1];
+            jointF[2] = desc.anchorA[2];
+            jointF[3] = desc.anchorB[0];
+            jointF[4] = desc.anchorB[1];
+            jointF[5] = desc.anchorB[2];
+            const axis = desc.axis ?? [0, 1, 0];
+            jointF[6] = axis[0];
+            jointF[7] = axis[1];
+            jointF[8] = axis[2];
+            jointF[9] = desc.limits?.min ?? 0;
+            jointF[10] = desc.limits?.max ?? 0;
+            // frames: identity quats (x,y,z,w)
+            jointF[14] = 1;
+            jointF[18] = 1;
+            s.dd_create_joint(realmId, jointId, parentBodyId, childBodyId, JOINT_TYPE[desc.type] ?? 0, ptr(jointF));
+        },
+        destroyJoint(realmId, jointId) {
+            s.dd_destroy_joint(realmId, jointId);
+        },
+        getIslands(realmId) {
+            // IslandManager internals aren't exposed over FFI — one island per
+            // known body (same shape as the WASM approximation).
+            const m = entityByBodyId.get(realmId);
+            if (!m)
+                return [];
+            const islands = [];
+            for (const bodyId of m.keys()) {
+                s.dd_get_linvel(realmId, bodyId, ptr(out3));
+                islands.push({
+                    bodyIds: [bodyId],
+                    maxImportance: 0,
+                    avgVelocity: Math.sqrt(out3[0] ** 2 + out3[1] ** 2 + out3[2] ** 2),
+                });
+            }
+            return islands;
+        },
+        serializeRealm() {
+            // Requires a serde-enabled rapier build — not wired yet.
+            return new Uint8Array(0);
+        },
+        deserializeRealm() { },
+        destroy() {
+            s.dd_destroy();
+            entityByBodyId.clear();
+            bodyIdByEntityIndex.clear();
+        },
+    };
+    return ffiLib;
+}

package/dist/libraries/physics-rapier/src/index.js

@@ -0,0 +1,9 @@
+export { UniversalPhysicsAPI } from "./api.js";
+export { RapierPhysicsBackend } from "./backend.js";
+export { bulkReadMultiRealm, bulkReadTransforms, bulkWriteTransforms } from "./bulk-ops.js";
+// Native FFI backend intentionally not re-exported here — ffi-lib.ts pulls
+// @downdraft/platform-native, which must stay out of web bundles.
+// Native code imports "@downdraft/engine/libraries/physics-rapier/ffi-backend".
+export { createRapierBackend, isNativeRuntime } from "./auto-backend.js";
+// Declarative library descriptor
+export { PhysicsAPITok, PhysicsRapierLib } from "./library.js";