Batocera - dekay/vpinball-wiki GitHub Wiki

Written for Beta version 42

[!Note] While there is an official Batocera Visual Pinball wiki page, much of VPX Standalone is still in beta. This guide provides practical steps to get VPX working today.

Resources

Installation

Follow the official Batocera wiki for detailed installation steps. Here's a quick summary:

  1. Flash the Batocera image to a USB drive.
  2. Boot your PC from the USB.
  3. Navigate to System Settings > Install Batocera on a New Disk to install it on your internal drive.

Avoid running Batocera permanently from USB β€” it's meant for installation or testing only.

Alternatively, you can flash the image directly onto the internal drive.

Wi-Fi Setup

For wireless networking, follow the Batocera guide: Wi-Fi Configuration

Updating Batocera (Enable Beta Features)

To enable VPX-specific features and updates, it's recommended to use the beta channel:

  1. Go to Updates & Downloads.
  2. Change Update Type to BUTTERFLY.
  3. Select Start Update.
  4. Reboot your system.

From the Batocera Release Wiki:

β€œButterfly” builds are not expected to introduce significant stability issues.

Multi-Monitor & Cabinet Setup

If you're building a pinball cabinet:

  • Go to System Settings > Multi Screen.
  • Disable β€œAuto” and manually assign each screen (playfield, DMD, backglass).
  • Rotate your playfield (usually 270Β° for vertical orientation).
  • Set individual resolutions for each monitor.

Detailed instructions: Multi-Monitor Setup Guide

DMD & Backglass Configuration

For 3-screen setups (playfield, DMD, backglass):

  1. Go to Game Settings > Per System Advanced Configuration.
  2. Adjust settings (like display assignments and DMD scaling).
  3. These are equivalent to editing .ini files in Windows-based VPX setups.

Adding Tables

To copy your VPX tables:

  1. On your host computer, open your file explorer.
  2. In the address bar, enter: 
    smb://<Batocera-IP>
    Example: 
    smb://192.168.1.10
  3. Navigate to: Roms/VPinball/

Recommended Folder Structure

Example using Jurassic Park (Data East 1993):

Roms/VPinball/
└── Jurassic Park/
    β”œβ”€β”€ Jurassic Park (Data East 1993) VPW 1.0.vpx
    β”œβ”€β”€ Jurassic Park (Data East 1993) VPW 1.0.vbs         # (optional)
    β”œβ”€β”€ Jurassic Park (Data East 1993) VPW 1.0.ini         # (optional, table-specific settings)
    β”œβ”€β”€ Jurassic Park (Data East 1993) VPW 1.0.directb2s   # (optional, backglass)
    β”œβ”€β”€ music/                                             # (if the table uses music)
    β”‚   └── *.mp3 / *.ogg / etc.
    β”œβ”€β”€ pupvideos/                                         # (if using PuP-Pack videos)
    β”‚   └── *
    └── pinmame/
        β”œβ”€β”€ roms/
        β”‚   └── jpark_l5.zip                               # ROM file
        β”œβ”€β”€ altcolor/
        β”‚   └── jpark/
        β”‚       └── jpark.cRZ                              # (optional, color DMD)
        β”œβ”€β”€ altsound/
        β”‚   └── jpark/
        β”‚       └── *                                      # (optional, alternate sound packs)
        β”œβ”€β”€ nvram/
        β”œβ”€β”€ ini/
        β”œβ”€β”€ cfg/

ROMs

Some VPX tables require ROMs (used by PinMAME). Instead of using the global folder (as done in Windows), keep everything together:

  • Create a pinmame/roms/ folder inside each table folder.
  • Place .zip ROM files there.

POV (Table Position Adjustments)

If your table layout is misaligned:

  1. Load the table.
  2. Press ESC to open the table menu.
  3. Use arrow keys to access Table Settings.

If keyboard inputs don’t work, confirm you're running the beta version of Batocera.

If prompted to set window size:

  • Go to Game Settings > Per System Advanced Configuration
  • Enable Custom Display Physical Setup
  • Set your monitor dimensions (in cm):
Width = physical width of the TV or monitor (not cabinet)
Height = physical height

Installing VPXBCT (Optional)

