pokemon_pinball_wiki/native-playable-table.md

# Native macOS Playable Table

## Status

The native playable-cabinet implementation lives under `emulation/`. It
combines two independently useful runtimes:

- QEMU 11 with HVF runs the generated ARM64 guest and genuine Pokémon Pro game
  code. Its Cocoa window and CoreAudio output are the backbox, game display,
  music, speech, and game effects.
- Visual Pinball X 10.8.1 owns the physical balls, collision geometry,
  switches, trough inventory, and moving playfield mechanisms.

The default VPX frontend is now the clean-room table assembled at
`emulation/vpx-rebuild/dist/PokemonPro_Rebuild.vpx`. The supported first
release is deliberately two-window. It does not use VNC,
noVNC, browser capture, JPEG screendumps, or the dashboard for gameplay. The
dashboard remains an optional diagnostic monitor. This is an
evidence-calibrated playable development recreation; it is not a
measurement-validated replica of ramp heights, coil forces, or rebound curves.

The one-command Finder entry point is `emulation/run-playable.command`; the
terminal entry point is `emulation/scripts/run-playable-macos.sh`.

### Clean rebuild workflow

With no table override, `emulation/scripts/run-playable-macos.sh` runs
`emulation/vpx-rebuild/build.sh` and selects
`emulation/vpx-rebuild/dist/PokemonPro_Rebuild.vpx`. The maintained sources are
`design/geometry.json`, `design/lights.json`, the VBS template, procedural
assets, and generator under `emulation/vpx-rebuild/`; generated `source/` and
`dist/` files must not be hand-edited. `emulation/vpx-rebuild/run-standalone.sh`
provides the short no-QEMU physics/render path.

`SPIKE3_VPX_TABLE` still permits an explicit custom table. If that table needs
a preparation step, set `SPIKE3_VPX_BUILD`; setting the custom table without a
build override prevents the clean rebuild script from modifying it. The
historical `emulation/vpx/PokemonPro_Greybox.vpx` and
`emulation/vpx/manual/PokemonPro_Manual.vpx` are deprecated historical
artifacts. The clean workflow does not inspect or write either file, and
neither is the active geometry source or default.

### Current stop point (2026-07-20)

The bridge now ingests host events immediately and routes service controls over
active-low CPU-SPI. Start and Action use the installed power-distribution
command `0x15` path, including unsolicited input reports. The genuine display
has acknowledged service navigation, and protocol tests cover a Start change
without a preceding host poll. Those are transport results, not a completed
game.

The clean table and canonical hardware contract pass their static validators.
`emulation/vpx-rebuild/qa/runtime-smoke.log` records a bounded VPX 10.8.1
`CaptureAttract` pass on the exact current table SHA-256
`ddce5d48033ee3c6e67248910a73897293e8b9c36eee29df164160a93572a30e`,
with table/VBS load, script compile/start, Metal initialization, two rendered
frames, clean close, and exit code 0. In integrated modes,
the clean script publishes physical contacts, consumes exact-address lamp
components, preserves ordered driver pulses, establishes reconnect baselines,
and releases transients/mechanisms on disconnect. Cabinet edges move the
flippers locally while cabinet/EOS state is still sent to the genuine game.

The final clean table also completed the supervised native QEMU/VPX startup
gate on 2026-07-20. The accepted session reached `Playable cabinet connected`
with synchronized VPX physics, 392 lamp updates, 7 LED frames, 1 driver pulse,
stable captive-ball contacts, and QEMU-keyboard coin/Start press-release
records. The default hardware-output wait is 420 seconds because normal game
initialization can take about five minutes. A transient bridge blip is accepted
only after a later synchronized reconnect; unrecovered disconnects still fail
closed.

The remaining immediate cabinet gate is completing and preserving a genuine
normal game cycle. The generated QEMU disk is writable and persistent, but the
current conagent `data_store` model is memory-only. After that gate, the final clean table still needs a captured normal game,
multiball, full physical shot coverage, integrated RGB/driver/mechanism traces,
restart recovery, and a 60-minute inventory soak. Earlier greybox/manual
runtime logs remain useful historical bridge evidence, but they do not prove
the clean table's geometry or final trajectories.

## Runtime ownership

| Concern | Authority |
| --- | --- |
| Rules, scoring, player/ball progression | Genuine game process in QEMU |
| Display, music, speech, game effects | QEMU Cocoa/CoreAudio |
| Ball physics and collision geometry | Native VPX at a 1,000 Hz physics step |
| Physical switch state and pulses | VPX table script and controller plugin |
| Lamps and mechanism driver commands | Genuine game through netbridge |
| Mechanical ball/rubber/flipper/gate sounds | VPX only |
| Window placement and focus | Native macOS helper |

