# 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
<https://www.sternpinball.com/game/pokemon/>. 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.
