@aethervtt/shard-input 0.0.1

package/dist/bindings.js

@@ -0,0 +1,107 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { GAMEPAD_AXES, GAMEPAD_BUTTONS } from "./devices.js";
+const MOUSE_BUTTONS = {
+  Left: "left",
+  Middle: "middle",
+  Right: "right",
+  Back: "back",
+  Forward: "forward"
+};
+const MOUSE_AXES = ["WheelX", "WheelY", "DeltaX", "DeltaY"];
+const KEY_CODES = /* @__PURE__ */ new Set([
+  ..."ABCDEFGHIJKLMNOPQRSTUVWXYZ".split("").map((c) => `Key${c}`),
+  ..."0123456789".split("").map((d) => `Digit${d}`),
+  ...Array.from({ length: 12 }, (_, i) => `F${i + 1}`),
+  ..."0123456789".split("").map((d) => `Numpad${d}`),
+  "Space",
+  "Enter",
+  "Escape",
+  "Tab",
+  "Backspace",
+  "Delete",
+  "Insert",
+  "Home",
+  "End",
+  "PageUp",
+  "PageDown",
+  "ArrowUp",
+  "ArrowDown",
+  "ArrowLeft",
+  "ArrowRight",
+  "ShiftLeft",
+  "ShiftRight",
+  "ControlLeft",
+  "ControlRight",
+  "AltLeft",
+  "AltRight",
+  "MetaLeft",
+  "MetaRight",
+  "CapsLock",
+  "Minus",
+  "Equal",
+  "BracketLeft",
+  "BracketRight",
+  "Backslash",
+  "Semicolon",
+  "Quote",
+  "Backquote",
+  "Comma",
+  "Period",
+  "Slash",
+  "NumpadAdd",
+  "NumpadSubtract",
+  "NumpadMultiply",
+  "NumpadDivide",
+  "NumpadEnter",
+  "NumpadDecimal"
+]);
+function unknown(binding, valid) {
+  return new ShardError("input/unknown-binding", `Unknown input binding "${binding}"`, {
+    hint: `Valid: ${valid.join(", ")}.`,
+    path: binding
+  });
+}
+function parseBinding(binding) {
+  const [device, name] = binding.split(":");
+  if (!name) throw unknown(binding, ["Key:<code>", "Mouse:<name>", "Gamepad:<name>", "Touch:Any"]);
+  switch (device) {
+    case "Key":
+      if (!KEY_CODES.has(name))
+        throw unknown(binding, [
+          "Key:KeyA\u2026KeyZ",
+          "Key:Digit0\u20269",
+          "Key:Space",
+          "Key:ArrowUp",
+          "Key:ShiftLeft",
+          "\u2026"
+        ]);
+      return { device: "key", code: name };
+    case "Mouse":
+      if (name in MOUSE_BUTTONS) return { device: "mouse-button", button: MOUSE_BUTTONS[name] };
+      if (MOUSE_AXES.includes(name))
+        return { device: "mouse-axis", axis: name };
+      throw unknown(
+        binding,
+        [...Object.keys(MOUSE_BUTTONS), ...MOUSE_AXES].map((n) => `Mouse:${n}`)
+      );
+    case "Gamepad":
+      if (GAMEPAD_BUTTONS.includes(name))
+        return { device: "gamepad-button", button: name };
+      if (GAMEPAD_AXES.includes(name))
+        return { device: "gamepad-axis", axis: name };
+      if (name === "LeftStick" || name === "RightStick")
+        return { device: "gamepad-stick", stick: name };
+      throw unknown(
+        binding,
+        [...GAMEPAD_BUTTONS, ...GAMEPAD_AXES, "LeftStick", "RightStick"].map((n) => `Gamepad:${n}`)
+      );
+    case "Touch":
+      if (name === "Any") return { device: "touch" };
+      throw unknown(binding, ["Touch:Any"]);
+    default:
+      throw unknown(binding, ["Key:<code>", "Mouse:<name>", "Gamepad:<name>", "Touch:Any"]);
+  }
+}
+export {
+  parseBinding
+};

package/dist/devices.d.ts

