From 54081ce90bf2b4cad803ab78db65b91c1217cc83 Mon Sep 17 00:00:00 2001
From: gbc dev <gbc@localhost>
Date: Sat, 4 Jul 2026 22:46:11 +0200
Subject: input: external control channel via FIFO

Adds --fifo [path] opening a named pipe that accepts button commands from any
process. Supports momentary taps (a, start, name:N), deterministic hold/release
(+name / -name), and 'release'. Merges with keyboard input; held state carries
true key-up semantics the terminal can't provide. GBC_INPUT_DEBUG traces state.
---
 README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 947211d..620f4c9 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,36 @@ Requires a truecolor-capable terminal (`COLORTERM=truecolor`) at least
 Since terminals don't report key-release, buttons are held for a few frames
 after each keypress (relying on the terminal's key-repeat for sustained holds).
 
+### External control channel (FIFO)
+
+Start with `--fifo [path]` (default `/tmp/gbc.fifo`) to open a named pipe that
+accepts button commands from any process. Unlike the terminal keyboard, this
+can send true key-**release** events, so it gives deterministic input for
+scripting and automated testing.
+
+```sh
+./build/gbc rom.gb --fifo /tmp/gbc.fifo &
+echo 'a' > /tmp/gbc.fifo          # momentary tap of A
+echo 'start' > /tmp/gbc.fifo      # tap Start
+echo '+left' > /tmp/gbc.fifo      # press and HOLD Left
+echo 'a b' > /tmp/gbc.fifo        # tap A and B together (Left still held)
+echo '-left' > /tmp/gbc.fifo      # release Left
+echo 'release' > /tmp/gbc.fifo    # release everything held
+echo 'a:30' > /tmp/gbc.fifo       # tap A, held for 30 frames
+```
+
+Commands (one line, space/comma separated tokens, case-insensitive):
+
+| Token          | Effect                                  |
+|----------------|-----------------------------------------|
+| `a b start select up down left right` | momentary tap  |
+| `name:N`       | tap held for N frames                   |
+| `+name`        | press and hold until released           |
+| `-name`        | release a held button                   |
+| `release`      | release all held buttons                |
+
+Set `GBC_INPUT_DEBUG=1` to trace resulting joypad state to stderr.
+
 ## Architecture
 
 | File        | Responsibility                                            |
-- 
cgit v1.3.1-sl0p