@jgengine/core 0.7.0 → 0.9.0

package/dist/input/bindingOverrides.js

@@ -0,0 +1,95 @@
+export const BINDING_OVERRIDES_STORAGE_PREFIX = "jgengine:keybinds:";
+export function bindingOverridesStorageKey(gameId) {
+    return `${BINDING_OVERRIDES_STORAGE_PREFIX}${gameId}`;
+}
+function defaultStorage() {
+    try {
+        if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+            return globalThis.localStorage ?? null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function isActionCodes(value) {
+    if (Array.isArray(value))
+        return value.every((code) => typeof code === "string");
+    if (value === null || typeof value !== "object")
+        return false;
+    const modes = value;
+    const okList = (list) => list === undefined || (Array.isArray(list) && list.every((code) => typeof code === "string"));
+    return okList(modes.hold) && okList(modes.toggle);
+}
+export function loadBindingOverrides(gameId, storage = defaultStorage()) {
+    if (storage == null)
+        return {};
+    try {
+        const raw = storage.getItem(bindingOverridesStorageKey(gameId));
+        if (raw === null)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object")
+            return {};
+        const result = {};
+        for (const [action, codes] of Object.entries(parsed)) {
+            if (isActionCodes(codes))
+                result[action] = codes;
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+function persist(gameId, overrides, storage) {
+    if (storage == null)
+        return;
+    try {
+        if (Object.keys(overrides).length === 0)
+            storage.removeItem(bindingOverridesStorageKey(gameId));
+        else
+            storage.setItem(bindingOverridesStorageKey(gameId), JSON.stringify(overrides));
+    }
+    catch {
+        /* ignore quota / private-mode failures */
+    }
+}
+export function saveBindingOverride(gameId, action, codes, storage = defaultStorage()) {
+    const overrides = { ...loadBindingOverrides(gameId, storage ?? undefined), [action]: codes };
+    persist(gameId, overrides, storage);
+    return overrides;
+}
+export function clearBindingOverride(gameId, action, storage = defaultStorage()) {
+    const overrides = { ...loadBindingOverrides(gameId, storage ?? undefined) };
+    delete overrides[action];
+    persist(gameId, overrides, storage);
+    return overrides;
+}
+export function clearAllBindingOverrides(gameId, storage = defaultStorage()) {
+    if (storage == null)
+        return;
+    try {
+        storage.removeItem(bindingOverridesStorageKey(gameId));
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Merge player rebinds over a game's authored `input` map. Only actions the
+ * game already declares can be overridden; unknown override keys are ignored so
+ * a stale localStorage entry can't inject phantom actions.
+ */
+export function applyBindingOverrides(input, overrides) {
+    if (Object.keys(overrides).length === 0)
+        return input;
+    const result = { ...input };
+    for (const action of Object.keys(input)) {
+        const override = overrides[action];
+        if (override !== undefined)
+            result[action] = override;
+    }
+    return result;
+}

package/dist/input/gestureSurface.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+import type { TouchGestureBindings } from "./touchScheme.js";
+export interface GestureSurfaceTuning {
+    /** A finger that moves less than this (px) and lifts quickly is a tap. */
+    tapMoveThresholdPx: number;
+    tapMaxMs: number;
+    /** Minimum travel (px) for a lift to register as a swipe. */
+    swipeMinPx: number;
+    /** Minimum lift velocity (px/ms) for a swipe; slower travel is a drag that ends quietly. */
+    swipeMinVelocity: number;
+    /** Default travel (px) per repeated drag action when the binding sets none. */
+    dragStepPx: number;
+}
+export declare const DEFAULT_GESTURE_TUNING: GestureSurfaceTuning;
+export interface GestureSurfaceTracker {
+    begin(x: number, y: number, nowMs: number): void;
+    /** Drag-step actions fired by this movement, in travel order. */
+    move(x: number, y: number): readonly string[];
+    /** Tap or swipe action resolved by lifting the finger, if any. */
+    end(x: number, y: number, nowMs: number): readonly string[];
+    cancel(): void;
+    isActive(): boolean;
+}
+export declare function createGestureSurfaceTracker(bindings: TouchGestureBindings, tuning?: GestureSurfaceTuning): GestureSurfaceTracker;

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

@@ -14,6 +14,19 @@ export interface PointerHit {
     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. */
@@ -22,3 +35,35 @@ export declare function aimToPoint(origin: PointerVec3, point: PointerVec3): Aim
 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

@@ -15,3 +15,51 @@ export function moveTargetFromHit(hit) {
 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/pointerAxis.d.ts

@@ -0,0 +1,30 @@
+export interface PointerAxisState {
+    /** Horizontal pointer position over the play surface in `[-1, 1]`: `-1` at the left edge, `+1` at the right. */
+    x: number;
+    /** Vertical pointer position over the play surface in `[-1, 1]`, screen convention: `-1` at the top edge, `+1` at the bottom — negate for aim-up. */
+    y: number;
+    /** `false` after the pointer leaves the surface; the last position is retained. */
+    active: boolean;
+}
+/** Maps one pointer axis onto an analog axis target — the pointer-backed counterpart of an `AxisBinding`'s key lists. */
+export interface PointerAxisBinding {
+    source: "x" | "y";
+    invert?: boolean;
+    /** Fraction of the half-range around center treated as zero; the remainder rescales to the full `[-1, 1]`. */
+    deadzone?: number;
+    /** Response-curve exponent on the magnitude: `1` linear (default), `>1` finer control near center. */
+    curve?: number;
+}
+export interface PointerSurfaceRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Normalize client coordinates against a surface rect into a `PointerAxisState`, clamped to `[-1, 1]` per axis. */
+export declare function normalizePointerToAxis(clientX: number, clientY: number, rect: PointerSurfaceRect): PointerAxisState;
+/**
+ * Resolve a pointer binding against the current pointer state: `null` when no pointer is active
+ * (callers fall back to their digital target), otherwise the deadzone/curve-shaped value in `[-1, 1]`.
+ */
+export declare function pointerAxisValue(binding: PointerAxisBinding, state: PointerAxisState | null | undefined): number | null;

package/dist/input/pointerAxis.js

@@ -0,0 +1,31 @@
+/** Normalize client coordinates against a surface rect into a `PointerAxisState`, clamped to `[-1, 1]` per axis. */
+export function normalizePointerToAxis(clientX, clientY, rect) {
+    const width = rect.width > 0 ? rect.width : 1;
+    const height = rect.height > 0 ? rect.height : 1;
+    return {
+        x: clampUnit(((clientX - rect.left) / width) * 2 - 1),
+        y: clampUnit(((clientY - rect.top) / height) * 2 - 1),
+        active: true,
+    };
+}
+/**
+ * Resolve a pointer binding against the current pointer state: `null` when no pointer is active
+ * (callers fall back to their digital target), otherwise the deadzone/curve-shaped value in `[-1, 1]`.
+ */
+export function pointerAxisValue(binding, state) {
+    if (state === null || state === undefined || !state.active)
+        return null;
+    let value = binding.source === "x" ? state.x : state.y;
+    if (binding.invert === true)
+        value = -value;
+    const deadzone = binding.deadzone ?? 0;
+    const magnitude = Math.abs(value);
+    if (magnitude <= deadzone)
+        return 0;
+    const scaled = (magnitude - deadzone) / (1 - deadzone);
+    const curved = Math.pow(Math.min(scaled, 1), binding.curve ?? 1);
+    return Math.sign(value) * curved;
+}
+function clampUnit(value) {
+    return value < -1 ? -1 : value > 1 ? 1 : value;
+}

package/dist/input/touchScheme.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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;
+    /** Overrides the derived classification: `primary` renders as a large thumb button, `utility` as a small chip away from the thumb zones. */
+    kind?: TouchButtonKind;
+}
+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 type TouchButtonKind = "primary" | "utility";
+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;
+    /** `primary` = frequent gameplay verb, rendered as a large thumb button; `utility` = meta action (start, restart, pause, toggles), rendered as a small chip. */
+    kind: TouchButtonKind;
+}
+export interface TouchScheme {
+    joystick: TouchJoystick | null;
+    buttons: readonly TouchButton[];
+    gestures: TouchGestureBindings | null;
+    look: boolean;
+    lookSensitivity: number;
+}
+export declare function touchButtonKind(action: string): TouchButtonKind;
+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,153 @@
+/**
+ * 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", "moveUp", "forward", "accelerate", "throttleUp", "pitchUp", "climb"],
+    down: ["moveBack", "moveBackward", "moveDown", "backward", "reverse", "brake", "throttleDown", "pitchDown", "dive"],
+    left: ["moveLeft", "turnLeft", "steerLeft", "yawLeft", "strafeLeft", "bankLeft", "rollLeft"],
+    right: ["moveRight", "turnRight", "steerRight", "yawRight", "strafeRight", "bankRight", "rollRight"],
+};
+const BUTTONABLE_RESERVED = new Set(["jump", "sprint", "interact", "useAbility"]);
+const UTILITY_ACTIONS = new Set([
+    "start",
+    "restart",
+    "reset",
+    "retry",
+    "pause",
+    "resume",
+    "menu",
+    "quit",
+    "exit",
+    "mute",
+    "unmute",
+    "help",
+    "settings",
+    "options",
+    "map",
+    "inventory",
+    "scoreboard",
+    "leaderboard",
+]);
+const UTILITY_PREFIXES = ["toggle", "cycle", "switch", "open", "close", "show", "hide", "zoom"];
+export function touchButtonKind(action) {
+    if (UTILITY_ACTIONS.has(action))
+        return "utility";
+    for (const prefix of UTILITY_PREFIXES) {
+        if (!action.startsWith(prefix))
+            continue;
+        const next = action.charAt(prefix.length);
+        if (next !== "" && next === next.toUpperCase())
+            return "utility";
+    }
+    return "primary";
+}
+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, kind: touchButtonKind(spec) }
+            : {
+                action: spec.action,
+                label: spec.label ?? touchActionLabel(spec.action),
+                icon: spec.icon ?? null,
+                kind: spec.kind ?? touchButtonKind(spec.action),
+            });
+    }
+    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, kind: touchButtonKind(action) }));
+    }
+    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/item/affix.d.ts

@@ -45,7 +45,7 @@ export interface RolledItem {
     affixes: readonly RolledAffix[];
     stats: Record<string, number>;
 }
-export declare function seededRng(seed: string | number): () => number;
+export { seededRng } from "../random/rng.js";
 export interface AffixRoller {
     rollRarity(rng: () => number): RarityTier;
     roll(base: ItemBaseDef, rarityId: string, rng: () => number): RolledItem;