0.5.0: game controller injection (POST/GET /pad) bed0f1e524fe

## 0.5.0

- `POST /pad?index=[&buttons=][&connected=]` — present a **virtual game

  controller** and set what is held. `buttons` is the canonical mask (bit0 LEFT,

  1 RIGHT, 2 UP, 3 DOWN, 4 A, 5 B, 6 X, 7 Y, 8 START, 9 SELECT, 10 L, 11 R —

  the SNES/Neo6502 native order, fixed across platforms). `connected=0` unplugs.

  Backend callback: `set_pad`.

- `GET /pad?index=` — read back `{index, connected, buttons}`, so a test can tell

  "the input never arrived" from "it arrived and was ignored". Backend callback:

  `get_pad`.

- A pad is a **level, not an event**: the held mask persists across `/step`

  frames until changed, unlike `/key`'s momentary tap. Conformance asserts this

  directly, because it is the property that makes `/pad` worth having rather

  than reusing `/key`.

- **Virtual, not SDL.** A backend presents a device its existing read path picks

  up rather than driving the host's joystick API. Headless CI has no joystick,

  and that is precisely the case this endpoint exists for.

- Motivation: a real bug that shipped. A port's pad read masked the firmware's

  merged controller down to its d-pad and tried to recover the buttons from the

  wrong controller index — movement worked, fire did nothing, and there was no

  way to catch it without a human holding hardware.

| `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 |

Current contract: **0.5.0**. Minors are purely additive (a missing capability

   write_mem/capture_audio for 0.3, set_pointer/get_pointer for 0.4,

   set_pad/get_pad for 0.5.

    .set_pad         = x16_set_pad,          /* 0.5 */

### `POST /pad?index=<n>  [&buttons=<mask>] [&connected=0|1]`  *(0.5)*

Inject a game controller — the pad analogue of `/key` and `/pointer`. Query

params (no body):

- `index` — which pad, 0-based. OPTIONAL, default 0.

- `buttons` — bitmask of what is HELD, in the canonical layout below. Omitted →

  the button state is left unchanged. `buttons=0` releases everything while

  leaving the pad connected.

- `connected` — OPTIONAL. `1` (the default whenever `buttons` is given) presents

  a **virtual pad** at `index`; `0` unplugs it. Unplugging matters: a program

  that asks "is a controller present" before offering two-player must be

  testable in both states, and on most platforms the count is what it asks.

- Response: `{ "injected": true }`. No controller support on the platform → 400.

Canonical button layout, low bit first:

| bit | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |

|---|---|---|---|---|---|---|---|---|---|---|---|---|

| | LEFT | RIGHT | UP | DOWN | A | B | X | Y | START | SELECT | L | R |

This is the SNES/Neo6502 native order, chosen for the same reason `/pointer`

fixed bit0 = primary: **one layout, defined once, so a test written against one

platform reads the same on another.** A backend whose hardware disagrees — the

X16 KERNAL reports RIGHT/LEFT/DOWN/UP — converts in its own floor. A test never

learns which machine it is on, which is the entire point.

Device-level, not driver-state: the injection MUST exercise the same path a real

pad takes, so what the program reads is what physical hardware would produce. On

an emulator that reads SDL joysticks, that means presenting a virtual pad the

existing read path picks up — **not** driving SDL, which would need a joystick

to exist and defeats the purpose. Headless CI has no joystick; that is the case

this endpoint is for.

Hold across frames: a pad is a LEVEL, not an event. `buttons` stays as set until

changed, so a press survives any number of `/step` frames without re-asserting —

unlike `/key`, whose TAP is deliberately momentary. Release explicitly.

### `GET /pad?index=<n>`  *(0.5)*

Read back a pad. Response:

```json

{ "index": 0, "connected": true, "buttons": 48 }

