@jgengine/core 0.7.0 → 0.8.0

package/dist/physics/physicsWorld.js

@@ -1,5 +1,10 @@
+export const SHAPE_BOX = 0;
+export const SHAPE_SPHERE = 1;
 const FLAG_SLEEPING = 1;
 const FLAG_STATIC = 2;
+const FLAG_DEAD = 4;
+/** Cap on `nx*ny*nz` broadphase cells — guards a huge-bounds/tiny-cellSize config from hanging `step()`. */
+export const MAX_BROADPHASE_CELLS = 1_000_000;
 /** Grid cell containing a point, clamped into the grid. Pure — exported for tests. */
 export function cellCoord(value, min, cellSize, cells) {
     const raw = Math.floor((value - min) / cellSize);
@@ -39,6 +44,8 @@ export class PhysicsWorld {
     halfZ;
     invMass;
     flags;
+    /** `SHAPE_BOX` (0) or `SHAPE_SPHERE` (1) per body; spheres keep their radius in halfX/halfY/halfZ. */
+    shape;
     /** 1 for a body that took part in a contact this frame; reset each `step()`. Render tint reads this. */
     contact;
     sleepTimer;
@@ -76,6 +83,12 @@ export class PhysicsWorld {
     jFreeCount = 0;
     jointHigh = 0;
     jointActiveCount = 0;
+    // Removed bodies tombstone (FLAG_DEAD) rather than compact: `id` is the SoA slot itself, handed
+    // out to callers and stored raw in joints/game state, so a slot can never move once allocated.
+    // `bodyHigh` is the high-water mark of ever-used slots; `bodyFree` recycles dead ones for addBody.
+    bodyFree;
+    bodyFreeCount = 0;
+    bodyHigh = 0;
     collisionListener = null;
     collisionMinSpeed = 0;
     collisionEvent = {
@@ -131,6 +144,7 @@ export class PhysicsWorld {
         this.halfZ = new Float32Array(cap);
         this.invMass = new Float32Array(cap);
         this.flags = new Uint8Array(cap);
+        this.shape = new Uint8Array(cap);
         this.contact = new Uint8Array(cap);
         this.sleepTimer = new Uint16Array(cap);
         this.prevX = new Float32Array(cap);
@@ -141,12 +155,18 @@ export class PhysicsWorld {
         this.ny = Math.max(1, Math.ceil(span(1) / this.cellSize));
         this.nz = Math.max(1, Math.ceil(span(2) / this.cellSize));
         this.numCells = this.nx * this.ny * this.nz;
+        if (this.numCells > MAX_BROADPHASE_CELLS) {
+            throw new Error(`PhysicsWorld: broadphase grid too large (${this.nx}x${this.ny}x${this.nz} = ${this.numCells} cells, ` +
+                `cap ${MAX_BROADPHASE_CELLS}). bounds=[${config.bounds.min}]..[${config.bounds.max}] cellSize=${this.cellSize}; ` +
+                `raise cellSize or shrink bounds.`);
+        }
         this.cellStart = new Int32Array(this.numCells + 1);
         this.cursor = new Int32Array(this.numCells);
         this.sorted = new Int32Array(cap);
         this.bodyCell = new Int32Array(cap);
         this.awakeList = new Int32Array(cap);
         this.awakeSlot = new Int32Array(cap).fill(-1);
+        this.bodyFree = new Int32Array(cap);
         const jc = this.jointCapacity;
         this.jSpring = new Uint8Array(jc);
         this.jActive = new Uint8Array(jc);
@@ -184,6 +204,10 @@ export class PhysicsWorld {
     get count() {
         return this.bodyCount;
     }
+    /** One past the highest slot `addBody` has ever handed out — the range `removeBody` leaves holes in. */
+    get highWater() {
+        return this.bodyHigh;
+    }
     get cells() {
         return { nx: this.nx, ny: this.ny, nz: this.nz, total: this.numCells };
     }
@@ -254,6 +278,12 @@ export class PhysicsWorld {
         this.jAnchorBY[id] = y;
         this.jAnchorBZ[id] = z;
     }
+    /** Move a joint's local anchor offset on A (world axes, no rotation applied by the solver). */
+    setJointAnchorA(id, x, y, z) {
+        this.jAnchorAX[id] = x;
+        this.jAnchorAY[id] = y;
+        this.jAnchorAZ[id] = z;
+    }
     setJointRest(id, restLength) {
         this.jRest[id] = restLength;
     }
@@ -291,9 +321,16 @@ export class PhysicsWorld {
         return n;
     }
     addBody(options) {
-        if (this.bodyCount >= this.capacity)
-            throw new Error("PhysicsWorld: capacity exceeded");
-        const i = this.bodyCount++;
+        let i;
+        if (this.bodyFreeCount > 0) {
+            i = this.bodyFree[--this.bodyFreeCount];
+        }
+        else {
+            if (this.bodyHigh >= this.capacity)
+                throw new Error("PhysicsWorld: capacity exceeded");
+            i = this.bodyHigh++;
+        }
+        this.bodyCount += 1;
         this.posX[i] = options.position[0];
         this.posY[i] = options.position[1];
         this.posZ[i] = options.position[2];
@@ -301,9 +338,18 @@ export class PhysicsWorld {
         this.velX[i] = v?.[0] ?? 0;
         this.velY[i] = v?.[1] ?? 0;
         this.velZ[i] = v?.[2] ?? 0;
-        this.halfX[i] = options.halfExtents[0];
-        this.halfY[i] = options.halfExtents[1];
-        this.halfZ[i] = options.halfExtents[2];
+        if (options.shape === "sphere") {
+            this.halfX[i] = options.radius;
+            this.halfY[i] = options.radius;
+            this.halfZ[i] = options.radius;
+            this.shape[i] = SHAPE_SPHERE;
+        }
+        else {
+            this.halfX[i] = options.halfExtents[0];
+            this.halfY[i] = options.halfExtents[1];
+            this.halfZ[i] = options.halfExtents[2];
+            this.shape[i] = SHAPE_BOX;
+        }
         const isStatic = options.static === true;
         const mass = options.mass ?? 1;
         this.invMass[i] = isStatic || mass <= 0 ? 0 : 1 / mass;
@@ -314,17 +360,69 @@ export class PhysicsWorld {
             f |= FLAG_SLEEPING;
         this.flags[i] = f;
         this.sleepTimer[i] = 0;
+        this.contact[i] = 0;
         this.awakeSlot[i] = -1;
         this.bodyCell[i] = this.cellOf(i);
         if ((f & FLAG_SLEEPING) === 0)
             this.addAwake(i);
         return i;
     }
+    /**
+     * 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) {
+        if (id < 0 || id >= this.bodyHigh)
+            return;
+        if ((this.flags[id] & FLAG_DEAD) !== 0)
+            return;
+        this.wakeTouching(id);
+        this.removeAwake(id);
+        this.flags[id] = FLAG_DEAD;
+        this.invMass[id] = 0;
+        this.velX[id] = 0;
+        this.velY[id] = 0;
+        this.velZ[id] = 0;
+        this.sleepTimer[id] = 0;
+        this.contact[id] = 0;
+        this.bodyCount -= 1;
+        this.bodyFree[this.bodyFreeCount++] = id;
+    }
+    wakeTouching(id) {
+        const pad = this.slop + 0.01;
+        const minX = this.posX[id] - this.halfX[id] - pad;
+        const maxX = this.posX[id] + this.halfX[id] + pad;
+        const minY = this.posY[id] - this.halfY[id] - pad;
+        const maxY = this.posY[id] + this.halfY[id] + pad;
+        const minZ = this.posZ[id] - this.halfZ[id] - pad;
+        const maxZ = this.posZ[id] + this.halfZ[id] + pad;
+        for (let j = 0; j < this.bodyHigh; j += 1) {
+            if (j === id)
+                continue;
+            const fj = this.flags[j];
+            if ((fj & (FLAG_DEAD | FLAG_STATIC)) !== 0 || (fj & FLAG_SLEEPING) === 0)
+                continue;
+            if (this.posX[j] - this.halfX[j] > maxX || this.posX[j] + this.halfX[j] < minX)
+                continue;
+            if (this.posY[j] - this.halfY[j] > maxY || this.posY[j] + this.halfY[j] < minY)
+                continue;
+            if (this.posZ[j] - this.halfZ[j] > maxZ || this.posZ[j] + this.halfZ[j] < minZ)
+                continue;
+            this.wake(j);
+        }
+    }
     isSleeping(i) {
         return (this.flags[i] & FLAG_SLEEPING) !== 0;
     }
+    isAlive(i) {
+        return (this.flags[i] & FLAG_DEAD) === 0;
+    }
     wake(i) {
-        if ((this.flags[i] & FLAG_STATIC) !== 0)
+        if ((this.flags[i] & (FLAG_STATIC | FLAG_DEAD)) !== 0)
             return;
         this.flags[i] &= ~FLAG_SLEEPING;
         this.sleepTimer[i] = 0;
@@ -333,9 +431,40 @@ export class PhysicsWorld {
         this.prevZ[i] = this.posZ[i];
         this.addAwake(i);
     }
+    /** Overwrite a body's velocity directly, waking it if asleep. */
+    setVelocity(id, x, y, z) {
+        if ((this.flags[id] & FLAG_DEAD) !== 0)
+            return;
+        this.velX[id] = x;
+        this.velY[id] = y;
+        this.velZ[id] = z;
+        this.wake(id);
+    }
+    /** Move a body, keeping its current velocity, and wake it if asleep. */
+    setPosition(id, x, y, z) {
+        if ((this.flags[id] & FLAG_DEAD) !== 0)
+            return;
+        this.posX[id] = x;
+        this.posY[id] = y;
+        this.posZ[id] = z;
+        this.prevX[id] = x;
+        this.prevY[id] = y;
+        this.prevZ[id] = z;
+        this.bodyCell[id] = this.cellOf(id);
+        this.wake(id);
+    }
+    /** Move a body and zero its velocity — a hard reset (respawn, teleporter) instead of a slide. */
+    teleport(id, x, y, z) {
+        this.setPosition(id, x, y, z);
+        if ((this.flags[id] & FLAG_DEAD) !== 0)
+            return;
+        this.velX[id] = 0;
+        this.velY[id] = 0;
+        this.velZ[id] = 0;
+    }
     wakeAll() {
-        for (let i = 0; i < this.bodyCount; i += 1) {
-            if ((this.flags[i] & FLAG_STATIC) === 0) {
+        for (let i = 0; i < this.bodyHigh; i += 1) {
+            if ((this.flags[i] & (FLAG_STATIC | FLAG_DEAD)) === 0) {
                 this.flags[i] &= ~FLAG_SLEEPING;
                 this.sleepTimer[i] = 0;
                 this.addAwake(i);
@@ -344,6 +473,8 @@ export class PhysicsWorld {
     }
     clear() {
         this.bodyCount = 0;
+        this.bodyHigh = 0;
+        this.bodyFreeCount = 0;
         this.accumulator = 0;
         this.awakeCount = 0;
         this.jointHigh = 0;
@@ -360,7 +491,7 @@ export class PhysicsWorld {
         let substeps = 0;
         this.stats.contacts = 0;
         this.stats.pairs = 0;
-        this.contact.fill(0, 0, this.bodyCount);
+        this.contact.fill(0, 0, this.bodyHigh);
         while (this.accumulator >= this.fixedDt) {
             this.substep(this.fixedDt);
             this.accumulator -= this.fixedDt;
@@ -453,7 +584,7 @@ export class PhysicsWorld {
         }
     }
     buildGrid() {
-        const n = this.bodyCount;
+        const n = this.bodyHigh;
         const start = this.cellStart;
         start.fill(0);
         // Sleeping bodies never move, so their cell index is cached from addBody / their last awake
@@ -463,13 +594,19 @@ export class PhysicsWorld {
             const i = this.awakeList[a];
             this.bodyCell[i] = this.cellOf(i);
         }
-        for (let i = 0; i < n; i += 1)
+        // Dead slots (tombstoned by removeBody) sit inside [0, bodyHigh) but never enter the grid.
+        for (let i = 0; i < n; i += 1) {
+            if ((this.flags[i] & FLAG_DEAD) !== 0)
+                continue;
             start[this.bodyCell[i] + 1] += 1;
+        }
         for (let c = 0; c < this.numCells; c += 1) {
             start[c + 1] += start[c];
             this.cursor[c] = start[c];
         }
         for (let i = 0; i < n; i += 1) {
+            if ((this.flags[i] & FLAG_DEAD) !== 0)
+                continue;
             const c = this.bodyCell[i];
             this.sorted[this.cursor[c]++] = i;
         }
@@ -520,39 +657,94 @@ export class PhysicsWorld {
         }
     }
     resolve(i, j, restitutionPass, countPass) {
-        const dx = this.posX[j] - this.posX[i];
-        const px = this.halfX[i] + this.halfX[j] - Math.abs(dx);
-        if (px <= 0)
-            return;
-        const dy = this.posY[j] - this.posY[i];
-        const py = this.halfY[i] + this.halfY[j] - Math.abs(dy);
-        if (py <= 0)
-            return;
-        const dz = this.posZ[j] - this.posZ[i];
-        const pz = this.halfZ[i] + this.halfZ[j] - Math.abs(dz);
-        if (pz <= 0)
-            return;
-        if (countPass) {
-            this.stats.pairs += 1;
-            this.stats.contacts += 1;
-            this.contact[i] = 1;
-            this.contact[j] = 1;
-        }
         let nX = 0;
         let nY = 0;
         let nZ = 0;
-        let pen;
-        if (px <= py && px <= pz) {
-            nX = dx < 0 ? -1 : 1;
-            pen = px;
+        let pen = 0;
+        const sphereI = this.shape[i] === SHAPE_SPHERE;
+        const sphereJ = this.shape[j] === SHAPE_SPHERE;
+        let needsAxisNormal = true;
+        if (sphereI && sphereJ) {
+            const dx = this.posX[j] - this.posX[i];
+            const dy = this.posY[j] - this.posY[i];
+            const dz = this.posZ[j] - this.posZ[i];
+            const radiusSum = this.halfX[i] + this.halfX[j];
+            const dist2 = dx * dx + dy * dy + dz * dz;
+            if (dist2 >= radiusSum * radiusSum)
+                return;
+            const dist = Math.sqrt(dist2);
+            if (dist > 1e-9) {
+                nX = dx / dist;
+                nY = dy / dist;
+                nZ = dz / dist;
+                pen = radiusSum - dist;
+            }
+            else {
+                nY = 1;
+                pen = radiusSum;
+            }
+            needsAxisNormal = false;
         }
-        else if (py <= pz) {
-            nY = dy < 0 ? -1 : 1;
-            pen = py;
+        else if (sphereI !== sphereJ) {
+            const box = sphereI ? j : i;
+            const sph = sphereI ? i : j;
+            const loX = this.posX[box] - this.halfX[box];
+            const hiX = this.posX[box] + this.halfX[box];
+            const loY = this.posY[box] - this.halfY[box];
+            const hiY = this.posY[box] + this.halfY[box];
+            const loZ = this.posZ[box] - this.halfZ[box];
+            const hiZ = this.posZ[box] + this.halfZ[box];
+            const sx = this.posX[sph];
+            const sy = this.posY[sph];
+            const sz = this.posZ[sph];
+            const dx = sx - (sx < loX ? loX : sx > hiX ? hiX : sx);
+            const dy = sy - (sy < loY ? loY : sy > hiY ? hiY : sy);
+            const dz = sz - (sz < loZ ? loZ : sz > hiZ ? hiZ : sz);
+            const dist2 = dx * dx + dy * dy + dz * dz;
+            if (dist2 > 1e-12) {
+                const radius = this.halfX[sph];
+                if (dist2 >= radius * radius)
+                    return;
+                const dist = Math.sqrt(dist2);
+                const towardSphere = sph === j ? 1 / dist : -1 / dist;
+                nX = dx * towardSphere;
+                nY = dy * towardSphere;
+                nZ = dz * towardSphere;
+                pen = radius - dist;
+                needsAxisNormal = false;
+            }
         }
-        else {
-            nZ = dz < 0 ? -1 : 1;
-            pen = pz;
+        if (needsAxisNormal) {
+            const dx = this.posX[j] - this.posX[i];
+            const px = this.halfX[i] + this.halfX[j] - Math.abs(dx);
+            if (px <= 0)
+                return;
+            const dy = this.posY[j] - this.posY[i];
+            const py = this.halfY[i] + this.halfY[j] - Math.abs(dy);
+            if (py <= 0)
+                return;
+            const dz = this.posZ[j] - this.posZ[i];
+            const pz = this.halfZ[i] + this.halfZ[j] - Math.abs(dz);
+            if (pz <= 0)
+                return;
+            if (px <= py && px <= pz) {
+                nX = dx < 0 ? -1 : 1;
+                pen = px;
+            }
+            else if (py <= pz) {
+                nY = dy < 0 ? -1 : 1;
+                pen = py;
+            }
+            else {
+                nZ = dz < 0 ? -1 : 1;
+                pen = pz;
+            }
+        }
+        if (countPass) {
+            this.stats.pairs += 1;
+            this.stats.contacts += 1;
+            this.contact[i] = 1;
+            this.contact[j] = 1;
         }
         const rvx = this.velX[j] - this.velX[i];
         const rvy = this.velY[j] - this.velY[i];

package/dist/physics/spatialGrid.d.ts

@@ -1,4 +1,4 @@
-import type { PhysicsBounds } from "./physicsWorld.js";
+import { type PhysicsBounds } from "./physicsWorld.js";
 export interface SpatialGridConfig {
     /** Horizontal extent to index; only x/z of the bounds are used (a top-down plane). */
     bounds: PhysicsBounds;

package/dist/physics/spatialGrid.js

@@ -1,3 +1,4 @@
+import { MAX_BROADPHASE_CELLS } from "./physicsWorld.js";
 /**
  * A uniform-grid broad-phase over the x/z plane, separate from the rigid-body sim, for cheap
  * same-tick proximity across hundreds–thousands of simple movers (swarm enemies). Rebuild each
@@ -30,6 +31,10 @@ export class SpatialGrid {
         this.nx = Math.max(1, Math.ceil(spanX / config.cellSize));
         this.nz = Math.max(1, Math.ceil(spanZ / config.cellSize));
         this.numCells = this.nx * this.nz;
+        if (this.numCells > MAX_BROADPHASE_CELLS) {
+            throw new Error(`SpatialGrid: grid too large (${this.nx}x${this.nz} = ${this.numCells} cells, cap ${MAX_BROADPHASE_CELLS}). ` +
+                `bounds=[${config.bounds.min}]..[${config.bounds.max}] cellSize=${config.cellSize}; raise cellSize or shrink bounds.`);
+        }
         this.cellStart = new Int32Array(this.numCells + 1);
         this.cursor = new Int32Array(this.numCells);
         this.sorted = new Int32Array(config.capacity);

package/dist/physics/vehicleBody.d.ts

@@ -77,6 +77,12 @@ export declare class VehicleBody {
     private readonly surfaceFriction;
     private groundedCount;
     constructor(world: PhysicsWorld, config: VehicleBodyConfig);
+    /**
+     * A wheel's local offset rotated by the current heading — the ground-side mount and the
+     * chassis-side spring anchor both derive from this, so the suspension axis stays vertical (not a
+     * mix of rotated and unrotated ends) as the chassis turns.
+     */
+    private rotateOffset;
     private wheelMount;
     get position(): [number, number, number];
     get forward(): [number, number];

package/dist/physics/vehicleBody.js

@@ -101,7 +101,7 @@ export class VehicleBody {
             const rest = wheel.restLength ?? this.suspensionRest;
             const id = world.springJoint({
                 bodyA: this.chassis,
-                anchorA: [wheel.offset[0], wheel.offset[1], wheel.offset[2]],
+                anchorA: this.rotateOffset(wheel.offset),
                 anchorB: [worldPos[0], worldPos[1] - rest, worldPos[2]],
                 restLength: rest,
                 stiffness,
@@ -118,15 +118,20 @@ export class VehicleBody {
             });
         }
     }
-    wheelMount(wheel) {
+    /**
+     * A wheel's local offset rotated by the current heading — the ground-side mount and the
+     * chassis-side spring anchor both derive from this, so the suspension axis stays vertical (not a
+     * mix of rotated and unrotated ends) as the chassis turns.
+     */
+    rotateOffset(offset) {
         const sin = Math.sin(this.heading);
         const cos = Math.cos(this.heading);
-        const [ox, oy, oz] = wheel.offset;
-        return [
-            this.world.posX[this.chassis] + ox * cos + oz * sin,
-            this.world.posY[this.chassis] + oy,
-            this.world.posZ[this.chassis] - ox * sin + oz * cos,
-        ];
+        const [ox, oy, oz] = offset;
+        return [ox * cos + oz * sin, oy, -ox * sin + oz * cos];
+    }
+    wheelMount(wheel) {
+        const [dx, dy, dz] = this.rotateOffset(wheel.offset);
+        return [this.world.posX[this.chassis] + dx, this.world.posY[this.chassis] + dy, this.world.posZ[this.chassis] + dz];
     }
     get position() {
         return [this.world.posX[this.chassis], this.world.posY[this.chassis], this.world.posZ[this.chassis]];
@@ -149,16 +154,8 @@ export class VehicleBody {
         return this.wheels.length;
     }
     resetTo(position, heading) {
-        const w = this.world;
-        const c = this.chassis;
-        w.posX[c] = position[0];
-        w.posY[c] = position[1];
-        w.posZ[c] = position[2];
-        w.velX[c] = 0;
-        w.velY[c] = 0;
-        w.velZ[c] = 0;
+        this.world.teleport(this.chassis, position[0], position[1], position[2]);
         this.heading = heading;
-        w.wake(c);
     }
     update(dt, input) {
         const w = this.world;
@@ -212,6 +209,8 @@ export class VehicleBody {
             const gap = mount[1] - (groundY + radius);
             const maxTravel = rest + radius;
             const grounded = gap <= maxTravel;
+            const anchorA = this.rotateOffset(wheel.offset);
+            w.setJointAnchorA(this.springs[i], anchorA[0], anchorA[1], anchorA[2]);
             w.setJointAnchor(this.springs[i], mount[0], groundY + radius, mount[2]);
             state.worldX = mount[0];
             state.worldY = groundY + radius;

package/dist/puzzle/cellGrid.d.ts

@@ -0,0 +1,26 @@
+export interface CellGrid<T> {
+    readonly width: number;
+    readonly height: number;
+    readonly cells: readonly (T | null)[];
+}
+export interface CellRun<T> {
+    readonly value: T;
+    readonly cells: readonly {
+        readonly x: number;
+        readonly y: number;
+    }[];
+    readonly direction: "row" | "column";
+}
+export declare function createCellGrid<T>(width: number, height: number): CellGrid<T>;
+export declare function inGridBounds<T>(grid: CellGrid<T>, x: number, y: number): boolean;
+export declare function cellAt<T>(grid: CellGrid<T>, x: number, y: number): T | null;
+export declare function withCell<T>(grid: CellGrid<T>, x: number, y: number, value: T | null): CellGrid<T>;
+export declare function withCells<T>(grid: CellGrid<T>, entries: readonly {
+    readonly x: number;
+    readonly y: number;
+    readonly value: T | null;
+}[]): CellGrid<T>;
+export declare function fullRows<T>(grid: CellGrid<T>): number[];
+export declare function clearRows<T>(grid: CellGrid<T>, rows: readonly number[]): CellGrid<T>;
+export declare function collapseColumns<T>(grid: CellGrid<T>): CellGrid<T>;
+export declare function findRuns<T>(grid: CellGrid<T>, minLength: number, matches?: (a: T, b: T) => boolean): CellRun<T>[];

package/dist/puzzle/cellGrid.js

@@ -0,0 +1,110 @@
+export function createCellGrid(width, height) {
+    return { width, height, cells: new Array(width * height).fill(null) };
+}
+export function inGridBounds(grid, x, y) {
+    return x >= 0 && x < grid.width && y >= 0 && y < grid.height;
+}
+export function cellAt(grid, x, y) {
+    if (!inGridBounds(grid, x, y))
+        return null;
+    return grid.cells[y * grid.width + x] ?? null;
+}
+export function withCell(grid, x, y, value) {
+    if (!inGridBounds(grid, x, y))
+        return grid;
+    const cells = grid.cells.slice();
+    cells[y * grid.width + x] = value;
+    return { width: grid.width, height: grid.height, cells };
+}
+export function withCells(grid, entries) {
+    const cells = grid.cells.slice();
+    for (const entry of entries) {
+        if (inGridBounds(grid, entry.x, entry.y))
+            cells[entry.y * grid.width + entry.x] = entry.value;
+    }
+    return { width: grid.width, height: grid.height, cells };
+}
+export function fullRows(grid) {
+    const rows = [];
+    for (let y = 0; y < grid.height; y += 1) {
+        let full = true;
+        for (let x = 0; x < grid.width; x += 1) {
+            if (cellAt(grid, x, y) === null) {
+                full = false;
+                break;
+            }
+        }
+        if (full)
+            rows.push(y);
+    }
+    return rows;
+}
+export function clearRows(grid, rows) {
+    const removed = new Set(rows);
+    const kept = [];
+    for (let y = 0; y < grid.height; y += 1) {
+        if (removed.has(y))
+            continue;
+        kept.push(grid.cells.slice(y * grid.width, y * grid.width + grid.width));
+    }
+    const clearedCount = grid.height - kept.length;
+    const cells = [];
+    for (let i = 0; i < clearedCount; i += 1)
+        cells.push(...new Array(grid.width).fill(null));
+    for (const row of kept)
+        cells.push(...row);
+    return { width: grid.width, height: grid.height, cells };
+}
+export function collapseColumns(grid) {
+    const cells = grid.cells.slice();
+    for (let x = 0; x < grid.width; x += 1) {
+        const values = [];
+        for (let y = 0; y < grid.height; y += 1) {
+            const value = cellAt(grid, x, y);
+            if (value !== null)
+                values.push(value);
+        }
+        const emptyCount = grid.height - values.length;
+        for (let y = 0; y < grid.height; y += 1) {
+            cells[y * grid.width + x] = y < emptyCount ? null : values[y - emptyCount];
+        }
+    }
+    return { width: grid.width, height: grid.height, cells };
+}
+function scanRuns(length, cellAtIndex, minLength, matches) {
+    const runs = [];
+    let start = 0;
+    for (let i = 1; i <= length; i += 1) {
+        const prev = cellAtIndex(i - 1);
+        const cur = i < length ? cellAtIndex(i) : null;
+        const continues = prev !== null && cur !== null && matches(prev, cur);
+        if (!continues) {
+            const runLength = i - start;
+            const value = cellAtIndex(start);
+            if (runLength >= minLength && value !== null)
+                runs.push({ value, start, end: i });
+            start = i;
+        }
+    }
+    return runs;
+}
+export function findRuns(grid, minLength, matches = (a, b) => a === b) {
+    const runs = [];
+    for (let y = 0; y < grid.height; y += 1) {
+        for (const run of scanRuns(grid.width, (x) => cellAt(grid, x, y), minLength, matches)) {
+            const cells = [];
+            for (let x = run.start; x < run.end; x += 1)
+                cells.push({ x, y });
+            runs.push({ value: run.value, cells, direction: "row" });
+        }
+    }
+    for (let x = 0; x < grid.width; x += 1) {
+        for (const run of scanRuns(grid.height, (y) => cellAt(grid, x, y), minLength, matches)) {
+            const cells = [];
+            for (let y = run.start; y < run.end; y += 1)
+                cells.push({ x, y });
+            runs.push({ value: run.value, cells, direction: "column" });
+        }
+    }
+    return runs;
+}

package/dist/puzzle/fallingPiece.d.ts

@@ -0,0 +1,24 @@
+import { type CellGrid } from "./cellGrid.js";
+export interface FallingPiece<TShape extends string = string> {
+    readonly shape: TShape;
+    readonly rotation: number;
+    readonly x: number;
+    readonly y: number;
+}
+export type ShapeTable<TShape extends string = string> = Record<TShape, readonly (readonly (readonly [number, number])[])[]>;
+export declare function pieceCells<TShape extends string>(table: ShapeTable<TShape>, piece: FallingPiece<TShape>): readonly (readonly [number, number])[];
+export declare function pieceCollides<T, TShape extends string>(grid: CellGrid<T>, table: ShapeTable<TShape>, piece: FallingPiece<TShape>): boolean;
+export declare function mergePiece<T, TShape extends string>(grid: CellGrid<T>, table: ShapeTable<TShape>, piece: FallingPiece<TShape>, value: T): CellGrid<T>;
+export declare function dropDistance<T, TShape extends string>(grid: CellGrid<T>, table: ShapeTable<TShape>, piece: FallingPiece<TShape>): number;
+export declare function gravityInterval(level: number, base?: number, perLevel?: number, min?: number): number;
+export declare function levelForLines(lines: number, linesPerLevel?: number): number;
+export declare function lineScore(cleared: number, level: number, table?: readonly number[]): number;
+export interface LockDelayState {
+    readonly delaySeconds: number;
+    readonly elapsed: number;
+}
+export declare function createLockDelay(delaySeconds: number): LockDelayState;
+export declare function stepLockDelay(state: LockDelayState, grounded: boolean, dt: number): {
+    state: LockDelayState;
+    locked: boolean;
+};