@remix-gg/three 0.1.1

package/dist/input/gestures.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Pure pointer-gesture state machine. No DOM, no three, no clock of its own —
+ * every decision is a function of the samples you feed it, which is what makes
+ * the thresholds testable instead of aspirational.
+ *
+ * Coordinates are DESIGN units (720x1080), so the thresholds mean the same
+ * physical distance on every screen.
+ */
+export type PointerPhase = 'down' | 'move' | 'up' | 'cancel';
+export type PointerSample = {
+    id: number;
+    x: number;
+    y: number;
+    /** Milliseconds, monotonic. */
+    time: number;
+    phase: PointerPhase;
+};
+export type GestureThresholds = {
+    tapMaxMs: number;
+    tapMaxTravel: number;
+    dragMinTravel: number;
+    swipeMinTravel: number;
+    /** Design units per second. */
+    swipeMinSpeed: number;
+};
+export declare const DEFAULT_THRESHOLDS: GestureThresholds;
+export type Pointer = {
+    readonly id: number;
+    readonly x: number;
+    readonly y: number;
+    /** Movement since the previous sample. */
+    readonly dx: number;
+    readonly dy: number;
+    readonly startX: number;
+    readonly startY: number;
+    /** Milliseconds held so far. */
+    readonly duration: number;
+    /** Path length, not displacement — a circle back to the start is not a tap. */
+    readonly travel: number;
+    readonly dragging: boolean;
+};
+/** A live pointer plus the bookkeeping the reducer needs. */
+export type TrackedPointer = Pointer & {
+    readonly startTime: number;
+};
+export type GestureState = {
+    readonly pointers: readonly TrackedPointer[];
+    readonly pinchStart: number | null;
+    readonly pinchLast: number | null;
+};
+export type TapEvent = {
+    pointerId: number;
+    x: number;
+    y: number;
+    duration: number;
+};
+export type DragEvent = {
+    pointerId: number;
+    x: number;
+    y: number;
+    dx: number;
+    dy: number;
+    totalX: number;
+    totalY: number;
+};
+export type SwipeDirection = 'up' | 'down' | 'left' | 'right';
+export type SwipeEvent = {
+    pointerId: number;
+    x: number;
+    y: number;
+    dx: number;
+    dy: number;
+    direction: SwipeDirection;
+    /** Design units per second. */
+    speed: number;
+};
+export type PinchEvent = {
+    /** Distance relative to the start of this two-finger gesture. */
+    scale: number;
+    /** Distance relative to the previous sample. */
+    delta: number;
+    distance: number;
+    centerX: number;
+    centerY: number;
+};
+export type GestureEvent = {
+    type: 'press';
+    data: TapEvent;
+} | {
+    type: 'release';
+    data: TapEvent;
+} | {
+    type: 'tap';
+    data: TapEvent;
+} | {
+    type: 'drag';
+    data: DragEvent;
+} | {
+    type: 'swipe';
+    data: SwipeEvent;
+} | {
+    type: 'pinch';
+    data: PinchEvent;
+};
+export type GestureEventMap = {
+    press: TapEvent;
+    release: TapEvent;
+    tap: TapEvent;
+    drag: DragEvent;
+    swipe: SwipeEvent;
+    pinch: PinchEvent;
+};
+export declare function createGestureState(): GestureState;
+/**
+ * Folds one pointer sample into the gesture state.
+ *
+ * Returns a new state — the input is never mutated, so a caller can replay
+ * samples in a test without the previous run bleeding through.
+ */
+export declare function reduceGestures(state: GestureState, sample: PointerSample, thresholds?: GestureThresholds): {
+    state: GestureState;
+    events: GestureEvent[];
+};
+//# sourceMappingURL=gestures.d.ts.map

package/dist/input/gestures.d.ts.map

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

package/dist/input/gestures.js

