@jgengine/core 0.6.0 → 0.8.0

package/dist/physics/carryable.js

@@ -0,0 +1,110 @@
+/**
+ * Movement multiplier (1 = unhindered, →0 = crushed) for a body of `mass` carried by `owners`.
+ * Pure — the HUD/movement kit reads it to slow a laden hauler (Lethal Company) and to gate items
+ * that need 2+ people (R.E.P.O.).
+ */
+export function carrySpeedMultiplier(mass, carryCapacity, owners) {
+    if (owners <= 0)
+        return 0;
+    if (mass <= 0)
+        return 1;
+    const scale = (carryCapacity * owners) / mass;
+    return scale < 0 ? 0 : scale > 1 ? 1 : scale;
+}
+/**
+ * A grabbed physics object following a moving hold point through a spring constraint (the pick —
+ * a raycast — is the caller's/shell's job; core owns the constraint). Supports shared multi-owner
+ * carry (the follow point is the average of owners' hold points), an encumbrance read, and
+ * drop/throw. Reuses `PhysicsWorld.springJoint` to a world anchor moved each frame.
+ */
+export class Carryable {
+    body;
+    world;
+    stiffness;
+    damping;
+    maxForce;
+    capacity;
+    holds = new Map();
+    joint = -1;
+    constructor(world, body, config = {}) {
+        this.world = world;
+        this.body = body;
+        this.stiffness = config.followStiffness ?? 60;
+        this.damping = config.followDamping ?? 12;
+        this.maxForce = config.maxForce ?? 40;
+        this.capacity = config.carryCapacity ?? 8;
+    }
+    get held() {
+        return this.holds.size > 0;
+    }
+    get owners() {
+        return this.holds.size;
+    }
+    mass() {
+        const im = this.world.invMass[this.body];
+        return im > 0 ? 1 / im : Number.POSITIVE_INFINITY;
+    }
+    speedMultiplier() {
+        return carrySpeedMultiplier(this.mass(), this.capacity, this.holds.size);
+    }
+    /** Add an owner grabbing at a hold point; the first owner creates the follow constraint. */
+    grab(ownerId, x, y, z) {
+        this.holds.set(ownerId, [x, y, z]);
+        if (this.joint < 0) {
+            this.joint = this.world.springJoint({
+                bodyA: this.body,
+                restLength: 0,
+                stiffness: this.stiffness,
+                damping: this.damping,
+                maxImpulse: this.maxForce,
+                anchorB: [x, y, z],
+            });
+        }
+        this.world.wake(this.body);
+    }
+    setHoldPoint(ownerId, x, y, z) {
+        const h = this.holds.get(ownerId);
+        if (h === undefined)
+            return;
+        h[0] = x;
+        h[1] = y;
+        h[2] = z;
+    }
+    release(ownerId) {
+        this.holds.delete(ownerId);
+        if (this.holds.size === 0 && this.joint >= 0) {
+            this.world.removeJoint(this.joint);
+            this.joint = -1;
+        }
+    }
+    /** Recompute the follow point (average of live hold points) and drive the constraint. */
+    update() {
+        if (this.joint < 0 || this.holds.size === 0)
+            return;
+        let tx = 0;
+        let ty = 0;
+        let tz = 0;
+        for (const h of this.holds.values()) {
+            tx += h[0];
+            ty += h[1];
+            tz += h[2];
+        }
+        const inv = 1 / this.holds.size;
+        this.world.setJointAnchor(this.joint, tx * inv, ty * inv, tz * inv);
+        this.world.wake(this.body);
+    }
+    drop() {
+        this.holds.clear();
+        if (this.joint >= 0) {
+            this.world.removeJoint(this.joint);
+            this.joint = -1;
+        }
+    }
+    throw(vx, vy, vz) {
+        this.drop();
+        this.world.velX[this.body] = vx;
+        this.world.velY[this.body] = vy;
+        this.world.velZ[this.body] = vz;
+        this.world.wake(this.body);
+    }
+}

package/dist/physics/damageZones.d.ts

