1681-engine / index / Keymap

Class: Keymap<A>

Defined in: src/input/Keymap.ts:25

Which keys each action sits on, as the player has rebound them: one table the input, the key hints on screen and a settings screen all read. A binding is a KeyboardEvent.code (KeyW, Digit1), so it means the same physical key on every layout. Each action keeps a list (W and ArrowUp, 1 and Q); a settings screen edits the first and leaves the alternates alone. Gamepad inputs (pad:a, pad:lx-) may be the player's too: each device keeps its own first binding, so a settings screen with a keys column and a pad column edits each without touching the other.

Two rules: one key serves one action at a time (a key bound twice would fire both, and the player could not tell which they meant), and reserved keys (Escape, Enter, Tab by default: the interface's own) are never taken.

Inputs the player cannot rebind — the gamepad's, a touch button, a reserved key an action should still answer to (Escape also pausing) — are the keymap's fixed inputs: given once to the constructor, laid after the player's keys by applyTo, and untouched by either rule above.

const keys = new Keymap({ jump: ['Space'], left: ['KeyA', 'ArrowLeft'], pause: ['KeyP'] }, undefined, { jump: ['pad:a'], pause: ['Escape'] });
keys.load(keymapStorage('my-game.keys').read());
keys.onChange(() => { keys.applyTo(actions); storage.write(keys.toJSON()); });
keys.bind('pause', 'KeyA'); // 'left' keeps only ArrowLeft

Type Parameters

Type Parameter
A extends string

Constructors

Constructor

new Keymap<A>(
   defaults, 
   reserved?, 
   fixed?
): Keymap<A>;

Defined in: src/input/Keymap.ts:36

reserved: keys never bound (default Escape, Enter, Tab; pass undefined for the default). fixed: inputs each action always has besides the player's keys (gamepad, touch, a reserved key), never saved or rebound.

Parameters

Parameter	Type
defaults	Readonly<Record<A, readonly string[]>>
reserved	Iterable<string>
fixed	Partial<Record<A, readonly string[]>>

Returns

Keymap<A>

Methods

actionFor()

actionFor(code): A | undefined;

Defined in: src/input/Keymap.ts:77

Which action a key belongs to, or undefined.

Parameters

Parameter	Type
code	string

Returns

A | undefined

---

actions()

actions(): A[];

Defined in: src/input/Keymap.ts:54

Every action, in the order the defaults named them.

Returns

A[]

---

applyTo()

applyTo<B>(actions, extra?): void;

Defined in: src/input/Keymap.ts:140

Hands the bindings to an Actions: each action's keys, then its fixed inputs, then its extra ones. Only the keymap's actions are bound, so the Actions may hold more (menu actions alongside the rebindable ones, each on its own fixed inputs); those are left as they are. Fixed and extra inputs are the game's, so neither the reserved keys nor one-key-one-action apply to them.

Type Parameters

Type Parameter
B extends string

Parameters

Parameter	Type
actions	Actions<A | B>
extra	Partial<Record<A, readonly string[]>>

Returns

void

---

bind()

bind(action, code): A[] | null;

Defined in: src/input/Keymap.ts:88

Puts code first on action in place of the action's first binding of the same device (a key replaces its first key, a pad input its first pad input), taking it off whatever else held it; returns the actions that lost it (to tell the player). A reserved key is refused (returns null). An action stripped of its last key keeps none: it is unbound until something is put back on it.

Parameters

Parameter	Type
action	A
code	string

Returns

A[] | null

---

fixedFor()

fixedFor(action): readonly string[];

Defined in: src/input/Keymap.ts:72

The inputs an action always has besides the player's keys (the constructor's fixed).

Parameters

Parameter	Type
action	A

Returns

readonly string[]

---

isReserved()

isReserved(code): boolean;

Defined in: src/input/Keymap.ts:58

Parameters

Parameter	Type
code	string

Returns

boolean

---

keysFor()

keysFor(action, device?): readonly string[];

Defined in: src/input/Keymap.ts:66

The bindings of one action, or only those of one device; the first of a device is the one a settings screen shows and edits.

Parameters

Parameter	Type
action	A
device?	InputDevice

Returns

readonly string[]

---

load()

load(saved): void;

Defined in: src/input/Keymap.ts:129

A saved set laid over this build's defaults. Only actions this build knows are read, so an old save cannot leave a key bound to nothing; an action newer than the save keeps its defaults only where no saved action holds that key (the saved one is what the player chose). Anything malformed is ignored.

Parameters

Parameter	Type
saved	unknown

Returns

void

---

onChange()

onChange(fn): () => void;

Defined in: src/input/Keymap.ts:145

Called after every change; returns a function that stops it.

Parameters

Parameter	Type
fn	() => void

Returns

() => void

---

reset()

reset(): void;

Defined in: src/input/Keymap.ts:112

Every action back on its defaults.

Returns

void

---

toJSON()

toJSON(): Record<A, string[]>;

Defined in: src/input/Keymap.ts:118

A plain object to store wherever the game keeps its settings.

Returns

Record<A, string[]>

---

unbind()

unbind(action): void;

Defined in: src/input/Keymap.ts:105

Takes every key off action.

Parameters

Parameter	Type
action	A

Returns

void