Table Build Workflow¶

An end-to-end reference for building a VPW table, from initial project decisions through post-release maintenance.

Scope Decision: Lite vs Premium¶

Before any technical work begins, the team must decide on scope. A Lite table applies physics improvements, sound packages, and bug fixes to an existing community table without reworking 3D assets or lighting. A Premium table is a full rebuild with Blender toolkit rendering, proper collidable geometry, and ramp primitives. Lite tables can ship in weeks; Premium tables take months to years (learned from Creature from the Black Lagoon and Cirqus Voltaire).

The key question, as debated on CFTBL, is whether existing primitives are already good enough. If the ramps are solid and just need physics and sound, go Lite. If the table deserves proper collidable ramps, toolkit lighting, and modern scripting, commit to Premium with a dedicated producer who assigns tasks and manages versions.

The recommended build order for Premium tables, established during Die Hard Trilogy:

Rules and insert layout (requires iteration)
Physics integration and Fleep sounds (can proceed in parallel)
Artwork finalization
Rules programming
Blender toolkit work (must come last, after artwork and layout are locked)

Team Formation and Version Control¶

VPW tables are collaborative. Common roles include a table lead (scripting, physics), a Blender/toolkit artist, a VR specialist, a sound integrator, and ideally a real machine owner for reference testing (learned from Iron Maiden and Diner).

The VPW Bot checkout system prevents the merge disasters that plagued early builds. Congo and Black Rose both lost entire versions of work when contributors built from stale copies. The discipline is straightforward: check out before working, check in with a version number and detailed changelog comment, and never work from a cached copy. VPX binary files cannot use git diff, so sequential version numbering and clear communication are the only safeguards against lost work (learned from Hook).

Playfield Acquisition¶

Scanning¶

The HP Scanjet 4600 and 4670 are the only scanners that produce distortion-free playfield scans, as documented extensively in the VPW Resources channel. These see-through scanners avoid the raised glass lip of flatbed models. Scan at 600 DPI in TIFF format in a dark room for consistent color reproduction.

For multi-pass stitching, PTGui produces the most accurate results. Manual stitching using a difference layer in Photoshop takes about 30 minutes but ensures accuracy. Critical rule from bord1947: never scale stitched scans. Crop and reduce to game asset resolution (~150 DPI for archival, 4K width for VPX) but preserve original proportions.

Hardtop overlays (plastic overlays for refinishing) from outsideedgeproducts.com provide an alternative scan source at approximately $350, with the art printed on the underside for high quality (learned from Jokerz).

Dimension Verification¶

Never trust playfield dimensions from online databases without verification. The Guns N' Roses build discovered that "internet wisdom" listed the playfield as 25" x 51.75" when the actual measured size was 23" x 46". To verify from a scan, divide pixel count by DPI: a 12168-pixel-wide scan at 600 DPI gives 20.28", confirming the standard 20.25" WPC width.

Use circular features (pop bumper holes, post holes) as circularity validation. If circles render as ovals, the dimensions are wrong. Cross-reference against IPDB specifications and, when possible, physical measurements with calipers (learned from Countdown and Breakshot).

