@jgengine/core 0.5.0 → 0.7.0

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);
+                    }
+                }
+            }
+        }
+    }
+}

package/dist/physics/structure.d.ts

@@ -0,0 +1,83 @@
+import type { PhysicsWorld } from "./physicsWorld.js";
+export interface StructureMaterial {
+    id: string;
+    /** Node integrity and edge strength default to this — brittle glass vs load-bearing concrete. */
+    strength: number;
+    /** Debris body mass when a node of this material collapses. Default 1. */
+    mass?: number;
+}
+export type StructureMaterialTable = Readonly<Record<string, StructureMaterial>>;
+export interface StructureNodeSpec {
+    id: string;
+    /** Body centre in world coordinates — also where its debris spawns. */
+    position: readonly [number, number, number];
+    halfExtents: readonly [number, number, number];
+    /** Overrides material mass for the collapsed debris body. */
+    mass?: number;
+    /** Hit points before the piece shatters. Default from `material.strength`, else 100. */
+    integrity?: number;
+    material?: string;
+    /** Foundation piece — reachability to any anchor is what keeps the rest standing. */
+    anchor?: boolean;
+}
+export interface StructureEdgeSpec {
+    a: string;
+    b: string;
+    /** Accumulated edge damage past this severs the connection. Default from `material.strength`, else 100. */
+    strength?: number;
+}
+export interface CollapseEvent {
+    /**
+     * Node ids that left the structure this operation — the shattered node plus every piece the loss
+     * disconnected from an anchor. This is the replicated collapse: broadcast the id list, not each
+     * fragment's physics (games re-derive the debris locally).
+     */
+    fell: readonly string[];
+    collapsed: boolean;
+}
+export interface DebrisConfig {
+    /** Outward kick magnitude applied to each debris body from `origin`. Default 3. */
+    impulse?: number;
+    /** Blast origin the kick radiates from. Defaults to each node's own position (straight drop). */
+    origin?: readonly [number, number, number];
+}
+/**
+ * A structural-integrity graph over a building — nodes are pieces (walls, beams, floors), edges are
+ * load-bearing connections, some nodes are anchored foundations. `damage`/`damageEdge` wear pieces and
+ * connections down; when a piece shatters or an edge severs, the graph recomputes which pieces still
+ * reach an anchor and hands back every newly-disconnected piece as one `CollapseEvent`. Feed that to
+ * `toDebris` to sink the fallen pieces into a `PhysicsWorld` as rigid bodies ("The Finals" smooth
+ * destruction, Rainbow Six walls). Coarse by design: it replicates the collapse event, not per fragment.
+ */
+export declare class StructureGraph {
+    private readonly nodes;
+    private readonly integrity;
+    private readonly adj;
+    private readonly edgeStrength;
+    private readonly edgeDamage;
+    private readonly fallenSpecs;
+    private readonly materials;
+    constructor(config: {
+        nodes: readonly StructureNodeSpec[];
+        edges: readonly StructureEdgeSpec[];
+        materials?: StructureMaterialTable;
+    });
+    private materialStrength;
+    has(id: string): boolean;
+    integrityOf(id: string): number;
+    nodeSpec(id: string): StructureNodeSpec | undefined;
+    neighbors(id: string): string[];
+    standing(): string[];
+    isSupported(id: string): boolean;
+    private supportedSet;
+    private removeNode;
+    private settle;
+    /** Wear a piece down; at ≤0 integrity it shatters and the loss cascades through unsupported pieces. */
+    damage(id: string, amount: number): CollapseEvent;
+    /** Wear a connection down; past its strength it severs and unsupported pieces cascade off. */
+    damageEdge(a: string, b: string, amount: number): CollapseEvent;
+    /** Cut a connection outright (a beam sheared by a blast), then cascade. */
+    severEdge(a: string, b: string): CollapseEvent;
+    /** Spawn one rigid debris body per fallen piece into `world`; returns the new body indices. */
+    toDebris(world: PhysicsWorld, event: CollapseEvent, config?: DebrisConfig): number[];
+}

package/dist/physics/traversal.d.ts

