@datamoc/mw_games 0.44.2 → 0.45.0

package/dist/core/Input.d.ts

@@ -1,256 +0,0 @@
-import { Signal } from './Signal.ts';
-/**
- * Keyboard input, bound to named actions.
- *
- * Game code asks about `'confirm'`, never about `'Enter'`. That indirection is what makes
- * rebinding possible at all, and it is far easier to put in from the start than to retrofit
- * once a hundred call sites know about key codes.
- *
- * Keys are identified by `KeyboardEvent.code` (the physical key), so a binding to `KeyZ`
- * lands on the same place under AZERTY as under QWERTY, which is what a player actually
- * wants from a movement key.
- *
- * @example
- * ```ts
- * import { Input } from '@datamoc/mw_games/core';
- *
- * Input.bind('confirm', ['Enter', 'Space']);
- * Input.bind('left', ['ArrowLeft', 'KeyA']);
- *
- * // in the game loop:
- * if (Input.justPressed('confirm')) console.log('confirmed');
- * if (Input.isDown('left')) console.log('moving left');
- * ```
- */
-export type Action = string;
-/** fires when an action starts; a listener returning true stops it reaching anything else */
-export declare const onAction: Signal<string>;
-/** fires for every keydown, for the rare case that needs the raw key */
-export declare const onKey: Signal<KeyboardEvent>;
-/**
- * Fires for the text a key press produces, one call per character - the signal a free text
- * field listens to. `onAction` carries named intent and `onKey` carries the physical key;
- * neither carries `event.key`, so neither can type a name or a save-slot label. A listener
- * returning true stops the text reaching anything else, the same convention the other input
- * signals use, so a focused field can swallow it.
- */
-export declare const onText: Signal<string>;
-/** the three phases of an input-method composition: CJK, dead keys, emoji pickers */
-export type CompositionPhase = 'start' | 'update' | 'end';
-export interface CompositionInput {
-    phase: CompositionPhase;
-    /** the composition string so far; on 'end' this is the text finally committed */
-    text: string;
-}
-/**
- * Fires through an input-method composition, so a text field can show the underlined
- * in-progress characters without committing them: 'update' replaces the preview and 'end'
- * commits `text`. Keys typed while composing are not also reported by `onText`
- * (`KeyboardEvent.isComposing` suppresses them), so a field follows one path or the other,
- * never both.
- */
-export declare const onComposition: Signal<CompositionInput>;
-/**
- * The text a keydown produces, or null when it produces none.
- *
- * A printable key is one whose `event.key` is a single character, held without Ctrl/Cmd/Alt
- * (those are shortcuts) and outside a composition (the IME's own events carry that text).
- * Named keys - 'Enter', 'Backspace', 'ArrowLeft', 'Dead', 'Unidentified' - are longer than
- * one character, which is what keeps them out without a hand-maintained exclusion list.
- */
-export declare function textFromKey(event: Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey' | 'isComposing'>): string | null;
-/** Fires `onText` for a non-empty string; empty is a no-op rather than a signal with nothing. */
-export declare function dispatchText(text: string): void;
-/**
- * Fires `onAction` for one named action - the programmatic counterpart of a physical key
- * press, without holding anything: an on-screen keyboard's Enter key feeds the confirm
- * action down the same signal a real key travels, so a prompt or menu cannot tell the two
- * apart. Deliberately no `held`/`pressedThisFrame` bookkeeping, because nothing is held.
- */
-export declare function dispatchAction(action: Action): void;
-/** Fires `onComposition`, copying the input so a listener cannot mutate the caller's object. */
-export declare function dispatchComposition(input: CompositionInput): void;
-/**
- * What one wheel notch means, decided by whichever modifier key was held - the same
- * physical wheel serves three different intents depending on it. `'zoom'` is for a game's
- * own in-scene zoom (`render.Camera.zoom`, typically), never the browser's own page/pinch
- * zoom, which `dispatchWheel` already calls `preventDefault()` to stop from firing at the
- * same time.
- */
-export type WheelAction = 'scroll' | 'scrollHorizontal' | 'zoom';
-export interface WheelInput {
-    action: WheelAction;
-    /** the raw wheel delta for whichever axis `action` reads; positive is down/right/out */
-    delta: number;
-}
-/** fires once per wheel notch, resolved to a `WheelAction` by the held modifier; a listener returning true stops it reaching anything else */
-export declare const onWheel: Signal<WheelInput>;
-/**
- * The documented default modifier convention: plain wheel scrolls vertically, Shift scrolls
- * horizontally (for a game with wide content - `ListView`'s own plain-wheel handling is a
- * single column and does not need this), Ctrl/Cmd zooms. Exported so a game can override the
- * convention itself rather than only being able to work around a baked-in one - unlike the
- * browser's own inconsistent-across-platforms Ctrl+wheel-means-zoom behaviour, which this
- * does not rely on: the modifier check happens here, not left to the browser to interpret.
- */
-export declare function wheelActionFor(event: Pick<globalThis.WheelEvent, 'ctrlKey' | 'metaKey' | 'shiftKey'>): WheelAction;
-/** the bindings a game starts with; every one can be replaced */
-export declare const DEFAULT_BINDINGS: Readonly<Record<Action, readonly string[]>>;
-export declare function bind(action: Action, keys: readonly string[]): void;
-/**
- * Every action currently bound to `key`, if any - the query a rebind flow needs before
- * committing a captured key, so it can warn (or auto-unbind the loser) instead of two
- * actions silently firing together the moment a key ends up shared between them. `bind`
- * itself does not call this or refuse a collision; nothing about existing behaviour changes
- * for a game that never rebinds.
- */
-export declare function actionsForKey(key: string): Action[];
-export declare function unbind(action: Action): void;
-export declare function keysFor(action: Action): string[];
-/** every binding, in a shape that can be written to a settings file and read back */
-export declare function exportBindings(): Record<Action, string[]>;
-export declare function importBindings(saved: Readonly<Record<Action, readonly string[]>>): void;
-export declare function resetBindings(): void;
-/** true for as long as the key is held */
-export declare function isDown(action: Action): boolean;
-/** true only on the frame the action began, for menus and single steps */
-export declare function justPressed(action: Action): boolean;
-export declare function justReleased(action: Action): boolean;
-/**
- * Clears the one-frame state.
- *
- * Called by `Game` at the end of every frame. It has to run after the scene's update, or
- * a `justPressed` would be missed by whatever polls it later in the same frame.
- */
-export declare function endFrame(): void;
-/** the pseudo key code for button `button` on pad `padIndex` - bind it the same way a `KeyboardEvent.code` is bound */
-export declare function gamepadButtonCode(padIndex: number, button: number): string;
-/** the pseudo key code for axis `axis` pushed past its deadzone in `direction` on pad `padIndex` */
-export declare function gamepadAxisCode(padIndex: number, axis: number, direction: 1 | -1): string;
-export declare function bindButton(action: Action, padIndex: number, buttons: readonly number[]): void;
-export declare function bindAxis(action: Action, padIndex: number, axis: number, direction: 1 | -1): void;
-/**
- * Folds every connected gamepad's buttons and axes into the same held-code state a keydown
- * would produce. There is no native "gamepad button pressed" event to attach a listener to
- * - the Gamepad API only ever hands back a live snapshot - so this has to be polled once a
- * frame instead, which is why `Game` calls it right before updating the scene, before
- * `endFrame` clears the one-frame flags.
- */
-export declare function pollGamepads(pads?: readonly (Gamepad | null)[]): void;
-export interface RumbleOptions {
-    /** milliseconds */
-    duration: number;
-    weakMagnitude?: number;
-    strongMagnitude?: number;
-}
-/**
- * Vibrates one connected gamepad, if it and the browser expose a dual-rumble actuator - a
- * no-op otherwise, rather than throwing, since support is inconsistent across browsers and a
- * game reaching for "juice" should not have to feature-test this itself.
- */
-export declare function rumble(padIndex: number, options: RumbleOptions, pads?: readonly (Gamepad | null)[]): void;
-/** the pseudo key code for an on-screen touch control identified by `id` - bind it the same way a `KeyboardEvent.code` is bound */
-export declare function touchCode(id: string): string;
-/** binds this player's own action to an on-screen touch control, the same way `bindButton` wires up a gamepad button - call once during setup, then toggle it with `pressTouch`/`releaseTouch` */
-export declare function bindTouch(action: Action, id?: string): void;
-/**
- * Presses an on-screen touch control bound with `bindTouch`, e.g. from a `Button`'s
- * `onPress` - shares the same held/`justPressed` state a real key does, so holding a virtual
- * d-pad button repeats a move the same way holding an arrow key does, rather than firing
- * once per tap the way `Button.onClick` alone would.
- */
-export declare function pressTouch(id: string): void;
-export declare function releaseTouch(id: string): void;
-/** where a swipe's own 8 directions and its short in-place tap map to, defaulting to this project's own default movement/wait bindings */
-export interface SwipeActions {
-    up?: Action;
-    down?: Action;
-    left?: Action;
-    right?: Action;
-    upLeft?: Action;
-    upRight?: Action;
-    downLeft?: Action;
-    downRight?: Action;
-    /** dispatched for a touch that moved less than `minDistance`; omit to ignore taps */
-    tap?: Action;
-}
-export interface SwipeOptions {
-    actions?: SwipeActions;
-    /** minimum drag distance, in CSS pixels, before a touch counts as a swipe rather than a tap; default 24 */
-    minDistance?: number;
-}
-/**
- * Turns a one-finger drag on `target` into a single directional action pulse - press
- * immediately followed by release, the same shape a quick key tap produces - resolved to one
- * of 8 directions by angle, or to `actions.tap` for a touch that barely moved. Movement by
- * swipe rather than a held virtual d-pad is the more common mobile roguelike control scheme
- * (a swipe per tile, not a held direction), so this dispatches one pulse per gesture rather
- * than holding an action down for the drag's duration.
- *
- * Returns a function that removes the listeners this attached.
- */
-export declare function attachSwipe(target: EventTarget, options?: SwipeOptions): () => void;
-/** where a pointer is, and where its current drag began */
-export interface PointerPoint {
-    /** CSS pixels from the target's top-left corner */
-    x: number;
-    y: number;
-    /** `x`/`y` through the `toWorld` option, or equal to them without one */
-    worldX: number;
-    worldY: number;
-    /** CSS pixel offset from where the press began; 0 outside a drag */
-    dx: number;
-    dy: number;
-    pointerId: number;
-    /** true while the button or finger is down */
-    pressed: boolean;
-}
-export interface PointerOptions {
-    /** maps target-relative CSS pixels to world units, e.g. `(x, y) => camera.toWorld(x, y)` */
-    toWorld?: (x: number, y: number) => {
-        x: number;
-        y: number;
-    };
-    /** movement, in CSS pixels, before a press counts as a drag rather than a click; default 4 */
-    dragThreshold?: number;
-}
-export interface PointerTracker {
-    readonly down: Signal<PointerPoint>;
-    /** every move, pressed or not (hover), with `dx`/`dy` set while pressed */
-    readonly move: Signal<PointerPoint>;
-    /** fires once a press has moved past the drag threshold, then on every further move */
-    readonly drag: Signal<PointerPoint>;
-    /** the release; `dragged` tells a drop from a click */
-    readonly up: Signal<PointerPoint & {
-        dragged: boolean;
-    }>;
-    /** the last known position, or null before the pointer has been seen */
-    readonly current: PointerPoint | null;
-    detach(): void;
-}
-/**
- * Pointer input as signals - down, move, drag, up - with positions relative to `target` and,
- * through `toWorld`, in world units, so a game does not reach for the renderer's own event
- * system to build a draggable thing. One pointer is tracked at a time (the first to press),
- * which is what a mouse or a single finger is; a second finger is ignored until the first lifts.
- *
- * @example
- * ```ts
- * import { Input } from '@datamoc/mw_games/core';
- *
- * const target = new EventTarget(); // the game's canvas in a browser
- * const pointer = Input.attachPointer(target, { dragThreshold: 6 });
- * pointer.drag.add((p) => console.log('dragging', p.worldX, p.worldY));
- * pointer.up.add((p) => console.log(p.dragged ? 'dropped' : 'clicked'));
- * pointer.detach();
- * ```
- */
-export declare function attachPointer(target: EventTarget & {
-    getBoundingClientRect?: () => {
-        left: number;
-        top: number;
-    };
-}, options?: PointerOptions): PointerTracker;
-export declare function attach(target?: EventTarget): void;
-export declare function detach(target?: EventTarget): void;
-//# sourceMappingURL=Input.d.ts.map

package/dist/core/Input.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Input.d.ts","sourceRoot":"","sources":["../../src/core/Input.ts"],"names":[],"mappings":"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"}