# Native macOS Playable Table

## Status

The first native playable-cabinet implementation lives under `emulation/`.
It combines two existing, 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 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 development recreation; it is not yet a playable release
and 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`.

### Current stop points (2026-07-14)

The latest native launch is blocked first by a VPX script error:

```text
Runtime error: Variable is undefined: 'Service1Key'
```

The table uses the unsupported legacy names `Service1Key` through
`Service4Key`. The pinned VPX host exposes those actions as
`VPXActionKey(25)` through `VPXActionKey(28)`. Since the references are inside
the common key handler, an input event can abort before even non-service input
is forwarded. This must be repaired and exercised in the native host before
the cabinet path can be called playable.

The next confirmed blocker is the power-distribution input model. Start and
Action physically enter the power-distribution board and are returned to the
game by command `0x15`, active-low in bits 1 and 0. Bit 2 is the active-low
cabinet-door input. The current generic `0xff` response therefore leaves both
buttons released and the door open, which is consistent with the observed
factory/pre-play setup screen remaining stuck. Correct idle/Start/Action/both
responses are `0x03`, `0x01`, `0x02`, and `0x00` respectively.

Separately, the game's CPU-SPI receive alignment is `00 || rx[0..6]`.
`0-SW-23` must therefore be raw byte 1 bit 7 low, making the correct idle raw
SPI record `ff7fffffffffffff`. The complete ordered plan and acceptance
checklist are in `emulation/VPX_EMULATOR_STATUS.md` in the parent emulator
repository.

## 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/vpx/layout.json` is the single mapping source. It records 45
playfield switches plus 11 sensors, 13 drivers, 113 logical lights expanded to
150 exact SPIKE channels, six serveable trough balls, and a separate captive
ball. The plugin mapping header is generated from this manifest by
`emulation/vpx-plugin/generate-layout-mapping.py`; it is not a second
handwritten address map.

## 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`: preserves the self-contained greybox rules and mechanisms.
- `spike3`: QEMU is authoritative for lamps and every driver-driven mechanism.
- `qa-spike3`: integrated handshake/input/output acceptance without falling
  back to standalone behavior.
- Other `qa-*` modes are deterministic native geometry, shot, sling-authority,
  plunger, and inventory checks documented in `emulation/vpx/README.md`.

In integrated mode, a missing controller is fail-safe: the table remains in
SPIKE mode, disables standalone serving/GI, de-energizes mechanisms, and logs
the error. It does not silently animate local flippers. Physical flippers,
slings, pops, trough eject, auto-launch, posts, gate, Meowth motor, and ejects
move only from mapped game driver pulses.

## Physics and private visual assets

The versioned `pokemon-pro-vpx-physics/v1` record in
`emulation/vpx/layout.json` fixes the inspected service-manual values at a
6.5-degree pitch, 1-1/16-inch steel ball, and 50 Shore A rubber. Every physics
or dimension value is tagged `manual`, `photo_estimate`, `comparable_part`, or
`playability_tuned`.

The registered overhead photograph is the provisional playfield texture; the
manual locator remains a hidden registration/QA layer. Reconstructed post and
pop meshes sit over simple collision bodies. Extracted Pokémon images are used
only as local toy decals or temporary plastics, and unmeasured toys/wireforms
remain labeled proxy geometry. The table, extracted artwork, reference photos,
manual, and game audio are private-use inputs 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, right trigger, or right stick | Plunger/launch |
| `1` or Menu | Start |
| `5` or View | Coin |
| Return, Left Option, or A | Action |
| `7`/`8`/`9`/`0` or D-pad | Service back/down/up/enter |

VPX 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.
- `emulation/vpx/build.sh` plus `emulation/vpx/qa.sh` verifies the assembled
  VPX, source round-trip, exact mapping counts, physics tags, ball inventory,
  and collision topology.
- The native `emulation/vpx/qa-*.sh` launchers exercise VPX itself rather than
  only inspecting generated JSON.
- A complete cabinet run additionally has to prove the real QEMU game accepts
  inputs/physical switches and drives VPX mechanisms through the live bridge.

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.
