Troubleshooting Cookbook¶

This guide covers common problems encountered in Visual Pinball X table development and playback, organized by problem category. Each section follows a problem-cause-solution format with specific error messages, proven fixes, and references to the tables where these issues were discovered and resolved.

VPX Editor and File Issues¶

Editor Crashes¶

VPX editor crashes are among the most frustrating issues during development, and they tend to correlate with table complexity. Tables with large numbers of primitives are more prone to editor lockups, particularly when clicking on a primitive before pressing F5 to play. Memory pressure from the image manager may also contribute. (oqqsan, fluffhead35, Goonies)

If VPX crashes when launching from the editor with a path error (e.g., referencing C:\projects when VPX is installed on D:), the fix is to reinstall using the VPX all-in-one installer from vpinball.com. Rename your old VPX folder first, then install fresh -- the drive letter does not matter. (o0skitso0o, iaakki, Monster Bash)

Practical mitigations:

Save frequently, especially before pressing F5
Reduce unused images in the Image Manager
Click on a primitive before pressing F5 (this anecdotally reduces crash frequency)
Keep a recent known-good backup of your table file at all times

Table File Corruption¶

VPX files can become corrupted through several mechanisms, each producing different symptoms.

Debug version corruption: Saving a table from the VPX debug build can corrupt all physics values in the material manager, setting everything to zero. Symptoms include flippers stuck in the up position and bizarre ball behavior. The only recovery is manually merging your changes back into the last known-good version. (fluffhead35, o0skitso0o, Diner)

Save corruption from crashes: When VPX crashes during a save operation, the resulting file may exhibit unexplained brightness changes, broken collections, and frame rate drops (e.g., from 40 FPS down to 15 FPS). Always check collections for incorrect object membership and verify VR room objects are hidden when they should be. (wrd1972, sixtoe, F14)

Full disk corruption: VPX can silently create a dummy .vpx file when the drive is full. The save operation reports success, but the resulting file is only ~12KB instead of the expected size. The VPX autosave feature is unreliable (it saves twice then never again), so always verify file size after saving critical work. (wylte, VPW Example Table)

VPX Autosave

Do not rely on VPX's built-in autosave. It has known issues where it fires twice and then stops. Maintain your own backup discipline -- save before every test run and keep dated copies of your working file.

Editor Bugs and Quirks¶

Collection and light renaming freeze: In VPX 10.7 betas, clicking the center handle of a VPX light and attempting to rename it can freeze VPX completely. Adding lights to collections before renaming triggers the issue. Workaround: rename objects before adding them to collections, or use VPX 10.6 where renaming works normally. (oqqsan, Blood Machines)

Table rename dialog: A VPX editor bug can cause the table object itself to be accidentally renamed (e.g., "Table1" becomes "Wall013001") through a dialog popup that appears when selecting and copying an object name. The dialog asks if you want to rename everything that uses it. If this happens, rename back to "Table1" in main preferences. (sixtoe, apophis79, Die Hard Trilogy)

Duplicate Visuals panel: VPX sometimes creates a duplicate "Visuals" panel in the editor. When this happens, it is unclear which panel's settings are saved. The second panel is usually the correct one. Best practice: save, close, and reopen VPX to validate your changes. (iaakki, apophis79, oqqsan, Die Hard Trilogy)

Collection grouping moves objects: When a VPX collection has grouping enabled, it is easy to accidentally move all objects in the collection instead of just one when zoomed in. This caused misaligned acrylic protectors in Theatre of Magic. Be cautious with collection grouping. (iaakki, TNA)

Collections report wrong counts: VPX collections have persistent bugs where they report incorrect object counts (e.g., showing 4 items when only 3 exist), objects receive events from wrong collections, and hit events stop working. The fix requires deleting old collections, creating new ones, disabling and re-enabling hit events on objects, and restarting VPX between steps. Leftover collections with the a_ prefix from other projects can make the problem worse. (iaakki, wylte, BOP)

Finding Stray Collection Items

VPX warns "Selected elements are part of one or more collections" when deleting but does not specify which collections. To find discrepancies, compare the count of items in a layer versus items in the corresponding collection. In Bad Cats, the GI layer had 91 items but the GI collection had 92 -- the extra item was a stray flasher. (iaakki, Bad Cats)

Version Compatibility¶

VPX 10.7 backward compatibility: Tables saved in VPX 10.7 are NOT backward compatible with 10.6. Accidentally opening and saving a 10.6 table in 10.7 will corrupt it. Always maintain separate files for different VPX versions. (rothbauerw, sixtoe, TFTC)

VPX 10.6 vs 10.7 beta: VPX 10.7 betas introduced physics regressions in certain builds. For example, build 328 broke balls' ability to rest on walls. Tables built for 10.6 should be played on 10.6. Key 10.7 benefits include unlimited layers, MP3/OGG audio support, and WebP image support, but beta builds can regress physics and lighting. (sixtoe, bountybob, pinstratsdan, Black Rose)

Save version mismatch: Saving a table in an older VPX version after editing in a newer one can silently delete features not supported by the older version. This caused light animation data loss in Theatre of Magic. Always save in the VPX version your project targets. (retrog33k, gtxjoe, TNA)

VPX 10.7.0 vs 10.7.2: Tables saved in 10.7.2 show a warning when opened in 10.7.0 but are functionally compatible. Some visual differences can occur: bumper initialization failures are more common in 10.7.0 32-bit, and phantom lights may appear under objects in 10.7.2 that do not exist in 10.7.0. (clarkkent9917, apophis79, sixtoe, Road Show)

