# 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 |
|---|---|
| `GET /status` | contract version, platform, frame counter, paused state |
| `GET /screenshot` | PPM image of the live screen |
| `GET /mem?addr=&len=&bank=` | raw memory bytes |
| `GET /regs` | CPU registers (JSON) |
| `POST /step?frames=` | advance N frames deterministically |
| `POST /key`, `/reset` | *(0.2)* inject input |

## Why

Every one of these ports (Pac-Man on X16, Neo6502, Agon; 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).
- **`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.

The payoff is uniformity: the same `emu_control.py` and the same pytest patterns
drive the X16, Neo6502, and Agon 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  [next]
client/emu_control.py   shared pytest client
conformance/            tests an emulator runs to prove it conforms          [next]
```

## Adopting it in an emulator (the shape)

Write the server once, adapt per fork. Each fork vendors `core/` and implements
~5 callbacks, then calls the server:

```c
#include "retro_control.h"

static retro_control_backend_t backend = {
    .platform       = "x16",
    .read_mem       = x16_read_mem,      /* debug-read, no side effects */
    .get_regs_json  = x16_get_regs_json,
    .get_framebuffer= x16_get_framebuffer,
    .step_frames    = x16_step_frames,
    .get_frame_count= x16_get_frame_count,
};

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

The socket loop, HTTP parsing, PPM encoding, JSON framing, and the
enqueue-to-emulator-thread marshalling live in the shared core — not in three
different codebases.

## Status

Early. `SPEC.md` (0.1.0) and the interfaces below are the stable target the
forks build against; the server `.c` and conformance suite are landing next.
Reference implementation: the Commander X16 fork (`x16-emulator`).