@waica/engine 0.20.0 → 0.22.0

package/README.md

@@ -137,6 +137,17 @@ A seeded Mulberry32 stream makes equivalent runs deterministic; `emit(count)` us
 
 Textures use the Game's shared `AssetLoader`; `pixelArt` chooses nearest or linear filtering, and `blend` selects normal or additive blending. All three are reactive authoring props. A failed or empty texture falls back to the flat colored quad. Batching keeps one draw submission but does not promise order-independent or globally exact alpha composition between meshes. `destroyMode: 'clear'` removes the batch with its owner; `'drain'` transfers it to scene scope, stops emission, and simulates it until empty. Scene unload and `game.dispose()` always clear drains.
 
+The three stock archetypes ship authored effects built on this component. In each case the emitter holds the look, and a small cue component from `@waica/behaviors` decides when it emits:
+
+| Cue | What it does | Archetype |
+| --- | --- | --- |
+| `SwingSparks` | Bursts `count` particles when the sibling `StateMachine` enters `state`. | isometric (player sword sparks) |
+| `DamagePuff` | Moves its entity to whatever `Health` reports on the `damage` event and bursts there. | isometric (`objects/hurt-smoke`) |
+| `DustPuffs` | Puffs on a ground takeoff into `jump` and bursts on any grounded exit from `jump` or `fall`. | platformer (player dust) |
+| `DustTrail` | Turns `emitting` on only while the machine is in `state`. | topdown (player walking dust) |
+
+The cues that hook a `StateMachine` must come after it and after the `ParticleEmitter` in the component list. The isometric demo also places plain emitter objects: `objects/wind` in the meadow and `objects/cave-dust` in the cave.
+
 `active`, `capacity`, and `emitting` are the only fields exposed by Runtime Snapshot. Particle arrays remain private. This first CPU implementation is intended for bounded 2D effects, not collision, per-particle scripting, GPU simulation, trails, rotation, or sub-emitters.
 
 ## Component lifecycle

package/dist/game.d.ts

