# retro-remote-debug-controller

A tiny, portable **HTTP control API for retro-platform emulators**, and the
shared tooling that speaks it. One contract → one test harness across every
Doomsday One port.

An emulator launched with a control-port flag exposes a localhost HTTP server:

| Endpoint | Returns | Since |
|---|---|---|
| `GET /status` | contract version, platform, frame counter, paused/running | 0.1 |
| `GET /screenshot` | PPM image of the live screen | 0.1 |
| `GET /mem?addr=&len=&bank=` | raw memory bytes | 0.1 |
| `GET /regs` | CPU registers (JSON) | 0.1 |
| `POST /step?frames=` | advance N frames deterministically | 0.1 |
| `POST /pause` / `POST /resume` | halt / resume the machine | 0.1 |
| `POST /key`, `POST /reset` | inject input / reset | 0.2 |
| `POST /mem?addr=&bank=` | write (poke) memory | 0.3 |
| `GET /audio` | drain synthesised PCM as a WAV | 0.3 |
| `POST /pointer?x=&y=&buttons=` | inject a pointer move/click | 0.4 |
| `GET /pointer` | read back pointer position + buttons | 0.4 |
| `POST /pad?index=&buttons=&connected=` | present a virtual controller, set what is held | 0.5 |
| `GET /pad?index=` | read back a pad's presence + held buttons | 0.5 |
| `GET /perf?windows=&frames=&since=` | performance metrics: the frame budget, work/idle/IRQ cycles, statistics windows, zones, raw frames | 0.6 |
| `POST /perf` | performance settings (JSON body): target FPS, idle mode, history, zones and marker names | 0.6 |

`/status` also lists `capabilities` from 0.6: the groups a server serves,
whatever level it reaches.

Current contract: **0.6.0**. Minors are purely additive (a missing capability
returns 501 and lowers the advertised contract), so a client reads
`/status.contract` and fails fast only on a MAJOR mismatch. See [SPEC.md](SPEC.md).

## Why

Every one of these ports (Pac-Man on X16, Neo6502, Agon, and NEC PC-FX; and
whatever's next) is chasing **frame-exact** arcade fidelity, and every one had
its own fragile, platform-specific way to check state headless (write to the SD
card, dump 64 KB of RAM on a magic jump, grep stdout — which lies). This
replaces all of that with one contract:

- **`GET /mem`** → assert game state (sprite table, actor positions);
  **`POST /mem`** pokes it back for setup.
- **`GET /screenshot`** → Pillow → assert pixels, or just catch "nothing
  rendered" (the exact class of bug that costs an afternoon otherwise).
- **`POST /step`** → deterministic, frame-addressable capture, so CI diffs don't
  flake against a free-running 60 Hz loop.
- **`POST /key`** → drive input; **`GET /audio`** → assert the sound a stepped
  window produced.

The payoff is uniformity: the same `emu_control.py` and the same pytest patterns
drive the X16, Neo6502, Agon, and PC-FX emulators.

## Layout

```
SPEC.md                 the normative HTTP contract (start here)
core/retro_control.h    portable backend vtable each emulator implements
core/retro_control.c    shared server: sockets, HTTP, PPM/JSON, marshalling
client/emu_control.py   shared pytest client (stdlib; Pillow optional)
conformance/            a platform-agnostic pytest that proves an emulator conforms
CHANGELOG.md            the additive contract history
```

## Adopting it in an emulator

Two first-class paths (both normative in [SPEC.md](SPEC.md#adoption-paths)):

- **Vendor the shared core** — for C/C++ emulators. Add this repo as a git
  submodule, compile `core/retro_control.c`, implement the backend callbacks,
  and wire three loop hooks. The socket loop, HTTP parsing, PPM/JSON encoding
  and pause/step control come for free.
- **Conform only** — for emulators in other languages (the FAB Agon emulator is
  Rust). Keep your own HTTP server; just match the contract and pass the
  conformance suite. Sharing the C core is an optimization, not a requirement.

The vendor path is one backend struct plus three hooks:

```c
#include "retro_control.h"

/* Four callbacks satisfy 0.1; add inject_key/reset for 0.2,
   write_mem/capture_audio for 0.3, set_pointer/get_pointer for 0.4,
   set_pad/get_pad for 0.5, get_perf/set_perf for 0.6.
   A NULL callback 501s its endpoint. */
static const retro_control_backend_t backend = {
    .platform        = "x16",
    .emulator        = "x16emu",
    .read_mem        = x16_read_mem,         /* debug-read, no side effects */
    .get_regs_json   = x16_get_regs_json,
    .get_framebuffer = x16_get_framebuffer,
    .get_frame_count = x16_get_frame_count,
    .inject_key      = x16_inject_key,       /* 0.2 */
    .reset           = x16_reset,            /* 0.2 */
    .write_mem       = x16_write_mem,        /* 0.3 */
    .capture_audio   = x16_capture_audio,    /* 0.3 */
    .set_pointer     = x16_set_pointer,      /* 0.4 */
    .set_pad         = x16_set_pad,          /* 0.5 */
    .get_pointer     = x16_get_pointer,      /* 0.4 */
    .get_perf        = x16_get_perf,         /* 0.6: malloc'd JSON */
    .set_perf        = x16_set_perf,         /* 0.6 */
};

if (control_port)                 /* set by -controlport / --control-port / env */
    retro_control_start(control_port, &backend);
```

Stepping and pausing are driven cooperatively from the emulator's main loop, not
by a callback — three hooks at a frame boundary:

```c
retro_control_service();                 /* run a pending request on the emu thread */
if (!retro_control_running()) { idle; }  /* gate advancing the machine (pause/step) */
... run one frame ...
if (frame_completed) retro_control_on_frame();   /* tick the /step budget */
```

## Status

Contract **0.5.0**, implemented across **four** emulators. The shared server and
the conformance suite (22 tests) are complete; tests gated *above* the server's
advertised level skip, so a 0.1-only backend still passes.

Reference implementation: the Commander X16 fork (`x16-emulator`), which vendors
`core/` as a git submodule; the NEC PC-FX fork (Mednafen) does the same, and the
FAB Agon emulator conforms directly in Rust.

> **Known gap — cumulative levels vs. absent devices.** A level is advertised
> only when *all* its callbacks are present, so a platform that lacks a device
> cannot advertise past it without supplying a stub. The PC-FX has no pointing
> device: it stubs `/pointer` to 400 in order to advertise **0.5.0** for the
> `/pad` support it genuinely has — but the suite gates the pointer tests on
> `minor >= 4`, so they then *run* and fail. Measured against the PC-FX fork:
> **19 passed, 3 failed**, the three being pointer tests. A single cumulative
> integer cannot express "has pad, has no pointer"; this needs either a
> per-capability declaration in `/status` or a conformance rule that treats a
> documented "no such device" 400 as a skip.