Table Build Workflow¶

This guide covers the practical workflow of building and modding Visual Pinball tables, from project planning through release. These patterns represent hard-won lessons from dozens of VPW builds -- techniques refined across years of collaborative development on tables ranging from early solid-state Bally machines to modern Stern SPIKE recreations.

Starting a Build¶

Project Planning and Preparation¶

Every successful VPW table build follows a deliberate order of operations. The build order for a toolkit-era VPW table, as established during Godzilla SEGA development, proceeds roughly as follows:

Build the skeleton layout in VPX with correct geometry (walls, triggers, ramps, kickers)
Hook insert lights to ROM via vpmMapLights AllLamps
Add flashers with PWM mod support
Add GI lights
Add nFozzy physics and Fleep sounds
Model ramps, toys, and plastics in Blender
Configure Blender toolkit (light names, codes, insert setup)
Run a test batch (1k samples)
Import the batch into VPX and apply materials
Iterate with movable animations and scripting
Run the 4k production batch
Add options menu, VR room, and final polish

(tastywasps, apophis79, tomate80, Godzilla SEGA)

The key principle is that physics functionality must be established before visual enhancements. As sixtoe put it during the Street Fighter 2 build: build ramps physically correct in VPX first so they work at the right height, then use that as the basis for Blender work.

Use the Example Table as Authority

The VPW Example Table is a bag of tricks -- not a framework. It demonstrates standard VPW features in one place for copying into your own projects. Many small issues have been solved there that have not made it into documentation. Always pull code snippets from the Example Table rather than written guides, as the Example Table code is more current. (apophis79)

VPX Version Selection¶

When starting a new table, version selection matters. During the Die Hard Trilogy build, the team chose VPX 10.7 over 10.6 for access to Lampz and LightSequencers. The reasoning: since development would take months, the newer version would stabilize by release time. For tables requiring Lampz or LightSequencers, 10.7+ is mandatory. (oqqsan, astronasty, fluffhead35, apophis79)

VPX 10.7 Editor Issues

The 10.7 editor has significant authoring regressions: the editor window does not update on the fly, long filenames get truncated, the layer manager randomly locks up, and textures can be randomly removed. Some builders do all real work in 10.6, then convert to 10.7 at the end for WebP image support. (sixtoe, iaakki, fluffhead35)

Original Table Development -- Whitewood First¶

For original tables (not recreations of real machines), the development order is: whitewood layout first, then playfield art and game code in parallel. Do not bother coding gameplay until the whitewood is done. Get the flow, shots, and mechanisms working first. Use VPX ramps and walls to get everything playable before making 3D models. As oqqsan described the Die Hard Trilogy whitewood stage: "it will look bad but play okay." Score variables should be defined at the top of the script from the start to save refactoring time later. (astronasty, oqqsan)

Layout design tips for original tables:

Make center ramps wide enough to be hittable from both forehand and backhand
VUK angle of just 1 degree to each side controls where the ball goes
Replace hard-to-see top lanes with target banks that pop bumpers can hit
Add slingshots on dividing walls near pop bumper areas to increase ball action
Avoid putting lights or mechanisms on the apron -- oqqsan reported extensive trouble with this on Blood Machines

(astronasty, oqqsan, Die Hard Trilogy)

Building from Existing Tables¶

When starting a VPW mod from an existing table, the approach depends on the table's condition and age. For the No Fear VPW mod, kev_v based it on Ninuzzu's 1.1 version from VPU and implemented VPW standard features incrementally: nFozzy physics first, then Fleep sounds, dynamic ball shadows, Flupper domes, Lampz, 3D inserts, and finally the Blender toolkit. Each version was uploaded as a separate file for incremental review. (kev_v, sixtoe)

The recommended implementation order for VPW features on an existing table:

nFozzy physics (flippers, targets, drop targets)
Fleep sounds
Dynamic ball shadows
Flupper domes / flasher blooms
Lampz light fading
3D inserts
Blender Toolkit bake

(sixtoe, kev_v, No Fear)

When overhauling a legacy table, as sixtoe did with Road Show: strip all attributes, clear out the script, rearrange layers for clarity, build a real physical trough to replace DestroyBall kickers, and build real physical subways. The original Road Show used destroyball kickers throughout, all of which were replaced with physical devices. (sixtoe)

Working with Original Authors -- VPW Protocol

VPW protocol requires contacting the original table author first. Authors release under their own name, not VPW, unless they prefer otherwise. For Taxi, icpjuggla was contacted via VPForums and permission was confirmed before release. Always check with original authors early in the process. (benji084, sixtoe, bord1947)

Learning Projects¶

When learning the toolkit for the first time, choose a simple table. Sixtoe used Spectrum specifically because of its simple layout and lack of complex mechanisms. He originally wanted to do Godzilla first but recognized that the ramp complexity was too much for a first toolkit project. (sixtoe)

Table Dimensions and Scaling¶

Standard Dimensions by Manufacturer¶

Getting accurate dimensions early is critical for a ground-up build -- everything else (ramps, plastics, inserts) is built relative to the playfield. The universal standard for non-widebody tables is 20.25 inches wide. This has been the cabinet width since the 1960s; at 20.5 inches there would be no clearance to lift the playfield. (bord1947, apophis79, sixtoe)

Common dimensions in VPX units (1 VP unit = 1.0625 inches / 50):

Era / System	Width	Length	VP Units (W x H)
Standard non-widebody	20.25"	46"	952 x 2162
System 11 (non-widebody)	20.25"	42"	952 x 1974
Standard Bally (pre-merger)	20.25"	42"	952 x 1974
BSD (exception)	20.25"	45"	952 x 2118

(bord1947, sixtoe, benji084, Earthshaker, Medieval Madness, Police Force)

The VPX Dimension Manager is Inaccurate

The VPX Dimension Manager is famously inaccurate and should not be trusted for precise measurements. Always verify dimensions independently. (friscopinball, apophis79, Earthshaker)

Verifying Dimensions¶

The quickest validation that a playfield scan has correct proportions is the circle test: check whether bumper holes and other circular features are actually circular. If circles appear oval, the image is being stretched or has an incorrect aspect ratio. (apophis79, mcarter78, Stargate)

To calculate playfield dimensions from a scan file, divide pixel width by DPI. Be aware that scanner metadata may report incorrect DPI (for example, 300 when actually 600). The verification process:

Calculate dimensions from reported DPI
Import to VPX and check that bumper holes are perfectly circular
If circles are oval, dimensions are wrong -- adjust accordingly

For the Medieval Madness scan: 12168 pixels / 600 DPI = 20.28" width, extrapolated length = 46.03". The resulting VPX table used 952 x 2162 VP units. (apophis79, sixtoe)

Table Rescaling¶

When a table has been built at incorrect scale, rescaling is a major undertaking. The Starship Troopers table was originally built at approximately half scale (515 x 1154 VP units) and had to be rescaled to standard 20.25" width. The process required recalculating every coordinate, primitive position, wall placement, and physics value. (Eighties8, iaakki, apophis79)

Widebody Considerations¶

Widebody tables like Maverick (Data East 1994) require special attention. Maverick had a widebody prototype (25" x 51.75") but production was squeezed to standard cabinet (20.25" x 46"). Width and length were verified against a real machine. For VR rooms, the cabinet model needs resizing in Blender for widebody fit. (antisect, ebislit, tastywasps, sixtoe)

Dimension Correction and Realignment¶

When a playfield image is corrected to proper dimensions, ALL physical objects must be realigned. The old Black Rose playfield was "squashed" causing misalignment. The correction process:

Set correct editor dimensions (952 x 2162 for standard WPC)
Use marks and scratches on the raw scan as positioning guides
Realign every physics object (primitives, walls, triggers, ramps, switches) to match new playfield holes
Check that cannon holes (or other circular features) are circular, validating correct proportions
Verify ramps and flipper shots still work after realignment

This is labor-intensive but necessary. (sixtoe, endi78, sheltemke, Black Rose)

Playfield Construction¶

Playfield Scanning¶

Scanner recommendations: the HP ScanJet 4670 or 4600 (flatbed-style portable scanner placed face-down on playfield) works well for playfields but is not ideal for plastics (the glass layer interferes). For plastics, use a different scanner type or a flatbed if the plastics can be removed. (friscopinball, clarkkent9917, bord1947, devious626)

Scan settings and technique:

Always scan at 600 DPI in TIFF format (never JPG)
Start upper-left, scan rows left-to-right with significant overlap
Include wood edges in each scan for alignment reference
Professional stitching of scan segments produces far better results than amateur attempts

Earthshaker used a brand new CPR (Classic Playfield Reproductions) unpopulated playfield for scanning, providing pristine condition with no signs of wear. ClarkKent performed professional stitching of the scan segments. (friscopinball, clarkkent9917, Earthshaker)