@@ -29,8 +29,10 @@ export interface GameOptions {
     viewHeight?: number;
     /** Fixed resolution (from the project's game.json); absent = fill the canvas. */
     resolution?: GameResolution;
-    /** Control overrides (action → key codes) on top of the defaults. */
+    /** Control overrides (action → key and `Gamepad:` codes) on top of the defaults. */
     bindings?: InputBindings;
+    /** Radial stick dead zone of `game.input`, in [0, 1); absent or invalid means 0.2 (ADR 0023). */
+    gamepadDeadZone?: number;
     /** Initial stat values (points, lives…) from the project's stats.json. */
     stats?: Record<string, StatValue>;
     /**
@@ -233,8 +235,8 @@ export declare class Game {
      */
     private runFrame;
     /**
-     * One Simulation Step: game.time's start-of-step pass (ADR 0017, CA-3)
-     * first, then the Component Update Schedule (ADR 0004) in full,
+     * One Simulation Step: the pad is read first (issue #75 CA-6), then
+     * game.time's start-of-step pass (ADR 0017, CA-3), then the Component Update Schedule (ADR 0004) in full,
      * collisions, the scene camera and the host's callbacks, every one of
      * them handed exactly SIMULATION_STEP (CA-1); then the input frame ends.
      */

package/dist/game.js

@@ -109,7 +109,7 @@ export class Game {
         this.baseViewHeight = viewHeight;
         this.viewHeight = viewHeight;
         this.resolution = options.resolution ?? null;
-        this.input = new Input(options.bindings);
+        this.input = new Input(options.bindings, { gamepadDeadZone: options.gamepadDeadZone });
         this.query = createSpatialQuery(this);
         this.stats = new Stats(options.stats);
         this.ui = new GameUi(this.stats, () => canvas.parentElement ?? document.body);
@@ -339,9 +339,10 @@ export class Game {
                     step: (onStep) => this.runFrame(1, onStep),
                     resume: (onStep) => this.resumeRuntime(onStep),
                     pause: () => this.stop(),
-                    injectAction: (action, operation) => this.input.injectAction(action, operation),
+                    injectAction: (action, operation, value) => this.input.injectAction(action, operation, value),
                     availableActions: () => this.input.availableActions(),
                     heldActions: () => this.input.heldActions(),
+                    actionValues: () => this.input.actionValues(),
                     inspect: (metadata, filters) => inspector.snapshot(metadata, filters),
                     click: (x, y) => {
                         this.pointer.injectClick(x, y);
@@ -489,12 +490,13 @@ export class Game {
         }
     }
     /**
-     * One Simulation Step: game.time's start-of-step pass (ADR 0017, CA-3)
-     * first, then the Component Update Schedule (ADR 0004) in full,
+     * One Simulation Step: the pad is read first (issue #75 CA-6), then
+     * game.time's start-of-step pass (ADR 0017, CA-3), then the Component Update Schedule (ADR 0004) in full,
      * collisions, the scene camera and the host's callbacks, every one of
      * them handed exactly SIMULATION_STEP (CA-1); then the input frame ends.
      */
     simulateStep() {
+        this.input.pollGamepad();
         advanceGameTime(this.time);
         // Existing drains advance before entity updates, so one detached during
         // this step begins on the next Simulation Step (ADR 0022).

package/dist/gamepad.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Gamepad sources for Actions (ADR 0023): the `Gamepad:<control>` binding
+ * vocabulary over the W3C `standard` mapping, the radial dead zone, and the
+ * player-1 pad slot. `Input` consumes this module; behaviors never see a pad.
+ */
+/** The slice of the W3C `Gamepad` object Waica reads, so tests can hand in plain objects. */
+export interface GamepadLike {
+    readonly index: number;
+    readonly id: string;
+    readonly mapping: string;
+    readonly connected: boolean;
+    readonly axes: readonly number[];
+    readonly buttons: readonly {
+        readonly value: number;
+    }[];
+}
+/** One pad control a binding code names: a button by index, or one half of a stick axis. */
+export type GamepadControl = {
+    kind: 'button';
+    index: number;
+} | {
+    kind: 'stick';
+    axis: number;
+    sign: 1 | -1;
+};
+export declare const GAMEPAD_CODE_PREFIX = "Gamepad:";
+/** An Action's source counts as held at this value or above (keys are always 1 while down). */
+export declare const ACTION_HELD_THRESHOLD = 0.5;
+/** Radial dead zone used when `GameOptions.gamepadDeadZone` is absent or invalid. */
+export declare const DEFAULT_GAMEPAD_DEAD_ZONE = 0.2;
+/** Every known `Gamepad:` code: buttons in index order, then the stick halves. */
+export declare const GAMEPAD_CODES: readonly string[];
+/** The control a binding code names; undefined for a keyboard code or an unknown pad name. */
+export declare function gamepadControl(code: string): GamepadControl | undefined;
+/**
+ * Radial dead zone: a stick shorter than `deadZone` reads as centered on
+ * both axes; past it the direction is kept and the magnitude is rescaled
+ * to `(m − d) / (1 − d)`, clamped to 1.
+ */
+export declare function radialDeadZone(x: number, y: number, deadZone: number): {
+    x: number;
+    y: number;
+};
+/** The configured dead zone if it is a finite number in [0, 1); otherwise warns once and uses the default. */
+export declare function resolveGamepadDeadZone(value: number | undefined, warn: (message: string) => void): number;
+/** Each known code's 0..1 value on this pad: buttons by `value`, stick halves dead-zoned per stick. */
+export declare function gamepadValues(pad: GamepadLike, deadZone: number): Map<string, number>;
+/** The browser's pads, or none where the Gamepad API is missing or refused (Node, happy-dom, a policy-blocked frame). */
+export declare function connectedGamepads(): readonly (GamepadLike | null)[];
+/** One poll of the player-1 slot: its pad, and whether the poll lost the pad that was active before it. */
+export interface GamepadSlotPoll {
+    pad: GamepadLike | null;
+    lostActive: boolean;
+}
+/**
+ * @internal Editor support (the controls panel's pad capture), not a stable
+ * API: each known code's value on the first connected standard pad at the
+ * default dead zone, or null when no such pad is present.
+ */
+export declare function firstStandardPadValues(): Map<string, number> | null;
+/**
+ * Player 1's pad: the first `standard` pad to connect, sticky until it
+ * disconnects; then the next one in connection order takes over. Order is
+ * the order polls first saw each pad (by index on the same poll).
+ */
+export declare class GamepadSlot {
+    private order;
+    private activeKey;
+    poll(pads: readonly (GamepadLike | null)[]): GamepadSlotPoll;
+}
+/** A connected pad with the W3C `standard` mapping; any other pad is ignored entirely. */
+export declare function isStandardPad(pad: GamepadLike | null | undefined): pad is GamepadLike;

package/dist/gamepad.js

@@ -0,0 +1,137 @@
+/**
+ * Gamepad sources for Actions (ADR 0023): the `Gamepad:<control>` binding
+ * vocabulary over the W3C `standard` mapping, the radial dead zone, and the
+ * player-1 pad slot. `Input` consumes this module; behaviors never see a pad.
+ */
+export const GAMEPAD_CODE_PREFIX = 'Gamepad:';
+/** An Action's source counts as held at this value or above (keys are always 1 while down). */
+export const ACTION_HELD_THRESHOLD = 0.5;
+/** Radial dead zone used when `GameOptions.gamepadDeadZone` is absent or invalid. */
+export const DEFAULT_GAMEPAD_DEAD_ZONE = 0.2;
+/** Standard-mapping buttons in W3C index order (0–16). */
+const BUTTON_NAMES = [
+    'A', 'B', 'X', 'Y', 'LB', 'RB', 'LT', 'RT', 'Back', 'Start', 'LeftStick', 'RightStick',
+    'DPadUp', 'DPadDown', 'DPadLeft', 'DPadRight', 'Home',
+];
+/** Stick halves: axes 0/1 are the left stick, 2/3 the right; "Up" is the negative Y axis. */
+const STICK_HALVES = {
+    LeftStickLeft: { axis: 0, sign: -1 },
+    LeftStickRight: { axis: 0, sign: 1 },
+    LeftStickUp: { axis: 1, sign: -1 },
+    LeftStickDown: { axis: 1, sign: 1 },
+    RightStickLeft: { axis: 2, sign: -1 },
+    RightStickRight: { axis: 2, sign: 1 },
+    RightStickUp: { axis: 3, sign: -1 },
+    RightStickDown: { axis: 3, sign: 1 },
+};
+const CONTROLS = new Map([
+    ...BUTTON_NAMES.map((name, index) => [
+        `${GAMEPAD_CODE_PREFIX}${name}`,
+        { kind: 'button', index },
+    ]),
+    ...Object.entries(STICK_HALVES).map(([name, half]) => [
+        `${GAMEPAD_CODE_PREFIX}${name}`,
+        { kind: 'stick', ...half },
+    ]),
+]);
+/** Every known `Gamepad:` code: buttons in index order, then the stick halves. */
+export const GAMEPAD_CODES = [...CONTROLS.keys()];
+/** The control a binding code names; undefined for a keyboard code or an unknown pad name. */
+export function gamepadControl(code) {
+    const control = CONTROLS.get(code);
+    return control ? { ...control } : undefined;
+}
+/**
+ * Radial dead zone: a stick shorter than `deadZone` reads as centered on
+ * both axes; past it the direction is kept and the magnitude is rescaled
+ * to `(m − d) / (1 − d)`, clamped to 1.
+ */
+export function radialDeadZone(x, y, deadZone) {
+    const magnitude = Math.hypot(x, y);
+    if (magnitude === 0 || magnitude < deadZone)
+        return { x: 0, y: 0 };
+    const scaled = Math.min(1, (magnitude - deadZone) / (1 - deadZone));
+    return { x: (x / magnitude) * scaled, y: (y / magnitude) * scaled };
+}
+/** The configured dead zone if it is a finite number in [0, 1); otherwise warns once and uses the default. */
+export function resolveGamepadDeadZone(value, warn) {
+    if (value === undefined)
+        return DEFAULT_GAMEPAD_DEAD_ZONE;
+    if (Number.isFinite(value) && value >= 0 && value < 1)
+        return value;
+    warn(`[waica] gamepadDeadZone must be a finite number from 0 up to (not including) 1; ` +
+        `got ${String(value)}, using ${DEFAULT_GAMEPAD_DEAD_ZONE}.`);
+    return DEFAULT_GAMEPAD_DEAD_ZONE;
+}
+/** Each known code's 0..1 value on this pad: buttons by `value`, stick halves dead-zoned per stick. */
+export function gamepadValues(pad, deadZone) {
+    const axis = (index) => pad.axes[index] ?? 0;
+    const sticks = [
+        radialDeadZone(axis(0), axis(1), deadZone),
+        radialDeadZone(axis(2), axis(3), deadZone),
+    ];
+    const values = new Map();
+    for (const [code, control] of CONTROLS) {
+        if (control.kind === 'button') {
+            values.set(code, pad.buttons[control.index]?.value ?? 0);
+            continue;
+        }
+        const stick = sticks[control.axis >> 1] ?? { x: 0, y: 0 };
+        const component = control.axis % 2 === 0 ? stick.x : stick.y;
+        values.set(code, Math.max(0, component * control.sign));
+    }
+    return values;
+}
+/** The browser's pads, or none where the Gamepad API is missing or refused (Node, happy-dom, a policy-blocked frame). */
+export function connectedGamepads() {
+    if (typeof navigator === 'undefined' || typeof navigator.getGamepads !== 'function')
+        return [];
+    try {
+        return navigator.getGamepads();
+    }
+    catch {
+        // A permissions policy can make getGamepads throw; input stays keyboard-only.
+        return [];
+    }
+}
+/**
+ * @internal Editor support (the controls panel's pad capture), not a stable
+ * API: each known code's value on the first connected standard pad at the
+ * default dead zone, or null when no such pad is present.
+ */
+export function firstStandardPadValues() {
+    const pad = connectedGamepads().find(isStandardPad);
+    return pad ? gamepadValues(pad, DEFAULT_GAMEPAD_DEAD_ZONE) : null;
+}
+/**
+ * Player 1's pad: the first `standard` pad to connect, sticky until it
+ * disconnects; then the next one in connection order takes over. Order is
+ * the order polls first saw each pad (by index on the same poll).
+ */
+export class GamepadSlot {
+    order = [];
+    activeKey = null;
+    poll(pads) {
+        const present = new Map();
+        for (const pad of pads)
+            if (isStandardPad(pad))
+                present.set(slotKey(pad), pad);
+        this.order = this.order.filter((key) => present.has(key));
+        for (const key of present.keys())
+            if (!this.order.includes(key))
+                this.order.push(key);
+        const previous = this.activeKey;
+        this.activeKey = this.order[0] ?? null;
+        return {
+            pad: this.activeKey === null ? null : (present.get(this.activeKey) ?? null),
+            lostActive: previous !== null && previous !== this.activeKey,
+        };
+    }
+}
+/** A connected pad with the W3C `standard` mapping; any other pad is ignored entirely. */
+export function isStandardPad(pad) {
+    return pad?.connected === true && pad.mapping === 'standard';
+}
+function slotKey(pad) {
+    return `${pad.index}|${pad.id}`;
+}

package/dist/index.d.ts

@@ -31,7 +31,9 @@ export type { ComponentModule } from './component-registry.js';
 export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 export type { ComponentUpdateCycleIssue, ComponentUpdateRegistry, ComponentUpdateScheduleIssue, ComponentUpdateScheduleResult, DuplicateComponentUpdateIssue, InvalidComponentUpdateConstraintIssue, InvalidComponentUpdateSchedule, InvalidUpdateConstraintReason, ValidComponentUpdateSchedule, } from './component-update-schedule.js';
 export { Input, DEFAULT_BINDINGS } from './input.js';
-export type { ActionName, InjectedActionOperation, InputBindings } from './input.js';
+export type { ActionName, InjectedActionOperation, InputBindings, InputOptions } from './input.js';
+export { ACTION_HELD_THRESHOLD, firstStandardPadValues, GAMEPAD_CODE_PREFIX, gamepadControl, } from './gamepad.js';
+export type { GamepadControl } from './gamepad.js';
 export { Pointer } from './pointer.js';
 export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from './pointer.js';
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export { authoringDefaults } from './authoring-defaults.js';
 export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
 export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 export { Input, DEFAULT_BINDINGS } from './input.js';
+export { ACTION_HELD_THRESHOLD, firstStandardPadValues, GAMEPAD_CODE_PREFIX, gamepadControl, } from './gamepad.js';
 export { Pointer } from './pointer.js';
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';

package/dist/input.d.ts

@@ -1,41 +1,89 @@
 export type ActionName = string;
 export type InjectedActionOperation = 'press' | 'hold' | 'release';
-/** Action → KeyboardEvent.code list. */
+/** Action → source codes: `KeyboardEvent.code` values and `Gamepad:<control>` codes (ADR 0023). */
 export type InputBindings = Record<string, string[]>;
 /** Neutral engine baseline; archetypes own their action vocabulary. */
 export declare const DEFAULT_BINDINGS: Readonly<InputBindings>;
+/** An injection's checked `value`, or why it is rejected. */
+export type InjectedValueCheck = {
+    value: number | undefined;
+} | {
+    error: string;
+};
 /**
- * Action-based input with archetype default bindings.
- * v0: keyboard. TODO(H1): gamepad and touch.
+ * The injection value rule Input and the Runtime Bridge share: only `hold`
+ * takes a value, a finite number in (0, 1]; an absent value always passes.
+ */
+export declare function checkInjectedValue(operation: InjectedActionOperation, value: unknown): InjectedValueCheck;
+export interface InputOptions {
+    /** Radial stick dead zone in [0, 1); absent or invalid means 0.2. */
+    gamepadDeadZone?: number;
+}
+/**
+ * Action-based input with archetype default bindings. Sources are keys and
+ * player 1's standard gamepad (ADR 0023); every Action has a 0..1 value, the
+ * max across its sources, and is held at 0.5 or above. Touch is still TODO.
  */
 export declare class Input {
     private readonly bindings;
     private readonly down;
     private readonly justDown;
-    private readonly injectedDown;
+    private readonly injectedHolds;
     private readonly injectedJustDown;
     private readonly injectedPresses;
     private readonly used;
+    private readonly deadZone;
+    private readonly padSlot;
+    /** Live pad values by code, after the last poll; disarmed codes read 0. */
+    private padValues;
+    /** Pad codes released while held: they count again only after dropping below the threshold. */
+    private readonly disarmed;
+    /** Actions held when the last step closed: a press is a step that starts from none of them (CA-5). */
+    private heldAtStepEnd;
     /** Installs exactly the action map supplied by the active archetype/project. */
-    constructor(bindings?: Readonly<InputBindings>);
-    /** Is the action held this frame? */
+    constructor(bindings?: Readonly<InputBindings>, options?: InputOptions);
+    /** Is the action held this frame (some source at 0.5 or above)? */
     held(action: ActionName): boolean;
-    /** Was the action pressed exactly this frame? */
+    /**
+     * Was the action pressed exactly this frame? True when no source held it
+     * as the last step closed and some source holds it now — or a key or an
+     * injection held it since, even if already released (a tap between steps).
+     */
     justPressed(action: ActionName): boolean;
+    /**
+     * The action's 0..1 value: the max across its sources — 1 for a key that
+     * is down, a pad button's value, a stick half's dead-zoned component, an
+     * injected hold's value. 0 for an unknown or unbound action.
+     */
+    value(action: ActionName): number;
     /** Installed semantic action names in deterministic order. */
     availableActions(): ActionName[];
     /**
-     * The key codes bound to the action, in their declared order (e.g.
+     * The source codes bound to the action, in their declared order (e.g.
      * `['KeyE', 'Space']`); `[]` for an unknown or unbound action. A new
      * array every call: mutating it never changes the bindings.
      */
     bindingsFor(action: ActionName): string[];
     /** Currently held semantic action names in deterministic order. */
     heldActions(): ActionName[];
-    /** Injects an action by semantic name; false means the action is not installed. */
-    injectAction(action: ActionName, operation: InjectedActionOperation): boolean;
-    /** -1..1 axis from two actions (left/right by default). */
+    /** The value of every held action, keyed in the same order as heldActions(). */
+    actionValues(): Record<ActionName, number>;
+    /**
+     * Injects an action by semantic name; false means the action is not
+     * installed. `hold` takes an optional value in (0, 1] (default 1) and is
+     * one more source of the action: below 0.5 it moves it without holding it.
+     * A value outside (0, 1], or any value on `press`/`release`, throws a
+     * RangeError before anything changes (checkInjectedValue, the Runtime
+     * Bridge's rule).
+     */
+    injectAction(action: ActionName, operation: InjectedActionOperation, value?: number): boolean;
+    /** -1..1 axis from two actions (left/right by default): value(positive) − value(negative). */
     axis(negative?: ActionName, positive?: ActionName): number;
+    /**
+     * Reads player 1's pad. The Game calls this once per Simulation Step,
+     * before component updates.
+     */
+    pollGamepad(): void;
     /**
      * Marks this frame's press of the action as spent, so consumers that
      * honor consumption (state-machine 'input:' triggers) ignore it. One
@@ -49,6 +97,8 @@ export declare class Input {
     endFrame(): void;
     dispose(): void;
     private isActive;
+    /** Every pad source reads 0; the ones that were held stay released until they drop below the threshold. */
+    private releasePad;
     private releaseAll;
     private onVisibilityChange;
     private onKeyDown;

package/dist/input.js

@@ -1,41 +1,96 @@
+import { ACTION_HELD_THRESHOLD, connectedGamepads, GAMEPAD_CODE_PREFIX, gamepadControl, gamepadValues, GamepadSlot, resolveGamepadDeadZone, } from './gamepad.js';
 /** Neutral engine baseline; archetypes own their action vocabulary. */
 export const DEFAULT_BINDINGS = {};
 /**
- * Action-based input with archetype default bindings.
- * v0: keyboard. TODO(H1): gamepad and touch.
+ * The injection value rule Input and the Runtime Bridge share: only `hold`
+ * takes a value, a finite number in (0, 1]; an absent value always passes.
+ */
+export function checkInjectedValue(operation, value) {
+    if (value === undefined)
+        return { value };
+    if (operation !== 'hold')
+        return { error: `${operation} does not accept a value; only hold does.` };
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) {
+        return { error: 'value must be a finite number greater than 0 and at most 1.' };
+    }
+    return { value };
+}
+/**
+ * Action-based input with archetype default bindings. Sources are keys and
+ * player 1's standard gamepad (ADR 0023); every Action has a 0..1 value, the
+ * max across its sources, and is held at 0.5 or above. Touch is still TODO.
  */
 export class Input {
     bindings = new Map();
     down = new Set();
     justDown = new Set();
-    injectedDown = new Set();
+    injectedHolds = new Map();
     injectedJustDown = new Set();
     injectedPresses = new Set();
     used = new Set();
+    deadZone;
+    padSlot = new GamepadSlot();
+    /** Live pad values by code, after the last poll; disarmed codes read 0. */
+    padValues = new Map();
+    /** Pad codes released while held: they count again only after dropping below the threshold. */
+    disarmed = new Set();
+    /** Actions held when the last step closed: a press is a step that starts from none of them (CA-5). */
+    heldAtStepEnd = new Set();
     /** Installs exactly the action map supplied by the active archetype/project. */
-    constructor(bindings = DEFAULT_BINDINGS) {
+    constructor(bindings = DEFAULT_BINDINGS, options = {}) {
+        const warned = new Set();
         for (const [action, codes] of Object.entries(bindings)) {
             this.bindings.set(action, new Set(codes));
+            for (const code of codes)
+                warnUnknownPadCode(code, warned);
         }
+        this.deadZone = resolveGamepadDeadZone(options.gamepadDeadZone, (message) => {
+            console.warn(message);
+        });
         window.addEventListener('keydown', this.onKeyDown);
         window.addEventListener('keyup', this.onKeyUp);
         window.addEventListener('blur', this.releaseAll);
         document.addEventListener('visibilitychange', this.onVisibilityChange);
     }
-    /** Is the action held this frame? */
+    /** Is the action held this frame (some source at 0.5 or above)? */
     held(action) {
-        return this.injectedDown.has(action) || this.isActive(action, this.down);
+        return this.value(action) >= ACTION_HELD_THRESHOLD;
     }
-    /** Was the action pressed exactly this frame? */
+    /**
+     * Was the action pressed exactly this frame? True when no source held it
+     * as the last step closed and some source holds it now — or a key or an
+     * injection held it since, even if already released (a tap between steps).
+     */
     justPressed(action) {
-        return this.injectedJustDown.has(action) || this.isActive(action, this.justDown);
+        if (this.heldAtStepEnd.has(action))
+            return false;
+        return (this.held(action) ||
+            this.injectedJustDown.has(action) ||
+            this.isActive(action, this.justDown));
+    }
+    /**
+     * The action's 0..1 value: the max across its sources — 1 for a key that
+     * is down, a pad button's value, a stick half's dead-zoned component, an
+     * injected hold's value. 0 for an unknown or unbound action.
+     */
+    value(action) {
+        const codes = this.bindings.get(action);
+        if (!codes)
+            return 0;
+        let value = this.injectedPresses.has(action) ? 1 : (this.injectedHolds.get(action) ?? 0);
+        for (const code of codes) {
+            if (this.down.has(code))
+                return 1;
+            value = Math.max(value, this.padValues.get(code) ?? 0);
+        }
+        return value;
     }
     /** Installed semantic action names in deterministic order. */
     availableActions() {
         return [...this.bindings.keys()].sort();
     }
     /**
-     * The key codes bound to the action, in their declared order (e.g.
+     * The source codes bound to the action, in their declared order (e.g.
      * `['KeyE', 'Space']`); `[]` for an unknown or unbound action. A new
      * array every call: mutating it never changes the bindings.
      */
@@ -46,29 +101,65 @@ export class Input {
     heldActions() {
         return this.availableActions().filter((action) => this.held(action));
     }
-    /** Injects an action by semantic name; false means the action is not installed. */
-    injectAction(action, operation) {
+    /** The value of every held action, keyed in the same order as heldActions(). */
+    actionValues() {
+        return Object.fromEntries(this.heldActions().map((action) => [action, this.value(action)]));
+    }
+    /**
+     * Injects an action by semantic name; false means the action is not
+     * installed. `hold` takes an optional value in (0, 1] (default 1) and is
+     * one more source of the action: below 0.5 it moves it without holding it.
+     * A value outside (0, 1], or any value on `press`/`release`, throws a
+     * RangeError before anything changes (checkInjectedValue, the Runtime
+     * Bridge's rule).
+     */
+    injectAction(action, operation, value) {
+        const checked = checkInjectedValue(operation, value);
+        if ('error' in checked)
+            throw new RangeError(checked.error);
         if (!this.bindings.has(action))
             return false;
         if (operation === 'release') {
-            this.injectedDown.delete(action);
+            this.injectedHolds.delete(action);
             this.injectedPresses.delete(action);
             return true;
         }
-        if (this.held(action)) {
-            if (operation === 'hold')
-                this.injectedPresses.delete(action);
-            return true;
+        const wasHeld = this.held(action);
+        if (operation === 'hold') {
+            // A queued press becomes this persistent hold rather than a second edge.
+            this.injectedPresses.delete(action);
+            this.injectedHolds.set(action, checked.value ?? 1);
         }
-        this.injectedDown.add(action);
-        this.injectedJustDown.add(action);
-        if (operation === 'press')
+        else if (!wasHeld) {
             this.injectedPresses.add(action);
+        }
+        if (!wasHeld && this.held(action))
+            this.injectedJustDown.add(action);
         return true;
     }
-    /** -1..1 axis from two actions (left/right by default). */
+    /** -1..1 axis from two actions (left/right by default): value(positive) − value(negative). */
     axis(negative = 'left', positive = 'right') {
-        return (this.held(positive) ? 1 : 0) - (this.held(negative) ? 1 : 0);
+        return this.value(positive) - this.value(negative);
+    }
+    /**
+     * Reads player 1's pad. The Game calls this once per Simulation Step,
+     * before component updates.
+     */
+    pollGamepad() {
+        const { pad, lostActive } = this.padSlot.poll(connectedGamepads());
+        // No pad, none lost and no pad values: nothing can change (the common keyboard-only case).
+        if (!pad && !lostActive && this.padValues.size === 0)
+            return;
+        if (lostActive)
+            this.releasePad();
+        const raw = pad ? gamepadValues(pad, this.deadZone) : new Map();
+        for (const [code, value] of raw) {
+            if (value < ACTION_HELD_THRESHOLD)
+                this.disarmed.delete(code);
+            else if (this.disarmed.has(code))
+                raw.set(code, 0);
+        }
+        this.padValues = raw;
     }
     /**
      * Marks this frame's press of the action as spent, so consumers that
@@ -87,13 +178,12 @@ export class Input {
     endFrame() {
         this.justDown.clear();
         this.injectedJustDown.clear();
-        for (const action of this.injectedPresses)
-            this.injectedDown.delete(action);
         this.injectedPresses.clear();
         this.used.clear();
+        this.heldAtStepEnd = new Set(this.heldActions());
     }
     dispose() {
-        this.injectedDown.clear();
+        this.injectedHolds.clear();
         this.injectedJustDown.clear();
         this.injectedPresses.clear();
         window.removeEventListener('keydown', this.onKeyDown);
@@ -110,9 +200,18 @@ export class Input {
                 return true;
         return false;
     }
+    /** Every pad source reads 0; the ones that were held stay released until they drop below the threshold. */
+    releasePad() {
+        for (const [code, value] of this.padValues) {
+            if (value >= ACTION_HELD_THRESHOLD)
+                this.disarmed.add(code);
+        }
+        this.padValues = new Map();
+    }
     releaseAll = () => {
         this.down.clear();
         this.justDown.clear();
+        this.releasePad();
     };
     onVisibilityChange = () => {
         if (document.visibilityState === 'hidden')
@@ -128,3 +227,10 @@ export class Input {
         this.down.delete(e.code);
     };
 }
+/** An unknown `Gamepad:` code never matches; it is reported once per code per Input. */
+function warnUnknownPadCode(code, warned) {
+    if (!code.startsWith(GAMEPAD_CODE_PREFIX) || warned.has(code) || gamepadControl(code))
+        return;
+    warned.add(code);
+    console.warn(`[waica] unknown gamepad binding "${code}": it never matches.`);
+}

package/dist/runtime-bridge.d.ts

@@ -18,8 +18,11 @@ export type RuntimeMode = 'paused' | 'real-time';
  * operation and before a screenshot. `camera-effects` (issue #74, ADR 0020)
  * announces that every snapshot carries `camera: { shake, fade, flash }`
  * from `game.cameraEffects`; the `scene` operation stays a hard cut.
+ * `analog-actions` (issue #75, ADR 0023) announces that `hold` takes an
+ * optional `value` in (0, 1] and that every control result carries
+ * `actionValues` beside `heldActions`.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects', 'analog-actions'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
@@ -31,8 +34,14 @@ export interface RuntimeMetadata {
     assets: AssetStatus;
 }
 export type RuntimeControlRequest = {
-    operation: 'press' | 'hold' | 'release';
+    operation: 'press' | 'release';
     action: string;
+}
+/** Holds at `value` in (0, 1]; without one, at 1. */
+ | {
+    operation: 'hold';
+    action: string;
+    value?: number;
 } | {
     operation: 'pause' | 'resume';
 }
@@ -50,6 +59,8 @@ export type RuntimeControlRequest = {
 };
 export interface RuntimeControlResult extends RuntimeMetadata {
     heldActions: string[];
+    /** The value of each held action, in the same order as `heldActions`. */
+    actionValues: Record<string, number>;
 }
 export declare class RuntimeBridgeOperationError extends Error {
     readonly code: 'runtime-invalid-state' | 'runtime-operation-failed';
@@ -82,9 +93,10 @@ export interface RuntimeBridgeHost {
     /** Starts clock-driven playback; `onStep` is told after every Simulation Step. */
     resume(onStep: () => void): void;
     pause(): void;
-    injectAction(action: string, operation: 'press' | 'hold' | 'release'): boolean;
+    injectAction(action: string, operation: 'press' | 'hold' | 'release', value?: number): boolean;
     availableActions(): string[];
     heldActions(): string[];
+    actionValues(): Record<string, number>;
     inspect(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
     click(x: number, y: number): void;
     /** Resolves `name` through the registered catalog and loads it. */

package/dist/runtime-bridge.js

@@ -1,5 +1,6 @@
 import enginePackage from '../package.json' with { type: 'json' };
 import { SIMULATION_STEP } from './fixed-step.js';
+import { checkInjectedValue } from './input.js';
 export const RUNTIME_BRIDGE_PROTOCOL_VERSION = 1;
 export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
 /**
@@ -17,6 +18,9 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * operation and before a screenshot. `camera-effects` (issue #74, ADR 0020)
  * announces that every snapshot carries `camera: { shake, fade, flash }`
  * from `game.cameraEffects`; the `scene` operation stays a hard cut.
+ * `analog-actions` (issue #75, ADR 0023) announces that `hold` takes an
+ * optional `value` in (0, 1] and that every control result carries
+ * `actionValues` beside `heldActions`.
  */
 export const RUNTIME_BRIDGE_CAPABILITIES = [
     'click',
@@ -24,6 +28,7 @@ export const RUNTIME_BRIDGE_CAPABILITIES = [
     'fixed-step',
     'assets',
     'camera-effects',
+    'analog-actions',
 ];
 export class RuntimeBridgeOperationError extends Error {
     code;
@@ -116,10 +121,17 @@ export class EngineRuntimeBridge {
                 throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unsupported runtime control operation "${unsupported.operation}".`);
             }
         }
-        return { ...this.metadata(), heldActions: this.host.heldActions() };
+        return {
+            ...this.metadata(),
+            heldActions: this.host.heldActions(),
+            actionValues: this.host.actionValues(),
+        };
     }
     injectAction(request) {
-        if (this.host.injectAction(request.action, request.operation))
+        const checked = checkInjectedValue(request.operation, 'value' in request ? request.value : undefined);
+        if ('error' in checked)
+            throw new RuntimeBridgeOperationError('runtime-operation-failed', checked.error);
+        if (this.host.injectAction(request.action, request.operation, checked.value))
             return;
         const available = this.host.availableActions();
         throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unknown action "${request.action}". Available actions: ${available.join(', ') || '(none)'}.`, available);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",