@@ -0,0 +1,56 @@
+import type { CollisionEvent } from "./physicsWorld.js";
+export interface DamageZoneDef {
+    id: string;
+    thresholds: readonly number[];
+    detachStage?: number;
+}
+export interface DamageZoneState {
+    id: string;
+    accumulated: number;
+    stage: number;
+    detached: boolean;
+}
+export interface DamageTransition {
+    zone: string;
+    stage: number;
+    previousStage: number;
+    detached: boolean;
+    disabled: boolean;
+    accumulated: number;
+    total: number;
+}
+export interface DamageModelConfig {
+    zones: readonly DamageZoneDef[];
+    disableAt?: number;
+    onStage?: (transition: DamageTransition) => void;
+    onDetach?: (zoneId: string, accumulated: number) => void;
+}
+/**
+ * Coarse crash-damage model (issue #86 — stages, not soft-body). Each zone accumulates contact impulse
+ * fed from G3's `onCollision` `CollisionEvent`; crossing a threshold bumps the zone to the next discrete
+ * stage (the caller swaps the visual/collider), an optional `detachStage` ejects a part as debris once,
+ * and a total-impulse `disableAt` flips the whole body to a disabled state. `absorb` returns a transition
+ * only when something actually changed, so it doubles as the event source for HUD/feed.
+ */
+export declare class DamageModel {
+    private readonly zones;
+    private readonly order;
+    private readonly disableAt;
+    private readonly onStage?;
+    private readonly onDetach?;
+    private totalImpulse;
+    private disabledFlag;
+    constructor(config: DamageModelConfig);
+    get total(): number;
+    get disabled(): boolean;
+    stageOf(zoneId: string): number;
+    states(): readonly DamageZoneState[];
+    absorb(zoneId: string, impulse: number): DamageTransition | null;
+    /**
+     * Route a raw {@link CollisionEvent} into a zone by a caller-supplied selector (front/rear/side from
+     * `nx`/`nz`, or which body index took the hit). The event's `impulse` feeds `absorb`.
+     */
+    routeCollision(event: CollisionEvent, resolveZone: (event: CollisionEvent) => string | null): DamageTransition | null;
+    reset(): void;
+}
+export declare function createDamageModel(config: DamageModelConfig): DamageModel;

package/dist/physics/damageZones.js

@@ -0,0 +1,107 @@
+function stageFor(thresholds, accumulated) {
+    let stage = 0;
+    for (const t of thresholds) {
+        if (accumulated >= t)
+            stage += 1;
+        else
+            break;
+    }
+    return stage;
+}
+/**
+ * Coarse crash-damage model (issue #86 — stages, not soft-body). Each zone accumulates contact impulse
+ * fed from G3's `onCollision` `CollisionEvent`; crossing a threshold bumps the zone to the next discrete
+ * stage (the caller swaps the visual/collider), an optional `detachStage` ejects a part as debris once,
+ * and a total-impulse `disableAt` flips the whole body to a disabled state. `absorb` returns a transition
+ * only when something actually changed, so it doubles as the event source for HUD/feed.
+ */
+export class DamageModel {
+    zones = new Map();
+    order = [];
+    disableAt;
+    onStage;
+    onDetach;
+    totalImpulse = 0;
+    disabledFlag = false;
+    constructor(config) {
+        for (const def of config.zones) {
+            this.zones.set(def.id, { def, state: { id: def.id, accumulated: 0, stage: 0, detached: false } });
+            this.order.push(def.id);
+        }
+        this.disableAt = config.disableAt ?? null;
+        this.onStage = config.onStage;
+        this.onDetach = config.onDetach;
+    }
+    get total() {
+        return this.totalImpulse;
+    }
+    get disabled() {
+        return this.disabledFlag;
+    }
+    stageOf(zoneId) {
+        return this.zones.get(zoneId)?.state.stage ?? 0;
+    }
+    states() {
+        return this.order.map((id) => {
+            const s = this.zones.get(id).state;
+            return { id: s.id, accumulated: s.accumulated, stage: s.stage, detached: s.detached };
+        });
+    }
+    absorb(zoneId, impulse) {
+        const entry = this.zones.get(zoneId);
+        if (entry === undefined || impulse <= 0)
+            return null;
+        const { def, state } = entry;
+        const previousStage = state.stage;
+        const wasDisabled = this.disabledFlag;
+        state.accumulated += impulse;
+        this.totalImpulse += impulse;
+        state.stage = stageFor(def.thresholds, state.accumulated);
+        let detachedNow = false;
+        if (def.detachStage !== undefined &&
+            !state.detached &&
+            state.stage >= def.detachStage) {
+            state.detached = true;
+            detachedNow = true;
+            this.onDetach?.(zoneId, state.accumulated);
+        }
+        if (this.disableAt !== null && this.totalImpulse >= this.disableAt)
+            this.disabledFlag = true;
+        const changed = state.stage !== previousStage || detachedNow || this.disabledFlag !== wasDisabled;
+        if (!changed)
+            return null;
+        const transition = {
+            zone: zoneId,
+            stage: state.stage,
+            previousStage,
+            detached: state.detached,
+            disabled: this.disabledFlag,
+            accumulated: state.accumulated,
+            total: this.totalImpulse,
+        };
+        this.onStage?.(transition);
+        return transition;
+    }
+    /**
+     * Route a raw {@link CollisionEvent} into a zone by a caller-supplied selector (front/rear/side from
+     * `nx`/`nz`, or which body index took the hit). The event's `impulse` feeds `absorb`.
+     */
+    routeCollision(event, resolveZone) {
+        const zone = resolveZone(event);
+        if (zone === null)
+            return null;
+        return this.absorb(zone, Math.abs(event.impulse));
+    }
+    reset() {
+        for (const { state } of this.zones.values()) {
+            state.accumulated = 0;
+            state.stage = 0;
+            state.detached = false;
+        }
+        this.totalImpulse = 0;
+        this.disabledFlag = false;
+    }
+}
+export function createDamageModel(config) {
+    return new DamageModel(config);
+}

