Disclaimer : This was built using Debian 12 x86_64 on a Ryzen 5 4600G, RX 550 4gb (and/or Vega 7 APU), 16gb ddr4 with 3 monitors plugged in @1080 using VPX 10.8.0. I had ZERO performance problems running any table and they all loaded crazy fast. Took me a while to figure this all out and there are still lots to add if you dig deeper (real DMD's, toys, dip switches etc). The files for a complete table are all over the internet and I left links to download them on the bottom of this document. If you're planning to play in desktop mode on a single monitor the steps are much easier to get there. You'll figure it out! =) Hopefully this will get VPX up and running natively on Linux! No Wine, no compromises*.

• Visualizing
• Basic Terms
• Installation
• Configuration
• Structure
• Table Aliases
• UltraDMD
• Alternative Sounds
• Alternative Colors
• PupPacks
• Basic Controls
• Basic TUI Frontend
• Table Download Links

This is what we're building here.

This is how it works.

Playfield - The graphical representation of the pinball table. Where the ball rolls.

• Types: Desktop (default), Fullscreen (Multi-window/Cabinet) and FSS (Full Single Screen).

B2S - The backglass. This is the top portion of the pinball, usually above the DMD. It also keeps the score on tables without a DMD. In VPX it uses the Directb2s for animated backglass. You ONLY need a backglass on 2/3 monitors cabinet setup!

DMD - Dot Matrix Display. These can be used with real dot matrix displays or emulated digitally. In VPX it uses FlexDMD (for FlexDMD and UltraDMD) and B2SDMD for b2s-DMD's in digital displays and Pixelcade/ZeDMD for real dot-matrix screens.

Table Types :

• Originals: Tables made from scratch on VStudio and VPX editor without a relation from an existing real table
• Recreations: Tables made to look like exact copies of existing real tables. (These might need a rom)
• VPinMAME Originals: Tables made from scratch using a real table as basis. Requires the rom from the original table.
• VPinMAME Recreations: Tables made to look like exact copies of existing real tables. Requires the table rom.
• MOD tables (original/recreations): Tables with modifications from its original counterparts, but not enought to be considered a new table. Added features, different graphics etc.

Machine Types :

• EM: Electro-Mechanical, the 1st pinball machines with just relays. Scores are on the backglass.
• SS: Solid State, more modern (than EM) machines with dot matrix display.
• LCD: LCD screen based backglass machines.

Back to Top

You can grab a release of the standalone here: https://github.com/vpinball/vpinball/releases . Or you can compile it yourself.

Dependencies:

sudo apt install git build-essential autoconf automake libtool cmake nasm bison curl zlib1g-dev libdrm-dev libgbm-dev libglu1-mesa-dev libegl-dev libudev-dev libx11-dev libxrandr-dev

Clone the repo:

git clone -b standalone https://github.com/vpinball/vpinball

Compile:

cd vpinball/standalone/linux-x64
./external.sh 
cd ../..
cp standalone/cmake/CMakeLists_gl-linux-x64.txt CMakeLists.txt
cmake -DCMAKE_BUILD_TYPE=Release -B build
cmake --build build -- -j$(nproc)

That's it! You are ready to play some pinball!

Help:

cd build/
./VPinballX_GL -h

Basic Usage:

./VPinballX_GL -play default_tables_dir/table_name_folder/table_name_file.vpx

eg:

cd build/
./VPinballX_GL -play tables/Tom_and_Jerry/tomandjerry.vpx

Back to Top

Keep reading this section if you plan to build a cabinet. Or just skip to Structure section.

The setup file to configure VPX by default is:

~/.vpinball/VPinballX.ini

This file will have all values as empty. It will use default values unless changed. This INI file will configure ALL tables, from positioning and resolution to lights and controls. If you need to configure a single table differently, you can copy this file to the table folder (explained in Structure ) and rename it with the same name as the .vpx file. (keeping the .ini extension)

This file is also where you will configure the type of visual you want: Desktop (default), Cabinet and Full Screen.

There are plural DMD emulators and each table might use one. So its wise to set them all with same dimensions/positioning. All data needed (X, Y etc) can be seen on the game log (the open terminal windows) while you drag the DMD and B2S with the mouse. Position it properly, take notes on the values and apply in the INI file. For example:

PinMAMEWindowX = 2816
PinMAMEWindowY = 1336
PinMAMEWindowWidth = 1024
PinMAMEWindowHeight = 256

FlexDMDWindowX = 2816
FlexDMDWindowY = 1336
FlexDMDWindowWidth = 1024
FlexDMDWindowHeight = 256

B2SDMDX = 2816
B2SDMDY = 1336
B2SDMDWidth = 1024
B2SDMDHeight = 256

With this example, the backglass will be in a similar position.

B2SBackglassX = 2816
B2SBackglassY = 568
B2SBackglassWidth = 1024
B2SBackglassHeight = 768

As you can see, there is a DMD within the B2S backglass too, and separated from it aswell. These are used for 2 or 3 monitors setup. You can mix and match those as you wish using singular ini files for each table. There is no way to make this "plug and play" unless both machines have the same exact monitor resolution, positioning etc... pretty much forget about it and set your own.

This section will controll the video options, here is an example of a vertical monitor in cabinet mode.

Display = 1
FullScreen = 1
WindowPosX = 3840
WindowPosY = 0
Width = 1080
Height = 1920

ViewCabScaleX = 1
ViewCabScaleY = 1
ViewCabScaleZ = 1
ViewCabPlayerX = 0.000000
ViewCabPlayerY = -0.000000
ViewCabPlayerZ = -300.000000
ViewCabLookAt = 5.000000
ViewCabRotation = 0
ViewCabFOV = 20.999908
ViewCabLayback = 48.000000

And finally we choose the mode we want. Sync mode should only be changed if the default one is giving you trouble.

; Defines the view mode used when running a table
; 0 - Desktop (default)
; 1 - Fullscreen: Gives you a top-down view on the playfield. For cabinet use or multi-window on desktop.
; 2 - Full Single Screen (FSS): Tries to show the whole machine including backglass if set up by the tabledesigner. Falls back to desktop view.
BGSet = 1

; Sync the frame rate with the refresh rate of your monitor
; 0 - None: No synchronization.
; 1 - Vertical Sync: Synchronize on video sync which avoids video tearing, but has higher input latency.
; 2 - Adaptive Sync: Synchronize on video sync, except for late frames (below target FPS), also has higher input latency.
; 3 - Frame Pacing (default): Targets real time simulation with low input- and video-latency (also dynamically adjusts framerate).
SyncMode = 2

Back to Top

The tables should be in the build/tables/ folder. There are many ways to organize, but here we will use the "portable" way. We will create a single folder for each table and keep all table related files in there.

So the most basic structure should look like this: (a table, a backglass and a rom)

This is how a pinmame structure should look like to be easily portable.

Back to Top

Table aliases are used when multiple tables use the same ROM. Since each table has it's own nvram and configs, this will cause issues when playing multiple tables using the same ROM. ( Do NOT rename ROMs! )

To (not) use alias in Linux we have to edit the .vbs file from the table and remove the alias. Since we have each ROM in a exclusive "portable table" structure, we don't need alias anyway.

Using the Beetle Juice table as an example, to avoid conflict with other tables that based on Iron Maiden Table, like Evil Dead 2 , do the following steps:

1. Extract the .vbs file from the table .vpx file

./VPinballX_GL -ExtractVBS tables/Beetlejuice\ \(Original 2023\)/Beetlejuice\ \(Original 2023\).vpx

2. Open the VBS file with any text editor and look for this line at the start:

Const cGameName = "ironmaid_btj"

3. Comment the ROM alias name and use the real ROM name, in this case:

'Const cGameName = "ironmaid_btj"
Const cGameName = "ironmaid"

4. Save and enjoy the table. The .vbs and .vpx must be named the same and must be on the same folder for VPX to read it.

Back to Top

The Linux version of FlexDMD (drop-in replacement of UltraDMD) is not able to play video files, but it can play animated gifs. So game.UltraDMD tables should be converted by editing the table script and converting the video files as follows:

1. Extracting the table script:

./VPinballX_GL -ExtractVBS path/to/table_name_file.vpx

This will extract a .vbs file alongside the .vpx file. Its a Visual Basic script, you can use any text editor to replace all occurrences of wmv's to gif.

This file should have the exact same name as the .vpx for VPinballX to read it.

Save and exit.

2. Navigate to the game.UltraDMD folder, where the videos are.

Use this command to properly convert all UltraDMD wmv's to animated gif's using ffmpeg:

for i in *.wmv; do ffmpeg -i "$i" -filter_complex "[0:v]split=2[v1][v2];[v1]palettegen=stats_mode=diff:max_colors=256[pal];[v2][pal]paletteuse=dither=bayer:bayer_scale=3[out]" -map "[out]" "${i%.*}.gif"; done

This will convert all video files to animated gifs, and you are free to delete the wmvs if you want.

rm -rfv ./*.wmv

3. Now enjoy UltraDMD tables! Playback should work just fine. (with no audio, of course)

Back to Top

Alternative sounds are a drop-in replacement for original table sounds. Some (old) tables had really bad sound effects and/or music, so the community has made altsound packs to replace them using libaltsound. Not exclusively, these can also be used to enhance or modify sounds on tables you don't like.

The altsound structure is a folder with the ROM name inside table_name/pinmame/altsound/. After 1st boot an altsound.ini file will be created in that folder and can be used to further set things up.

There are 3 types of altsound packs : (from altsound.ini)

• Legacy : The original AltSound format that parses a file/folder structure similar to the PinSound system. It is no longer used for new AltSound packages. These have a common structure of many folders (sfx, music, voice etc) inside the altsound/ROM_name/ folder.

"tomy_400" is the name of the table's ROM (tomy_400.zip).

• AltSound : a CSV-based format designed as a replacement for the PinSound format. This format defines samples according to "channels" with loosely defined behaviors controlled by the associated metadata "gain", "ducking", "stop", and "loop" fields. This is the format currently used by most AltSound authors. These have no folder structure inside table_name/ROM_name/ folder.

• G-Sound : a new CSV-based format that defines samples according to contextual types, allowing for more intuitively designed AltSound packages. General playback behavior is dictated by the assigned type. Behaviors can evolve without the need for adding additional CSV fields, and the combinatorial complexity that comes with it. NOTE: This option requires the new g-sound.csv format

Using The Who's Tommy Pinball Wizard table as example, I had no luck using 'legacy' sound packs. The files were being correctly read and loaded but no sound would come out and BASS was spitting a "no available channel" error (ERROR: BASS initialization error: BASS_ERROR_NOCHAN). So I tried the 'AltSound' method, using a .csv file. You need to change from 'legacy' to AltSound in the altsound.ini file inside the table_name/pinmame/altsound/'rom_name'/ folder!

[format]
format = AltSound

Here is the structure for reference.

Back to Top

Alternative color is a DMD coloring process made by users to enhance table's DMD visual. They are really cool but few.

This is what the basic structure looks like.

Back to Top

Pup Packs are a set of videos composed in several configurable windows. They introduce multimedia into the backglass, dmd, toppers etc.

You will need to chose your screen composition within the pup pack folder. You will encounter a series of .bat files to switch between them. These are windows batch files so open them on a text editor and reproduce what it would do manually. Mostly its about copying over some files and changing a screen.txt file. Don't be scared it's quite simple.

This is the expected structure

A .bat file will generally look like this

As you can see, you just need to copy those files into the root pup folder, and that will overwrite some files, that's normal.

Back to Top

VPX (windows) controls not all work. The "F's" (f1, f2 etc) menus are not implemented in Linux. Everything needs to be changed using the config files mentioned in this document. For reference, here are some working and most used keybindings:

• Left shift - left flipper
• Right shift - right flipper
• Enter - plunger (ball launcher)
• z - left bump
• / - right bump
• Space - bottom bump
• 5 - add coins
• 1 - start
• (8)(9) - volume controls
• ESC - menu

Machine operations are different between vendors, these keys work on Data East machines and some others. If you are having trouble entering the machine settings, specially to change volume levels, Pinball.xlsx is a spreadsheet with pinmame tables and links to tutorials for volume adjustments, ball count etc.

• 7 - enter machine setup (feedback on DMD)
• 7 - scroll through setup pages
• 1 - accept

Back to Top

To create a basic launcher we can use the vpxtool text frontend (GUI in progress). This tool can do many other things, but lets focus on a simple launcher.

1- Download the latest release on -> https://github.com/francisdb/vpxtool

2 - Create a configuration file

vpxtool config setup

3- Edit the default configuration. Make sure to set the path to your Visual Pinball executable and your tables folder.

vpxtool config edit

4- Launch the text based frontend to test the configuration.

vpxtool frontend

The frontend will also show the bios files and will tell if a bios is missing or wrong! =)

Back to Top

Sites that contain all files needed, even the roms and media packs for frontends. You will need to create a (free) account for these:

• https://www.vpforums.org/P
• https://vpuniverse.com/
• https://pinballnirvana.com/
• https://www.pinsound-community.org (altsounds etc)

Other:

• https://vpinhub.com/vpxtables (this is just a hub but helps)
• https://archive.org/download/Visual_Pinball_2020-06-20/ (last resort, old tables)

Scripts:

• https://github.com/jsm174/vpx-standalone-scripts These should help load some troublemaker tables. They are really old tho, but so are some tables. Trial and error here.

Volume Adjustment:

• https://www.vpforums.org/index.php?showtopic=5220
• Pinball.xlsx (Spreadsheet file with VPinMAME tables with links for volume adjustments and more)

Sources:

• Visual Pinball X -> https://github.com/vpinball/vpinball
• VPX GUI Tools and INI Editor -> https://github.com/surtarso/vpx-gui-tools
• As Simple As Possible Cabinet Front-End -> https://github.com/surtarso/ASAPCabinetFE
• vpxtool by Francisdb -> https://github.com/francisdb/vpxtool

Special thanks to Snortt, Francisdb and Toxieainc for helping me setting things up.

Back to Top

*sorta... ;)