@@ -0,0 +1,171 @@
+/**
+ * Pure pointer-gesture state machine. No DOM, no three, no clock of its own —
+ * every decision is a function of the samples you feed it, which is what makes
+ * the thresholds testable instead of aspirational.
+ *
+ * Coordinates are DESIGN units (720x1080), so the thresholds mean the same
+ * physical distance on every screen.
+ */
+export const DEFAULT_THRESHOLDS = {
+    tapMaxMs: 250,
+    tapMaxTravel: 12,
+    dragMinTravel: 8,
+    swipeMinTravel: 60,
+    swipeMinSpeed: 200,
+};
+export function createGestureState() {
+    return { pointers: [], pinchStart: null, pinchLast: null };
+}
+function distance(a, b) {
+    return Math.hypot(a.x - b.x, a.y - b.y);
+}
+function directionOf(dx, dy) {
+    if (Math.abs(dx) >= Math.abs(dy))
+        return dx >= 0 ? 'right' : 'left';
+    return dy >= 0 ? 'down' : 'up';
+}
+/**
+ * Folds one pointer sample into the gesture state.
+ *
+ * Returns a new state — the input is never mutated, so a caller can replay
+ * samples in a test without the previous run bleeding through.
+ */
+export function reduceGestures(state, sample, thresholds = DEFAULT_THRESHOLDS) {
+    const pointers = state.pointers.map((p) => ({ ...p }));
+    const events = [];
+    const index = pointers.findIndex((p) => p.id === sample.id);
+    if (sample.phase === 'down') {
+        // A duplicate `down` for a live id means we missed the `up` (pointer
+        // capture lost, view swapped). Restart the pointer rather than tracking two.
+        if (index >= 0)
+            pointers.splice(index, 1);
+        pointers.push({
+            id: sample.id,
+            x: sample.x,
+            y: sample.y,
+            dx: 0,
+            dy: 0,
+            startX: sample.x,
+            startY: sample.y,
+            startTime: sample.time,
+            duration: 0,
+            travel: 0,
+            dragging: false,
+        });
+        events.push({
+            type: 'press',
+            data: { pointerId: sample.id, x: sample.x, y: sample.y, duration: 0 },
+        });
+    }
+    else if (index >= 0) {
+        const pointer = pointers[index];
+        const dx = sample.x - pointer.x;
+        const dy = sample.y - pointer.y;
+        pointer.x = sample.x;
+        pointer.y = sample.y;
+        pointer.dx = dx;
+        pointer.dy = dy;
+        pointer.travel += Math.hypot(dx, dy);
+        pointer.duration = sample.time - pointer.startTime;
+        const displacement = Math.hypot(pointer.x - pointer.startX, pointer.y - pointer.startY);
+        if (sample.phase === 'move') {
+            if (!pointer.dragging && displacement > thresholds.dragMinTravel)
+                pointer.dragging = true;
+            if (pointer.dragging) {
+                events.push({
+                    type: 'drag',
+                    data: {
+                        pointerId: pointer.id,
+                        x: pointer.x,
+                        y: pointer.y,
+                        dx,
+                        dy,
+                        totalX: pointer.x - pointer.startX,
+                        totalY: pointer.y - pointer.startY,
+                    },
+                });
+            }
+        }
+        else {
+            // Native views and trackpads may coalesce a short drag into a down/up
+            // pair whose endpoints differ. Preserve that terminal movement: without
+            // it a control built on `input.on('drag')` receives no drag at all even
+            // though the pointer travelled across the game.
+            if (sample.phase === 'up' &&
+                displacement > thresholds.dragMinTravel &&
+                (dx !== 0 || dy !== 0)) {
+                events.push({
+                    type: 'drag',
+                    data: {
+                        pointerId: pointer.id,
+                        x: pointer.x,
+                        y: pointer.y,
+                        dx,
+                        dy,
+                        totalX: pointer.x - pointer.startX,
+                        totalY: pointer.y - pointer.startY,
+                    },
+                });
+            }
+            pointers.splice(index, 1);
+            const tapLike = {
+                pointerId: pointer.id,
+                x: pointer.x,
+                y: pointer.y,
+                duration: pointer.duration,
+            };
+            events.push({ type: 'release', data: tapLike });
+            // A cancel is the system taking the pointer away (a call, a system
+            // gesture). It must never read as intent.
+            if (sample.phase === 'up') {
+                const speed = pointer.duration > 0 ? (displacement / pointer.duration) * 1000 : 0;
+                if (displacement >= thresholds.swipeMinTravel && speed >= thresholds.swipeMinSpeed) {
+                    events.push({
+                        type: 'swipe',
+                        data: {
+                            pointerId: pointer.id,
+                            x: pointer.x,
+                            y: pointer.y,
+                            dx: pointer.x - pointer.startX,
+                            dy: pointer.y - pointer.startY,
+                            direction: directionOf(pointer.x - pointer.startX, pointer.y - pointer.startY),
+                            speed,
+                        },
+                    });
+                }
+                else if (pointer.duration <= thresholds.tapMaxMs &&
+                    pointer.travel <= thresholds.tapMaxTravel) {
+                    events.push({ type: 'tap', data: tapLike });
+                }
+            }
+        }
+    }
+    let pinchStart = state.pinchStart;
+    let pinchLast = state.pinchLast;
+    const [first, second] = pointers;
+    if (first && second && pointers.length === 2) {
+        const current = distance(first, second);
+        if (pinchStart === null || pinchLast === null) {
+            pinchStart = current;
+            pinchLast = current;
+        }
+        else if (sample.phase === 'move') {
+            events.push({
+                type: 'pinch',
+                data: {
+                    scale: pinchStart > 0 ? current / pinchStart : 1,
+                    delta: pinchLast > 0 ? current / pinchLast : 1,
+                    distance: current,
+                    centerX: (first.x + second.x) / 2,
+                    centerY: (first.y + second.y) / 2,
+                },
+            });
+            pinchLast = current;
+        }
+    }
+    else {
+        pinchStart = null;
+        pinchLast = null;
+    }
+    return { state: { pointers, pinchStart, pinchLast }, events };
+}

