Hardware & Cabinet¶

This guide covers hardware integration between virtual pinball software and physical cabinet components, including DOF, nudge hardware, display configuration, recording equipment, and GPU recommendations.

DOF Integration¶

Controllers and Configuration¶

DOF (Direct Output Framework) connects VPX to physical cabinet feedback devices: solenoid-driven contactors, LEDs, motors, and addressable LED strips. Use DOTK (DirectOutput Toolkit) v0.09 for developing DOF effects (v0.10 has bugs). Download from github.com/Vroonsh/DirectOutput/releases/tag/DOTKv0.09 (learned from Game of Thrones).

Solenoid Safety¶

Critical safety issue: DOFOn commands left solenoids continuously energized, causing real hardware damage (burnt fuse/solenoid). The bug was GI code that sent DOFOn instead of DOFPulse. Rules (learned from Game of Thrones):

Solenoid-related DOF outputs must use DOFPulse, never DOFOn
DOFOn is reserved for flippers, button lights, and RGB effects
Always test DOF thoroughly before release -- continuous-on solenoids present a fire risk

Contactor Mapping Best Practices¶

Diverter solenoids (which hold position for extended periods) should NOT have DOF contactor effects assigned. On real machines, diverter coils are small, quiet, and designed to be held on. Assigning DOF contactors to diverters risks burning out physical solenoids because the diverter signal can remain active for the duration of gameplay. Only momentary solenoids (bumpers, slingshots, kickers) should have contactor mappings (learned from F-14 Tomcat).

Best practice from TerryRed: only flippers should be allowed to remain "on" in DOF configs. All other solenoids should have max duration limits (e.g., S5 MAX100 = 100ms max auto-shutoff) (learned from F-14 Tomcat).

DOF Public Config Corruption¶

The DOF public configuration database can become corrupted when users accidentally overwrite shared entries with incorrect data. Symptoms: wrong solenoid mappings, flashers not firing, contactors triggering on wrong events. Back up your DOF config before updating, and verify behavior after any config refresh (learned from Cirqus Voltaire).

Addressable LED Effects¶

Beat the Clock implemented a DOF-driven countdown clock on the backwall using addressable LEDs that mirror the table's clock inserts. Configuration uses SHP (Shape) commands for number display (SHPNumber0-5, SHPColon) in the DOF Config Tool's "PF Back Effects MX" entries (learned from Beat the Clock).

Nudge Hardware¶

Tilt Plumb Simulation (VPX 10.8.1 Native)¶

VPX 10.8.1 includes a native tilt plumb simulator running in the core physics engine at 1kHz. It models a 3D Newtonian mass on a bar that can hit and bounce against a ring -- these hits generate tilt signals. Three nudge models are available (learned from Physics Debate):

Legacy: Direct force on balls
Acceleration-based: Impulse to cabinet spring-mass model
Velocity-based: Best quality, requires Pinscape firmware update

The LiveUI overlay shows the dynamic plumb position when nudging. Settings include inertia factor and tilt threshold, adjustable per setup.

Setup steps: load the nudge calibration table in live editor mode (F7), select Nudge Options from the menu bar, adjust nudge settings, enable plumb simulation and adjust inertia/threshold. For Pinscape users: install Mjr's improved firmware first, enable velocity sensor in VPX settings.

Script-Based Tilt Bob (Pre-10.8.1)¶

Before VPX 10.8.1's native implementation, iaakki prototyped a virtual tilt bob using a VPX ball in a collidable cup mesh. Forward nudges are more secure than sideways (matching real tilt rod orientation). This approach was superseded by the native plumb simulation which runs at 1kHz in the physics engine, impossible to replicate accurately from script (learned from Physics Debate).

Tilt Handling in VPX Tables¶

The MechanicalTilt keycode triggers CheckTilt in the script. Real Stern behavior: 2 warnings per ball, 3rd tilts. Add a debouncing timer (Stern default: 1000ms ignore window after contact). keycode = MechanicalTilt should add more tilt value than regular nudge. VPX hits the 'T' keycode when the analog nudge limit is exceeded. Separate mechanical tilt handling from desktop nudge-key tilt for cab vs desktop play (learned from Game of Thrones).

