@jgengine/core 0.18.0 → 0.19.0

package/dist/movement/characterController.js

@@ -0,0 +1,216 @@
+function resolve(config) {
+    return {
+        radius: config.radius,
+        height: config.height,
+        stepHeight: config.stepHeight ?? 0.35,
+        maxSlopeDeg: config.maxSlopeDeg ?? 50,
+        skinWidth: config.skinWidth ?? 0.02,
+        crouchHeight: config.crouchHeight ?? config.height * 0.6,
+        snapDistance: config.snapDistance ?? 0.3,
+        maxSlides: config.maxSlides ?? 4,
+        mask: config.mask ?? 0xffffffff,
+    };
+}
+/**
+ * Collide-and-slide capsule controller over any {@link PhysicsBackend}: horizontal slide along walls, step-up over
+ * ledges, slope limit, ceiling test, crouch with headroom check, ground snapping, and moving-platform carry read from
+ * the ground body's velocity. Pure over the backend's `shapecast`/`overlap`; the caller owns input and gravity policy.
+ *
+ * @capability character-controller capsule walk over the physics backend — slide, step-up, slopes, crouch, platforms
+ */
+export function createCharacterController(initial) {
+    let cfg = resolve(initial);
+    let state = {
+        position: [0, 0, 0],
+        verticalVelocity: 0,
+        grounded: false,
+        groundNormal: [0, 1, 0],
+        groundBody: null,
+        crouching: false,
+    };
+    function currentHeight() {
+        return state.crouching ? cfg.crouchHeight : cfg.height;
+    }
+    function shapeFor(height) {
+        const halfHeight = Math.max(0, height / 2 - cfg.radius);
+        return { kind: "capsule", radius: cfg.radius, halfHeight };
+    }
+    function centerFor(position, height) {
+        return [position[0], position[1] + height / 2, position[2]];
+    }
+    function walkable(normal) {
+        return normal[1] >= Math.cos((cfg.maxSlopeDeg * Math.PI) / 180);
+    }
+    function cast(backend, from, height, motion, self) {
+        return backend.shapecast({
+            shape: shapeFor(height),
+            position: centerFor(from, height),
+            motion,
+            mask: cfg.mask,
+            ...(self === undefined ? {} : { exclude: self }),
+        });
+    }
+    /** Move along `motion`, stopping `skinWidth` short of the first hit. Returns the fraction travelled and the hit. */
+    function sweep(backend, pos, height, motion, self) {
+        const len = Math.hypot(motion[0], motion[1], motion[2]);
+        if (!(len > 1e-9))
+            return { fraction: 1, hit: null };
+        const hit = cast(backend, pos, height, motion, self);
+        if (hit === null) {
+            pos[0] += motion[0];
+            pos[1] += motion[1];
+            pos[2] += motion[2];
+            return { fraction: 1, hit: null };
+        }
+        const back = cfg.skinWidth / len;
+        const fraction = Math.max(0, hit.toi - back);
+        pos[0] += motion[0] * fraction;
+        pos[1] += motion[1] * fraction;
+        pos[2] += motion[2] * fraction;
+        return { fraction, hit };
+    }
+    return {
+        config: () => cfg,
+        retune(next) {
+            cfg = resolve({ ...cfg, ...next });
+        },
+        state: () => state,
+        snapshot: () => ({
+            position: [state.position[0], state.position[1], state.position[2]],
+            verticalVelocity: state.verticalVelocity,
+            grounded: state.grounded,
+            groundNormal: [state.groundNormal[0], state.groundNormal[1], state.groundNormal[2]],
+            groundBody: state.groundBody,
+            crouching: state.crouching,
+        }),
+        restore(next) {
+            state = {
+                position: [next.position[0], next.position[1], next.position[2]],
+                verticalVelocity: next.verticalVelocity,
+                grounded: next.grounded,
+                groundNormal: [next.groundNormal[0], next.groundNormal[1], next.groundNormal[2]],
+                groundBody: next.groundBody,
+                crouching: next.crouching,
+            };
+        },
+        shape: () => shapeFor(currentHeight()),
+        center: () => centerFor(state.position, currentHeight()),
+        move(backend, input) {
+            const { dt, self } = input;
+            const result = {
+                moved: [0, 0, 0],
+                grounded: false,
+                groundNormal: [0, 1, 0],
+                hitWall: false,
+                hitCeiling: false,
+                steppedUp: false,
+                crouchBlocked: false,
+            };
+            const start = [state.position[0], state.position[1], state.position[2]];
+            const pos = [start[0], start[1], start[2]];
+            if (input.crouch === true && !state.crouching) {
+                state.crouching = true;
+            }
+            else if (input.crouch === false && state.crouching) {
+                const standing = backend.overlap({
+                    shape: shapeFor(cfg.height),
+                    position: centerFor(pos, cfg.height),
+                    mask: cfg.mask,
+                    ...(self === undefined ? {} : { exclude: self }),
+                });
+                if (standing.length === 0)
+                    state.crouching = false;
+                else
+                    result.crouchBlocked = true;
+            }
+            const height = currentHeight();
+            let carry = [0, 0, 0];
+            if (state.grounded && state.groundBody !== null) {
+                const ground = backend.body(state.groundBody);
+                if (ground !== null)
+                    carry = [ground.velocity[0] * dt, ground.velocity[1] * dt, ground.velocity[2] * dt];
+            }
+            let remaining = [input.motion[0] + carry[0], 0, input.motion[2] + carry[2]];
+            for (let i = 0; i < cfg.maxSlides; i += 1) {
+                const { hit, fraction } = sweep(backend, pos, height, remaining, self);
+                if (hit === null)
+                    break;
+                const left = [remaining[0] * (1 - fraction), remaining[1] * (1 - fraction), remaining[2] * (1 - fraction)];
+                const dot = left[0] * hit.normal[0] + left[1] * hit.normal[1] + left[2] * hit.normal[2];
+                const slid = [
+                    left[0] - hit.normal[0] * dot,
+                    left[1] - hit.normal[1] * dot,
+                    left[2] - hit.normal[2] * dot,
+                ];
+                if (!walkable(hit.normal)) {
+                    result.hitWall = true;
+                    slid[1] = 0;
+                    if (cfg.stepHeight > 0 && !result.steppedUp && tryStepUp(backend, pos, height, remaining, self)) {
+                        result.steppedUp = true;
+                        result.hitWall = false;
+                        break;
+                    }
+                }
+                if (Math.hypot(slid[0], slid[1], slid[2]) < 1e-6)
+                    break;
+                remaining = slid;
+            }
+            if (input.gravity !== undefined)
+                state.verticalVelocity -= input.gravity * dt;
+            if (input.jumpVelocity !== undefined && state.grounded) {
+                state.verticalVelocity = input.jumpVelocity;
+                state.grounded = false;
+            }
+            const wasGrounded = state.grounded;
+            let vertical = state.verticalVelocity * dt + carry[1];
+            if (wasGrounded && vertical <= 0)
+                vertical -= cfg.snapDistance;
+            const { hit: verticalHit } = sweep(backend, pos, height, [0, vertical, 0], self);
+            if (verticalHit !== null && vertical > 0) {
+                result.hitCeiling = true;
+                state.verticalVelocity = 0;
+                state.grounded = false;
+                state.groundBody = null;
+            }
+            else if (verticalHit !== null && walkable(verticalHit.normal)) {
+                state.grounded = true;
+                state.groundNormal = [verticalHit.normal[0], verticalHit.normal[1], verticalHit.normal[2]];
+                state.groundBody = verticalHit.body;
+                if (state.verticalVelocity < 0)
+                    state.verticalVelocity = 0;
+                // A contact at t=0 means touching or already inside; lift by the skin so the next casts start clear.
+                if (verticalHit.toi <= 0)
+                    pos[1] += cfg.skinWidth;
+            }
+            else {
+                state.grounded = false;
+                state.groundBody = null;
+                state.groundNormal = [0, 1, 0];
+            }
+            state.position = pos;
+            result.moved = [pos[0] - start[0], pos[1] - start[1], pos[2] - start[2]];
+            result.grounded = state.grounded;
+            result.groundNormal = [state.groundNormal[0], state.groundNormal[1], state.groundNormal[2]];
+            return result;
+        },
+    };
+    function tryStepUp(backend, pos, height, motion, self) {
+        const probe = [pos[0], pos[1], pos[2]];
+        const up = sweep(backend, probe, height, [0, cfg.stepHeight, 0], self);
+        if (up.hit !== null && up.fraction <= 0)
+            return false;
+        const forward = sweep(backend, probe, height, motion, self);
+        if (forward.hit !== null && forward.fraction < 0.05)
+            return false;
+        const drop = -(probe[1] - pos[1]);
+        const down = sweep(backend, probe, height, [0, drop, 0], self);
+        if (down.hit === null || !walkable(down.hit.normal))
+            return false;
+        if (probe[1] <= pos[1] + 1e-6)
+            return false;
+        pos[0] = probe[0];
+        pos[1] = probe[1];
+        pos[2] = probe[2];
+        return true;
+    }
+}