Playfield scans are "worth their weight in gold," as skillman604 noted during the Game of Thrones build. The GoT playfield was professionally scanned on a full-size flatbed scanner in one pass. The upper playfield, lacking a scan, was done from a single stretched photo -- a far inferior result. Lesson: stitching is hit-and-miss; a single high-quality scan or photo under neutral lighting is far better. Always overlay the result against the blueprint from the manual to verify alignment. (skillman604)

Photography Setup¶

When scanning is not available, photography is the fallback. Use an iPhone 12 or similar (26mm lens) rather than a GoPro due to less barrel distortion. Key setup details:

Take a grid paper photo at the same distance as playfield photos to create a lens distortion profile
Use a crosshair frame cutout as reference for alignment (crosshairs 2 inches apart for skew/rotation/distance reference)
Camera rig (small table) keeps camera in the exact same plane for each shot
Avoid direct lighting -- use natural light bouncing off white walls to minimize glare
Overcast days are ideal for outdoor shots
For reference photos: low ISO (320) and slow shutter (1/50) to avoid blown highlights

(benji084, bord1947, ebislit, wylte, Police Force, Tommy)

Building Without a Scan¶

When no scan exists, the Last Action Hero approach works: create a photo stitch from high-quality web resources, then use AI upscaling to improve resolution. Always overlay against the blueprint from the manual. This produces results that are good enough to build from, though never as accurate as a proper scan. (tomate80)

Playfield Art Integration¶

For 4K cabinet displays, make the playfield image 2160 pixels wide. When exporting a blueprint at 4096 x 1804, scale to 4904 x 2160 for proper 4K width. DMD images do not need to be higher than 1080p. (astronasty, apophis79, Die Hard Trilogy)

Playfield art can be delivered as a layered PSD with separate inserts, shadows, and text layers. For Road Show, ClarkKent provided a Photoshop file with separate shadow layers, completely redrawn inserts in separate layers, and a text-only layer. For VPX table building, the text layer needs to be exported as a separate PNG. Insert cutouts need hard (non-anti-aliased) edges -- smooth edges cause jaggies with the VPX flasher method. (clarkkent9917, astronasty)

For playfield redraws, Police Force was redrawn at 3996 x 8820 (200% larger than original for crisp results). The redraw process: black outlines first, then color fills. This was brad1x's 4th Python Anghelo table redraw. (brad1x)

Playfield Mesh¶

A playfield mesh is essential for proper ball physics interaction. The mesh needs holes for subways, saucers, and VUKs. Put outlines on the playfield image where subway holes and saucer holes go so the mesh creator knows placement. (apophis79, Die Hard Trilogy)

Kicker Lip-Out

Switching kickers to use playfield mesh cutouts instead of solid surface allows the ball to lip out naturally, producing more realistic behavior. (gtxjoe, Police Force)

For VUK and scoop holes causing ball suspension issues, minimum subway depth should be lower than -75 (the playfield is approximately 24 units deep and needs room for a 50-unit ball). Use legacy mode for kicker settings. (wylte, bord, Tommy)

Ball shadow primitives placed at Z=0 cause Z-fighting (flickering) with the playfield surface. Fix: adjust the Z height of all ball shadow primitives to 1.01. This minor offset completely eliminates the artifact. (uncle_paulie95, Earthshaker)

Table Height and Truncation¶

Table height can be set shorter than standard to match a playfield scan's aspect ratio without distorting the image. Defender used a table height of 1968 (instead of standard 2000+) for this reason. When ramps extend beyond the playfield edge, the table boundary must extend to accommodate them (balls do not roll past the defined table boundary). Options: increase the table boundary with dead space at top (without stretching the playfield image), or use a hidden kicker teleport system. (apophis79, bord1947, gtxjoe, benji084)

Collidable Objects and Walls¶

Blender Collidables vs VPX Walls¶

After extensive testing, the VPW community generally recommends VPX walls for most physics objects, with Blender collidable primitives reserved for ramps and complex shapes. The Earthshaker team tested full-primitive collidables from Blender (as used in Haunted House) and reverted to VPX walls for most objects. The findings:

Pros of Blender collidables:

Perfect alignment with visual meshes
Reduced VPX setup work

Cons of Blender collidables:

Very difficult to tweak during physics tuning (requires round-tripping through Blender)
Hard to identify ball flow issues and fill gaps for ball traps
Normals affect ball collision -- reversed normals let balls pass through (red face = passable)
Most physics-tweaking contributors cannot easily work with primitives
Inlane/orbit exit wall adjustments dramatically alter table flow and need iterative tuning

Decision: Keep primitive collidables for ramps (where visual-physical alignment matters most), revert everything else to VPX walls. bord1947 endorsed 100% mesh physics only when the modeler is highly trusted. (sixtoe, apophis79, tomate80, bord1947, benji084, Earthshaker)

Collidable Primitive Grouping¶

Collidable primitives must be grouped by physics material type because VPX applies one physics material per primitive. The grouping:

Posts -- at corners of rubber bands, larger diameter
Pins/Pegs -- free-standing smaller posts
Rubber band middles -- stretched rubber between posts
Sleeves -- rubber sleeves over posts

Each group is a separate mesh in Blender. Posts should be modeled at the final rubber diameter (not bare post diameter). Slingshot walls must remain as VPX wall objects because they trigger leaf switches. Targets, bumpers, and gates remain as VPX objects. Individual cylinders should be separate primitives (not merged) so physics materials can be tweaked per-object. (bord1947, sixtoe, apophis79, tomate80, Earthshaker)

Lane Guides and Inlanes¶

Lane guides should always be made with VPX walls rather than collidable primitives. Collidable prims have intermittent collision issues that cause ball sticking. The same principle applies to inlanes -- walls are the gold standard for any straight guide or lane boundary. (iaakki, tomate80, rothbauerw, Maverick)

Collidable Plastics¶

High-polygon plastic primitives (28k+ polys) are far too heavy for collision. Set normal VPX walls (lightweight, fast) to cover areas where the ball can get stuck. Adding walls in a row at increasing heights helps contain the ball at multiple levels. Invisible walls on top of plastics prevent the ball from getting trapped. (iaakki, tomate80, Tales from the Crypt)

Insert Implementation¶

3D Insert Workflow¶

The complete workflow for adding 3D inserts to a table, as established during the Metallica build:

Preparation: Separate insert images to their own layer in Photoshop at high DPI
Copy from existing tables: Most insert trays already exist in other tables (Austin Powers, Ghostbusters, etc.). Do not recreate -- copy/paste both primitives (ON and OFF trays must stay aligned on top of each other)
Punch holes in the playfield texture with alpha transparency
Position precisely using the playfield reference image
Tune materials for each insert type

(iaakki, benji084, ebislit, Metallica)

Copy Insert Primitives Between Tables

Instead of exporting/importing OBJ files separately, copy insert primitives directly between open VPX tables. Open both tables, drag selection in the source, copy with Edit > Copy, then paste in the target with Edit > "Paste at." This preserves all parameters and materials automatically. (benji084, Spiderman)

2-Prim vs 3-Prim Inserts¶

For the VPW Example Table, 2-prim inserts were chosen over 3-prim because 3-prim inserts are extremely difficult to tune correctly. The 2-prim version can be tuned with whatever material and depth-level combination and produce good results. The 3-prim version requires precise adjustment of material opacities (which can even be inverted between ON/OFF states) and depth bias. If someone uses the example table as reference, they will most likely tune 3-prim inserts incorrectly. (iaakki, apophis79, sixtoe)

Physical Inserts vs Baked Insert Text¶

The decision between physical 3D inserts and baked insert text depends on the target platform. For Last Action Hero, the decision was: use physical 3D inserts for better VR experience, but bake insert text as part of the playfield. This gives the best of both worlds -- depth for VR, clarity for text. (sixtoe, tomate80)

Insert Punching¶

When preparing the playfield for 3D inserts, separate the insert areas from the playfield layer, create a separate layer for insert text/images, and punch the holes with alpha transparency. Set playfield image alpha to 150 on insert overlays to approximate how a real insert overlay will look. Inserts with black centers may look wrong -- consider making them transparent instead. (ebislit, iaakki, oqqsan, Metallica, Die Hard Trilogy)

Insert Lighting -- Flupper Method¶

Insert lighting brings a table to life. The Flupper method uses paired GI light objects per bulb position. Worth dialing in values for each bulb depending on table location. Good examples to study: Tales from the Crypt, Team Spiryer. Flupper flasher domes can be placed at key locations for better illumination than flat inserts alone -- recommended spots include under elevated structures, on top of towers, and on back walls. (gtxjoe, benji084, Police Force)

Insert Lighting -- DisableLighting Method¶

