@aura3d/engine 4.1.3 → 4.3.0

package/dist/game/motion/handBounce.js

@@ -0,0 +1,267 @@
+import { resolveBone } from "./boneAttach.js";
+const lerp = (a, b, t) => a + (b - a) * t;
+const smoothstep = (t) => (t <= 0 ? 0 : t >= 1 ? 1 : t * t * (3 - 2 * t));
+export function resolveHandBounceConfig(options = {}) {
+    const ballRadius = options.ballRadius ?? 0.13;
+    const floorY = options.floorY ?? 0;
+    return {
+        hand: options.hand ?? "right",
+        ballRadius,
+        floorY,
+        armReach: options.armReach ?? 0.55,
+        ballGap: options.ballGap ?? 0.09,
+        standing: { period: 0.46, palmTop: 1.02, palmPush: 0.62, ...options.standing },
+        running: { period: 0.3, palmTop: 0.92, palmPush: 0.6, ...options.running },
+        runSpeed: options.runSpeed ?? 0.45,
+        phases: { rideEnd: 0.35, palmTurn: 0.6, floorAt: 0.66, catchFrom: 0.92, ...options.phases },
+        floorBallY: floorY + ballRadius
+    };
+}
+/** Palm height, ball height and body effort for phase `t` (0..1). `shoulderY` is the live world Y of the dribbling shoulder. */
+export function handBounceCycle(config, t, shoulderY, moving = false) {
+    const gait = moving ? config.running : config.standing;
+    const { rideEnd, palmTurn, floorAt } = config.phases;
+    const top = Math.min(config.floorY + gait.palmTop, shoulderY - 0.3);
+    const push = Math.max(config.floorY + gait.palmPush, shoulderY - config.armReach);
+    const low = push - 0.04;
+    let palmY;
+    let effort;
+    if (t < rideEnd) {
+        const s = t / rideEnd;
+        effort = Math.pow(s, 1.6);
+        palmY = lerp(top, push, effort);
+    }
+    else if (t < palmTurn) {
+        const s = (t - rideEnd) / (palmTurn - rideEnd);
+        effort = 1;
+        palmY = lerp(push, low, 1 - (1 - s) * (1 - s));
+    }
+    else {
+        const s = (t - palmTurn) / (1 - palmTurn);
+        effort = t < floorAt ? 1 : 1 - smoothstep((t - floorAt) / (1 - floorAt));
+        palmY = lerp(low, top, smoothstep(s));
+    }
+    return { palmY, ballY: handBounceBallY(config, t, palmY, push - config.ballGap, top - config.ballGap), effort };
+}
+/**
+ * Ball centre height for phase `t`. `palmY` is the palm the ball rides while in contact (pass the RENDERED palm so the ball
+ * cannot leave a hand that could not follow its target); `releaseY` is the ball height when it leaves the palm and `catchY`
+ * the height of the palm that receives it. In the air the ball falls to the floor and rebounds, so the bounce point is always
+ * `config.floorBallY`.
+ */
+export function handBounceBallY(config, t, palmY, releaseY, catchY) {
+    const { rideEnd, floorAt, catchFrom } = config.phases;
+    if (t < rideEnd)
+        return palmY - config.ballGap;
+    if (t < floorAt) {
+        const s = (t - rideEnd) / (floorAt - rideEnd);
+        return lerp(releaseY, config.floorBallY, Math.pow(s, 1.2));
+    }
+    if (t >= catchFrom)
+        return palmY - config.ballGap;
+    const s = (t - floorAt) / (catchFrom - floorAt);
+    return lerp(config.floorBallY, catchY, 1 - Math.pow(1 - s, 1.7));
+}
+/**
+ * 1 while the palm is on the ball (riding down, and the catch at the top), 0 while the ball is free in the air. Anything that
+ * offsets the ball from the palm (stride lead, outward nudge) is scaled by `1 - weight`, so the ball is glued to the palm at the
+ * contact points however fast the handler runs.
+ */
+export function handBounceContactWeight(config, phase) {
+    const { rideEnd, floorAt, catchFrom } = config.phases;
+    const t = ((phase % 1) + 1) % 1;
+    if (t < rideEnd)
+        return 1;
+    if (t < floorAt)
+        return 1 - smoothstep((t - rideEnd) / 0.1);
+    if (t < catchFrom)
+        return smoothstep((t - floorAt - 0.1) / (catchFrom - floorAt - 0.1));
+    return 1;
+}
+/** Horizontal ball position: on the palm at contact, drifting ahead with the handler's stride only while the ball is in the air. */
+export function handBounceBallXZ(config, palm, holder, phase) {
+    const free = 1 - handBounceContactWeight(config, phase);
+    const ox = palm[0] - holder.x;
+    const oz = palm[2] - holder.z;
+    const olen = Math.hypot(ox, oz) || 1;
+    return {
+        x: palm[0] + (ox / olen) * 0.02 * free + holder.vx * 0.04 * free,
+        z: palm[2] + (oz / olen) * 0.02 * free + holder.vz * 0.04 * free
+    };
+}
+/** Clamp a palm target into the arm's reach sphere around the shoulder (a target the arm cannot reach makes the hand miss the ball). */
+export function clampPalmReach(shoulder, target, reach) {
+    const dx = target[0] - shoulder[0];
+    const dy = target[1] - shoulder[1];
+    const dz = target[2] - shoulder[2];
+    const d = Math.hypot(dx, dy, dz);
+    if (d <= reach || d < 1e-9)
+        return [target[0], target[1], target[2]];
+    const k = reach / d;
+    return [shoulder[0] + dx * k, shoulder[1] + dy * k, shoulder[2] + dz * k];
+}
+/** Upper-body pitch angles (radians, forward positive) for a handler bouncing the ball: stationary handlers crouch into the push, runners bend at the waist. */
+export function handBounceOverlayAngles(effort, moving, leanScale = 1) {
+    if (moving) {
+        const lean = (1.28 + 0.77 * effort) * leanScale;
+        return { spine: lean * 0.55, chest: lean * 0.45, head: -lean * 0.6 };
+    }
+    return { spine: (0.2 + 0.3 * effort) * leanScale, chest: (0.12 + 0.2 * effort) * leanScale, head: -0.22 };
+}
+const SIDE_PREFIX = { left: "left", right: "right" };
+export function createHandBounce(options = {}) {
+    const config = resolveHandBounceConfig(options);
+    const side = SIDE_PREFIX[config.hand];
+    const names = options.boneNames;
+    const pick = (role, fallback) => (names ? resolveBone(names, role) ?? fallback : fallback);
+    const spineName = pick("spine", "Spine");
+    const chestName = names ? names.find((n) => /chest/i.test(n) && !/upper/i.test(n)) ?? spineName : "Chest";
+    const headName = pick("head", "Head");
+    const armUpper = pick(`${side}UpperArm`, config.hand === "left" ? "LeftUpperArm" : "RightUpperArm");
+    const armFore = pick(`${side}Forearm`, config.hand === "left" ? "LeftForearm" : "RightForearm");
+    let phase = 0;
+    let moving = false;
+    let releaseY = config.floorBallY + 0.4;
+    let active = false;
+    let contact = 1;
+    let effort = 0;
+    let palmY = config.floorY + config.standing.palmTop;
+    let ball = [0, config.floorBallY, 0];
+    let prevBall;
+    let lastDt = 1 / 60;
+    let floorContact = false;
+    const frame = () => ({ phase, moving, contact, effort, palmY, ball: [ball[0], ball[1], ball[2]], floorContact });
+    return {
+        config,
+        step(dt, input) {
+            if (!(dt > 0))
+                throw new Error("createHandBounce.step: dt must be a positive fixed step");
+            moving = input.moving ?? (input.speed ?? 0) > config.runSpeed;
+            const gait = moving ? config.running : config.standing;
+            if (!active) {
+                active = true;
+                phase = 0;
+                prevBall = undefined;
+            }
+            phase = input.hold ? 0 : (phase + dt / gait.period) % 1;
+            const cyc = handBounceCycle(config, phase, input.shoulderY, moving);
+            effort = input.hold ? 0 : cyc.effort;
+            contact = handBounceContactWeight(config, phase);
+            prevBall = [ball[0], ball[1], ball[2]];
+            lastDt = dt;
+            if (input.palm) {
+                const palm = input.palm;
+                if (input.hold) {
+                    ball = [palm[0], palm[1], palm[2]];
+                }
+                else {
+                    const at = handBounceBallXZ(config, palm, input.holder, phase);
+                    if (phase < config.phases.rideEnd)
+                        releaseY = palm[1] - config.ballGap;
+                    ball = [at.x, handBounceBallY(config, phase, palm[1], releaseY, palm[1] - config.ballGap), at.z];
+                }
+                palmY = palm[1];
+            }
+            else {
+                palmY = cyc.palmY;
+                ball = [input.holder.x, cyc.ballY, input.holder.z];
+            }
+            floorContact = ball[1] <= config.floorBallY + 0.02;
+            return frame();
+        },
+        state() {
+            return { phase, moving, contact, effort, palmY, ball: [ball[0], ball[1], ball[2]], releaseY, floorContact, active };
+        },
+        overlay(leanScale = 1) {
+            const a = handBounceOverlayAngles(effort, moving, leanScale);
+            return {
+                mode: moving ? "overlay" : "pose",
+                effort,
+                bones: { [spineName]: { pitch: a.spine }, [chestName]: { pitch: a.chest }, [headName]: { pitch: a.head } },
+                arm: { upper: armUpper, forearm: armFore }
+            };
+        },
+        release() {
+            const dt = Math.max(lastDt, 1e-6);
+            const p = prevBall ?? ball;
+            active = false;
+            return {
+                position: [ball[0], ball[1], ball[2]],
+                velocity: [(ball[0] - p[0]) / dt, (ball[1] - p[1]) / dt, (ball[2] - p[2]) / dt]
+            };
+        },
+        pickup(at) {
+            active = true;
+            phase = config.phases.catchFrom;
+            releaseY = at[1];
+            ball = [at[0], at[1], at[2]];
+            prevBall = undefined;
+        },
+        reset() {
+            phase = 0;
+            active = false;
+            moving = false;
+            prevBall = undefined;
+            ball = [0, config.floorBallY, 0];
+        }
+    };
+}
+/** Limits the Aura Hoops dribble is held to. */
+export const DEFAULT_HAND_BOUNCE_LIMITS = { meet: 0.12, floorContact: 0.55, floorError: 0.02, maxDistance: 0.9 };
+/** Probe: feed per-frame palm and ball world positions of a dribble; returns the distances the game must keep small. Call it from QA hooks and tools/game-checks. */
+export function measureHandBall(samples, options = {}) {
+    const config = resolveHandBounceConfig(options);
+    const limits = { ...DEFAULT_HAND_BOUNCE_LIMITS, ...options.limits };
+    let meetMax = 0;
+    let floorMax = Number.NaN;
+    let floorPalm = Number.NaN;
+    let maxDistance = 0;
+    let lowest = Infinity;
+    let floorSamples = 0;
+    let meetSamples = 0;
+    let used = 0;
+    for (const s of samples) {
+        if (s.dribbling === false)
+            continue;
+        used += 1;
+        const d = Math.hypot(s.palm[0] - s.ball[0], s.palm[1] - s.ball[1], s.palm[2] - s.ball[2]);
+        maxDistance = Math.max(maxDistance, d);
+        lowest = Math.min(lowest, s.ball[1]);
+        const t = ((s.phase % 1) + 1) % 1;
+        if (t < 0.04 || t > config.phases.catchFrom + 0.01) {
+            meetMax = Math.max(meetMax, d);
+            meetSamples += 1;
+        }
+        if (s.ball[1] <= config.floorBallY + 0.02) {
+            floorMax = Number.isNaN(floorMax) ? d : Math.max(floorMax, d);
+            const h = s.palm[1] - config.floorY;
+            floorPalm = Number.isNaN(floorPalm) ? h : Math.max(floorPalm, h);
+            floorSamples += 1;
+        }
+    }
+    const floorError = used === 0 ? Number.NaN : Math.abs(lowest - config.floorBallY);
+    const failures = [];
+    if (used === 0)
+        failures.push("no dribble samples");
+    if (meetSamples > 0 && meetMax > limits.meet)
+        failures.push(`palm to ball at the meet ${meetMax.toFixed(3)} m > ${limits.meet} m`);
+    if (floorSamples > 0 && floorMax > limits.floorContact)
+        failures.push(`palm to ball at the floor contact ${floorMax.toFixed(3)} m > ${limits.floorContact} m`);
+    if (used > 0 && floorError > limits.floorError)
+        failures.push(`ball centre misses the floor by ${floorError.toFixed(3)} m > ${limits.floorError} m`);
+    if (maxDistance > limits.maxDistance)
+        failures.push(`ball strays ${maxDistance.toFixed(3)} m from the hand > ${limits.maxDistance} m`);
+    return {
+        samples: used,
+        meetMax,
+        floorContactMax: floorMax,
+        floorContactPalmHeightMax: floorPalm,
+        floorError,
+        maxDistance,
+        floorSamples,
+        meetSamples,
+        ok: failures.length === 0,
+        failures
+    };
+}
+//# sourceMappingURL=handBounce.js.map