package/dist/movement/freeFlight.d.ts

@@ -0,0 +1,119 @@
+import { type AnalogMoveIntent, type CollisionObstacle, type MovementKeysState } from "./movementModel.js";
+import { type AxisBinding } from "../input/axisInput.js";
+import type { PointerAxisState } from "../input/pointerAxis.js";
+import type { ChaseCameraTuning } from "../runtime/cameraDirector.js";
+/** Free-flight families — character-scale 6DOF movement, distinct from vehicle aerodynamics. */
+export type FreeFlightMode = "creative" | "spectator" | "noclip" | "hover";
+/** Per-axis bindings for free-flight — which actions drive each flight axis. Positive is forward/right/up. */
+export interface FreeFlightBindings {
+    /** Forward/back — default `moveForward` / `moveBack` (W/S). */
+    forward?: AxisBinding;
+    /** Strafe right/left — default `moveRight` / `moveLeft` (D/A). */
+    strafe?: AxisBinding;
+    /** Ascend/descend — default `jump` / `crouch` (Space / Ctrl+C). */
+    vertical?: AxisBinding;
+    /** Sprint — default `sprint` (Shift) held. */
+    sprint?: AxisBinding;
+}
+/** Data-first tuning for one free-flight profile. */
+export interface FreeFlightTuning {
+    mode: FreeFlightMode;
+    /** Horizontal base speed (units/s) before sprint. Default 8. */
+    speed?: number;
+    /** Vertical base speed for ascend/descend. Default = `speed`. */
+    verticalSpeed?: number;
+    /** Sprint multiplier while shift is held. Default 1.8. */
+    sprintMultiplier?: number;
+    /** Lerp rate toward target velocity. Default 20. */
+    acceleration?: number;
+    /** Extra damping applied when no input (0 = rely on lerp). Default 0. */
+    damping?: number;
+    /** Downward acceleration for hover mode. Default 0 (weightless). */
+    gravity?: number;
+    /** Upward thrust acceleration while ascending in hover. Default 32. */
+    thrust?: number;
+    /** When true, forward moves along the look pitch (spectator). Default false. */
+    alignWithLook?: boolean;
+    /** Top vertical fall speed in hover. Default 20. */
+    maxFallSpeed?: number;
+    /** Whether to slide against world solids. Default true for creative/hover, false for spectator/noclip. */
+    collide?: boolean;
+    /** Axis bindings for this flight profile — which actions drive each axis. Unlisted axes keep the defaults above. */
+    bindings?: FreeFlightBindings;
+    /** Camera POV while this flight is active — chase tuning overlay applied on mount, cleared on dismount. Null clears. */
+    camera?: ChaseCameraTuning | null;
+}
+/** Velocity state for a free-flight actor — serializable and ownable by the caller. */
+export interface FreeFlightState {
+    vx: number;
+    vy: number;
+    vz: number;
+}
+/** Intent for one free-flight tick — forward/right from WASD/analog, vertical from jump/crouch. */
+export interface FreeFlightIntent {
+    forward: number;
+    right: number;
+    vertical: number;
+    sprint: boolean;
+    moving: boolean;
+}
+/** World displacement produced by one free-flight tick. */
+export interface FreeFlightStep {
+    stepX: number;
+    stepY: number;
+    stepZ: number;
+}
+/** Stateful handle for any free-flight actor with snapshot/restore/retune. */
+export interface FreeFlightController {
+    tick(dt: number, intent: FreeFlightIntent, yaw: number, pitch?: number): FreeFlightStep;
+    velocity(): readonly [number, number, number];
+    snapshot(): FreeFlightState;
+    restore(next: FreeFlightState): void;
+    retune(next: FreeFlightTuning): void;
+    reset(): void;
+}
+/** Create an empty flight velocity state. */
+export declare function createFreeFlightState(): FreeFlightState;
+/**
+ * Translate held keys + analog into a free-flight intent.
+ * Vertical is `space - (control|c)` so jump ascends and crouch descends — the same
+ * keys that walk/jump/crouch use, re-mapped for flight without re-binding.
+ */
+export declare function resolveFreeFlightIntent(keys: MovementKeysState, analog: AnalogMoveIntent | null | undefined): FreeFlightIntent;
+/**
+ * Translate live input (held actions + analog + pointer) into a flight intent using
+ * per-profile axis bindings. Unlisted bindings fall back to the defaults above so
+ * existing games keep WASD/Space/Ctrl/Shift without declaring anything.
+ */
+export declare function resolveFreeFlightIntentFromInput(isDown: (action: string) => boolean, value: (action: string) => number, pointer: PointerAxisState | null, bindings?: FreeFlightBindings): FreeFlightIntent;
+/**
+ * Advance one frame of free-flight kinematics.
+ * Horizontal uses yaw-relative strafe (A = left, D = right) — never roll/bank.
+ * Vertical is independent of pitch unless `alignWithLook` is true (spectator).
+ */
+export declare function advanceFreeFlight(state: FreeFlightState, intent: FreeFlightIntent, yaw: number, pitch: number | undefined, dt: number, tuning: FreeFlightTuning): FreeFlightStep;
+/** Resolve a flight step against world solids (XZ slide + Y clamp). */
+export declare function resolveFlightStep(position: readonly [number, number, number], stepX: number, stepY: number, stepZ: number, obstacles: readonly CollisionObstacle[], radius?: number): {
+    stepX: number;
+    stepY: number;
+    stepZ: number;
+};
+/**
+ * Totally free flight for any actor — character, camera, drone, or debug rig.
+ * Horizontal is always yaw-relative strafe; vertical is jump/crouch. Use `alignWithLook`
+ * for a 6DOF spectator that flies where the camera looks.
+ * @capability free-flight camera-relative creative/spectator/noclip/hover flight with correct strafe, sprint, and optional gravity
+ */
+export declare function createFreeFlightController(initialTuning: FreeFlightTuning, options?: {
+    yaw?: number;
+    pitch?: number;
+    state?: FreeFlightState;
+}): FreeFlightController;
+/** Preset for Minecraft-like creative flight — weightless, collides, yaw-relative strafe. */
+export declare const CREATIVE_FLIGHT_TUNING: FreeFlightTuning;
+/** Preset for spectator — weightless, noclips, flies where the camera looks. */
+export declare const SPECTATOR_FLIGHT_TUNING: FreeFlightTuning;
+/** Preset for noclip — weightless, noclips, yaw-relative with independent vertical. */
+export declare const NOCLIP_FLIGHT_TUNING: FreeFlightTuning;
+/** Preset for hover/jetpack — gravity + thrust, useful for short bursts. */
+export declare const HOVER_FLIGHT_TUNING: FreeFlightTuning;