package/dist/physics/forceVolume.d.ts

@@ -0,0 +1,48 @@
+import type { PhysicsBounds, PhysicsWorld } from "./physicsWorld.js";
+export type ForceMode = "impulse" | "velocity" | "accelerate";
+export interface ForceVolumeConfig {
+    /** Region a body's center must be inside to be affected. */
+    bounds: PhysicsBounds;
+    /** `impulse` adds to velocity, `velocity` sets it, `accelerate` adds force·dt each tick. */
+    force: readonly [number, number, number];
+    /** Default `impulse`. */
+    mode?: ForceMode;
+    /** Fire only when a body first enters (boost pad) rather than every tick inside (fan/wind). Default false. */
+    once?: boolean;
+}
+/**
+ * A trigger region that pushes bodies passing through it — boost pads (`impulse` + `once`),
+ * conveyors (`velocity`), fans/wind (`accelerate`). Call `apply` each tick; `once` mode fires only
+ * on entry by tracking membership between ticks.
+ */
+export declare class ForceVolume {
+    readonly bounds: PhysicsBounds;
+    readonly mode: ForceMode;
+    readonly once: boolean;
+    private readonly fx;
+    private readonly fy;
+    private readonly fz;
+    private members;
+    private nextMembers;
+    constructor(config: ForceVolumeConfig);
+    apply(world: PhysicsWorld, dt: number): void;
+}
+export interface PlatformCarryConfig {
+    /** Vertical gap between a rider's base and the platform top counted as "standing on". Default 0.12. */
+    contactTolerance?: number;
+}
+/**
+ * Carries bodies standing on a moving platform by composing their transform with the platform's
+ * per-`step` delta — moving/rotating lifts and conveyor floors (Fall Guys, Gang Beasts). The
+ * platform is a body the game repositions each frame; riders are detected by overlap on its top face.
+ */
+export declare class PlatformCarry {
+    private readonly world;
+    private readonly platform;
+    private readonly tolerance;
+    private prevX;
+    private prevY;
+    private prevZ;
+    constructor(world: PhysicsWorld, platform: number, config?: PlatformCarryConfig);
+    step(): void;
+}

package/dist/physics/forceVolume.js

