@driftengine/physics 3.61.0

package/dist/compoundContact.js

@@ -0,0 +1,221 @@
+import { collideShapes, createManifold } from './manifold.js';
+import { MAX_MESH_MANIFOLDS, collideMesh, isMesh } from './meshContact.js';
+import { shapeBounds } from './shape.js';
+/**
+ * The most parts one body may be made of.
+ *
+ * **It lives here rather than beside `decomposeConvex`, and that is a measurement rather than a
+ * preference.** It was declared in `decompose.ts`, which is offline and which nothing in a frame
+ * should reach; importing one integer from there put the whole decomposition — the voxeliser, the
+ * flood fill, the merge, the direction table — into every bundle that touches the physics runtime.
+ * `physics-only` moved outside its 3% band and an A/B against this one import line was what said so.
+ *
+ * A constant about how many shapes a body may hold is a fact about bodies. `decompose.ts` imports it
+ * from here to cap `maxHulls`, which is the direction the dependency should have run in from the
+ * start.
+ */
+export const MAX_BODY_PARTS = 32;
+/**
+ * A body made of several convex shapes, against whatever it meets.
+ *
+ * **The half of convex decomposition that lives in the tick.** `decomposeConvex` turns a concave
+ * mesh into hulls offline; without this there is nowhere for them to go, because `BodySet.shape`
+ * holds one shape per body and a decomposed body would have to become several bodies held together
+ * by joints. `world.ts`'s own refusal message said the runtime already accepted hulls, and it did
+ * not.
+ *
+ * **A part carries no offset and no rotation, and that is not a simplification.** A `ConvexShape` is
+ * a point cloud in the body's frame — `shape.ts` says so where it defines `vertices` — so a
+ * decomposition's parts are already where they belong. The kinematic `Body.parts` carries `ox/oy/oz`
+ * because it wraps shapes a caller built at the origin and placed afterwards; nothing here does
+ * that, and a field that is always zero is a field that is eventually set wrong.
+ *
+ * **This fills a set of manifolds where an ordinary pair fills one**, which is the shape
+ * `meshContact.ts` established: `prepareContact` appends a constraint rather than replacing one and
+ * `storeWarm` accumulates by pair, so the solver needed nothing new.
+ */
+/**
+ * How many contact planes one pair may produce.
+ *
+ * **The same number as `MAX_BODY_PARTS`, so a compound against a single convex shape can never
+ * overflow**: every part gets a plane. Two compounds can, at up to 32 by 32 part pairs against 32
+ * slots, and the overflow rule there is the mesh path's — stop when the set is full. That is the one
+ * place in this design where a contact can be dropped without anybody being told, and what would
+ * make it matter is two 32-part bodies interpenetrating deeply.
+ */
+export const MAX_PAIR_MANIFOLDS = MAX_BODY_PARTS;
+/** Whether a body is made of parts rather than of one shape. */
+export function isCompound(parts) {
+    return parts !== undefined;
+}
+/** How many shapes a body presents to the narrow phase, whichever way it is built. */
+export function partCount(shape, parts) {
+    if (parts !== undefined)
+        return parts.length;
+    return shape === undefined ? 0 : 1;
+}
+/** One of them, by index. */
+export function partAt(shape, parts, index) {
+    if (parts !== undefined)
+        return parts[index];
+    return shape;
+}
+/**
+ * The largest distance from a body's own origin to any point of any part.
+ *
+ * What `boundsOf` needs, and it is a maximum rather than a sum because every part is already in the
+ * body's frame: a part built off to one side carries that offset inside its own `boundRadius`.
+ */
+export function partsBoundRadius(parts) {
+    let radius = 0;
+    for (const part of parts)
+        if (part.boundRadius > radius)
+            radius = part.boundRadius;
+    return radius;
+}
+/** Scratch spheres, one per part of each side, so pruning allocates nothing. */
+const SPHERES_A = new Float64Array(MAX_BODY_PARTS * 4);
+const SPHERES_B = new Float64Array(MAX_BODY_PARTS * 4);
+const LOCAL = { minX: 0, minY: 0, minZ: 0, maxX: 0, maxY: 0, maxZ: 0 };
+const SCRATCH = createManifold();
+const MESH_SCRATCH = Array.from({ length: MAX_MESH_MANIFOLDS }, createManifold);
+/**
+ * A bounding sphere per part, in world, so the pair loop is a distance test and not a full collide.
+ *
+ * Computed once for each side of a pair rather than once per part pair: with 32 parts a side that is
+ * 64 bound computations instead of 1,024 of them. `shapeBounds` reads a part's own points, which are
+ * in the body frame, so the centre only has to be carried through the pose.
+ */
+function fillSpheres(shape, parts, pose, out) {
+    const count = partCount(shape, parts);
+    for (let i = 0; i < count; i++) {
+        const part = partAt(shape, parts, i);
+        shapeBounds(part, LOCAL);
+        const cx = (LOCAL.minX + LOCAL.maxX) * 0.5;
+        const cy = (LOCAL.minY + LOCAL.maxY) * 0.5;
+        const cz = (LOCAL.minZ + LOCAL.maxZ) * 0.5;
+        const hx = (LOCAL.maxX - LOCAL.minX) * 0.5;
+        const hy = (LOCAL.maxY - LOCAL.minY) * 0.5;
+        const hz = (LOCAL.maxZ - LOCAL.minZ) * 0.5;
+        rotate(pose, cx, cy, cz, out, i * 4);
+        out[i * 4] = out[i * 4] + pose.x;
+        out[i * 4 + 1] = out[i * 4 + 1] + pose.y;
+        out[i * 4 + 2] = out[i * 4 + 2] + pose.z;
+        out[i * 4 + 3] = Math.sqrt(hx * hx + hy * hy + hz * hz);
+    }
+    return count;
+}
+/** A vector through a pose's rotation, written into `out` at `at`. */
+function rotate(pose, x, y, z, out, at) {
+    const { qx, qy, qz, qw } = pose;
+    const tx = 2 * (qy * z - qz * y);
+    const ty = 2 * (qz * x - qx * z);
+    const tz = 2 * (qx * y - qy * x);
+    out[at] = x + qw * tx + (qy * tz - qz * ty);
+    out[at + 1] = y + qw * ty + (qz * tx - qx * tz);
+    out[at + 2] = z + qw * tz + (qx * ty - qy * tx);
+}
+/**
+ * Every touching pair of parts, as one manifold each.
+ *
+ * **A mesh partner is the pair this row exists for**, and it gets a rule of its own. A decomposed
+ * body falling onto a level is a dynamic compound against a static mesh, so refusing it would refuse
+ * the case. Each part goes through `collideMesh` unchanged, and the budget is divided between the
+ * parts that find candidates, **never below one each**. That is a deliberate departure from the mesh
+ * path's own first-come rule: `collideMesh` stops at eight and drops the rest, which is defensible
+ * when the ninth candidate is a triangle and indefensible when it is a whole limb of the body — one
+ * leg of a chair sinking through a floor while the other three hold.
+ */
+export function collideCompound(shapeA, partsA, poseA, shapeB, partsB, poseB, margin, out) {
+    const countA = fillSpheres(shapeA, partsA, poseA, SPHERES_A);
+    const countB = fillSpheres(shapeB, partsB, poseB, SPHERES_B);
+    if (countA === 0 || countB === 0)
+        return 0;
+    /*
+     * A mesh has no parts and never moves, so it is always the other side of the pair. Its budget is
+     * shared out below rather than spent by whichever part is tried first.
+     */
+    const meshSide = countA === 1 && isMesh(partAt(shapeA, partsA, 0))
+        ? 0
+        : countB === 1 && isMesh(partAt(shapeB, partsB, 0))
+            ? 1
+            : -1;
+    if (meshSide >= 0) {
+        return collideCompoundMesh(meshSide === 0 ? shapeB : shapeA, meshSide === 0 ? partsB : partsA, meshSide === 0 ? poseB : poseA, partAt(meshSide === 0 ? shapeA : shapeB, meshSide === 0 ? partsA : partsB, 0), meshSide === 0 ? poseA : poseB, meshSide === 0, margin, out);
+    }
+    let count = 0;
+    for (let i = 0; i < countA && count < out.length; i++) {
+        const ax = SPHERES_A[i * 4];
+        const ay = SPHERES_A[i * 4 + 1];
+        const az = SPHERES_A[i * 4 + 2];
+        const ar = SPHERES_A[i * 4 + 3] + margin;
+        const shapeI = partAt(shapeA, partsA, i);
+        for (let j = 0; j < countB && count < out.length; j++) {
+            const dx = SPHERES_B[j * 4] - ax;
+            const dy = SPHERES_B[j * 4 + 1] - ay;
+            const dz = SPHERES_B[j * 4 + 2] - az;
+            const reach = ar + SPHERES_B[j * 4 + 3];
+            if (dx * dx + dy * dy + dz * dz > reach * reach)
+                continue;
+            const shapeJ = partAt(shapeB, partsB, j);
+            if (!collideShapes(shapeI, poseA, shapeJ, poseB, margin, SCRATCH))
+                continue;
+            copyInto(SCRATCH, out[count], partKey(i, j));
+            count++;
+        }
+    }
+    return count;
+}
+/** Every part of a compound against one static triangle mesh, sharing the manifold budget. */
+function collideCompoundMesh(shape, parts, pose, mesh, meshPose, meshIsA, margin, out) {
+    const count = partCount(shape, parts);
+    /*
+     * At least one slot each, and the remainder shared. A part that touches the mesh always gets a
+     * contact plane; a part that touches it in three places gets three only if the budget allows.
+     */
+    const share = Math.max(1, Math.floor(out.length / Math.max(1, count)));
+    let filled = 0;
+    for (let i = 0; i < count && filled < out.length; i++) {
+        const part = partAt(shape, parts, i);
+        /*
+         * The scratch set is passed whole and the *copy* is what the share limits — slicing it here
+         * would allocate an array per part per pair, in the tick, which is the one thing this package
+         * does not do.
+         */
+        const found = meshIsA
+            ? collideMesh(mesh, meshPose, part, pose, margin, MESH_SCRATCH)
+            : collideMesh(part, pose, mesh, meshPose, margin, MESH_SCRATCH);
+        const room = Math.min(found, share, out.length - filled);
+        for (let m = 0; m < room && filled < out.length; m++) {
+            copyInto(MESH_SCRATCH[m], out[filled], partKey(i, 0));
+            filled++;
+        }
+    }
+    return filled;
+}
+/**
+ * The two part indices, folded into one number the feature id can carry.
+ *
+ * `meshContact.ts` folds a triangle index into every feature id for the same reason: warm starting
+ * pairs an accumulated impulse to a contact by identity, and a body resting across two parts would
+ * otherwise hand one part's impulse to the other on the tick a contact moves between them.
+ */
+function partKey(a, b) {
+    return a * MAX_BODY_PARTS + b;
+}
+/** A manifold copied into the pair's set, with the part pair folded into every feature id. */
+function copyInto(from, to, key) {
+    to.nx = from.nx;
+    to.ny = from.ny;
+    to.nz = from.nz;
+    to.count = from.count;
+    to.curvedA = from.curvedA;
+    to.curvedB = from.curvedB;
+    for (let i = 0; i < from.count; i++) {
+        to.points[i * 3] = from.points[i * 3] ?? 0;
+        to.points[i * 3 + 1] = from.points[i * 3 + 1] ?? 0;
+        to.points[i * 3 + 2] = from.points[i * 3 + 2] ?? 0;
+        to.separations[i] = from.separations[i] ?? 0;
+        to.featureIds[i] = (((key & 0xffff) << 12) ^ (from.featureIds[i] ?? 0)) | 0;
+    }
+}