@@ -0,0 +1,77 @@
+import type { MouseButton } from '@aethervtt/shard-platform';
+/** Pressed/just-pressed/just-released bookkeeping for a set of named buttons. */
+declare class ButtonSet<K extends string> {
+    private readonly down;
+    private readonly pressedNow;
+    private readonly releasedNow;
+    /** @internal start of frame */
+    beginFrame(): void;
+    /** @internal */
+    set(key: K, pressed: boolean): void;
+    /** @internal release everything (focus loss) */
+    releaseAll(): void;
+    pressed(key: K): boolean;
+    justPressed(key: K): boolean;
+    justReleased(key: K): boolean;
+    /** Currently held keys. */
+    held(): K[];
+}
+/** Keys by `KeyboardEvent.code` (physical position: `KeyW`, `Space`, `ArrowUp`, `ShiftLeft`). */
+export declare class KeyboardState extends ButtonSet<string> {
+    /** Characters typed this frame, key repeats included; "\b" is a backspace. For text fields. */
+    typed: string;
+    /** @internal */
+    beginFrame(): void;
+}
+export declare class MouseState extends ButtonSet<MouseButton> {
+    /** Pointer position in canvas pixels. */
+    readonly position: [number, number];
+    /** Movement this frame, in canvas pixels (works under pointer lock). */
+    readonly delta: [number, number];
+    /** Wheel movement this frame, in pixels. */
+    readonly wheel: [number, number];
+    /**
+     * The pointer belongs to something drawn over the game (UI) this frame: action maps read mouse
+     * buttons and the wheel as released, so clicking a HUD button doesn't also fire.
+     */
+    captured: boolean;
+    /** @internal */
+    beginFrame(): void;
+}
+export declare const GAMEPAD_BUTTONS: readonly ['South', 'East', 'West', 'North', 'LeftBumper', 'RightBumper', 'LeftTrigger', 'RightTrigger', 'Select', 'Start', 'LeftStickPress', 'RightStickPress', 'DpadUp', 'DpadDown', 'DpadLeft', 'DpadRight', 'Home'];
+export declare const GAMEPAD_AXES: readonly ['LeftStickX', 'LeftStickY', 'RightStickX', 'RightStickY'];
+export type GamepadButton = (typeof GAMEPAD_BUTTONS)[number];
+export type GamepadAxis = (typeof GAMEPAD_AXES)[number];
+/** One gamepad in the standard mapping. Stick Y is up-positive here (the DOM's is down-positive). */
+export declare class GamepadState extends ButtonSet<GamepadButton> {
+    connected: boolean;
+    readonly buttonValues: Float32Array<ArrayBuffer>;
+    readonly axisValues: Float32Array<ArrayBuffer>;
+    button(name: GamepadButton): number;
+    axis(name: GamepadAxis): number;
+}
+export declare class GamepadsState {
+    private readonly pads;
+    get(index: number): GamepadState | undefined;
+    /** Connected gamepads. */
+    connected(): GamepadState[];
+    /** @internal */
+    slot(index: number): GamepadState;
+    /** @internal */
+    beginFrame(): void;
+}
+export interface Touch {
+    id: number;
+    position: [number, number];
+    start: [number, number];
+}
+export declare class TouchesState {
+    readonly active: Map<number, Touch>;
+    readonly started: number[];
+    readonly ended: number[];
+    /** Touches that belong to UI: action maps don't see them. */
+    readonly captured: Set<number>;
+    /** @internal */
+    beginFrame(): void;
+}
+export {};

package/dist/devices.js