For inserts that are too bright at center (common with triangle inserts), use the DisableLighting setup: mix DL with Bulb at -0.5 height. Each lamp type (insert, GI, flasher) may need a custom fading equation to match ROM behavior. (iaakki, Ghostbusters)

Frosted Inserts¶

For frosted guitar-pick or plectrum-shaped inserts, use the triangle-shaped frosted insert from Ghostbusters, then create frosted texture images for it. To eliminate jagged edges on round/angled inserts: add the blended edge into the flasher image itself and make the cutout slightly larger so insert and flasher overlap. (iaakki, ebislit, Metallica, Ghostbusters)

Insert Text Shadows¶

Insert text shadows simulate ambient occlusion, not actual light-source shadows. The shadow angle is relative to the text baseline (not light angle) and is extremely exaggerated. Purpose: add darkness around text to prevent a "floating" appearance and help blend into the insert. Direction should come from overhead (simulating multiple ambient lights where shadow only shows underneath). Use Photoshop for quality. (benji084, iaakki, Spiderman)

Ramps and Wire Guides¶

Ramp Construction¶

VPX ramps have significant limitations: they can only specify start/end width (no width control along the ramp) and start/end height. Workarounds:

Use multiple ramps: one for the fixed-width section, a second for the tapered entrance
The "height offset" parameter allows brute-force adjustments for humps/curves (difficult to use, VR helps visualize)
For ramp exit behavior: export the VPX ramp as a primitive, add a beveled hole at the exit point for a satisfying drop-through with randomness

(gtxjoe, benji084, Police Force)

Best practice: build ramps physically correct in VPX first so they work at the right height. This serves as the basis for Blender modeling. Physics functionality before visual polish. (sixtoe, Street Fighter 2)

Collidable Ramps in Blender¶

When VPX native ramps cause ball rejection (especially merged or split ramps), build a low-poly collidable ramp in Blender. Process: create ramp geometry in VPX for path reference, export, model a clean version in Blender, reimport as collidable primitive. This solved constant rejection on the upper right split ramp in Die Hard Trilogy. (apophis79, oqqsan)

Complex ramp meshes should be split into two versions: a high-poly visible mesh and a low-poly invisible collidable mesh. VPX calculates collision math for every face in a collidable primitive. Target: approximately 1600 triangles for a ramp serving both visual and physics roles. Technique: delete all surfaces not visible in-game, or use Blender's "limited dissolve." (sixtoe, jlouloulou, Stargate)

Converting VPX Ramps to Primitives¶

For visual polish, ramps can be modeled in Blender from VPX ramp templates. The process used for Police Force:

Import VPX table to Blender, use ramps as size/shape guide
Model high-poly ramp with improved bevel size (more rounded edges)
Apply textures and render
Export and import back to VPX

(tomate80, benji084, Police Force)

Wire Ramp Implementation¶

Wire ramp textures come in medium, high, and very high contrast versions. Higher contrast equals a shinier appearance; generally "very high" is preferred for a new/clean look. For tables with stacked wire ramps running one above the other (like Last Action Hero), this is unusual but correct per reference photos. (tomate80, cyberpez)

Wire ramps can have their polygon count significantly reduced (70k to 17k triangles in one case) without visible quality loss in the final render. (tomate80, benji084)

Ramp Physics¶

Every real pinball ramp has a metal entrance flap. During the Big Bang Bar v2.0 cycle, gedankekojote97 added the missing entrance flap on the plastic main ramp -- a detail requiring a full 12-hour bake run. (passion4pins, gedankekojote97)

For ramp height determination, reference photos and gameplay video are essential. On Earthshaker, the complex stacked spiral ramp required careful height analysis:

Wood sidewalls approximately 50 VP units high
Bottom ramp sits just above plastics, nearly flush
Top spiral ramp sits on top of bottom ramp with minimal clearance (ball diameter + small gap)
Ball is 27mm; ramp walls approximately 30mm
The spiral ramp literally scrapes the pop bumper top (decal damage visible on real machines)

Key principle: get the ramp entrance heights right first since they affect physics; the descending portion matters less. (sixtoe, tomate80, benji084, Earthshaker)

Ramp Rolling Sounds¶

Wire ramp rolling sound loops require placing triggers at ramp entry/exit points to turn the rolling sound on and off. Multiple triggers are needed per ramp to handle entry, sections, and exit. The looped rolling sound should match loop length to ball travel time. Best reference implementation: Star Wars Data East table. (fluffhead35, Maverick, Tommy)

Ramps Extending Beyond Playfield¶

When ramps extend behind the playfield edge, the table boundary must extend. Options: increase the table boundary with dead space at top (without stretching the playfield image) or use a hidden kicker teleport system. For accuracy, use the real ramp approach. Tables like Austin Powers, Dr. Dude, and Kong King handle this the same way. (gtxjoe, benji084, Police Force)

Mechanisms and Toys¶

Kickers and Saucers¶

VPX kickers sometimes fail to capture balls reliably. The fix, proven across multiple tables: replace kickers with switches and change the ball-kicking methodology. Instead of relying on VPX's kicker grab mechanism, use a trigger/switch to detect ball entry, then use KickZ to eject. General rule: for hidden mechanisms (balls not visible), switch-based VUKs are more reliable than kicker objects. (apophis79, Road Show)

Instead of using enable/disable code for saucers, set the kicker's hit height to 8. This prevents the kicker from grabbing the ball until it has actually fallen into the saucer, solving the problem of balls bouncing around and not meeting velocity requirements. Combined with properly sized playfield mesh holes (wider than 50 VP units), this approach is more reliable than the older velocity-checking method. (rothbauerw, F14)

For scoops, original construction often does NOT have metal edges above the playfield -- those are aftermarket cliffy protectors. The original is just a hole in the playfield wood with the scoop metal sitting flush or slightly below the surface. (sixtoe, tomate80, Last Action Hero)

For scoops that need to handle multiple balls, make the physical hole a cone shape so one ball must sit almost directly on top of the other. No room for balls to get moved to the side and jam on edges. (sixtoe, X-Men)

VUKs (Vertical Up Kickers)¶

To create a smooth curved ball path for a VUK, rotate a standard VPX wire ramp on its side, align it to the desired profile, then export as a mesh/primitive. The ball rides smoother through the curved ramp than through deflector walls. (wrd1972, cyberpez, F14)

Subway-to-VUK transitions can be implemented using bezier curves to create a pipe path for the ball. The underside/backside of the path can clip through visible geometry because the ball itself hides the offending mesh. (mcarter78, sixtoe, Stargate)

Best practice for VUKs (replacing old cvpmBallstack which destroys and creates balls):

Cut a hole in the playfield and extrude a receiver cup (separate mesh or part of playfield)
Place a switch at the bottom triggering the ROM switch
Use a kicker at the bottom to eject the ball upward

(niwak, apophis79, X-Men)

Ball Locks and Troughs¶

VPW standard practice is to simulate ball troughs using kickers instead of letting balls physically roll through. Benefits:

VPX physics engine does not constantly solve ball positions in the trough
Eliminates ball collision "chattering" when two balls rest against each other
Balls locked in kickers have zero/near-zero impact on physics performance

ROM controls the drain kick-in solenoid and plunger-lane kick-out solenoid; gravity (simulated via timed kicker chain) moves balls between. Timer interval between kicks must match ROM expectations -- 300ms works for Gottlieb System 3. (apophis79, rothbauerw, bhitney, Stargate)

The VPW Example Table uses a "physical trough" where balls are only created once at table initialization and never destroyed. The SolRelease sub kicks the next ball into the plunger lane, setting off a chain reaction in the trough. Solenoid subs should fire the kicker regardless of whether a ball is present. Control logic for when to release should exist outside SolRelease since it is meant to be ROM-compatible. (apophis79)

For lock mechanisms like Road Show, key findings:

Switches may need to be swapped between positions
Lock pin logic may need inversion (normally locked, not normally unlocked)
cvpmBallStack destroys balls and sometimes fails -- replace with direct switch/kicker management
When balls are not visible during lock, use kickers instead of triggers for reliability

(sixtoe, apophis79, Road Show)

Physical Trough Implementation¶

When adding a physical trough to replace DestroyBall calls, remove all GetBalls calls and replace them with a global gBOT array. Ensure all code references gBOT instead of BOT. (apophis79, Tommy)

Complex Mechanisms¶

Goalie mechanisms (WCS94): Require specific scripting patterns for correct ball interaction with the moving goalie figure.

Drawbridge stepper motors (Medieval Madness): Uses Controller.GetMech(0) for position sensing, which broke with newer VPinMAME solenoid handling. Fix found in GitHub issue vpinball/pinmame#226: replace the GetMech-based implementation with HandleMech=0. (sixtoe, apophis79)

