J Sync 7/21/26

This commit is contained in:
MrARM
2026-07-21 10:45:59 -05:00
parent 32751448c6
commit 8c6547acbd
8 changed files with 451 additions and 302 deletions

View File

@@ -1,216 +1,193 @@
# Pokemon Pro VPX Table Recreation
# Pokemon Pro VPX Clean Rebuild
## 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.
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`.
Confirmed on 2026-07-14 after the continuous-collision rebuild:
`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.
- `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.
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`.
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 edition scope
## Evidence and registration
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:
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/`.
- 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 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 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.
The single locator-to-table transform into the 952 by 2115 VPX plane is:
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.
```text
VPX x = source x * 952 / 451
VPX y = source y * 2115 / 998
## 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
```
`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.
Run the table without QEMU for a physics/rendering check:
## Implemented geometry
```sh
emulation/vpx-rebuild/run-standalone.sh
```
`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:
Run the native QEMU/VPX cabinet path:
- 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.
```sh
emulation/scripts/run-playable-macos.sh
```
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 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.
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.
## Validation record and remaining acceptance
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 following claims have different evidence boundaries and must not be
collapsed into one "playable" result:
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.
| 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. |
## Construction layers and mechanical assets
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.
`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.
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.