Software Setup & Configuration¶

This guide covers software installation, configuration, and compatibility for VPX table development and playback, including VPinMAME, FlexDMD, PUP packs, and VPX versions.

VPX Version Management¶

64-bit Migration¶

No need to uninstall 32-bit VPX. Rename vpinballx.exe files to keep multiple versions:

vpinball10.8.0_863_64bit.exe
vpinball10.7.3_32bit.exe

Requirements: - 64-bit VPX executable - 64-bit VPinMAME (run Setup64.exe) - B2S Server v2.0+ (works with both 32 and 64-bit)

A detailed guide was pinned in the #64bit-pincab channel. (apophis79, sheltemke, BBB)

64-bit Requirements for Specific Tables¶

Big Bang Bar: Almost certainly requires VPX 64-bit. Users must update VPinMAME to latest 64-bit beta. Common crash on startup = outdated VPinMAME. (apophis79, BBB)
Game of Thrones: For complex tables with toolkit, use 64-bit VPX exclusively for editing. 32-bit VPX can only run the table once before crashing, requiring restart for each edit. (skillman604, sixtoe)

Version Compatibility Notes¶

VPX 10.7 vs 10.8: - Moving table files between versions should not break anything - Texture files can disappear when loading in different versions - VR features optimized for 10.8 #814 - Desktop mode development works in 10.7.3; VR fine-tuning requires 10.8 - Bug warning: VPX 10.8 beta caused blurry assets/textures; RC2 (10.7.x) fixed the issue. Check GitHub Actions for latest builds. (iaakki, astronasty, niwak)

VPX 10.8 PoV Changes: - Table rotation should be set to 0 for newer VPX builds (both portrait and landscape) - Users on Beta 5 or earlier may see the table sideways - Cabinet users need to adjust PoV after upgrading (wylte, apophis79, GNR)

Frame Pacing and Performance¶

Frame pacing synchronizes physics/controller with ~1ms latency, matching real pinball controller processing time. May make fast flips unnecessary as it provides equivalent or better latency than real hardware.

Without frame pacing: latency tied to FPS (60fps = 16ms, sometimes 2 frames = 32ms)
Frame pacing prevents GPU from stalling CPU -- they run fully in parallel
Best frame rate is display refresh rate
Use hardware sync (driver sync) rather than user sync settings

(niwak, GNR)

VPX Standalone Compatibility¶

Key changes for VPX standalone (iOS/Android): - Replace Array(x, x, x) patterns with proper Class objects - Add If Controller Is Nothing Then B2SOn = False check for B2S - Add If Not IsNull(m_lightSequencerCollection) null checks - Property setters cannot use same variable name as property name - Set keyword not needed for Dictionary object assignments - Light controller needs IsNull check on m_vpxLightSyncCollection before For Each loop

Debug commands for Android:

adb shell run-as org.vpinballx.spongebob cat /data/data/org.vpinballx.spongebob/files/vpinball.log
adb -d logcat org.vpinballx.spongebob  # Watch logs during runtime

(jsm174, flux5009, SpongeBob)

VPinMAME Setup¶

VPinMAME Version Compatibility¶

Cabinet users: Always use hardware-level solenoid release timers (Pinscape/PinOne/solenoid saver) regardless of VPM version. The stuck solenoid issue can cause physical damage.

VPM 3.6 (official release, Jan 2025): Safe for Space Station, PWM works, no solenoid locking
VPM 3.7 pre-release builds: Mixed compatibility -- some fix S11 PWM but break SAM audio
VPM 3.7-46: Confirmed working for both Space Station PWM/DOF and SAM audio

(bhitney, apophis79, sixtoe, robbykingpin, Space Station)

PinMAME 3.6 Physics Output¶

PinMAME 3.6 added physics output for System 11 tables. Adaptation cleaned up GameOn/GI/BackBox solenoids. System 11 tables perform fast blinks on lamps and modulate flashers -- behavior verified against real machine video references. (niwak, Bad Cats)