VPX 10.8 playfield mesh handling: VPX 10.8 split the visible and physics playfield mesh handling. Tables using older approaches (such as Defender's ON_Prims collection) may show a black playfield and missing reflections. Fix by ensuring the playfield mesh follows 10.8 conventions. (apophis79, wylte, Defender)

Version Merge and Binary Format¶

The VPX binary file format makes collaborative development extremely difficult. While scripts can be compared with WinMerge or Notepad++ diff, table-level changes (primitive positions, light settings, collections) cannot be diffed at all. A version merge on Bad Cats between a GI update (v2.11, based on v2.03) and mainline took 4 hours of manual work. (sixtoe, o0skitso0o, iaakki, fleep1280, Bad Cats)

Ball Physics Problems¶

Ball Stuck Issues¶

Balls getting stuck is one of the most common physics issues. Diagnosis starts with identifying the exact ball coordinates using the VPX debugger.

Getting stuck ball coordinates:

With the table loaded and ball stuck, press D to open the debugger
Look at ball position values (X, Y, Z)
Use those coordinates to identify the problem geometry

(DJRobX via Thalamus, Starship Troopers)

Velocity nudge fix for stuck balls on ramps: When a ball loses momentum on a ramp curve and stops, you can detect the condition and apply a small velocity nudge:

If gBOT(b).z > 94 And gBOT(b).z < 100 And gBOT(b).x < 70 _
   And gBOT(b).y < 1175 And gBOT(b).y > 1110 _
   And gBOT(b).vely < 0.1 Then
    gBOT(b).vely = gBOT(b).vely + 2
End If

This checks if a ball is within a specific problem zone and barely moving, then gives it a downhill push. Adjust the coordinate ranges and velocity threshold for your specific table. (rothbauerw, Godzilla SEGA)

Common stuck ball causes and fixes:

Overlapping geometry: Ramps made of walls AND a primitive mesh create a "hill" at ramp exits. Fix by modifying the primitive to match the ramp exit shape and deleting redundant walls. (tomate80, Monster Bash)
Collidable screws/decorations: Random collidable primitives (e.g., a screw floating in the shooter lane) can block ball paths. Always check for collidable primitives when balls get stuck in unexpected locations. (sixtoe, F14)
Ball sinking into playfield mesh: If the ball's Z position is below 25.00 (e.g., 23.87), it is sinking into the mesh. Add a physical VPX wall just below the surface at the problem location. (apophis79, daphishbowl, Iron Maiden)
Ball stuck behind drop walls: Using a drop wall for mechanisms like hatches can cause "Narnia balls" (balls teleporting) when the wall raises while balls are nearby. Change to a wall that toggles collidable = false instead. (iaakki, Blood Machines)
Ball stuck behind bumpers: Usually caused by playfield warp in scans. Turn up bumper thresholds by 1 to reduce trapping. (Deleted User, wylte, Tommy)

InRect Helper

The InRect function can detect when a ball is in a problem zone and apply corrective forces. But be careful with the ball index -- GetBalls array indices can change unpredictably during gameplay. Setting lob=0 ensures no balls are skipped. (apophis79, iaakki, TFTC)

Narnia Ball Recovery¶

When a ball falls through gaps in playfield geometry, it drops into "Narnia" -- infinite free-fall below the table. The symptom is a ball count that drops by one with no drain event, accompanied by a permanent ball-rolling sound. Rather than trying to patch every possible geometry gap with invisible walls, implement a Narnia guard timer:

Sub NarniaGuard_Timer
    Dim balls, b
    balls = GetBalls
    For b = 0 To UBound(balls)
        If balls(b).z < -500 Then
            ' Ball has fallen through -- recover it
            balls(b).x = 250  ' Safe X position
            balls(b).y = 800  ' Safe Y position
            balls(b).z = 50   ' Above playfield
            balls(b).velx = 0
            balls(b).vely = 0
            balls(b).velz = 0
        End If
    Next
End Sub

Set the timer interval to 300ms. First implemented in World Cup Soccer, then refined for Road Show and Game of Thrones.

Do NOT Return Narnia Balls to the Drain

Placing recovered balls in the drain confuses the ROM into thinking an extra ball is in the trough, causing double-ball-in-plunger-lane bugs. Instead, return the ball to its logical position (e.g., back into the lock mechanism it fell from). (apophis79, Road Show)

Ball Path and Trajectory¶

Ball flying off ramps: Common causes include gate brackets set to "collidable" instead of "toys" (the ball hits brackets mid-ramp) and flipper strength set too high for the table's system type (e.g., 3300 vs the proper 2300-2600 for System 11). (gtxjoe, benji084, astronasty, Police Force)

Ramp apex stuck balls: Balls getting stuck on a ramp curve are usually caused by the ramp apex not matching the physical high point. Set the apex of the hill at the apex of the corner, then ensure the descent is gradual. When elevation and table slope cancel out, you get a flat section where the ball loses all momentum. Real ramp protectors bridge the playfield-to-ramp transition gradually; VPX ramps with steep inclines slam the ball and kill momentum. (sixtoe, fluffhead35, manners7344, Diner)

Right orbit return issues: If the ball hits the flipper tip instead of the middle on orbit returns, adjust the return path wall angles. Even small changes (one corner, one unit) can make the difference between consistent orbit combos and frustrating drains. (apophis79, Die Hard Trilogy)

Ball escaping over apron: During aggressive multiball, balls can jump over the apron wall. Set non-visible apron walls to height 100-300 units as standard practice across all tables. (wylte, apophis79, sixtoe, Last Action Hero)

Playfield Mesh Issues¶

The playfield_mesh primitive is central to many ball physics problems. Several critical facts:

Case sensitivity: The name playfield_mesh is case-sensitive in VPX. Naming it Playfield_Mesh (capitalized) causes VPX to fall back to a flat surface. VBScript in general is not case-sensitive, making this a special case. (rothbauerw, F14)

Origin alignment: After adding a playfield mesh, if all inserts appear misaligned from their light positions, the mesh was accidentally nudged from 0,0 during editing. Ensure the playfield_mesh primitive is exactly at position 0,0. (o0skitso0o, astronasty, sixtoe, Congo)

Z-position flickering: Flickering or spastic playfield ball reflections are caused by the playfield_mesh being at a non-zero Z position (e.g., -9 instead of 0). Fix by exporting the mesh to its own layer, reimporting, and resetting coordinates to 0,0,0 with scale 1,1,1. (apophis79, sixtoe, flux5009, Die Hard Trilogy)

Flipper area mesh lines: Playfield mesh polygon edges intersecting the flipper area cause the ball to hover halfway up a flipper until you flip. Avoid creating polygon edges in the flipper zone. (apophis79, Congo)

VPX 10.7.2 physics regression: In 10.7.2, the playfield_mesh is a specially-named primitive whose physics properties are overridden by table playfield settings. If the "override material settings" checkbox is checked on the primitive, behavior can differ from 10.6. Many tables had this checkbox set because it previously had no effect. Per niwak (VPX dev): backward compatibility was intended, and any deviation is a bug in VPX, not in tables. (apophis79, iaakki, rothbauerw, niwak, Physics Debate)

Missing reflections in VPX 10.8: Multiple VPW tables lost reflections in VPX 10.8, including Iron Maiden, Judge Dredd, Lethal Weapon 3, and others. Root cause: playfield_mesh primitives interfering with the render probe. Fix by deleting primitives starting with "playfield_mesh" and recreating them, or by un-ticking "Use Transparency" on the "playfield" material and commenting out UpdateMaterial lines. (apophis79, wylte, studly_do_right, Defender)

Playfield mesh edge ball sticking: Balls can catch on seam lines where mesh segments meet. Fix by ensuring mesh segments overlap slightly or by smoothing the seam in Blender. (mcarter78, WCS94)

Collision and Bounce¶

Balls resting on primitives: Balls resting on primitives can slowly sink through and disappear during idle. Captive balls are especially affected -- if the walls cradling a captive ball are primitives rather than VPX walls, the ball never settles. Solution: always use VPX walls (not primitives) to support resting balls. (sixtoe, gedankekojote97, Street Fighter 2)

Target bouncer ball jumps: The target bouncer code gives Z-velocity on first hit. If a second target amplifies it, the ball can gain enough height to jump walls. Add "ceiling" walls above target areas to cap jump height. Also check for tiny lips in walls that cause odd ball behavior. (rothbauerw, Monster Bash)

Moving collidable objects limitation: VPX has a hard limitation: you cannot have a moving collidable object except the built-in flipper. As soon as a primitive starts moving, it stops being collidable. To simulate moving collision surfaces (like a battering ram), use cascading walls at different positions and enable/disable them as the animated object moves:

' Enable/disable collision walls based on ram position
Sub UpdateRamCollision(position)
    Ram_Low.Collidable = (position < 200)
    Ram_Mid.Collidable = (position >= 200 And position < 400)
    Ram_High.Collidable = (position >= 400)
End Sub

(sixtoe, bhitney, iaakki, Game of Thrones, Blood Machines)

Flipper Issues¶

Flipper Physics Problems¶

Flipper nudge bug (cradled balls jumping): When both flippers have cradled balls, the balls can start jumping on their own. The root cause is that the flipper gets knocked off its end angle, triggering an EOS recheck that mistakenly nudges the ball on the other flipper. (iaakki, rothbauerw, Metallica)

VPX flipper nudge fix: This was traced to a floating point comparison bug in VPX. The fix was applied at the VPX engine level. (Blood Machines)

Ball jiggle on flipper cradle: A ball jiggling or rolling on its own when cradled on the right flipper is usually caused by nearby playfield mesh nodes creating micro-collisions, or by cuts/gaps in the playfield surface geometry near the flipper area. This is a common VPX issue without a complete fix. (astronasty, apophis79, Blood Machines)

Ball held between flippers: In VPX, when holding a ball on the flipper and a second ball rolls into the held ball, the held ball gets tossed off. On a real machine, the held ball stops the incoming ball. This is a fundamental VPX physics limitation with no known workaround. (clarkkent9917, apophis79, Road Show)

Flipper Configuration¶

nFozzy right flipper angle: Right flipper angles must be negative values for nFozzy physics code to work. Setting a positive value (e.g., 238 instead of -122) breaks live catch, nudge, and all flipper tricks. Also ensure CheckLiveCatch is actually called somewhere in the flipper_collide subs. (iaakki, Congo)

Flipper positioning: Ball jamming on a flipper during feeds from ramps can be caused by the flipper being off by just 1-2 pixels. Move the flipper in small increments (e.g., 2 units down, 3 right) and test by shooting the right orbit 3 times -- the ball should live catch on the left flipper cleanly. (iaakki, sixtoe, Ghostbusters)

EOS Torque for post passes: If flippers are not falling fast enough for post passes and backhands, check the EOS Torque setting. A common error is setting it to 0.125 when it should be 0.275. This directly affects how quickly the flipper drops, essential for advanced flipper techniques. (rothbauerw, Die Hard Trilogy)

EOS Torque parameter corruption: The same VPX table file downloaded by different users can have different flipper EOS Torque values -- one correct, one corrupted. Fix by hard-coding the EOS Torque value in the table script to override potentially corrupted table property values:

LeftFlipper.EOSTorque = 0.275
RightFlipper.EOSTorque = 0.275

(apophis79, retrog33k, Iron Maiden)

Flipper return speed tuning: Key parameters for flipper return speed:

EOST=0.275 (EOS Torque)
EOSA=6 (EOS Angle)
FReturn=0.055 (Return Strength -- biggest effect on return speed)
EOSReturn=0.025

(apophis79, iaakki, Blood Machines)

Flipper angle tuning from video reference: For accurate flipper angles, overlay the VPX blueprint on PAPA video screenshots to compare positions. For Black Rose, 77 degrees (and -77 for left) was optimal after extensive testing. Too flat causes slings to feel slow and ramp shots to be unreliable. (sixtoe, apophis79, Black Rose)

Staged Flipper Issues¶

Staged flipper solenoid conflict: Williams sometimes repurposed secondary upper flipper solenoids for other mechanisms (like drop targets). If a drop target solenoid stops firing, check whether the staged flipper code is overwriting that SolCallback. Fix by commenting out the conflicting staged flipper solenoid callback lines. (apophis79, sixtoe, Defender)

Lighting and Visual Problems¶

GI (General Illumination) Issues¶

GI on/off logic inversion: If GI does not come back on after timed events, the logic may be inverted. Correct behavior: SetRelayGI 0 means GI is ON, SetRelayGI 1 means GI is OFF. (apophis79, Dr Who)

Static rendering blocking dynamic GI: Plastics with "static rendering" checked will not respond to dynamic GI changes -- lights below will not illuminate them during gameplay. Fix by unchecking "static rendering" on any primitive that needs to respond to GI. The tradeoff is that colors may appear washed out without static rendering's vibrancy optimizations. (iaakki, Bad Cats)

GI lightmaps not responding: After VPX updates, GI lightmaps can stop responding to control lights. This can be caused by lightmap opacity values being modified by script in a way that conflicts with newer VPX behavior. (apophis79, niwak, Guns N Roses)

GI not updating in VLM tables: If VLM table parts appear dark or untextured despite correct baking, the GI may not be hooked into the Lampz system. GI lightmaps need to be registered in Lampz callbacks to update properly. (flux5009, Iron Man)

GI blue stutter: Some frame stuttering when GI changes to blue (blacklight mode transition) is expected on tables with complex lighting setups. (bietekwiet, Big Bang Bar)

GI light intensity values: Check for GI bulbs set to extremely high intensity values (e.g., 500). Reduce to around 25. Light emission scale and range values should be around 4,000,000 each. A bloom setting of 0.1-0.2 can help reduce over-bright ball reflections. (o0skitso0o, Diner)

Light and Flasher Issues¶

Flashers staying on in standalone player: Update the flasher code to ensure complete off-state handling. The standalone player's VBScript engine handles flasher state transitions differently. (apophis79, Road Show)

DOF "fire hazard" -- GI staying on: If DOF solenoids or contactors fire continuously, the cause is often GI code copied from another table that sends DOFOn (persistent) instead of DOFPulse. Solenoid-related outputs should only use DOFPulse. Only flippers, start button lights, and RGB action buttons should use DOFOn. (skillman604, Game of Thrones)

Random lamp state corruption: The showstopper bug where lamp states randomly light up incorrectly (mode lamps lit at game start, inserts stuck on) is caused by controller.changedlamps not providing correct lamp states. Fix by setting UseLamps = 0 in the script. (iaakki, herweh, Indiana Jones)

Bumper/flasher initialization conflict: VPX can choke when bumpers and flashers initialize simultaneously, causing bumper lights to appear dark. Stage the initialization with a 100ms gap -- initialize bumpers first via a delayed timer, then flashers. (apophis79, Road Show)

LampFader array size mismatch: If VPX crashes on table load with LampFader/Lampz errors, check that array sizes in the Lampz class match the highest lamp number used. If lamps go up to 150 but arrays are dimensioned to 140, any lamp above 140 causes an array bounds error. (flux5009, Iron Man)

Insert Rendering Issues¶

Black inserts from static rendering: Insert primitives turn black when the static rendering flag is set. The issue appears in F5 (full play mode) but not F6 (play from editor). Remove the static flag from off-state insert primitives. (oqqsan, Die Hard Trilogy)

Black layer blocking insert visibility: Inserts not visible except from extreme angles indicate a black layer at Z-zero blocking the view. Create a NEW playfield material (not editing the existing "Playfield" material, which can reset). Ensure the material's Alpha is turned on and that insert lights have the correct image assigned. (benji084, iaakki, Spider-Man)

Frosted insert jagged edges: Light leak lines around insert text can be fixed by enabling Fast FXAA or increasing resolution. Brute force anti-aliasing also works but is more GPU-intensive. (benji084, brad1x, Bad Cats)

Skitso-style inserts require reflections: Skitso's insert technique requires "Reflect Playfield" to be enabled in VPX global video settings. When disabled, inserts appear as dark boxes. Inform users to enable playfield reflections. (o0skitso0o, rothbauerw, Monster Bash)

Transparent/ghost ball fix: Ghost ball issues are caused by insert primitives having wrong depth bias, settings, and materials. The diagnostic clue is the ball flashing on/off when a light flashes. The fix involves moving collidable rubbers to separate layers, filling ball-trap holes with proper walls (not relying on the plastics layer, which lets fast balls punch through), and removing duplicate GI that doubles up with toolkit renders. (sixtoe, Game of Thrones)

Shadow Problems¶

Ball shadows disappearing over holes: Ball shadows disappear when rolling over lane switch holes because the ball X/Y properties become undefined over playfield mesh cutouts. Solutions: remove the playfield mesh dependency and use an arbitrary invisible plane the same size as the playfield, or use alpha holes in the playfield image instead of mesh cuts (the TFTC method). (apophis79, rothbauerw, benji084, Hang Glider)

Giant ambient shadow bug: The ambient shadow can occasionally become enormous when ball Z values from wire ramps produce bad float values in the size multiplier. Comment out the shadow size-change code as a quick fix. (wylte, iaakki, Judge Dredd)

Hammer shadow Z-fighting: When two shadow primitives share the same depth value, they Z-fight visually. Fix by offsetting one slightly (e.g., change hammer shadow depth from 1.0 to 0.9). (sixtoe, Metallica)

Ball shadow disappearing after timer changes: When consolidating timers, the BallShadowUpdate call can accidentally be omitted. Verify it is included in the unified game timer. (embee1979, sixtoe, Taxi)

Ball shadow depth bias with flashers: Flashers at -1200 depth bias and ball shadows at -10 depth bias create artifacts. A white halo appears around the ambient ball shadow during flasher events. Workaround: hide ball shadows when large flashers are bright. This is a fundamental limitation of VPX's z-buffer when multiple transparent layers overlap. (iaakki, sixtoe, TFTC)

Rendering and Graphics Issues¶

Texture and Material Problems¶

D3DERR_INVALIDCALL texture error: The error Fatal Error: unable to create texture! D3DERR_INVALIDCALL at renderdevice.cpp is caused by playfield textures being too large for video memory (e.g., 4000x8822 pixels). Fix by turning down "max texture size" from "unlimited" in VPX settings, resizing the playfield image, or restarting VPX to clear video RAM. (iaakki, benji084, Indiana Jones)

Grey playfield in VPX 10.7: Common causes include using random 10.7 beta builds instead of the final release, crash-recovery corrupting table state, or loading tables from slow HDDs where the preloader fails. AMD GPUs (especially 6xxx series) can show depth buffer issues -- fix by deleting the VR cab bottom primitive. (iaakki, sixtoe, Indiana Jones)

VPX texture re-import limitation: VPX does not remove old images when re-importing textures. The old image remains in the table file, bloating its size. Manually delete old images from the Image Manager before re-importing. (Metallica)

Playfield image misalignment: When a new playfield scan is "squished" to fit an existing template, all elements become misaligned -- ramp exits hit wrong spots, lights and inserts are offset. Always verify playfield dimensions against manufacturer specs. Building on a dimensionally incorrect playfield (e.g., Data East Batman built at widebody dimensions when the real machine is standard) requires a complete rebuild. (ebislit, iaakki, sixtoe, Metallica; rothbauerw, Physics Debate)

Table file size and texture limits: VPX (32-bit) starts eating/dropping textures when table files exceed ~300MB. Optimization strategies:

Convert PNG to WebP format
Reduce pixel dimensions to match on-screen representation
Use 8-bit color when fine color detail is not needed
Remove alpha channels from textures that do not need transparency
Keep DMD assets external, not embedded in the table file
Use the Music folder (loads on demand) instead of embedding WAVs

One table was reduced from 650MB to 225MB after removing unused images. (apophis79, tomate80, daphishbowl, Iron Maiden)

Compressed vs Uncompressed Memory

VPX cannot use compressed images at runtime -- it must uncompress them into RAM first. A 300KB compressed texture can expand to 246MB in memory. The "Image Size (in table)" column in VPX's image manager shows actual memory usage, not the compressed file size. (apophis79, tomate80, WCS94)

Depth Bias and Layering¶

Depth bias controls the rendering order of overlapping elements. Issues arise when multiple elements compete for the same visual space.

Negative depth bias breaking ball trails: A negative depth bias on the playfield causes the playfield to render after the ball trail, making trails non-functional. (niwak, Johnny Mnemonic)

Death Star depth bias in VR: Negative depth bias values (e.g., -600) cause rendering issues in VR. Changing to positive values (e.g., +600) fixes VR rendering. (sixtoe, Star Wars DE)

Z-fighting on playfield primitives: Texture distortion on primitives at playfield level is caused by Z-fighting (two surfaces at the same Z height). Raise the primitive 1-5 VPX units above the playfield. (apophis79, clarkkent9917, Road Show)

Reflection and Transparency Issues¶

Under-playfield graphics bleed: Graphics under the playfield bleed through in both desktop and VR modes. Place a basic six-sided oblong primitive block under the playfield to stop the bleed. In VR this is essential as the player can see from any angle. Build this into the cabinet model and leave it enabled in all modes. (sixtoe, oqqsan, Earthshaker)

Transparent plastic double-face rendering: Some transparent plastics show decal imagery printed on both top and bottom faces, causing a blurred/doubled appearance. Root causes can include misaligned lightmaps, objects imported into Blender with unapplied rotations (fix with "Apply All Transformations"), and duplicate material nodes in the layer separator mask (fix via Outliner > Blender File view > right-click duplicate > "Remap Users"). (tomate80, benji084, apophis79, flux5009, sixtoe, niwak, Earthshaker)

Playfield transparency shader issues: If the playfield appears semi-transparent, the likely cause is a missing hole mask in the playfield shader. The hole mask (which defines alpha holes) is distinct from the insert mask (which defines insert vs wood areas). (frank_enste1n, metated, Warlok)

Plastic opacity alpha channel: If bulbs are visible through "solid" parts of plastics, check the alpha mask file. Dark brown areas instead of pure black for non-transparent regions will cause light bleed. The alpha mask must use pure black and white only. (flupper1, tomate80, Judge Dredd)

Normal Map Issues¶

Normal maps not working from all angles: Normal map effects can look correct from VR view but disappear from desktop POV. The effect changes dramatically with viewing angle. Normal maps need to be baked in the correct X, Y, Z position for rendering. (iaakki, embee1979, Metallica)

VPX 10.8 normal map regression: VPX 10.8 broke rendering on tables like Monster Bash. Root causes included incomplete normal mapping for tangent/object space in both DirectX and OpenGL, and tables that relied on a long-standing bug where texture transparency was ignored if material opacity was 1.0 (old workaround: set opacity to 0.9999). niwak pushed an automatic fix to VPX that corrects old tables on load. (niwak, hayjay., iaakki, Monster Bash)

VR-Specific Issues¶

VR Display Problems¶

VR playfield ghosting: Two playfields not aligned, visible during head movement. Fix by setting playfield reflection probe roughness to 0. Only visible in VR headset, not in preview windows. (apophis79, studly_do_right, Godzilla SEGA)

VR black screen with GL shaders: If the table works in 2D but shows a black/dark playfield in VR, the issue may be specific GL shader versions. Test with older shader versions to isolate. Many shader changes between versions 110 and 121 broke VR rendering for some tables. (rajojoey, niwak, uncle_paulie95, Twilight Zone)

VR performance degradation over time: Progressive frame rate drops in VR (smooth at start, unplayable by the 4th mode) can be caused by FlexDMD logging overhead. Fix by modifying the FlexDMD.log.config file to reduce logging. (astronasty, pinstratsdan, SpongeBob)

Pale/white playfield flashing in GL build: Occurs only in VPX GL build (not DX), triggered when ball goes above the playfield. Fix by disabling Max Ambient Occlusion. AO and SCSP should be off by default on toolkit tables. (oqqsan, apophis79, sixtoe, SpongeBob)

VR preview window blocking DMD: FlexDMD not showing in VR can be caused by the VR preview window overlapping the captured DMD area. Adjust preview window size in video settings via the table .ini file. The preview window takes the configured size even when disabled. (apophis79, niwak, dgrimmreaper, Defender)

VR Rendering Issues¶

VR black primitive bug: Material and image swapping on primitives causes them to go black in VR mode. The VR renderer handles texture loading differently than cabinet mode. Workarounds include rendering textures without alpha, using DL/color changes instead of image swaps, or maintaining VR-specific primitive versions. (iaakki, benji084, sixtoe, Indiana Jones)

Unshaded additive blend artifacts: VR display artifacts can be resolved by unchecking "Unshaded Additive Blend" under primitives in the CabLit layer. (dgrimmreaper, Big Bang Bar)

Static rendering causing floating lights: Lights that appear to float above their primitives in VR can be caused by static rendering. Check that materials/objects are set to "active" not "static." (Radical, Taxi)

Flasher dome Z-fighting in VR: Flasher domes show a black halo/line in VR when the lit primitive becomes visible. Two faces sharing exactly the same coordinates cause Z-fighting. No reliable fix has been found -- this is considered a long-outstanding VR engine bug. (sixtoe, Radical)

VR Component Issues¶

VR backglass shadow from raytraced light: A shadow appearing on the VR backglass when balls pass through certain areas is caused by a GI lightmap connected to a VPX light with "Raytraced ball shadows" enabled. Switch to a different light on the same GI string that does not have raytraced shadows. (apophis79, dgrimmreaper, No Fear)

B2S reels appearing in VR ceiling: B2S backglass elements showing up in the VR room ceiling are caused by having the B2S file in the same folder as the VR table. Move the B2S file or modify object visibility for VR mode. (studly_do_right, astronasty, SpongeBob)

VR apron line artifact: A visible line over the apron in VR is caused by the apron being made from a ramp instead of proper geometry. Remake the apron without using ramp geometry. (callev, sixtoe, Metallica)

LUTs in VR affect entire room: LUT color/brightness changes apply to the entire VR room (cabinet, walls, everything), not just the playfield. The room can strobe with LUT changes. Use the global GI flasher technique instead, which only affects the playfield area. (sixtoe, F14)

VR plunger animation: For proper VR plunger behavior, implement animation code in a dedicated timer:

Sub TimerPlunger_Timer
    ' Animate plunger pull and release for VR display
    ' Match plunger primitive position to actual plunger state
End Sub

(dgrimmreaper, mcarter78, Team One)

VR background issues: If the VR room shows background color through windows, set FSImage to none (not default) and ensure background color is pure black, not grey. (bhitney, mcarter78, Team One)

DisableLightFromBelow for VR sideblades: VR sideblades showing odd reflections in VPX 10.7+ can be fixed by setting "DisableLightFromBelow" to 1 on the sideblade primitives. (sixtoe, apophis79, Bad Cats)

Sound Issues¶

Sound System Problems¶

Bass.dll sound corruption: VPX 10.8 early builds had a bass.dll bug that corrupted table sounds when saved. Symptoms include flipper volume fluctuating or muting randomly during play. Once corrupted, the damage is permanent in that file. Always keep a backup before saving in early VPX 10.8 builds. (apophis, retro27, Ghostbusters)

WAV 32-bit float incompatible with VPX 10.7: WAV files saved as 32-bit float format do not play in VPX 10.7 final (they work in 10.7.2+). The sounds import but produce no audio, and the Sound Manager will not preview them. Fix by re-exporting WAV files as 24-bit signed integer in Audacity. Always use 24-bit WAV for maximum compatibility. (apophis79, iaakki, fleep1280, sixtoe, BOP)

Sound distortion from dual triggers: When a ball enters a hole from an angle that triggers both left and right sound triggers simultaneously, audio distorts. Solutions include using a single trigger with random sound selection, adding a wall to direct ball flow, or switching one trigger to a different PlaySound function. (clarkkent9917, sixtoe, Road Show)

R2D2 sound-per-frame bug: Placing a sound call inside a per-frame animation loop creates continuous buzzing. Change to a quieter sound effect or move the call outside the loop. (sixtoe, apophis79, Star Wars DE)

Audio Configuration¶

7.1 audio causing VPX stalls: VPX can stall or freeze when using 7.1 surround sound, particularly the "7.1 Enhanced" option. The game pauses as if alt-tabbed, and pressing the flipper button unfreezes it. Try regular 7.1 mode instead of Enhanced. This primarily affects cabinet setups. (astronasty, Blood Machines)

WAV vs MP3 rules:

Music/background audio: Use MP3 to save space
Sound effects needing positional audio or deformation (pan, frequency shift): Must use WAV
Table mechanical sounds: Always WAV
Callouts played at fixed volume/pan: MP3 works
SSF effects: Require WAV

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

Ball rolling sound volume: After implementing Fleep sounds, ball rolling sounds can become much louder than expected. Reduce the sound multiplier and add a velocity threshold (ballvel > 2) so very slow movement produces no rolling sound. (oqqsan, goill773, MF Doom)

SSF (Surround Sound Feedback) Issues¶

SSF positional audio not working: Some Fleep sound calls may use basic PlaySound instead of positional PlaySound. Check each call individually. Also verify that MP3 format is not being used for SSF samples -- convert to WAV if issues persist. (astronasty, apophis79, thalamus, Maverick)

SSF bass triggering accelerometer: Excessive bass in SSF sounds (~50Hz and below) can trigger the accelerometer/nudge sensor, causing unintended ball movement. Fleep Rev02 rebalanced sub frequencies across mechanical sounds. Reduce the ShakerIntensity setting or manually adjust volume for the most problematic sounds (usually the reactor/motor sound). (bietekwiet, fleep1280, TNA)

SSF feedback changes between versions: If pop bumpers and slingshots lost their heavy thudding SSF feedback, check the dedicated volume levels for bumpers/slings in the table script. The sound package may have been changed between versions. (joepicasso, Blood Machines)

ROM and Controller Issues¶

ROM Problems¶

ROM resets during games: ROM resets are generally not a VPX table-level issue. VPX only passes switch inputs to VPinMAME. If resets occur, the issue is at the ROM/VPinMAME level and would also happen on a real machine. (sixtoe, bountybob, Dr Who)

Updated ROMs required: Some ROMs were updated in PinMAME releases (e.g., Doctor Who parent ROM in PinMAME Christmas 2020). Using old ROM sets with the wrong sound ROM causes PinMAME to not load sounds. Re-download the ROM. (sixtoe, Dr Who)

Gottlieb System 1 ROM requirements: Gottlieb System 1 tables (like Count-Down) require redumped ROMs with the corrected A1752CF spider chip. Old ROM sets have the wrong sound ROM. Download updated ROMs from the PinballNirvana forums. Requires VPinMAME v1122 or later. (dgrimmreaper, carny_priest, Count-Down)

Gottlieb System 3 NVRAM: All Gottlieb System 3 tables need a preset NVRAM file. Without it, ball count problems occur and the table will not accept coins. The NVRAM pack (bally_6803_gts3_nvram.zip) is required. (gedankekojote97, primetime5k, Street Fighter 2)

DMD stuck on logo screen: If the DMD shows the game logo but does not animate, check: (1) DMD Extension must be in the VPinSPA folder, not the main VPinMAME folder; (2) Freezy version compatibility (recommend 1.71 or 1.10.2+). (wrd1972, retro27, Ghostbusters)

Data East ROM -- ball not releasing from trough: GNR VPW requires VPX 10.8 Beta 5 minimum (build 1347+) and VPinMAME 3.6. Using older versions causes flippers not responding and balls not releasing. (stavcas, colvert, Guns N Roses)

VPinMAME Setup Issues¶

VPinMAME vs PinMAME confusion: VPinMAME (DLL used by VPX) and PinMAME (standalone EXE) are separate components. Installing PinMAME when you need VPinMAME causes tables to fail -- ball will not release, version shows as old. VPinMAME.dll should be in the VisualPinball folder. PinMAME.exe is used for ROM auditing and sound ripping, not for playing tables. (tomate80, apophis79, Street Fighter 2)

PinMAME directory corruption after VPX update: If tables fail to load properly after a VPX update (all lights on full, configs lost, DMD may still work), try deleting the PinMAME directory and letting it regenerate. (sixtoe, apophis79, T2)

Missing PulseTimer breaks ROM communication: If a table will not accept coins or control drop targets, check for a missing PulseTimer object. The timer with specific settings is required for VPinMAME communication. (apophis79, Flash Gordon)

PWM solenoid regression (System 11): VPinMAME regressions have caused System 11 switched solenoids to not turn off properly when using PWM. This is dangerous for cabinet users where physical solenoids can overheat.

Cabinet Safety

Always use hardware-level solenoid release timers (via Pinscape, PinOne, or solenoid saver) as a safety measure, regardless of software state. A software bug should never be able to cause physical damage. (robbykingpin, sixtoe, bhitney, Space Station)

AltSound/GSound Setup¶

Copy the folder to VPinMAME/altsound/<ROM_name> and set sound mode to 1 in the F1 menu.

Sound modes:

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

Mode 2/3 will hang on 64-bit without PinSound software running. If altsound does not work after updating, delete the ROM's registry entry. Old altsound.ini files from early AltSound 2.0 testing are not backwards compatible -- delete and let the system regenerate. (mrgrynch, sixtoe, idigstuff, primetime5k)

DOF and Controller Integration¶

DOF registry causing table freezes: Table freezing at GI-on can be caused by DOF-related registry entries. Clean up DOF entries in the Windows registry. DOF runs as a service and can corrupt even on clean VPX installs. (sixtoe, Radical)

DOF with custom controller.vbs: Ensure DOF calls use the correct format. DOFPulse for solenoid effects, DOFOn only for persistent states. (Die Hard Trilogy)

PWM UseVPMModSol=2 stuck solenoids: Setting Const UseVPMModSol = 2 (PWM mode) causes erroneous DOF solenoid activation at table startup. Switching to UseVPMModSol = 1 resolves it. Diverter solenoids (S21, S22) should be removed from DOF configs as they stay active during gameplay. Safety measure: DOF configs can include MAX duration values:

S5 MAX100    ' 100ms maximum run time
S10 m1000 MAX6000  ' 1000ms minimum, 6000ms maximum

(apophis79, wrd1972, terryred, F14; bhitney, apophis79, Space Station)

B2S causing DOF freezes: B2S backglass service can start writing 10MB/s to disk even without a B2S file present, causing freezes. This happens when DOF GI controls trigger. Disable DOF lines calling GI in the script. (iaakki, sixtoe, Spider-Man)

Script Errors¶

VBScript Runtime Errors¶

Division by zero in COR calculation: When cor.ballvel returns zero, the COR calculation divides by zero. Quick fix:

RealCOR = BallSpeed(aBall) / (cor.ballvel(aBall.id) + 0.00000001)

(apophis79, iaakki, Taxi)

Variable undefined PI: nFozzy physics code requires PI to be defined. Add this constant to your script:

Const PI = 3.14159265358979

(benji084, rothbauerw, Radical)

BallCor/division by zero on launch: Tables using nFozzy physics sometimes throw "Division by zero" or "BallCor collision" errors on launch. This relates to the RDampen timer and captive ball initialization. If there is no RDampen timer, the table will never launch. When it launches intermittently, it is likely the captive ball issue -- ball collisions detected before table initialization completes. (benji084, iaakki, sheltemke, Maverick)

Null error in NF flipper SpoofBall class: Intermittent null errors occur when the unhit event does not fire on a flipper trigger (e.g., ball drains through center, or ball destroyed during multiball). The error appears on the next flip. (rothbauerw, iaakki, apophis79, Taxi)

CoRTracker out of range: If the cor tracker throws "out of range" errors, check captive ball array access for bounds checking:

If mechpos < 5 Then mechpos = 5
If mechpos > UBound(mechArray) Then mechpos = UBound(mechArray)

(rothbauerw, Monster Bash)

AudioPan and AudioFade CSng error: Ensure sound functions use proper type conversion. (Ghostbusters)

High score overflow (CLng vs Int): Scores exceeding ~2.4 billion cause the game to fail loading next time due to corrupted high score data. The CLng function overflows at large values. Fix by changing CLng to Int in the high score loading code. (oqqsan, primetime5k, SpongeBob)

Script Logic Bugs¶

Duplicate timer sub detection: VBScript silently uses only the last defined sub when duplicates exist. The first sub's logic is completely ignored. Periodically run a duplicate-sub checker on your scripts, especially as tables accumulate code from multiple developers. (apophis79, Goonies)

VUK switch sequence bug: If a VUK keeps kicking repeatedly, check the switch sequence code. Common issues include a missing Exit Sub after the step counter reaches 0, causing the sequence to only execute once until table restart. The step counter increment should be at the top of the sub, starting with case 1 instead of case 0. (cyberpez, oqqsan, iaakki, TFTC)

SwordMask infinite loop (multi-game state leak): A random selection loop can freeze the game if the bitmask tracking collected items is not reset between games and not properly preserved between players. Once all items are collected across any combination of players/games, the random selection loop never finds an uncollected item. Fix: (1) Reset bitmask on new game; (2) Properly save/restore bitmask in PlayerState; (3) Replace retry-random with linear scan from random starting index, guaranteeing termination:

' Instead of: Do While already collected, pick random
' Use: Start at random index, scan linearly
startIdx = RndNbr(8) - 1
For i = 0 To 7
    checkIdx = (startIdx + i) Mod 8
    If Not IsCollected(checkIdx) Then
        selectedSword = checkIdx
        Exit For
    End If
Next

(bhitney, donkeyklonk, Game of Thrones)

Fader error from out-of-sequence testing: When testing subroutines via the debugger out of normal sequence, fader errors occur that require killing VPX. Disable both lamp timers before exiting to close cleanly. (scampa123, iaakki, Die Hard Trilogy)

Const vs Dim for script options: Using Const for variables that need runtime modification (like CabinetMode) causes errors when VR mode tries to reassign them. Use Dim instead:

Dim CabinetMode
If VRRoom = 1 Or VRRoom = 3 Then
    CabinetMode = 0
Else
    CabinetMode = 1
End If

(leojreimroc, sixtoe, TFTC)

Script Performance Issues¶

Debug.Print performance impact: A single uncommented Debug.Print statement in a frequently-called sub can cause noticeable stuttering. Debug.Print writes to both console and log file each frame. Always comment out debug prints before release. This was the root cause of the Guns N Roses v1.0.2 performance regression. (apophis79, Guns N Roses)

Duplicate cor.update calls: Having cor.update called in multiple timers (e.g., both the game timer and a separate physics timer) wastes CPU cycles and can cause physics inconsistencies. Consolidate to a single timer. (MF Doom)

Global VBS script conflicts: Namespace conflicts between table scripts and old global VBS plugin files (e.g., globalplugin.vbs) can cause errors during specific game events. Delete or rename conflicting files in the VPX scripts folder. (soundscape2k, Iron Maiden)

VBScript standalone syntax issues: Dangling : Else statements with no following instruction trip the standalone script engine. Ensure all Else clauses have instructions. Also, mixed line endings (CRLF and LF) from copy-pasting code from different sources can cause strange behavior on non-Windows platforms. (jsm174, somatika, Starship Troopers, Defender)

DMD and Display Issues¶

FlexDMD Problems¶

FlexDMD "Object required" error: This typically means the FlexDMD asset folder (e.g., <tablename>.FlexDMD) is missing from the Tables directory. The VPX file and FlexDMD folder are separate downloads. (skillman604, wylte, Game of Thrones)

FlexDMD race condition: FlexDMD can crash with "Could not find file" errors during multiball when multiple DMD scenes fire rapidly. This is a race condition in scene creation that is not reproducible on demand. Do NOT add fallback PNG files as that masks the root issue. (bhitney, .thalamus, Game of Thrones)

FlexDMD version confusion: FlexDMD and Freezy DMD are separate components. FlexDMD must be installed separately from Freezy. If a table errors on FlexDMD, set UseFlexDMD = False in the script or update FlexDMD. (studly_do_right, Defender)

FlexDMD not appearing on cabinet: De-register and re-register both 32-bit and 64-bit FlexDMD versions. Get the latest release and reset the registration. Order of 32/64-bit installation does not matter. (sixtoe, tomate80, SpongeBob)

FlexDMD VR exit error: Exiting in VR mode throws a FlexDMD error because VR terminates FlexDMD before VPX tries to clean it up. Add a check in the exit routine:

If Not FlexDMD Is Nothing Or VRRoom = 0 Then
    ' Clean up FlexDMD
End If

(iaakki, oqqsan, VPW Example Table)

FlexDMD lag vs PupDMD: FlexDMD can be unable to keep up with fast update timers. For tables that heavily use video DMD content, PupDMD is strongly preferred. Keep FlexDMD implementations simple (static images only) to avoid lag. (soundscape2k, daphishbowl, Iron Maiden)

PuP Display Issues¶

PuP micro-stuttering: Common causes include:

Continuously updating scores/player names in the PuP update routine even when values have not changed (only update on change)
Using clear.png to hide images instead of setting label visibility (visibility toggle is most efficient)
PUP video files not optimized -- run through ffmpeg at 30fps, no audio, HD resolution to reduce from 2.65GB to 1.1GB with no visible quality difference

(daphishbowl, donkeyklonk, apophis79, Die Hard Trilogy; soundscape2k, terryred, Iron Maiden)

PuP INI file preventing display: If PuP displays do not appear at all, check for a pinupplayer.ini file in the PuP pack folder. This INI contains screen positions hardcoded for a specific cabinet setup. Delete or rename the INI file and let the PuP pack's screens.pup file handle display assignment. (retrog33k, iaakki, MF Doom)

PuP not closing on table exit: Traced to Controller.Stop being commented out in table1_exit. Ensure these lines are present and uncommented:

Sub Table1_Exit
    If B2SOn Then
        Controller.Stop
    End If
    Set PuPlayer = Nothing
End Sub

(merlinrtp, apophis79, kemurro, MF Doom)

PinUP Display crash on second table load: PinUP processes (PinupDisplay and pinupPlayer) get stuck in the task manager after the first run. Kill those processes to restart without a full reboot. Turn off "full screen exclusive" in VPX to reduce the issue. Adding Set PuPlayer = Nothing in the exit sub helps release the COM object. (kev_v, daphishbowl, terryred, Iron Maiden)

Orbital PuP framework slow loading: Tables using the older Orbital PuP framework can take 1-5 minutes to load. Update to the latest PinUp Player version, which handles legacy Orbital init calls much faster. Some Orbital-style PuP packs only work with 32-bit VPX. (iaakki, donkeyklonk, MF Doom)

B2S Backglass Issues¶

B2S DLL vs EXE mode -- ball stutter: B2S running in DLL mode causes ball stutter on some tables. Switching to EXE mode eliminates it. If experiencing constant ball stutter with solid FPS, check B2S mode first. (sheltemke, jarr3, jlouloulou, BOP)

B2S "Run as EXE" causing FlexDMD focus loss: When B2S is set to "Run as EXE" mode, it can cause FlexDMD tables to lose focus (playfield goes blurry). Disable "Run as EXE" in B2S settings. For FlexDMD debugging, check FlexDMD.log and DmdDevice.log. (astronasty, niwak, Blood Machines)

B2S backglass not lighting with PWM: When using UseVPMModSol=2, B2S backglass lights do not illuminate because B2S needs to translate 0-255 PWM values into binary lamp states. This was fixed in later B2S versions with a threshold of 64. (sheltemke, passion4pins, apophis79, No Fear)

B2S service activating without file present: The B2S service starts even without a .b2s file, writing 10MB/s to disk. Removing the file does not help -- disable DOF script lines (GI DOF control) instead. (iaakki, Spider-Man)

B2S performance issues: B2S can cause frame spikes and stuttering. Enable "Start this backglass in Exe mode" to run it in a separate process. Increase skip frames from default to higher values if needed. (oqqsan, iaakki, Radical)

Backglass interfering with GI/LUT: DirectB2S can interfere with GI and LUT behavior at startup. Try removing the backglass and using a static image instead. (ebislit, Black Rose)

Mechanism and Toy Issues¶

Drop Targets¶

Drop target bricking not disabling: If DTEnableBrick=0 is not fully disabling bricking, the DTCheckBrick sub may be using ObjRotZ instead of RotZ for orientation, causing perpendicular velocity calculations to be wrong. Move values from ObjRotZ to RotZ. (gtxjoe, rothbauerw, Hang Glider)

Roth drop targets require timer: When implementing Roth drop targets, the DropTarget Animate call must be in a timer. Without the timer, the primary collidable gets set to 0 instead of 1 at startup. This is the first thing to check when DTs are not working. (fluffhead35, apophis79, Diner)

Drop target texture appears black: When copying a drop target primitive from the example table and assigning a new texture, if it renders black, check the material assignment. A ball shadow material accidentally applied to the drop target is a common cause. (kev_v, sixtoe, No Fear)

Drop targets not working after toolkit update: After importing a new batch with an updated toolkit, some primitives need rotation to function. Verify rotation values on drop target primitives after toolkit updates. (apophis79, Last Action Hero)

Drop target popping ball off table: Drop target scripts that kick the ball up during reset can occasionally pop the ball off the playfield. A glass simulation would fix this but is rare and considered acceptable. (pinstratsdan, Defender)

VUKs and Kickers¶

VUK trapdoor Z-threshold bug: If a ball fails to trigger a VUK trapdoor, check whether the ball actually reaches the required Z height. Debug the actual ball Z position rather than assuming theoretical values. A ball reaching Z=109.72 will fail a > 110 threshold check. (sixtoe, apophis79, Scared Stiff)

VUK switch sequence bug: See the Script Logic Bugs section for the detailed fix on switch sequence counters. (cyberpez, oqqsan, iaakki, TFTC)

GetBalls LOB value breaking VUK: The InRect function may skip ball index 0 (assuming it is the captive ball), but the ball in the VUK can sometimes become index 0. Ball indices in GetBalls change unpredictably. Set lob=0 so no balls are skipped. (apophis79, iaakki, TFTC)

Two balls in scoop causing rocket-launch eject: When two balls enter a scoop simultaneously, the kicker can eject with extreme force. Adjust kicker physics settings, radius, or add switch timing to reject the second ball. (pinstratsdan, apophis79, Last Action Hero)

Crate door bounce-back: If a door mechanism bounces the ball back instead of capturing it, add a velocity-killing wall behind the door that activates when the door opens. This absorbs the ball's momentum for clean capture. (sixtoe, Scared Stiff)

Complex Mechanisms¶

Ball lock impact crash: Crashes when a ball hits a locked ball can be caused by errors in wall hit subs (e.g., sw76wall_hit). Add proper error handling and null checks for ball collision events. (DarthVito, rothbauerw, Dr Who)

Captive ball bouncing on its own: Captive balls bouncing when the table is idle indicates overcomplicated captive ball physics. Rebuild with a simpler approach. VPX balls should rest on VPX walls, not primitives, for stable behavior. (iaakki, sixtoe, bord1947, Metallica)

Captive ball dislodging via debug mode: Debug Mode that teleports balls to flippers can unintentionally affect captive/Newton balls. Exclude captive balls from debug ball-move functions. (daphishbowl, Iron Maiden)

Deadworld disc release delay: The ball in the Deadworld mechanism may not release for ~30 seconds (disc keeps spinning). This can be caused by a missing "fake search" animation where the ROM performs search behavior that VPX does not display, making it look stuck. (Deleted User, sixtoe, Judge Dredd)

Magnet behavior at low FPS: VPX magnets behave differently below 30 FPS -- they lose their grip on balls. The physics simulation steps become too coarse for magnets to maintain hold. This is a fundamental limitation. (iaakki, Blood Machines)

Performance Issues¶

Frame Rate and Stuttering¶

Windows Real-Time Protection: This is one of the most common causes of micro-stuttering in VPX. It can cause drops even when the FPS counter shows high/stable frame rates, and it turns itself back on automatically after being disabled. Windows Defender's real-time protection scans VPinMAME/VPX communications, especially impacting tables with modulated flashers that make many calls between VPX and VPinMAME. (astronasty, apophis79, rothbauerw, sixtoe, Die Hard Trilogy, Indiana Jones)

Always Check Windows Defender

When experiencing performance issues, always verify that Windows Real-Time Protection has not re-enabled itself. In later Windows versions, the "script paranoia" check cannot be turned off normally -- you may need to fully disable Defender.

Frame Pacing vs VSync: Frame Pacing mode in VPX can cause stuttering on some tables while VSync runs smoothly on the same hardware. This can be table-specific. The GL version of VPX often does not work well with Frame Pacing. When diagnosing performance issues, try switching between Frame Pacing and VSync before investigating table-specific causes. Frame Pacing goes bad when framerate cannot be maintained; VSync degrades more gracefully. (apophis79, tomate80, Lethal Weapon 3; pinstratsdan, Medieval Madness)

Light update loop optimization: Frame drops linked to light index lookup functions using loops instead of direct index access. Change loop-based light lookups to direct index lookups. Stutter that correlates with PUP media playing during light update calls confirms the source. (apophis79, daphishbowl, Iron Maiden)

VLM nestmap texture stutter on first load: First-time stutter when hitting bumpers/flashers is caused by lazy GPU texture loading of large nestmap textures. Fix with a preloader that briefly activates flasher callbacks during table_init to force GPU texture loading. Better solution: create small hidden objects inside the apron for each nestmap, visible by default, then toggle off after a delay. This was eventually included in the toolkit's export script. (niwak, iaakki, Iron Man)

Progressive stuttering from colored DMD ROM: Colored/colorized DMD ROMs can cause progressive stuttering due to memory leaks in the colorization, which is not fixable at the table level. If experiencing progressive frame drops, test with the standard (uncolored) ROM. (pinstratsdan, Medieval Madness)

Memory Issues¶

VPX 32-bit memory limitations: VPX running in 32-bit mode has severe memory limits. When memory is exhausted, textures get silently downscaled or go missing. In VPX 10.7+, a warning dialog appears when the table fails to load fully. Saving after this occurs permanently degrades the textures in the file. Use 64-bit VPX for complex tables, especially VLM toolkit tables. (niwak, iaakki, Iron Man)

Out-of-memory on repeated launches: VPX leaks memory from table to table and play to play. Heavy tables need VPX freshly started. Symptoms include blurry (downsized) images and white areas where textures dropped entirely. Check image manager for "downsized" markers. Always end-task residual VPX processes in Task Manager. (iaakki, tomate80, niwak, sixtoe, Indiana Jones, X-Men)

VRAM usage at 4K: At 4K resolution, VPX tables can consume 3+ GB VRAM (vs 1.4 GB at 1080p). VPX may convert compressed textures to uncompressed in memory regardless of on-disk format. Focus optimization on pixel dimensions rather than compression format. (terryred, Iron Maiden)

x86 vs x64 on toolkit tables: Toolkit tables (X-Men, Iron Man, Twilight Zone) are designed for x64 VPX. x86 has a 4GB address space limit that is too small for high-res lightmapped textures. The 4GB patcher is useless (VPX exe is already marked for it). (niwak, X-Men)

GPU and Rendering Performance¶

Refraction probes performance impact: SSR (Screen Space Reflection) probes significantly impact performance. On a 4060Ti at 4K: SSR probes = ~82fps, disabled/Plane Reflection probes = ~120fps. To disable without deleting: change probe type from SSR to "Plane Reflection Probe" which effectively unassigns them. (apophis79, redbone615, darthvito, Guns N Roses)

Removing ramp refractions: Disabling ramp refractions can drop GPU load from 100% to 90% on a GTX 1060 at 4K 60Hz. In Render Probe Manager, set the ramp's Plane Reflection probe Max Quality to "Disabled." (iaakki, Johnny Mnemonic)

VLM flasher lightmap polygon count: Wire ramps in the Parts collection cause flasher lightmaps to reach 200K-500K polygons, causing stuttering when flashers activate. Each flasher creates its own copy of the Parts lightmap mesh. With 5 flashers at 500K polys each, 2.5M polys are alpha-blended simultaneously. Linked flashers (firing together) should share a single lightmap. Reduce wire ramp polygon count via merge-by-distance. (apophis79, sixtoe, tomate80, Lethal Weapon 3)

Transparent objects dominating VR frametime: Performance profiling on BOP showed transparent objects consuming 50-65% of frametime. Removing screws (144 polys each, 78 total) showed significant stability improvement. First-time flasher firing causes texture loading stutter -- implement a preloader. (iaakki, rothbauerw, BOP)

Non-collidable primitives should be "toys": Primitives not marked as "toys" in VPX still get processed in collision detection even if set to non-collidable, wasting CPU. Always check the Toy flag on decorative primitives. (djrobx, Star Wars DE)

Computer sleep interrupting renders: Long VLM renders (3+ hours) can be interrupted by Windows sleep. Use Windows PowerToys "Awake" utility or adjust power saving options. (tomate80, fluffhead35, Iron Man)

Switch and Trigger Issues¶

Switch Detection¶

Opto switches need inverted logic: Opto switch logic is sometimes inverted compared to regular switches. If a VUK or subway mechanism is not behaving correctly (ball not held, or kicking out immediately), try swapping the switch assignments. (apophis79, sixtoe, No Fear)

Overlapping switches prevent magnets: If magnet triggers and switch triggers overlap in the same physical space, magnets may not fire at all. Separate the overlapping positions. (sixtoe, No Fear)

Wire switch surface assignment: Elevated switches on ramps need their surface property assigned to the correct wall that defines ramp height. Switches near playfield level work without surface assignment, but elevated switches require it. Also check that switch animation direction is correct (e.g., BP.rotx = -a vs BP.rotx = a). (rothbauerw, nestorgian, benji084, Bad Cats)

Trigger Configuration¶

Trigger shape "None" causes ball fall-through: VPX triggers with shape set to "None" can cause balls to fall through ramps. Changing to "Star" shape eliminates the problem. "None" shaped triggers can also be very off-center from their actual trigger zone. This is a VPX bug. (sixtoe, niwak, No Fear)

Trigger shape "None" only fires once: VPX triggers with shape "None" may only fire their _hit sub once. Workarounds: change shape to "Star" (fires correctly every time), or keep "None" but increase hit height to 150. (fluffhead35, sixtoe, Road Show)

Trigger hit height behavior: Hit height 150 on "None" type triggers matches how flipper triggers work. While high hit height could theoretically trigger from overhead balls, this has not been observed in practice. (Road Show)

Game Logic Bugs¶

Mode and State Issues¶

Wizard mode state reset: If wizard mode conditions are not properly reset between games, modes can break or become permanently inaccessible. Always reset all mode state variables on game start. (Die Hard Trilogy, Goonies)

Mission start prevention during multiball: Mode-starting mechanisms that are not properly locked out during multiball can cause overlapping game states. Ensure mode-start conditions check for active multiball. (Blood Machines)

Tilt breaks game completely: If tilting causes a complete game break, check the tilt handling code for errors in tilt relay logic or script error handling. (apophis79, mcarter78, Time Fantasy)

Multiball Issues¶

Ball save on scoop eject deaths: Scoop ejects can cause unfair drains when the ball hits the back of a flipper. Add a 2-3 second ball save on scoop eject. Stop and restart the ball save timer on each eject for exact timing. (oqqsan, astronasty, SpongeBob)

Lost ball after multiball: When balls disappear after multiball, the autoplunger may be too weak, causing balls to stack in the shooter lane. Increase autoplunger force (e.g., from 55 to 95). (iaakki, Metallica)

Double ball in plunger lane: Often caused by Narnia ball recovery placing balls in the drain. See the Narnia Ball Recovery section. (apophis79, sixtoe, wylte, Road Show)

Gottlieb System 3 trough issues: The Gottlieb System 3 trough is unusual -- a 3-ball trough with only two switches and a two-stage gravity-fed kicker. Switch 31 should rest on the last ball of the stack, not on the ball before release. Incorrect trough configuration causes multiball ball count issues. (apophis79, sixtoe, gedankekojote97, Street Fighter 2)

Scoring Issues¶

Negative score bug: Scores going negative can be prevented with an Abs() workaround. (Goonies)

High score overflow crash: See High score overflow (CLng vs Int) in the Script Errors section. (oqqsan, primetime5k, SpongeBob)

Blender and Toolkit Issues¶

Toolkit Baking Problems¶

Blender crash during bake (plastics): Crashes on specific plastic objects are often caused by the "Apply Decal - NoExp Node" modifier. Workaround: change margin settings from "Adjacent faces" to "Extend" (may cause artifacts), lower margin size, or try a newer Blender version. (tomate80, niwak, flux5009, Game of Thrones)

Bake failures and path errors: When bake/nesting fails with path errors despite files existing, move the blend file to a different drive location and re-run. The issue may be related to file path length or special characters. (gedankekojote97, SpongeBob)

VLM baking requires Object Mode: VLM baking fails if Blender is in Edit Mode. Must be in Object Mode before pressing the render/batch button. Test with just the 'meshes' button first to verify the export pipeline. (flux5009, tomate80, Iron Man)

GPU denoising causes black renders: When GPU memory runs out during baking, the render completes but denoising fails, producing black/missing textures. Uncheck "Use GPU to denoise" in Blender render settings. (tomate80, WCS94)

Nestmap/batch failing from UV issues: Symptoms include inserts appearing black in VPX and UnderPF not rendering. Check UV maps in the blend file for missing or corrupted mapping data. (tomate80, flux5009, apophis79, Last Action Hero)

Blender toolkit export blocked by empty geometry: Objects with no geometry in the export collection will block the entire export. Remove or fix zero-geometry objects. (Scared Stiff)

Toolkit Object Issues¶

Coordinate system position bug: The toolkit can produce incorrectly positioned objects (upside down, wrong angle) due to left-hand vs right-hand coordinate system conversion. Workaround: manually adjust RotZ to 180 or modify position in VPX editor. The bug particularly affects lockdown bars, siderails, and button housings. Objects in the "movable collection" can be repositioned after bake without re-rendering. (niwak, rawd, Game of Thrones)

VLM subdivision modifier inflation: Missing NoExp suffix on Subdivision modifiers causes VLM mesh export to apply subdivisions, inflating polygon counts dramatically. One table went from 1.2M to 2.5M triangles. Diagnostic: compare VLM.Bake vs VLM.Results triangle counts -- a large jump indicates missing NoExp. Fixing this on one table reduced batch time from 11 hours to 4 hours and file size from 268MB to 222MB. (flux5009, apophis79, tomate80, Lethal Weapon 3)

VLM nestmap process hanging: The nestmap generation can hang when the Parts collection has too many connected faces. Split oversized Parts collections into separate collections (cab walls, light blockers, etc.) to reduce per-collection face counts. (flux5009, apophis79, tomate80, Lethal Weapon 3)

Nestmap memory exhaustion: Nestmap failing with "expected 'Image' type found 'Image' instead" means out of memory. Reduce nestmap size (8K to 4K), close all other applications, or split collections. (mcarter78, apophis79, cyberpez, Skateball)

Material and Rendering¶

VLM zero-power light corrupting lightmaps: A VLM light with power set to 0 in the Room collection causes all lightmaps to render incorrectly (overexposed/blown out) while bakemaps look fine. Delete or disable zero-power lights rather than leaving them at 0. (apophis79, Lethal Weapon 3)

GIOFF playfield appearing dark in nestmap: If nestmaps show a dark GIOFF playfield despite correct renders, add the GIOFF PF render to the nestmap manually in Photoshop. This is a recurring toolkit issue. (tomate80, Last Action Hero)

Emissive materials projecting through parts: Emissive materials can bleed light through objects behind them. Check material node settings for emission strength and ensure proper light blockers are in place. (Haunted House)

Layer separator material corruption: Layer separators rendering visible or not working are caused by wrong or corrupted material node setup. When joining plastics, remove extra stacked decal materials, keep one. Append materials from a known-working blend file rather than copying: File > Append > navigate to blend > Materials > layer.sep. (mcarter78, retroritchie, apophis79, Skateball)

Indirect light clamping zeroed: Renders showing extreme overexposure (no light in inserts/posts, everything glowing) are caused by Indirect Light Clamping in render settings being set to 0. Reset to 1.0 or higher. (mcarter78, apophis79, Skateball, Time Fantasy)

Blender version compatibility: Blender 4.1 is recommended for VLM baking. Newer versions have caused rendering issues (missing results, black textures). Blender 4.0 is also considered stable. Appending materials between different Blender versions (e.g., 3.4 to 3.2) causes materials to appear black/broken. (mcarter78, tomate80, apophis79, WCS94; iaakki, TNA)

System and Platform Issues¶

32-bit vs 64-bit¶

64-bit migration: No need to uninstall 32-bit VPX. Rename executables 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). (apophis79, sheltemke, BBB)