@@ -0,0 +1,119 @@
+function inside(bounds, x, y, z) {
+    return (x >= bounds.min[0] &&
+        x <= bounds.max[0] &&
+        y >= bounds.min[1] &&
+        y <= bounds.max[1] &&
+        z >= bounds.min[2] &&
+        z <= bounds.max[2]);
+}
+/**
+ * A trigger region that pushes bodies passing through it — boost pads (`impulse` + `once`),
+ * conveyors (`velocity`), fans/wind (`accelerate`). Call `apply` each tick; `once` mode fires only
+ * on entry by tracking membership between ticks.
+ */
+export class ForceVolume {
+    bounds;
+    mode;
+    once;
+    fx;
+    fy;
+    fz;
+    members = new Set();
+    nextMembers = new Set();
+    constructor(config) {
+        this.bounds = config.bounds;
+        this.mode = config.mode ?? "impulse";
+        this.once = config.once ?? false;
+        this.fx = config.force[0];
+        this.fy = config.force[1];
+        this.fz = config.force[2];
+    }
+    apply(world, dt) {
+        const next = this.nextMembers;
+        next.clear();
+        const high = world.highWater;
+        for (let i = 0; i < high; i += 1) {
+            if (world.invMass[i] === 0)
+                continue;
+            if (!inside(this.bounds, world.posX[i], world.posY[i], world.posZ[i]))
+                continue;
+            const wasInside = this.members.has(i);
+            next.add(i);
+            if (this.once && wasInside)
+                continue;
+            switch (this.mode) {
+                case "velocity":
+                    world.velX[i] = this.fx;
+                    world.velY[i] = this.fy;
+                    world.velZ[i] = this.fz;
+                    break;
+                case "accelerate":
+                    world.velX[i] += this.fx * dt;
+                    world.velY[i] += this.fy * dt;
+                    world.velZ[i] += this.fz * dt;
+                    break;
+                default:
+                    world.velX[i] += this.fx;
+                    world.velY[i] += this.fy;
+                    world.velZ[i] += this.fz;
+            }
+            world.wake(i);
+        }
+        this.nextMembers = this.members;
+        this.members = next;
+    }
+}
+/**
+ * Carries bodies standing on a moving platform by composing their transform with the platform's
+ * per-`step` delta — moving/rotating lifts and conveyor floors (Fall Guys, Gang Beasts). The
+ * platform is a body the game repositions each frame; riders are detected by overlap on its top face.
+ */
+export class PlatformCarry {
+    world;
+    platform;
+    tolerance;
+    prevX;
+    prevY;
+    prevZ;
+    constructor(world, platform, config = {}) {
+        this.world = world;
+        this.platform = platform;
+        this.tolerance = config.contactTolerance ?? 0.12;
+        this.prevX = world.posX[platform];
+        this.prevY = world.posY[platform];
+        this.prevZ = world.posZ[platform];
+    }
+    step() {
+        const w = this.world;
+        const p = this.platform;
+        const dx = w.posX[p] - this.prevX;
+        const dy = w.posY[p] - this.prevY;
+        const dz = w.posZ[p] - this.prevZ;
+        const topY = this.prevY + w.halfY[p];
+        const px = this.prevX;
+        const pz = this.prevZ;
+        this.prevX = w.posX[p];
+        this.prevY = w.posY[p];
+        this.prevZ = w.posZ[p];
+        if (dx === 0 && dy === 0 && dz === 0)
+            return;
+        const hx = w.halfX[p];
+        const hz = w.halfZ[p];
+        const high = w.highWater;
+        for (let i = 0; i < high; i += 1) {
+            if (i === p || !w.isAlive(i))
+                continue;
+            const base = w.posY[i] - w.halfY[i];
+            if (base < topY - this.tolerance || base > topY + this.tolerance)
+                continue;
+            if (Math.abs(w.posX[i] - px) > hx + w.halfX[i])
+                continue;
+            if (Math.abs(w.posZ[i] - pz) > hz + w.halfZ[i])
+                continue;
+            w.posX[i] += dx;
+            w.posY[i] += dy;
+            w.posZ[i] += dz;
+            w.wake(i);
+        }
+    }
+}

package/dist/physics/physicsWorld.d.ts

