Race state websocket #4

New issue

Closed

opened 2026-10-17 02:09:13 +00:00 by mintopia · 2 comments

mintopia commented

2026-10-17 02:09:13 +00:00

Owner

What to build

External apps can connect to a local websocket server the game opens when BLUR_STATE_WS=<port> is set (off by default, localhost only). On connect a client gets a JSON snapshot of the game-state feed, then a JSON message for every change. The message format is documented.

Acceptance criteria

With BLUR_STATE_WS set, a websocket client (e.g. websocat) gets a snapshot on connect, then changes as the player moves through menus/events/lobbies
Multiple clients at once; client disconnects don't affect the game
Unset: no listener is opened
Binds to localhost only
Message format documented; env var in the README table
Verified on BLUR_ENGINE=recomp

Blocked by

## What to build External apps can connect to a local websocket server the game opens when `BLUR_STATE_WS=<port>` is set (off by default, localhost only). On connect a client gets a JSON snapshot of the game-state feed, then a JSON message for every change. The message format is documented. ## Acceptance criteria - [ ] With `BLUR_STATE_WS` set, a websocket client (e.g. `websocat`) gets a snapshot on connect, then changes as the player moves through menus/events/lobbies - [ ] Multiple clients at once; client disconnects don't affect the game - [ ] Unset: no listener is opened - [ ] Binds to localhost only - [ ] Message format documented; env var in the README table - [ ] Verified on `BLUR_ENGINE=recomp` ## Blocked by - #2

mintopia added this to the Game enhancements (post-port) milestone

2026-10-17 02:09:13 +00:00

mintopia added a new dependency

2026-10-17 02:09:14 +00:00

#2 Game-state feed

mintopia referenced this issue

2026-10-17 02:09:14 +00:00

Live race telemetry in the game-state feed #5

mintopia added a new dependency

2026-10-17 02:09:15 +00:00

#5 Live race telemetry in the game-state feed

mintopia added the

ready-for-agent

label

2026-10-17 02:09:18 +00:00

mintopia self-assigned this

2026-10-17 19:28:41 +00:00

mintopia commented

2026-10-17 19:37:58 +00:00

Author

Owner

Implemented. BLUR_STATE_WS=<port> starts a Network.framework websocket server bound to 127.0.0.1 only (src/host/state_ws.mm); unset = no listener. On connect: {"type":"snapshot","state":{...}}, then {"type":"change","key":..,"value":..} per change (format in docs/state-websocket.md, env var in README). Multiple clients supported; disconnects dont affect the game. Verified on BLUR_ENGINE=recomp via mdrive.py mp_menus: snapshot + live screen/mode changes received, lsof shows only 127.0.0.1:port listening, second client connect/kill left game and first client running. Unit test state_ws_test added (ctest state_ws passes). Lobby/event-track keys come from the existing #2 feed and were not exercised by this menu plan.

Implemented. `BLUR_STATE_WS=<port>` starts a Network.framework websocket server bound to 127.0.0.1 only (`src/host/state_ws.mm`); unset = no listener. On connect: `{"type":"snapshot","state":{...}}`, then `{"type":"change","key":..,"value":..}` per change (format in `docs/state-websocket.md`, env var in README). Multiple clients supported; disconnects dont affect the game. Verified on `BLUR_ENGINE=recomp` via `mdrive.py mp_menus`: snapshot + live screen/mode changes received, `lsof` shows only `127.0.0.1:port` listening, second client connect/kill left game and first client running. Unit test `state_ws_test` added (ctest state_ws passes). Lobby/event-track keys come from the existing #2 feed and were not exercised by this menu plan.

mintopia closed this issue

2026-10-17 19:42:13 +00:00

mintopia commented

2026-10-17 19:42:13 +00:00

Author

Owner

Completed and merged by Harmonic (task 7).

mintopia referenced this issue from a commit

2026-10-19 09:56:15 +00:00

Race state websocket: BLUR_STATE_WS serves the game-state feed on a loopback websocket (#4)

mintopia referenced this issue from a commit

2026-10-19 09:56:15 +00:00