dolmen-keys v0.0.5

dolmen-keys

This package contains a number of useful modules for keyboard handling in games and 3D applications using Solid.js.

Typically in a game, keys are used as real-time control signals. A particular movement or action, such as moving forward or turning left, will be performed continuously for as long as a key is held down. Moreover, these actions are often assigned to key combinations, such as "shift+left to strafe left".

These methods require a KeysManagerContext:

<KeysManagerContext.Provider value={new KeysManager()}>
  {...}
</KeysManagerContext.Provider>

The KeysManager.activeKeys property returns an object that has a boolean flag for each keyboard key that is currently held down. This is a reactive store.

createActiveKeys

The createActiveKeys hook allows key combinations to be mapped to a set of boolean signals. It includes logic to normalize the modifier keys - so you can listen for shift, left-shift, right-shift and so on.

const cameraControls = createActiveKeys({
  strafeLeft: 'shift+left',
  strafeRight: 'shift+right',
  rotateLeft: 'left',
  rotateRight: 'right',
  moveForward: 'up',
  moveBack: 'down',
});

The return result is a reactive store which has a property for each of the named signals.

function animate() {
  if (keys.strafeLeft) {
    // update position
  }

  if (keys.rotateLeft) {
    // etc.
  }
}

There is an exclusion algorithm which prevents multiple signals using the same base key from being triggered simultaneously. The 'base key' is the rightmost key in the key combo string, so for example in the combo 'shift-a' the base key is 'a'. If multiple signals are defined using the same base key, only one of those signals can be active at a time.

Under the exclusion rule, key combos defined earlier in the map take precedence over those defined later. So in the above example, both 'strafeLeft' and 'rotateLeft' have the same base key, 'left'. Pressing 'shift+left' will activate the 'strafeLeft' signal only. Pressing 'left' without shift will activate only the 'rotateLeft' signal. This works regardless of the order in which the keys are pressed, so if 'shift' is pressed while already holding down 'left', the activated signal will change from 'rotateLeft' to 'strafeLeft'.

Because of this, you will generally want to put the more complex key combinations first, so that they take precedence over combinations with fewer keys.

createShortcuts

The createShortcuts hook allows you to listen for keypresses instead of held keys.

These functions can be used together in the following way:

createShortcuts({
  'ctrl+z': onUndo,
  'meta+z': onUndo,
  esc: onCancelDrag,
});

// Now use cameraControls.strafeLeft, etc.;