@jgengine/core 0.7.0 → 0.8.0

package/dist/nav/navGrid.d.ts

@@ -15,6 +15,8 @@ export interface FindPathOptions {
     smooth?: boolean;
     /** Diameter of the mover in world units — blocks cells within this margin of an obstacle. Default 0. */
     clearance?: number;
+    /** Multiplier (>=1) applied to the base cost of stepping from one cell center to a neighbour's. Use to penalize slopes, terrain, etc. */
+    stepCost?: (from: NavPoint, to: NavPoint) => number;
 }
 export interface NavGrid {
     readonly cols: number;
@@ -42,5 +44,13 @@ export declare function createNavGrid(config: NavGridConfig): NavGrid;
  * the nearest walkable cell so a click on an obstacle still routes to its edge.
  */
 export declare function findPath(grid: NavGrid, from: NavPoint, to: NavPoint, options?: FindPathOptions): NavPoint[] | null;
+/**
+ * `FindPathOptions.stepCost` factory that penalizes steep terrain: cost is
+ * `1 + weight * |Δheight| / horizontalDistance`, so with the default weight a
+ * 45° slope roughly doubles the step cost.
+ */
+export declare function slopeStepCost(field: {
+    sampleHeight(x: number, z: number): number;
+}, weight?: number): (from: NavPoint, to: NavPoint) => number;
 /** Remove waypoints the mover can skip because it has clear line-of-sight past them. */
 export declare function smoothPath(grid: NavGrid, points: readonly NavPoint[]): NavPoint[];

package/dist/nav/navGrid.js

@@ -149,6 +149,7 @@ function withClearance(grid, clearance) {
  */
 export function findPath(grid, from, to, options = {}) {
     const passable = withClearance(grid, options.clearance ?? 0);
+    const stepCost = options.stepCost;
     const startCell = grid.cellAt(from);
     const goalCell = grid.cellAt(to);
     const start = passable(startCell.col, startCell.row) ? startCell : grid.nearestWalkable(from);
@@ -209,7 +210,8 @@ export function findPath(grid, from, to, options = {}) {
             const nKey = keyOf(nc, nr);
             if (closed.has(nKey))
                 continue;
-            const tentative = g + step;
+            const multiplier = stepCost === undefined ? 1 : Math.max(1, stepCost(grid.center(col, row), grid.center(nc, nr)));
+            const tentative = g + step * multiplier;
             if (tentative < (gScore.get(nKey) ?? Number.POSITIVE_INFINITY)) {
                 gScore.set(nKey, tentative);
                 cameFrom.set(nKey, current.key);
@@ -231,6 +233,21 @@ export function findPath(grid, from, to, options = {}) {
         raw[raw.length - 1] = [to[0], to[1]];
     return options.smooth === false ? raw : smoothPath(grid, raw);
 }
+const DEFAULT_SLOPE_STEP_WEIGHT = 1;
+/**
+ * `FindPathOptions.stepCost` factory that penalizes steep terrain: cost is
+ * `1 + weight * |Δheight| / horizontalDistance`, so with the default weight a
+ * 45° slope roughly doubles the step cost.
+ */
+export function slopeStepCost(field, weight = DEFAULT_SLOPE_STEP_WEIGHT) {
+    return (from, to) => {
+        const horizontal = Math.hypot(to[0] - from[0], to[1] - from[1]);
+        if (horizontal < 1e-6)
+            return 1;
+        const rise = field.sampleHeight(to[0], to[1]) - field.sampleHeight(from[0], from[1]);
+        return 1 + (weight * Math.abs(rise)) / horizontal;
+    };
+}
 /** Remove waypoints the mover can skip because it has clear line-of-sight past them. */
 export function smoothPath(grid, points) {
     if (points.length <= 2)

package/dist/nav/pathFollow.d.ts

@@ -17,8 +17,10 @@ export interface PathFollowState {
     /** Total world-distance covered so far — drives progress/leak logic in tower defense. */
     distanceTravelled: number;
 }
-/** Lift an A* / navmesh `[x, z]` polyline onto a `y` plane for a path-follower. */
-export declare function pathFromNav(points: readonly NavPoint[], y?: number): Waypoint[];
+export interface HeightSampler {
+    sampleHeight(x: number, z: number): number;
+}
+export declare function pathFromNav(points: readonly NavPoint[], elevation?: number | HeightSampler, offset?: number): Waypoint[];
 export declare function createPathFollow(config: PathFollowConfig): PathFollowState;
 /**
  * Advance a path-follower by `speed * dt` along its authored polyline. Pure — returns

package/dist/nav/pathFollow.js

@@ -1,6 +1,8 @@
-/** Lift an A* / navmesh `[x, z]` polyline onto a `y` plane for a path-follower. */
-export function pathFromNav(points, y = 0) {
-    return points.map((point) => [point[0], y, point[1]]);
+export function pathFromNav(points, elevation = 0, offset = 0) {
+    if (typeof elevation === "number") {
+        return points.map((point) => [point[0], elevation + offset, point[1]]);
+    }
+    return points.map((point) => [point[0], elevation.sampleHeight(point[0], point[1]) + offset, point[1]]);
 }
 export function createPathFollow(config) {
     const first = config.waypoints[0];

package/dist/physics/ballisticSweep.d.ts

@@ -0,0 +1,18 @@
+import type { PhysicsWorld } from "./physicsWorld.js";
+export interface BallisticSweepHit {
+    point: [number, number, number];
+    time: number;
+}
+export type BallisticSweep = (origin: readonly [number, number, number], velocity: readonly [number, number, number], gravity: number, maxTime: number) => BallisticSweepHit | null;
+export interface BallisticSweepOptions {
+    /** Fixed march interval along the arc, in seconds. Default 1/60. */
+    step?: number;
+    /** Projectile radius; each body AABB is inflated by this before the point test. Default 0. */
+    radius?: number;
+}
+/**
+ * Marches the closed-form arc (constant gravity, straight lateral) through `world` and reports the
+ * first sample inside any live body's AABB — sleeping bodies included — refined by one bisection
+ * between the last clear sample and the hit sample. Returns `null` when the whole arc is clear.
+ */
+export declare function createBallisticSweep(world: PhysicsWorld, options?: BallisticSweepOptions): BallisticSweep;

package/dist/physics/ballisticSweep.js

@@ -0,0 +1,49 @@
+const DEFAULT_SWEEP_STEP = 1 / 60;
+/**
+ * Marches the closed-form arc (constant gravity, straight lateral) through `world` and reports the
+ * first sample inside any live body's AABB — sleeping bodies included — refined by one bisection
+ * between the last clear sample and the hit sample. Returns `null` when the whole arc is clear.
+ */
+export function createBallisticSweep(world, options = {}) {
+    const step = options.step ?? DEFAULT_SWEEP_STEP;
+    const radius = options.radius ?? 0;
+    function overlapsAnyBody(x, y, z) {
+        for (let i = 0; i < world.highWater; i += 1) {
+            if (!world.isAlive(i))
+                continue;
+            if (Math.abs(x - world.posX[i]) > world.halfX[i] + radius)
+                continue;
+            if (Math.abs(y - world.posY[i]) > world.halfY[i] + radius)
+                continue;
+            if (Math.abs(z - world.posZ[i]) > world.halfZ[i] + radius)
+                continue;
+            return true;
+        }
+        return false;
+    }
+    return (origin, velocity, gravity, maxTime) => {
+        const pointAt = (t) => [
+            origin[0] + velocity[0] * t,
+            origin[1] + velocity[1] * t - 0.5 * gravity * t * t,
+            origin[2] + velocity[2] * t,
+        ];
+        let lastClear = 0;
+        let t = 0;
+        for (;;) {
+            const sample = pointAt(t);
+            if (overlapsAnyBody(sample[0], sample[1], sample[2])) {
+                if (t === 0)
+                    return { point: sample, time: 0 };
+                const mid = (lastClear + t) / 2;
+                const midSample = pointAt(mid);
+                return overlapsAnyBody(midSample[0], midSample[1], midSample[2])
+                    ? { point: midSample, time: mid }
+                    : { point: sample, time: t };
+            }
+            if (t >= maxTime)
+                return null;
+            lastClear = t;
+            t = Math.min(t + step, maxTime);
+        }
+    };
+}

package/dist/physics/forceVolume.js

@@ -31,8 +31,8 @@ export class ForceVolume {
     apply(world, dt) {
         const next = this.nextMembers;
         next.clear();
-        const count = world.count;
-        for (let i = 0; i < count; i += 1) {
+        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]))
@@ -99,9 +99,9 @@ export class PlatformCarry {
             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)
+        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)

package/dist/physics/physicsWorld.d.ts

@@ -49,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;
@@ -60,6 +59,18 @@ 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`
@@ -96,6 +107,8 @@ export interface CollisionEvent {
     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. */
@@ -130,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;
@@ -165,6 +180,9 @@ export declare class PhysicsWorld {
     private jFreeCount;
     private jointHigh;
     private jointActiveCount;
+    private readonly bodyFree;
+    private bodyFreeCount;
+    private bodyHigh;
     private collisionListener;
     private collisionMinSpeed;
     private readonly collisionEvent;
@@ -175,6 +193,8 @@ 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;
@@ -196,13 +216,32 @@ export declare class PhysicsWorld {
     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. */