package/dist/controller.d.ts

@@ -0,0 +1,351 @@
+import type { QueryFilter } from './query.ts';
+import type { ConvexShape } from './shape.ts';
+import type { PhysicsWorld } from './world.ts';
+/**
+ * A kinematic capsule character: the mechanism, and the feel that rides on it.
+ *
+ * **Kinematic and not a dynamic body.** A dynamic character falls over, cannot be steered crisply,
+ * and turns every design question about movement into a question about torque. Every shipping
+ * engine ships a kinematic controller for exactly that reason, and this one sweeps the same
+ * `PhysicsWorld` everything else queries, so it sees moving bodies as well as scenery.
+ *
+ * **Feel is here too, and that is a decision `AGENTS.md` records.** That file's worked example for
+ * the engine/game boundary once said a controller was game because "friction, coyote time and slide
+ * boost are one game's feel". The same file's *audio* rule draws the line correctly: the DSP graph
+ * is engine and which sounds play is game. A controller that takes a friction curve and a
+ * coyote-time duration takes numbers and time, which is what that file says engine APIs take; what
+ * stays game is which numbers. **What would make this wrong** is a parameter that only means
+ * something in one game.
+ *
+ * **Coyote time and jump buffering are counted in ticks**, never accumulated in a float of seconds.
+ * That is the determinism contract reaching into the feel layer, and the difference between a
+ * replay that matches and one that drifts by a frame after an hour of uptime.
+ */
+export declare const GROUNDED = 0;
+export declare const AIRBORNE = 1;
+export declare const SLIDING = 2;
+export type ControllerState = 0 | 1 | 2;
+export interface ControllerOptions {
+    radius?: number;
+    /** Half the cylindrical section, so total height is `2 * (halfHeight + radius)`. */
+    halfHeight?: number;
+    /** How high a lip may be and still be walked over. */
+    stepHeight?: number;
+    /** Cosine of the steepest walkable slope. Above it the character slides. */
+    slopeCos?: number;
+    maxSpeed?: number;
+    acceleration?: number;
+    deceleration?: number;
+    airControl?: number;
+    jumpSpeed?: number;
+    /** Upward velocity is cut to this fraction when the jump is released early. */
+    jumpCutoff?: number;
+    gravity?: number;
+    /** Ticks after leaving the ground during which a jump still counts. */
+    coyoteTicks?: number;
+    /** Ticks a jump press is remembered for, so pressing just before landing still fires. */
+    jumpBufferTicks?: number;
+    /** Extra downhill acceleration while sliding on too steep a surface. */
+    slideBoost?: number;
+    /** Impulse scale applied to dynamic bodies the character walks into. */
+    pushStrength?: number;
+    filter?: QueryFilter;
+    /**
+     * A surface to stand on beside the bodies, where the world has one.
+     *
+     * Consulted *after* the bodies and only when they found nothing walkable, so a consumer with
+     * both keeps whatever a collider said — a body is a thing that is there, and a surface is a
+     * description of where the ground is. Absent means bodies alone, which is every consumer that
+     * has not asked.
+     */
+    ground?: GroundProbe;
+}
+/**
+ * A surface the controller can stand on that is not a body.
+ *
+ * **Declared structurally, so nothing is imported in either direction.** `@driftengine/core`'s
+ * `GroundSurface` satisfies this exactly and neither package names the other — the same shape
+ * `ragdollFromBones` uses for a pose, and for the same reason: this package imports no other
+ * engine package, and a surface that knew about splines and ribbon meshes could not live here.
+ *
+ * **Why a character needs one at all.** An analytic surface answers *where the ground is in this
+ * column*; a collider answers *what is solid*. They are different questions and a banked deck is
+ * where they diverge — a world-axis box over a banked strip has a flat top at the strip's highest
+ * corner, so a character standing on the box hovers above the track through every corner. A
+ * consumer with such a deck could sweep bodies or stand on the deck, and never both.
+ *
+ * `atY` is the height of whatever is asking, so a route that passes over itself answers with the
+ * deck *under* the asker rather than the highest one in the column.
+ *
+ * **The field names were `nx`, `ny`, `nz` until 2026-08-28 and that was a defect**, because the
+ * paragraph above was not true: `SurfaceHit` spells them `normalX`, `normalY`, `normalZ`, so a real
+ * `GroundSurface` handed to a controller wrote three fields nothing read and left three fields
+ * nothing wrote. TypeScript allows the assignment — method parameters are bivariant — so it
+ * compiled, and a *flat* surface still behaved, because the scratch it was handed happens to start
+ * at `(0, 1, 0)`. Only a banked one showed it, by giving the character the normal of whatever body
+ * it last touched. Renamed rather than aliased: nothing in three consumers implements this
+ * interface, and a compile error naming the field is a one-line fix where a stale normal is a week.
+ */
+export interface GroundProbeHit {
+    /** Height of the surface in this column. */
+    y: number;
+    normalX: number;
+    normalY: number;
+    normalZ: number;
+}
+export interface GroundProbe {
+    sample(x: number, z: number, out: GroundProbeHit, atY?: number): boolean;
+}
+export interface ControllerInput {
+    /** Desired direction, in world units per second. Length above `maxSpeed` is clamped. */
+    moveX: number;
+    moveZ: number;
+    /**
+     * The third component, for a body whose up is not world Y. Absent means zero, which is what
+     * every caller with a level floor means and is arithmetically what they got before this existed.
+     *
+     * **Two components span the tangent plane only while up is world Y**, and `setUp` made up a
+     * parameter without making the input one. On a wall whose normal is +Z, up the wall is +Y and no
+     * pair of `moveX` and `moveZ` describes it: the input plane collapses onto a line, so a body that
+     * could stand on the wall could not be steered along it. Reported from outside by a consumer that
+     * gave up on the acceleration curves, the air control and the speed clamp entirely — writing
+     * `velX`/`velY`/`velZ` directly each tick with `acceleration: 0, deceleration: 0` so that
+     * `applyFeel` would leave the velocity alone — which is the whole of the feel this class exists
+     * to provide, bypassed to get one axis back.
+     *
+     * Read as a world direction and flattened onto the surface, exactly as the other two are. A
+     * caller supplying all three describes "forward" in whatever frame it is standing in.
+     */
+    moveY?: number;
+    /**
+     * Whether to flatten the move vector onto the plane the body is standing on. Absent means yes,
+     * which is what every caller before this got and what a body moving on one surface wants.
+     *
+     * **False is for a body between two surfaces, which is the one case the projection cannot
+     * serve.** Steering normally holds the along-up component out, steers the rest and puts it back,
+     * because that component is gravity and the jump rather than the stick. A body crossing a convex
+     * edge has a third thing there: while its frame rotates from the old face to the new, the correct
+     * direction of travel is neither face's tangent but a blend of them, held by the contacts already
+     * on the far side. Flattened onto the frame's current plane that command is turned aside — by
+     * **8.5 degrees early in a 90-degree crossing and more later** — and the body crawls the transfer
+     * instead of crossing it. Measured from outside on a sprint across a 90-degree convex edge:
+     * contacts decaying from four to none by tick 46, slipping at 46, falling by 51, **21 ticks of 90
+     * with nothing under it** against none when the velocity was written directly.
+     *
+     * **It is the projection and not the acceleration**, which the reporter separated before asking:
+     * the same crossing at acceleration times 15, 60, 240 and 2000 of `maxSpeed` gave 21 ticks every
+     * time. A lag would have improved.
+     *
+     * With this false the move vector is the velocity the body is steered toward *whole* — the
+     * along-up component included, because a caller that has taken responsibility for the direction
+     * has taken responsibility for all of it. Everything else still applies: the speed clamp, the
+     * acceleration and deceleration curves, `airControl` when off the ground, and gravity afterwards.
+     * That is the difference between this and the direct velocity write it exists to retire, which
+     * bypasses all four.
+     */
+    projectMove?: boolean;
+    /** Held, not edge-triggered: the controller does its own edge detection and buffering. */
+    jump: boolean;
+}
+export declare class CharacterController {
+    x: number;
+    y: number;
+    z: number;
+    velX: number;
+    velY: number;
+    velZ: number;
+    state: ControllerState;
+    /** The surface normal under the feet, meaningful when grounded or sliding. */
+    groundX: number;
+    groundY: number;
+    groundZ: number;
+    /**
+     * Which way is up for this body, as a unit vector. World up unless a caller says otherwise.
+     *
+     * **The whole of this class used to assume one axis, and none of it was wrong for doing so.**
+     * `velY` was the only representation of vertical velocity, `gravity` was a scalar applied to it,
+     * `slopeCos` was measured against world Y, `stepHeight` was a height only because up was fixed,
+     * and the three states were decided by a downward probe. That is a complete and correct
+     * controller for a body on a floor, and it cannot represent one on a wall at all.
+     *
+     * A consumer needing one had to reimplement the sweep, the step-over, the slope test and the
+     * ground probe — roughly nine hundred lines that would not share this file's contact code, so
+     * the two would drift. It is not a gecko's problem: it is every wall-crawler, every
+     * arbitrary-gravity level and every walker on the inside of a rotating station.
+     *
+     * Settable per tick, because a body walking around a corner changes frame continuously and the
+     * alternative is rebuilding the controller. Read through `setUp`, which normalises, so the dot
+     * products below can assume unit length.
+     */
+    upX: number;
+    upY: number;
+    upZ: number;
+    /**
+     * Which way this body falls, which is not always the way it stands.
+     *
+     * Tracks `up` until a caller sets it, and that default is the one that keeps every existing
+     * consumer unchanged. Kept separate because a support normal and a fall direction are different
+     * questions: a body clinging to a wall stands in the wall's frame and may still fall the way the
+     * world falls the moment it lets go.
+     */
+    private gravityX;
+    private gravityY;
+    private gravityZ;
+    /** Whether `setUp` should carry the fall direction with it. Cleared by `setGravityDirection`. */
+    private gravityFollowsUp;
+    /** Which body is being stood on, or −1. */
+    groundBody: number;
+    readonly shape: ConvexShape;
+    /**
+     * A ball the size of the capsule's foot, swept down to find ground.
+     *
+     * **A single ray from the capsule's axis is not enough**, and the failure is specific: a character
+     * balanced on the lip of a step has its axis over open air, the ray misses, it is reported
+     * airborne, and stepping is disabled — so it stalls on the edge of the very step it was climbing.
+     * A ball finds ground under any part of the foot. It is slightly smaller than the capsule so a
+     * wall pressed against the side cannot be mistaken for a floor.
+     */
+    readonly foot: ConvexShape;
+    readonly radius: number;
+    readonly halfHeight: number;
+    readonly stepHeight: number;
+    readonly slopeCos: number;
+    readonly maxSpeed: number;
+    readonly acceleration: number;
+    readonly deceleration: number;
+    readonly airControl: number;
+    readonly jumpSpeed: number;
+    readonly jumpCutoff: number;
+    readonly gravity: number;
+    readonly coyoteTicks: number;
+    readonly jumpBufferTicks: number;
+    readonly slideBoost: number;
+    readonly pushStrength: number;
+    readonly filter: QueryFilter | undefined;
+    /** Ticks since the character last had ground under it. */
+    private airTicks;
+    /** Ticks since a jump was pressed and not yet used. */
+    private bufferTicks;
+    private jumpHeld;
+    private rising;
+    private pose;
+    private hit;
+    /** `tryStep` needs its own, because it sweeps twice and `hit` is still being read afterwards. */
+    private stepHit;
+    private ground;
+    /** The analytic surface, where a consumer supplied one. See `GroundProbe`. */
+    private readonly probe;
+    /** Scratch for the probe, claimed once: `senseGround` runs every tick. */
+    private readonly probed;
+    constructor(options?: ControllerOptions);
+    /**
+     * Point this body's up at a direction, normalising it.
+     *
+     * A zero-length vector is refused rather than normalised into a NaN frame, because every dot
+     * product below would then answer NaN and the states would read as a body that is nowhere. It
+     * keeps the frame it had, which is the defined state the two-backends rule asks for in the
+     * renderer and is the right answer here for the same reason.
+     */
+    setUp(x: number, y: number, z: number): void;
+    /**
+     * Point the fall direction somewhere other than up, and stop it following.
+     *
+     * The sign convention is `up`'s: `gravity` is negative, so this is the direction a *rise* goes
+     * and gravity is applied against it. That is the same arithmetic as before — `velY += gravity *
+     * dt` with a gravity of −20 is an acceleration along −Y — generalised rather than reversed.
+     */
+    setGravityDirection(x: number, y: number, z: number): void;
+    /** This body's speed along its own up. What `velY` was when up was always world Y. */
+    get speedAlongUp(): number;
+    /** Set that component, leaving the tangent velocity exactly as it was. */
+    private setSpeedAlongUp;
+    /** Place the character, clearing whatever it was doing. */
+    teleport(x: number, y: number, z: number): void;
+    /** Advance one fixed tick. */
+    move(world: PhysicsWorld, dt: number, input: ControllerInput): void;
+    /**
+     * Let the analytic surface stop a descent, the way a body would have.
+     *
+     * **Without this a probe is a sensor and not a floor, and that was the shape of it until
+     * 2026-08-28.** `senseGround` read the surface and set `GROUNDED`, and nothing anywhere put the
+     * feet back on it: the sweep resolves bodies, the surface is not a body, so a character over a
+     * purely analytic world sank through it at gravity. It reported `GROUNDED` for three ticks while
+     * the gap stayed inside the six-centimetre tolerance, then went airborne and fell for ever —
+     * measured at ten metres under the floor after one second. Every test the seam had ran a single
+     * tick from feet already exactly on the surface, which is the one arrangement that cannot see it.
+     *
+     * A consumer with terrain therefore had to hold their own character up, which is the hundred
+     * lines they reported writing, and to write them again for anything else that stands on ground.
+     *
+     * **Only a descent this tick could have caused, which is what keeps it a floor rather than a
+     * magnet.** A character that is under the surface by more than this tick's fall is under it for
+     * some other reason — spawned in a cellar, walked into a tunnel, thrown through by an impulse —
+     * and hoisting them would be teleporting them through whatever is over their head. Rising is left
+     * alone entirely, so a jump leaves.
+     */
+    private standOnSurface;
+    private applyFeel;
+    /**
+     * Sweep, slide along whatever was hit, and try again — a fixed number of times.
+     *
+     * A step is attempted before sliding: lift by the step height, sweep forward, and drop. A
+     * character that slid off every lip would catch on kerbs and stair nosings, which reads as the
+     * world being sticky rather than as the character being short.
+     */
+    private sweep;
+    /**
+     * Lift, sweep forward, drop. Returns whether the whole step was taken.
+     *
+     * **The lift and the drop are along this body's up rather than along world Y**, which is what
+     * makes `stepHeight` a height rather than a Y offset. The forward part is the remainder of the
+     * move flattened into the tangent plane, for the same reason: what is left of a blocked move
+     * includes whatever of it was along up, and lifting by the step height and then also moving up
+     * would climb twice.
+     */
+    private tryStep;
+    /**
+     * Sweep the foot ball down, and fall back to a ray when what it finds is not walkable.
+     *
+     * The ball is what lets a character stand on the lip of a step: a ray from the capsule's axis has
+     * open air beneath it there, reports airborne, and disables the stepping that was carrying it up.
+     *
+     * **But a ball also brushes the side of the ledge it is walking off**, and a wall's normal is
+     * horizontal, so the ball alone reported *sliding* — which refused the coyote-time jump the
+     * character had every right to. So a non-walkable ball result is not trusted on its own: a ray
+     * down the axis decides whether there is genuinely a steep surface underfoot, or merely a wall
+     * beside it. Two cheap queries, and each covers the other's blind spot.
+     */
+    private senseGround;
+    /**
+     * Push a dynamic body the character walked into, so a crate is not a wall.
+     *
+     * **The push carries the character's speed, not its per-tick step.** Adding the displacement —
+     * four metres a second comes to 0.067 of a metre in a tick — is less than the impulse ground
+     * friction takes off a crate in the same tick, so the crate is pushed and immediately stopped and
+     * never moves at all. Measured: a 30 kg crate under 0.5 friction shed 0.082 a tick against 0.067
+     * put in.
+     *
+     * So it sets a *target* rather than accumulating: the body is brought up to the character's own
+     * speed into the surface, scaled by `pushStrength`, and never slowed if it is already faster.
+     * **What this gives up** is momentum transfer — a heavy crate moves as readily as a light one,
+     * because a kinematic character has no mass to trade. **What would make it wrong** is a consumer
+     * wanting mass to matter, and the answer then is a dynamic character, which §12 refuses for
+     * reasons that have nothing to do with this.
+     */
+    private push;
+    /**
+     * The capsule at this body's position, standing along this body's up.
+     *
+     * **The quaternion used to be left at identity**, which was right while up was always world Y
+     * and is the one thing that cannot be left out once it is not: a body on a wall whose capsule is
+     * still world-vertical is swept against the wall by its side rather than its foot, so it rests a
+     * radius away instead of standing on it.
+     *
+     * The shortest arc from world Y to `up`, built directly rather than through an axis-angle,
+     * because the half-angle form is one square root. **The half turn is the case that has to be
+     * written out**: an up of exactly −Y makes the cross product zero and `w` zero with it, which
+     * normalises to NaN, and there is no shortest arc to pick because every arc is the same length.
+     * A turn about X is chosen, which is as good as any and is stable.
+     */
+    private readPose;
+}