64-bit VPX benefits: Large texture VR rooms and PUP packs perform better on 64-bit due to eliminated memory limitations. Anti-aliasing (AA) is enabled by default in 64-bit VPX and can cause stutter with flashers -- disable it if experiencing issues. (iaakki, Blood Machines)

Big Bang Bar 64-bit crash: VPX 64-bit crash with EXCEPTION_INT_DIVIDE_BY_ZERO is fixed by updating to VPinMAME 3.6 beta which contains a specific Capcom crash fix. (rothbauerw, Big Bang Bar)

64-bit VPinSPA exit hang: 64-bit VPinSPA does not exit cleanly (dllhost.exe hangs). Brute force fix:

Sub Table1_Exit
    Kill32BitCOMSurrogate()
End Sub

(blamer/movieguru, Ghostbusters)

Standalone Player Issues¶

Segmentation fault from gBOT: 95% of ball-to-flipper seg faults in standalone are caused by allBalls = gBOT. Fix by changing to allBalls = GetBalls. The gBOT array is fine to use elsewhere, but in Cor.Update it can cause sporadic crashes due to Windows COM reference counting. (jsm174, apophis79, Defender, Road Show)

VBS Join() crash: Standalone VPX crashes when doing Join() where the first array element is empty (uninitialized). Manually concatenate instead of using Join. (somatika, jsm174, Defender)

