@jgengine/core 0.6.0 → 0.7.0

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 count = world.count;
+        for (let i = 0; i < count; 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 count = w.count;
+        for (let i = 0; i < count; i += 1) {
+            if (i === p)
+                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;
@@ -56,6 +60,42 @@ export interface AddBodyOptions {
     /** Seed the body asleep (a settled bed pays no integration cost until woken). */
     asleep?: boolean;
 }
+/**
+ * `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;
+}
 /** 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 +117,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;
@@ -105,6 +147,27 @@ 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 collisionListener;
+    private collisionMinSpeed;
+    private readonly collisionEvent;
     private bodyCount;
     private accumulator;
     private readonly stats;
@@ -118,6 +181,25 @@ export declare class PhysicsWorld {
         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;
+    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;
     isSleeping(i: number): boolean;
     wake(i: number): void;
@@ -132,5 +214,6 @@ export declare class PhysicsWorld {
     private cellOf;
     private solve;
     private resolve;
+    private solveJoints;
     private updateSleep;
 }