Software Setup & Configuration¶

This guide covers the installation and configuration of all software components in the virtual pinball stack, from VPX itself through ROM emulation, display systems, sound, and development tools.

VPX Installation¶

32-bit vs 64-bit¶

VPX ships in both 32-bit and 64-bit variants. There is no need to uninstall 32-bit VPX when installing 64-bit -- rename the executables (e.g., vpinball10.8.0_863_64bit.exe) and keep both versions side by side (learned from Big Bang Bar).

Some tables require 64-bit VPX (Big Bang Bar being the notable example). The 32-bit version has hard RAM limits: table files exceeding approximately 300-350 MB cause textures to silently disappear (go white) at runtime. The 32-bit version is effectively deprecated per Niwak (learned from Fish Tales, Iron Maiden).

Running toolkit tables on 32-bit VPX hits texture memory limits, causing VPX to automatically downsample lightmap nestmaps. This is visible as soft/blurry graphics when GI activates. Manually downresizing EXR lightmaps to 4K in Blender and re-saving with DWAA compression produces cleaner results than VPX's runtime downsampling.

Performance Settings¶

For performance issues, disable playfield reflections, FXAA, AO, and screen space reflections first. Next, lower resolution. Finally, change textures from "unlimited" to the next option down. With all these disabled, tables can launch at 5K on a 4GB video card (with low framerate). Check if the saved table file has forced video settings that override user preferences (learned from Bad Cats).

Set "Maximum Pre-Rendered Frames" to 0 in VPX video settings for VPX 10.8+. The default value caused VPX 10.8's new frame scheduling to conflict with GPU driver frame queuing, resulting in intermittent frame drops (learned from Cirqus Voltaire).

OpenGL vs DirectX¶