Operating System Issues¶

False positive virus detection: VPX files are commonly flagged as Trojan:Win32/Wacatac.B!ml. This is a false positive. Verify clean via VirusTotal. VPX files cannot be signed to prevent this. (apophis79, iaakki, Big Bang Bar)

Windows locale decimal separator: Systems using comma instead of dot for decimal separator (e.g., European locales) can corrupt VPX parameter values. Entering 0.2 may result in 9.867855e-3. This also affects dmdext and pup-capture configurations. (iaakki, terryred, tomate80, Iron Maiden)

VPX decimal separator input: In VPX, entering a dot instead of a comma for decimal values can result in wrong values (25 instead of 2.5). You must tab or press enter after entering a value in the VPX editor or it may not save. (kev_v, No Fear)

Locale keycode issues: Spanish locale can cause keycode issues where keyboard presses register incorrectly (key 6 maps to 7, key 2 maps to 3). Try SetLocale 11274 (Argentina) instead of SetLocale 1033. (apophis79, tomate80, Street Fighter 2)

Anaglyph 3D empty LUT slot: Tables with an empty color grading LUT slot do not work with anaglyph 3D mode. Add a 1-to-1 (identity) LUT file. Minor performance impact. (tomate80, robbykingpin, Defender)

Ramp and Wire Issues¶