Custom ROM Integration¶

To integrate custom ROM .bin files into VPinMAME: 1. Rename the .bin files to match the numbering pattern of the original ROM zip 2. Replace files in the ROM zip (e.g., replace files "26" and "27" in bcats_l5.zip) 3. Checksum mismatch warning can be ignored

Example: The Cat's Meow ROM for Bad Cats adds ball save, game pause, quit game, doghouse lamp support, and 5 selectable rule sets. Final version 1.3 requires VPM 3.7 v28+. (benji084, primetime5k, carny_priest, Bad Cats)

AltSound/GSound Installation¶

Copy folder to VPinMAME/altsound/<ROM_name>, set sound mode to 1 in F1 menu. Requires latest VPinMAME with GSound support.

Sound modes: - 0: ROM only - 1: AltSound/GSound - 2: PinSound (requires PinSound software) - 3: PinSound + Recordings

Important: Mode 2/3 will hang on 64-bit without PinSound software running.

Troubleshooting: If altsound doesn't work after updating, delete the ROM's registry entry. (mrgrynch, sixtoe, idigstuff, GNR)

VPinSPA (Stern Pinball Arcade)¶

Installation Requirements¶

Ghostbusters requires VPinSPA (not standard VPinMAME): 1. Run the installer (one-time setup) 2. ROM files extract to C:\Visual Pinball\VPinMAME\spagb100 3. Contains SternGB.dll and image.bin (not standard .zip ROM format) 4. Can test ROM launch via VPinSPA test tool before launching table 5. Requires Visual Studio 2012 C++ redistributable (x86) 6. DirectDraw registry setting may need to be set to 1

ROM version from Stern Pinball Arcade is 1.15 (not the updated 1.17+ code from real machines). (iaakki, Ghostbusters)

VPinSPA DMD Extension¶

For altcolor DMD to work with VPinSPA: 1. Use Freezy DMDExt 1.71 specifically (not latest) -- later updates: Freezy 1.10.2 works correctly 2. Place dmddevice.dll and dmddevice.ini in VPinSPA folder (not main VPinMAME folder) 3. Altcolor files go in VPinSPA/altcolor/ subfolder 4. Name files: pin2dmd.pal and pin2dmd.vni 5. Remove .vni file if colors incorrect (use .pal only)

(netzzwerg, multiple, Ghostbusters)

64-bit VPinSPA Registry Hack¶

Registry hack to run VPinSPA (32-bit DLL) in 64-bit VPX. Run as Administrator:

reg.exe ADD "HKEY_CLASSES_ROOT\WOW6432Node\CLSID\{F389C8B7-144F-4C63-A2E3-246D168F9D3A}" /f /v AppID /t REG_SZ /d "{F389C8B7-144F-4C63-A2E3-246D168F9D3A}"

reg.exe ADD "HKEY_CLASSES_ROOT\WOW6432Node\AppID\{F389C8B7-144F-4C63-A2E3-246D168F9D3A}"

reg.exe ADD "HKEY_CLASSES_ROOT\WOW6432Node\AppID\{F389C8B7-144F-4C63-A2E3-246D168F9D3A}" /f /v DllSurrogate /t REG_SZ

WARNING: Creates DLL surrogate to bypass WOW64 protections. Potentially unsafe - could cause system instability or prevent software installation. Works for some users, fails to exit cleanly for others. (mike da spike, Ghostbusters)

VPinSPA vs Real Spike ROM¶

VPinSPA ROM extracted from Stern Pinball Arcade (x86 Windows): - Not actual Spike hardware ROM (ARM Linux) - Compiled for different target architecture - SternGB.dll proprietary to Farsight (not Stern code) - Real Spike ROM cannot be swapped into VPinSPA - ROM version stuck at 1.15 (SPA never updated to 1.17+) - Binary comparison: zero matches with real Spike ROM

