pokemon_pinball_wiki/vpx-table-recreation.md

# Pokemon Pro VPX Table Recreation

## Status

An evidence-calibrated Visual Pinball X 10.8.1 table is implemented under
`emulation/vpx/`. The generated `emulation/vpx/PokemonPro_Greybox.vpx` keeps a
self-contained `standalone` mode and adds `spike3`, where the genuine game in
QEMU owns rules, lamps, and mechanism drivers while VPX owns physical balls
and contacts. See `native-playable-table.md` for the complete cabinet path.

Confirmed on 2026-07-14 after the continuous-collision rebuild:

- `emulation/vpx/build.sh` regenerated the manifest and diff-friendly VPX
  source, assembled the table with `vpxtool 0.33.4`, imported the standalone
  VBS, and passed `vpxtool verify`.
- `emulation/vpx/qa.sh` first validated 13 continuous collision polygons and
  13 separate visual rails with zero legacy segment rectangles and zero
  self-intersections, then re-extracted the assembled table and matched its
  configuration, exact VBS, and all 323 named game items, including reusable
  mechanical meshes, five private decal planes, and hidden QA/controller
  objects. VPX binary float
  quantization is compared at 0.01 VPX-unit precision.
- `emulation/vpx/qa-live.sh` loaded the table in the local macOS BGFX player,
  compiled its VBS, ran the correctly named table initialization event, served
  a ball, and captured a live playfield frame.
- `emulation/vpx/qa-mechanisms.sh` physically launched test balls through the
  left and right outlane switch/drain paths and center drain, then exercised
  Town VUK capture/eject, Poke Ball hold/release, and shooter-lane service. All
  required events are present in `emulation/vpx/qa/mechanism-runtime.log`.
- `emulation/vpx/qa-plunger.sh` served a free ball, pulled and fired the actual
  VPX plunger, and detected that same ball after it cleared the shooter-lane
  mouth into the main playfield. The old midway-up-lane checkpoint was removed.
  The position trace and passing event are preserved in
  `emulation/vpx/qa/plunger-runtime.log`.
- `emulation/vpx/qa-sling-authority.sh` proved that both integrated-mode sling
  balls remain captured until their mapped QEMU drivers arrive and are safely
  released on disconnect.
- `emulation/vpx/qa-shots.sh` exercised physical outlane/center drains, actual
  trap/shooter/sling mechanisms, every mapped ramp/orbit contact route, both
  pops, captive-ball retention, posts/gate/Meowth motion, and restored physical
  inventory to the captive ball. Ramp/orbit coverage in this harness is a
  native contact/driver route test, not a claim that a physical ball traversed
  every full elevated trajectory.
- `SOAK_SECONDS=8 emulation/vpx/qa-soak.sh` completed eight cycles with the
  six-plus-one inventory invariant. The default is 3,600 seconds; that full
  soak remains unrun.

For a standalone play test, double-click `emulation/vpx/run.command` or run
`emulation/vpx/run.sh`. For the integrated cabinet, use
`emulation/run-playable.command`. The standalone launcher probes the verified
`~/Downloads/vpinball/build/VPinballX_BGFX.app/Contents/MacOS/VPinballX_BGFX`
path and the originally supplied `~/Downloads/vpinballbuild/` path.

## Evidence and registration

The full service manual is preserved as
`emulation/vpx/reference/Pokemon_Pro_web.pdf` (SHA-256
`50a1906b5c609cd3a84970b6a6e9b0be839b4d0a588d8b27361936ab6537d6bb`).
Rendered PDF pages 16, 20, 25, 41, 42, 49, 51, 52, and 56 through 62 retain
their original page numbers under `emulation/vpx/reference/manual-pages/`.

The primary locator is the target-root asset
`/games/pokemon_pro/assets/nuk/images/Test/pokemon_playfield_pro.png`. The
preserved 451 by 998 grayscale copy has SHA-256
`09477fe9bd50cfeba34bbff2eac5c272fc79eed6a6ed07fc40da636c5fde977b`.
Three user-supplied machine photographs are preserved under
`emulation/vpx/reference/photos/`; their hashes and the inspectable crop used
to register the overhead photograph are recorded in `emulation/vpx/layout.json`.

