@jgengine/core 0.6.0 → 0.8.0

package/dist/input/gestureSurface.js

@@ -0,0 +1,120 @@
+/**
+ * Single-finger play-surface gesture recognizer for touch controls: taps,
+ * directional flick swipes, and continuous step drags all resolve to action
+ * names from a TouchGestureBindings declaration. Drag steps stream out of
+ * move() as the finger travels; taps and swipes resolve on end(). Timestamps
+ * are injected so the state machine stays pure; the capture layer owns touch
+ * identifiers and pointer capture.
+ */
+export const DEFAULT_GESTURE_TUNING = {
+    tapMoveThresholdPx: 12,
+    tapMaxMs: 280,
+    swipeMinPx: 48,
+    swipeMinVelocity: 0.45,
+    dragStepPx: 36,
+};
+export function createGestureSurfaceTracker(bindings, tuning = DEFAULT_GESTURE_TUNING) {
+    const drag = bindings.drag;
+    const dragStepPx = drag?.stepPx ?? tuning.dragStepPx;
+    const dragBound = {
+        horizontal: drag?.left !== undefined || drag?.right !== undefined,
+        vertical: drag?.up !== undefined || drag?.down !== undefined,
+    };
+    let active = false;
+    let startX = 0;
+    let startY = 0;
+    let lastX = 0;
+    let lastY = 0;
+    let startTime = 0;
+    let moved = false;
+    let axis = null;
+    let dragAccum = 0;
+    let dragStepsFired = 0;
+    const commitAxis = (totalDx, totalDy) => {
+        if (axis !== null)
+            return;
+        axis = Math.abs(totalDx) >= Math.abs(totalDy) ? "horizontal" : "vertical";
+    };
+    const swipeFor = (totalDx, totalDy) => {
+        if (axis === "horizontal") {
+            return totalDx >= 0 ? bindings.swipeRight : bindings.swipeLeft;
+        }
+        return totalDy >= 0 ? bindings.swipeDown : bindings.swipeUp;
+    };
+    const dragActionFor = (direction) => {
+        if (axis === "horizontal")
+            return direction >= 0 ? drag?.right : drag?.left;
+        return direction >= 0 ? drag?.down : drag?.up;
+    };
+    return {
+        begin(x, y, nowMs) {
+            active = true;
+            startX = lastX = x;
+            startY = lastY = y;
+            startTime = nowMs;
+            moved = false;
+            axis = null;
+            dragAccum = 0;
+            dragStepsFired = 0;
+        },
+        move(x, y) {
+            if (!active)
+                return [];
+            const totalDx = x - startX;
+            const totalDy = y - startY;
+            if (!moved && Math.hypot(totalDx, totalDy) > tuning.tapMoveThresholdPx) {
+                moved = true;
+                commitAxis(totalDx, totalDy);
+            }
+            const fired = [];
+            if (moved && axis !== null && dragBound[axis]) {
+                const delta = axis === "horizontal" ? x - lastX : y - lastY;
+                if (delta !== 0 && dragAccum !== 0 && Math.sign(delta) !== Math.sign(dragAccum))
+                    dragAccum = 0;
+                dragAccum += delta;
+                while (Math.abs(dragAccum) >= dragStepPx) {
+                    const direction = Math.sign(dragAccum);
+                    const action = dragActionFor(direction);
+                    dragAccum -= direction * dragStepPx;
+                    if (action !== undefined) {
+                        fired.push(action);
+                        dragStepsFired += 1;
+                    }
+                }
+            }
+            lastX = x;
+            lastY = y;
+            return fired;
+        },
+        end(x, y, nowMs) {
+            if (!active)
+                return [];
+            active = false;
+            const totalDx = x - startX;
+            const totalDy = y - startY;
+            const elapsed = nowMs - startTime;
+            if (!moved) {
+                if (elapsed <= tuning.tapMaxMs && bindings.tap !== undefined)
+                    return [bindings.tap];
+                return [];
+            }
+            const travel = Math.hypot(totalDx, totalDy);
+            const velocity = elapsed <= 0 ? Infinity : travel / elapsed;
+            if (travel < tuning.swipeMinPx || velocity < tuning.swipeMinVelocity)
+                return [];
+            const direction = axis === "horizontal" ? Math.sign(totalDx) : Math.sign(totalDy);
+            if (axis !== null && dragBound[axis] && dragActionFor(direction) !== undefined)
+                return [];
+            const swipe = swipeFor(totalDx, totalDy);
+            if (swipe === undefined || dragStepsFired > 0)
+                return [];
+            return [swipe];
+        },
+        cancel() {
+            active = false;
+        },
+        isActive() {
+            return active;
+        },
+    };
+}