True Spike emulation would require ARM emulator + understanding of distributed node architecture. (iaakki, Ghostbusters)

FlexDMD¶

FlexDMD Setup for Non-ROM Tables¶

Stern SPIKE system is not emulated in VPinMAME, so FlexDMD is used for DMD display. Requirements:

FlexDMD installed (v1.8+ for Game of Thrones, v1.9.0.0 release for SpongeBob)
A separate <tablename>.FlexDMD folder with image assets in the Tables directory
The VPX file and FlexDMD folder are separate downloads

Common error: "Object required" at FlexDMD init line means the folder is missing. (skillman604, wylte, Game of Thrones)

Bitmap Font System¶

FlexDMD uses .fnt/.png bitmap font pairs. Font files created with BMFont tool from TTF.

Creation workflow: 1. Download desired font (e.g., from dafont.com) 2. Use online bitmap font generator: https://snowb.org 3. Set pixel height of font, change color to white 4. Generator produces .fnt file and .png spritesheet 5. Font references each character via coordinates in the .txt/.fnt file

DMD resolution: 128x32. Max font height ~16px for 2 lines of text, or 32px for single line. (oqqsan, gedankekojote97, SpongeBob)

Image Loading¶

Memory limits: Loading FlexDMD images directly into VPX table file (FlexDMD.NewImage("Background2", "VPX.bg2&bitmap")) works on small tables but crashes large tables.

Cause: VPX is 32-bit, has RAM address limit. 4K PNG textures get uncompressed to much larger VRAM/RAM footprint. Keep DMD assets in external folder, not embedded in table file.

256-color BMPs may help with FlexDMD performance vs 24-bit images. (oqqsan, terryred, Blood Machines)

GIF and Video Handling¶

Scale GIFs to 128x32 for DMD resolution
GIFs don't stop on table pause -- make last frame long (20 sec) to simulate stop
MP4-to-GIF conversion: aconvert.com/video/mp4-to-gif/
Videos added live are always on top and start from frame 1
FlexDMD.LockRenderThread/UnlockRenderThread required when updating DMD

(oqqsan, lumigado, Blood Machines)

PUP Pack Configuration¶

Multi-Screen Setup¶

PUP pack options: 1. 3-screen cab 2. 2-screen with overlay 3. Desktop with DesktopPunch 6. PUP + FlexDMD on separate screens

Each option needs its own .bat file. pupdmddriver=2 for option 6.

Desktop mode: Requires pupinit.bat and PupDesktopPunch.exe. PinballY frontend can interfere with PUP layers, causing black screens. (frankh.5542, heartbeatmd, scampa123, Blood Machines)

PUP Layer Architecture¶

PUP player layer ordering: scores play on highest layer, then application windows (VPX, calculator, etc.), then videos on lowest layer (desktop level).

This is why DesktopPunch.exe is needed for single-monitor play - it cuts a hole in the VPX window so videos below can be seen through. (iaakki, Blood Machines)

PupDMD Update Timer¶

The pupDMDupdate timer needs to refresh fast enough to show spinner count changes. Initial working value was 50 (VPX timer units). Nailbuster recommended 250, but this may be too slow for rapidly changing values. (soundscape2k, Iron Maiden)

B2S Backglass¶

B2S Creation Workflow¶

B2S backglass creation: extract images from existing .b2s file, replace with re-drawn artwork, re-package.

Animation layers in B2S correspond to lamp/solenoid states. For VR, the table may contain its own fully animated backglass separate from B2S.

Critical: Ensure B2S file is included in the zip when packaging releases -- this was missed on multiple Bad Cats releases. (brad1x, benji084, iaakki, Bad Cats)

Audio Configuration¶

WAV vs MP3¶

Rules for WAV vs MP3 in VPX tables: 1. Music/background audio: Use MP3 to save space 2. Sound effects that need positional audio or deformation (pan, frequency shift): Must use WAV 3. Table mechanical sounds: Always WAV 4. MP3 works for callouts played with PlaySound at fixed volume/pan 5. SSF (surround sound feedback) effects: Require WAV

