# Pokemon Pro VPX Clean Rebuild ## Status The active Visual Pinball X implementation is the from-scratch Stern Pokemon Pro rebuild under `emulation/vpx-rebuild/`. Its local assembled output is `emulation/vpx-rebuild/dist/PokemonPro_Rebuild.vpx`; the default native cabinet launcher builds and selects that file through `emulation/scripts/run-playable-macos.sh`. `emulation/vpx/PokemonPro_Greybox.vpx` is deprecated historical work. The clean rebuild generator does not inspect or write it, and it is not a generator input, geometry source, build dependency, or runtime default. The rebuild also does not import the legacy `emulation/vpx/layout.json`, script, materials, models, or coordinates. The clean table targets the **Pro** edition only. VPX owns balls, contacts, collision, mechanical motion, rendering, and mechanical sound. The genuine game running in QEMU remains authoritative for rules, scoring, display, music, speech, lamp levels, and ordered mechanism-driver pulses. The complete native cabinet path is documented in `native-playable-table.md`. ## Evidence and edition scope The design basis and source URLs are recorded in `emulation/vpx-rebuild/design/REFERENCE.md`. The official product-family page provided for edition verification is . Primary evidence is: - Stern's official Pokemon Pro product photography and feature information; - the official Pokemon Pro service and game manual, preserved locally as `emulation/vpx/reference/Pokemon_Pro_web.pdf` with SHA-256 `50a1906b5c609cd3a84970b6a6e9b0be839b4d0a588d8b27361936ab6537d6bb`; - Stern's Pro/Premium/LE feature matrix and official overview/gameplay video; and - the extracted target-root Pro locator `/games/pokemon_pro/assets/nuk/images/Test/pokemon_playfield_pro.png`. The 451 by 998 locator is registered to a 952 by 2115 VPX-unit playfield. It is used for XY placement, while official manual assemblies and photographs constrain paths and mechanism identities. The table implements the Pro layout: two lower flippers and slings, dual inlanes/outlanes, right shooter lane, Bulbasaur outer-left orbit, Squirtle left ramp, Pikachu right ramp, Charmander right orbit/spinner, two Tall Grass pops, six BATTLE targets, motorized Meowth, the Pokedex captive/Newton-ball area, Town scoop/VUK, static Pro Poke Ball with stop post, and the Pro Psyduck stand-up target. Premium/LE-only moving Poke Ball, animatronic Pikachu, arena magnet, whirlpool, and Psyduck scoop behavior are excluded. Secondary photographs are useful for cross-checking, but official Stern evidence controls when sources differ. ## Sources of truth and generated artifacts The rebuild is generator-owned. Its maintained inputs are: | Path | Role | | --- | --- | | `emulation/vpx-rebuild/design/geometry.json` | Clean-room XY/Z, collision, mechanism, and physics design with evidence/provenance fields. | | `emulation/vpx-rebuild/design/lights.json` | Independent trace of 113 logical Pro lamp locations and exact component bindings. | | `emulation/playfield-contract/pokemon-pro-hardware.json` | Geometry-free switch, sensor, cabinet, driver, and lamp contract. | | `emulation/vpx-rebuild/script/PokemonPro_Rebuild.vbs.in` | Table behavior and SPIKE 3 integration template. | | `emulation/vpx-rebuild/assets/` | Registered private playfield image plus original procedural models and mechanical audio. | | `emulation/vpx-rebuild/tools/generate_table.py` | Deterministic unpacked-VPX source generator. | `emulation/vpx-rebuild/source/` is generated and must not be hand-edited. `emulation/vpx-rebuild/dist/PokemonPro_Rebuild.vpx` and its `.vbs` sidecar are local build outputs. `emulation/vpx-rebuild/qa/` contains the validation report, round-trip extraction, overlays, captures, and runtime logs. The final verified 2026-07-20 distribution is 5,902,336 bytes with SHA-256 `ddce5d48033ee3c6e67248910a73897293e8b9c36eee29df164160a93572a30e`; the same value is recorded in `qa/rebuild-validation.json` and the matching runtime-smoke log. ## Physical and visual implementation The generator constructs native VPX walls, rails, posts, rubbers, flippers, slings, targets, spinner, gates, kickers, bumpers, ramps, wireforms, plunger, lights, and procedural models. Major retained-ball mechanisms have explicit physical ownership: the Town VUK owns its captured ball, the right-ramp hold kicker retains its ball until the Pikachu post driver releases it, and the Pokedex captive chain is bounded by guides, a Newton target, and a one-way retainer gate. Driver commands are queued briefly for their spatial mechanism envelope rather than moving an unrelated ball. The validator rejects scripted ball teleports. The captive lower/upper optos use circular VPX occupancy volumes and aggregate `BallCntOver` state across all three retained balls. Their construction kickers are disabled seed-only loaders. This avoids the custom polygon trigger's z=50 grazing plane, which produced hundreds of thousands of false make/break edges in the first integrated attempt. The accepted run published one initial state per opto and no continuing idle chatter. The current playfield base is deterministically registered from Stern's official Pro photograph. It preserves authentic visible artwork but is not a bare playfield scan: photographed rails, toys, shadows, and lamps remain baked under separately rendered VPX geometry. Provenance and rejected cleanup experiments are recorded in `emulation/vpx-rebuild/assets/playfield/PROVENANCE.md`. A licensed, stripped playfield scan remains necessary before the base art can be called publication-quality. The active build has 113 logical lamps expanded through the hardware contract to 176 component bindings at 150 exact SPIKE addresses, including 30 RGB logical lamps. Integrated mode consumes exact-address `L` records so separate red, green, and blue levels are retained; the lossy maximum-component compatibility getter is not the primary render path. GI, feature lamps, and flashers are represented by VPX light emitters over the registered trace. Mechanical and physics audio is an original procedural CC0 bank under `emulation/vpx-rebuild/assets/sounds/`. Its 69 synthesized source events cover rolling surfaces and impact, flipper, sling, bumper, target, gate, spinner, kicker, plunger, drain, and mechanism behavior. The assembled table registers the variants and aliases needed by the script. It does not copy sound samples from the game image; QEMU continues to provide licensed music, speech, and game effects. ## Electrical contract and integration behavior `emulation/playfield-contract/pokemon-pro-hardware.json` is the canonical geometry-free mapping. Static validation records 45 switches, 11 sensors, 9 cabinet controls, 13 drivers, and 113 logical lamps. The controller plugin and netbridge load its compatibility projection directly, while the clean rebuild uses its richer channel records for VPX object/event bindings. Physical make/break contacts publish both edges; momentary targets, pops, slings, and spinner events publish pulses. The Town VUK and right-ramp hold are real kicker-owned states rather than dummy triggers. Start and Action retain their installed power-distribution command `0x15` routing, and the service panel retains its live-corrected CPU-SPI routing. In `spike3` and `qa-spike3`, one `D` record is one ordered mechanism pulse. Snapshot driver counts establish reconnect baselines and are never replayed as new physical actions. Flippers are the documented exception: cabinet edges move them locally and publish cabinet/EOS state because the live node-board path does not produce ordinary flipper driver pulses. A disconnected controller causes transient contacts and energized mechanisms to release; it does not silently fall back to standalone rules. Reconnect restores stable state and lamp/driver baselines before new events are accepted. ## Build and run The deterministic build regenerates the registered playfield, procedural models, and audio; generates unpacked source; assembles and imports VBS with `vpxtool`; verifies and round-trip extracts the compound file; compares the script; and runs the rebuild validator: ```sh emulation/vpx-rebuild/build.sh ``` Run the table without QEMU for a physics/rendering check: ```sh emulation/vpx-rebuild/run-standalone.sh ``` Run the native QEMU/VPX cabinet path: ```sh emulation/scripts/run-playable-macos.sh ``` The default controls are left/right Shift for flippers, Return for plunger/action, `1` for Start, `5` for coin, and the configured VPX nudge keys. The QEMU window relays the same cabinet and service controls through the hardware contract. ## Validation record and remaining acceptance The following claims have different evidence boundaries and must not be collapsed into one "playable" result: | Layer | Current evidence | What it does not prove | | --- | --- | --- | | Hardware contract | `python3 emulation/playfield-contract/validate_contract.py --json` passes schema, counts, routes, evidence, consumer loading, and generated-header parity. | Live bridge traffic, rendered lamps, mechanism motion, or gameplay. | | Generated table | `emulation/vpx-rebuild/build.sh` passes audio validation, `vpxtool verify`, exact VBS round-trip comparison, contract/object checks, collision/clearance checks, lamp routes, and the no-ball-teleport rule; details are in `qa/rebuild-validation.json`. | Real-machine dimensions, every shot trajectory, long-session behavior, or QEMU rules progression. | | VPX runtime load | `emulation/vpx-rebuild/qa/runtime-smoke.log` records a bounded VPX 10.8.1 `CaptureAttract` pass on the exact current table SHA-256 `ddce5d48033ee3c6e67248910a73897293e8b9c36eee29df164160a93572a30e`: table/VBS load, script compile/start, Metal initialization, two captured frames, clean close, and exit code 0. | Interactive ball/shot coverage, audible-output quality, or every mechanism sequence. | | Integrated cabinet | The 2026-07-20 native run reached `Playable cabinet connected` with QEMU authoritative, VPX physics synchronized, 392 lamp updates, 7 LED frames, 1 driver pulse, stable captive contacts, and QEMU-keyboard coin/Start press-release records. Shutdown left the bridge disconnected and the QEMU monitor stopped. Plugin/netbridge suites also cover reconnect baselines and ordered delivery. | A complete normal game, multiball, every mechanism/shot, or long-session performance. | | Physical accuracy | Official locator/manual/photo registration supports edition, identities, and top-down placement. | Measured ramp Z, clearances, coil forces, friction/restitution, toy travel, or production-hardware timing. | The next acceptance gate is a complete normal game on this final build, including trough serve, launch, scoring shots, retained-ball mechanisms, drain/next ball, and game over, followed by restart/inventory checks. A multiball sequence, every full ramp/orbit trajectory, 60-minute soak, frame-time percentiles, and direct comparison with a physical Pokemon Pro remain open. In particular, Meowth crank motion and Pikachu post travel are evidence-backed simulations whose production-hardware direction, stroke, and timing still need direct confirmation. The official photograph, Pokemon/Stern character imagery, service manual, and assembled private-use table are assessment artifacts. Do not publish them without the relevant rights. The procedural mechanical audio is CC0, but that does not make the complete table redistributable.