package/dist/input/pointer.d.ts

@@ -0,0 +1,69 @@
+import type { Aim } from "../scene/spatial.js";
+export type PointerVec3 = readonly [number, number, number];
+/**
+ * Renderer-free result of a screen→world raycast. The shell's pointer service
+ * produces this from the cursor; core-side gameplay (item.use aim, click-to-move,
+ * ground-target abilities, pings) consumes it without touching three.js.
+ */
+export interface PointerHit {
+    /** World-space point under the cursor (surface or ground plane). */
+    point: PointerVec3;
+    /** World-space surface normal at the hit; `[0, 1, 0]` for the ground plane. */
+    normal: PointerVec3;
+    /** Topmost scene-entity instance id under the cursor, or null over open ground. */
+    entity: string | null;
+    /** Topmost scene-object instance id under the cursor, or null. */
+    object: string | null;
+    /** Texture-space UV at the hit, when the intersected mesh carries UVs; absent for the ground-plane fallback. */
+    uv?: {
+        u: number;
+        v: number;
+    };
+    /** Sampled `#rrggbb` color + PBR params from the hit mesh's `MeshStandardMaterial` (#151.2); `null`/unset when the hit surface has no standard material (e.g. the ground plane). */
+    material?: {
+        color: string;
+        metalness?: number;
+        roughness?: number;
+    } | null;
+    /** Index of the hit instance when the intersected mesh is a `THREE.InstancedMesh`; absent otherwise. */
+    instanceId?: number;
+}
+export type PointerButton = "primary" | "secondary" | "middle";
+/** Build an `origin → point` aim for `item.use` / projectiles, firing toward the cursor. */
+export declare function aimToPoint(origin: PointerVec3, point: PointerVec3): Aim;
+/** The move-to target of a pointer hit — sugar over `hit.point`. */
+export declare function moveTargetFromHit(hit: PointerHit): PointerVec3;
+/** Project a pointer hit onto the XZ plane for navmesh routing (`findPath` takes `[x, z]`). */
+export declare function groundOf(hit: PointerHit): readonly [number, number];
+/** Snapshot of an in-progress or just-released drag: origin/current cursor points plus the clamped pull vector. */
+export interface DragState {
+    origin: PointerVec3;
+    current: PointerVec3;
+    /** `current - origin`, clamped to `maxPull` in length. */
+    pull: PointerVec3;
+    /** Length of `pull`, at most `maxPull`. */
+    magnitude: number;
+    /** `magnitude / maxPull`, in `[0, 1]`. `0` when `maxPull` is unset. */
+    fraction: number;
+}
+export type DragResult = DragState;
+export interface DragCaptureConfig {
+    /** Clamp on pull-vector length. Unset (default) means unclamped. */
+    maxPull?: number;
+    /** Max distance from `origin` a `begin()` point may be to start a drag. Unset (default) means unrestricted. */
+    grabRadius?: number;
+}
+/** Renderer-agnostic drag-capture / pull-vector state machine for slingshot-style aiming, drawback abilities, and similar gestures. */
+export interface DragCapture {
+    /** Start a drag at `origin` if `at` is within `grabRadius` of it. Returns whether the drag started. */
+    begin(origin: PointerVec3, at: PointerVec3): boolean;
+    /** Move the drag's current point. No-op when no drag is active. */
+    update(at: PointerVec3): void;
+    /** End the drag, returning its final state, or `null` if no drag was active. */
+    release(): DragResult | null;
+    /** Abort the drag without producing a result. */
+    cancel(): void;
+    /** The current drag state, or `null` when idle. */
+    state(): DragState | null;
+}
+export declare function createDragCapture(config?: DragCaptureConfig): DragCapture;