package/dist/movement/freeFlight.js

@@ -0,0 +1,294 @@
+import { MOVEMENT_TUNING } from "./movementModel.js";
+import { DEFAULT_OBSTACLE_PLAYER_RADIUS } from "./movementModel.js";
+import { sampleAxisBindings } from "../input/axisInput.js";
+const ANALOG_EPSILON = 0.02;
+/** Create an empty flight velocity state. */
+export function createFreeFlightState() {
+    return { vx: 0, vy: 0, vz: 0 };
+}
+const DEFAULT_FORWARD_BINDING = { positive: ["moveForward"], negative: ["moveBack"] };
+const DEFAULT_STRAFE_BINDING = { positive: ["moveRight"], negative: ["moveLeft"] };
+const DEFAULT_VERTICAL_BINDING = { positive: ["jump"], negative: ["crouch", "control", "c"] };
+const DEFAULT_SPRINT_BINDING = { positive: ["sprint"] };
+/**
+ * Translate held keys + analog into a free-flight intent.
+ * Vertical is `space - (control|c)` so jump ascends and crouch descends — the same
+ * keys that walk/jump/crouch use, re-mapped for flight without re-binding.
+ */
+export function resolveFreeFlightIntent(keys, analog) {
+    let forward = (keys.w ? 1 : 0) - (keys.s ? 1 : 0);
+    let right = (keys.d ? 1 : 0) - (keys.a ? 1 : 0);
+    if (analog !== undefined && analog !== null) {
+        forward = Math.abs(analog.forward) < ANALOG_EPSILON ? 0 : Math.max(-1, Math.min(1, analog.forward));
+        right = Math.abs(analog.right) < ANALOG_EPSILON ? 0 : Math.max(-1, Math.min(1, analog.right));
+    }
+    const vertical = (keys.space ? 1 : 0) - (keys.control || keys.c ? 1 : 0);
+    const sprint = keys.shift && vertical >= 0;
+    const moving = forward !== 0 || right !== 0 || vertical !== 0;
+    return { forward, right, vertical, sprint, moving };
+}
+/**
+ * Translate live input (held actions + analog + pointer) into a flight intent using
+ * per-profile axis bindings. Unlisted bindings fall back to the defaults above so
+ * existing games keep WASD/Space/Ctrl/Shift without declaring anything.
+ */
+export function resolveFreeFlightIntentFromInput(isDown, value, pointer, bindings) {
+    const forwardBinding = bindings?.forward ?? DEFAULT_FORWARD_BINDING;
+    const strafeBinding = bindings?.strafe ?? DEFAULT_STRAFE_BINDING;
+    const verticalBinding = bindings?.vertical ?? DEFAULT_VERTICAL_BINDING;
+    const sprintBinding = bindings?.sprint ?? DEFAULT_SPRINT_BINDING;
+    const forward = sampleAxisBindings({ forward: forwardBinding }, isDown, pointer, undefined, value).forward;
+    const right = sampleAxisBindings({ strafe: strafeBinding }, isDown, pointer, undefined, value).strafe;
+    const vertical = sampleAxisBindings({ vertical: verticalBinding }, isDown, pointer, undefined, value).vertical;
+    const sprintVal = sampleAxisBindings({ sprint: sprintBinding }, isDown, pointer, { sprint: { min: 0, max: 1 } }, value).sprint;
+    const sprint = sprintVal > 0.5;
+    const moving = forward !== 0 || right !== 0 || vertical !== 0;
+    return { forward, right, vertical, sprint, moving };
+}
+/**
+ * Advance one frame of free-flight kinematics.
+ * Horizontal uses yaw-relative strafe (A = left, D = right) — never roll/bank.
+ * Vertical is independent of pitch unless `alignWithLook` is true (spectator).
+ */
+export function advanceFreeFlight(state, intent, yaw, pitch, dt, tuning) {
+    const delta = Math.min(dt, MOVEMENT_TUNING.maxFrameSeconds);
+    if (delta <= 0)
+        return { stepX: 0, stepY: 0, stepZ: 0 };
+    const speed = tuning.speed ?? 8;
+    const verticalSpeed = tuning.verticalSpeed ?? speed;
+    const sprintMult = tuning.sprintMultiplier ?? 1.8;
+    const accel = tuning.acceleration ?? 20;
+    const damping = tuning.damping ?? 0;
+    const gravity = tuning.gravity ?? 0;
+    const thrust = tuning.thrust ?? 32;
+    const maxFall = tuning.maxFallSpeed ?? 20;
+    const align = tuning.alignWithLook === true && pitch !== undefined;
+    const sprintScale = intent.sprint ? sprintMult : 1;
+    let targetX = 0;
+    let targetZ = 0;
+    let targetY = 0;
+    if (align) {
+        const cp = Math.cos(pitch);
+        const sp = Math.sin(pitch);
+        const sy = Math.sin(yaw);
+        const cy = Math.cos(yaw);
+        const fx = sy * cp;
+        const fy = sp;
+        const fz = cy * cp;
+        const rx = cy;
+        const rz = -sy;
+        const rawX = fx * intent.forward + rx * intent.right;
+        const rawY = fy * intent.forward;
+        const rawZ = fz * intent.forward + rz * intent.right;
+        const hLen = Math.hypot(rawX, rawY, rawZ);
+        if (hLen > 1e-6) {
+            const scale = Math.min(1, hLen) / hLen;
+            const sx = rawX * scale;
+            const sy2 = rawY * scale;
+            const sz = rawZ * scale;
+            const horizScale = speed * sprintScale;
+            const vertScale = verticalSpeed * sprintScale;
+            targetX = sx * horizScale;
+            targetY = sy2 * horizScale + intent.vertical * vertScale;
+            targetZ = sz * horizScale;
+        }
+        else {
+            targetY = intent.vertical * verticalSpeed * sprintScale;
+        }
+    }
+    else {
+        const sy = Math.sin(yaw);
+        const cy = Math.cos(yaw);
+        let fx = sy;
+        let fz = cy;
+        const lenSq = fx * fx + fz * fz;
+        if (lenSq < 1e-6) {
+            fx = 0;
+            fz = -1;
+        }
+        else {
+            const inv = 1 / Math.sqrt(lenSq);
+            fx *= inv;
+            fz *= inv;
+        }
+        const rx = -fz;
+        const rz = fx;
+        let rawX = fx * intent.forward + rx * intent.right;
+        let rawZ = fz * intent.forward + rz * intent.right;
+        const len = Math.hypot(rawX, rawZ);
+        if (len > 1e-6) {
+            const scale = Math.min(1, len) / len;
+            rawX *= scale;
+            rawZ *= scale;
+        }
+        else {
+            rawX = 0;
+            rawZ = 0;
+        }
+        targetX = rawX * speed * sprintScale;
+        targetZ = rawZ * speed * sprintScale;
+        targetY = intent.vertical * verticalSpeed * sprintScale;
+    }
+    if (gravity > 0) {
+        const alpha = 1 - Math.exp(-accel * delta);
+        state.vx += (targetX - state.vx) * alpha;
+        state.vz += (targetZ - state.vz) * alpha;
+        if (damping > 0 && !intent.moving) {
+            const damp = Math.exp(-damping * delta);
+            state.vx *= damp;
+            state.vz *= damp;
+        }
+        const thrustAccel = intent.vertical * thrust;
+        state.vy += (thrustAccel - gravity) * delta;
+        if (intent.vertical !== 0) {
+            const vyTarget = targetY;
+            const vyAlpha = 1 - Math.exp(-accel * delta);
+            state.vy += (vyTarget - state.vy) * vyAlpha * 0.5;
+        }
+        if (damping > 0 && intent.vertical === 0) {
+            state.vy *= Math.exp(-damping * delta * 0.5);
+        }
+        if (state.vy < -maxFall)
+            state.vy = -maxFall;
+    }
+    else {
+        const alpha = 1 - Math.exp(-accel * delta);
+        state.vx += (targetX - state.vx) * alpha;
+        state.vy += (targetY - state.vy) * alpha;
+        state.vz += (targetZ - state.vz) * alpha;
+        if (damping > 0 && !intent.moving) {
+            const damp = Math.exp(-damping * delta);
+            state.vx *= damp;
+            state.vy *= damp;
+            state.vz *= damp;
+        }
+    }
+    return { stepX: state.vx * delta, stepY: state.vy * delta, stepZ: state.vz * delta };
+}
+/** Resolve a flight step against world solids (XZ slide + Y clamp). */
+export function resolveFlightStep(position, stepX, stepY, stepZ, obstacles, radius = DEFAULT_OBSTACLE_PLAYER_RADIUS) {
+    const feetY = position[1];
+    const headY = feetY + 1.8;
+    let clampedY = stepY;
+    const nextY = feetY + stepY;
+    const nextHead = nextY + 1.8;
+    for (const ob of obstacles) {
+        const ox = ob.position[0] + (ob.offset?.[0] ?? 0);
+        const oy = ob.position[1] + (ob.offset?.[1] ?? 0);
+        const oz = ob.position[2] + (ob.offset?.[2] ?? 0);
+        const hx = ob.halfExtents?.[0] ?? 0.5;
+        const hy = ob.halfExtents?.[1] ?? 0.5;
+        const hz = ob.halfExtents?.[2] ?? 0.5;
+        if (ob.boxes !== undefined && ob.boxes.length > 0) {
+            for (const box of ob.boxes) {
+                const minX = ox + box.min[0] - radius;
+                const maxX = ox + box.max[0] + radius;
+                const minY = oy + box.min[1];
+                const maxY = oy + box.max[1];
+                const minZ = oz + box.min[2] - radius;
+                const maxZ = oz + box.max[2] + radius;
+                const insideXZ = position[0] > minX && position[0] < maxX && position[2] > minZ && position[2] < maxZ;
+                if (!insideXZ)
+                    continue;
+                if (stepY > 0 && feetY < maxY && nextHead > minY && nextHead > maxY && feetY < minY) {
+                    clampedY = Math.min(clampedY, minY - headY - 1e-3);
+                }
+                else if (stepY < 0 && headY > minY && nextY < maxY && nextY < minY && headY > maxY) {
+                    clampedY = Math.max(clampedY, maxY - feetY + 1e-3);
+                }
+            }
+            continue;
+        }
+        const minX = ox - hx - radius;
+        const maxX = ox + hx + radius;
+        const minY = oy - hy;
+        const maxY = oy + hy;
+        const minZ = oz - hz - radius;
+        const maxZ = oz + hz + radius;
+        const insideXZ = position[0] > minX && position[0] < maxX && position[2] > minZ && position[2] < maxZ;
+        if (!insideXZ)
+            continue;
+        if (stepY > 0 && feetY < maxY && nextHead > minY && nextHead > maxY && feetY < minY) {
+            clampedY = Math.min(clampedY, minY - headY - 1e-3);
+        }
+        else if (stepY < 0 && headY > minY && nextY < maxY && nextY < minY && headY > maxY) {
+            clampedY = Math.max(clampedY, maxY - feetY + 1e-3);
+        }
+    }
+    return { stepX, stepY: clampedY, stepZ };
+}
+/**
+ * Totally free flight for any actor — character, camera, drone, or debug rig.
+ * Horizontal is always yaw-relative strafe; vertical is jump/crouch. Use `alignWithLook`
+ * for a 6DOF spectator that flies where the camera looks.
+ * @capability free-flight camera-relative creative/spectator/noclip/hover flight with correct strafe, sprint, and optional gravity
+ */
+export function createFreeFlightController(initialTuning, options = {}) {
+    let tuning = initialTuning;
+    const state = options.state !== undefined ? { ...options.state } : createFreeFlightState();
+    let yaw = options.yaw ?? 0;
+    let pitch = options.pitch ?? 0;
+    return {
+        tick(dt, intent, nextYaw, nextPitch) {
+            yaw = nextYaw;
+            if (nextPitch !== undefined)
+                pitch = nextPitch;
+            return advanceFreeFlight(state, intent, yaw, pitch, dt, tuning);
+        },
+        velocity: () => [state.vx, state.vy, state.vz],
+        snapshot: () => ({ ...state }),
+        restore(next) {
+            state.vx = next.vx;
+            state.vy = next.vy;
+            state.vz = next.vz;
+        },
+        retune(next) {
+            tuning = next;
+        },
+        reset() {
+            state.vx = 0;
+            state.vy = 0;
+            state.vz = 0;
+        },
+    };
+}
+/** Preset for Minecraft-like creative flight — weightless, collides, yaw-relative strafe. */
+export const CREATIVE_FLIGHT_TUNING = {
+    mode: "creative",
+    speed: 8,
+    verticalSpeed: 8,
+    sprintMultiplier: 2.2,
+    acceleration: 22,
+    collide: true,
+};
+/** Preset for spectator — weightless, noclips, flies where the camera looks. */
+export const SPECTATOR_FLIGHT_TUNING = {
+    mode: "spectator",
+    speed: 12,
+    verticalSpeed: 12,
+    sprintMultiplier: 2.5,
+    acceleration: 18,
+    collide: false,
+    alignWithLook: true,
+};
+/** Preset for noclip — weightless, noclips, yaw-relative with independent vertical. */
+export const NOCLIP_FLIGHT_TUNING = {
+    mode: "noclip",
+    speed: 14,
+    verticalSpeed: 14,
+    sprintMultiplier: 3,
+    acceleration: 18,
+    collide: false,
+    alignWithLook: false,
+};
+/** Preset for hover/jetpack — gravity + thrust, useful for short bursts. */
+export const HOVER_FLIGHT_TUNING = {
+    mode: "hover",
+    speed: 6,
+    verticalSpeed: 6,
+    sprintMultiplier: 1.6,
+    acceleration: 16,
+    gravity: 18,
+    thrust: 34,
+    collide: true,
+};