package/dist/input/index.d.ts

@@ -0,0 +1,30 @@
+import { type Plane, Vector3 } from 'three';
+import type { Intersection, Object3D } from 'three';
+import type { CameraRig } from '../camera.js';
+import type { Viewport } from '../viewport.js';
+import { type GestureEventMap, type GestureThresholds, type Pointer } from './gestures.js';
+export type { Pointer, GestureThresholds };
+export type { DragEvent, GestureEvent, GestureEventMap, PinchEvent, SwipeDirection, SwipeEvent, TapEvent, } from './gestures.js';
+/**
+ * Unified pointer input in DESIGN units, plus scene and ground-plane picking.
+ *
+ * Mobile is the target, so there is deliberately no keyboard and no hover path:
+ * a game built around either is unplayable on the device most Remix players
+ * use. A mouse arrives here as a single pointer and behaves like a finger.
+ */
+export type Input = {
+    readonly pointers: readonly Pointer[];
+    readonly primary: Pointer | null;
+    enabled: boolean;
+    on<K extends keyof GestureEventMap>(event: K, cb: (data: GestureEventMap[K]) => void): () => void;
+    /** Ray-cast from a pointer. Defaults to the primary pointer and the whole scene. */
+    pick(objects?: Object3D[], pointer?: Pointer | null): Intersection[];
+    /** Where a pointer's ray meets a plane — the ground-truth for tap-to-move. */
+    pickPlane(plane: Plane, out?: Vector3, pointer?: Pointer | null): Vector3 | null;
+    dispose(): void;
+};
+export type InputOptions = {
+    thresholds?: Partial<GestureThresholds>;
+};
+export declare function createInput(canvas: HTMLCanvasElement, viewport: Viewport, rig: CameraRig, scene: Object3D, options?: InputOptions): Input;
+//# sourceMappingURL=index.d.ts.map

package/dist/input/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/input/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAsB,OAAO,EAAE,MAAM,OAAO,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,EAEL,KAAK,eAAe,EAEpB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EAGb,MAAM,eAAe,CAAA;AAEtB,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAA;AAC1C,YAAY,EACV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,UAAU,EACV,cAAc,EACd,UAAU,EACV,QAAQ,GACT,MAAM,eAAe,CAAA;AAEtB;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,EAAE,CAAC,CAAC,SAAS,MAAM,eAAe,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IACjG,oFAAoF;IACpF,IAAI,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,YAAY,EAAE,CAAA;IACpE,8EAA8E;IAC9E,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAAA;IAChF,OAAO,IAAI,IAAI,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;CACxC,CAAA;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,QAAQ,EACf,OAAO,GAAE,YAAiB,GACzB,KAAK,CAyHP"}

