@jgengine/core 0.5.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

@@ -0,0 +1,219 @@
+export interface PhysicsBounds {
+    min: readonly [number, number, number];
+    max: readonly [number, number, number];
+}
+export interface PhysicsWorldConfig {
+    /** Maximum bodies the SoA buffers can hold. Fixed at construction; no reallocation later. */
+    capacity: number;
+    /** AABB container; every body is constrained inside it (floor included). */
+    bounds: PhysicsBounds;
+    /** Downward acceleration applied to awake bodies each substep. Default -20. */
+    gravity?: number;
+    /** Broadphase cell edge; tune to ≈ small-body diameter. Default 1. */
+    cellSize?: number;
+    /** Fixed substep length in seconds. Default 1/60. */
+    fixedDt?: number;
+    /** Cap on substeps per `step()` — bounds catch-up work, drops the rest. Default 4. */
+    maxSubsteps?: number;
+    /** Bounce factor on contacts and walls, 0..1. Default 0.2. */
+    restitution?: number;
+    /** Approach speed below which restitution is ignored (contacts rest instead of jittering). Default 1. */
+    restitutionThreshold?: number;
+    /** Coulomb friction coefficient on contacts and the floor, 0..1. Default 0.4. */
+    friction?: number;
+    /** Per-second linear velocity damping (physical energy bleed so piles settle and sleep). Default 0.2. */
+    linearDamping?: number;
+    /** Sequential-impulse velocity iterations per substep (higher = more stable stacks). Default 4. */
+    solverIterations?: number;
+    /** Baumgarte positional-correction fraction per substep, 0..1. Default 0.2. */
+    correctionFactor?: number;
+    /** Penetration tolerated before correction kicks in. Default 0.005. */
+    slop?: number;
+    /** Speed at or below which a body counts as still. Default 0.08. */
+    sleepLinearVelocity?: number;
+    /** Consecutive still substeps before a body sleeps. Default 30. */
+    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;
+    awake: number;
+    sleeping: number;
+    contacts: number;
+    pairs: number;
+    substeps: number;
+    stepMs: number;
+}
+export interface AddBodyOptions {
+    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;
+    /** Immovable collider: never integrates, never sleeps-out, invMass 0. */
+    static?: boolean;
+    /** 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. */
+export declare function cellIndex(cx: number, cy: number, cz: number, nx: number, ny: number): number;
+export declare class PhysicsWorld {
+    readonly capacity: number;
+    readonly bounds: PhysicsBounds;
+    readonly gravity: number;
+    readonly cellSize: number;
+    readonly fixedDt: number;
+    readonly maxSubsteps: number;
+    readonly restitution: number;
+    readonly restitutionThreshold: number;
+    readonly friction: number;
+    readonly linearDamping: number;
+    readonly solverIterations: number;
+    readonly correctionFactor: number;
+    readonly slop: number;
+    readonly sleepMove2: number;
+    readonly sleepSteps: number;
+    readonly wakeThreshold: number;
+    readonly jointCapacity: number;
+    readonly jointCorrection: number;
+    readonly posX: Float32Array;
+    readonly posY: Float32Array;
+    readonly posZ: Float32Array;
+    readonly velX: Float32Array;
+    readonly velY: Float32Array;
+    readonly velZ: Float32Array;
+    readonly halfX: Float32Array;
+    readonly halfY: Float32Array;
+    readonly halfZ: Float32Array;
+    readonly invMass: Float32Array;
+    readonly flags: 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;
+    private readonly prevX;
+    private readonly prevY;
+    private readonly prevZ;
+    private readonly nx;
+    private readonly ny;
+    private readonly nz;
+    private readonly numCells;
+    private readonly cellStart;
+    private readonly cursor;
+    private readonly sorted;
+    private readonly bodyCell;
+    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;
+    constructor(config: PhysicsWorldConfig);
+    private addAwake;
+    private removeAwake;
+    get count(): 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;
+    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;
+    wakeAll(): void;
+    clear(): void;
+    /** Advance by a real frame delta; runs whole fixed substeps and carries the remainder. */
+    step(frameDt: number): PhysicsStats;
+    getStats(): PhysicsStats;
+    private substep;
+    private constrainBounds;
+    private buildGrid;
+    private cellOf;
+    private solve;
+    private resolve;
+    private solveJoints;
+    private updateSleep;
+}