Space Station toy (Space Station): The center toy has 4 rotational positions (0, 90, 180, 270 degrees) controlled by the ROM. Use timer-based rotation animation with fixed step angles; the diverter is a separate collidable primitive that rotates with the toy. (tomate80, apophis79)

Moving ramp safety (X-Men): The IceMan ramp uses an IceManHold variable to prevent the ramp from moving while a ball is on it -- you cannot move a collidable primitive safely with a ball on it. Hit subs at ramp entry/exit increment and decrement the hold counter. (niwak, sixtoe)

Flipper Setup¶

Basic Configuration¶

Flipper angle accuracy is critical to table feel. The PAPA video overlay technique, developed during Medieval Madness tuning, is highly effective: overlay PAPA tournament video frames with VPX table screenshots to compare flipper positions. For MM, initial angles were too flat, making the game too easy. After overlay comparison, the flipper up-angle was raised approximately 4 degrees and down-angle raised approximately 5 degrees. Effects:

Changed the "power point" of flippers -- more velocity available at ramp shot angles
Made ball control much harder (realistic hot-potato feel)
Left ramp became backhandable but difficult; right ramp not backhandable (confirmed accurate by machine owner)
Holding flipper up no longer auto-catches moat returns

(apophis79, sixtoe, majordrain, Medieval Madness)

PAPA Machine Flipper Angles

PAPA tournament machines often have modified flipper angles that differ from factory settings. Their machines are intentionally made harder. Do not use PAPA videos as definitive reference for flipper positions -- use them only for rough references, not for how normal machines play. (sixtoe, jlouloulou, Stargate)

Flipper length should be approximately 147 VP units. When changing flipper length, also adjust the endpoint primitives for trajectory correction. All flippers should use consistent end radius values. Standard flipper area gap: 23 VPX units between flipper and surround (kicker radius 11.5) to prevent the ball from activating the flipper trigger when simply being cradled. (rothbauerw, wrd1972, apophis79, sixtoe, F14, Godzilla SEGA)

Flipper Mass and Cradle Collision¶

The FlipperCradleCollision value of 2.5 has been the VPW standard since flipper tricks were implemented. Lowering it to 0 makes flippers snappier but adversely affects flipper tricks (tap passes, post passes). rothbauerw confirmed 2.5 has been the standard across multiple years of tables. (friscopinball, apophis79, rothbauerw, Earthshaker)

Staged Flippers¶

Modern VPinMAME handles staged flippers automatically. The old StagedFlipperMod approach (with KeyUpperRight) is deprecated and broken. To implement staged flippers:

Remove the StagedFlipperMod code entirely
Uncomment the standard solenoid callback for the upper flipper

Staged flipper support was added to various VPW tables including F14 (by Primetime5k), Road Show, and X-Men. When merging script changes across versions, flipper-related subs need careful verification -- a subtle bug in Road Show's upper flipper sub only impacted staged flipping and would not be noticed without a staged flipper controller. (primetime5k, robbykingpin)

Flipper Physics by Era¶

Gottlieb System 3 flippers are extremely powerful with steep angles, trademarked as "Catch-All Flippers." Red-sleeved coils at 3.85 ohms / 48 volts are standard (very strong). Key differences from Williams/Bally: no reliable live catch, no tap pass, post passes are risky. Ball frequently goes airborne when kicked on the fly. (jlouloulou, mcarter78, bord1947, Stargate)

Upper flippers often do not need full nFozzy implementation. If the flipper points downward at rest and cannot live catch or do tricks, basic flipper settings are sufficient. Only add full nFozzy if tricks are needed. (tastywasps)

Flipper Rubber Options¶

Adding user-selectable flipper rubber color via texture swaps requires 6 images total (flipperL_on, flipperL_off, flipperR_on, flipperR_off, etc.). Flipper rubber type (standard PU, silicone, specialty) significantly affects physics. Black rubber has much less bounce than Titan red. Test each type during physics tuning. (apophis79, tomate80, wylte, Starship Troopers, Tommy)

Slope and Flipper Power Correlation¶

When adjusting slope and flipper strength, increase both together (steeper slope requires stronger flippers). Wire ramps need friction retuning after slope/power changes. (wylte, Tommy)

Drop Targets and Standup Targets¶

Drop Target Implementation -- Roth Method¶

Roth's drop target implementation enables sweeping (hitting multiple targets with one shot), which the old cvpmDropTarget class cannot do. Key implementation details:

Primitives need proper pivot points for the code to work
The "rotx to bend the target back" comment is misleading -- the code automatically calculates rotation using both rotx and roty based on orientation angle
When DT orientation angle is approximately 80 degrees, rotx alone slants sideways rather than bending back

Configurable parameters:

Const DTDropSpeed = 110    'in milliseconds
Const DTMaxBend = 8        'degrees
Const DTBrickVel = 30
Const DTMass = 0.2

Default drop target mass is critical: too low (default) and the ball passes right through. Testing on Big Bang Bar showed 0.4 was more physical, and 0.6 was the sweet spot for satisfying gameplay. (iaakki, rothbauerw, sixtoe, wylte, Police Force, Big Bang Bar)

Drop Target Animation Fix

Incremental animation fails when targets are hit rapidly in succession. The timer-based animation needs to handle the case where a new hit arrives before the previous animation completes. (sixtoe, Starship Troopers)

Drop Target Bounce¶

Instead of faking drop target bounce with script (targetbouncer), use the VPX physics engine directly: set the secondary collidable wall as a primitive angled at approximately 15 degrees. This produces natural-feeling bounce. For standup targets, 4-7 degrees of layback works well. You may need to increase elasticity approximately 15% to compensate for velocity loss parallel to the playfield. The original targetbouncer code was later criticized for "killing the flow" with balls bouncing too high and stopping on landing. (apophis79, rothbauerw)

Standup Target Heights¶

Roth standup target collidable primitives must not be too tall -- they can block ramp paths. When adding standup target animations, check associated collidable prim heights to avoid interfering with ball travel on overlapping ramps. (apophis79, Godzilla SEGA)

Standup target elasticity should be in the 0.8-0.9 range to match observed bounce-back behavior from real machine video analysis. The dampening script should not be used for standup targets since real targets have minimal falloff -- the harder you hit, the harder they bounce back. (apophis79, manners7344)

Dynamic Shadows for Drop Targets¶

Drop target shadows can be scripted to appear and disappear when targets move. These are separate from the standard dynamic ball shadows and add visual depth. (apophis79, Defender)

Pop Bumpers and Slingshots¶

Pop Bumper Radius¶

Pop bumper radius in VPX is NOT the hat size -- it is the metal ring/bumper zone size. Oversized radius causes the ball to stay trapped in bumpers for extended periods. Big Bang Bar reduced from 43 to 38 (matching Breakshot). This is a common issue across many VPW tables. If the ball gets trapped in pops for 20+ seconds, the radius is too large. (sixtoe, Big Bang Bar)

Pop Bumper Sensitivity¶

Early Data East machines have less sensitive bumpers by design. Do not set the threshold too low expecting modern sensitivity. Add bumper skirt animation for visual feedback. (wylte, Tommy)

Slingshot Construction -- Modern VPW Standard¶

The standard modern slingshot uses the nFozzy physics approach with layered components. The slingshot correction system modifies ball velocity angle based on where the ball hits the slingshot face, using a correction curve similar to the flipper correction code. The correction center point aligns with the kicker arm position: hits near the top deflect more upward, hits near the bottom deflect more downward. Correction values in the 4-7 degree range are correct (the original correction table used 10 degrees which was too high). (apophis79, iaakki, Eighties8, Starship Troopers)

Slingshot Tuning for Difficulty

For tables that play too easy, increasing sling strength is an effective way to add difficulty without making the game feel unfair. On Medieval Madness, sling strength was increased to 5.1 with threshold lowered to 1.8, matching the real machine where slings are "terrifying." (apophis79, majordrain, iaakki)

Magna Slings¶

Ghostbusters Premium/LE has magna slings (magnets in slings for unpredictable deflection). Magna slings use a magnet effects script. Many players prefer them off, so the VPX implementation includes a toggle. The Pro version has normal slings with a slightly different layout. (multiple, Ghostbusters)

Physics Integration¶

nFozzy Physics Implementation¶

nFozzy physics integration into a VPW table takes roughly one day. The implementation checklist:

Make flipper meshes
Set up the RDampen timer
Add physics materials (zCol_rubberposts, zCol_rubberbands, etc.)
Rebuild rubber/post collections for dampening
Add flipper correction code
Add Fleep mechanical sounds
Add Lampz/ModLampz fading system

The biggest task is rebuilding all collidable posts and rubbers with the correct physics materials. Always pull the latest script from the VPW Example Table (not paper docs -- the example is more current). (rothbauerw, iaakki, Eighties8, apophis79)

