Document VPX emulator status and recovery plan
This commit is contained in:
MrARM
216
vpx-table-recreation.md
Normal file
216
vpx-table-recreation.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user