The tilt switch mapping must not collide with other cabinet button assignments. One table had tilt switch set to -7, which mapped to the "Advance" button inside the cabinet, causing the service menu to activate when a player tilted (learned from Guns N' Roses).

Flipper Input: Leaf Switch vs Keyboard Polling¶

Physical cabinet flipper button input method significantly affects flipper trick detection (learned from Fish Tales):

KL25Z board with leaf switches: Limited to approximately 20ms minimum due to debounce (8ms) plus spring contact bounce. Occasionally misses fast taps entirely.
PS/2 keyboard hack with gold leaf switches: Pure interrupt-driven (no USB polling), achieves 5-8ms tap detection with zero missed contacts.

For tap passes to feel natural, the sosramp parameter needs to be very low (~0.5) to compensate for input latency. Players at 60 Hz are further disadvantaged because VPX can only register inputs once per frame (16.7ms).

PinAffinity (mjrnet.org/pinscape/PinAffinity.html) dedicates CPU threads to pinball software and sends other processes to other cores. Combined with a stripped-down Windows installation, this reduces input lag and script timing jitter. Important for consistent flipper physics, especially live catch timing (learned from Austin Powers).

Recording and Scanning Equipment¶

Playfield Scanning¶

The HP Scanjet 4600 and 4670 (20+ years old, discontinued) are the only scanners that produce distortion-free playfield scans suitable for VPX. Both are see-through scanners -- flatbed scanners have a raised glass lip that causes inaccuracy. Scan at 300-600 dpi in a dark room for consistent color reproduction. The proprietary USB/power cable can be spliced from standard USB wire colors with about 30 minutes of soldering (learned from VPW Resources).

For plastics and backglasses, use an Epson 4490 or similar scanner with adjustable focus -- the HP 4670 cannot focus on objects raised above its surface (learned from VPW Resources).

Sound Recording¶

Fleep's recommended microphone types in order of preference (learned from Fleep Sounds Guide):

Large Diaphragm Cardioid Condenser (e.g., Blue Yeti at gain 0)
Small Diaphragm Cardioid Condenser
Cardioid Dynamic
X/Y Stereo Condenser (Zoom portable recorders)
Electret/MEMS (phones/GoPros, last resort)

Key procedure: record with video synced to audio (to correlate sounds with physical events), playfield glass ON (retains true cabinet acoustics), device slightly above lockdown bar on tripod (never laying on the cabinet). Deliver via Google Drive or Dropbox, never YouTube which compresses audio.

3D Scanning¶

Polycam phone app (even older iPhones) can produce high-quality 3D scans of pinball toys. For best results: place the piece on a lazy susan with good lighting and rotate slowly while scanning. The resulting mesh can be decimated significantly in Blender (100K tris down to 4.6K) while retaining visual quality (learned from Godzilla).

Qclone (iOS app) is an alternative for photogrammetry. It provides a printable grid for reference and displays a sphere of capture angles to complete. Free to use, $15 to unlock 3D file export. 3DF Zephyr is a PC-based alternative (learned from Austin Powers).

Screen Setup¶

Playfield Display¶

For cabinet playfield monitors, correct POV (Point of View) settings depend on physical cabinet geometry: monitor size, tilt angle, player height, and portrait vs landscape orientation. Key parameters (learned from Congo):

Inclination: 6-20 degrees depending on cabinet build
FOV: 29-45 degrees
Layback: 42-70 degrees
Once Inclination, FOV, and Layback are dialed for your physical setup, only X/Y offsets need per-table adjustment

The coin-on-glass trick: place a physical coin on the cabinet glass next to a round insert and adjust POV until they match size.

Anti-Ball-Stretch Configuration¶

The "Anti Ball Stretch" checkbox alone is not sufficient -- you must also enter your monitor's aspect ratio (e.g., 16:9) in the associated fields. Without the ratio, the ball still appears egg-shaped on rotated monitors. The ratio may need to be swapped (9:16 vs 16:9) depending on whether the monitor is natively portrait or landscape-rotated (learned from Congo).

DMD Display¶

Desktop DMD visibility is controlled by UseVPMColoredDMD. For cabinet mode, set the initial declaration to False. The desktop mode logic activates it conditionally. A common release-day bug: forgetting to set the initial const to False causes the DMD to render in both modes (learned from Dr. Who).

DMD textbox aspect ratio should be set to approximately 300x90 to respect the display's native ratio. Default DMD size is squished vertically (learned from Dr. Who).

SSF (Surround Sound Feedback)¶

For tables with multiple sound categories, define separate volume constants tuned for SSF cabinet use (learned from Goonies):

Const VolumeDial = 0.7       ' Mechanical Sound Volume
Const MusicVolumeDial = 0.4  ' Background Music Volume
Const BackGlassVolumeDial = 0.5 ' Callout Sound Volume

All mechanical sound effects (PlaySound calls) must be connected to the VolumeDial variable. Format: PlaySound "fx_relay", 1, VolumeDial. Without this, mechanical sounds ignore the user's volume setting (learned from Goldeneye).

Playfield physical sounds must be mono, not multi-channel. Stereo sounds cause errors and degrade SSF output (learned from Ghostbusters).

The sound panning in VPX uses a pan law where center-panned sounds are louder than hard-panned: Left=100%, Middle=200%, Right=100%. This is a code-level limitation that cannot be changed from the script side (learned from Fleep Sounds Guide).

GPU Recommendations¶

For VR: the minimum GPU recommended is a GTX 1060, with a GTX 1660 handling everything satisfactorily (learned from Dr. Who). Monitor refresh rate above 144 Hz provides diminishing returns -- sixtoe could not tell the difference between 144 Hz and 240 Hz.

Stable frame pacing (consistent time between frames) matters more than raw FPS for perceived smoothness. A flat 110 FPS with consistent frame timing feels smoother than fluctuating 130-150 FPS (learned from Dr. Who).

Render probe roughness is the single biggest GPU consumer. Removing roughness from render probes yields up to 40% FPS improvement on some systems. Multiple render probes compound the performance hit. Overlapping refractions (bumper caps near each other) cause more performance issues than single refractions (learned from Fish Tales, Bad Cats).

The DX9 renderer lacks modern GPU optimizations. Draw calls and state changes are the performance bottleneck, not polygon count. Tables with fewer polygons but more state changes can perform worse than higher-poly tables with fewer state changes (learned from Bad Cats).

POV Calibration Workflow for Cabinets¶

Once the base POV parameters (Inclination, FOV, Layback) are dialed in for your cabinet's physical setup, only X/Y offsets need per-table adjustment because VPX origin varies by table.

Flupper's recommended calibration values for reference: Inclination 6, FOV 45, Layback 65, designed so the top of the table tucks under the backbox, matching real machine perspective (learned from Congo).

Set min and max table slope to the same value during testing so you know exactly what slope you are working with. Difficulty level affects scatter but NOT ball mass (learned from Physics Debate).

VR Cabinet Mode Hardware Considerations¶

VR room objects can cause significant stutter. Reducing texture sizes for cabinet elements helps but may not eliminate VR stutter entirely. The vrroom script variable controls room mode (0=off, 1=full, 2=reduced). Investigate VR stutter by disabling B2S, checking external DMD capture, and testing with vrroom=2 to isolate the performance bottleneck (learned from Cactus Canyon).

See VR Development for comprehensive VR-specific guidance.

Cabinet Button Mapping¶

vpmKeyUp and vpmKeyDown subs in the system-specific .vbs file handle basic keystrokes including flipping. You only add code to the table's keydown/keyup subs to supplement that. FlipperActivate/FlipperDeActivate can be moved to the SolLFlipper and SolRFlipper solenoid callback subs (learned from Jurassic Park).

Staged flipper support requires dual-contact leaf switches in the cabinet. Single-contact switches cannot support staging. Primetime5k maintains a spreadsheet of tables with staged flippers at docs.google.com/spreadsheets/d/1cPvIOk5o0VgnUk8sSPvCOt1VaH613PIS1JDJTEl7Qoc/ -- staged flippers started appearing after 1988 (learned from Jurassic Park).

Analog Plunger Bug¶

VPX has a longstanding bug where the analog plunger (physical cabinet plunger) does not work correctly: VPX internally checks if the keyboard "plunge" key is pressed, and if not, resets the plunge status -- even when an analog device is actively pulling the plunger. Workaround: use two timers with associated code to manage the plunger state independently (learned from Earthshaker).