package/dist/input/index.js

@@ -0,0 +1,121 @@
+import { Raycaster, Vector2, Vector3 } from 'three';
+import { DEFAULT_THRESHOLDS, createGestureState, reduceGestures, } from './gestures.js';
+export function createInput(canvas, viewport, rig, scene, options = {}) {
+    const thresholds = options.thresholds
+        ? { ...DEFAULT_THRESHOLDS, ...options.thresholds }
+        : undefined;
+    const listeners = new Map();
+    const raycaster = new Raycaster();
+    const ndc = new Vector2();
+    const design = new Vector2();
+    let state = createGestureState();
+    let enabled = true;
+    // Without `touch-action: none` the browser eats the second pointermove of
+    // every drag to decide whether it is a scroll.
+    canvas.style.touchAction = 'none';
+    function dispatch(sample) {
+        const result = reduceGestures(state, sample, thresholds);
+        state = result.state;
+        for (const event of result.events) {
+            const set = listeners.get(event.type);
+            if (!set)
+                continue;
+            for (const cb of [...set])
+                cb(event.data);
+        }
+    }
+    function sampleOf(event, phase) {
+        viewport.toDesign(event.clientX, event.clientY, design);
+        return { id: event.pointerId, x: design.x, y: design.y, time: event.timeStamp, phase };
+    }
+    const onDown = (event) => {
+        if (!enabled)
+            return;
+        event.preventDefault();
+        // Capture so a finger that slides off the canvas keeps reporting; without
+        // it a drag that leaves the edge sticks forever in the "down" state.
+        canvas.setPointerCapture?.(event.pointerId);
+        dispatch(sampleOf(event, 'down'));
+    };
+    const onMove = (event) => {
+        if (!enabled)
+            return;
+        dispatch(sampleOf(event, 'move'));
+    };
+    const onUp = (event) => {
+        if (!enabled)
+            return;
+        canvas.releasePointerCapture?.(event.pointerId);
+        dispatch(sampleOf(event, 'up'));
+    };
+    const onCancel = (event) => {
+        if (!enabled)
+            return;
+        dispatch(sampleOf(event, 'cancel'));
+    };
+    canvas.addEventListener('pointerdown', onDown);
+    canvas.addEventListener('pointermove', onMove);
+    canvas.addEventListener('pointerup', onUp);
+    canvas.addEventListener('pointercancel', onCancel);
+    function resolve(pointer) {
+        return pointer ?? state.pointers[0] ?? null;
+    }
+    function aim(pointer) {
+        viewport.designToNdc(pointer.x, pointer.y, ndc);
+        raycaster.setFromCamera(ndc, rig.camera);
+    }
+    return {
+        get pointers() {
+            return state.pointers;
+        },
+        get primary() {
+            return state.pointers[0] ?? null;
+        },
+        get enabled() {
+            return enabled;
+        },
+        set enabled(value) {
+            enabled = value;
+            // Dropping the tracked pointers matters: re-enabling mid-drag would
+            // otherwise emit a drag with a huge delta from a stale origin.
+            if (!value)
+                state = createGestureState();
+        },
+        on(event, cb) {
+            let set = listeners.get(event);
+            if (!set) {
+                set = new Set();
+                listeners.set(event, set);
+            }
+            const entry = cb;
+            set.add(entry);
+            return () => {
+                set?.delete(entry);
+            };
+        },
+        pick(objects, pointer) {
+            const active = resolve(pointer);
+            if (!active)
+                return [];
+            aim(active);
+            return objects
+                ? raycaster.intersectObjects(objects, true)
+                : raycaster.intersectObjects(scene.children, true);
+        },
+        pickPlane(plane, out, pointer) {
+            const active = resolve(pointer);
+            if (!active)
+                return null;
+            aim(active);
+            return raycaster.ray.intersectPlane(plane, out ?? new Vector3());
+        },
+        dispose() {
+            canvas.removeEventListener('pointerdown', onDown);
+            canvas.removeEventListener('pointermove', onMove);
+            canvas.removeEventListener('pointerup', onUp);
+            canvas.removeEventListener('pointercancel', onCancel);
+            listeners.clear();
+            state = createGestureState();
+        },
+    };
+}