`emulation/playfield-contract/pokemon-pro-hardware.json` is the canonical
geometry-free mapping. It records 45 playfield switches, 11 sensors, 9 cabinet
controls, 13 drivers, and 113 logical lamps expanded to 176 component bindings
at 150 exact SPIKE addresses. The plugin mapping header is generated from this
contract by `emulation/vpx-plugin/generate-layout-mapping.py`; it is not a
second handwritten address map. Ball inventory and placement live separately
in the clean geometry/script rather than becoming transport fields.

## Playfield protocol and safe recovery

`analysis/netbridge-emulator/netbridge_emu.py` provides a persistent,
loopback-only JSONL endpoint at `127.0.0.1:8091` using
`spike3-playfield/v1`. VPX sends `hello`, `switch.set`, `switch.pulse`,
`cabinet.set`, `release_transient`, and `heartbeat`. The bridge sends complete
`snapshot` records, coalescible `lamp.delta` records, lossless ordered
`driver.pulse` records, and `status` records.

Every server record has a process-unique `bridge_session`, a monotonic launcher
`bridge_generation`, sequence, model revision, and monotonic timestamp. A new
connection is not considered ready after TCP connect or `hello`. The bridge
first sends a disconnected snapshot and `synchronizing`; the plugin releases
transients, restores stable switch/cabinet state, and sends a heartbeat as an
ordering barrier. The bridge reports `ready` and sends QEMU monitor `cont` only
after that barrier and after the guest UART is connected.

With `physics_authority=vpx`, the netbridge synthetic shooter, trough, outlane,
VUK, flipper-EOS, and ball-return shortcuts are disabled from process start.
On a VPX disconnect, transient contacts open, VPX mechanisms de-energize,
stable trough/held-ball contacts remain, and QEMU receives monitor `stop`. A
supervised bridge restart removes the old readiness record, restores only
stable contacts plus lamp/driver snapshot baselines, assigns a new session and
generation, and never replays cumulative driver counts as new pulses.

The implementation and synchronization tests are in
`analysis/netbridge-emulator/test_netbridge_emu.py`. The native supervisor is
`emulation/scripts/run-macos.sh`; the outer cabinet lifecycle and identity
checks are in `emulation/scripts/run-playable-macos.sh`.

## VPX plugin and table modes

`emulation/vpx-plugin/` is rebased to the installed VPX commit
`ca80d1604e6a525db2a3f6d1ec704fc651d573fa`. Its builder checks the exact Git
revision, host binary SHA-256, ARM64 architecture, and bundle version before
writing `emulation/work/vpx-plugin/Spike3Controller/vpx-host-attestation.txt`.
The playable launcher copies the attested app to a private workspace runtime,
installs the matching plugin there, and ad-hoc signs that private copy. It does
not modify the user's source VPX app.

Network work runs on a background thread. Bounded queues keep socket I/O away
from VPX's render/physics thread; lamp state is coalesced, while driver events
retain order and cumulative counters. Reconnect snapshots establish a driver
counter baseline and cannot become stale physical events.

The table has explicit modes:

- `standalone`: provides local serving, flipper/plunger control, and mechanism
  behavior for no-QEMU physics/render checks.
- `spike3`: QEMU is authoritative for lamps and every driver-driven mechanism.
- `qa-spike3`: integrated handshake/input/output acceptance without falling
  back to standalone behavior.

In integrated mode, a missing controller is fail-safe: the table remains in
SPIKE mode, disables standalone serving/GI, de-energizes driver-controlled
mechanisms, and logs the error. Flippers are the deliberate exception to game
driver ownership: cabinet buttons actuate them locally and publish their
cabinet/EOS states to the bridge. Slings, pops, trough eject, auto-launch,
posts, gate, Meowth motor, and ejects move only from mapped game driver pulses.

## Physics and private visual assets

`emulation/vpx-rebuild/design/geometry.json` is the active clean-room geometry
and physics source. It fixes a 952 by 2115 VPX plane, 6.5-degree pitch, and
standard 50-unit-diameter ball. XY references follow the full 451 by 998 Pro
locator registration; Z paths, clearances, restitution, friction, coil force,
and mechanism timing remain simulation values until measured on a physical Pro
machine. `design/lights.json` independently records lamp placement and
confidence rather than deriving visual coordinates from the transport map.