Rubber Dampening¶

The nFozzy rubber dampening system implements a more precise elasticity curve than standard VPX settings. The system requires separating rubber objects into two collections: aPhysicsRubberPosts and aPhysicsRubberSleeves. Sleeves have lower elasticity than posts (0.85 of the rubber elasticity values). Bands use standard VP settings and are not part of the dampening system.

The dampener applies velocity-dependent elasticity curves. For posts: at velocity 3.77 or below, elasticity is 0.935; from 3.77 to 5.76 it ramps to 0.942; from 5.76 to 15.84 it ramps down to 0.874; from 15.84 to 56 it ramps down to 0.64. (rothbauerw, benji084, F14)

Rubber Configuration¶

Separate rubber posts from rubber bands for different elasticity:

Keep original posts/rubbers visible but non-collidable
Place invisible collidable cylinders where posts are, assigned to dposts collection with z_col_rubberposts material
Make rubber bands visible but non-collidable, with invisible walls assigned zcol_RubberBands material

Rubber height 35 aligns with the slot in the post (verified in F6 mode zoomed in). Standard across most tables. (benji084, gtxjoe, Police Force)

RDampen Timer Performance¶

The RDampen timer was originally set to 1ms but should be 10ms. On one table, the 1ms setting caused an 80fps limit due to script load. At 10ms, no performance issues. For visual-only timers (flashers, lamp fading), frame timer (-1, tied to framerate) is acceptable but requires FPS-adaptive formulas. (rothbauerw, iaakki)

Kicker Exit Variance¶

Kicker exit variance (.InitExitVariance and .KickForceVar) is essential to prevent repeatable ball patterns. Without variance, every eject from scoops, VUKs, and troughs follows the exact same trajectory, making the game feel robotic. Even small variance values create noticeable randomness matching real machine behavior. (rothbauerw)

Inlane Speed Limiting¶

Inlane speed should be limited (typically to 10 units) to prevent unrealistic ball behavior. Lane guide physics: elasticity 0.42 (nFozzy plastic value), friction exaggerated to 0.9 to tame ball speed. Common VPX issue: inlanes feel slippery without manual tuning. An inlane slowdown code reduces ball speed when returning from ramps to inlanes, preventing unrealistic fast returns. (iaakki, apophis79, TNA, Starship Troopers)

Modified Rubber Physics Materials¶

For a more bouncy, realistic feel, some tables use modified rubber material Elasticity Falloff values:

zCol_RubberBands: Elasticity Falloff changed from 0.13 to 0.1
zCol_RubberPosts: Elasticity Falloff changed from 0.1 to 0.05

(wylte)

BallSize Convention¶

VPX scripts should use BallSize = 50 (standard). If an older script uses BallSize = 25, change it to 50 and divide the affected constants by 2. The BallSize parameter is expected to be 50 in other parts of the nFozzy script. Correct ball size for a 1-1/16" ball in VPX is 50. Looks more realistic at 51 or 52, but physics are calibrated for 50. (tastywasps, apophis79, bountybob)

Real Machine Reference¶

Real machine owner feedback is invaluable for physics tuning. For Medieval Madness, majordrain (real MM owner) provided critical reference:

Post passing very easy due to flat flipper angle, but keeping ball on flipper is hard
Cannot backhand ramps from a trap on either flipper
Moat feed to left flipper is highly variable -- sometimes clips sling, sometimes bounces to right sling, rarely catches just by holding flipper up
Live catch and dead bounce to right flipper work well
Slings should be terrifying and dangerous
Game plays harder than it seems

Final physics values based on this feedback: sling strength 5.1, sling threshold 1.8, playfield friction 0.22, target mass 0.1. (majordrain, apophis79, Medieval Madness)

Early Solid State Physics¶

Early SS tables need special physics attention. Rubbers need reduced elasticity compared to modern tables. Tune rubber materials to get the distinct early SS feel. (mcarter78, frank_enste1n, Countdown)

GI and Lighting Setup¶

GI Implementation¶

GI light organization for the Blender toolkit with color modding support:

Render all GI pure white in Blender -- color is applied in VPX script
Group lights in the same string with matching VPX name (all named e.g., "GI001")
Insert lights use standard format (L1, L69), flashers use F1, GI lights can use underscore format (GI_1)
For single-string GI, drive all lightmaps from a single GI light object

(apophis79, tomate80, niwak, bord1947, Haunted House, Godzilla SEGA)

GI Light Placement¶

Proper GI implementation uses 3 lights per physical bulb:

PF light -- illuminates the playfield
Plastic light -- for plastic mesh and hot spot
Ambient light -- general area illumination

For older-style doubled GI lights (big + small per position), delete extras and keep one per position. GI numbers are arbitrary (copy/paste auto-increment). (iaakki, benji084, Spiderman, Police Force)

GI String Mapping¶

Map GI strings by observing ROM behavior during gameplay modes. For Black Rose, 5 GI strings were mapped by watching which strings flickered, faded, or stayed lit during different game states (cannon firing mode, video mode, lock sequences). The manual's GI mapping was found to be incorrect -- always verify against actual ROM behavior. (sixtoe, o0skitso0o, Black Rose)

Track GI levels by uncommenting debug prints in the GIUpdates sub. The code maps GI brightness (0-1 float) to ColorGrade images numbered 0-8. Formula: Int(gi1lvl*7+1.5). (iaakki, sixtoe)

GI from Ground Up -- Skitso Approach¶

Skitso's GI rebuild process:

Create new GI lighting from scratch rather than modifying broken existing setup
Tweak playfield texture, plastic textures, ball texture, and decal textures to suit the new lighting
Create new LUT specifically tuned for the table
Adjust flashers under specific areas
Tweak metal/material settings for better contrast
Fix depth bias (DB) issues (they break easily in VR)

(o0skitso0o, Black Rose)

GI Special Effects¶

Global GI flasher: A single huge flasher covering the entire table, no image just color. Keyed off GI color -- if GI is purple, the whole table gets a purple haze. Use additive blend mode. Opacity adjustable (50-400%+ depending on effect wanted). Provides subtle color correction matching GI state. (sixtoe, Spiderman, X-Men)

GI-off hack: For tables with baked GI in textures (no separate off-state renders), add a dark flasher overlay covering the entire playfield. When GI is off, activate the dark overlay to dim the whole table. (sixtoe, T2)

Playfield AO shadow with GI fade: A playfield AO shadow on a flasher whose opacity changes with GI level, adding depth that responds to lighting state. (iaakki, skitso, Ghostbusters)

Lightmap Brightness Tuning¶

Lightmap brightness adjustments require careful comparison. During Big Bang Bar v2.0.1, all lightmaps were made 30% brighter, which was too much (tubes appeared to emit rather than transmit light). This was reverted in v2.0.2. Lesson: compare screenshots across versions before adjusting global brightness. (apophis79, passion4pins)

Primitive Fading¶

The core technique for GI/flasher fading: duplicate primitives with ON and OFF textures, fade opacity between them. DisableLighting values MUST be the same for ON and OFF prims at all times. Script updates materials via blenddisablelighting. Limitation: with only 2 primitive layers, only one fading animation can run at a time. If GI fades while a flasher fires, one must override the other. Adding 4 layers of primitives enables independent GI + flasher fading but requires rebaking and full script rework. (iaakki, tomate80, Tales from the Crypt)

Blender Toolkit Integration¶

Toolkit Setup¶

When configuring the Blender toolkit:

Ensure playfield size is set in the Blender file before running any batch or export
The toolkit includes a built-in blueprint generation button that creates a top-down reference image
Blueprints are found in Blender's Image Viewer dropdown (they do not appear automatically)
Generate separate blueprints with and without ramps for different alignment tasks
Import blueprints into VPX as a reference layer to align physics objects to Blender visual positions

(niwak, tomate80, benji084, sixtoe, Earthshaker)

For playfield setup with alpha cutouts, the PFTransparency texture node can block light transmission through insert holes. If insert lights are not visible through the playfield, try disconnecting the PFTransparency node. (sixtoe, mcarter78, Harlem Globetrotters)

Toolkit Movables¶

All movable objects must have correct local axis orientation. The updated toolkit requires rotating every movable object 180 degrees in the Z axis in Blender before baking for correct animation in VPX. Movables are set up with pivots and rotations, using "Use Obj Pos" when appropriate. (apophis79, tomate80, Godzilla SEGA)

Toolkit Baking¶

Batch render times scale with samples:

1k samples: approximately 1.5 hours
2k samples: approximately 2.5 hours
4k samples: approximately 10 hours (or under 5 hours on fast hardware)