```

- `connected` — whether anything is present at that index, real or virtual.

- `buttons` — the current mask in the layout above.

- Same job as `GET /pointer`: distinguishes "the input never reached the

  platform" from "it arrived and the program ignored it". No controller support

  on the platform → 400.

    # Canonical pad bitmask (SPEC "Canonical button layout"). The SNES /

    # Neo6502 native order, fixed across platforms so a test written on one

    # machine reads the same on another.

    PAD_LEFT   = 0x0001

    PAD_RIGHT  = 0x0002

    PAD_UP     = 0x0004

    PAD_DOWN   = 0x0008

    PAD_A      = 0x0010

    PAD_B      = 0x0020

    PAD_X      = 0x0040

    PAD_Y      = 0x0080

    PAD_START  = 0x0100

    PAD_SELECT = 0x0200

    PAD_L      = 0x0400

    PAD_R      = 0x0800

    def pad(self, buttons: int | None = None, index: int = 0,

            connected: bool | None = None) -> None:

        """Present a virtual controller and set what is held (contract 0.5).

        `buttons` is a mask of PAD_* — omit to leave the held state alone.

        `connected=False` unplugs the pad, which is testable behaviour in its

        own right: a program that asks whether a controller is present before

        offering two-player needs both answers.

        Unlike key(), a pad is a LEVEL: the state persists across step()

        frames until changed, so a press does not need re-asserting. Release

        with pad(0)."""

        parts = [f"index={index}"]

        if buttons is not None:

            parts.append(f"buttons={buttons}")

        if connected is not None:

            parts.append(f"connected={1 if connected else 0}")

        self._post("/pad?" + "&".join(parts))

    def pad_get(self, index: int = 0) -> dict:

        """GET /pad — {index, connected, buttons} (contract 0.5). Distinguishes

        'the input never arrived' from 'it arrived and was ignored'."""

        body, _ = self._get(f"/pad?index={index}")

        return json.loads(body)

# -- contract 0.5: pad injection (skipped on < 0.5 servers) ------------------

def test_pad_injection(emu):

    """/pad presents a virtual controller and sets what is held. The pad's

    *effect* is platform-specific and tested per-port; the contract surface is

    asserted here."""

    if _contract_minor(emu) < 5:

        pytest.skip("contract < 0.5 (no pad injection)")

    emu.pad(buttons=emu.PAD_A)                      # A held, pad plugged in

    emu.pad(buttons=emu.PAD_A | emu.PAD_LEFT)       # two at once

    emu.pad(buttons=0)                              # all released, still there

    emu.pad(index=1, buttons=emu.PAD_B)             # a second pad

    emu.pad(connected=False)                        # unplug pad 0

    emu.pad(connected=False, index=1)

def test_pad_readback(emu):

    """GET /pad reports {index, connected, buttons} (contract 0.5)."""

    if _contract_minor(emu) < 5:

        pytest.skip("contract < 0.5")

    emu.pause()

    try:

        emu.pad(buttons=emu.PAD_A | emu.PAD_RIGHT)

        emu.step(1)

        st = emu.pad_get()

        assert isinstance(st["buttons"], int)

        assert isinstance(st["connected"], bool)

        assert st["index"] == 0

        assert st["connected"] is True, "injected pad reports itself absent"

        # The mask must survive the round trip: this is the check that

        # separates "the server accepted it" from "the backend stored it".

        assert st["buttons"] == emu.PAD_A | emu.PAD_RIGHT, (

            f"held {st['buttons']:#x}, injected "

            f"{emu.PAD_A | emu.PAD_RIGHT:#x}")

    finally:

        emu.pad(buttons=0)

        emu.resume()

def test_pad_is_a_level_not_an_event(emu):

    """A pad HOLDS. Unlike a key tap, an injected press must survive stepping —

    a program that samples input once a frame has to still see it on frame 10.

    This is the difference that makes /pad worth having rather than reusing

    /key, so it is asserted rather than assumed."""

    if _contract_minor(emu) < 5:

        pytest.skip("contract < 0.5")

    emu.pause()

    try:

        emu.pad(buttons=emu.PAD_B)

        emu.step(10)

        assert emu.pad_get()["buttons"] == emu.PAD_B, (

            "the held mask did not survive 10 frames — /pad is behaving "

            "like a momentary key tap")

    finally:

        emu.pad(buttons=0)

        emu.resume()

def test_pad_unplug_is_observable(emu):

    """connected=0 must actually unplug. A program that offers two-player only

    when a second controller is present needs both answers to be reachable, so

    a backend that always reports 'connected' is not conformant."""

    if _contract_minor(emu) < 5:

        pytest.skip("contract < 0.5")

    emu.pause()

    try:

        emu.pad(buttons=0)                     # plugged in

        assert emu.pad_get()["connected"] is True

        emu.pad(connected=False)

        assert emu.pad_get()["connected"] is False, (

            "the pad still reports connected after connected=0")

    finally:

        emu.pad(connected=False)

        emu.resume()

               REQ_WRITE, REQ_AUDIO, REQ_PTR_SET, REQ_PTR_GET,

               REQ_PAD_SET, REQ_PAD_GET } req_t;

static int      g_pad_index;     /* which pad (0-based) */

static int      g_pad_buttons;   /* held mask, or -1 = leave unchanged */

static int      g_pad_connected; /* 1 plug, 0 unplug, -1 = unchanged */

    case REQ_PAD_SET: {

        const char *json;

        if (!g_be->set_pad) {

            json = "{\"error\":\"not implemented\"}"; g_resp_status = 501;

        } else if (g_be->set_pad(g_pad_index, g_pad_buttons, g_pad_connected)) {

            json = "{\"injected\":true}"; g_resp_status = 200;

        } else {

            json = "{\"error\":\"no controller\"}"; g_resp_status = 400;

        }

        size_t l = strlen(json);

        uint8_t *b = (uint8_t *)malloc(l + 1);

        if (b) memcpy(b, json, l + 1);

        g_resp_body = b; g_resp_len = b ? l : 0;

        g_resp_ctype = "application/json";

        break;

    }

    case REQ_PAD_GET: {

        char *b;

        if (!g_be->get_pad) {

            const char *json = "{\"error\":\"not implemented\"}";

            size_t l = strlen(json); b = (char *)malloc(l + 1);

            if (b) memcpy(b, json, l + 1);

            g_resp_len = b ? l : 0; g_resp_status = 501;

        } else {

            int buttons = 0, connected = 0;

            int ok = g_be->get_pad(g_pad_index, &buttons, &connected);

            b = (char *)malloc(96);

            if (!b) { g_resp_len = 0; g_resp_status = 500; }

            else if (ok) {

                g_resp_len = (size_t)snprintf(b, 96,

                    "{\"index\":%d,\"connected\":%s,\"buttons\":%d}",

                    g_pad_index, connected ? "true" : "false", buttons);

                g_resp_status = 200;

            } else {

                g_resp_len = (size_t)snprintf(b, 96,

                    "{\"error\":\"no controller\"}");

                g_resp_status = 400;

            }

        }

        g_resp_body = (uint8_t *)b;

        g_resp_ctype = "application/json";

        break;

    }

         g_be->set_pointer && g_be->get_pointer &&

         g_be->set_pad && g_be->get_pad) ? "0.5.0" :

        (g_be->inject_key && g_be->write_mem && g_be->capture_audio &&

        }

        return;

    }

    if (!strcmp(target, "/pad")) {

        g_pad_index = (int)query_long(query, "index", 0);

        if (is_post) {                        /* 0.5: present / set a pad */

            g_pad_buttons = (int)query_long(query, "buttons", -1);

            /* `connected` defaults to plugging it in whenever buttons were

             * given -- injecting a press on an absent pad is never what the

             * caller meant -- and to leaving it alone otherwise. */

            g_pad_connected = (int)query_long(query, "connected",

                                              g_pad_buttons >= 0 ? 1 : -1);

            do_marshalled(fd, REQ_PAD_SET);

        } else {                              /* 0.5: read a pad back */

            do_marshalled(fd, REQ_PAD_GET);

 * whose backend callbacks are all present: 0.5.0 needs set_pad + get_pad (on

 * top of 0.4); 0.4.0 needs set_pointer + get_pointer (on top of 0.3); 0.3.0

 * needs inject_key + write_mem + capture_audio; 0.2.0 needs inject_key; else

 * 0.1.0. Keeps a partial backend honest. */

#define RETRO_CONTROL_CONTRACT "0.5.0"

    /* 0.5: present a virtual game controller at `index` and set what is held.

     *

     * `buttons` is the canonical mask (SPEC "Canonical button layout"): bit0

     * LEFT, 1 RIGHT, 2 UP, 3 DOWN, 4 A, 5 B, 6 X, 7 Y, 8 START, 9 SELECT,

     * 10 L, 11 R -- the SNES/Neo6502 native order. A backend whose hardware

     * disagrees converts here, so a test never learns which machine it is on.

     * -1 leaves the mask unchanged.

     *

     * `connected` is 1 to present the pad, 0 to unplug it, -1 to leave the

     * presence unchanged. Unplugging is testable behaviour in its own right:

     * a program that asks "is a pad there" before offering two-player needs

     * both answers.

     *

     * A pad is a LEVEL, not an event -- the state persists across frames until

     * changed, unlike inject_key's TAP.

     *

     * MUST drive the same path a real pad takes. On an emulator reading SDL

     * joysticks that means presenting a virtual device the existing read path

     * picks up, NOT calling into SDL: headless CI has no joystick, which is

     * the case this exists for.

     *

     * Return 1 on success, 0 if the platform has no controller support

     * (server -> 400). NULL => POST /pad returns 501. */

    int (*set_pad)(int index, int buttons, int connected);

    /* 0.5: report a pad's presence and held mask (same layout as set_pad).

     * Return 1 on success (values written), 0 if unsupported. NULL => GET /pad

     * returns 501. */

    int (*get_pad)(int index, int *buttons, int *connected);