Ramp Physics¶

Ball stuck behind ramps: Balls getting stuck between ramp and wall, or jumping over targets into plastic areas. Fix by enabling collision on walls that were turned off and checking wall/ramp intersections. Decals can sit proud of ramp geometry, causing clips. (sixtoe, oqqsan, Spider-Man)

Ramp speed too fast: If ramps feel too fast after physics adjustments, adjust ramp friction or ramp primitive material settings. Test at multiple resolutions as rendering speed can affect physics feel. (iaakki, Metallica)

Ball under ramps: Balls bouncing under ramps and traveling back up subways can be prevented by adding one-way gates to subways and guard primitives under ramp edges. (daphishbowl, Iron Maiden)

Wire and Wall Issues¶

Wall intersecting ramp: Wall intersections with ramp geometry are caught in F6 debug view. Even small intersections can cause ball escape. (benji084, Police Force)

Ramp wall intersection ball escape: When enabling collision on walls, check if they intersect with ramp geometry. Ramp decals sitting proud of actual ramp geometry can cause walls to pop through even if they clear the decal visually. Needs collision testing, not just visual inspection. (sixtoe, Spider-Man)

Wire ramp texture brightness: Wire ramps appearing noisy/too bright (especially at 4K) can be caused by corrupt ramp textures plus DL multiplier set too high. Correct the texture and adjust DL multiplier to ~0.2. Hook DL to the GI system for dynamic adjustment. (sixtoe, bord1947, tomate80, Judge Dredd)