The single locator-to-table transform into the 952 by 2115 VPX plane is:

```text
VPX x = source x * 952 / 451
VPX y = source y * 2115 / 998
```

`emulation/vpx/qa/layout-overlay.png` places the actual buffered collision
polygons, their source centerlines, ramp
centerlines, switches, lamps, and coils over the locator.
`emulation/vpx/qa/photo-geometry-overlay.png` applies the same trace to the
registered overhead photograph. The generator retains review tolerances of 4
source pixels for lamp centers, 8 pixels for switch/coil markers, and 6 pixels
for major wall/ramp edges unless explicitly marked approximate.

## Implemented geometry

`emulation/vpx/layout.json` is the versioned manifest. Its records carry a
stable VPX name, coordinates, evidence page, confidence, dimension provenance,
and Z profile where applicable. The current lower and main playfield includes:

- separate center, left-outlane, and right-outlane drains with open apron
  mouths, registered outlane switches, return guides, inlanes, and a contained
  shooter lane;
- 13 continuous rail paths, 18 posts, 4 rubber guides, 2 slingshots,
  2 flippers, 2 pop bumpers, the apron, drain area, and trough proxy;
- 7 ball paths: jump ramp, left clear return, Pikachu ramp, Poke Ball ramp,
  main four-wire return, its attached elevated side branch, and shooter-lane
  guide, plus the left and right orbits;
- 20 target areas covering BATTLE, Team Rocket, Berry, Psyduck, lower banks,
  arena, spinner, and captive/Newton-ball positions;
- Town right-eject VUK, Poke Ball hold, closed captive-ball enclosure with a
  retained ball, three one-way gates, and two functional ramp posts; and
- low, noncollidable envelopes for Meowth, Pikachu, Poke Ball, and the Town
  billboard, plus reusable detailed meshes for 18 guide posts and 2 pop-bumper
  caps. Mesh appearance is separated from native VPX collision bodies.

The first lower-playfield pass had two confirmed defects: apron walls closed
the outlane drain mouths, and the right guide post pinched a standard VPX ball
against the shooter wall. The current geometry leaves both drain mouths open
and places the right post on the inner guide with verified ball clearance.

The first served-ball pass also left the ball locked in the enabled
`BallRelease` cup, so a moving plunger could not affect it. The current script
disables that capture cup immediately after release, the served ball seats 20
VPX units ahead of the resting plunger face, and the shooter guide is a
noncollidable visual guide over the playfield rather than an artificial ramp
surface. The containing shooter walls extend behind the full plunger stroke.

The next shooter pass found two additional confirmed faults. First, the
33-source-pixel shooter channel and thick collision walls left only a few VPX
units of side clearance around a 50-unit ball, causing severe rail scrub.
Second, the right wire-ramp side part was incorrectly modeled as a second
playfield-level return. Its low duplicate landing crossed the shooter path at
approximately source y=700. Manual page 41 identifies parts `515-1094-00` and
`515-1094-01` as the main and attached side wire ramps. The side geometry now
merges into the elevated main return at source `(382,530)`, the shooter channel
retains at least 18 VPX units of validated free-running clearance, and a
full-pull plunger speed of 150 reaches the main-playfield checkpoint. The live
trace reached VPX y=1321.1 and logged `plunger launch entered main playfield`.

The base collision layer was then rebuilt rather than patched. The old
generator emitted one closed rectangle for every centerline segment, yielding
39 independent wall objects with overlapping square ends and internal contact
faces at bends. The replacement buffers each complete centerline into one
rounded polygon. Connected evidence paths were consolidated before buffering:
five cabinet/back pieces became one U-shaped perimeter, the shooter sides and
stop became one U-channel, and the Town VUK back/right walls became one L-shaped
perimeter. Runtime collision walls are invisible and visual rails are separate,
non-colliding copies. `qa/collision-topology.json` records polygon vertex count,
winding, area, and intersection count; `qa/collision-validation.json` enforces
13 collision objects, 13 visual objects, zero old segment objects, and zero
self-intersections. Live plunger and mechanism tests passed after this rebuild.