Per Niwak, OpenGL is recommended for desktop/cabinet play, not just VR. Key differences (learned from Guns N' Roses):

OpenGL: Hardware-level adaptive sync, MSAA anti-aliasing, stereo rendering. Precise refresh rate delivery.
DirectX 9: Software-level adaptive sync roughly emulated by VPX, less precise. Better performance on certain hardware, cleaner supersampling appearance on some setups.
GL disadvantage: FlexDMD hidden behind playfield in desktop mode on some configurations.
Future direction: DX10+/Vulkan planned to replace both.

Registry Fixes¶

Window position recovery: The VPX script editor window can become invisible when monitor configurations change. The window position is stored in the Windows registry and can reference a monitor that no longer exists. Fix: close VPX, open Registry Editor, navigate to the VPX registry keys for window positions, and delete the position entries. Alternative: right-click the editor window in the taskbar preview, select "Move", then press arrow keys to bring it back on screen (learned from Bram Stoker's Dracula).

VSync override bug: Tables shipping with VSync override set to 1 instead of -1 in the User properties tab cause loading crashes and setting persistence failures. Always verify VSync override is set to -1 before release (learned from Johnny Mnemonic).

PinMAME / VPinMAME Setup¶

Installation¶

VPinMAME 64-bit must be installed separately by running Setup64.exe. A common user error is installing PinMAME but not VPinMAME (learned from Big Bang Bar). As of B2S Server version 2.0, a separate B2S x64 install is not required.

PWM Migration (PinMAME 3.6+)¶

PinMAME 3.6 introduced physics-based PWM (Pulse Width Modulation) output for hardware-accurate lamp fading, replacing manual scripted fading. Migration steps (learned from Godzilla, Breakshot):

Set UseVPMModSol = 2 for new physics output (value 1 maintains backward compatibility)
PWM signals from core.vbs are now float 0..1 range (previously 0..255 when accessing Controller directly)
Remove SolMask array initializations (optional cleanup)
Set light object fader to "Incandescent" (can be done from script via the Fader property)
Updating a lightmapped VPW table takes less than 5 minutes

To enforce a minimum VPinMAME version, use the first argument of LoadVPM: LoadVPM "03060000","CAPCOM.VBS",3.10 forces users to have VPM 3.6+ (learned from Defender).

Caution with UseVPMModSol=2: This setting can cause DOF cabinet solenoids to activate and stay stuck on at table startup. If diverter or kicker solenoids send DOF signals without deactivation, add MAX100 duration limits in DOF config (learned from F-14 Tomcat). The T-Rex mech on Jurassic Park also exhibited erratic behavior with UseVPMModSol=2; adjusting speed and tolerances in motor simulation code was required rather than disabling ModSol entirely (learned from Jurassic Park).

Cabinet Mode Checkbox¶

The "Cabinet Mode" checkbox in VPinMAME ROM settings (F1) should be enabled by default even on desktop. Despite its misleading name, it suppresses the VPinMAME splash screen and warning message boxes, and prevents sticky flipper bugs when using B2S in non-exe mode (learned from Jokerz).

ROM Management¶

MAME uses parent/child ROM sets. The parent (latest chronological version) contains all ROMs including sound. Child ROMs only contain files that differ from the parent. Both ZIP files must be present in the ROMs folder (learned from Judge Dredd).

For Gottlieb System 1 ROMs, the fixed "CF" spider chip redump is required. Old versions had a bad byte. Use the fixed ROM pack from PinballNirvana specifically for VPinMAME v3.6.0-963+ (learned from Countdown).

Home ROM variants (_h suffix) remove coin-related features for home use, but this can break some table features that depend on coin door switches. Look for _hc variants that restore coin support (learned from Cirqus Voltaire).

NVRAM and Config Files¶

When a table exhibits erratic behavior (switches not registering, mechanisms firing incorrectly), deleting the NVRAM (.nv) and config (.cfg) files forces the ROM to reinitialize with factory defaults. NVRAM files are stored in VPinMAME's nvram directory, named after the ROM. Always try NVRAM deletion before assuming the table script is broken (learned from Cactus Canyon).

DIP switch defaults can be set via script (SetDefaultDips function, requires table restart) or by shipping a pre-configured .nv file with the table (learned from Haunted House).

B2S Backglass Setup¶

The B2S (DirectB2S) editor does not allow replacing images in existing elements except the main backglass. To update animated elements: import the new image, create a new element with the same parameters (sequence timing, ROM ID triggers), then delete the original (learned from Bad Cats).

B2S animations are driven by Controller.B2SSetData calls in the VPX script. Critical: wrap B2S calls in If B2SOn Then ... End If to prevent runtime errors when no B2S is loaded (learned from Cirqus Voltaire).

PUP Pack Configuration¶

PUP packs are distributed separately from VPX table files (typically 200-300+ MB). Both must be updated together for features to work (learned from Die Hard Trilogy).

All PUP videos must be 1920x1080. Non-standard resolutions can cause codec crashes (learned from Iron Maiden). Add Set PuPlayer = Nothing in the Table_Exit sub to properly release the PUP COM object. Without this, PUP processes can hang in the task manager (learned from Iron Maiden).

PUP media optimization: ffmpeg batch processing can reduce PUP media dramatically (2.65 GB to 1.1 GB in one case) by re-encoding all videos at 30fps/HD with lower bitrate. No visible quality difference on 1080p DMD screens (learned from Iron Maiden).

VPX 10.8 broke the PupDMD "desktop punch" feature. Workarounds: use windowed mode instead of exclusive fullscreen, or set resolution to 1 pixel less than native (the "1-pixel trick") in GL mode (learned from Goonies).

FlexDMD Setup¶

FlexDMD provides a scriptable dot-matrix display for original (non-ROM) tables and as a DMD alternative for ROM tables.

If FlexDMD does not appear in desktop mode: check FlexDMDUI.exe for green checkmarks, check DmdDevice.ini (the [virtualdmd] section may default to enabled = false), and ensure FlexDMD and freezy dmdext are installed in the correct VisualPinball folder (learned from Game of Thrones).

FlexDMD can crash with System.OutOfMemoryException on 32-bit VPX. Use 64-bit VPX to avoid this (learned from Game of Thrones).

Random stutters from FlexDMD are often caused by FlexDMD.log.config having minlevel set to "Trace" instead of "Warn". Change the logging rules to "warn" for release builds (learned from Goonies).

Auto-detect FlexDMD installation by wrapping the CreateObject call in error handling rather than checking filesystem paths. FlexDMD is built into standalone VPX and always available there (learned from VPW Example Table).

DMD Extensions (Freezy dmdext)¶

For 64-bit VPX with colorization: install Freezy's x64 DMD extensions, then apply Lucky1's coloring files on top. SERUM colorization is the preferred path forward for VPX standalone compatibility (learned from Big Bang Bar, Breakshot).

Running 64-bit VPX requires 64-bit versions of Freezy DMD and dmdext. Mixing 32-bit dmdext with 64-bit VPX causes crashes or missing DMD (learned from LOTR).

DOF Configuration¶

Use DOTK (DirectOutput Toolkit) v0.09 for developing DOF effects. Do NOT use v0.10, which has bugs. Download from github.com/Vroonsh/DirectOutput/releases/tag/DOTKv0.09 (learned from Game of Thrones).

Critical safety issue: A GI-On DOF command left solenoids continuously energized, causing real hardware damage (burnt fuse/solenoid). Only solenoid-related DOF outputs should use DOFPulse; DOFOn should be reserved for flippers, button lights, and RGB. Always test DOF thoroughly before release (learned from Game of Thrones).

Diverter solenoids should NOT have DOF contactor effects assigned. They hold position for extended periods and can burn out physical solenoids in cabinets. Only momentary solenoids (bumpers, slingshots, kickers) should have contactor mappings (learned from F-14 Tomcat).

The DOF public configuration database can become corrupted when users accidentally overwrite shared entries. Back up your DOF config before updating (learned from Cirqus Voltaire).

VPinSPA (Stern Pinball Arcade Emulation)¶

Ghostbusters uses VPinSPA instead of standard VPinMAME. Setup requirements (learned from Ghostbusters):

Install VPinSPA using provided installer
May need Microsoft Visual C++ 2012 x86 redistributable
ROM files extract to C:\Visual Pinball\VPinMAME\spagb100\
The ROM originates from Stern Pinball Arcade (free base game on Steam), extracted via pba-tools
DMD Extension must be installed into the VPinSPA folder specifically

For 64-bit operation, registry entries must be added (see Ghostbusters extraction for the specific commands). Warning: this removes WOW64 protections and behavior is undefined.

Altsound Setup¶

Altsound can be baked directly into the VPX table script, eliminating the need for PinSound or external altsound software. The approach uses a "sound command listener" function that intercepts ROM sound commands and plays replacement sounds from imported VPX sound files. OGG format in VPX 10.7+ reduces file size dramatically (~65MB vs ~150MB for WAV). PinSound no longer supports virtual pinball, making this approach the future direction (learned from Goldeneye).

Standalone VPX Considerations¶

gBOT vs GetBalls Crash¶

Standalone VPX crashes (segfault) when CorTracker uses allBalls = gBOT instead of allBalls = GetBalls. This causes 95% of "ball hits flipper then segfault" crashes in standalone. The gBOT variable is a VPX-specific optimization that does not exist in standalone (learned from Defender, Jurassic Park).

Variable Clashes¶

VPX loads globalplugin.vbs (if present) into the same script namespace as the table script. If both define subs with the same name, the globalplugin version silently overrides the table version, causing type mismatches and crashes. Use table-specific prefixes for custom functions (learned from Iron Maiden).

VPX Script Debugger¶

Installing Visual Studio 2010 Isolated Shell provides enhanced VBScript debugging for VPX with a full call stack trace, showing the chain of function calls that led to a crash rather than just the error line. Available via Microsoft Visual Studio downloads (search "shell 2010" at my.visualstudio.com/Downloads). The built-in VPX debugger (press D during gameplay) shows debug.print output but lacks call stack information (learned from Bram Stoker's Dracula).

Realtime property adjustment works in F5 (play) mode but NOT in F6 (editor play) mode in some VPX versions. Debug workflow: run table in F5, press D to open debugger, type plastic001.depthbias = -200 and press Enter to see immediate visual changes (learned from Bram Stoker's Dracula).

Blender Toolkit Installation and Compatibility¶

The VPX Lightmapper toolkit requires specific Blender versions. Blender 3.6 is confirmed compatible. Blender 4.0 may not apply bump maps to text the same way, and VPX toolkit export features may not work correctly (learned from Bad Cats).

When opening old Blender files in newer versions, blackbody nodes on lights can break, causing the entire render to appear red. Manually re-set blackbody nodes after upgrading Blender versions (learned from Creature from the Black Lagoon).

Install "Tony McMapFace" as an alternative tonemapper by replacing files in Blender's datafiles/colormanagement directory. The default Filmic tonemapper produces oversaturated results. All toolkit tables benefit from this tonemapper. With Tony McMapFace (and later AGX), 2700K bulb temperature -- the physically correct value for incandescent bulbs -- works correctly, whereas Filmic required 3000-3200K to avoid excessive yellow (learned from Breakshot, Jurassic Park).

Virus Detection False Positives¶

Windows Defender may flag VPX release archives as Wacatac trojan. This is a confirmed false positive. VPX files cannot be code-signed, making false positives unavoidable. Use VirusTotal to cross-check across multiple scanners (learned from Big Bang Bar).

VPReg.stg Settings File¶

VPX SaveValue/LoadValue commands store persistent data (high scores, service menu settings) in VPReg.stg in the User directory. This file stores data across all tables. A tool exists to view and edit this file (shared in VPW resources) (learned from Game of Thrones).

VPX Table State Persistence Bug¶

VPX saves certain table state on exit. If the table tilts and then crashes or is force-closed, bumper and slingshot threshold values can be permanently set to 100 (disabled) in the saved state. Fix: re-download the table, or manually reset threshold values. Prevention: set all pop bumper and slingshot thresholds at table init (learned from Jokerz).