@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/libraries/physics-native/src/broadphase.js

@@ -0,0 +1,79 @@
+// ============================================================================
+// Broadphase — Spatial hash grid for AABB pair generation
+//
+// Inserts body AABBs into a uniform grid, then queries neighboring cells for
+// potential collision pairs. O(n) insert + O(n * k) pair gen where k is the
+// average number of bodies per cell.
+// ============================================================================
+export class Broadphase {
+    cellSize;
+    cells = new Map();
+    constructor(cellSize = 8) {
+        this.cellSize = cellSize;
+    }
+    key(cx, cy, cz) {
+        return `${cx}:${cy}:${cz}`;
+    }
+    worldToCell(pos) {
+        return Math.floor(pos / this.cellSize);
+    }
+    insert(bodyId, aabb) {
+        const minCx = this.worldToCell(aabb.minX);
+        const maxCx = this.worldToCell(aabb.maxX);
+        const minCy = this.worldToCell(aabb.minY);
+        const maxCy = this.worldToCell(aabb.maxY);
+        const minCz = this.worldToCell(aabb.minZ);
+        const maxCz = this.worldToCell(aabb.maxZ);
+        const entry = { bodyId, aabb };
+        for (let cx = minCx; cx <= maxCx; cx++) {
+            for (let cy = minCy; cy <= maxCy; cy++) {
+                for (let cz = minCz; cz <= maxCz; cz++) {
+                    const k = this.key(cx, cy, cz);
+                    let cell = this.cells.get(k);
+                    if (!cell) {
+                        cell = [];
+                        this.cells.set(k, cell);
+                    }
+                    cell.push(entry);
+                }
+            }
+        }
+    }
+    /**
+     * Generate unique candidate collision pairs by checking overlapping AABBs
+     * in the same grid cells. Returns pairs as [bodyA, bodyB] with bodyA < bodyB.
+     */
+    generatePairs() {
+        const pairs = [];
+        const seen = new Set();
+        for (const cell of this.cells.values()) {
+            for (let i = 0; i < cell.length; i++) {
+                for (let j = i + 1; j < cell.length; j++) {
+                    const a = cell[i];
+                    const b = cell[j];
+                    const aId = Math.min(a.bodyId, b.bodyId);
+                    const bId = Math.max(a.bodyId, b.bodyId);
+                    const pairKey = `${aId}:${bId}`;
+                    if (seen.has(pairKey))
+                        continue;
+                    seen.add(pairKey);
+                    if (this.aabbOverlap(a.aabb, b.aabb)) {
+                        pairs.push([aId, bId]);
+                    }
+                }
+            }
+        }
+        return pairs;
+    }
+    clear() {
+        this.cells.clear();
+    }
+    setCellSize(size) {
+        this.cellSize = size;
+    }
+    aabbOverlap(a, b) {
+        return a.minX <= b.maxX && a.maxX >= b.minX &&
+            a.minY <= b.maxY && a.maxY >= b.minY &&
+            a.minZ <= b.maxZ && a.maxZ >= b.minZ;
+    }
+}

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

@@ -0,0 +1,6 @@
+export { NativePhysicsBackend } from "./backend.js";
+export { Broadphase } from "./broadphase.js";
+export { detectCollision } from "./narrowphase.js";
+export { integrate, resolveContact } from "./solver.js";
+export * from "./types.js";
+export { PhysicsNativeLib, PhysicsNativeAPITok } from "./library.js";

package/dist/libraries/physics-native/src/library.js