package/dist/movement/glideModel.d.ts

@@ -40,6 +40,9 @@ export interface GlideModel {
     step(dt: number, input?: GlideInput, externalVelocity?: GlideVec3): GlideStep;
     pose(): GlideStep;
     launch(position: GlideVec3, heading: number, initialSpeed?: number): void;
+    /** Plain JSON copy of the glider's position, velocity and heading. */
+    snapshot(): GlideStep;
+    restore(next: GlideStep): void;
 }
 /**
  * Gliding/wingsuit descent control — lift, drag, and steering from a launch.

package/dist/movement/glideModel.js

@@ -32,6 +32,12 @@ export function createGlideModel(config = {}) {
             vz = Math.cos(heading) * initialSpeed;
         },
         pose: snapshot,
+        snapshot,
+        restore(next) {
+            [x, y, z] = next.position;
+            [vx, vy, vz] = next.velocity;
+            heading = next.heading;
+        },
         step(dt, input = {}, externalVelocity) {
             if (dt <= 0)
                 return snapshot();

package/dist/movement/grappleSwing.d.ts

@@ -28,6 +28,8 @@ export interface GrappleSwing {
     fire(anchor: SwingVec3, from: SwingVec3): void;
     release(): void;
     state(): GrappleSwingState;
+    /** Puts a {@link GrappleSwing.state} back; `anchor: null` detaches. */
+    restore(next: GrappleSwingState): void;
     /** Constrain one frame. `reeling` shortens the rope; returns the corrected position/velocity. */
     step(position: SwingVec3, velocity: SwingVec3, dt: number, reeling?: boolean): GrappleSwingStep;
 }

package/dist/movement/grappleSwing.js

@@ -18,7 +18,11 @@ export function createGrappleSwing(config = {}) {
         release() {
             anchor = null;
         },
-        state: () => ({ attached: anchor !== null, anchor, ropeLength }),
+        state: () => ({ attached: anchor !== null, anchor: anchor === null ? null : [anchor[0], anchor[1], anchor[2]], ropeLength }),
+        restore(next) {
+            anchor = next.anchor === null ? null : [next.anchor[0], next.anchor[1], next.anchor[2]];
+            ropeLength = next.ropeLength;
+        },
         step(position, velocity, dt, reeling = false) {
             if (anchor === null || dt <= 0)
                 return { position, velocity };