package/dist/game/motion/handBounce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handBounce.js","sourceRoot":"","sources":["../../../../../packages/game/src/motion/handBounce.ts"],"names":[],"mappings":"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"}

package/dist/game/motion/impact.d.ts

@@ -0,0 +1,113 @@
+export type V3 = [number, number, number];
+export interface ImpactBoxCollider {
+    readonly kind: "box";
+    readonly id: string;
+    readonly center: readonly [number, number, number];
+    readonly half: readonly [number, number, number];
+    /** Rotation about Y in radians. */
+    readonly yaw?: number;
+    readonly tag?: string;
+    readonly restitution?: number;
+    readonly friction?: number;
+}
+export interface ImpactSphereCollider {
+    readonly kind: "sphere";
+    readonly id: string;
+    readonly center: readonly [number, number, number];
+    readonly radius: number;
+    readonly tag?: string;
+    readonly restitution?: number;
+    readonly friction?: number;
+}
+export type ImpactCollider = ImpactBoxCollider | ImpactSphereCollider;
+export interface ImpactBody {
+    position: V3;
+    velocity: V3;
+    radius: number;
+}
+export interface Impact {
+    readonly colliderId: string;
+    readonly tag: string | undefined;
+    readonly point: V3;
+    /** Unit normal pointing out of the collider, towards the body. */
+    readonly normal: V3;
+    /** Approach speed along the normal before the response, m/s. */
+    readonly speed: number;
+    readonly impulse: number;
+}
+export interface ImpactWorldOptions {
+    readonly colliders: readonly ImpactCollider[];
+    readonly restitution?: number;
+    readonly friction?: number;
+    /** Contacts slower than this resolve but do not emit an event (resting contact). Default 0.5 m/s. */
+    readonly eventMinSpeed?: number;
+    readonly onImpact?: (impact: Impact) => void;
+}
+export interface ImpactWorld {
+    step(body: ImpactBody, dt: number): Impact[];
+    add(collider: ImpactCollider): void;
+    remove(id: string): void;
+    reset(): void;
+}
+/**
+ * Swept-sphere collision against static boxes (optionally yawed) and spheres. A body moving fast cannot
+ * tunnel through a wall or gate; each new contact emits one `Impact` (continuous sliding does not repeat).
+ * Box corners are treated as sharp expanded boxes (slightly conservative at corners).
+ */
+export declare function createImpactWorld(options: ImpactWorldOptions): ImpactWorld;
+export interface HitStop {
+    trigger(ms: number): void;
+    update(realDtSeconds: number): void;
+    /** Multiply the simulation time step by this; 1 normally, near 0 during a hit-stop. */
+    timeScale(): number;
+    readonly active: boolean;
+}
+export declare function createHitStop(frozenScale?: number): HitStop;
+export interface CameraShake {
+    add(trauma: number): void;
+    update(dt: number): {
+        readonly x: number;
+        readonly y: number;
+        readonly roll: number;
+    };
+    readonly trauma: number;
+}
+/** Trauma-based shake: offset scales with trauma squared, decays linearly, deterministic (no Math.random). */
+export declare function createCameraShake(options?: {
+    readonly decayPerSecond?: number;
+    readonly maxOffset?: number;
+    readonly maxRoll?: number;
+}): CameraShake;
+export interface ParticleBurst {
+    readonly point: V3;
+    readonly normal: V3;
+    readonly count: number;
+    readonly speed: number;
+}
+export interface ImpactFeedbackOptions {
+    readonly hitStop?: HitStop;
+    readonly shake?: CameraShake;
+    /** Play a cue by name at a gain 0..1 (wire to a cue bank). */
+    readonly cue?: (name: string, gain: number) => void;
+    readonly cueName?: string;
+    readonly particles?: (burst: ParticleBurst) => void;
+    readonly onDamage?: (amount: number, impact: Impact) => void;
+    /** Impact speed (m/s) that maps to full strength. Default 12. */
+    readonly fullSpeed?: number;
+    /** Hit-stop duration range in ms. Defaults 30 to 80. */
+    readonly hitStopMs?: readonly [number, number];
+    readonly damagePerSpeed?: number;
+    readonly minSpeed?: number;
+}
+export interface ImpactFeedbackResult {
+    readonly strength: number;
+    readonly hitStopMs: number;
+    readonly trauma: number;
+    readonly damage: number;
+    readonly particleCount: number;
+}
+/** The standard feedback bundle for a solid hit: hit-stop, camera shake, sound, particles and damage, scaled by speed. */
+export declare function createImpactFeedback(options: ImpactFeedbackOptions): {
+    handle(impact: Impact): ImpactFeedbackResult;
+};
+//# sourceMappingURL=impact.d.ts.map

