Visual Pinball Standalone (VPX) is Recalbox's pinball simulator. It is available on Raspberry Pi 5 / 500 and on PC (x86_64) — other boards do not have the graphics power required.
In 10.1, Recalbox generates VPX's configuration itself on every launch: quality profile, DMD size and position, display mode, pad mapping. You no longer need to touch VPX's .ini files to play — unless you want to take over, and this page tells you where to do it.
Tables go into /recalbox/share/roms/vpinball, in .vpx format. Two layouts are possible.
┣ 📁 recalbox
┃ ┣ 📁 share
┃ ┃ ┣ 📁 roms
┃ ┃ ┃ ┣ 📁 vpinball
┃ ┃ ┃ ┃ ┣ 📁 My Table
┃ ┃ ┃ ┃ ┃ ┣ 🗒 My Table.vpx
┃ ┃ ┃ ┃ ┃ ┣ 🗒 My Table.directb2s
┃ ┃ ┃ ┃ ┃ ┣ 📁 roms
┃ ┃ ┃ ┃ ┃ ┃ ┣ 🗒 pinmame_rom.zip
┃ ┃ ┃ ┃ ┃ ┣ 📁 override
┃ ┃ ┃ ┃ ┃ ┃ ┣ 🗒 desktop.ini
Each table is self-contained with its dependencies: by far the easiest layout to maintain, back up and troubleshoot.
┣ 📁 recalbox
┃ ┣ 📁 share
┃ ┃ ┣ 📁 roms
┃ ┃ ┃ ┣ 📁 vpinball
┃ ┃ ┃ ┃ ┣ 🗒 My Table 1.vpx
┃ ┃ ┃ ┃ ┣ 🗒 My Table 2.vpx
┃ ┃ ┃ ┃ ┣ 📁 roms
┃ ┃ ┃ ┃ ┃ ┣ 🗒 table_1_rom.zip
┃ ┃ ┃ ┃ ┃ ┣ 🗒 table_2_rom.zip
Every table then shares the same roms folder.
Only the .vpx file is mandatory: many tables play with nothing else. Everything else is optional and depends on the table:
| Item | Purpose |
|---|---|
<table>.vpx |
The table itself. Required. |
<table>.vbs |
The table script, when shipped separately. Some tables will not start without it. |
<table>.directb2s |
The backglass (the illuminated head). Required to display it on a second screen. |
roms folder |
The PinMAME roms (.zip), containing the real pinball machine's original program. Recalbox points PinMAME at the table's folder, so the roms subfolder must sit next to the .vpx. |
altsound folder |
Alternative soundtracks. |
altcolor folder |
DMD (score display) colourisation. |
pupvideos folder |
PinUP Player video content shown on the backglass. |
override folder |
Your configuration overrides, see below. |
Not every table needs a PinMAME rom: "original" tables (modern creations) do not use one. The exact rom name expected is stated by the table's author.
Recalbox picks the mode automatically, based on screen orientation and your settings:
| Mode | When? | What you see |
|---|---|---|
| Desktop | landscape screen (the default) | the table in its backdrop, with the backglass and DMD drawn by the table itself |
| FSS (Full Single Screen) | portrait screen — TATE rotation, left or right |
the table stood up, filling the screen, with the DMD embedded bottom-left |
| Cabinet | PC only, portrait screen + pinball.cabinet=1 + a second screen configured |
the table on the main screen, backglass and DMD on the second screen |
Screen rotation is set in Recalbox's display options (TATE mode). On a laptop in cabinet mode, the table shows on the external screen stood up, and the scores on the internal one.
On Raspberry Pi 5, cabinet mode is not available: the board only drives a single output for VPX. FSS gives the best result there on an upright screen.
recalbox.confAll Visual Pinball settings live in recalbox.conf: in 10.1 there is no dedicated menu in EmulationStation.
| Option | Values | Default | Effect |
|---|---|---|---|
pinball.profile |
1 performance, 2 table values, 3 quality, 4 Raspberry Pi |
4 on Pi 5, 1 elsewhere |
Rendering profile: anti-aliasing, reflections, ambient occlusion, anisotropic filtering… |
pinball.ball_trail |
0 / 1 |
0 |
Trail behind the ball. |
pinball.score_size |
multiplier (1, 1.5, 2, 4…) |
2 |
DMD size. The DMD is 128×32 dots: 2 gives a 256-dot-wide panel, 8 a 1024-dot one (80 % of a 1280-wide screen). |
pinball.cabinet |
0 / 1 |
0 |
Enables cabinet mode (PC with two screens only). |
pinball.screen1 |
output name (HDMI-1, DP-1…) |
— | Table screen. |
pinball.screen2 |
output name | — | Backglass screen. Mandatory in cabinet mode. |
pinball.screen1.resolution |
1920x1080 |
1920x1080 |
Table screen resolution. |
pinball.screen2.resolution |
1920x1080 |
1920x1080 |
Backglass screen resolution. |
pinball.custominput |
0 / 1 / 2 |
0 |
0: Recalbox configures the pad; 1: you configure it yourself in VPX's LiveUI; 2: pad disabled inside VPX, to route it through a pad-to-keyboard. |
pinball.autoconf |
0 / 1 |
0 |
Automatic generation of a settings file for the launched table. |
Two more settings are inherited from Recalbox's general options: the FPS counter and pad rumble.
Recalbox builds the mapping itself from your pad, using its real button indices — there is no need to redo it inside VPX.
| Control | Action |
|---|---|
L1 / R1 |
Left / right flipper |
R2 |
Plunger |
B |
Action button (lockbar) |
Y / A |
Left / right magnasave |
UP |
Centre nudge |
LEFT / RIGHT |
Left / right nudge |
SELECT |
Insert a credit |
START |
Start the game |
X |
Pause |
L2 |
Open the coin door (service mode) |
L3 |
Pinball service menu |
HOTKEY + B |
Open the LiveUI (table options) |
HOTKEY + START |
Quit the table |
Inside the LiveUI, navigation works with the D-pad, or with the magnasave buttons (Y / A) to move up and down and the flippers (L1 / R1) to validate and adjust — VPX's stock scheme.
The LiveUI (HOTKEY + B) lets you tune a table mid-game. To freeze settings, create an override folder next to the table containing an .ini file named after the display mode:
┣ 📁 My Table
┃ ┣ 🗒 My Table.vpx
┃ ┣ 📁 override
┃ ┃ ┣ 🗒 desktop.ini
┃ ┃ ┣ 🗒 FSS.ini
┃ ┃ ┣ 🗒 cabinet.ini
┃ ┃ ┣ 🗒 default.ini
On launch, Recalbox copies the file matching the current mode (desktop.ini, FSS.ini or cabinet.ini) next to the table, under the name <table>.ini — VPX's per-table settings file. If the mode file does not exist, default.ini is used; if neither exists, any leftover <table>.ini is removed.
That file follows the structure of VPinballX.ini: bracketed sections ([Player], [ScoreView], [Backglass], [Plugin.PinMAME]…) followed by Key = Value lines. The most reliable way to find the right keys is to tune the table in the LiveUI and copy the resulting values.
Recalbox writes its configuration to:
/recalbox/share/system/configs/vpinball/VPinballX-configgen.ini
That file is regenerated on every launch, so editing it is pointless. To drive VPX entirely yourself, create this file instead:
/recalbox/share/system/configs/vpinball/VPinballX-custom.ini
As soon as it exists, Recalbox uses it as-is and stops configuring anything: quality profile, DMD, display mode and pad mapping are then entirely up to you. Delete it to return to the automatic behaviour.
For advanced users only: most table problems are solved far faster with
pinball.profileand the LiveUI than with a hand-written configuration file.