@@ -0,0 +1,57 @@
+// ============================================================================
+// PhysicsNativeLib — declarative engine library descriptor for @downdraft/engine/libraries/physics-native
+//
+// Games declare `libraries: [PhysicsNativeLib]` (or with config override)
+// in their GameModule. The host creates the NativePhysicsBackend (sim-side
+// only — physics has no renderer component).
+//
+// Games that need full control can still import NativePhysicsBackend directly
+// (escape hatch).
+// ============================================================================
+import { RealmTier, resourceToken } from "@downdraft/engine";
+import { NativePhysicsBackend } from "./backend.js";
+// ── Typed tokens (DI) ──
+/** Token for the native physics backend. Inject in sim systems that need physics. */
+export const PhysicsNativeAPITok = resourceToken("physics-native:api");
+// ── Descriptor ──
+export const PhysicsNativeLib = {
+    name: "physics-native",
+    version: "1.0.0",
+    // No SAB channels — physics is sim-only, results synced via main SimBuffer.
+    sabChannels: [],
+    provides: [PhysicsNativeAPITok],
+    sim: {
+        create(config, ctx) {
+            const backend = new NativePhysicsBackend();
+            // Create a default realm with the configured gravity.
+            // Games can create additional realms via backend.createRealm().
+            backend.createRealm({
+                id: 0,
+                name: "default",
+                tier: RealmTier.Near,
+                gravity: config.gravity ?? [0, -9.8, 0],
+                tierConfig: {
+                    tickFrequency: 1,
+                    solverIterations: 4,
+                    promoteThreshold: 0,
+                    demoteThreshold: 50,
+                    demoteDwellTime: 0,
+                },
+            });
+            ctx.provide(PhysicsNativeAPITok, backend);
+            return backend;
+        },
+        dispose(backend) {
+            backend.destroy();
+        },
+        // tick is game-specific (calls backend.step() with entity data, reads back
+        // transforms, etc.) — games wire this via onReady or a sim system.
+    },
+    tickPhase: "physics",
+    // No renderer setup — physics is entirely sim-side.
+    defaultConfig: {
+        gravity: [0, -9.8, 0],
+        fixedDt: 1 / 60,
+        maxEntities: 4096,
+    },
+};

package/dist/libraries/physics-native/src/narrowphase-shapes.js

