@waica/engine 0.21.0 → 0.23.0

package/README.md

@@ -150,6 +150,20 @@ The cues that hook a `StateMachine` must come after it and after the `ParticleEm
 
 `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.
 
+## Sprite Batches
+
+`Sprite` and `AnimatedSprite` are drawn through **Sprite Batches** by default (ADR 0024). Every frame, after y-sort, the engine orders everything it draws exactly as three would without batching — layer bands, then y-sort, then spawn order, with particle batches, tilemaps and any other mesh in between — and each run of consecutive sprites that share a batch key becomes one instanced draw call. The key is the art and how it is sampled: the texture (an `AnimatedSprite`'s current sheet), `pixelArt` and `shape`. Each sprite is one instance carrying its own placement, color, frame and flip, so tinting, resizing, re-anchoring or animating a sprite never creates a material, and what is drawn in front of what never changes.
+
+- **On by default.** A scene without a `render` block, or with `render.batch: true`, batches. Nothing to configure: sprites of one texture in a row draw in one call, a sprite of other art (or a particle batch, a tilemap) in between starts a new run.
+- **Culling and Group order kept.** A sprite outside the camera is skipped for the frame, as three culls a sprite's own mesh, and an off-camera renderable never splits a run. A run hangs under a Group with its sprites' Group `renderOrder`, so `entity.node.renderOrder` orders batched sprites exactly as it orders their meshes without batching.
+- **Shared art.** All live sprites of one key share one material and one texture clone, scene-scoped: released with the scene at `unloadScene()` and `game.dispose()`. A sprite whose texture fails moves alone to the untextured entry of its shape and keeps showing its `color`.
+- **Reusable slots and buffers.** A destroyed sprite's slot goes to the next spawn of its key. Each run draws through a pooled instance buffer sized by that run: 16 instances at first, doubling when a longer run needs it, never shrinking during the scene. A key drawn as several runs keeps one buffer per run, so instance memory stays proportional to the sprites drawn. Once the buffers have grown to a scene's longest runs (and as many runs as it ever splits into), spawning, destroying and reordering sprites allocates no GPU objects.
+- **Turning it off.** Scene JSON `"render": { "batch": false }` (the editor's **Sprite batching** toggle in the scene inspector) restores the per-sprite path: one mesh, one material and one draw call per sprite. Use it to rule batching out when a scene looks different than you expect, or while debugging draw order; the cost is one draw call per sprite, which is what dominates frame time with thousands of sprites.
+
+Under batching, the object a sprite adds to its entity is a hidden placement anchor that is never drawn. Hide or show a batched sprite through its entity (`entity.node.visible`, as `Health` blinking does); the anchor's own `visible` is not read for the batched draw, and setting it to true makes three also draw the anchor as a plain quad (without the sprite's tint or frame) — leave it alone, or use `render.batch: false` when code needs one real mesh per sprite.
+
+How much batching saves depends on how interleaved a scene is: one texture over the whole scene draws in one call, while a top-down scene that alternates many textures by y gains little. Runtime Snapshots are unchanged — batches are not entities, and sprites report the same state either way.
+
 ## Component lifecycle
 
 Waica keeps the lifecycle boundaries distinct:

package/dist/collision-category.js

@@ -5,7 +5,10 @@ export function validCollisionLayer(value) {
 }
 /** Package-internal exact directional interest check. */
 export function collisionMaskTargets(mask, targetLayer) {
-    if (!validCollisionLayer(targetLayer) || !Array.isArray(mask))
+    if (!Array.isArray(mask))
         return false;
-    return mask.some((entry) => typeof entry === 'string' && (entry === '*' || entry === targetLayer));
+    // Membership first: with explicit masks it rejects most pairs of a dense
+    // scene before the layer's syntax check runs. A '*' mask still checks it.
+    const named = mask.some((entry) => typeof entry === 'string' && (entry === '*' || entry === targetLayer));
+    return named && validCollisionLayer(targetLayer);
 }

package/dist/collision-dispatch.d.ts

@@ -4,5 +4,11 @@ export interface CollisionDispatchStats {
     readonly candidatePairs: number;
     readonly narrowphaseCalls: number;
 }
-/** Game's package-internal trigger dispatch implementation. */
+/**
+ * Game's package-internal trigger dispatch implementation. Pairs come from a
+ * frozen grid; each pair is then checked live, most selective checks first
+ * (liveness, masks, then the snapshotted Hitbox still mounted). The checks
+ * have no side effects, so their order only changes how fast a pair is
+ * rejected.
+ */
 export declare function dispatchCollisions(game: Game): CollisionDispatchStats;

package/dist/collision-dispatch.js

@@ -3,34 +3,41 @@ import { collisionMaskTargets } from './collision-category.js';
 import { collisionOverlap } from './collision-shape.js';
 import { Hitbox } from './components/hitbox.js';
 import { createHitboxBroadphase } from './spatial-broadphase.js';
-/** Game's package-internal trigger dispatch implementation. */
+/**
+ * Game's package-internal trigger dispatch implementation. Pairs come from a
+ * frozen grid; each pair is then checked live, most selective checks first
+ * (liveness, masks, then the snapshotted Hitbox still mounted). The checks
+ * have no side effects, so their order only changes how fast a pair is
+ * rejected.
+ */
 export function dispatchCollisions(game) {
-    const pairs = createHitboxBroadphase(game).pairs();
+    let candidatePairs = 0;
     let narrowphaseCalls = 0;
-    for (const [first, second] of pairs) {
+    createHitboxBroadphase(game).forEachPair((first, second) => {
+        candidatePairs += 1;
         const a = first.entity;
         const b = second.entity;
         if (!a.alive || !b.alive)
-            continue;
-        if (a.get(Hitbox) !== first.hitbox || b.get(Hitbox) !== second.hitbox)
-            continue;
+            return;
         const notifyA = collisionMaskTargets(first.hitbox.collidesWith, second.hitbox.layer);
         const notifyB = collisionMaskTargets(second.hitbox.collidesWith, first.hitbox.layer);
         if (!notifyA && !notifyB)
-            continue;
+            return;
+        if (a.get(Hitbox) !== first.hitbox || b.get(Hitbox) !== second.hitbox)
+            return;
         narrowphaseCalls += 1;
         if (!collisionOverlap(collisionBody(first.hitbox), collisionBody(second.hitbox)))
-            continue;
+            return;
         if (notifyA) {
             for (const component of [...a.components])
                 component.onCollide?.(b);
         }
         if (!a.alive || !b.alive)
-            continue;
+            return;
         if (notifyB) {
             for (const component of [...b.components])
                 component.onCollide?.(a);
         }
-    }
-    return { candidatePairs: pairs.length, narrowphaseCalls };
+    });
+    return { candidatePairs, narrowphaseCalls };
 }

package/dist/components/animated-sprite.d.ts

@@ -113,6 +113,8 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
      * touches game.assets, so it counts nowhere and warns about nothing.
      */
     private sheetTexture;
+    /** The batch key of a sheet: its art, this sprite's filtering, a rectangle. */
+    private sheetKey;
     private showFrame;
     /** Repositions/rescales the displayed frame inside its anchored full-size box. */
     private syncQuad;

package/dist/components/animated-sprite.js

@@ -4,6 +4,9 @@ import { ClipPlayer } from '../animation/clip-player.js';
 import { locateFrame, sheetCell } from '../animation/sheet.js';
 import { spritePlacement } from '../sprite-placement.js';
 import { reportRejection } from '../report-rejection.js';
+import { spriteBatchesOf, spriteInstanceOf } from '../sprite-batches.js';
+/** Where a frame on a failed sheet draws: the flat (white) untextured quad. */
+const UNTEXTURED = { texture: null, pixelArt: false, shape: 'rectangle' };
 const clampAnchor = (value) => Math.min(1, Math.max(0, value));
 /**
  * Sprite animated from one or more spritesheets. The main sheet is the
@@ -139,6 +142,8 @@ export class AnimatedSprite extends Component {
     texs = [];
     // Clones whose sheet failed to load: applyFrame never installs them (CA-4).
     failedSheets = new Set();
+    // The drawn quad, or under Sprite Batches (ADR 0024) the hidden anchor of
+    // this sprite's instance, whose frame UV is read from the sheet clone.
     mesh;
     frame = 0;
     // Current frame's quad scale relative to the sheet's largest cell: always
@@ -169,8 +174,17 @@ export class AnimatedSprite extends Component {
             tex.repeat.set(1 / Math.max(1, sheet.cols), 1 / Math.max(1, sheet.rows));
             return tex;
         });
-        const material = new THREE.MeshBasicMaterial({ map: this.texs[0], transparent: true });
-        this.mesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), material);
+        const batches = spriteBatchesOf(this.game);
+        if (batches?.enabled) {
+            const instance = batches.attach(this.sheetKey(0));
+            instance.shownSheet = 0;
+            instance.uvSource = this.texs[0] ?? instance.uvSource;
+            this.mesh = instance.anchor;
+        }
+        else {
+            const material = new THREE.MeshBasicMaterial({ map: this.texs[0], transparent: true });
+            this.mesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), material);
+        }
         this.mesh.position.z = this.layer * 0.01;
         this.syncQuad();
         this.entity.node.add(this.mesh);
@@ -193,9 +207,16 @@ export class AnimatedSprite extends Component {
         this.showFrame(this.player.advance(dt));
     }
     onDestroy() {
-        this.mesh?.removeFromParent();
-        this.mesh?.geometry.dispose();
-        this.mesh?.material.dispose();
+        const instance = spriteInstanceOf(this.mesh);
+        if (instance) {
+            instance.release();
+        }
+        else {
+            this.mesh?.removeFromParent();
+            this.mesh?.geometry.dispose();
+            this.mesh?.material.dispose();
+        }
+        this.mesh = undefined;
         // Only this sprite's clones: the cached bases live with the Game.
         for (const tex of this.texs)
             tex.dispose();
@@ -225,6 +246,10 @@ export class AnimatedSprite extends Component {
         }), 'sheet texture settle');
         return texture;
     }
+    /** The batch key of a sheet: its art, this sprite's filtering, a rectangle. */
+    sheetKey(index) {
+        return { texture: this.sheets[index]?.texture ?? '', pixelArt: this.pixelArt, shape: 'rectangle' };
+    }
     showFrame(index) {
         this.frame = index;
         this.applyFrame();
@@ -254,7 +279,17 @@ export class AnimatedSprite extends Component {
         const tex = this.texs[located.sheet];
         if (!sheet || !tex)
             return;
-        if (this.mesh) {
+        const instance = spriteInstanceOf(this.mesh);
+        if (instance) {
+            const failed = this.failedSheets.has(tex);
+            if (instance.shownSheet !== located.sheet || instance.shownSheetFailed !== failed) {
+                instance.moveTo(failed ? UNTEXTURED : this.sheetKey(located.sheet));
+                instance.shownSheet = located.sheet;
+                instance.shownSheetFailed = failed;
+            }
+            instance.uvSource = tex;
+        }
+        else if (this.mesh) {
             const map = this.failedSheets.has(tex) ? null : tex;
             if (this.mesh.material.map !== map) {
                 this.mesh.material.map = map;

package/dist/components/sprite.d.ts

@@ -68,6 +68,12 @@ export declare class Sprite extends Component implements YSortParticipant {
     set shape(value: SpriteShape);
     private mesh?;
     onReady(): void;
+    private buildMesh;
+    /**
+     * One instance in the batch of this sprite's key, tinted like the material
+     * the per-sprite path would build: white over a texture, `color` without.
+     */
+    private joinBatch;
     onDestroy(): void;
     /**
      * CA-4's failure rule: an image that never arrives leaves the flat

package/dist/components/sprite.js

@@ -2,6 +2,7 @@ import * as THREE from 'three';
 import { Component } from '../component.js';
 import { spritePlacement } from '../sprite-placement.js';
 import { reportRejection } from '../report-rejection.js';
+import { spriteBatchesOf, spriteInstanceOf } from '../sprite-batches.js';
 const clampAnchor = (value) => Math.min(1, Math.max(0, value));
 /**
  * Textured or flat-color quad. In the unified pipeline, a 2D sprite is a
@@ -41,7 +42,11 @@ export class Sprite extends Component {
     }
     set color(value) {
         this._color = value;
-        this.mesh?.material.color.setHex(value);
+        const instance = spriteInstanceOf(this.mesh);
+        if (instance)
+            instance.color.setHex(value);
+        else
+            this.mesh?.material.color.setHex(value);
     }
     _offsetX = 0;
     _offsetY = 0;
@@ -102,11 +107,30 @@ export class Sprite extends Component {
         this._shape = value === 'circle' ? 'circle' : 'rectangle';
         if (!this.mesh)
             return;
+        const instance = spriteInstanceOf(this.mesh);
+        if (instance) {
+            instance.moveTo({ ...instance.key, shape: this._shape });
+            return;
+        }
         this.mesh.geometry.dispose();
         this.mesh.geometry = this.createGeometry();
     }
+    // The drawn quad, or under Sprite Batches (ADR 0024) the hidden anchor of
+    // this sprite's instance: the same placement either way.
     mesh;
     onReady() {
+        const batches = spriteBatchesOf(this.game);
+        if (batches?.enabled)
+            this.joinBatch(batches);
+        else
+            this.buildMesh();
+        if (!this.mesh)
+            return;
+        this.mesh.position.z = this.layer * 0.01;
+        this.syncQuad();
+        this.entity.node.add(this.mesh);
+    }
+    buildMesh() {
         const material = new THREE.MeshBasicMaterial({ color: this.color, transparent: true });
         if (this.texture) {
             // Its own clone of the cached base (game.assets, ADR 0019): filters
@@ -125,11 +149,35 @@ export class Sprite extends Component {
             }), 'sprite texture settle');
         }
         this.mesh = new THREE.Mesh(this.createGeometry(), material);
-        this.mesh.position.z = this.layer * 0.01;
-        this.syncQuad();
-        this.entity.node.add(this.mesh);
+    }
+    /**
+     * One instance in the batch of this sprite's key, tinted like the material
+     * the per-sprite path would build: white over a texture, `color` without.
+     */
+    joinBatch(batches) {
+        const key = { texture: this.texture || null, pixelArt: this.pixelArt, shape: this._shape };
+        const instance = batches.attach(key);
+        instance.color.setHex(this.texture ? 0xffffff : this.color);
+        this.mesh = instance.anchor;
+        const settled = batches.settled(key);
+        if (!settled)
+            return;
+        reportRejection(settled.then((outcome) => {
+            // CA-4's failure rule, copy-on-write: only this sprite leaves the
+            // shared entry, for the untextured one of its shape, with its color.
+            if (outcome !== 'failed' || spriteInstanceOf(this.mesh) !== instance)
+                return;
+            instance.moveTo({ ...instance.key, texture: null });
+            instance.color.setHex(this.color);
+        }), 'sprite texture settle');
     }
     onDestroy() {
+        const instance = spriteInstanceOf(this.mesh);
+        if (instance) {
+            instance.release();
+            this.mesh = undefined;
+            return;
+        }
         this.mesh?.removeFromParent();
         this.mesh?.geometry.dispose();
         // Only this sprite's clone: the cached base lives with the Game.

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>;
     /**
@@ -101,6 +103,8 @@ export declare class Game {
     simulate: boolean;
     private readonly renderer;
     private readonly resizeObserver;
+    /** Scene-scoped Sprite Batches (ADR 0024); `render.batch: false` opts a scene out. */
+    private readonly spriteBatches;
     private readonly updateFns;
     private readonly invalidUpdateCompositions;
     /**
@@ -233,8 +237,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

@@ -18,6 +18,7 @@ import { projectIsometric, unprojectIsometric } from './projection.js';
 import { isYSortBatchParticipant, isYSortParticipant, ySortZ, } from './render-sort.js';
 import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { sceneDrainsOf } from './scene-drains.js';
+import { createSpriteBatches } from './sprite-batches.js';
 import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
 import { anchoredPiecesOf, GameUi } from './ui.js';
@@ -72,6 +73,8 @@ export class Game {
     // TODO(H1): migrate to WebGPURenderer (three/webgpu) with automatic WebGL2 fallback.
     renderer;
     resizeObserver;
+    /** Scene-scoped Sprite Batches (ADR 0024); `render.batch: false` opts a scene out. */
+    spriteBatches;
     updateFns = new Set();
     invalidUpdateCompositions = new WeakMap();
     /**
@@ -109,7 +112,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);
@@ -133,6 +136,7 @@ export class Game {
             // catalog is registered at call time, which outlives every scene.
             resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
         });
+        this.spriteBatches = createSpriteBatches(this, this.assets);
         this.cameraEffects = new CameraEffects({
             host: () => canvas.parentElement ?? document.body,
             // One screen pixel in world units: the shake snaps to it (never the base).
@@ -205,6 +209,8 @@ export class Game {
             entity.destroy();
         // Drains transferred by the destruction cascade above are scene-scoped too.
         sceneDrainsOf(this).clear();
+        // After the cascade freed every slot: the batches go with their scene.
+        this.spriteBatches.unload();
         this.registry = null;
         this.renderSort = null;
         this.sceneProjection = null;
@@ -299,6 +305,7 @@ export class Game {
      */
     setSceneRender(json) {
         this.renderSort = json?.sort === 'y' ? 'y' : null;
+        this.spriteBatches.enabled = json?.batch !== false;
         const projection = json?.projection === 'isometric' ? 'isometric' : null;
         if (projection === this.sceneProjection)
             return;
@@ -339,9 +346,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);
@@ -398,6 +406,7 @@ export class Game {
         for (const entity of [...this.entities])
             entity.destroy();
         sceneDrainsOf(this).clear();
+        this.spriteBatches.unload();
         // After the entities: their clones go with the cascade above, the
         // cached bases go here, exactly once (ADR 0019).
         this.assets.dispose();
@@ -489,12 +498,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).
@@ -600,7 +610,7 @@ export class Game {
                 this.renderer.clear(true, false, false);
                 this.renderer.setScissorTest(true);
             }
-            this.renderer.render(this.scene, this.camera);
+            this.spriteBatches.drawFrame(this.scene, this.camera, () => this.renderer.render(this.scene, this.camera));
         }
         finally {
             this.camera.position.x = x;

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';