Primitive ramp normals -- ball passing through: Balls can pass through primitive ramps if mesh normals only face one direction. Add external faces along the upper portion of the ramp where balls might approach from the "wrong" side. Common with Blender-imported meshes where normals face outward but gameplay sends balls against the inner face. (sixtoe, WCS94)

Special Case Issues¶

Gate and Diverter¶

Gate ghost bouncing: For weird "ghost bounce" behavior near an outlane gate, set gate elasticity to 0.8 and move the gate slightly so the end overlaps with the physical post. Ensure the VPX gate orientation matches the physical prim alignment. (apophis79, Iron Maiden)

Gate positioning: Even 1 unit of gate positioning error can completely block ball flow. After changing metal post primitives, check that gate holders still have correct height and angle. (iaakki, sixtoe, Spider-Man)

Gate sounds from both directions: Gates missing sound when hit from the closed direction need triggers for hit sounds from both directions. Increase gate bounciness for proper ball rejection. (mcarter78, studly_do_right, Skateball)

Plunger Issues¶

Impulse plunger for kickbacks: Using a regular plunger instead of an impulse plunger for kickbacks causes intermittent failures and occasional double-fires. Replace with impulse plunger for reliability. (apophis79, Congo)

Launch ball stuck: Ball sticking at launch near kickout holes is usually caused by primitive-based collision geometry needing adjustment. Investigate all collidable primitives in the launch area. (apophis79, sixtoe, gedankekojote97, Street Fighter 2)

