Keyboard Warriors — Developer Reference
Complete specification for the mac_sc and pc_sc fields
in shortcut JSON files. Covers every detectable key, accepted synonyms,
chip display behaviour, and OS differences.
Tokens are combined with + to form a shortcut string. Order does not matter, the parser normalises modifiers before matching. Tokens are not case-sensitive, but uppercase is prefered to distinguish shortcut data from the surrounding code.
The system accepts any piped alternative as a correct answer. The chip always shows only the first alternative, so be sure to prioritise the preferred shortcut first. Give priority to memorability and universality.
Use the literal value NULL (not an empty string) when a shortcut does not exist on a given platform. This prevents the question appearing on that OS.
The system accepts CMD and OPT in PC fields and vice versa, normalising them internally. Using the native token for each platform makes JSON files far easier to read and audit. Mistakes between OS shortcuts are less likely and more apparent.
Modifiers appear on the graphical keyboard and light up when held. Left and right physical variants are interchangeable. Holding either satisfies the requirement.
Chip columns show the short form (used in multi-key shortcuts) then the long form (used when the shortcut has only one or two tokens).
| Token | Synonyms | Mac chips | PC chips | Notes |
|---|---|---|---|---|
| CMD | COMMAND |
⌘
⌘ command
|
— use CTRL in PC fields | Maps to the ⌘ Command key on Mac. Accepted in PC fields as a synonym for CTRL. |
| CTRL | CMD | — use CMD in Mac fields |
Ctrl
Ctrl
|
PC primary command modifier. Accepted in Mac fields as a synonym for CMD. |
| SHIFT | — |
⇧
⇧ Shift
|
⇧
⇧ Shift
|
|
| OPT | OPTION |
⌥
⌥ option
|
— use ALT in PC fields | Mac Option key. Accepted in PC fields as a synonym for ALT. |
| ALT | OPTION OPT | — use OPT in Mac fields |
Alt
Alt
|
PC Alt key. Accepted in Mac fields as a synonym for OPT. |
| CONTROL | — |
⌃
⌃ control
|
— | The physical ⌃ Control key on Mac — a separate modifier used in a small number of Mac shortcuts (e.g. CONTROL+CMD+V for Paste Special). Not to be confused with CTRL, which is the PC primary command modifier. Mac only |
| WIN | WINDOWS | — |
Win
Win
|
Windows key. Not present on Mac. PC only |
| FN | FUNCTION |
fn
fn
|
FN
FN
|
Actual keypresses cannot be detected by the browser, but the token can be defined for use with the graphical keyboard UI. |
These appear on the graphical keyboard and light up when pressed.
Chip columns show the short form then the long form, as above.
| Token | Synonyms | Mac chips | PC chips |
|---|---|---|---|
| RETURN | ENTER |
↩
↩ return
|
↵
↵ enter
|
| BACKSPACE | DEL BACKDELETE |
⌫
⌫ delete
|
⌫
⌫ Backspace
|
| DELETE | — |
⌦
⌦ delete
|
⌦
⌦ Delete
|
| TAB | — |
⇥
⇥ tab
|
Tab
Tab
|
| SPACE | SPACEBAR | Space | Space |
| ESCAPE | ESC | Esc | Esc |
| CAPSLOCK | — |
⇪
⇪ caps lock
|
Caps
Caps Lock
|
| ARROWUP | UP |
↑
↑ up
|
↑
↑
|
| ARROWDOWN | DOWN |
↓
↓ down
|
↓
↓
|
| ARROWLEFT | LEFT |
←
← left
|
←
←
|
| ARROWRIGHT | RIGHT |
→
→ right
|
→
→
|
Write the letter directly. Same on both platforms.
Write the digit directly. Same on both platforms.
Write the label directly. These appear on the graphical keyboard and light up when pressed. Same on both platforms.
Not on the graphical keyboard. When pressed, these appear as a floating chip pill above the stats row. On Mac extended keyboards, the keys physically labelled PrintScreen / ScrollLock / Pause report to the browser as F13 / F14 / F15.
Each physical key has an unshifted character and a shifted character. Use whichever token matches what the shortcut documentation refers to. The chip displays accordingly. Both tokens match the same physical key regardless of whether Shift is actually held.
| Physical key | Unshifted token → chip | Shifted token → chip |
|---|---|---|
= key |
EQUAL = | PLUS + |
- key |
MINUS - | UNDERSCORE _ |
[ key |
BRACKETLEFT [ | OPENBRACE { |
] key |
BRACKETRIGHT ] | CLOSEBRACE } |
\ key |
BACKSLASH \ | PIPE | |
; key |
SEMICOLON ; | COLON : |
' key |
QUOTE ' | DOUBLEQUOTE " |
, key |
COMMA , | LESSTHAN < |
. key |
PERIOD . | MORETHAN > |
/ key |
SLASH / | QUESTION ? |
` key |
GRAVE ` | TILDE ~ |
1 key |
1 1 | EXCLAMATION ! |
2 key |
2 2 | AT @ |
3 key |
3 3 | HASH # |
4 key |
4 4 | DOLLAR $ |
5 key |
5 5 | PERCENT % |
6 key |
6 6 | CARET ^ |
7 key |
7 7 | AMPERSAND & |
8 key |
8 8 | ASTERISK * |
9 key |
9 9 | OPENPAREN ( |
0 key |
0 0 | CLOSEPAREN ) |
Additional synonyms accepted by the parser: EQUALS = EQUAL, OPENBRACKET = BRACKETLEFT, CLOSEBRACKET = BRACKETRIGHT, BACKTICK = GRAVE. These produce identical behaviour to the primary token. Note: TILDE is not a synonym for GRAVE — it matches the same physical key but renders ~ on the chip, following the same pattern as all shifted-character tokens above.
These keys are not on the graphical keyboard. When pressed, they appear as a floating chip pill above the stats row rather than lighting a key. They can be used in shortcut definitions and are correctly matched and displayed.
| Token | Mac chip | PC chip | Notes |
|---|---|---|---|
| HOME | ↖ home | Home | On Mac: also triggered by Fn+Left |
| END | ↘ end | End | On Mac: also triggered by Fn+Right |
| PAGEUP | ⇞ page up | Page Up | On Mac: also triggered by Fn+Up |
| PAGEDOWN | ⇟ page down | Page Down | On Mac: also triggered by Fn+Down |
| INSERT | — | Insert | Not present on Mac keyboards PC |
| DELETE | ⌦ delete | ⌦ Delete | Forward delete. Distinct from BACKSPACE. |
| Token | Synonyms | Chip | Platform | Notes |
|---|---|---|---|---|
| PRINTSCREEN | — | PrintScreen | PC | Mac extended keyboards report F13 instead |
| SCROLLLOCK | — | ScrollLock | PC | Mac extended keyboards report F14 instead |
| PAUSE | — | Pause | PC | Mac extended keyboards report F15 instead |
| NUMLOCK | — | Number Lock | PC | PC NumLock key |
| CLEAR | — | clear | Mac | Mac numpad Clear key. Distinct from NUMLOCK. |
| CONTEXTMENU | APPS | ContextMenu | PC | The menu key right of spacebar on many PC keyboards |
| HELP | — | Help | Mac | Mac extended keyboard Help key |
All numpad keys appear as extended chip pills. The system automatically lights the equivalent main keyboard key on the graphical keyboard where one exists.
| Token | Chip | Graphical keyboard key lit |
|---|---|---|
| NUMPAD0 – NUMPAD9 | 0 – 9 | Digit 0–9 |
| NUMPADADD | + | = key |
| NUMPADSUBTRACT | - | - key |
| NUMPADMULTIPLY | * | 8 key |
| NUMPADDIVIDE | / | / key |
| NUMPADDECIMAL | . | . key |
| NUMPADENTER | ↵ | Return / Enter key |
| NUMPADEQUAL | = | = key |
| NUMPADCOMMA | , | , key |