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:

emulation/vpx-rebuild/build.sh

Run the table without QEMU for a physics/rendering check:

emulation/vpx-rebuild/run-standalone.sh

Run the native QEMU/VPX cabinet path:

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.

11 KiB Raw Blame History