@@ -35,6 +35,10 @@ export interface PhysicsWorldConfig {
     sleepThresholdSteps?: number;
     /** Approach speed a contact must exceed to wake a sleeping body (resting contacts don't). Default 0.5. */
     wakeThreshold?: number;
+    /** Maximum simultaneous joints the constraint buffers can hold. Default 256. */
+    jointCapacity?: number;
+    /** Baumgarte fraction applied to hard-joint positional error per iteration, 0..1. Default 0.5. */
+    jointCorrection?: number;
 }
 export interface PhysicsStats {
     count: number;
@@ -45,9 +49,8 @@ export interface PhysicsStats {
     substeps: number;
     stepMs: number;
 }
-export interface AddBodyOptions {
+export interface BodyCommonOptions {
     position: readonly [number, number, number];
-    halfExtents: readonly [number, number, number];
     velocity?: readonly [number, number, number];
     /** ≤ 0 or omitted with `static` → infinite mass (immovable collider). Default 1. */
     mass?: number;
@@ -56,6 +59,56 @@ export interface AddBodyOptions {
     /** Seed the body asleep (a settled bed pays no integration cost until woken). */
     asleep?: boolean;
 }
+export interface BoxBodyOptions extends BodyCommonOptions {
+    shape?: "box";
+    halfExtents: readonly [number, number, number];
+}
+/** The radius fills all three half-extent columns, so broadphase and bounds see the sphere's enclosing AABB. */
+export interface SphereBodyOptions extends BodyCommonOptions {
+    shape: "sphere";
+    radius: number;
+}
+export type AddBodyOptions = BoxBodyOptions | SphereBodyOptions;
+export declare const SHAPE_BOX = 0;
+export declare const SHAPE_SPHERE = 1;
+/**
+ * `hinge`/`fixed`/`distance` are hard bilateral constraints; `spring` is a soft PD constraint.
+ * No angular state → `hinge`/`fixed` both pin the shared anchor (`axis` is metadata), `distance`
+ * holds a fixed separation, `spring` drives toward `restLength` (suspension, follow-point carry).
+ */
+export type JointKind = "hinge" | "distance" | "spring" | "fixed";
+export interface JointOptions {
+    /** First body index. */
+    bodyA: number;
+    /** Second body index, or omit / < 0 to anchor A to a fixed world point (`anchorB`). */
+    bodyB?: number;
+    /** Local offset of the anchor on A, in world axes (no rotation). Default [0,0,0]. */
+    anchorA?: readonly [number, number, number];
+    /** Local offset on B, or — when B is a world anchor — the world point itself. Default [0,0,0]. */
+    anchorB?: readonly [number, number, number];
+    /** Target separation for `distance`/`spring`. Defaults to the anchors' current distance. */
+    restLength?: number;
+    /** Spring restoring rate. Default 40. */
+    stiffness?: number;
+    /** Spring damping (relative-velocity bleed). Default 6. */
+    damping?: number;
+    /** Clamp on the per-substep spring impulse (a follow-point that never yanks). Default unbounded. */
+    maxImpulse?: number;
+    /** Hinge axis, retained as metadata (this sim has no angular DOF). */
+    axis?: readonly [number, number, number];
+}
+/** A contact reported to `onCollision`. The object is reused each call — read/copy, never retain. */
+export interface CollisionEvent {
+    a: number;
+    b: number;
+    nx: number;
+    ny: number;
+    nz: number;
+    approachSpeed: number;
+    impulse: number;
+}
+/** Cap on `nx*ny*nz` broadphase cells — guards a huge-bounds/tiny-cellSize config from hanging `step()`. */
+export declare const MAX_BROADPHASE_CELLS = 1000000;
 /** Grid cell containing a point, clamped into the grid. Pure — exported for tests. */
 export declare function cellCoord(value: number, min: number, cellSize: number, cells: number): number;
 /** Linear cell index from clamped 3D coords. Pure — exported for tests. */
@@ -77,6 +130,8 @@ export declare class PhysicsWorld {
     readonly sleepMove2: number;
     readonly sleepSteps: number;
     readonly wakeThreshold: number;
+    readonly jointCapacity: number;
+    readonly jointCorrection: number;
     readonly posX: Float32Array;
     readonly posY: Float32Array;
     readonly posZ: Float32Array;
@@ -88,6 +143,8 @@ export declare class PhysicsWorld {
     readonly halfZ: Float32Array;
     readonly invMass: Float32Array;
     readonly flags: Uint8Array;
+    /** `SHAPE_BOX` (0) or `SHAPE_SPHERE` (1) per body; spheres keep their radius in halfX/halfY/halfZ. */
+    readonly shape: Uint8Array;
     /** 1 for a body that took part in a contact this frame; reset each `step()`. Render tint reads this. */
     readonly contact: Uint8Array;
     private readonly sleepTimer;
@@ -105,6 +162,30 @@ export declare class PhysicsWorld {
     private readonly awakeList;
     private readonly awakeSlot;
     private awakeCount;
+    private readonly jSpring;
+    private readonly jActive;
+    private readonly jBodyA;
+    private readonly jBodyB;
+    private readonly jAnchorAX;
+    private readonly jAnchorAY;
+    private readonly jAnchorAZ;
+    private readonly jAnchorBX;
+    private readonly jAnchorBY;
+    private readonly jAnchorBZ;
+    private readonly jRest;
+    private readonly jStiffness;
+    private readonly jDamping;
+    private readonly jMaxImpulse;
+    private readonly jFree;
+    private jFreeCount;
+    private jointHigh;
+    private jointActiveCount;
+    private readonly bodyFree;
+    private bodyFreeCount;
+    private bodyHigh;
+    private collisionListener;
+    private collisionMinSpeed;
+    private readonly collisionEvent;
     private bodyCount;
     private accumulator;
     private readonly stats;
@@ -112,15 +193,55 @@ export declare class PhysicsWorld {
     private addAwake;
     private removeAwake;
     get count(): number;
+    /** One past the highest slot `addBody` has ever handed out — the range `removeBody` leaves holes in. */
+    get highWater(): number;
     get cells(): {
         nx: number;
         ny: number;
         nz: number;
         total: number;
     };
+    get jointCount(): number;
+    /**
+     * Deliver every impacting contact (approach speed ≥ `minApproachSpeed`) to `listener` during
+     * `step`. The event object is reused — read/copy it, never retain. Pass `null` to detach. This is
+     * the seam crash-damage and destruction read; contacts otherwise stay inside the sim.
+     */
+    onCollision(listener: ((e: CollisionEvent) => void) | null, minApproachSpeed?: number): void;
+    hingeJoint(options: JointOptions): number;
+    fixedJoint(options: JointOptions): number;
+    distanceJoint(options: JointOptions): number;
+    springJoint(options: JointOptions): number;
+    private addJoint;
+    removeJoint(id: number): void;
+    /** Move a joint's world anchor point (only meaningful when `bodyB` is a world anchor). */
+    setJointAnchor(id: number, x: number, y: number, z: number): void;
+    /** Move a joint's local anchor offset on A (world axes, no rotation applied by the solver). */
+    setJointAnchorA(id: number, x: number, y: number, z: number): void;
+    setJointRest(id: number, restLength: number): void;
+    private jointDistance;
+    /** Write [ax,ay,az,bx,by,bz] world endpoints per active joint into `out`; returns the joint count. */
+    readJointSegments(out: Float32Array): number;
     addBody(options: AddBodyOptions): number;
+    /**
+     * Remove a body: it drops out of integration, the solver, and the broadphase, and its slot is
+     * queued for the next `addBody` to reuse. `id` and every other body's `id` stay valid — a dead
+     * slot is tombstoned (`FLAG_DEAD`), never swapped, since ids are handed out raw and stored as-is
+     * in joints and game state. There is no persistent contact set to consult, so — conservatively —
+     * any sleeping body whose AABB touches the removed body's (padded by `slop`) is woken; a body
+     * that was resting on it always qualifies.
+     */
+    removeBody(id: number): void;
+    private wakeTouching;
     isSleeping(i: number): boolean;
+    isAlive(i: number): boolean;
     wake(i: number): void;
+    /** Overwrite a body's velocity directly, waking it if asleep. */
+    setVelocity(id: number, x: number, y: number, z: number): void;
+    /** Move a body, keeping its current velocity, and wake it if asleep. */
+    setPosition(id: number, x: number, y: number, z: number): void;
+    /** Move a body and zero its velocity — a hard reset (respawn, teleporter) instead of a slide. */
+    teleport(id: number, x: number, y: number, z: number): void;
     wakeAll(): void;
     clear(): void;
     /** Advance by a real frame delta; runs whole fixed substeps and carries the remainder. */
@@ -132,5 +253,6 @@ export declare class PhysicsWorld {
     private cellOf;
     private solve;
     private resolve;
+    private solveJoints;
     private updateSleep;
 }