package/dist/juice.d.ts

@@ -0,0 +1,151 @@
+import type { CameraRig } from './camera.js';
+/**
+ * Game feel: tweens, screen shake, hit-stop.
+ *
+ * The mechanisms behind "juice" — the layer of feedback that makes a hit feel
+ * like a hit. They live in the SDK because two of them physically cannot be
+ * hand-rolled well here: screen shake fights the camera rigs (a rig like
+ * `followRig` rewrites the camera transform every frame, so a game adding its
+ * own offset either loses it or double-applies it), and hit-stop is a pause of
+ * the fixed-timestep simulation, which only the update loop can express.
+ *
+ * What stays with the game is taste. These are parameterised mechanisms, not a
+ * house style: a shake's magnitude belongs to the event that caused it and a
+ * calm puzzle game calls none of this. The guide teaches matching intensity to
+ * tone; this file only makes the mechanism correct.
+ */
+export type Easing = (t: number) => number;
+/**
+ * The curated set. Linear motion everywhere is the tell of an untweened game —
+ * real objects accelerate — but a menagerie of forty easings is choice with no
+ * information. These seven cover the moves portrait games make: `quadOut` for
+ * almost everything that moves on screen, `backOut` for pops that overshoot,
+ * `elasticOut` for the rare springy emphasis, the rest for symmetry and ramps.
+ */
+export declare const easings: {
+    readonly linear: (t: number) => number;
+    readonly quadIn: (t: number) => number;
+    readonly quadOut: (t: number) => number;
+    readonly quadInOut: (t: number) => number;
+    readonly cubicOut: (t: number) => number;
+    readonly backOut: (t: number) => number;
+    readonly elasticOut: (t: number) => number;
+};
+export type EasingName = keyof typeof easings;
+/** Numeric properties of `T` — the only thing a tween can drive. */
+type NumericKeys<T> = {
+    [K in keyof T]: T[K] extends number ? K : never;
+}[keyof T];
+export type TweenOptions = {
+    /** Seconds for one leg. A yoyo tween takes 2 × duration for the round trip. */
+    duration: number;
+    /** Defaults to 'quadOut', the one that suits most motion. */
+    easing?: EasingName | Easing;
+    /** Return to the starting values after reaching the target. */
+    yoyo?: boolean;
+    /** Runs after each update — e.g. pushing a tweened counter into the HUD. */
+    onUpdate?: () => void;
+    /** Runs exactly once, when the tween lands (not when it is cancelled). */
+    onComplete?: () => void;
+};
+export type TweenHandle = {
+    cancel(): void;
+    readonly done: boolean;
+};
+export type Tweens = {
+    /**
+     * Animate `target`'s numeric properties to `to`. Start values are read NOW,
+     * at the call — a tween started from mid-flight starts from mid-flight.
+     */
+    to<T>(target: T, to: Partial<Pick<T, NumericKeys<T>>>, options: TweenOptions): TweenHandle;
+    /** Advance every tween. Call once per fixed step, from `update`. */
+    update(step: number): void;
+    /** Drop everything mid-flight, no callbacks. For the run reset. */
+    cancelAll(): void;
+    readonly active: number;
+};
+/**
+ * A tween runner stepped by the game's own fixed timestep.
+ *
+ * Stepped, not clocked: it advances only when `update(step)` is called, so
+ * tweens pause with the simulation (including during hit-stop, which is the
+ * behaviour that reads as impact), run identically on 60 Hz and 120 Hz
+ * displays, and are deterministic under test.
+ *
+ * Create it once at module scope, call `tweens.update(step)` first thing in
+ * the game's update, and `tweens.cancelAll()` from the run reset — a tween
+ * from the previous run landing on a freshly reset object is a classic ghost.
+ */
+export declare function createTweens(): Tweens;
+export type ShakeRigOptions = {
+    /** Camera offset in world units at full trauma. Characters are ~1 unit. */
+    maxOffset?: number;
+    /** Roll in radians at full trauma. A little goes a long way. */
+    maxRoll?: number;
+    /** Trauma lost per second. 1.5 means a full shake settles in ~0.7s. */
+    decay?: number;
+    /** The random source, for deterministic tests. Defaults to Math.random. */
+    rng?: () => number;
+};
+export type ShakeRig = CameraRig & {
+    /**
+     * Add trauma, clamped to 1. Scale it to the event: a pickup is ~0.15, a hit
+     * ~0.35, a death ~0.7. Perceived shake is trauma squared, so small events
+     * barely register and big ones dominate — which is the point.
+     */
+    shake(trauma: number): void;
+    readonly trauma: number;
+};
+/**
+ * Wraps any camera rig with trauma-based screen shake.
+ *
+ * A decorator, because ownership is the entire problem: rigs own the camera
+ * transform, and `followRig` rewrites it every frame while `portraitRig` never
+ * touches it after boot. Adding an offset directly therefore either vanishes
+ * next frame or accumulates forever, depending on which rig the game picked.
+ * The wrapper removes last frame's offset, lets the inner rig do its work,
+ * then applies a fresh one — correct against both behaviours.
+ *
+ * Trauma-squared with linear decay (Squirrel Eiserloh's model): shake feels
+ * proportional to events this way, and it composes — two quick hits raise
+ * trauma additively instead of restarting a fixed animation.
+ *
+ * Shake runs on render time (`rig.update(dt)`), so it keeps moving during
+ * hit-stop and after `gameOver` — a dead-still camera over a game-over sheet
+ * reads as a hang, and shake-through-freeze is the classic impact combo.
+ *
+ *     const rig = shakeRig(portraitRig())
+ *     await createGame({ camera: rig, ... })
+ *     rig.shake(0.4)
+ */
+export declare function shakeRig(rig: CameraRig, options?: ShakeRigOptions): ShakeRig;
+export type HitStop = {
+    /** Freeze the simulation for `seconds`. Overlapping triggers take the max. */
+    trigger(seconds: number): void;
+    /**
+     * Consume one fixed step of freeze. The gate at the top of update:
+     *
+     *     update(game, step) {
+     *       if (hitStop.frozen(step)) return
+     *       ...
+     *     }
+     */
+    frozen(step: number): boolean;
+    readonly active: boolean;
+};
+/**
+ * Hit-stop: the few-frame freeze that sells an impact.
+ *
+ * It cannot be a sleep and cannot skip rendering — the loop keeps drawing the
+ * frozen state, which is exactly the effect. What stops is simulation, and the
+ * game owns its update, so this is a countdown the game gates on rather than
+ * something the SDK can impose.
+ *
+ * Keep it short and rare: 0.05–0.12s, on the few biggest moments (a death, a
+ * heavy hit). On every minor event it stops reading as impact and starts
+ * reading as jank. Screen shake keeps moving through it (see `shakeRig`) —
+ * freeze-plus-shake is the combination that reads as force.
+ */
+export declare function createHitStop(): HitStop;
+export {};
+//# sourceMappingURL=juice.d.ts.map

package/dist/juice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"juice.d.ts","sourceRoot":"","sources":["../src/juice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C;;;;;;;;;;;;;;GAcG;AAKH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,OAAO;yBACN,MAAM;yBACN,MAAM;0BACL,MAAM;4BACJ,MAAM;2BACP,MAAM;0BACP,MAAM;6BACH,MAAM;CAEmB,CAAA;AAE3C,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,OAAO,CAAA;AAgB7C,oEAAoE;AACpE,KAAK,WAAW,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,GAAG,KAAK;CAAE,CAAC,MAAM,CAAC,CAAC,CAAA;AAElF,MAAM,MAAM,YAAY,GAAG;IACzB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAA;IAChB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAA;IAC5B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,IAAI,IAAI,CAAA;IACd,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,MAAM,GAAG;IACnB;;;OAGG;IACH,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,WAAW,CAAA;IAC1F,oEAAoE;IACpE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,mEAAmE;IACnE,SAAS,IAAI,IAAI,CAAA;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAA;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAyFrC;AAKD,MAAM,MAAM,eAAe,GAAG;IAC5B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG;IACjC;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,QAAQ,CAkDhF;AAKD,MAAM,MAAM,OAAO,GAAG;IACpB,8EAA8E;IAC9E,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAoBvC"}