## Construction layers and mechanical assets

`emulation/vpx/layer-map.json` defines 16 stable editor layers: base playfield,
cabinet/apron, hidden collision rails, visual guides, mounted hardware, targets, plastics/proxies,
flat ramps, wireforms, toys/models, switches/sensors, feature lamps,
GI/flashers, coil markers, script controllers, and QA. Collision, electrical,
script, and QA layers are hidden by default. This separates construction level from
electrical/debug overlays without changing runtime names.

The Pinball Makers Files Section was reviewed as a source of comparable
mechanical references. It warns that community files are untested. Three
original private-development references are preserved under
`emulation/vpx/assets/cad-reference/`: star post `PL-00172-OT`, faceted post
`C-11561-20`, and WPC pop-bumper assembly `B-9414`. Because the files are
SolidWorks documents and no reliable local SolidWorks importer is available,
the embedded OBJ assets are new Blender reconstructions rather than converted
upstream geometry. Hashes, source URL, and the CC BY-NC-SA/noncommercial
boundary are recorded in `emulation/vpx/assets/README.md`.

The hardware layer retains 45 playfield switches, 11 mechanism/trough sensors,
13 coil locations, and 113 physical lamps: 73 feature inserts, 10 flashers,
and 30 GI bulbs. SPIKE addresses remain attached to stable names such as
`sw_right_eject`, `sw_left_ramp_enter`, and `lamp_battle_b_lamp`. The controller
plugin mapping is generated directly from these manifest records.

Five local extracted images are embedded as noncolliding Pikachu, Meowth,
Psyduck, Eevee, and Poké Ball decals on replaceable proxy toys/plastics. The
registered overhead photograph remains the playfield texture. These images,
the photograph, reference manual, and game content are private-use evidence
and must be excluded from a redistributable VPX package.

## Standalone and integrated behavior

The table-side VBS is self-contained. `1` starts or serves, left/right Shift
operate the flippers, holding Return pulls the plunger, releasing Return fires
it, and Escape exits. Pops and
slings use VPX physics; switch hits are logged and pulse corresponding lamps;
ramp posts operate; Town and Poke Ball kickers capture and eject; the captive
ball is loaded at initialization; and all three drains destroy and re-serve a
test ball. A watchdog also recovers a play ball lost outside a legal drain.

In `spike3`, all physical switch make/break states and debounced contacts go to
the pinned native controller plugin. QEMU is authoritative for every lamp and
driver action. Flippers, slings, pops, ejects, trough release, auto-launch,
posts, gate, and Meowth therefore do not animate speculatively. If the plugin
or bridge is absent, the table de-energizes mechanisms and does not silently
fall back. Standalone remains independent and explicitly selectable.

`qa-spike3` waits for synchronization and a short game-settle period, sends
coin and Start, samples 32 alternating left/right press-release cycles through
the real QEMU driver path, then sends action. Six-field driver records preserve
both server-output-to-VPX and matching input-to-VPX drain latency.

## Confidence boundary and next work

Top-down placement and hardware marker counts are evidence-backed. Ramp
heights, clearances, and several hidden collision envelopes are still labeled
as comparable-Stern estimates; no art, script, model, or game-specific
geometry was copied from the comparison table.

The assembled file, initialization, manual-plunger launch onto the main
playfield, all three drains, both outlane switch/drain paths, Town VUK, Poké
Ball hold, captive-ball load, QEMU-authoritative sling release, mapped
mechanism actions, private playfield texture, and short inventory soak are
live-tested in VPX. A combined QEMU+VPX run is separately required to prove the
genuine game's progression and timing.

Full physical traversal of every elevated ramp/orbit, the 60-minute soak,
normal three-ball completion, multiball, and direct physical Z/force
measurement remain follow-up acceptance. The current mechanical meshes are
comparable parts and decal-backed proxies, not measured Pokémon-specific
assemblies. QEMU supplies scoring, display, speech, music, and game effects;
VPX supplies only table physics and mechanical sounds.