@@ -0,0 +1,75 @@
+import type { PhysicsWorld } from "./physicsWorld.js";
+export interface GrappleConfig {
+    /** Metres per second the rope shortens under `reel` / lengthens under `payOut`. Default 8. */
+    reelSpeed?: number;
+    /** Rope refuses to shorten past this — the traveller stops on top of the anchor, not inside it. Default 1.5. */
+    minLength?: number;
+    /** Firing range; `fire` beyond this misses. Default 40. */
+    maxLength?: number;
+    /** Elastic rope (spring) that yanks and bounces, vs a rigid `distance` cable that holds a hard length. Default false. */
+    elastic?: boolean;
+    /** Spring restoring rate when `elastic`. Default 40. */
+    stiffness?: number;
+    /** Spring damping when `elastic`. Default 6. */
+    damping?: number;
+}
+/**
+ * A fired-anchor rope on the joint API — grapple (reel toward a hit point), zipline (rigid cable to a
+ * far anchor you then slide/reel along), swing (rigid rope + gravity = a pendulum). `fire` attaches a
+ * `distance`/`spring` joint from the traveller body to a fixed world point; `reel` shrinks its rest
+ * length so the constraint drags the body in; `moveAnchor` re-points it (zipline glide, grapple-to-
+ * moving-target). The pick — a raycast to find the anchor — is the caller's; core owns the constraint.
+ */
+export declare class Grapple {
+    readonly body: number;
+    private readonly world;
+    private readonly reelSpeed;
+    private readonly minLength;
+    private readonly maxLength;
+    private readonly elastic;
+    private readonly stiffness;
+    private readonly damping;
+    private joint;
+    private length;
+    private ax;
+    private ay;
+    private az;
+    constructor(world: PhysicsWorld, body: number, config?: GrappleConfig);
+    get attached(): boolean;
+    get ropeLength(): number;
+    anchor(): readonly [number, number, number] | null;
+    distanceToAnchor(): number;
+    /** Attach to a world anchor point. Returns false (a miss) when the point is beyond `maxLength`. */
+    fire(x: number, y: number, z: number): boolean;
+    /** Shorten the rope by `reelSpeed * dt`, pulling the traveller toward the anchor. Clamps at `minLength`. */
+    reel(dt: number): void;
+    /** Pay out slack, lengthening the rope up to `maxLength`. */
+    payOut(dt: number): void;
+    /** Re-point the anchor (slide a zipline attachment along the cable, or track a moving target). */
+    moveAnchor(x: number, y: number, z: number): void;
+    release(): void;
+}
+export interface GlideConfig {
+    /** Fraction of world gravity the glider still feels — 1 is normal fall, 0 hangs. Default 0.25. */
+    gravityScale?: number;
+    /** Forward acceleration applied along the steer vector each `apply`. Default 6. */
+    thrust?: number;
+    /** Terminal descent clamp so a glide never plummets. Default 8. */
+    maxFallSpeed?: number;
+}
+/**
+ * A reduced-gravity, forward-thrust glide over a physics body — wingsuit / glider / paraglider
+ * (Enshrouded, Grounded). Call `apply(dt, steerX, steerZ)` each frame *before* `world.step`: it feeds
+ * back most of the gravity the sim is about to apply (leaving `gravityScale` of it), pushes the body
+ * along the steer vector by `thrust`, and clamps descent to `maxFallSpeed`. Stop calling it to fall
+ * normally again — no attach/detach state to leak.
+ */
+export declare class Glide {
+    readonly body: number;
+    private readonly world;
+    private readonly gravityScale;
+    private readonly thrust;
+    private readonly maxFallSpeed;
+    constructor(world: PhysicsWorld, body: number, config?: GlideConfig);
+    apply(dt: number, steerX?: number, steerZ?: number): void;
+}

package/dist/physics/traversal.js