package/dist/game/motion/impact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact.d.ts","sourceRoot":"","sources":["../../../../../packages/game/src/motion/impact.ts"],"names":[],"mappings":"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"}

package/dist/game/motion/impact.js

@@ -0,0 +1,233 @@
+const EPS = 1e-9;
+function rotY(v, yaw) {
+    const c = Math.cos(yaw);
+    const s = Math.sin(yaw);
+    return [c * v[0] + s * v[2], v[1], -s * v[0] + c * v[2]];
+}
+function sweepBox(p, d, radius, box) {
+    const yaw = box.yaw ?? 0;
+    const rel = [p[0] - box.center[0], p[1] - box.center[1], p[2] - box.center[2]];
+    const lp = rotY(rel, -yaw);
+    const ld = rotY(d, -yaw);
+    const h = [box.half[0] + radius, box.half[1] + radius, box.half[2] + radius];
+    const inside = Math.abs(lp[0]) < h[0] && Math.abs(lp[1]) < h[1] && Math.abs(lp[2]) < h[2];
+    if (inside) {
+        let axis = 0;
+        let best = Number.POSITIVE_INFINITY;
+        for (let i = 0; i < 3; i += 1) {
+            const pen = h[i] - Math.abs(lp[i]);
+            if (pen < best) {
+                best = pen;
+                axis = i;
+            }
+        }
+        const n = [0, 0, 0];
+        n[axis] = lp[axis] >= 0 ? 1 : -1;
+        return { t: 0, normal: rotY(n, yaw), collider: box };
+    }
+    let tmin = 0;
+    let tmax = 1;
+    let axisHit = -1;
+    let sign = 1;
+    for (let i = 0; i < 3; i += 1) {
+        const o = lp[i];
+        const dir = ld[i];
+        if (Math.abs(dir) < EPS) {
+            if (Math.abs(o) >= h[i])
+                return undefined;
+            continue;
+        }
+        let t1 = (-h[i] - o) / dir;
+        let t2 = (h[i] - o) / dir;
+        let s = -1;
+        if (t1 > t2) {
+            [t1, t2] = [t2, t1];
+            s = 1;
+        }
+        if (t1 > tmin) {
+            tmin = t1;
+            axisHit = i;
+            sign = s;
+        }
+        tmax = Math.min(tmax, t2);
+        if (tmin > tmax)
+            return undefined;
+    }
+    if (axisHit < 0)
+        return undefined;
+    const n = [0, 0, 0];
+    n[axisHit] = sign;
+    return { t: tmin, normal: rotY(n, yaw), collider: box };
+}
+function sweepSphere(p, d, radius, s) {
+    const R = radius + s.radius;
+    const m = [p[0] - s.center[0], p[1] - s.center[1], p[2] - s.center[2]];
+    const a = d[0] * d[0] + d[1] * d[1] + d[2] * d[2];
+    const c = m[0] * m[0] + m[1] * m[1] + m[2] * m[2] - R * R;
+    if (c < 0) {
+        const len = Math.hypot(m[0], m[1], m[2]) || 1;
+        return { t: 0, normal: [m[0] / len, m[1] / len, m[2] / len], collider: s };
+    }
+    if (a < EPS)
+        return undefined;
+    const b = m[0] * d[0] + m[1] * d[1] + m[2] * d[2];
+    if (b >= 0)
+        return undefined;
+    const disc = b * b - a * c;
+    if (disc < 0)
+        return undefined;
+    const t = (-b - Math.sqrt(disc)) / a;
+    if (t < 0 || t > 1)
+        return undefined;
+    const hit = [m[0] + d[0] * t, m[1] + d[1] * t, m[2] + d[2] * t];
+    const len = Math.hypot(hit[0], hit[1], hit[2]) || 1;
+    return { t, normal: [hit[0] / len, hit[1] / len, hit[2] / len], collider: s };
+}
+/**
+ * Swept-sphere collision against static boxes (optionally yawed) and spheres. A body moving fast cannot
+ * tunnel through a wall or gate; each new contact emits one `Impact` (continuous sliding does not repeat).
+ * Box corners are treated as sharp expanded boxes (slightly conservative at corners).
+ */
+export function createImpactWorld(options) {
+    const colliders = new Map();
+    for (const c of options.colliders)
+        colliders.set(c.id, c);
+    const baseRestitution = options.restitution ?? 0.2;
+    const baseFriction = options.friction ?? 0.1;
+    const eventMin = options.eventMinSpeed ?? 0.5;
+    let touching = new Set();
+    return {
+        add(c) {
+            colliders.set(c.id, c);
+        },
+        remove(id) {
+            colliders.delete(id);
+            touching.delete(id);
+        },
+        reset() {
+            touching = new Set();
+        },
+        step(body, dt) {
+            const impacts = [];
+            const now = new Set();
+            let remaining = dt;
+            for (let iter = 0; iter < 4 && remaining > 0; iter += 1) {
+                const d = [body.velocity[0] * remaining, body.velocity[1] * remaining, body.velocity[2] * remaining];
+                let best;
+                for (const c of colliders.values()) {
+                    const hit = c.kind === "box" ? sweepBox(body.position, d, body.radius, c) : sweepSphere(body.position, d, body.radius, c);
+                    if (hit !== undefined && (best === undefined || hit.t < best.t))
+                        best = hit;
+                }
+                if (best === undefined) {
+                    body.position[0] += d[0];
+                    body.position[1] += d[1];
+                    body.position[2] += d[2];
+                    remaining = 0;
+                    break;
+                }
+                const skin = 1e-4;
+                const tt = Math.max(0, best.t);
+                body.position[0] += d[0] * tt + best.normal[0] * skin;
+                body.position[1] += d[1] * tt + best.normal[1] * skin;
+                body.position[2] += d[2] * tt + best.normal[2] * skin;
+                const n = best.normal;
+                const vn = body.velocity[0] * n[0] + body.velocity[1] * n[1] + body.velocity[2] * n[2];
+                const approach = Math.max(0, -vn);
+                const e = best.collider.restitution ?? baseRestitution;
+                const mu = best.collider.friction ?? baseFriction;
+                if (vn < 0) {
+                    const tx = body.velocity[0] - vn * n[0];
+                    const ty = body.velocity[1] - vn * n[1];
+                    const tz = body.velocity[2] - vn * n[2];
+                    const keep = Math.max(0, 1 - mu);
+                    body.velocity[0] = tx * keep - e * vn * n[0];
+                    body.velocity[1] = ty * keep - e * vn * n[1];
+                    body.velocity[2] = tz * keep - e * vn * n[2];
+                }
+                const id = best.collider.id;
+                now.add(id);
+                if (!touching.has(id) && approach >= eventMin) {
+                    const point = [body.position[0] - n[0] * body.radius, body.position[1] - n[1] * body.radius, body.position[2] - n[2] * body.radius];
+                    const impact = { colliderId: id, tag: best.collider.tag, point, normal: [n[0], n[1], n[2]], speed: approach, impulse: approach * (1 + e) };
+                    impacts.push(impact);
+                    options.onImpact?.(impact);
+                }
+                remaining *= 1 - tt;
+                if (tt >= 1)
+                    break;
+            }
+            touching = now;
+            return impacts;
+        }
+    };
+}
+export function createHitStop(frozenScale = 0.02) {
+    let remaining = 0;
+    return {
+        trigger(ms) {
+            remaining = Math.max(remaining, Math.max(0, ms) / 1000);
+        },
+        update(dt) {
+            remaining = Math.max(0, remaining - Math.max(0, dt));
+        },
+        timeScale() {
+            return remaining > 0 ? frozenScale : 1;
+        },
+        get active() {
+            return remaining > 0;
+        }
+    };
+}
+/** Trauma-based shake: offset scales with trauma squared, decays linearly, deterministic (no Math.random). */
+export function createCameraShake(options = {}) {
+    const decay = options.decayPerSecond ?? 1.6;
+    const maxOffset = options.maxOffset ?? 0.12;
+    const maxRoll = options.maxRoll ?? 0.04;
+    let trauma = 0;
+    let t = 0;
+    return {
+        add(amount) {
+            trauma = Math.min(1, trauma + Math.max(0, amount));
+        },
+        update(dt) {
+            t += Math.max(0, dt);
+            trauma = Math.max(0, trauma - decay * Math.max(0, dt));
+            const s = trauma * trauma;
+            return {
+                x: s * maxOffset * Math.sin(t * 61.3 + 1.7),
+                y: s * maxOffset * Math.sin(t * 47.9 + 4.1),
+                roll: s * maxRoll * Math.sin(t * 39.1 + 2.9)
+            };
+        },
+        get trauma() {
+            return trauma;
+        }
+    };
+}
+/** The standard feedback bundle for a solid hit: hit-stop, camera shake, sound, particles and damage, scaled by speed. */
+export function createImpactFeedback(options) {
+    const full = options.fullSpeed ?? 12;
+    const [msLo, msHi] = options.hitStopMs ?? [30, 80];
+    const minSpeed = options.minSpeed ?? 0.5;
+    return {
+        handle(impact) {
+            const strength = Math.max(0, Math.min(1, impact.speed / full));
+            if (impact.speed < minSpeed)
+                return { strength, hitStopMs: 0, trauma: 0, damage: 0, particleCount: 0 };
+            const hitStopMs = msLo + (msHi - msLo) * strength;
+            const trauma = 0.2 + 0.8 * strength;
+            const damage = (options.damagePerSpeed ?? 0) * impact.speed;
+            const particleCount = Math.round(4 + 28 * strength);
+            options.hitStop?.trigger(hitStopMs);
+            options.shake?.add(trauma);
+            if (options.cue !== undefined)
+                options.cue(options.cueName ?? "impact", 0.25 + 0.75 * strength);
+            options.particles?.({ point: impact.point, normal: impact.normal, count: particleCount, speed: 1 + 5 * strength });
+            if (damage > 0)
+                options.onDamage?.(damage, impact);
+            return { strength, hitStopMs, trauma, damage, particleCount };
+        }
+    };
+}
+//# sourceMappingURL=impact.js.map