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

• Batocera Wiki – Visual Pinball
• Virtual Pinball Discord
• VPX Standalone Table Patches (by jsm174)
• Interview with @jsm174 about VPX Standalone and Batocera

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

⚠️ Troubleshooting:
If your tables fail to launch after running the script:

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