package/dist/input/pointer.js

@@ -0,0 +1,65 @@
+/** Build an `origin → point` aim for `item.use` / projectiles, firing toward the cursor. */
+export function aimToPoint(origin, point) {
+    const dx = point[0] - origin[0];
+    const dy = point[1] - origin[1];
+    const dz = point[2] - origin[2];
+    const length = Math.hypot(dx, dy, dz);
+    const direction = length < 1e-9 ? [0, 0, 1] : [dx / length, dy / length, dz / length];
+    return { origin, direction };
+}
+/** The move-to target of a pointer hit — sugar over `hit.point`. */
+export function moveTargetFromHit(hit) {
+    return hit.point;
+}
+/** Project a pointer hit onto the XZ plane for navmesh routing (`findPath` takes `[x, z]`). */
+export function groundOf(hit) {
+    return [hit.point[0], hit.point[2]];
+}
+function subtractVec3(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+function lengthVec3(v) {
+    return Math.hypot(v[0], v[1], v[2]);
+}
+export function createDragCapture(config = {}) {
+    const maxPull = config.maxPull ?? Number.POSITIVE_INFINITY;
+    const grabRadius = config.grabRadius ?? Number.POSITIVE_INFINITY;
+    let origin = null;
+    let current = null;
+    function snapshot() {
+        if (origin === null || current === null)
+            return null;
+        const offset = subtractVec3(current, origin);
+        const rawLength = lengthVec3(offset);
+        const scale = rawLength > maxPull && rawLength > 0 ? maxPull / rawLength : 1;
+        const pull = [offset[0] * scale, offset[1] * scale, offset[2] * scale];
+        const magnitude = Math.min(rawLength, maxPull);
+        const fraction = Number.isFinite(maxPull) && maxPull > 0 ? magnitude / maxPull : 0;
+        return { origin, current, pull, magnitude, fraction };
+    }
+    return {
+        begin(dragOrigin, at) {
+            if (lengthVec3(subtractVec3(at, dragOrigin)) > grabRadius)
+                return false;
+            origin = dragOrigin;
+            current = at;
+            return true;
+        },
+        update(at) {
+            if (origin === null)
+                return;
+            current = at;
+        },
+        release() {
+            const result = snapshot();
+            origin = null;
+            current = null;
+            return result;
+        },
+        cancel() {
+            origin = null;
+            current = null;
+        },
+        state: snapshot,
+    };
+}

package/dist/input/touchScheme.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Touch control scheme derived from a game's existing action bindings: the
+ * capture layer renders a virtual joystick, on-screen buttons, and a gesture
+ * surface, and feeds synthetic `touch:<action>` codes into the same
+ * ActionStateTracker the keyboard uses, so games gain touch play without any
+ * per-game input code. Games refine the derived defaults through
+ * TouchControlsConfig (gesture bindings, button curation) or opt out entirely
+ * with `touch: false`.
+ */
+import { type ActionCodesMap } from "./actionBindings.js";
+export declare const TOUCH_CODE_PREFIX = "touch:";
+export declare function touchCode(action: string): string;
+/** Every action gains a synthetic touch code alongside its physical codes. */
+export declare function withTouchCodes(map: ActionCodesMap | undefined): ActionCodesMap;
+export interface TouchDragBinding {
+    /** Action fired once per `stepPx` of travel toward that side. */
+    left?: string;
+    right?: string;
+    up?: string;
+    down?: string;
+    stepPx?: number;
+}
+export interface TouchGestureBindings {
+    /** Action fired by a quick still tap on the play surface. */
+    tap?: string;
+    /** Actions fired by a fast flick past the swipe threshold. */
+    swipeUp?: string;
+    swipeDown?: string;
+    swipeLeft?: string;
+    swipeRight?: string;
+    /** Continuous drag: repeats the directional action every `stepPx` of travel. Wins over swipes on its axis, except a flick can still fire the swipe binding for a direction the drag leaves unbound. */
+    drag?: TouchDragBinding;
+}
+export interface TouchButtonSpec {
+    action: string;
+    label?: string;
+    /** Glyph name from the capture layer's icon catalog (`@jgengine/react/gameIcons` `GameIconName`); unset derives one from the action name, `false` forces the text label. */
+    icon?: string | false;
+}
+export interface TouchControlsConfig {
+    /** `false` removes the virtual joystick even when movement actions are bound. */
+    movement?: false;
+    /** Curated on-screen buttons (order preserved); omit to derive one button per remaining action. */
+    buttons?: readonly (string | TouchButtonSpec)[];
+    /** Play-surface gestures; actions consumed here stop appearing as derived buttons. */
+    gestures?: TouchGestureBindings;
+    /** Drag-to-look on the play surface; defaults to true for first-person games. */
+    look?: boolean;
+    /** Radians of look rotation per pixel of touch travel. Default 0.005. */
+    lookSensitivity?: number;
+    /** Actions to leave off the derived button cluster. */
+    hidden?: readonly string[];
+}
+export interface TouchJoystick {
+    up: string | null;
+    down: string | null;
+    left: string | null;
+    right: string | null;
+}
+export interface TouchButton {
+    action: string;
+    label: string;
+    /** Glyph hint for the capture layer: a name to render, `false` to force text, null to derive from the action name. */
+    icon: string | false | null;
+}
+export interface TouchScheme {
+    joystick: TouchJoystick | null;
+    buttons: readonly TouchButton[];
+    gestures: TouchGestureBindings | null;
+    look: boolean;
+    lookSensitivity: number;
+}
+export declare function touchActionLabel(action: string): string;
+export interface DeriveTouchSchemeOptions {
+    reserved: ReadonlySet<string>;
+    firstPerson: boolean;
+    config?: TouchControlsConfig | false;
+}
+/**
+ * Null means "render no touch controls" — either the game opted out or there
+ * is nothing to synthesize.
+ */
+export declare function deriveTouchScheme(input: ActionCodesMap | undefined, { reserved, firstPerson, config }: DeriveTouchSchemeOptions): TouchScheme | null;

package/dist/input/touchScheme.js

@@ -0,0 +1,115 @@
+/**
+ * Touch control scheme derived from a game's existing action bindings: the
+ * capture layer renders a virtual joystick, on-screen buttons, and a gesture
+ * surface, and feeds synthetic `touch:<action>` codes into the same
+ * ActionStateTracker the keyboard uses, so games gain touch play without any
+ * per-game input code. Games refine the derived defaults through
+ * TouchControlsConfig (gesture bindings, button curation) or opt out entirely
+ * with `touch: false`.
+ */
+import { isHotbarSlotAction } from "./actionBindings.js";
+export const TOUCH_CODE_PREFIX = "touch:";
+export function touchCode(action) {
+    return `${TOUCH_CODE_PREFIX}${action}`;
+}
+/** Every action gains a synthetic touch code alongside its physical codes. */
+export function withTouchCodes(map) {
+    const result = {};
+    for (const action of Object.keys(map ?? {})) {
+        const codes = map[action];
+        const synthetic = touchCode(action);
+        if (Array.isArray(codes)) {
+            result[action] = [...codes, synthetic];
+        }
+        else {
+            const modes = codes;
+            const toggleOnly = (modes.toggle?.length ?? 0) > 0 && (modes.hold?.length ?? 0) === 0;
+            result[action] = toggleOnly
+                ? { hold: modes.hold, toggle: [...(modes.toggle ?? []), synthetic] }
+                : { hold: [...(modes.hold ?? []), synthetic], toggle: modes.toggle };
+        }
+    }
+    return result;
+}
+const DEFAULT_LOOK_SENSITIVITY = 0.005;
+const JOYSTICK_AXES = {
+    up: ["moveForward"],
+    down: ["moveBack"],
+    left: ["moveLeft", "turnLeft"],
+    right: ["moveRight", "turnRight"],
+};
+const BUTTONABLE_RESERVED = new Set(["jump", "sprint", "interact", "useAbility"]);
+export function touchActionLabel(action) {
+    const spaced = action.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+function gestureActions(gestures) {
+    const used = new Set();
+    if (gestures === undefined)
+        return used;
+    for (const action of [gestures.tap, gestures.swipeUp, gestures.swipeDown, gestures.swipeLeft, gestures.swipeRight]) {
+        if (action !== undefined)
+            used.add(action);
+    }
+    const drag = gestures.drag;
+    for (const action of [drag?.left, drag?.right, drag?.up, drag?.down]) {
+        if (action !== undefined)
+            used.add(action);
+    }
+    return used;
+}
+/**
+ * Null means "render no touch controls" — either the game opted out or there
+ * is nothing to synthesize.
+ */
+export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
+    if (config === false)
+        return null;
+    const actions = Object.keys(input ?? {});
+    const bound = new Set(actions);
+    const joystickMapped = new Set();
+    let joystick = null;
+    if (config?.movement !== false) {
+        const resolveAxis = (candidates) => {
+            const action = candidates.find((candidate) => bound.has(candidate)) ?? null;
+            if (action !== null)
+                joystickMapped.add(action);
+            return action;
+        };
+        const axes = {
+            up: resolveAxis(JOYSTICK_AXES.up),
+            down: resolveAxis(JOYSTICK_AXES.down),
+            left: resolveAxis(JOYSTICK_AXES.left),
+            right: resolveAxis(JOYSTICK_AXES.right),
+        };
+        joystick = axes.up === null && axes.down === null && axes.left === null && axes.right === null ? null : axes;
+    }
+    const gestures = config?.gestures ?? null;
+    const consumedByGestures = gestureActions(config?.gestures);
+    const hidden = new Set(config?.hidden ?? []);
+    let buttons;
+    if (config?.buttons !== undefined) {
+        buttons = config.buttons.map((spec) => typeof spec === "string"
+            ? { action: spec, label: touchActionLabel(spec), icon: null }
+            : { action: spec.action, label: spec.label ?? touchActionLabel(spec.action), icon: spec.icon ?? null });
+    }
+    else {
+        buttons = actions
+            .filter((action) => !joystickMapped.has(action))
+            .filter((action) => !isHotbarSlotAction(action))
+            .filter((action) => !consumedByGestures.has(action))
+            .filter((action) => !hidden.has(action))
+            .filter((action) => !reserved.has(action) || BUTTONABLE_RESERVED.has(action))
+            .map((action) => ({ action, label: touchActionLabel(action), icon: null }));
+    }
+    const look = config?.look ?? firstPerson;
+    if (joystick === null && buttons.length === 0 && gestures === null && !look)
+        return null;
+    return {
+        joystick,
+        buttons,
+        gestures,
+        look,
+        lookSensitivity: config?.lookSensitivity ?? DEFAULT_LOOK_SENSITIVITY,
+    };
+}

package/dist/interaction/contextMenu.d.ts

@@ -0,0 +1,30 @@
+export type ContextTargetKind = "entity" | "object";
+/** One right-click verb: a label plus the command it dispatches (walk-then-act supported by args). */
+export interface ContextVerb {
+    label: string;
+    command: string;
+    args?: Record<string, unknown>;
+    /** Greyed-out and non-dispatchable when true (e.g. requirement unmet). */
+    disabled?: boolean;
+}
+export declare function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb;
+export interface ContextMenu {
+    kind: ContextTargetKind;
+    targetId: string;
+    /** World point the click landed on, forwarded to dispatched commands for walk-then-act. */
+    point?: readonly [number, number, number];
+    verbs: readonly ContextVerb[];
+}
+export interface BuildContextMenuInput {
+    kind: ContextTargetKind;
+    targetId: string;
+    verbs: readonly ContextVerb[] | undefined;
+    point?: readonly [number, number, number];
+}
+/** Assemble a menu from a target's catalog verbs; null when the target lists none. */
+export declare function buildContextMenu(input: BuildContextMenuInput): ContextMenu | null;
+/**
+ * Command input a chosen verb dispatches: the verb's own args, plus the target id and
+ * the world point, so a single handler can walk the actor to the target then perform it.
+ */
+export declare function contextVerbInput(menu: ContextMenu, verb: ContextVerb): Record<string, unknown>;

package/dist/interaction/contextMenu.js

@@ -0,0 +1,22 @@
+export function contextVerb(label, command, args) {
+    return args === undefined ? { label, command } : { label, command, args };
+}
+/** Assemble a menu from a target's catalog verbs; null when the target lists none. */
+export function buildContextMenu(input) {
+    if (input.verbs === undefined || input.verbs.length === 0)
+        return null;
+    const menu = { kind: input.kind, targetId: input.targetId, verbs: input.verbs };
+    if (input.point !== undefined)
+        menu.point = input.point;
+    return menu;
+}
+/**
+ * Command input a chosen verb dispatches: the verb's own args, plus the target id and
+ * the world point, so a single handler can walk the actor to the target then perform it.
+ */
+export function contextVerbInput(menu, verb) {
+    const base = { ...verb.args, target: menu.targetId, targetKind: menu.kind };
+    if (menu.point !== undefined)
+        base.point = menu.point;
+    return base;
+}

package/dist/interaction/qte.d.ts

@@ -0,0 +1,20 @@
+export interface QteStep {
+    id: string;
+    action: string;
+    windowStart: number;
+    windowEnd: number;
+}
+export interface QteInputEvent {
+    action: string;
+    at: number;
+}
+export type QteOutcome = {
+    status: "success";
+} | {
+    status: "fail";
+    atStep: string;
+    reason: "missed-window" | "wrong-action" | "too-early";
+};
+export declare function evaluateQteSequence(steps: readonly QteStep[], inputs: readonly QteInputEvent[]): QteOutcome;
+export declare function pendingQteStep(steps: readonly QteStep[], elapsedSeconds: number): QteStep | null;
+export declare function qteProgress(steps: readonly QteStep[], elapsedSeconds: number): number;

package/dist/interaction/qte.js

@@ -0,0 +1,24 @@
+export function evaluateQteSequence(steps, inputs) {
+    for (let index = 0; index < steps.length; index += 1) {
+        const step = steps[index];
+        const input = inputs[index];
+        if (input === undefined)
+            return { status: "fail", atStep: step.id, reason: "missed-window" };
+        if (input.at < step.windowStart)
+            return { status: "fail", atStep: step.id, reason: "too-early" };
+        if (input.at > step.windowEnd)
+            return { status: "fail", atStep: step.id, reason: "missed-window" };
+        if (input.action !== step.action)
+            return { status: "fail", atStep: step.id, reason: "wrong-action" };
+    }
+    return { status: "success" };
+}
+export function pendingQteStep(steps, elapsedSeconds) {
+    return (steps.find((step) => elapsedSeconds >= step.windowStart && elapsedSeconds <= step.windowEnd) ?? null);
+}
+export function qteProgress(steps, elapsedSeconds) {
+    if (steps.length === 0)
+        return 1;
+    const passed = steps.filter((step) => elapsedSeconds > step.windowEnd).length;
+    return passed / steps.length;
+}

package/dist/interaction/skillCheck.d.ts

@@ -0,0 +1,20 @@
+export interface SkillCheckZone {
+    start: number;
+    end: number;
+}
+export interface SkillCheckConfig {
+    trackWidth: number;
+    zone: SkillCheckZone;
+    markerPeriod: number;
+    window: number;
+    zoneDriftPerSecond?: number;
+}
+export interface SkillCheckResult {
+    success: boolean;
+    timedOut: boolean;
+    markerPosition: number;
+    zone: SkillCheckZone;
+}
+export declare function skillCheckMarkerPosition(config: SkillCheckConfig, elapsedSeconds: number): number;
+export declare function skillCheckZoneAt(config: SkillCheckConfig, elapsedSeconds: number): SkillCheckZone;
+export declare function evaluateSkillCheck(config: SkillCheckConfig, elapsedSeconds: number): SkillCheckResult;

package/dist/interaction/skillCheck.js

@@ -0,0 +1,26 @@
+function bounce(t, period, max) {
+    if (period <= 0 || max <= 0)
+        return 0;
+    const cycle = max * 2;
+    const phase = ((t % period) / period) * cycle;
+    return phase <= max ? phase : cycle - phase;
+}
+export function skillCheckMarkerPosition(config, elapsedSeconds) {
+    return bounce(Math.max(0, elapsedSeconds), config.markerPeriod, config.trackWidth);
+}
+export function skillCheckZoneAt(config, elapsedSeconds) {
+    const drift = config.zoneDriftPerSecond ?? 0;
+    if (drift === 0)
+        return config.zone;
+    const width = config.zone.end - config.zone.start;
+    const travel = Math.max(0, config.trackWidth - width);
+    const start = bounce(Math.max(0, elapsedSeconds) * Math.abs(drift), config.markerPeriod, travel);
+    return { start, end: start + width };
+}
+export function evaluateSkillCheck(config, elapsedSeconds) {
+    const timedOut = elapsedSeconds > config.window;
+    const markerPosition = skillCheckMarkerPosition(config, elapsedSeconds);
+    const zone = skillCheckZoneAt(config, elapsedSeconds);
+    const inZone = markerPosition >= zone.start && markerPosition <= zone.end;
+    return { success: !timedOut && inZone, timedOut, markerPosition, zone };
+}

package/dist/inventory/shapedGrid.d.ts

@@ -0,0 +1,56 @@
+export type Cell = readonly [number, number];
+export type Footprint = readonly Cell[];
+export type Rotation = 0 | 1 | 2 | 3;
+export interface ShapedItem<T> {
+    id: string;
+    value: T;
+    footprint: Footprint;
+}
+export interface Placement<T> {
+    id: string;
+    value: T;
+    footprint: Footprint;
+    origin: Cell;
+    rotation: Rotation;
+}
+export interface ShapedGrid<T> {
+    readonly width: number;
+    readonly height: number;
+    readonly placements: readonly Placement<T>[];
+}
+export type ShapedRejection = "out-of-bounds" | "overlap" | "duplicate-id" | "unknown-id";
+export interface ShapedPlaceResult<T> {
+    status: "ok";
+    grid: ShapedGrid<T>;
+}
+export interface ShapedRejected {
+    status: "rejected";
+    reason: ShapedRejection;
+    detail?: string;
+}
+export type ShapedResult<T> = ShapedPlaceResult<T> | ShapedRejected;
+export declare function normalizeFootprint(footprint: Footprint): Footprint;
+export declare function rotateFootprint(footprint: Footprint, rotation: Rotation): Footprint;
+export declare function occupiedCells(footprint: Footprint, origin: Cell, rotation: Rotation): Cell[];
+export declare function createShapedGrid<T>(width: number, height: number): ShapedGrid<T>;
+export declare function canPlace<T>(grid: ShapedGrid<T>, footprint: Footprint, origin: Cell, rotation: Rotation, ignoreId?: string): ShapedRejection | null;
+export declare function placeShaped<T>(grid: ShapedGrid<T>, item: ShapedItem<T>, origin: Cell, rotation?: Rotation): ShapedResult<T>;
+export declare function removeShaped<T>(grid: ShapedGrid<T>, id: string): ShapedResult<T>;
+export declare function moveShaped<T>(grid: ShapedGrid<T>, id: string, origin: Cell, rotation?: Rotation): ShapedResult<T>;
+export declare function cellOccupant<T>(grid: ShapedGrid<T>, cell: Cell): string | null;
+export interface GridAdjacencyQuery {
+    cellsOf(id: string): readonly Cell[];
+    neighborsOf(id: string): readonly string[];
+    touching(idA: string, idB: string): boolean;
+    adjacentCells(cells: readonly Cell[]): readonly Cell[];
+}
+export declare function gridAdjacencyQuery<T>(grid: ShapedGrid<T>, options?: {
+    diagonal?: boolean;
+}): GridAdjacencyQuery;
+export declare function cellFromPoint(point: {
+    x: number;
+    y: number;
+}, cellSize: number, gridOrigin?: {
+    x: number;
+    y: number;
+}): Cell;