The NoExp prefix on objects that do not need export reduces file size by approximately 70MB. Always bake from the active camera. For long renders, start them when leaving for extended periods. Do separate visual test renders (no inserts or flashers baked) first to validate physics before committing to full bakes. (tomate80, mechaenron, Godzilla SEGA, Stargate)

FastGI Approximation

FastGI approximation in render settings can cause lighting issues and plastic visibility problems. Uncheck this setting for proper GI and plastic rendering. (mcarter78, tomate80, Countdown)

Toolkit File Size Management¶

Earthshaker reached 520MB at 4K bake (versus 308MB for RCT and 251MB for TZ). Analysis revealed:

2.8M polygons total (versus TZ's 1.1M)
2.3M of those polygons were in lightmaps alone
Images consumed 279MB in the VPX file, 2294MB in GPU memory
Root cause: 10 dome lights plus numerous inserts created exponentially more lightmap renders
Insert lights accounted for approximately 82% of total renders

Reducing flasher power in Blender reduced lightmap count and file size. Real performance offenders are COM objects, VPinMAME-to-B2S registry data paths, and scripting overhead -- not backfacing faces (which are never rendered by GPU and not processed by CPU). (apophis79, tomate80, niwak, sixtoe)

Post-Toolkit Import¶

After importing a Blender Toolkit batch into VPX, a series of manual steps are required:

VLM Materials: Assign VLM materials to all baked primitives (without them, everything appears pink). Layer 0-3 and playfield get VLM.bake.active; remaining objects get VLM.bake.solid; all VLM.Lightmaps get VLM.Lightmap material
Playfield setup: Set "Hide parts behind" checkbox on BM_Playfield; add reflection probe (strength 0.2-0.3, roughness 1-2 to avoid mirror effect)
GI lightmap connections: Re-verify and fix connections between Blender lightmaps and VPX lights (names must match)
Table image: Set to VLM.NestMap2 (not blank/0) for correct playfield lighting on lightmapper tables
Hide objects: Hide all collidable prims and lights that should not be visible

Materials can be imported from another VPW toolkit table as a one-time setup. After every toolkit batch import, GI lightmap connections need re-verification. (apophis79, tomate80, sixtoe, Godzilla SEGA, No Fear, X-Men)

Mods as Separate Bake Collections¶

To add optional mods (like additional figures or toys), create a 'Mods' collection set to 'Split' in the VLM.Bake, move parts into it (use short names for name length limits). Set the sync property to toggle visibility. Simple for static toys; gets harder with lights involved (need separate lighting scenarios). (niwak, X-Men)

Sound Integration¶

Fleep Mechanical Sounds¶

Adding Fleep sounds requires scripting knowledge -- specifically knowing where to replace or delete existing sound-related routine calls. This is described as the hardest part of the integration. The Fleep package replaces default VPX mechanical sounds with realistic recordings. Sound quality is immediately noticeable even on desktop. Fleep sounds should match the era and manufacturer of the table. (apophis79, tomate80, Lethal Weapon 3)

The core concept: replace individual sound calls with collection-based hit event sounds. Objects in collections automatically play appropriate sounds when hit. Sound collections (Walls, Metals, Rubbers) need to be populated and wired to the correct objects. (Eighties8, apophis79, sixtoe, Starship Troopers)

Fleep sound package selection should match the table era:

Use appropriate flipper sounds for the manufacturer and era
SSF (surround sound feedback) effects require WAV format
Music/background audio can use MP3 to save space
Sound effects needing positional audio or deformation (pan, frequency shift) must use WAV
MP3 works for callouts played with PlaySound at fixed volume/pan

(oqqsan, sixtoe, apophis79, fluffhead35, hauntfreaks)

Fleep Recording¶

Fleep's recording best practices for capturing sounds from a real machine:

Microphone selection (in descending order of quality):

Large Diaphragm Cardioid Condenser -- more low/low-mid, less high, full-bodied sound. USB option: Blue Yeti (Gain at 0)
Small Diaphragm Cardioid Condenser -- less low/low-mid, more top end, bright sound

Setup requirements:

Room as quiet as possible
Turn off game SFX/music via service menu or unplug backglass speakers
Record approximately 10 minutes of gameplay (avoid triggering flippers while ball hits slingshots for cleaner samples)
Run solenoid test: 5x full cycles

(fleep1280)

Sound Wiring¶

When a table has custom-recorded sounds, do not replace them with Fleep sounds. Wire up Fleep for generic mechanical sounds (ball roll, ramp roll, rubber hits, metal hits, walls) but keep table-specific recordings. When replacing DestroyBall kickers with physical devices, all associated sound triggers need re-hooking since the original trigger points no longer exist. (fluffhead35, sixtoe, Road Show)

Auto-Plunger Sound¶

Auto-plunger (solenoid-driven) should use a solenoid-type sound, not the default Fleep rubber spring sound. Both the fire and return sounds should be wrapped in level-adjusted static sound calls positioned at the plunger location. (wylte, Guns N Roses)

Wire Ramp Sound Volume¶

Wire ramp rolling sounds may be too quiet if mathematically combined with the VolumeDial setting. Fix: remove VolumeDial from the BallRoll and RampRoll sound math to make them independent. Set BallRollVolume = 0.8 and RampRollVolume = 0.8 as independent constants. (fluffhead35, Road Show)

Shaker Motor Sounds¶

Fleep's shaker motor sound support uses a "cartridge" system -- a lightweight version of the full mechanical sounds package specifically for shaker effects. Configuration includes intensity levels (Low/Normal/High) and volume (0-1). VPX 10.7 does not play back 32-bit floating-point audio files -- samples must be in standard format. (fleep1280, Road Show)

Flipper Rattle Sound¶

Flippers make a mechanical rattle sound (clicking/buzzing when held) that is authentic to real tables. Implementation: a continuous sound loop while the flipper is held, different from the flip action itself. (pinstratsdan, Ghostbusters)

VR Implementation¶

VR Setup Workflow¶

VR implementation is a separate pass after desktop gameplay is solid. The typical VR setup involves: creating a VR room with cabinet art, adding a VR backglass, setting up button animations, and testing. VR room images should be downsized from ultra quality for the final release. (dgrimmreaper, dardog81, WCS94)

VR room workflow: use existing VR objects from a similar-sized table as a starting point. Cabinet needs resizing in Blender for widebody or non-standard tables. Import 3D models (.blend/.fbx) to VPX by exporting as .obj first. Room brightness must be wired to the light level option via a SetRoomBrightness sub (array of material names + corresponding base values). Desktop rails/lockbar from the toolkit should be hidden in VR mode. (tastywasps, sixtoe, rawd, Guns N Roses)

VR Room Components¶

VR room tiers:

Minimal room: Basic environment with backglass
Ultra minimal room: Bare minimum (table + essential surroundings)
Mega room: Full environment with detailed surroundings

For the minimal VR room, a simple inverted sphere with a texture wrapped around it works well. High-poly 3D models are too heavy for VR rooms and need rebuilding at lower poly counts. Reduce texture sizes to improve VRAM usage. (sixtoe, djrobx, rothbauerw, F14, Spiderman)

VR rooms can be added as F12 Tweak Menu options supporting multiple room choices. Collections of VR objects are toggled via visibility. (dardog81, bhitney, X-Men)

VR Backglass¶

B2S backglass creation involves multiple specialists: artwork, DMD integration, VR-specific lighting, and animation layers corresponding to lamp/solenoid states. For VR, the table may contain its own fully animated backglass separate from B2S.

VR backglass flasher IDs need to be mapped from real machine lamp test videos. GI strings drive backglass lighting in B2SDesigner. Day/night slider affects VR element brightness -- materials need manual brightness adjustment to counteract darkening. (dardog81, apophis79, hauntfreaks, Medieval Madness)

For EM tables, VR backglass reels can be implemented by copying core VR backglass code from existing builds (Scampa123's Spirit of 76 is a common reference). (mcarter78, dgrimmreaper, scampa123, Team One)

VR-Specific Features¶

VR Topper: Uses VPX flashers for insert lights (you cannot rotate VP lights in VR). House lights triggered by monitoring DisableLighting of corresponding inserts via timer watch. All timers disabled when not in VR mode to save performance. (rawd, Game of Thrones)

VR Undercab Lighting: Works independently of other lights and shadows, intensity is controllable. Can be connected to targets/events: pulse during attract mode, solid during certain game modes, flash on specific hits. (rawd, astronasty, Die Hard Trilogy)

VR Cabinet Completeness: Common items to verify: gaps under cabinet showing floor, missing front buttons (Start, Extra Ball), coin door, plunger model, button lights wired to correct lamp signals, wall at lower apron to prevent see-through, animated button presses. (retro27, callev, rothbauerw, dgrimmreaper, Road Show)

Mirror Sideblades¶

Mirror sideblades work correctly in OpenGL renderer but have missing reflections in DirectX renderer. Objects need "Reflection Enabled" checked, and lightmaps also need reflections enabled. GL works better with render probes and DX is being phased out -- recommend GL for tables with mirror sideblades. (iaakki, apophis79, benji084, niwak, Bad Cats)

VR Environmental Image¶

The environmental image affects overall table appearance significantly. White bloom in the center causes a washed-out look. For Dr. Who, switching to Flupper's shiny environment and dropping the day/night slider down produced better results. Ball visibility also depends on the environment -- test various ball images for your lighting setup. (sixtoe, apophis79)

Multi-Level Playfields¶

Haunted House established the architecture for multi-level playfields in VPX. Key decisions:

Main playfield should be at Z position 0 (the previous raised approach at Z=450-500 is no longer needed as VPX 10.8 resolved old limitations)
Lower playfield is angled at -11 degrees relative to the main playfield
Upper playfield can use separate physics materials with different friction

For upper playfield physics, ensure friction matches the main playfield settings. On Game of Thrones, the upper PF felt like "basic VPX physics" because its material friction was set to 0.20 while the main PF was 0.22. (cyberpez, apophis79, rothbauerw, astronasty, sixtoe, Haunted House, Game of Thrones)

Testing and Debugging¶

Shot Tester and Debug System¶

Testing mode integrated with shot tester keys (R for ramp, others for targets/lanes). The debug window shows timing and velocity. Hold P to capture the ball, adjust angle with shift keys. Velocity values print to the debug window for documentation. Makes iteration/testing much faster than playing full games. (gtxjoe, benji084, Police Force)

For testing wizard modes and complex game states, use cheat commands via the debug window (press D). (astronasty, Die Hard Trilogy)

Test automation can play a table for extended periods. On Radical, automation played for 2 hours with the first ball, achieving a 75 million score. Only requires occasional manual plunger pulls after ball locks. Useful for finding stuck balls and physics issues. (iaakki)

Debug Aids¶

Press D during gameplay to view the debug log
Must turn off FS 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

(mrgrynch, oqqsan, apophis79)

Narnia Check (Ball Out of Bounds)¶

A "Narnia check" detects when a ball has jumped out of bounds. On Defender, a ball jumped over the slingshot and off the table. Including an out-of-bounds ball detection routine prevents balls from disappearing during play. (apophis79)

SolCallback Enabled Parameter Guard¶

SolCallback subs fire twice -- once with Enabled=True and once with Enabled=False. If the sub does not check the Enabled parameter, the action executes on both calls, causing double sounds, double kicks, etc. Always add an If Enabled Then guard. This was the root cause of Medieval Madness's moat VUK playing a double sound. (iaakki, apophis79, sixtoe)

Captive Ball Initialization Timing¶

Captive ball creation at table init can cause crashes if the nFozzy physics dampener is still initializing when the ball touches dampened objects. Fix: move captive ball creation to the preloader phase (later in startup). (iaakki, apophis79, Tales from the Crypt)

Original Table Design¶

Layout Design Principles¶

Layout design tips for original tables, drawn from the Die Hard Trilogy development:

A third flipper can dramatically improve an uninspired two-flipper layout
Replace 3 pop bumpers with 1 center pop + slings/rubber bands around the outside to save space
Complex multi-step mechanisms (diverter + VUK + ramp) should be simplified to single entry points for better gameplay flow
Create "sneak-in" entrances under structures (like Theatre of Magic's trunk shot) for skill shots
Place elongated saucers so the ball can fall in from the side when moving slowly but rolls right over at high speed

(astronasty, oqqsan, mysda, Die Hard Trilogy)

Insert Color Coding¶

Insert color conventions for player feedback:

Red = bad/negative (ambush, failed, disqualified). Do not use red for positive collectibles
Yellow/Orange = in progress (hitting drop targets toward multiplier)
Green = positive (completed, collected)

(oqqsan, astronasty, Die Hard Trilogy)

Apron Considerations¶

Avoid putting lights or mechanics on the apron. Set the apron to negative depth bias to fix ball trail rendering issues. Debug instructions can be placed on the apron during development. (oqqsan, astronasty, apophis79, Die Hard Trilogy, Defender)

Version Control and Collaboration¶

Table File Versioning¶

Table versioning follows a pattern like TableName10.7_XXX.vpx where XXX is a sequential build number. Sub-versions use letter suffixes (140b, 140c, etc.). Each upload includes a changelog comment in the script header. Do not upload test builds to avoid confusion. Wait for the designated file maintainer to upload before pasting in your changes. (multiple, Die Hard Trilogy)

VPW Check-In/Check-Out System¶

VPW uses a bot-managed check-in/check-out system for table files:

Check out the latest version before making changes
Upload the modified file to personal cloud storage (Dropbox/Google Drive)
Check in with version number, download link, and change comments
Version history is maintained in the channel

Critical: always work from the latest checked-in version. (VPW Bot, apophis79, Stargate)

Collaborative Development¶

VPW table development involves parallel work streams that must be carefully merged. Common problems and solutions from Black Rose and Game of Thrones:

Always work from the latest version -- confirm which version is current before starting
Version numbering must be bumped to avoid confusion
One person should be project director with final say
Keep changelogs in the script header documenting each version's changes
Limit concurrent WIP projects to avoid burnout and version drift
There is no good way to "diff" or "merge" VPX files -- version control is manual copy/merge with version numbers

Typical role distribution on a VPW build:

Coder: Builds functional table with all rules (ROM analysis or original coding)
3D artist: Builds complete Blender model with toolkit
VR specialist: Adds topper, backbox, cabinet art
Physics/lighting specialists: Refinement passes
Testing team: Extensive cabinet play

(sixtoe, apophis79, iaakki, sheltemke, skillman604, Black Rose, Game of Thrones)

Working with Original Authors¶

VPW protocol:

First attempt is always to contact the original author and have them lead/approve changes
Authors release under their own name, not VPW, unless they prefer otherwise
Best practice: check with original authors early in the process
When renaming from personal edits (e.g., "Kevv-edit") to "VPW Mod," this signals it is a team project

(benji084, sixtoe, bord1947)

Resource Organization¶

Shared development resources are typically organized in Dropbox with folders for: Playfield (photo tiles, stitching attempts, overlay references), Plastics (scans and photos), Reference (manual excerpts, measurement data), and Builds (versioned VPX files). (benji084, Police Force)

Release Preparation¶

Release Checklist¶

Pre-release items compiled from multiple VPW releases:

Fix nudge/tilt switch values
Cabinet mode toggle
Standalone compatibility patches
Ball brightness option
Room light level affecting all objects (apron, VR room)
Option menu constant numbering (check for duplicated indices)
Debug print statements commented out
Refraction options in tweak menu
Flipper animation placement (keydown/keyup vs solenoid subs)
Auto-plunger sound vs spring plunger sound
Inlane speed limiting
SetLocale 1033 for international compatibility
B2S file included in the zip
Competition NVRAM file if applicable
VR siderails/lockdown bar visibility correct per mode
Trough-is-full function to prevent option menu during gameplay

(apophis79, sixtoe, wylte, Guns N Roses, Metallica, Road Show)

Release Wording

For ground-up VPW builds, the release text should reflect this -- "table tune-up by VPW" is incorrect for scratch builds. Proper credit attribution matters: original table builder should be prominently credited, plus specific contributors listed. (apophis79, sixtoe, Maverick)

Table options previously stored as in-script constants should be migrated to VPX's Tweak menu for user-friendliness. Options include: playfield reflections, flasher brightness, VR room settings, shaker motor configuration, and alternative sound selections. The process is documented in VPW example tables. (apophis79, nestorgian, Road Show)

Post-Release Maintenance¶

"Finished" tables are never truly finished -- community play reveals edge cases that development testing misses. Road Show saw 2+ years of post-release refinement from v1.0 to v1.5.5. Maintenance categories:

Physics micro-tuning (scoop geometry, flipper strength, bumper force)
Visual polish (higher-res textures, corrected plastics, accurate ball guides)
Compatibility fixes (standalone player, VPX version differences)
Feature additions (staged flippers, tweak menu options, VR button animation)
Bug fixes discovered by competition play (VPW weekly competition is an effective stress test)

(clarkkent9917, apophis79, sixtoe, Road Show)

Performance Optimization¶

Timer Optimization¶

Many table scripts use 1ms timers unnecessarily, wasting CPU cycles. Most visual effects and game logic work correctly at 10-20ms intervals. Changed timer intervals need associated code adjustments to maintain correct behavior -- scale movement/animation increments proportionally. (apophis79, Road Show)

Solenoid Callback Stutter¶

Persistent micro-stutters during gameplay can be traced to the solenoid callback method in core.vbs. Fix: use VPX native solenoid callback handling instead of core.vbs wrapping. This was described as a dragon "chased for years" that was finally killed on Earthshaker. Requires VPX 10.8.0-1904 and VPinMAME 3.6-862 or later. (apophis79, niwak, Earthshaker)

Image Size Optimization¶

Oversized textures waste texture memory and can look worse due to VPX resizing. Rules of thumb:

Inlane textures at 4K when inlanes are only 1/8 of table length can be reduced to 2K (4x smaller, 25MB to 5MB) with zero visible quality loss
Colossal image sizes give diminishing returns, eat texture memory, and VPX can produce artifacts when resizing
Always evaluate actual screen area coverage when choosing texture resolution

Maverick went from 190MB to 100MB through image optimization (resizing oversized textures, WebP conversion). (sixtoe, Maverick)

VPX Performance Analysis¶

On a GTX 1080 at 2440x1440 with AO and SSR enabled, a table ran at 143-144 fps with CPU at 13-15% and GPU at 36-39%. Transparent elements consistently have the biggest proportional performance impact. VPX cannot fully utilize system resources due to its codebase age. Physics run through VBScript which is not optimized. (iaakki, Radical)

DisableStaticPrerendering¶

The DisableStaticPrerendering feature allows adjusting room light level in real-time through the options menu without requiring table restart, while maintaining performance benefits of static rendering during normal play. Requires VPX build 1666+. (apophis79, niwak, Godzilla SEGA)

Special Topics¶

System-Specific Setup¶

Gottlieb System 80 (Haunted House): Uses lamp multiplexing where some "lights" (lamp outputs) control solenoids/flashers. Lower playfield flashers are controlled through the lamp matrix rather than dedicated solenoid outputs. Flasher behavior must be mapped from lamp callbacks rather than solenoid callbacks. (apophis79, cyberpez)

Gottlieb System 3 (Stargate): Trough configured differently than Williams/Bally. Do NOT add a 4th trough kicker (only 3 needed). Switch 24 is drain/outhole. Physical trough photos from Pinside are essential for mapping switches correctly. (apophis79, rothbauerw, sixtoe, wylte)

Data East flashers: Use switching relays for dual function. L-side = high voltage solenoids (kickers, flippers, pop bumpers); R-side = flashers (lamps). (sixtoe, wylte, Last Action Hero)

Bally/Williams post-merger: After the merger (first post-merger game: Truck Stop), both brands used the same hardware. Williams flipper bats are correct for post-merger "Bally" games. (lumigado, apophis79, Black Rose)

EM Tables¶

EM table modes vary: some have credit reels, some are novelty/add-a-ball games. Desktop score displays for System 11 tables need segmented digit objects copied from another System 11 table (Whirlwind, Taxi, Dr. Dude). VR and desktop digit implementations cannot run simultaneously -- code must toggle based on VRRoom state. (mcarter78, leojreimroc, .rawd, Team One, Diner)

Competition NVRAM¶

Factory-default NVRAM files with specific settings (extra ball buy-ins disabled, etc.) can be bundled for competition play. Some ROMs have quirks that cannot be toggled via settings. These files are essential for organized competition use. (apophis79, pinstratsdan, Big Bang Bar, Tales from the Crypt)

Gottlieb System 3 NVRAM¶

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

PWM and Lamp Control¶

The PWM update (UseVPMModSol=2) migration process varies in difficulty. For tables built on latest VPW methods, it can be a quick 5-minute update. Changes: remove InitPWM sub, update UpdateGI and FlashMod subs for new physics output, set all light fader models to None. PWM outputs are more realistic -- ROMs usually do not send full brightness to prevent overheating, so inserts may need to be slightly brighter than real gameplay to compensate. (apophis79, No Fear)

Upgrading from older JP (Jordy Pijpers) fading code to PWM requires converting from JP fading to either Lampz (intermediate step) or directly to PWM. Tables with "epic light shows" make PWM particularly worthwhile but the conversion is non-trivial. (iaakki, apophis79, Monster Bash)

Locale Issues¶

Spanish locale can cause keycode issues where keyboard presses do not register correctly. Commenting out SetLocale 1033 and trying SetLocale 11274 (Argentina) may resolve debugger problems. Keycode mapping can shift. Always include SetLocale 1033 in release builds for international compatibility. (apophis79, tomate80, Street Fighter 2)

Playfield Reflections¶

Balls reflect the playfield image -- even if playfield_mesh is set to invisible, there must be an image assigned to the playfield object. Without it, ball undersides appear pure black. Setting the PF image to the nestmap and enabling dynamic reflections resolves the issue. (apophis79, iaakki, Godzilla SEGA)

playfield_mesh is a special name in VPX -- it is the primitive used for playfield rendering (needed for the special reflection render path). If collidable, it also handles physics. Set collidable=false on playfield_mesh if you have a separate physics object. (niwak, X-Men)

Playfield Print Bump Mapping¶

Playfield print bump mapping gives printed areas (like insert letters) visible depth -- the raised/sunken edge effect visible on real playfields. Following Freezy's VPE tutorial, this works in Blender's material system. Fairly experimental but adds depth perception. (niwak, X-Men)

Development Tools¶

Desktop POV Setup¶

POV parameters explained:

Inclination (default 6): table slope appearance
FoV (typical 45): camera lens shape; higher = more fisheye
Layback (typical 45-60): tilts/stretches vertically; no IRL analogue
Scales: keep Z at 1; X/Y below 1, approximately 0.9:1 ratio for slight width
Offsets: camera position, table-dependent

FoV and Layback affect ball appearance (stretching at back, squashing at front). Every setup/screen/person is unique. (wylte, Guns N Roses)

Align the POV so the table area matches the blacked-out region on the desktop background. Delete the POV file to troubleshoot scaling/clipping issues. (apophis79, pinstratsdan, bountybob, Diner)

Reference Material¶

Document screw and nut placement from real machines for 3D modeling accuracy. While minor detail, it contributes to overall realism. Physical measurements from real machines are invaluable -- drop target dimensions, ramp entry/exit heights, post heights, and sideblade heights all feed directly into VPX object placement. (wylte, iaakki, Tommy, Space Station)

Blender Export/Import¶

The pivot point for VPX meshes exported from Blender is at XYZ coordinates 0,0,0 in Blender. Setting the mesh origin to (0,0,0) ensures the pivot imports correctly into VPX without manual adjustment. (flupper1, F14)

For importing primitives with correct position AND local pivot/rotation axis:

Export primitives from Blender with table origin (0,0,0) as "dummy" position references
Import dummies into VPX with all transformation values at zero -- they will be at the correct table position
Replace dummy meshes with the actual detailed geometry

(Deleted User, tomate80, T2)

VPX F6 Flying Camera¶

To inspect tables from any angle:

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

Useful for checking primitive placement and lighting from cabinet perspective. (astronasty)

Build Philosophy¶

WIP Strategy¶

Community pressure is real. For Police Force, the strategy was to post a WIP video to buy time while the table was still being polished. A WIP video shows progress without revealing full table quality and prevents rushed releases. (gtxjoe, tomate80)

Complete Project Timelines¶

VPW builds vary enormously in duration:

Godzilla SEGA: Approximately 9 months (Jan-Sep 2023)
Maverick: Approximately 3 months of active development
Earthshaker: 3+ years with distinct phases
Tales from the Crypt: Approximately 6.5 months
Game of Thrones: 10 months

The longest builds involve complex mechanisms, multiple playfield levels, or extensive custom ROM analysis. The Earthshaker timeline is instructive:

Lite build (Apr-Dec 2021): Initial rubber dampeners, subway/trough rework, VR room, physics objects
Scan acquisition (Nov 2022-May 2023): CPR playfield scan arranged, professionally stitched
Blender Toolkit build (Sep 2023-Apr 2024): Complete 3D modeling (estimated 50-80 hours), plastics traced in Illustrator/Blender
Script and physics (Dec 2023-Apr 2024): nFozzy/Fleep scripting, lightmap control, physical table layout rebuild
Testing and polish (Feb-May 2024): Went through 53+ versions before approaching release

(various, Earthshaker)

The VPW Example Table¶

The VPW Example Table is intentionally not a game framework like Orbital or JPSalas. The concept is to pick and choose features, not use it as a complete starting point for game logic. Features demonstrated as of v1.0: nFozzy flippers and physics corrections, Fleep sound package, ramp rolling SFX, Lampz light fading, Flupper dome flashers, Flupper bumpers, 3D inserts, Roth drop targets with shadows, dynamic ball shadows, Rubberizer, TargetBouncer, VR cabinet and room, FlexDMD scoreboard with intro. (apophis79, sixtoe, oqqsan, iaakki)