194 lines
11 KiB
Markdown
194 lines
11 KiB
Markdown
# 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.
|