Visual Pinball X

• Emulator: vpinball standalone
• Folder: /userdata/roms/vpinball
• Accepted ROM formats: .vpx

No Visual Pinball X emulator in Batocera needs a BIOS file to run.

The current version of Visual Pinball supports version 10 (.vpx extension) tables.

The Virtual Pinball Spreadsheet is an excellent online resource for tracking down your old favorite tables or helping you find new ones, all created by the community and freely available. Tables and other content can then be found at The Virtual Pinball Forums or Virtual Pinball Universe.

Place your VPX tables in the .vpx format in /userdata/roms/vpinball/<table_name>/ (eg. /userdata/roms/vpinball/Haunted House (Gottlieb 1982)/Haunted House (Gottlieb 1982) VPW 2.1.vpx)

Many historical tables require the original ROM file extracted from the pinball machine mainboard to run. You have two choices in how to organize your ROM files: either all in one directory or per table.

If you choose to put them all in one directory, they need to be placed in /userdata/system/configs/vpinball/pinmame/roms/ in zip format. A few tables that also require an nvram .nv file require them to be placed in /userdata/system/configs/vpinball/pinmame/nvram/. You will also need to set MAIN MENU → GAME SETINGS → PER SYSTEM ADVANCED CONFIGURATION → VISUAL PINBALL X → PER TABLE FOLDER to “Off” for Visual Pinball to find your ROMs when organized this way.

If you choose to have the ROMs organized per table (the default in v39+), then the proper ROM(s) in .zip format are placed in /userdata/roms/vpinball/<table_name>/roms (eg. /userdata/roms/vpinball/Phantom Of The Opera (Data East 1990)/roms/poto_a32.zip). A few tables also require an nvram .nv file placed in /userdata/roms/vpinball/<table_name>/nvram. You should have the PER TABLE FOLDER setting for VISUAL PINBALL X mentioned above to “Auto” or “On” if you organize your ROMs in this fashion.

Visual Pinball uses VBScript (VBS) as the scripting engine for tables. Due to incomplete support in Wine, some tables will fail to run without modification.

These tables may run with a modified VBS file which can be found at https://github.com/jsm174/vpx-standalone-scripts

Put the .vbs file in /userdata/roms/vpinball/<table_name>, next to the VPX table. Only the .vbs file is required (not the .vbs.original, nor the .vbs.patch files). The name must match the exact name of the table (eg. /userdata/roms/vpinball/Guns N Roses (Data East 1994)/Guns N Roses (Data East 1994) VPW v1.1.vbs)

Virtual Pinball is very flexible and provides support for alternative, optional features (alternate sound effects, colorized Dot Matrix Displays, etc) that may be separate from the main table download. These features are contained in files that are separate downloads and best organized in separate folders within that for the table. The recommended folder organization for use within Batocera v39+ is shown below.

Visual Pinball Standalone is a modified version of VPinballX that is designed to run on non-Windows platforms. It is an open source cross-platform pinball table simulator that targets not only Desktop users but Pincab users as well. Standalone is not currently as full-featured as its Windows counterpart (it does not include the table editor nor does it support head tracking, for example) but the features it has are enough to support a dedicated cabinet. Standalone is also in active development and new functionality is being added on a regular basis.

Standardized features available to all cores of this emulator: vpinball.videomode, vpinball.padtokeyboard, vpinball.videomode, vpinball.bezel, vpinball.bezel_stretch, vpinball.hud, vpinball.hud_corner, vpinball.bezel.tattoo, vpinball.bezel.tattoo_corner, vpinball.bezel.tattoo_file, vpinball.bezel.resize_tattoo

Due to the extreme variety of hardware, no generic procedure exists to change the volume or the number of balls. But an excellent topic on this subject is here: https://www.vpforums.org/index.php?showtopic=38669#entry388038

For non DMD tables, the options are configured through Dip switches. Vpinball standalone version doesn't support pressing [F6] to display a window with the options. A way to access dip switches settings (and many more…) is to use the very powerful vpxtool. Most of the time, a description with what each dip switch does is also included directly in the .vbs file, where they can be edited. eg. In the Fathom table, you can have 5 balls per play instead of 3 by changing this part:

' Number of Balls / game
	SetDip &H40000000,1		'Number of balls.  0,0 = 3, 0,1 = 3, 1,0 = 5, 1,1 = 5
	SetDip &H80000000,0

More information on what each Dip switch does is found in the table's user manual.

1. Press Esc then choose Adjust Camera
2. Use:
   1. Flippers (shift keys by default) to increase/decrease value
   2. Magnasaves (ctrl keys by default) to select previous/next item
   3. Credit (5 key by default) to reset to table's defaults
   4. Start (1 key by default) to save your changes in an pov file