VPX 10.7 can call MP3 files directly from the sound manager. (oqqsan, sixtoe, apophis79, fluffhead35, hauntfreaks, Goonies)

VR Integration¶

Single VPX File Approach¶

Combined VR room and desktop into a single VPX file. VR primitives on dedicated layers with script-toggled visibility.

Issue: Adding VR walls/primitives can shift table position, requiring POV re-adjustment. Always re-import cabinet POV after modifying VR elements.

For minimal VR rooms, use a switch option so users can choose full or minimal room. Desktop cabinet mode can break when VR modifications are added -- always verify both modes. (iaakki, benji084, sixtoe, Bad Cats)

Mirror Sideblades - GL vs DX Renderer¶

Mirror sideblades work correctly in OpenGL renderer but have missing reflections in DirectX renderer. Objects need "Reflection Enabled" checked, and lightmaps also need reflections enabled.

In DX mode, some objects disappear from reflections based on viewing angle. No script-side detection of GL vs DX is available.

Recommendation: GL works better with render probes and DX is being phased out -- recommend GL for tables with mirror sideblades. (iaakki, apophis79, benji084, niwak, Bad Cats)

Debugging Tools¶

Debug Log Viewing¶

Press D during gameplay to view debug log
Must turn off FS Exclusive mode first for debug window to appear
Use msgbox to debug startup events (stops execution until OK pressed)
vpinball.log captures all output but is noisy
Blood Machines and example tables contain file logging scripts for cleaner output

(mrgrynch, oqqsan, apophis79, SpongeBob)

VPX F6 Flying Camera¶

To get free-camera view in VPX F6 mode: 1. Under Keys/Nudge/DOF options, enable "Enable Flying" 2. Hold Alt + arrow keys to move camera 3. Nudge keys rotate the view left/right

Allows inspecting table from any angle including side views. Useful for checking primitive placement and lighting from cabinet perspective. (astronasty, Blood Machines)

DOF Integration¶

DOF Config Tool Submission¶

DOF commands are submitted to the DOF Config Tool site for publication (takes a few days). The cgamename entry stays the same across table versions -- new DOF commands are added to the existing entry.

Process: 1. Add DOF calls in script 2. Test on physical cabinet with solenoids/contactors/LEDs 3. Submit config to DOF Config Tool site

(apophis79, Goonies)

DOF Development with DOTK¶

For DOF development, use DirectOutput Toolkit (DOTK) v0.09 (NOT v0.10 which has bugs): https://github.com/Vroonsh/DirectOutput/releases/tag/DOTKv0.09

It lets you visualize DOF effects. Tie fire button inputs to the launch button as well for cabs without a fire button. (apophis79, Game of Thrones)

Scorbit Integration¶

Scorbit support added via PUP pack integration. Requires qrview.exe and sToken.exe in the PUP directory (not tables directory).

For PUP-based tables, Scorbit files go in the PUP pack folder. Must set scorbit game mode in script when modes start/stop. Works for multiplayer. (daphishbowl, soundscape2k, bountybob, Iron Maiden)

Special Requirements¶

Gottlieb System 3 NVRAM¶

All Gottlieb tables need preset NVRAM file. Without it, ball count problems occur and table won't accept coins.

Available as pack: bally_6803_gts3_nvram.zip. This is a consistent requirement across Gottlieb System 3 games. (gedankekojote97, primetime5k, Street Fighter 2)

Locale Issues¶

Spanish locale caused keycode issues - keyboard presses not registering correctly. Commenting out SetLocale 1033 line and trying SetLocale 11274 (Argentina) resolved debugger problems.

Keycode mapping shifted: key 6→7, key 2→3, key 1→2. VBScript locale settings can interfere with keyboard input handling. (apophis79, tomate80, Street Fighter 2)