VPXBCT is a utility for capturing backglass and playfield images and videos from your Visual Pinball X (VPX) Standalone cabinet running Batocera 42.

For detailed instructions and the project files, visit the GitHub repository:
https://github.com/jsm174/vpxbct

Tables Not Loading or Crashing?

If tables exit to menu or fail to load:

  1. Download the VPX standalone patches: https://github.com/jsm174/vpx-standalone-scripts

  2. Replace the patched files into your existing:

    /Roms/VPinball/<Table Folder>/

These patches resolve compatibility issues in Batocera for certain tables.

How can I get the very latest version of VPinball installed?

You can use a convenient script created by @jsm174 that automatically downloads and installs the latest Visual Pinball build straight from the "master" branch on GitHub. This means you can keep your setup up to date without having to manually compile the program or hunt for official releases. Since many new features are still in beta (as discussed on Discord), using this script gives you early access to the latest improvements and fixes.

1. Get a GitHub account

If you don’t already have one, you’ll need to create a free account at github.com.

2. Create a GitHub Personal Access Token (PAT)

This token allows the script to securely access the Visual Pinball repository on GitHub.

Follow GitHub's official instructions to create a new PAT.

Important: When creating the token, make sure to select the repo scope to allow the script to access the repository.

Copy the generated token β€” you’ll need to paste it into the script in the next steps.

3. Download the update script

Save the batocera-vpx-upgrade.sh script to a convenient location on your Batocera system. We recommend placing it in:

/userdata/system/configs/vpinball/

to keep all your VPX-related files organized.

4. Edit the script to add your PAT

Open the script file to edit it. If you’re comfortable with the terminal, you can use a simple text editor like nano on Linux or Batocera by running:

nano /userdata/system/configs/vpinball/batocera-vpx-upgrade.sh

Find line 3 where it says:

GITHUB_PAT=""

Paste your GitHub PAT between the quotes, so it looks like this example:

GITHUB_PAT="abcdef123456"

5. (Optional) Change the version branch or rendering backend

By default, the script downloads the OpenGL (GL) version of VPX from the master branch.

If you want the BGFX (modern graphics backend) version instead, edit line 56 and replace contains("GL") with contains("BGFX").

You can also specify a different GitHub branch to install by modifying the same line.

For more details about the different VPX flavors and rendering backends, see the About Visual Pinball β€” VPX Flavors page.

6. Make the script executable

Before you can run the script, you need to give it execute permission. Open a terminal on your Batocera system or ssh into Batocera and run:

chmod +x /userdata/system/configs/vpinball/batocera-vpx-upgrade.sh

7. Run the script

Run the script by entering this command in the terminal (assuming you are in the directory where the script is located):

./batocera-vpx-upgrade.sh
After it runs successfully, you will see the new version folder created inside:

```bash
/system/configs/vpinball

[!Note] If your tables fail to launch after running the script:

  • Make sure Batocera is running the latest beta version (v42 or newer).
  • Delete your VPinballX.ini file β€” it will regenerate automatically the next time you launch VPX.

Troubleshooting

I'm trying to make changes in Batocera's Advanced per Emulator Settings for Visual Pinball but the values don't seem to "stick" between reboots.

When Batocera starts up, the very first thing it does is read the Advanced Settings values from batocera.conf and put them into the VPinballX.ini file using their configgen tool. That .ini file is in turn read by Visual Pinball when it starts up. The batocera.conf entries for Visual Pinball will look something like this:

# ------------ User-generated Configurations ----------- #
system.cpu.governor=performance
ScrollLoadMedias=0
global.videooutput2=DP-4
global.videooutput3=DP-3
vpinball.tdp=100.000000
vpinball.vpinball_b2sgrill=0
vpinball.vpinball_screenheight=61.183998
vpinball.vpinball_screenwidth=106.846001
vpinball.vpinball_screeninclination=14.000000
vpinball.vpinball_screenplayery=0.000000
vpinball.vpinball_screenplayerz=70.000000
vpinball.vpinball_vsync=0
backglass.theme=backglass-boxart
global.netplay.nickname=BATOCERA Player
vpinball.vpinball_b2sdmd=0
es.resolution3=1360x768.60.02
vpinball.vpinball_flexdmd=manual
vpinball.vpinball_pinmame=manual
global.exithotkeyonly=0
vpinball.vpinball_customphysicalsetup=1

Note the last line above. If vpinball.vpinball_customphysicalsetup is not present or not set =1, the Advanced Configuration settings will be reset each time. There seems to be a bug somewhere in the configgen script that causes this line to not be included. Manually add this line to the file and see if that solves the problem (Reference: Discord discussion)

I'm having difficulty getting EmulationStation and Batocera to treat my controller inputs the same way. How can I fix this?

You've probably sunk a lot of time messing with SDL Game Controller and gamecontrollerdb. An easier way is to set things up for joystick controls. To do that...

  • Set GamepadOverride = 0 in your VPinballX.ini file
  • Use joystick values for all settings (retrieve by doing sdl2-jstest -t 0 and adding +1 to each value) and set them in your VPinballX.ini file. You might end up with something that looks like this:
JoyLFlipKey = 2        (these values are +1 from whatever button sdl2-jstest reports)
JoyRFlipKey = 7
JoyStagedLFlipKey = 
JoyStagedRFlipKey = 
JoyPlungerKey = 6
JoyAddCreditKey = 0
JoyAddCredit2Key = 9
JoyLMagnaSave = 1
JoyRMagnaSave = 8
JoyStartGameKey = 3
JoyExitGameKey = 4
  • Create a script that, on the launch of every game, wipes out the evmap trickery that Batocera does behind the scenes. The script can be named whatever you like but it must have a filename extension of .sh.
#!/bin/bash

case $1 in
    gameStart)
        echo '{}' | tee /usr/share/evmapy/vpinball.keys > /dev/null
        echo '{}' | tee /userdata/system/configs/evmapy/vpinball.keys > /dev/null
    ;;

esac
  • Save that file to Batocera's /userdata/system/scripts directory, making sure to make it executable by running chmod +x <scriptname.sh> once it has been copied over. (Reference: Discord discussion).

Tips and Tricks

How can I configure my joystick to send keyboard events?

evsieve to the rescue!

This example is courtesy of @jsm174 from this Discord post that maps the hat on an XBox360 joystick to keyboard input. Note that it includes wiping out the evmap trickery that Batocera does behind the scenes as discussed in the Troubleshooting section. Like the example above, the file can be named whatever you like but it will require the .sh extension and must be made executable with chmod +x <scriptname.sh>.

#!/bin/bash

logfile=/tmp/vpinball-evsieve.log
pidfile=/tmp/evsieve-vpinball.pid

case $1 in
    gameStart)
        echo '{}' | tee /usr/share/evmapy/vpinball.keys > /dev/null
        echo '{}' | tee /userdata/system/configs/evmapy/vpinball.keys > /dev/null

        echo "$(date): Game starting - System: $2, Emulator: $3, Core: $4, ROM: $5" >> $logfile
        
        if [ "$2" = "vpinball" ]; then
            echo "$(date): Starting evsieve for VPinball system, ROM: $5" >> $logfile
            
            evsieve --input /dev/input/by-id/*Microsoft_Controller_*-event-joystick* \
                    --map abs:hat0y:-1 key:1:1 \
                    --map abs:hat0y:0 key:1:0 \
                    --map abs:hat0x:1 key:f4:1 \
                    --map abs:hat0x:0 key:f4:0 \
                    --output key create-link=/dev/input/evsieve-keyboard name="Virtual Keyboard" &
            
            echo $! > $pidfile
            echo "$(date): Evsieve started with PID: $!" >> $logfile
        fi
        ;;
        
    gameStop)
        echo "$(date): Game stopping - System: $2" >> $logfile
        
        if [ -f $pidfile ]; then
            PID=$(cat $pidfile)
            echo "$(date): Stopping evsieve (PID: $PID)" >> $logfile
            
            kill $PID 2>/dev/null
            
            rm -f $pidfile
            rm -f /dev/input/evsieve-keyboard
            
            echo "$(date): Evsieve stopped and cleaned up" >> $logfile
        fi
        ;;
esac

This script only runs when a Visual Pinball game starts and ends (thanks to the check if [ "$2" = "vpinball" ]). This way the hat generates keyboard events only in Visual Pinball and not in EmulationStation.