In v38, this creates a .pov file next to your table .vpx file, with the same name (in /userdata/roms/vpinball). Note that Environment Emission is not saved in this .pov file and must be set in your table's .ini file

The .pov files are deprecated in v39. The customization process remains exactly the same (press Esc then choose Adjust Camera), but it now creates a .ini file. It's recommended to remove the old .pov files to use the new .ini files, and also to choose the Camera view instead of the Legacy view. ( is this required or optional?)

It'll help keep track of your ball in fast moments or with dark tables.

• v38: in the VPinballX.ini file, put these values

[Player]
; Ball options
BallTrail = 1
BallTrailStrength = 0.8

• v39: you can configure this directly in the Advanced Options of the emulator

This setting won't change the real nudge intensity, just the visual effect. If you want a more subtle visual effect when nudging:

• v38: in the VPinballX.ini file, put these values:

[Player]
; Visual nudge strength
NudgeStrength = 0.01

• v39: you can configure this directly in the Advanced Options of the emulator

1. If a particular table has a low music volume, you should first check if the volume is adjustable by accessing its service menu (or try pressing 8, or 9, or 7). Note that for some tables, it'll be impossible to adjust it.
2. If you want to balance the volumes between mechanical sounds of music sounds, you can do it globally (by editing the VPinballX.ini file), or on a table basis (by editing the table's .ini file, located next to its .vpx). Look for this section:

[Player]
MusicVolume = 100
SoundVolume = 5

• v39+: you can also configure this directly in the Advanced Options of the emulator

(starting in v39 of Batocera)

The sounds included in the rom can be totally replaced. You can find some packages at https://vpuniverse.com/files/category/113-altsound/ or http://altsound.vpin24.com/

1. Download the .zip file
2. Extract it in /userdata/roms/vpinball/<table_folder>/pinmame/altsound/<rom_name> (example: /userdata/roms/vpinball/Guns_n_Roses_1994/altsound/gnr_300 for the Data East Guns N' Roses table)

Data East tables are notorious for having a very bad sound quality. You can find altsound packages which can be simply a better version of the original sounds, or a very different version.

Only the Serum colorization system is supported (https://vpuniverse.com/files/category/173-serum-dmd-colorizations/) at the moment (with Batocera 39+)

1. Download the corresponding .cRZ file for the pinmame ROM and copy it into /userdata/roms/vpinball/<table_folder>/pinmame/altcolor/<rom_name>/<rom.cRZ> (ex: /userdata/roms/vpinball/Tron_Legacy/pinmame/altcolor/trn_174h/trn_174h.cRZ for Tron Legacy).
2. Check on jsm174's GitHub page if a pre-existing updated script for Serum colored DMD .vbs.dmdcolored file exists. If it does, you can download it and copy it into the table directory and rename it with a .vbs extension, letting it sit next to the .vpx file, with the same filename (ex: /userdata/roms/vpinball/Tron_Legacy/Tron Legacy (Stern 2011) VPW Mod v1.1.vbs (from the original .vbs.dmdcolored on jsm174's Github repo).
3. If no .vbs.dmdcolored script is available and the DMD is not colorized, you can try and set it by yourself:
   1. first, extract the .vbs script from the .vpx table file using a tool like the VPX-VBS extractor;
   2. In the .vbs file, replace the UseVPMDMD parameter by UseVPMColoredDMD;
   3. Save the table, and keep the same filename as the .vpx table, just with the extension changed to .vbs. It's not necessary to import the .vbs file back into the .vpx file, if a .vbs file exists in the folder, it takes priority.

Animated backglasses are files with .directb2s extension and should be placed next to your .vpx file. The support was added for v39+. The extension .directb2s must be lower case and the name has to be identical to your table's name (eg: Transporter the Rescue (Midway 1989) VPW v1.05.directb2s for Transporter the Rescue (Midway 1989) VPW v1.05.vpx).

If you want to activate PUP support, edit these settings in VPinballX.ini:

[Standalone]
B2SPlugins = 1
PUPCapture = 1
PUPPlugin = 1

Download the corresponding PUP Pack and copy it into /userdata/roms/vpinball/<table_folder>/pupvideos/<rom_name>/ (eg: /userdata/roms/vpinball/Lord of the Rings (Stern 2003)/pupvideos/lotr).

The expected ratio for the backglass and the FullDMD are 16:9. For the topper, it's not strictly defined, so 4:1 ratio is a good starting point to start experimenting.

You need to be patient: don't expect everything to work as it's a WIP.

If it's not working as expected, you can check if you have the correct (ie: adapted to desktop or 2 screens, or 3 screens…) playlists.pup, screens.pup and triggers.pup files in /userdata/roms/vpinball/<table_folder>/pupvideos/<rom_name>/. Most of the time, you have a PuP-Pack_Options folder with some preconfigured ready-to-use files. Eg: for Batman 66 Stern Tribute (2021), you need to replace the 3 .pup files in /userdata/roms/vpinball/Batman 66 Stern Tribute (2021)/pupvideos/b66_orig/ by the ones from /userdata/roms/vpinball/Batman 66 Stern Tribute (2021)/pupvideos/b66_orig/PuP-Pack_Options/Option 3 - Desktop.

A few ideas if a puppack is not working:

• sometimes you need to activate it in the .vbs script (eg: the goonies table)
• make sure the folder “PupCapture” is spelled this way (this folder is currently case-sensitive, so it won't work if it's “PuPCapture” for example)

Starting with Batocera v40, Batocera supports running on a VPX-based pincab. Here are the configuration steps:

• First, define if you want the primary screen for ES to be the playfield or the backglass (assuming you have at least 2 screens for your pincab).
• Let's assume that you choose the backglass as the primary ES screen. Define its identifier and resolution in EmulationStation (SYSTEM SETTINGS → VIDEO OUTPUT). Don't keep the AUTO value ( why?). If necessary, tweak the resolution in SYSTEM SETTINGS → ADVANCED FRONTEND OPTIONS ( any specific reason outside of the usual reasons for wanting to adjust resolution?))
• Then, in SYSTEM SETTINGS → MULTISCREEN define the output for the secondary screen. In our example here, this would be the playfield for VPX, and the information screen for EmulationStation.
• For the DMD, you have two options:
  • Either use another screen for DMD, defined as the DMD SCREEN in this MULTISCREEN menu;
  • Or a physical LED-based DMD like a Pixelcade or a ZeDMD, configured it in SYSTEM SETTINGS → DMD.
• If you use a 3rd screen as the DMD, go to SYSTEM SETTINGS → DMD and set the server to DMDSIMULATOR. If you have a physical LED-based DMD, set this option to DMDSERVER (FOR REAL DMDs).
• When you launch a VPX table, Batocera will try and detect which screen is the backglass, which screen is the playfield (independently from the selection that has been made for EmulationStation). If it gets inverted, you can swap the screens for the playfield and the backglass with the option INVERSE PLAYFIELD AND B2S in the advanced settings of Virtual Pinball.
• When using Batocera in a pincab, in the same advanced settings for the Virtual Pinball system, set the PLAYFIELD MODE to FULLSCREEN.
• If the playfield is not set up correctly, like it is in single-screen mode and not the right playfield view you expect, it can be fixed from the VPX menu:
  • Plug a keyboard to your Batocera machine and press ESC to enter the VPX menus
  • Go to table options, then Page 2/3 Point of View
  • Use left and right CTRL keys to browse the menu options, and use left and right SHIFT key to change values
  • Set View layout mode to Window.
  • Press the key 1 on your keyboard to save the setting.

As of now, not everything is supported in Batocera v40, but things move fast. In particular what is missing compared to traditional Windows-based pincabs:

• DOFlink to control toys (addressable LEDs, shakers…)
• SFF and multi-output sound systems

Even if SFF is not fully supported yet, you can still use multiple sound cards. For example, on my pincab, I have two sound cards: one for the backglass music and sound effects, and one for the ball and bumper “physical” sounds. I can list all the sound outputs supported by VPinballX by logging into Batocera and running:

# /usr/bin/vpinball/VPinballX_GL -listsn
2025-06-14 15:18:37.153 INFO  [10019] [VPApp::InitInstance@926] Starting VPX - v10.8.0 Final (Rev. 9999 (unknown), linux OpenGL 64bits)
2025-06-14 15:18:37.154 INFO  [10019] [VPApp::InitInstance@929] Settings file was loaded from /userdata/system/.vpinball/VPinballX.ini
2025-06-14 15:18:37.154 INFO  [10019] [VPApp::InitInstance@930] m_logicalNumberOfProcessors=4
2025-06-14 15:18:37.154 INFO  [10019] [VPApp::InitInstance@931] m_szMyPath=/usr/bin/vpinball/
2025-06-14 15:18:37.154 INFO  [10019] [VPApp::InitInstance@932] m_szMyPrefPath=/userdata/system/.vpinball/
2025-06-14 15:18:37.154 INFO  [10019] [VPApp::InitInstance@980] Available sound devices:
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 1: name=Default, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 2: name= USB Audio: USB Audio, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 3: name=HDA Intel PCH: ALC221 Analog, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 4: name=HDA NVidia: LG TV, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 5: name=HDA NVidia: HDMI 1, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 6: name=HDA NVidia: HDMI 2, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 7: name=HDA NVidia: HDMI 3, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 8: name=HDA Intel HDMI: HDMI 0 *, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 9: name=HDA Intel HDMI: HDMI 1, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 10: name=HDA Intel HDMI: HDMI 2, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 11: name=Default Audio Device, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 12: name=Rate Converter Plugin Using Samplerate Library, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 13: name=Rate Converter Plugin Using Speex Resampler, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 14: name=Open Sound System, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 15: name=PipeWire Sound Server, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 16: name=PulseAudio Sound Server, enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 17: name=Plugin using Speex DSP (resample, agc, denoise, echo, dereverb), enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 18: name=Plugin for channel upmix (4,6,8), enabled=1
2025-06-14 15:18:37.171 INFO  [10019] [VPApp::InitInstance@985] id 19: name=Plugin for channel downmix (stereo) with a simple spacialization, enabled=1

In my case, I want to use my default speakers for the backglass music and effects, which is managed by PipeWire Sound Server (id 15 above) and my other USB sound card for the ball and bumper physical effects with id 2 above. I can edit the batocera.conf file and add:

vpinball.vpinball_sounddevice=2
vpinball.vpinball_sounddevicebg=15

For earlier Batocera v39 and lower, this is not supported. A pinball and Batocera fan shared information about how to tweak Batocera v39 for pincabs at this location.

Very useful to access and manipulate the service menu of the pinball, in order to change the volume, or the number of balls in play (and many other parameters)

Here are the default Visual Pinball X's controls shown on a Batocera RetroPad:

Example: you want to replace the AddCreditKey by I keypress:

• open the /userdata/system/configs/vpinball/VPinballX.ini file.
• In the Keyboard input mappings section, replace AddCreditKey = 23
• the keycodes are available here: https://github.com/vpinball/vpinball/tree/standalone/standalone#keyboard

You should have a look at the Pad2Key system as modifications of /userdata/system/configs/vpinball/VPinballX.ini for the joystick are not taken into account.

In v40+, you can control the plunger with the right stick by editing your VPinballX.ini:

[Player]
; Plunger
PlungerAxis = 5

The main log file is located in /userdata/system/configs/vpinball/vpinball.log

• Ensure the correct ROM file (in ZIP format) is present at /userdata/system/configs/vpinball/pinmame/roms.
• Some tables require the correct VBS file.

https://github.com/vpinball/vpinball/tree/standalone/standalone#my-game-is-not-displaying-a-dmd. The https://github.com/jsm174/vpx-standalone-scripts repository also has a bunch of files with a .vbs.dmd extension: they contain some hacks to display the DMD if you're playing on a single screen. Just rename the extension to .vbs and put this file next to your table (with the exact same name).

• some tables are configured after their first launch, try exiting and relaunching it again.
• some Bally and Gottlieb tables (gts3 type: cueball wizard for example) need a pre-initialized nvram to accept coins. You can get some files here https://www.vpforums.org/index.php?app=downloads&showfile=1362 and copy them to /userdata/system/configs/vpinball/pinmame/roms

Batocera may be unintentionally interpreting readings from your controller as that from an accelerometer, whether your controller has one (PS4 Dualshock) or not (XBox 360). Edit the file /userdata/system/configs/vpinball/VPinballX.ini to turn this off:

[Player]
; Nudge
PBWEnabled = 0

Note that you will still be able to nudge the table with the DPad even after this change.

Press F11 to display the FPS.

If your table is not playing smoothly:

1. Use a lower resolution: go to Advanced System Options → Video Mode.
2. Starting with v39, the Advanced Options have performance presets to match your hardware's capabilities.
3. More advanced fix: fine tuning the settings in VPinballX.ini may allow you to play at a higher resolution by sacrifying visual effects. For example, a table will look much nicer at 4K without dynamic ambient occlusion than at 1080p with dynamic ambient occlusion (which can bring your GPU to its knees…). You could start with:

[Player]
; Video options
SyncMode = 2
MaxFramerate = 60
MaxPrerenderedFrames = 0
FXAA = 0
Sharpen = 0
ScaleFXDMD = 0
DisableAO = 1
DynamicAO = 0
SSRefl = 
PFReflection = 4

Note: Some settings in the VPinballX.ini file only apply to specific systems (windows for eg). Eg: UseNVidiaAPI has no effect on standalone version.

For further troubleshooting, refer to the generic support pages.