@jgengine/core 0.6.0 → 0.7.0

package/dist/physics/physicsWorld.js

@@ -26,6 +26,8 @@ export class PhysicsWorld {
     sleepMove2;
     sleepSteps;
     wakeThreshold;
+    jointCapacity;
+    jointCorrection;
     posX;
     posY;
     posZ;
@@ -56,6 +58,35 @@ export class PhysicsWorld {
     awakeList;
     awakeSlot;
     awakeCount = 0;
+    jSpring;
+    jActive;
+    jBodyA;
+    jBodyB;
+    jAnchorAX;
+    jAnchorAY;
+    jAnchorAZ;
+    jAnchorBX;
+    jAnchorBY;
+    jAnchorBZ;
+    jRest;
+    jStiffness;
+    jDamping;
+    jMaxImpulse;
+    jFree;
+    jFreeCount = 0;
+    jointHigh = 0;
+    jointActiveCount = 0;
+    collisionListener = null;
+    collisionMinSpeed = 0;
+    collisionEvent = {
+        a: 0,
+        b: 0,
+        nx: 0,
+        ny: 0,
+        nz: 0,
+        approachSpeed: 0,
+        impulse: 0,
+    };
     bodyCount = 0;
     accumulator = 0;
     stats = {
@@ -86,6 +117,8 @@ export class PhysicsWorld {
         this.sleepMove2 = sleepMoveEps * sleepMoveEps;
         this.sleepSteps = config.sleepThresholdSteps ?? 30;
         this.wakeThreshold = config.wakeThreshold ?? 0.5;
+        this.jointCapacity = Math.max(0, config.jointCapacity ?? 256);
+        this.jointCorrection = config.jointCorrection ?? 0.5;
         const cap = config.capacity;
         this.posX = new Float32Array(cap);
         this.posY = new Float32Array(cap);
@@ -114,6 +147,22 @@ export class PhysicsWorld {
         this.bodyCell = new Int32Array(cap);
         this.awakeList = new Int32Array(cap);
         this.awakeSlot = new Int32Array(cap).fill(-1);
+        const jc = this.jointCapacity;
+        this.jSpring = new Uint8Array(jc);
+        this.jActive = new Uint8Array(jc);
+        this.jBodyA = new Int32Array(jc);
+        this.jBodyB = new Int32Array(jc);
+        this.jAnchorAX = new Float32Array(jc);
+        this.jAnchorAY = new Float32Array(jc);
+        this.jAnchorAZ = new Float32Array(jc);
+        this.jAnchorBX = new Float32Array(jc);
+        this.jAnchorBY = new Float32Array(jc);
+        this.jAnchorBZ = new Float32Array(jc);
+        this.jRest = new Float32Array(jc);
+        this.jStiffness = new Float32Array(jc);
+        this.jDamping = new Float32Array(jc);
+        this.jMaxImpulse = new Float32Array(jc);
+        this.jFree = new Int32Array(jc);
     }
     addAwake(i) {
         if (this.awakeSlot[i] >= 0)
@@ -138,6 +187,109 @@ export class PhysicsWorld {
     get cells() {
         return { nx: this.nx, ny: this.ny, nz: this.nz, total: this.numCells };
     }
+    get jointCount() {
+        return this.jointActiveCount;
+    }
+    /**
+     * 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, minApproachSpeed = 0) {
+        this.collisionListener = listener;
+        this.collisionMinSpeed = minApproachSpeed;
+    }
+    hingeJoint(options) {
+        return this.addJoint(options, false, 0);
+    }
+    fixedJoint(options) {
+        return this.addJoint(options, false, 0);
+    }
+    distanceJoint(options) {
+        return this.addJoint(options, false, null);
+    }
+    springJoint(options) {
+        return this.addJoint(options, true, null);
+    }
+    addJoint(options, spring, restOverride) {
+        let id;
+        if (this.jFreeCount > 0) {
+            id = this.jFree[--this.jFreeCount];
+        }
+        else {
+            if (this.jointHigh >= this.jointCapacity)
+                throw new Error("PhysicsWorld: joint capacity exceeded");
+            id = this.jointHigh++;
+        }
+        const bodyB = options.bodyB ?? -1;
+        const aA = options.anchorA;
+        const aB = options.anchorB;
+        this.jBodyA[id] = options.bodyA;
+        this.jBodyB[id] = bodyB;
+        this.jAnchorAX[id] = aA?.[0] ?? 0;
+        this.jAnchorAY[id] = aA?.[1] ?? 0;
+        this.jAnchorAZ[id] = aA?.[2] ?? 0;
+        this.jAnchorBX[id] = aB?.[0] ?? 0;
+        this.jAnchorBY[id] = aB?.[1] ?? 0;
+        this.jAnchorBZ[id] = aB?.[2] ?? 0;
+        this.jSpring[id] = spring ? 1 : 0;
+        this.jStiffness[id] = options.stiffness ?? 40;
+        this.jDamping[id] = options.damping ?? 6;
+        this.jMaxImpulse[id] = options.maxImpulse ?? Number.POSITIVE_INFINITY;
+        this.jRest[id] = restOverride ?? options.restLength ?? this.jointDistance(id);
+        this.jActive[id] = 1;
+        this.jointActiveCount += 1;
+        return id;
+    }
+    removeJoint(id) {
+        if (this.jActive[id] !== 1)
+            return;
+        this.jActive[id] = 0;
+        this.jFree[this.jFreeCount++] = id;
+        this.jointActiveCount -= 1;
+    }
+    /** Move a joint's world anchor point (only meaningful when `bodyB` is a world anchor). */
+    setJointAnchor(id, x, y, z) {
+        this.jAnchorBX[id] = x;
+        this.jAnchorBY[id] = y;
+        this.jAnchorBZ[id] = z;
+    }
+    setJointRest(id, restLength) {
+        this.jRest[id] = restLength;
+    }
+    jointDistance(id) {
+        const bA = this.jBodyA[id];
+        const bB = this.jBodyB[id];
+        const ax = (bA >= 0 ? this.posX[bA] : 0) + this.jAnchorAX[id];
+        const ay = (bA >= 0 ? this.posY[bA] : 0) + this.jAnchorAY[id];
+        const az = (bA >= 0 ? this.posZ[bA] : 0) + this.jAnchorAZ[id];
+        const bx = bB >= 0 ? this.posX[bB] + this.jAnchorBX[id] : this.jAnchorBX[id];
+        const by = bB >= 0 ? this.posY[bB] + this.jAnchorBY[id] : this.jAnchorBY[id];
+        const bz = bB >= 0 ? this.posZ[bB] + this.jAnchorBZ[id] : this.jAnchorBZ[id];
+        const dx = bx - ax;
+        const dy = by - ay;
+        const dz = bz - az;
+        return Math.sqrt(dx * dx + dy * dy + dz * dz);
+    }
+    /** Write [ax,ay,az,bx,by,bz] world endpoints per active joint into `out`; returns the joint count. */
+    readJointSegments(out) {
+        let n = 0;
+        for (let id = 0; id < this.jointHigh; id += 1) {
+            if (this.jActive[id] !== 1)
+                continue;
+            const bA = this.jBodyA[id];
+            const bB = this.jBodyB[id];
+            const o = n * 6;
+            out[o] = (bA >= 0 ? this.posX[bA] : 0) + this.jAnchorAX[id];
+            out[o + 1] = (bA >= 0 ? this.posY[bA] : 0) + this.jAnchorAY[id];
+            out[o + 2] = (bA >= 0 ? this.posZ[bA] : 0) + this.jAnchorAZ[id];
+            out[o + 3] = bB >= 0 ? this.posX[bB] + this.jAnchorBX[id] : this.jAnchorBX[id];
+            out[o + 4] = bB >= 0 ? this.posY[bB] + this.jAnchorBY[id] : this.jAnchorBY[id];
+            out[o + 5] = bB >= 0 ? this.posZ[bB] + this.jAnchorBZ[id] : this.jAnchorBZ[id];
+            n += 1;
+        }
+        return n;
+    }
     addBody(options) {
         if (this.bodyCount >= this.capacity)
             throw new Error("PhysicsWorld: capacity exceeded");
@@ -194,6 +346,9 @@ export class PhysicsWorld {
         this.bodyCount = 0;
         this.accumulator = 0;
         this.awakeCount = 0;
+        this.jointHigh = 0;
+        this.jFreeCount = 0;
+        this.jointActiveCount = 0;
     }
     /** Advance by a real frame delta; runs whole fixed substeps and carries the remainder. */
     step(frameDt) {
@@ -243,8 +398,11 @@ export class PhysicsWorld {
         }
         this.buildGrid();
         const iterations = this.solverIterations;
-        for (let it = 0; it < iterations; it += 1)
+        for (let it = 0; it < iterations; it += 1) {
             this.solve(it === 0, it === iterations - 1);
+            if (this.jointActiveCount > 0)
+                this.solveJoints(dt);
+        }
         for (let a = 0; a < this.awakeCount; a += 1)
             this.constrainBounds(this.awakeList[a]);
         this.updateSleep();
@@ -416,6 +574,17 @@ export class PhysicsWorld {
         if (rvn < 0) {
             const e = restitutionPass && -rvn > this.restitutionThreshold ? this.restitution : 0;
             const jn = (-(1 + e) * rvn) / imSum;
+            if (restitutionPass && this.collisionListener !== null && -rvn >= this.collisionMinSpeed) {
+                const ev = this.collisionEvent;
+                ev.a = i;
+                ev.b = j;
+                ev.nx = nX;
+                ev.ny = nY;
+                ev.nz = nZ;
+                ev.approachSpeed = -rvn;
+                ev.impulse = jn;
+                this.collisionListener(ev);
+            }
             this.velX[i] -= jn * imI * nX;
             this.velY[i] -= jn * imI * nY;
             this.velZ[i] -= jn * imI * nZ;
@@ -452,6 +621,97 @@ export class PhysicsWorld {
         this.posY[j] += corr * imJ * nY;
         this.posZ[j] += corr * imJ * nZ;
     }
+    solveJoints(dt) {
+        const beta = this.jointCorrection;
+        const slop = this.slop;
+        for (let id = 0; id < this.jointHigh; id += 1) {
+            if (this.jActive[id] !== 1)
+                continue;
+            const bA = this.jBodyA[id];
+            const bB = this.jBodyB[id];
+            const ax = (bA >= 0 ? this.posX[bA] : 0) + this.jAnchorAX[id];
+            const ay = (bA >= 0 ? this.posY[bA] : 0) + this.jAnchorAY[id];
+            const az = (bA >= 0 ? this.posZ[bA] : 0) + this.jAnchorAZ[id];
+            const bx = bB >= 0 ? this.posX[bB] + this.jAnchorBX[id] : this.jAnchorBX[id];
+            const by = bB >= 0 ? this.posY[bB] + this.jAnchorBY[id] : this.jAnchorBY[id];
+            const bz = bB >= 0 ? this.posZ[bB] + this.jAnchorBZ[id] : this.jAnchorBZ[id];
+            const dx = bx - ax;
+            const dy = by - ay;
+            const dz = bz - az;
+            const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            if (dist < 1e-9)
+                continue;
+            const nX = dx / dist;
+            const nY = dy / dist;
+            const nZ = dz / dist;
+            const c = dist - this.jRest[id];
+            const imA = bA >= 0 ? this.invMass[bA] : 0;
+            const imB = bB >= 0 ? this.invMass[bB] : 0;
+            const imSum = imA + imB;
+            if (imSum === 0)
+                continue;
+            const vax = bA >= 0 ? this.velX[bA] : 0;
+            const vay = bA >= 0 ? this.velY[bA] : 0;
+            const vaz = bA >= 0 ? this.velZ[bA] : 0;
+            const vbx = bB >= 0 ? this.velX[bB] : 0;
+            const vby = bB >= 0 ? this.velY[bB] : 0;
+            const vbz = bB >= 0 ? this.velZ[bB] : 0;
+            const rvn = (vbx - vax) * nX + (vby - vay) * nY + (vbz - vaz) * nZ;
+            if (this.jSpring[id] === 1) {
+                if (Math.abs(c) > slop) {
+                    if (bA >= 0)
+                        this.wake(bA);
+                    if (bB >= 0)
+                        this.wake(bB);
+                }
+                let jn = (-(this.jStiffness[id] * c + this.jDamping[id] * rvn) * dt) / imSum;
+                const maxJ = this.jMaxImpulse[id];
+                if (jn > maxJ)
+                    jn = maxJ;
+                else if (jn < -maxJ)
+                    jn = -maxJ;
+                if (bA >= 0) {
+                    this.velX[bA] -= jn * imA * nX;
+                    this.velY[bA] -= jn * imA * nY;
+                    this.velZ[bA] -= jn * imA * nZ;
+                }
+                if (bB >= 0) {
+                    this.velX[bB] += jn * imB * nX;
+                    this.velY[bB] += jn * imB * nY;
+                    this.velZ[bB] += jn * imB * nZ;
+                }
+                continue;
+            }
+            if (Math.abs(c) > slop) {
+                if (bA >= 0)
+                    this.wake(bA);
+                if (bB >= 0)
+                    this.wake(bB);
+            }
+            const jn = -rvn / imSum;
+            if (bA >= 0) {
+                this.velX[bA] -= jn * imA * nX;
+                this.velY[bA] -= jn * imA * nY;
+                this.velZ[bA] -= jn * imA * nZ;
+            }
+            if (bB >= 0) {
+                this.velX[bB] += jn * imB * nX;
+                this.velY[bB] += jn * imB * nY;
+                this.velZ[bB] += jn * imB * nZ;
+            }
+            const corr = (c * beta) / imSum;
+            if (bA >= 0) {
+                this.posX[bA] += corr * imA * nX;
+                this.posY[bA] += corr * imA * nY;
+                this.posZ[bA] += corr * imA * nZ;
+            }
+            if (bB >= 0) {
+                this.posX[bB] -= corr * imB * nX;
+                this.posY[bB] -= corr * imB * nY;
+                this.posZ[bB] -= corr * imB * nZ;
+            }
+        }
+    }
     updateSleep() {
         // A body sleeps when it has actually stopped moving — measured by displacement over
         // the substep, not instantaneous velocity, which can stay "stuck" nonzero on a body

package/dist/physics/ragdoll.d.ts

@@ -0,0 +1,49 @@
+import type { PhysicsWorld } from "./physicsWorld.js";
+export interface RagdollBoneSpec {
+    name: string;
+    position: readonly [number, number, number];
+    halfExtents: readonly [number, number, number];
+    /** Default 1. */
+    mass?: number;
+}
+export interface RagdollLinkSpec {
+    a: string;
+    b: string;
+    /** `hinge` pins the shared anchor; `distance` (default) holds the bones' current separation. */
+    kind?: "hinge" | "distance";
+    /** World point for a hinge pin. Defaults to the midpoint of the two bone centers. */
+    anchor?: readonly [number, number, number];
+}
+export interface RagdollBalanceConfig {
+    /** Bone the motor keeps upright (torso/head). */
+    root: string;
+    /** Target height of the root above the floor the motor drives toward. */
+    targetHeight: number;
+    /** Corrective gain pulling the root back to `targetHeight`. Default 8. */
+    strength?: number;
+    /** Locomotion push applied to the root from the move vector (active-ragdoll walking). Default 6. */
+    moveForce?: number;
+}
+export interface RagdollConfig {
+    bones: RagdollBoneSpec[];
+    links: RagdollLinkSpec[];
+    /** Optional active-ragdoll balance motor; omit for a purely floppy ragdoll. */
+    balance?: RagdollBalanceConfig;
+}
+/**
+ * A jointed multi-body character — floppy by default, or active-ragdoll when a balance motor is
+ * configured. Bones are `PhysicsWorld` bodies; links are joints on the joint API. `balance(dt, mx, mz)`
+ * drives the root toward its target height (staying upright) and pushes it by the move vector.
+ */
+export declare class Ragdoll {
+    readonly bones: Record<string, number>;
+    readonly links: number[];
+    private readonly world;
+    private readonly config?;
+    constructor(world: PhysicsWorld, bones: Record<string, number>, links: number[], balance?: RagdollBalanceConfig);
+    centerOfMass(): [number, number, number];
+    applyImpulse(bone: string, x: number, y: number, z: number): void;
+    balance(dt: number, moveX?: number, moveZ?: number): void;
+    remove(): void;
+}
+export declare function createRagdoll(world: PhysicsWorld, config: RagdollConfig): Ragdoll;

package/dist/physics/ragdoll.js

@@ -0,0 +1,103 @@
+/**
+ * A jointed multi-body character — floppy by default, or active-ragdoll when a balance motor is
+ * configured. Bones are `PhysicsWorld` bodies; links are joints on the joint API. `balance(dt, mx, mz)`
+ * drives the root toward its target height (staying upright) and pushes it by the move vector.
+ */
+export class Ragdoll {
+    bones;
+    links;
+    world;
+    config;
+    constructor(world, bones, links, balance) {
+        this.world = world;
+        this.bones = bones;
+        this.links = links;
+        this.config = balance;
+    }
+    centerOfMass() {
+        const w = this.world;
+        let mx = 0;
+        let my = 0;
+        let mz = 0;
+        let total = 0;
+        for (const id of Object.values(this.bones)) {
+            const im = w.invMass[id];
+            const m = im > 0 ? 1 / im : 0;
+            mx += w.posX[id] * m;
+            my += w.posY[id] * m;
+            mz += w.posZ[id] * m;
+            total += m;
+        }
+        if (total === 0)
+            return [0, 0, 0];
+        return [mx / total, my / total, mz / total];
+    }
+    applyImpulse(bone, x, y, z) {
+        const w = this.world;
+        const id = this.bones[bone];
+        if (id === undefined)
+            return;
+        const im = w.invMass[id];
+        w.velX[id] += x * im;
+        w.velY[id] += y * im;
+        w.velZ[id] += z * im;
+        w.wake(id);
+    }
+    balance(dt, moveX = 0, moveZ = 0) {
+        const c = this.config;
+        if (c === undefined)
+            return;
+        const w = this.world;
+        const id = this.bones[c.root];
+        if (id === undefined)
+            return;
+        const strength = c.strength ?? 8;
+        const moveForce = c.moveForce ?? 6;
+        const err = c.targetHeight - w.posY[id];
+        w.velY[id] += err * strength * dt;
+        w.velX[id] += moveX * moveForce * dt;
+        w.velZ[id] += moveZ * moveForce * dt;
+        w.wake(id);
+    }
+    remove() {
+        for (const j of this.links)
+            this.world.removeJoint(j);
+        this.links.length = 0;
+    }
+}
+export function createRagdoll(world, config) {
+    const bones = {};
+    for (const spec of config.bones) {
+        bones[spec.name] = world.addBody({
+            position: spec.position,
+            halfExtents: spec.halfExtents,
+            mass: spec.mass ?? 1,
+        });
+    }
+    const links = [];
+    for (const link of config.links) {
+        const a = bones[link.a];
+        const b = bones[link.b];
+        if (a === undefined || b === undefined)
+            continue;
+        if ((link.kind ?? "distance") === "hinge") {
+            const mid = link.anchor !== undefined
+                ? [link.anchor[0], link.anchor[1], link.anchor[2]]
+                : [
+                    (world.posX[a] + world.posX[b]) / 2,
+                    (world.posY[a] + world.posY[b]) / 2,
+                    (world.posZ[a] + world.posZ[b]) / 2,
+                ];
+            links.push(world.hingeJoint({
+                bodyA: a,
+                bodyB: b,
+                anchorA: [mid[0] - world.posX[a], mid[1] - world.posY[a], mid[2] - world.posZ[a]],
+                anchorB: [mid[0] - world.posX[b], mid[1] - world.posY[b], mid[2] - world.posZ[b]],
+            }));
+        }
+        else {
+            links.push(world.distanceJoint({ bodyA: a, bodyB: b }));
+        }
+    }
+    return new Ragdoll(world, bones, links, config.balance);
+}

package/dist/physics/spatialGrid.d.ts

@@ -0,0 +1,41 @@
+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;
+    /** Cell edge; tune to ≈ the query/contact radius so a hit touches ≤ 4 cells. */
+    cellSize: number;
+    /** Maximum entities the index holds; fixed at construction. */
+    capacity: number;
+}
+/**
+ * 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
+ * tick from the caller's own position arrays, then `queryCircle` (enemies hitting the player / an
+ * AoE) or `forEachPair` (mutual separation). Both are precise: no false negatives, no false
+ * positives beyond the exact distance test.
+ */
+export declare class SpatialGrid {
+    readonly cellSize: number;
+    readonly nx: number;
+    readonly nz: number;
+    readonly capacity: number;
+    private readonly minX;
+    private readonly minZ;
+    private readonly numCells;
+    private readonly cellStart;
+    private readonly cursor;
+    private readonly sorted;
+    private readonly cellOfBody;
+    private xs;
+    private zs;
+    private entityCount;
+    constructor(config: SpatialGridConfig);
+    get count(): number;
+    private cellX;
+    private cellZ;
+    rebuild(count: number, xs: Float32Array, zs: Float32Array): void;
+    /** Fill `out` with every entity within `radius` of (x,z); returns the hit count (capped at `out.length`). */
+    queryCircle(x: number, z: number, radius: number, out: Int32Array): number;
+    /** Invoke `cb(a, b)` once for each unordered pair within `maxDistance` (mutual separation/overlap). */
+    forEachPair(maxDistance: number, cb: (a: number, b: number) => void): void;
+}

package/dist/physics/spatialGrid.js

@@ -0,0 +1,138 @@
+/**
+ * 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
+ * tick from the caller's own position arrays, then `queryCircle` (enemies hitting the player / an
+ * AoE) or `forEachPair` (mutual separation). Both are precise: no false negatives, no false
+ * positives beyond the exact distance test.
+ */
+export class SpatialGrid {
+    cellSize;
+    nx;
+    nz;
+    capacity;
+    minX;
+    minZ;
+    numCells;
+    cellStart;
+    cursor;
+    sorted;
+    cellOfBody;
+    xs = null;
+    zs = null;
+    entityCount = 0;
+    constructor(config) {
+        this.cellSize = config.cellSize;
+        this.capacity = config.capacity;
+        this.minX = config.bounds.min[0];
+        this.minZ = config.bounds.min[2];
+        const spanX = Math.max(config.bounds.max[0] - config.bounds.min[0], config.cellSize);
+        const spanZ = Math.max(config.bounds.max[2] - config.bounds.min[2], config.cellSize);
+        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;
+        this.cellStart = new Int32Array(this.numCells + 1);
+        this.cursor = new Int32Array(this.numCells);
+        this.sorted = new Int32Array(config.capacity);
+        this.cellOfBody = new Int32Array(config.capacity);
+    }
+    get count() {
+        return this.entityCount;
+    }
+    cellX(x) {
+        const raw = Math.floor((x - this.minX) / this.cellSize);
+        return raw < 0 ? 0 : raw >= this.nx ? this.nx - 1 : raw;
+    }
+    cellZ(z) {
+        const raw = Math.floor((z - this.minZ) / this.cellSize);
+        return raw < 0 ? 0 : raw >= this.nz ? this.nz - 1 : raw;
+    }
+    rebuild(count, xs, zs) {
+        this.entityCount = count;
+        this.xs = xs;
+        this.zs = zs;
+        const start = this.cellStart;
+        start.fill(0);
+        for (let i = 0; i < count; i += 1) {
+            const c = this.cellZ(zs[i]) * this.nx + this.cellX(xs[i]);
+            this.cellOfBody[i] = c;
+            start[c + 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 < count; i += 1) {
+            const c = this.cellOfBody[i];
+            this.sorted[this.cursor[c]++] = i;
+        }
+    }
+    /** Fill `out` with every entity within `radius` of (x,z); returns the hit count (capped at `out.length`). */
+    queryCircle(x, z, radius, out) {
+        const xs = this.xs;
+        const zs = this.zs;
+        if (xs === null || zs === null)
+            return 0;
+        const r2 = radius * radius;
+        const cxMin = this.cellX(x - radius);
+        const cxMax = this.cellX(x + radius);
+        const czMin = this.cellZ(z - radius);
+        const czMax = this.cellZ(z + radius);
+        const limit = out.length;
+        let n = 0;
+        for (let cz = czMin; cz <= czMax; cz += 1) {
+            const rowBase = cz * this.nx;
+            for (let cx = cxMin; cx <= cxMax; cx += 1) {
+                const cell = rowBase + cx;
+                const end = this.cellStart[cell + 1];
+                for (let s = this.cellStart[cell]; s < end; s += 1) {
+                    const id = this.sorted[s];
+                    const dx = xs[id] - x;
+                    const dz = zs[id] - z;
+                    if (dx * dx + dz * dz <= r2) {
+                        if (n >= limit)
+                            return n;
+                        out[n++] = id;
+                    }
+                }
+            }
+        }
+        return n;
+    }
+    /** Invoke `cb(a, b)` once for each unordered pair within `maxDistance` (mutual separation/overlap). */
+    forEachPair(maxDistance, cb) {
+        const xs = this.xs;
+        const zs = this.zs;
+        if (xs === null || zs === null)
+            return;
+        const d2 = maxDistance * maxDistance;
+        const nx = this.nx;
+        const nz = this.nz;
+        for (let i = 0; i < this.entityCount; i += 1) {
+            const c = this.cellOfBody[i];
+            const cz = (c / nx) | 0;
+            const cx = c - cz * nx;
+            const x = xs[i];
+            const z = zs[i];
+            const z0 = cz > 0 ? cz - 1 : cz;
+            const z1 = cz < nz - 1 ? cz + 1 : cz;
+            const x0 = cx > 0 ? cx - 1 : cx;
+            const x1 = cx < nx - 1 ? cx + 1 : cx;
+            for (let gz = z0; gz <= z1; gz += 1) {
+                const rowBase = gz * nx;
+                for (let gx = x0; gx <= x1; gx += 1) {
+                    const cell = rowBase + gx;
+                    const end = this.cellStart[cell + 1];
+                    for (let s = this.cellStart[cell]; s < end; s += 1) {
+                        const j = this.sorted[s];
+                        if (j <= i)
+                            continue;
+                        const dx = xs[j] - x;
+                        const dz = zs[j] - z;
+                        if (dx * dx + dz * dz <= d2)
+                            cb(i, j);
+                    }
+                }
+            }
+        }
+    }
+}