Ball trough not capturing: If the drain kicker is not capturing balls, check: (1) InitSw first parameter must be the drain switch number (not 0), and (2) the drain kicker must be enabled in VPX. (metated, apophis79, Quicksilver)

POV Settings Issues¶

POV causing ball loss: Modified POV settings, especially Z-scale values, can affect collision geometry and cause rare ball interaction bugs. When debugging rare ball behavior, always check if the player modified their POV. Removing the POV file can resolve persistent ball loss issues. (pinstratsdan, fluffhead35, tomate80, Maverick)

POV saving unintended settings: POV files save more than just camera position -- they can include render settings like ambient occlusion. Users may find AO enabled despite being set to OFF in table defaults. (tomate80, Sixtoe, Starship Troopers)

Table rotation in newer VPX: 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)

Nudge and Tilt¶

Digital nudge too weak: VPX digital nudge is effectively non-existent when all nudge values are set to 1. Increase the force value for noticeable nudge response:

' Too weak:
If keycode = LeftTiltKey Then Nudge 90, 1
' Better:
If keycode = LeftTiltKey Then Nudge 90, 5

(tastywasps, iaakki, Physics Debate)

Ball spin visualization: If ball spin appears excessive, press F11 twice to visualize actual spin. Textured balls make spin appear more pronounced than it is. Compare to the Example table to determine if behavior is normal. (merlinrtp, apophis79)