@@ -0,0 +1,137 @@
+class ButtonSet {
+  down = /* @__PURE__ */ new Set();
+  pressedNow = /* @__PURE__ */ new Set();
+  releasedNow = /* @__PURE__ */ new Set();
+  /** @internal start of frame */
+  beginFrame() {
+    this.pressedNow.clear();
+    this.releasedNow.clear();
+  }
+  /** @internal */
+  set(key, pressed) {
+    if (pressed && !this.down.has(key)) {
+      this.down.add(key);
+      this.pressedNow.add(key);
+    } else if (!pressed && this.down.has(key)) {
+      this.down.delete(key);
+      this.releasedNow.add(key);
+    }
+  }
+  /** @internal release everything (focus loss) */
+  releaseAll() {
+    for (const key of this.down) this.releasedNow.add(key);
+    this.down.clear();
+  }
+  pressed(key) {
+    return this.down.has(key);
+  }
+  justPressed(key) {
+    return this.pressedNow.has(key);
+  }
+  justReleased(key) {
+    return this.releasedNow.has(key);
+  }
+  /** Currently held keys. */
+  held() {
+    return [...this.down];
+  }
+}
+class KeyboardState extends ButtonSet {
+  /** Characters typed this frame, key repeats included; "\b" is a backspace. For text fields. */
+  typed = "";
+  /** @internal */
+  beginFrame() {
+    super.beginFrame();
+    this.typed = "";
+  }
+}
+class MouseState extends ButtonSet {
+  /** Pointer position in canvas pixels. */
+  position = [0, 0];
+  /** Movement this frame, in canvas pixels (works under pointer lock). */
+  delta = [0, 0];
+  /** Wheel movement this frame, in pixels. */
+  wheel = [0, 0];
+  /**
+   * The pointer belongs to something drawn over the game (UI) this frame: action maps read mouse
+   * buttons and the wheel as released, so clicking a HUD button doesn't also fire.
+   */
+  captured = false;
+  /** @internal */
+  beginFrame() {
+    super.beginFrame();
+    this.delta[0] = this.delta[1] = 0;
+    this.wheel[0] = this.wheel[1] = 0;
+  }
+}
+const GAMEPAD_BUTTONS = [
+  "South",
+  "East",
+  "West",
+  "North",
+  "LeftBumper",
+  "RightBumper",
+  "LeftTrigger",
+  "RightTrigger",
+  "Select",
+  "Start",
+  "LeftStickPress",
+  "RightStickPress",
+  "DpadUp",
+  "DpadDown",
+  "DpadLeft",
+  "DpadRight",
+  "Home"
+];
+const GAMEPAD_AXES = ["LeftStickX", "LeftStickY", "RightStickX", "RightStickY"];
+class GamepadState extends ButtonSet {
+  connected = false;
+  buttonValues = new Float32Array(GAMEPAD_BUTTONS.length);
+  axisValues = new Float32Array(GAMEPAD_AXES.length);
+  button(name) {
+    return this.buttonValues[GAMEPAD_BUTTONS.indexOf(name)] ?? 0;
+  }
+  axis(name) {
+    return this.axisValues[GAMEPAD_AXES.indexOf(name)] ?? 0;
+  }
+}
+class GamepadsState {
+  pads = [];
+  get(index) {
+    return this.pads[index]?.connected ? this.pads[index] : void 0;
+  }
+  /** Connected gamepads. */
+  connected() {
+    return this.pads.filter((p) => p.connected);
+  }
+  /** @internal */
+  slot(index) {
+    this.pads[index] ??= new GamepadState();
+    return this.pads[index];
+  }
+  /** @internal */
+  beginFrame() {
+    for (const pad of this.pads) pad?.beginFrame();
+  }
+}
+class TouchesState {
+  active = /* @__PURE__ */ new Map();
+  started = [];
+  ended = [];
+  /** Touches that belong to UI: action maps don't see them. */
+  captured = /* @__PURE__ */ new Set();
+  /** @internal */
+  beginFrame() {
+    this.started.length = 0;
+    this.ended.length = 0;
+  }
+}
+export {
+  GAMEPAD_AXES,
+  GAMEPAD_BUTTONS,
+  GamepadState,
+  GamepadsState,
+  KeyboardState,
+  MouseState,
+  TouchesState
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { type ActionDef, type ActionMapDef, ActionState, type Axis1dAction, type Axis2dAction, actionMapSchema, type ButtonAction, defineActions, type Interaction, } from './actions.js';
+export { type ParsedBinding, parseBinding } from './bindings.js';
+export { GAMEPAD_AXES, GAMEPAD_BUTTONS, type GamepadAxis, type GamepadButton, GamepadState, GamepadsState, KeyboardState, MouseState, type Touch, TouchesState, } from './devices.js';
+export { addActions, describeInput, Gamepads, type InjectedInput, InputContext, type InputContextValue, type InputPluginOptions, InputQueue, injectInput, inputPlugin, Keyboard, Mouse, rebindAction, startRecording, startReplay, stopRecording, Touches, updateActions, updateInput, } from './plugin.js';

package/dist/index.js

@@ -0,0 +1,62 @@
+import {
+  ActionState,
+  actionMapSchema,
+  defineActions
+} from "./actions.js";
+import { parseBinding } from "./bindings.js";
+import {
+  GAMEPAD_AXES,
+  GAMEPAD_BUTTONS,
+  GamepadState,
+  GamepadsState,
+  KeyboardState,
+  MouseState,
+  TouchesState
+} from "./devices.js";
+import {
+  addActions,
+  describeInput,
+  Gamepads,
+  InputContext,
+  InputQueue,
+  injectInput,
+  inputPlugin,
+  Keyboard,
+  Mouse,
+  rebindAction,
+  startRecording,
+  startReplay,
+  stopRecording,
+  Touches,
+  updateActions,
+  updateInput
+} from "./plugin.js";
+export {
+  ActionState,
+  GAMEPAD_AXES,
+  GAMEPAD_BUTTONS,
+  GamepadState,
+  Gamepads,
+  GamepadsState,
+  InputContext,
+  InputQueue,
+  Keyboard,
+  KeyboardState,
+  Mouse,
+  MouseState,
+  Touches,
+  TouchesState,
+  actionMapSchema,
+  addActions,
+  defineActions,
+  describeInput,
+  injectInput,
+  inputPlugin,
+  parseBinding,
+  rebindAction,
+  startRecording,
+  startReplay,
+  stopRecording,
+  updateActions,
+  updateInput
+};

package/dist/plugin.d.ts

@@ -0,0 +1,93 @@
+import { type World } from '@aethervtt/shard-core';
+import type { InputSource, RawInputEvent } from '@aethervtt/shard-platform';
+import { type Plugin } from '@aethervtt/shard-runtime';
+import type { ActionMapDef, ActionState } from './actions.js';
+import { GamepadsState, KeyboardState, MouseState, TouchesState } from './devices.js';
+export declare const Keyboard: import("@aethervtt/shard-core").ResourceDef<KeyboardState>;
+export declare const Mouse: import("@aethervtt/shard-core").ResourceDef<MouseState>;
+export declare const Gamepads: import("@aethervtt/shard-core").ResourceDef<GamepadsState>;
+export declare const Touches: import("@aethervtt/shard-core").ResourceDef<TouchesState>;
+interface InputQueueState {
+    source: InputSource | undefined;
+    /** Injected events, applied at the start of the next frame. */
+    pending: RawInputEvent[];
+    scratch: RawInputEvent[];
+    maps: ActionState<string>[];
+    /** Frames recorded so far (events per frame), when recording. */
+    recording: RawInputEvent[][] | undefined;
+    /** Frames to play back instead of live input, when replaying. */
+    replay: {
+        frames: Map<number, RawInputEvent[]>;
+        frame: number;
+        length: number;
+    } | undefined;
+}
+export declare const InputQueue: import("@aethervtt/shard-core").ResourceDef<InputQueueState>;
+export interface InputPluginOptions {
+    /** Live input (e.g. `createDomInputSource(canvas)`). Omit when headless. */
+    source?: InputSource;
+    /** Action maps to install as resources. */
+    actions?: readonly ActionMapDef<string>[];
+}
+export interface InputContextValue {
+    /** Action maps listen only in their own context (`game` by default) or `any`. */
+    active: string;
+}
+export declare const InputContext: import("@aethervtt/shard-core").ResourceDef<InputContextValue>;
+/** Drains input once, at the start of the frame, so every system sees the same state. */
+export declare const updateInput: import("@aethervtt/shard-core").SystemDef<undefined>;
+/**
+ * Recomputes action maps from device state, after `input/update`. Systems that claim input first
+ * (UI capturing the pointer, setting the context) run between the two.
+ */
+export declare const updateActions: import("@aethervtt/shard-core").SystemDef<undefined>;
+export declare function inputPlugin(options?: InputPluginOptions): Plugin;
+/** Installs an action map as a resource (also callable after startup). */
+export declare function addActions<K extends string>(world: World, map: ActionMapDef<K>): ActionState<K>;
+/**
+ * Rebinds one action by `"<map>.<action>"` (`rebindAction(world, 'game/Controls.jump',
+ * ['Key:KeyJ'])`); `undefined` restores the authored bindings. With the save plugin, the engine
+ * settings keep rebindings across restarts.
+ */
+export declare function rebindAction(world: World, action: string, bindings: readonly unknown[] | undefined): void;
+export type InjectedInput = RawInputEvent | {
+    key: string;
+    pressed: boolean;
+} | {
+    mouse: 'left' | 'middle' | 'right';
+    pressed: boolean;
+} | {
+    action: string;
+    pressed: boolean;
+    value?: number;
+};
+/**
+ * Queues synthetic input, applied at the start of the next frame through the same path as real
+ * input (so it's recorded and replayed too). Actions are named `"<map>.<action>"`.
+ */
+export declare function injectInput(world: World, input: InjectedInput): void;
+export declare function startRecording(world: World): void;
+/** Stops recording and returns it as JSON lines: `{"f":<frame>,"e":[...events]}` per non-empty frame. */
+export declare function stopRecording(world: World): string;
+/** Plays a recording back from the next frame on, ignoring live input until it ends. */
+export declare function startReplay(world: World, recording: string): void;
+/** Devices, action maps, and current values. For agents. */
+export declare function describeInput(world: World): {
+    source: string;
+    recording: boolean;
+    replaying: boolean;
+    keysHeld: string[];
+    gamepads: number;
+    touches: number;
+    context: string;
+    pointerCaptured: boolean;
+    actionMaps: {
+        name: string;
+        enabled: boolean;
+        context: string;
+        live: boolean;
+        values: Record<string, unknown>;
+        rebindings: Partial<Record<string, readonly string[] | readonly import("./actions.js").Axis1dBinding[] | readonly import("./actions.js").Axis2dBinding[]>>;
+    }[];
+};
+export {};