@@ -0,0 +1,138 @@
+/**
+ * A fired-anchor rope on the joint API — grapple (reel toward a hit point), zipline (rigid cable to a
+ * far anchor you then slide/reel along), swing (rigid rope + gravity = a pendulum). `fire` attaches a
+ * `distance`/`spring` joint from the traveller body to a fixed world point; `reel` shrinks its rest
+ * length so the constraint drags the body in; `moveAnchor` re-points it (zipline glide, grapple-to-
+ * moving-target). The pick — a raycast to find the anchor — is the caller's; core owns the constraint.
+ */
+export class Grapple {
+    body;
+    world;
+    reelSpeed;
+    minLength;
+    maxLength;
+    elastic;
+    stiffness;
+    damping;
+    joint = -1;
+    length = 0;
+    ax = 0;
+    ay = 0;
+    az = 0;
+    constructor(world, body, config = {}) {
+        this.world = world;
+        this.body = body;
+        this.reelSpeed = config.reelSpeed ?? 8;
+        this.minLength = config.minLength ?? 1.5;
+        this.maxLength = config.maxLength ?? 40;
+        this.elastic = config.elastic ?? false;
+        this.stiffness = config.stiffness ?? 40;
+        this.damping = config.damping ?? 6;
+    }
+    get attached() {
+        return this.joint >= 0;
+    }
+    get ropeLength() {
+        return this.length;
+    }
+    anchor() {
+        return this.joint < 0 ? null : [this.ax, this.ay, this.az];
+    }
+    distanceToAnchor() {
+        const w = this.world;
+        const dx = this.ax - w.posX[this.body];
+        const dy = this.ay - w.posY[this.body];
+        const dz = this.az - w.posZ[this.body];
+        return Math.sqrt(dx * dx + dy * dy + dz * dz);
+    }
+    /** Attach to a world anchor point. Returns false (a miss) when the point is beyond `maxLength`. */
+    fire(x, y, z) {
+        if (this.joint >= 0)
+            this.release();
+        const w = this.world;
+        const dx = x - w.posX[this.body];
+        const dy = y - w.posY[this.body];
+        const dz = z - w.posZ[this.body];
+        const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (dist > this.maxLength)
+            return false;
+        this.ax = x;
+        this.ay = y;
+        this.az = z;
+        this.length = dist;
+        const opts = {
+            bodyA: this.body,
+            anchorB: [x, y, z],
+            restLength: dist,
+            stiffness: this.stiffness,
+            damping: this.damping,
+        };
+        this.joint = this.elastic ? w.springJoint(opts) : w.distanceJoint(opts);
+        w.wake(this.body);
+        return true;
+    }
+    /** Shorten the rope by `reelSpeed * dt`, pulling the traveller toward the anchor. Clamps at `minLength`. */
+    reel(dt) {
+        if (this.joint < 0)
+            return;
+        this.length = Math.max(this.minLength, this.length - this.reelSpeed * dt);
+        this.world.setJointRest(this.joint, this.length);
+        this.world.wake(this.body);
+    }
+    /** Pay out slack, lengthening the rope up to `maxLength`. */
+    payOut(dt) {
+        if (this.joint < 0)
+            return;
+        this.length = Math.min(this.maxLength, this.length + this.reelSpeed * dt);
+        this.world.setJointRest(this.joint, this.length);
+        this.world.wake(this.body);
+    }
+    /** Re-point the anchor (slide a zipline attachment along the cable, or track a moving target). */
+    moveAnchor(x, y, z) {
+        if (this.joint < 0)
+            return;
+        this.ax = x;
+        this.ay = y;
+        this.az = z;
+        this.world.setJointAnchor(this.joint, x, y, z);
+        this.world.wake(this.body);
+    }
+    release() {
+        if (this.joint < 0)
+            return;
+        this.world.removeJoint(this.joint);
+        this.joint = -1;
+    }
+}
+/**
+ * A reduced-gravity, forward-thrust glide over a physics body — wingsuit / glider / paraglider
+ * (Enshrouded, Grounded). Call `apply(dt, steerX, steerZ)` each frame *before* `world.step`: it feeds
+ * back most of the gravity the sim is about to apply (leaving `gravityScale` of it), pushes the body
+ * along the steer vector by `thrust`, and clamps descent to `maxFallSpeed`. Stop calling it to fall
+ * normally again — no attach/detach state to leak.
+ */
+export class Glide {
+    body;
+    world;
+    gravityScale;
+    thrust;
+    maxFallSpeed;
+    constructor(world, body, config = {}) {
+        this.world = world;
+        this.body = body;
+        this.gravityScale = config.gravityScale ?? 0.25;
+        this.thrust = config.thrust ?? 6;
+        this.maxFallSpeed = config.maxFallSpeed ?? 8;
+    }
+    apply(dt, steerX = 0, steerZ = 0) {
+        const w = this.world;
+        const b = this.body;
+        const counter = -w.gravity * (1 - this.gravityScale);
+        w.velY[b] += counter * dt;
+        w.velX[b] += steerX * this.thrust * dt;
+        w.velZ[b] += steerZ * this.thrust * dt;
+        if (w.velY[b] < -this.maxFallSpeed)
+            w.velY[b] = -this.maxFallSpeed;
+        w.wake(b);
+    }
+}