Debugging Tools and Techniques¶

Debug Log Viewing¶

Press D during gameplay to open the debug log
Must turn off Fullscreen Exclusive mode first for the debug window to appear
Use MsgBox to debug startup events (stops execution until OK is pressed)
vpinball.log captures all output but is noisy
Add Debug.Print statements temporarily for targeted debugging, but always remove before release

(mrgrynch, oqqsan, apophis79, SpongeBob)

VPX F6 Flying Camera¶

To get a free-camera view in VPX F6 mode:

Under Keys/Nudge/DOF options, enable "Enable Flying"
Hold Alt + arrow keys to move camera
Nudge keys rotate the view left/right

This allows inspecting the table from any angle including side views, useful for checking primitive placement and lighting from cabinet perspective. (astronasty, Blood Machines)

VPX Debugger in VR¶

The VPX script debugger does not function properly in VR mode. VR-specific issues cannot be easily tested without VR hardware. Use Debug.Print and log files for VR debugging. (sixtoe, Radical)

Finding Lamp and Solenoid Assignments¶

Use the All-in-1 Visual B2S tool to identify unknown lamp numbers. Run it as a normal backglass, watch lights flicker during gameplay to deduce lamp assignments. Useful for both lights and solenoids. Tool available at vpuniverse.com. (mcarter78, apophis79, Skateball)

VPReg.stg Settings Storage¶

Table option settings (from Flex/Magna menus) are saved in Visual Pinball\User\VPReg.stg. Inspect with 7-zip (right-click > 7-zip > Open archive). The file is read-only. If running VPVR from a subfolder, it creates its own User folder with separate settings that will not transfer. (apophis79, X-Men)

Performance Profiling¶

When FPS issues are hard to isolate, consider implementing a profiler that adds timestamp logging to the beginning and end of each sub to identify which routines consume the most time. (iaakki, sixtoe, Metallica)

VPinSPA (Stern Pinball Arcade)¶

Installation and Setup¶

VPinSPA is required for certain Stern tables (like Ghostbusters) that use a proprietary ROM format rather than standard VPinMAME.

Installation requirements:

Run the VPinSPA installer (one-time setup)
ROM files extract to C:\Visual Pinball\VPinMAME\spagb100
Install Visual Studio 2012 C++ redistributable (x86) -- required dependency
DirectDraw registry setting may need to be set to 1
If setup.exe reports "can't find VPinSPA.dll" even with the file present, install the VC++ 2012 redistributable or use an "all-in-one" VC++ runtime package

(iaakki, multiple, Ghostbusters)

VPinSPA DMD Extension¶

For altcolor DMD to work with VPinSPA:

Use Freezy DMDExt 1.71 specifically, or 1.10.2+ (not intermediate versions)
Place dmddevice.dll and dmddevice.ini in the VPinSPA folder (NOT main VPinMAME folder)
Altcolor files go in VPinSPA/altcolor/ subfolder
Name files: pin2dmd.pal and pin2dmd.vni
Remove .vni file if colors are incorrect (use .pal only)

(netzzwerg, Ghostbusters)

64-bit VPinSPA 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

System Stability Risk

This creates a DLL surrogate to bypass WOW64 protections. It may cause system instability or prevent software installation. It works for some users but fails to exit cleanly for others. (mike da spike, Ghostbusters)

VPinSPA CPU Usage¶

VPinSPA can max CPU (100%) on older systems (e.g., i5-3570K) even with all table objects and script removed except the controller. This is a known VPinSPA limitation. (rothbauerw, Ghostbusters)