Interface GlobalKeyEntry

Whether this global key fires before the layer broadcast.

• false (default): layer broadcast → global key → screen stack
• true: global key → layer broadcast → screen stack

Whitelist of screen components that may use this global key.

• "*" or omitted: all screens
• []: no screens (effectively disabled)
• [Menu, Game]: only when the stack top is exactly Menu or Game

Whether screen components are allowed to override this global key via boundKeyboard. Defaults to true.

When false, calling boundKeyboard with the same key while the current screen is in the global key's category whitelist will throw a runtime error.

When true, an overlay-phase entry (affectLayer: true) fires even while no layer is open. With the default false, the entry is skipped when no layers exist. Only relevant when affectLayer is true.

Key name(s) to match.

Supports single string or array. Uses the same normalized key-name format as boundKeyboard ("s", "ctrl+q", "return", etc.).

Restrict this global key to a specific mode.

When set, the processor skips this entry unless currentMode matches. Checked before when, affectLayer, category, and cover evaluation. When omitted, the global key fires in all modes (including no-mode).

Callback invoked on every key press while counting toward times. Receives the number of remaining presses before the handler fires. Requires times to be set; throws at registration otherwise.

Callback to invoke when the key is pressed. Can also be a string naming a registered shortcut action (see KeyboardEngine.addAction), whose callback is invoked instead.

Number of times the global key must be pressed before the handler fires. Defaults to undefined (fire immediately on every press).

The counter is per-global-key-entry and never auto-resets. When the counter reaches times, the handler fires and the counter resets to 0.

Must be >= 1.

Examples:

• times: 2 → handler fires on the 2nd, 4th, 6th… press.

Optional condition callback. When provided, the global key only fires if this returns true at the moment of the key press. When false, the entry is skipped entirely — cover, category, and other options are not evaluated.