@@ -0,0 +1,348 @@
+// ============================================================================
+// Narrowphase shape functions — SAT and distance-based collision detection
+//
+// Each function returns a ContactManifoldLocal or null. Normal points from A
+// to B. All positions are world-space centers.
+// ============================================================================
+// --- Math helpers ---
+function sub(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+function add(a, b) {
+    return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+function scale(a, s) {
+    return [a[0] * s, a[1] * s, a[2] * s];
+}
+function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+function cross(a, b) {
+    return [
+        a[1] * b[2] - a[2] * b[1],
+        a[2] * b[0] - a[0] * b[2],
+        a[0] * b[1] - a[1] * b[0],
+    ];
+}
+function length(a) {
+    return Math.sqrt(a[0] * a[0] + a[1] * a[1] + a[2] * a[2]);
+}
+function normalize(a) {
+    const len = length(a);
+    if (len < 1e-9)
+        return [0, 0, 0];
+    return [a[0] / len, a[1] / len, a[2] / len];
+}
+/**
+ * Rotate a vector by a quaternion (xyzw).
+ */
+export function rotateVec(v, q) {
+    const qx = q[0], qy = q[1], qz = q[2], qw = q[3];
+    // t = 2 * cross(q.xyz, v)
+    const tx = 2 * (qy * v[2] - qz * v[1]);
+    const ty = 2 * (qz * v[0] - qx * v[2]);
+    const tz = 2 * (qx * v[1] - qy * v[0]);
+    // result = v + qw * t + cross(q.xyz, t)
+    return [
+        v[0] + qw * tx + (qy * tz - qz * ty),
+        v[1] + qw * ty + (qz * tx - qx * tz),
+        v[2] + qw * tz + (qx * ty - qy * tx),
+    ];
+}
+/**
+ * Get the three axis vectors of a box from its quaternion.
+ */
+function boxAxes(q) {
+    return [
+        rotateVec([1, 0, 0], q),
+        rotateVec([0, 1, 0], q),
+        rotateVec([0, 0, 1], q),
+    ];
+}
+function clamp(v, min, max) {
+    return v < min ? min : v > max ? max : v;
+}
+// --- Sphere-Sphere ---
+export function sphereSphereContact(posA, radiusA, posB, radiusB) {
+    const delta = sub(posB, posA);
+    const dist = length(delta);
+    const sumRadii = radiusA + radiusB;
+    if (dist >= sumRadii)
+        return null;
+    const normal = dist > 1e-9 ? scale(delta, 1 / dist) : [0, 1, 0];
+    const penetration = sumRadii - dist;
+    const contactPoint = add(posA, scale(normal, radiusA - penetration * 0.5));
+    return {
+        normal: normal,
+        penetrationDepth: penetration,
+        points: [{ point: contactPoint, penetration }],
+    };
+}
+// --- Sphere-Box ---
+export function sphereBoxContact(spherePos, sphereRadius, boxPos, boxRot, boxHalf) {
+    // Transform sphere center into box local space
+    const invRot = [boxRot[0], boxRot[1], boxRot[2], -boxRot[3]];
+    const localSphere = rotateVec(sub(spherePos, boxPos), invRot);
+    // Clamp to box to find closest point
+    const closest = [
+        clamp(localSphere[0], -boxHalf[0], boxHalf[0]),
+        clamp(localSphere[1], -boxHalf[1], boxHalf[1]),
+        clamp(localSphere[2], -boxHalf[2], boxHalf[2]),
+    ];
+    const localDelta = sub(localSphere, closest);
+    const distSq = dot(localDelta, localDelta);
+    if (distSq >= sphereRadius * sphereRadius)
+        return null;
+    const dist = Math.sqrt(distSq);
+    let localNormal;
+    let penetration;
+    if (dist > 1e-9) {
+        localNormal = scale(localDelta, 1 / dist);
+        penetration = sphereRadius - dist;
+    }
+    else {
+        // Sphere center is inside the box — push out along the axis of least penetration
+        const penX = boxHalf[0] - Math.abs(localSphere[0]);
+        const penY = boxHalf[1] - Math.abs(localSphere[1]);
+        const penZ = boxHalf[2] - Math.abs(localSphere[2]);
+        if (penX <= penY && penX <= penZ) {
+            localNormal = [Math.sign(localSphere[0]) || 1, 0, 0];
+            penetration = penX + sphereRadius;
+        }
+        else if (penY <= penZ) {
+            localNormal = [0, Math.sign(localSphere[1]) || 1, 0];
+            penetration = penY + sphereRadius;
+        }
+        else {
+            localNormal = [0, 0, Math.sign(localSphere[2]) || 1];
+            penetration = penZ + sphereRadius;
+        }
+    }
+    // Transform normal back to world space
+    const worldNormal = rotateVec(localNormal, boxRot);
+    const worldClosest = add(boxPos, rotateVec(closest, boxRot));
+    // Normal points from box to sphere; we need A to B = box to sphere
+    // But caller expects A=sphere, B=box so normal should be sphere to box = negated
+    const normalAtoB = scale(worldNormal, -1);
+    return {
+        normal: normalAtoB,
+        penetrationDepth: penetration,
+        points: [{ point: worldClosest, penetration }],
+    };
+}
+// --- Box-Box (SAT) ---
+export function boxBoxContact(posA, rotA, halfA, posB, rotB, halfB) {
+    const axesA = boxAxes(rotA);
+    const axesB = boxAxes(rotB);
+    // 15 axes to test: 3 from A, 3 from B, 9 cross products
+    const axes = [...axesA, ...axesB];
+    for (let i = 0; i < 3; i++) {
+        for (let j = 0; j < 3; j++) {
+            const ax = cross(axesA[i], axesB[j]);
+            const len = length(ax);
+            if (len > 1e-9) {
+                axes.push(scale(ax, 1 / len));
+            }
+        }
+    }
+    const delta = sub(posB, posA);
+    let minPen = Infinity;
+    let minAxis = [0, 1, 0];
+    for (let _i = 0, _it = axes, _n = _it.length; _i < _n; _i++) {
+        const axis = _it[_i];
+        const projA = projectBox(posA, axesA, halfA, axis);
+        const projB = projectBox(posB, axesB, halfB, axis);
+        const overlap = Math.min(projA.max, projB.max) - Math.max(projA.min, projB.min);
+        if (overlap <= 0)
+            return null;
+        if (overlap < minPen) {
+            minPen = overlap;
+            minAxis = axis;
+            // Ensure normal points from A to B
+            if (dot(delta, axis) < 0) {
+                minAxis = scale(axis, -1);
+            }
+        }
+    }
+    // Contact point: approximate as the midpoint of the overlap region projected
+    const contactPoint = add(posA, scale(minAxis, 0));
+    // Better: average of centers projected onto the contact plane
+    const centerA = posA;
+    const centerB = posB;
+    const mid = scale(add(centerA, centerB), 0.5);
+    return {
+        normal: minAxis,
+        penetrationDepth: minPen,
+        points: [{ point: mid, penetration: minPen }],
+    };
+}
+function projectBox(pos, axes, half, axis) {
+    const center = dot(pos, axis);
+    let radius = 0;
+    for (let i = 0; i < 3; i++) {
+        radius += Math.abs(dot(axes[i], axis)) * half[i];
+    }
+    return { min: center - radius, max: center + radius };
+}
+// --- Capsule helpers ---
+/**
+ * Get the two endpoints of a capsule's axis in world space.
+ */
+function capsuleEndpoints(pos, rot, halfHeight) {
+    const up = rotateVec([0, 1, 0], rot);
+    const top = add(pos, scale(up, halfHeight));
+    const bottom = add(pos, scale(up, -halfHeight));
+    return [top, bottom];
+}
+/**
+ * Closest point on a line segment to a point.
+ */
+function closestPointOnSegment(p, a, b) {
+    const ab = sub(b, a);
+    const t = clamp(dot(sub(p, a), ab) / dot(ab, ab), 0, 1);
+    return add(a, scale(ab, t));
+}
+/**
+ * Closest points between two line segments.
+ */
+function segmentSegmentClosest(a1, a2, b1, b2) {
+    const d1 = sub(a2, a1);
+    const d2 = sub(b2, b1);
+    const r = sub(a1, b1);
+    const a = dot(d1, d1);
+    const e = dot(d2, d2);
+    const f = dot(d2, r);
+    let s, t;
+    if (a <= 1e-9 && e <= 1e-9) {
+        s = 0;
+        t = 0;
+    }
+    else if (a <= 1e-9) {
+        s = 0;
+        t = clamp(-f / e, 0, 1);
+    }
+    else {
+        const c = dot(d1, r);
+        if (e <= 1e-9) {
+            t = 0;
+            s = clamp(-c / a, 0, 1);
+        }
+        else {
+            const b = dot(d1, d2);
+            const denom = a * e - b * b;
+            if (denom > 1e-9) {
+                s = clamp((b * f - c * e) / denom, 0, 1);
+            }
+            else {
+                s = 0;
+            }
+            t = clamp((b * s + f) / e, 0, 1);
+        }
+    }
+    const pointA = add(a1, scale(d1, s));
+    const pointB = add(b1, scale(d2, t));
+    const dist = length(sub(pointA, pointB));
+    return { pointA, pointB, dist };
+}
+// --- Capsule-Box ---
+export function capsuleBoxContact(capPos, capRot, capHalfH, capRadius, boxPos, boxRot, boxHalf) {
+    const [top, bottom] = capsuleEndpoints(capPos, capRot, capHalfH);
+    // Transform capsule endpoints into box local space
+    const invRot = [boxRot[0], boxRot[1], boxRot[2], -boxRot[3]];
+    const localTop = rotateVec(sub(top, boxPos), invRot);
+    const localBottom = rotateVec(sub(bottom, boxPos), invRot);
+    // Sample the capsule axis at a few points and find closest on box
+    let bestDist = Infinity;
+    let bestLocalPoint = [0, 0, 0];
+    let bestAxisPoint = [0, 0, 0];
+    const samples = 8;
+    for (let i = 0; i <= samples; i++) {
+        const t = i / samples;
+        const p = add(localBottom, scale(sub(localTop, localBottom), t));
+        const closest = [
+            clamp(p[0], -boxHalf[0], boxHalf[0]),
+            clamp(p[1], -boxHalf[1], boxHalf[1]),
+            clamp(p[2], -boxHalf[2], boxHalf[2]),
+        ];
+        const d = length(sub(p, closest));
+        if (d < bestDist) {
+            bestDist = d;
+            bestLocalPoint = closest;
+            bestAxisPoint = p;
+        }
+    }
+    if (bestDist >= capRadius)
+        return null;
+    const localDelta = sub(bestAxisPoint, bestLocalPoint);
+    const dist = bestDist;
+    let localNormal;
+    let penetration;
+    if (dist > 1e-9) {
+        localNormal = scale(localDelta, 1 / dist);
+        penetration = capRadius - dist;
+    }
+    else {
+        // Capsule axis inside box — push out along least penetration axis
+        const penX = boxHalf[0] - Math.abs(bestAxisPoint[0]);
+        const penY = boxHalf[1] - Math.abs(bestAxisPoint[1]);
+        const penZ = boxHalf[2] - Math.abs(bestAxisPoint[2]);
+        if (penX <= penY && penX <= penZ) {
+            localNormal = [Math.sign(bestAxisPoint[0]) || 1, 0, 0];
+            penetration = penX + capRadius;
+        }
+        else if (penY <= penZ) {
+            localNormal = [0, Math.sign(bestAxisPoint[1]) || 1, 0];
+            penetration = penY + capRadius;
+        }
+        else {
+            localNormal = [0, 0, Math.sign(bestAxisPoint[2]) || 1];
+            penetration = penZ + capRadius;
+        }
+    }
+    // Normal points from box to capsule; we need A=capsule to B=box, so negate
+    const worldNormal = rotateVec(localNormal, boxRot);
+    const normalAtoB = scale(worldNormal, -1);
+    const worldContact = add(boxPos, rotateVec(bestLocalPoint, boxRot));
+    return {
+        normal: normalAtoB,
+        penetrationDepth: penetration,
+        points: [{ point: worldContact, penetration }],
+    };
+}
+// --- Capsule-Sphere ---
+export function capsuleSphereContact(capPos, capRot, capHalfH, capRadius, spherePos, sphereRadius) {
+    const [top, bottom] = capsuleEndpoints(capPos, capRot, capHalfH);
+    const closest = closestPointOnSegment(spherePos, bottom, top);
+    const delta = sub(spherePos, closest);
+    const dist = length(delta);
+    const sumRadii = capRadius + sphereRadius;
+    if (dist >= sumRadii)
+        return null;
+    const normal = dist > 1e-9 ? scale(delta, 1 / dist) : [0, 1, 0];
+    const penetration = sumRadii - dist;
+    const contactPoint = add(closest, scale(normal, capRadius - penetration * 0.5));
+    return {
+        normal: normal,
+        penetrationDepth: penetration,
+        points: [{ point: contactPoint, penetration }],
+    };
+}
+// --- Capsule-Capsule ---
+export function capsuleCapsuleContact(posA, rotA, halfHA, radiusA, posB, rotB, halfHB, radiusB) {
+    const [topA, bottomA] = capsuleEndpoints(posA, rotA, halfHA);
+    const [topB, bottomB] = capsuleEndpoints(posB, rotB, halfHB);
+    const { pointA, pointB, dist } = segmentSegmentClosest(bottomA, topA, bottomB, topB);
+    const sumRadii = radiusA + radiusB;
+    if (dist >= sumRadii)
+        return null;
+    const normal = dist > 1e-9
+        ? normalize(sub(pointB, pointA))
+        : [0, 1, 0];
+    const penetration = sumRadii - dist;
+    const contactPoint = scale(add(pointA, pointB), 0.5);
+    return {
+        normal: normal,
+        penetrationDepth: penetration,
+        points: [{ point: contactPoint, penetration }],
+    };
+}

package/dist/libraries/physics-native/src/narrowphase.js

@@ -0,0 +1,60 @@
+// ============================================================================
+// Narrowphase — Shape-specific collision detection
+//
+// Computes contact manifolds (normal, penetration depth, contact points) for
+// pairs of collider shapes: box-box, sphere-sphere, sphere-box, capsule
+// shapes. Returns null for non-colliding pairs.
+// ============================================================================
+import { boxBoxContact, sphereSphereContact, sphereBoxContact, capsuleBoxContact, capsuleSphereContact, capsuleCapsuleContact, } from "./narrowphase-shapes.js";
+export function detectCollision(shapeA, posA, rotA, shapeB, posB, rotB) {
+    const typeA = shapeA.type;
+    const typeB = shapeB.type;
+    if (typeA === "sphere" && typeB === "sphere") {
+        return sphereSphereContact(posA, shapeA.radius, posB, shapeB.radius);
+    }
+    if (typeA === "sphere" && typeB === "box") {
+        return sphereBoxContact(posA, shapeA.radius, posB, rotB, shapeB.halfExtents);
+    }
+    if (typeA === "box" && typeB === "sphere") {
+        const result = sphereBoxContact(posB, shapeB.radius, posA, rotA, shapeA.halfExtents);
+        if (!result)
+            return null;
+        // Flip normal to point from A to B
+        return {
+            ...result,
+            normal: [-result.normal[0], -result.normal[1], -result.normal[2]],
+        };
+    }
+    if (typeA === "box" && typeB === "box") {
+        return boxBoxContact(posA, rotA, shapeA.halfExtents, posB, rotB, shapeB.halfExtents);
+    }
+    if (typeA === "capsule" && typeB === "box") {
+        return capsuleBoxContact(posA, rotA, shapeA.halfHeight, shapeA.radius, posB, rotB, shapeB.halfExtents);
+    }
+    if (typeA === "box" && typeB === "capsule") {
+        const result = capsuleBoxContact(posB, rotB, shapeB.halfHeight, shapeB.radius, posA, rotA, shapeA.halfExtents);
+        if (!result)
+            return null;
+        return {
+            ...result,
+            normal: [-result.normal[0], -result.normal[1], -result.normal[2]],
+        };
+    }
+    if (typeA === "capsule" && typeB === "sphere") {
+        return capsuleSphereContact(posA, rotA, shapeA.halfHeight, shapeA.radius, posB, shapeB.radius);
+    }
+    if (typeA === "sphere" && typeB === "capsule") {
+        const result = capsuleSphereContact(posB, rotB, shapeB.halfHeight, shapeB.radius, posA, shapeA.radius);
+        if (!result)
+            return null;
+        return {
+            ...result,
+            normal: [-result.normal[0], -result.normal[1], -result.normal[2]],
+        };
+    }
+    if (typeA === "capsule" && typeB === "capsule") {
+        return capsuleCapsuleContact(posA, rotA, shapeA.halfHeight, shapeA.radius, posB, rotB, shapeB.halfHeight, shapeB.radius);
+    }
+    // Mesh/convex shapes: not supported in native narrowphase
+    return null;
+}

package/dist/libraries/physics-native/src/solver.js

@@ -0,0 +1,105 @@
+// ============================================================================
+// Solver — Impulse-based collision response + position correction
+//
+// Resolves velocity constraints (restitution + friction) and applies positional
+// correction (Baumgarte stabilization) to prevent sinking.
+// ============================================================================
+/**
+ * Resolve a single contact manifold between two bodies.
+ * Mutates body velocities in-place.
+ */
+export function resolveContact(a, b, manifold) {
+    if (a.isStatic && b.isStatic)
+        return;
+    if (a.isKinematic && b.isKinematic)
+        return;
+    const normal = manifold.normal;
+    const penetration = manifold.penetrationDepth;
+    // --- Positional correction (Baumgarte) ---
+    const percent = 0.4; // penetration slop correction factor
+    const slop = 0.01; // penetration allowance
+    const correctionMag = Math.max(penetration - slop, 0) * percent;
+    const totalInvMass = a.invMass + b.invMass;
+    if (totalInvMass > 0) {
+        const correction = scale(normal, correctionMag / totalInvMass);
+        if (!a.isStatic && !a.isKinematic) {
+            a.position = sub(a.position, scale(correction, a.invMass));
+        }
+        if (!b.isStatic && !b.isKinematic) {
+            b.position = add(b.position, scale(correction, b.invMass));
+        }
+    }
+    // --- Velocity resolution ---
+    for (let _i = 0, _it = manifold.points, _n = _it.length; _i < _n; _i++) {
+        const cp = _it[_i];
+        const ra = sub(cp.point, a.position);
+        const rb = sub(cp.point, b.position);
+        // Velocities at contact point (simplified: no angular contribution for now)
+        const velA = a.linearVelocity;
+        const velB = b.linearVelocity;
+        const relVel = sub(velB, velA);
+        const velAlongNormal = dot(relVel, normal);
+        if (velAlongNormal > 0)
+            continue; // separating
+        const e = Math.min(a.restitution, b.restitution);
+        const j = -(1 + e) * velAlongNormal / totalInvMass;
+        const impulse = scale(normal, j);
+        if (!a.isStatic && !a.isKinematic) {
+            a.linearVelocity = sub(a.linearVelocity, scale(impulse, a.invMass));
+        }
+        if (!b.isStatic && !b.isKinematic) {
+            b.linearVelocity = add(b.linearVelocity, scale(impulse, b.invMass));
+        }
+        // --- Friction (simplified Coulomb) ---
+        const tangent = sub(relVel, scale(normal, dot(relVel, normal)));
+        const tangentLen = length(tangent);
+        if (tangentLen < 1e-6)
+            continue;
+        const tangentDir = scale(tangent, 1 / tangentLen);
+        const frictionCoef = Math.sqrt(a.friction * b.friction);
+        const jt = -dot(relVel, tangentDir) / totalInvMass;
+        const jtMax = frictionCoef * Math.abs(j);
+        const jtClamped = Math.max(-jtMax, Math.min(jtMax, jt));
+        const frictionImpulse = scale(tangentDir, jtClamped);
+        if (!a.isStatic && !a.isKinematic) {
+            a.linearVelocity = sub(a.linearVelocity, scale(frictionImpulse, a.invMass));
+        }
+        if (!b.isStatic && !b.isKinematic) {
+            b.linearVelocity = add(b.linearVelocity, scale(frictionImpulse, b.invMass));
+        }
+    }
+}
+/**
+ * Integrate body position and apply gravity.
+ */
+export function integrate(body, gravity, dt) {
+    if (body.isStatic || body.isKinematic)
+        return;
+    // Validate finiteness of inputs to prevent NaN/Inf propagation
+    if (!Number.isFinite(dt) ||
+        !Number.isFinite(gravity[0]) || !Number.isFinite(gravity[1]) || !Number.isFinite(gravity[2]) ||
+        !Number.isFinite(body.linearVelocity[0]) || !Number.isFinite(body.linearVelocity[1]) || !Number.isFinite(body.linearVelocity[2]) ||
+        !Number.isFinite(body.position[0]) || !Number.isFinite(body.position[1]) || !Number.isFinite(body.position[2])) {
+        return;
+    }
+    // Apply gravity
+    body.linearVelocity = add(body.linearVelocity, scale(gravity, dt));
+    // Integrate position
+    body.position = add(body.position, scale(body.linearVelocity, dt));
+}
+// --- Vec3 helpers (local to solver to avoid import cycle) ---
+function add(a, b) {
+    return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+function sub(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+function scale(a, s) {
+    return [a[0] * s, a[1] * s, a[2] * s];
+}
+function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+function length(a) {
+    return Math.sqrt(a[0] * a[0] + a[1] * a[1] + a[2] * a[2]);
+}

package/dist/libraries/physics-native/src/types.js

@@ -0,0 +1,4 @@
+// ============================================================================
+// Types — Shared types for the native physics backend
+// ============================================================================
+export {};