Games from the home computers of the 80s (Amstrad, Commodore 64, ZX Spectrum…) were played on the keyboard — if only to press SPACE to start the game. Recalbox's Pad To Keyboard (P2K) module translates your controller's actions into keyboard key presses (and mouse movements): those games become fully playable with a controller alone, no keyboard plugged in.
The principle: when launching a game that has a P2K configuration, Recalbox creates a virtual keyboard (and a virtual mouse), seen by the system as real devices. During the game, every controller action is instantly translated into a key press/release — with no measurable input lag, even on Raspberry Pi.
Two examples:
START to SPACE;A to SPACE — the game plays as if it had always been designed for a controller.Recalbox already ships a few P2K configurations with some ports (Theme Hospital, Pico-8…), and the scraper can download more automatically.
A P2K configuration is a plain text file, with the same naming rules as configuration overrides:
.p2k.cfg placed inside the folder — for example /recalbox/share/roms/c64/.p2k.cfg;.p2k.cfg — for example mygame.d64.p2k.cfg next to mygame.d64.If several files exist, they are read from the topmost folder down to the game's folder, then the game's own file: each level can add mappings, replace those of an upper level (same button, new key), or remove them (same button, empty value — 0:select =).
# D-pad to the arrow keys
0:up = up
0:down = down
0:right = right
0:left = left
# Button A for the space bar
0:a = space
# Button B for the Y key (Y/N questions)
0:b = y
# And the START button for ENTER
0:start = enter
Each mapping line has the form PAD:ACTION = KEY:
PAD — the controller number, from 0 to 9 (0 = player 1, by far the most common case);ACTION — the controller button or direction (table below);KEY — the keyboard key pressed when the action is engaged, and released when the action is released.Lines starting with # are comments, empty lines are ignored, and neither case nor spaces around the = matter.
The mapping is 1 to 1: to get
SHIFT + A, mapleftshiftto one button (L1for instance) andato another, then press both buttons together — or use a key combination.
The A/B/X/Y button positions are those of a Nintendo (Super Nintendo) controller.
| Action | Description | Action | Description |
|---|---|---|---|
up |
D-pad, up | j1up |
left stick, up |
down |
D-pad, down | j1down |
left stick, down |
left |
D-pad, left | j1left |
left stick, left |
right |
D-pad, right | j1right |
left stick, right |
a |
A button | j2up |
right stick, up |
b |
B button | j2down |
right stick, down |
x |
X button | j2left |
right stick, left |
y |
Y button | j2right |
right stick, right |
l1 / r1 |
L1 / R1 buttons | l2 / r2 |
L2 / R2 buttons |
l3 / r3 |
stick clicks | start / select |
START / SELECT buttons |
hotkey |
HOTKEY button |
Prefix an action with + so it only triggers in combination with the HOTKEY button:
# HOTKEY + D-pad: F1 to F4 keys
0:+up = f1
0:+down = f2
0:+right = f3
0:+left = f4
All actions accept the + prefix, except select and hotkey itself.
The virtual keyboard is a 105-key QWERTY keyboard, with no particular language or layout: keep in mind that letter positions are those of a QWERTY. The usable key names:
| Family | Keys |
|---|---|
| Letters | a to z (QWERTY layout) |
| Digits (top row) | 0 to 9 |
| Function keys | f1 to f12 |
| Arrows | up, down, left, right |
| Editing | space, enter, backspace, tab, insert, delete, esc |
| Navigation | home, end, pageup, pagedown, break |
| Modifiers | leftshift, rightshift, leftctrl, rightctrl, leftalt, rightalt |
| Numeric keypad | kp0 to kp9, kpdot, kpenter, kpplus, kpminus, kpasterisk, kpslash |
| Symbols | s01 to s11 (see below) |
The symbol keys, whose engraving depends on the keyboard, have neutral names (US QWERTY positions):
| Name | Key | Name | Key | Name | Key |
|---|---|---|---|---|---|
s01 |
` | s05 | ] | s09 | , |
||||
s02 |
- |
s06 |
; |
s10 |
. |
s03 |
= |
s07 |
' |
s11 |
/ |
s04 |
[ |
s08 |
\ |
Add ;; followed by a short text at the end of a line to document it:
0:left = kp4 ;; Move left
0:right = kp6 ;; Move right
0:a = space ;; Fire!
0:b = leftshift ;; Speed up!
In a game list, when the selected game has a P2K configuration, the help bar at the bottom of the screen shows P2K CONTROLS: press X to open the PAD TO KEYBOARD CONTROLS window, which lists each button with its description.
📷 Screenshot to come:
p2k-controls.png(PAD TO KEYBOARD CONTROLS window on a game with descriptions)
P2K can also emulate a 3-button mouse. On top of the keyboard keys, these values can be assigned to any action:
| Value | Effect |
|---|---|
mouse.button.left |
left mouse button |
mouse.button.middle |
middle button (wheel click) |
mouse.button.right |
right mouse button |
mouse.move.up / mouse.move.down |
vertical movement |
mouse.move.left / mouse.move.right |
horizontal movement |
With an analog stick, the cursor speed follows the stick's tilt; with the D-pad or buttons, the cursor accelerates progressively then stabilizes. Handy shortcut: mouse.moves (with an "s") assigns the 4 directions of a stick at once — only on j1 or j2:
# Recalbox's Pad-to-Keyboard configuration
# Mouse-only DOS game
# Movement: right stick
0:j2 = mouse.moves ;; Move the mouse
# Buttons
0:a = mouse.button.left ;; Left click
0:b = mouse.button.right ;; Right click
You can map mouse movement to several elements at once (D-pad + both sticks, for instance) and let everyone pick their favorite control.
Mouse values cannot be mixed with keyboard keys in a combination or sequence: a mouse value is used alone on its line.
An action can trigger up to 32 keys, in two ways.
Combination (keys held together): list the keys separated by spaces. When the button is pressed, they are pressed in order; when released, released in reverse order:
# CTRL+C on the R1 button
0:r1 = leftctrl c ;; Break!
If the emulator needs a delay between keys, prefix the list with + followed by a delay in milliseconds:
# CTRL, then C 100 ms later
0:r1 = +100 leftctrl c ;; Break!
Sequence (keys typed one after another, as on a keyboard): prefix the list with / followed by the delay in milliseconds between each press/release — /0 for no delay. The sequence is sent when the button is pressed (releasing it does nothing):
# Types F, G, H, J in a row, 25 ms between each
0:r1 = /25 f g h j ;; Types FGHJ
# The same with no delay
0:select = /0 r u n enter ;; Types RUN then Enter
The
/prefix must always be followed by a number:/ f g h j(with a bare/) is rejected, write/0 f g h j.
The community shares its P2K configurations on ScreenScraper: the internal scraper can install them automatically next to your roms.
In SCRAPER → OPTIONS, enable INSTALL PAD-2-KEYBOARD CONFIGURATIONS (scraper.screenscraper.p2k key in recalbox.conf, disabled by default). During scraping, if a P2K configuration exists for a game, it is saved as <rom>.p2k.cfg next to the rom — without overwriting an existing file.
And the other way around: if you create good configurations, upload them to ScreenScraper for everyone's benefit, keeping them intuitive (a game should start with START or A), and come discuss them on the Recalbox Discord.
To create your files without memorizing the syntax, an online generator is available: recalbox-p2k-gen.recalbox.com.