Standard dimensions by manufacturer: - Williams/Bally standard: 20.25" x 46" (952 VP units wide) - Williams/Bally widebody: 23" x 46" - Stern modern: 20.25" x 45" (not 46" -- learned from Metallica) - Capcom: varies, verify per table

The VP unit conversion formula is: VP units = inches * 800 / 17, where 50 VP units equals 1.0625 inches (one pinball diameter) (learned from Bram Stoker's Dracula).

Blueprint Overlay and Alignment¶

With a properly scanned playfield image, objects can be placed at the holes visible in the scan. The alignment workflow from Bram Stoker's Dracula: import the scan at correct dimensions, create blueprint overlays from manual diagrams, align rubber posts to playfield holes first (center of hex nut = center of hole), then align inserts, physics objects, and remaining primitives layer by layer. When blueprints and scans conflict, trust the scan -- blueprints from manuals of this era are not always precise.

For Fish Tales, the alignment was verified by overlaying the manual blueprint at 50% opacity in an image editor, using straight lines and screw holes as anchor points.

Blender Toolkit Integration¶

Collection Organization¶

The standard Blender collection structure for toolkit tables, first established on Haunted House and refined on Iron Man:

VLM.Bake: All static objects (playfields, parts, overlay items). Sub-collections for parts, separate playfield collections if different depth biases are needed, and "underPF" for objects visible through transparent playfield areas.
VLM.Lights: All light objects. Inserts in one collection (Split), GI per string (Grouped, with shadow-casting lights in separate Split collection), Flashers (Split), Room light collection (Solid render mode).
VLM.Movables: Animated objects (targets, flippers, gates, spinners).

At least one light collection must have "Solid" bake mode selected, or no bakemaps will be generated -- only lightmaps. This was the source of missing bakemaps on Haunted House.

Naming and the 31-Character Limit¶

VPX has a hard 31-character limit on primitive and lightmap names. Toolkit lightmap names follow the pattern LM_<light collection>_<light name>_<part collection>_<part name>, and long names are silently truncated, causing duplicate name conflicts and broken lightmap assignments (learned from Haunted House, Iron Man).

Keep all component names at most 6 characters. Use abbreviated prefixes: "GI" not "GeneralIllumination", "PF" not "Playfield". The NoExp prefix on Blender modifiers tells the toolkit to skip them during export, preventing subdivision modifiers from inflating polygon counts (learned from Iron Man and Johnny Mnemonic).

Batch Export Settings¶

Critical settings discovered through trial and error on Haunted House: - Nestmap size: 8192 (8K), not 256. At 256, the export produces dozens of tiny images instead of properly packed atlases. - Render ratio: 25% for quick 1K test renders (2-3 hours), 50% for 2K iteration renders, 100% for final 4K (15+ hours). - Export mode: Use "Hide" not "Remove All" to preserve original objects in the VPX file.

If the blend file name stays the same, manually delete the render results directory before re-running -- the toolkit only renders items not already in the results directory.

Bake Workflow¶

After the batch completes, a new VPX file is produced with bakemaps and lightmaps plus a helper script. Integration steps from Godzilla:

Import VLM materials from another toolkit table if not auto-assigned
Apply VLM.Bake.Solid to opaque elements, VLM.Bake.Active to transparent elements
Set up movable objects using _Animate methods
Hide all collidable physics primitives and VPX light objects
Assign render/refraction probes (these get lost on import and must be re-assigned)

Movable objects (drop targets, flippers, spinners, gates) must NOT have the "static" flag set or they will not respond to script-driven property changes at runtime (learned from Countdown).

VPX Import and Object Setup¶

Layer Organization¶

Recommended layer structure from Batman DE: Layers 1-3 for collidable objects (ramps, flippers, walls, switches, targets, posts, pegs), Layers 4-6 for primitives and inserts, Layers 7-9 for lights, Layers 10-11 for VR objects and playfield-sized flashers. This makes debugging easier and helps spot duplicate collidable objects -- a common problem in collaborative builds.

Timer objects must go in the Timers layer (not lightmaps) to survive Blender re-bakes (learned from Countdown). Timers placed on the VLM.Visual layer get deleted when a new toolkit batch is imported (learned from Last Action Hero).

Playfield Mesh Implementation¶

The playfield mesh primitive must be named exactly playfield_mesh. VPX treats this specially as the replacement physical playfield surface. When present, VPX uses this mesh for ball physics instead of the flat default. Physical holes can be cut in the mesh with beveled edges, allowing balls to fall through to under-playfield mechanisms (learned from Blood Machines and Congo).

Key gotchas: - If accidentally nudged from 0,0, all inserts and lights misalign with the playfield image - Loop cuts in the flipper area can cause balls to stick at standstill (learned from Batman DE) - Cutting rollover switch holes can allow balls to fall through -- use transparency in the texture instead (learned from Batman DE)

Mechanism Wiring¶

Kickers, Scoops, and VUKs¶

For scoops and VUKs, use the Y-axis for kick direction, not Z-axis. Z kicks straight up; Y kicks forward onto the playfield (learned from Hook). The KickZ method parameters are: angle (direction relative to editor arrow), speed, inclination (90 = straight up), and heightz (Z translation before kick). Sometimes a small non-zero heightz is required for the method to work (learned from Road Show).

Physical kickers provide more realistic ball behavior than legacy VUK implementations. They produce a proper acceleration curve instead of an instant velocity change (learned from CFTBL).

Drop Targets¶

Roth drop target primitives must face the drain at RotZ=0. Using ObjRotZ instead of RotZ for orientation causes all hit angle calculations to be incorrect -- the brick check evaluates perpendicular velocity using RotZ (learned from Hang Glider and Countdown). Drop target layback of 4-7 degrees produces realistic bounce (learned from Physics Debate).

Spinners¶

Spinners require two baked positions (0 and 180 degrees flipped) with opacity cross-fading during rotation. The 180-degree version must be slightly larger (e.g., scale 0.575 vs 0.570) to prevent z-fighting during cross-fade (learned from Harlem Globetrotters).

Sound Integration¶

Fleep Sound Packages¶

Fleep sound packages require specific VPX collections with "Fire events for this collection" enabled. Required collections often missing from new builds: Metals, Rollovers, Apron, Walls (learned from Breakshot).

Sound cartridge selection should match the machine's era and system, not just manufacturer. Even matching assembly part numbers does not guarantee matching sounds -- coils get replaced and cabinet resonance affects recordings. Compare by ear (learned from Bride of Pinbot).

Always use WAV format for table mechanical sounds. MP3 files route through a different audio engine (bass) that breaks SSF positional audio (learned from Maverick).

Sound Recording¶

Fleep's recommended procedure: glass ON for true cabinet acoustics, recording device on tripod slightly above lockdown bar (never resting on the cabinet), in the quietest room possible with game SFX and music turned off. Record 10 minutes of gameplay plus solenoid test cycles. Deliver via Google Drive or Dropbox -- YouTube compresses and degrades audio quality.

Display Setup¶

B2S Backglass¶

B2S animations are driven by Controller.B2SSetData calls triggered by switch events. Wrap all B2S calls in If B2SOn Then to prevent runtime errors for non-B2S users (learned from Cirqus Voltaire). Run B2S in exe mode as standard practice to prevent frame rate spikes (learned from Radical).

FlexDMD¶

For original (non-ROM) tables, FlexDMD provides a scriptable dot-matrix display. Set FlexDMD log level to "Warn" not "Trace" -- Trace level logs every operation to disk, causing stutters during gameplay (learned from Goonies). The FlexDMD update timer must remain enabled throughout the entire game session -- disabling it after the intro breaks the DMD on subsequent games.

PUP Packs¶

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

Testing Methodology¶

Competition Testing¶

Focused competitive play exposes edge cases that casual testing misses. The VP Chat competition on Maverick revealed three undiscovered bugs in a table released for months: missing tilt functionality, stuck ball areas, and a drop target ball-launch bug.

Real Machine Reference¶

Having a real machine owner on the team is invaluable. The Iron Maiden methodology: remove glass for clear video, turn down ROM music to isolate SFX, play slowly through each mode individually, record with camera showing both playfield and DMD, maintain a Google Sheets tracker for issues. Side-by-side play (VPX next to real machine) is the gold standard for calibration (learned from Metallica).

Physics Feedback Protocol¶

When providing physics feedback: provide PAPA or competition video timestamps showing expected behavior, not subjective descriptions. Tables are tuned as "new or well-maintained machines" -- they play faster than worn arcade machines. Without video evidence, feedback becomes endless back-and-forth tweaking (learned from Monster Bash).

Release Checklist¶

Before release, verify: - BallSize = 50 (not legacy 25) - Ball mass = 1 (not 1.3, even for widebody tables) - VRRoom = 0 for desktop releases (VR room primitives cause 20-40 FPS loss even when not visually needed) - All debug.print statements removed (I/O overhead causes visible frame drops) - VSync override set to -1 (not 1) in table User properties - Insert depth bias values verified after any VPX crash or version change - Flipper trigger margins at 27 VP units (updated from 23 in 2024 -- see Physics Tuning) - Metal wall hit thresholds at 2 - Pop bumper radius sized to the rubber skirt/ring, not the plastic cap - Playfield physical sounds are mono, not stereo (stereo degrades SSF output) - Cabinet Mode checkbox enabled in VPinMAME ROM settings - Wait at least a week after RC status before publishing -- there is always something found in extra testing time

Post-Release Patching¶

Post-release version management should remain centralized and accessible. Die Hard Trilogy demonstrates the failure mode: updates managed on a personal server became inaccessible when the lead coder left the community.

For patching the VPW Bot checkout system, increment the version number on every check-in with a changelog comment. Common post-release fixes include timer interval adjustments (1ms to 20ms), missing tilt functionality, stuck ball areas, and sling threshold tuning.

Multi-Playfield Table Architecture¶

For tables like Haunted House (3 playfields, 8 flippers):

Main playfield at Z=0 (VPX 10.8 resolved older limitations requiring raised playfields)
Lower playfield at its measured angle relative to main (e.g., 11 degrees for Haunted House)
Flippers on angled sub-playfields need two-axis rotation: set up local axes normally, then rotate globally for the slope
Drop target animation code resets RotX to zero, which breaks targets on angled playfields. Fix: add the playfield angle offset to RotX in the animate sub, using a z-height check to identify which targets are affected

Table Dimension Correction¶

If a table is built at incorrect dimensions, the error propagates into all assets including Blender files. Correction requires fixing VPX playfield dimensions, realigning all objects, and fixing the Blender file separately. Verify corrected dimensions by checking that scanned plastics (which are at correct size) fit properly. Catch dimension errors early by checking plastics alignment -- the correction is painful enough that the Bram Stoker's Dracula team delayed work for months rather than face it.