useGameControls

Binds keyboard controls and generates matching help text.

import { useGameControls } from 'filedom';

const controls = useGameControls({
  shortcuts: [
    { keys: ['r'], label: 'RESTART', onPress: () => restart() },
  ],
  onQuit: () => session.exit(),
});

The hook listens for keydowns itself. Each key goes first to ?, which toggles help, then to the first shortcut whose keys include it, then to q if onQuit is set. Help text and overlay configuration are read once on mount; handlers can change on every render.

The help panel lists the hints lines, then one line per visible shortcut (KEYS - LABEL), then Q - QUIT when onQuit is set, then ? - CLOSE.

Options

PropType

shortcutsShortcut[]

Keyboard bindings; see Shortcut below.

TypeShortcut[]

hints?string[]

Help lines for non-key input such as mouse or drag, shown above the shortcut lines.

Typestring[]

onQuit?(() => void)

Called when Q is pressed and no shortcut claims it. Adds Q - QUIT to help.

Type(() => void)

winEffect?WinEffectMode

'accent' (default) shows four accent icons on a win; 'none' turns them off.

TypeWinEffectMode

messages?Partial<GameResultMessages>

Overrides for the won, lost and draw text. Defaults: YOU WIN, GAME OVER, DRAW.

TypePartial<GameResultMessages>

help?TextStyle

How the ? help panel is drawn. Default { shape: { kind: 'sliced' }, onDemand: false }.

TypeTextStyle

banner?TextStyle

How the result banner is drawn. Default { shape: { kind: 'sliced' }, onDemand: false }.

TypeTextStyle

TextStyle

type TextStyle = {
  shape?: TextShape;   // 'sliced' (default), 'glyphs', or 'grid'
  onDemand?: boolean;  // create the tiles on show so they draw over dragged icons
};

shape sets how large the text reads and how many files it costs, and onDemand sets its z; see Text. In a drag-driven game such as solitaire or chess, set onDemand on the banner so it draws over dragged icons. A grid help panel avoids the problem a different way: the overlay anchors it at the bottom of the desktop, clear of the play area.

help: { shape: { kind: 'grid', charsPerCell: 3, linesPerCell: 2 } },
banner: { onDemand: true },

Shortcut

type Shortcut = {
  keys: string[];
  label: string;
  onPress: (key: string) => void;
  display?: string;
  hidden?: boolean;
};

keys are normalized key names, as described in useKeypress. onPress receives the key that matched. display replaces the keys column in help, which otherwise shows the keys uppercased and joined with /. hidden leaves a binding out of help but keeps it active.

Returns

GameOverlayController: handle (the resolved configuration), showHelp, toggleHelp(), and onKey(key). onKey toggles help on ? and returns whether it handled the key. Pass the controller to GameOverlay.