The deterministically registered official Pro photograph is the provisional
playfield texture; it retains photographed hardware, shadows, and lighting
under the separately rendered VPX geometry. Original procedural meshes provide
posts, hardware, toys, and mechanisms, and the CC0 mechanical bank supplies
physics audio without copying game samples. The table, official photograph,
Pokemon/Stern imagery, reference manual, and assembled output are private-use
artifacts and are excluded from any redistributable package.

## Controls and native windows

The launcher writes a private VPX input profile without overwriting existing
service bindings. Defaults are:

| Input | Function |
| --- | --- |
| Left/Right Shift or LB/RB | Flippers |
| Return, Space, A, or right trigger | Action/launch |
| `1` or Menu | Start |
| `5` or View | Coin |
| `7`/`8`/`9`/`0` or D-pad | Service back/down/up/enter |

The QEMU guest keyboard relay now implements the same map as VPX. Previously,
only Shift was a cabinet control when the Cocoa backbox had focus; Return and
`1` through `9` still used an obsolete diagnostic switch map. That produced the
observed failure where flippers navigated Guided Setup while Start, coin,
Action, and service keys did nothing useful. The corrected relay maps `1`,
`5`, Return/Space, and `7`/`8`/`9`/`0` to the named cabinet inputs above.

The 2026-07-15 generated rootfs was rebuilt with the correction. The installed
AArch64 `/usr/local/spike-emu/bin/keyboard-switch-relay` was extracted from the
ext4 image and matched an independent source build at SHA-256
`55054003950873900b5ce203292846f158b861060dbdd2e04b5be4a8afa1869c`.
A headless QEMU monitor test injected all ten keys and
`emulation/work/logs/keyboard-relay.log` recorded matching press/release pairs
for both flippers, Start, coin, Action twice, and all four service controls.
That event-name check alone was insufficient: CPU and powerdist contacts do
not pass through a node input-bank poll. The playfield bridge now runs a
bounded host-event pump which routes those edges to their real transports
immediately while leaving ordinary node-bus edges queued until the relevant
bank read. The cabinet aliases and routes are loaded from
`emulation/playfield-contract/pokemon-pro-hardware.json`.

VPX normally receives focus. On two displays the AppKit/Accessibility helper attempts a
fullscreen VPX playfield plus fullscreen QEMU backbox. On one display it uses
approximately 65% for VPX and 35% for a 16:9 backbox. If Accessibility access
is declined or a window does not expose fullscreen through AX, both processes
remain running and the launcher prints the saved placement log and manual
layout.

## Verification boundary

The reproducible checks are split by what they prove:

- `python3 -m unittest discover -s analysis/netbridge-emulator -v` verifies
  recovered serial behavior, protocol ordering, output identity, safe pause,
  snapshot restore, synchronization, and lossless driver delivery.
- `emulation/vpx-plugin/tests/run-tests.sh` verifies the generated mapping,
  background client, ordered input edges, output records, driver baseline, and
  reconnect behavior against a loopback server.
- `python3 emulation/playfield-contract/validate_contract.py --json` verifies
  the geometry-free schema, channel counts/routes, manual evidence, consumer
  loading, and generated-header parity.
- `emulation/vpx-rebuild/build.sh` regenerates assets/source, verifies the
  assembled VPX, compares the round-trip VBS, and runs contract/object,
  geometry, clearance, lamp-route, audio, and no-ball-teleport checks recorded
  in `emulation/vpx-rebuild/qa/rebuild-validation.json`.
- `emulation/vpx-rebuild/qa/runtime-smoke.log` records the exact current table
  loading, compiling/starting its script, rendering two frames, and closing
  with exit code 0 under VPX 10.8.1 `CaptureAttract`. It does not claim
  interactive ball or mechanism coverage.
- The accepted live cabinet startup proves the real QEMU game returned lamp,
  LED, and driver output through the final table/plugin path and received
  QEMU-keyboard coin/Start edges. It does not prove a complete normal game.

Do not infer a normal three-ball game, multiball, measured frame-rate percentile,
or 60-minute invariant soak from the static/unit suites. Those acceptance rows
must remain explicitly open until their corresponding native run logs exist.

## Optional composed backbox

QEMU D-Bus shared-memory scanout is a follow-up only. It must demonstrate
correct page flips, sustained 60 fps for ten minutes, and no more than one
added frame before being connected to a VPX Backglass/ScoreView texture. The
working two-window Cocoa path remains the fallback; VNC/browser/screendump
capture is not an accepted gameplay fallback.