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.

Community based tables for can be downloaded from https://www.vpforums.org or https://vpuniverse.com

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. To play these tables, put the proper ROM in .zip format 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 a nvram .nv file placed in /userdata/roms/vpinball/<table_name>/nvram.

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)

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. The DIP switche values must be changed by editing the .vbs file. 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

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

If your controller supports an accelerometer, it may be being used unintentionally. Edit the /userdata/system/configs/vpinball/VPinballX.ini file to turn off the accelerometer:

[Player]
; Nudge
PBWEnabled = 0

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.