Feed: apply the ADR 0019 message contract #31

New issue

Closed

opened 2026-10-20 18:41:23 +00:00 by mintopia · 4 comments

mintopia commented

2026-10-20 18:41:23 +00:00

Owner

Refactor every feed message to ADR 0019.

Acceptance

Envelope {type, race_id, race_ms, ...} on every message; events carry event + data.
change.value native JSON; null = cleared; optional fields absent.
snake_case, all times integer _ms, racer/victim/attacker, mods always an array, lowercase icon names.
hit moves to the envelope with serial (+0x14) added.
roster = client state in snapshot and lobby: [{racer, join_ref, name, car, mods, local, ai}]; standings drops name/car/mods.
car_names/mod_names no longer on the wire (repo data, #30).
Drop race_time; event key -> race_type; speeds folded into standings as mph; race_result = {final, completed, standings}.
track_name/route_name documented.
powerups stays a fixed 3-slot array, null = empty slot (ADR 0019 exception).
race_result times in ms as time_ms (was whole seconds as time).
race_id: minted UUIDv7 per race until #34 finds a game ID.
docs/state-websocket.md, examples/live-timing, ws_tap.py, tests/state_ws_test.mm updated; no compatibility shim.

Rules

Wire format: ADR 0019 (docs/decisions/0019-feed-message-contract.md). Repo data/tools: ADR 0020.
Fix and verify on BLUR_ENGINE=recomp only.
Update docs/state-websocket.md and examples/live-timing for any feed change.
Test races: use the scripts/ scenarios (windowed, low settings) once #33 exists.

Refactor every feed message to ADR 0019. ## Acceptance - Envelope `{type, race_id, race_ms, ...}` on every message; events carry `event` + `data`. - `change.value` native JSON; `null` = cleared; optional fields absent. - snake_case, all times integer `_ms`, `racer`/`victim`/`attacker`, `mods` always an array, lowercase icon names. - `hit` moves to the envelope with `serial` (`+0x14`) added. - `roster` = client state in snapshot and lobby: `[{racer, join_ref, name, car, mods, local, ai}]`; `standings` drops `name`/`car`/`mods`. - `car_names`/`mod_names` no longer on the wire (repo data, #30). - Drop `race_time`; `event` key -> `race_type`; `speeds` folded into `standings` as `mph`; `race_result` = `{final, completed, standings}`. - `track_name`/`route_name` documented. - `powerups` stays a fixed 3-slot array, `null` = empty slot (ADR 0019 exception). - `race_result` times in ms as `time_ms` (was whole seconds as `time`). - `race_id`: minted UUIDv7 per race until #34 finds a game ID. - `docs/state-websocket.md`, `examples/live-timing`, `ws_tap.py`, `tests/state_ws_test.mm` updated; no compatibility shim. ## Rules - Wire format: ADR 0019 (`docs/decisions/0019-feed-message-contract.md`). Repo data/tools: ADR 0020. - Fix and verify on `BLUR_ENGINE=recomp` only. - Update `docs/state-websocket.md` and `examples/live-timing` for any feed change. - Test races: use the `scripts/` scenarios (windowed, low settings) once #33 exists.

mintopia added this to the Feed: standard messages, powerup events, race stats milestone

2026-10-20 18:41:23 +00:00

mintopia referenced this issue

2026-10-20 18:41:32 +00:00

Spike: game race ID shared across LAN instances #34

mintopia added a new dependency

2026-10-20 18:41:36 +00:00

#30 Lookup data and art generated by tools

mintopia added a new dependency

2026-10-20 18:41:36 +00:00

#32 Feed: dev-only debug state for scripts

mintopia added the

ready-for-agent

label

2026-10-20 18:41:42 +00:00

mintopia commented

2026-10-20 18:52:35 +00:00

Author

Owner

Research findings (static: Blur.exe strings + current src), 2026-10-20.

Drift inventory checked against ADR 0019. Covered by the acceptance list except:

race_result.time is whole seconds today, unlabelled. Under ADR 0019 it becomes _ms (e.g. time_ms) inside race_result.standings.
powerups uses null slots ([null,null,null]), while ADR 0019 says to leave optional fields out. Decide: keep a fixed 3-slot array with null = empty slot (positional, document it as an exception), or a compact array of held kinds.

Already intended by ADR 0019, no action: ids are local to each instance (match LAN by serial), hit race_ms is the local racer's clock, no schema version.

Current emitters: src/host/race_feed.cpp, game_state.cpp, state_ws.mm, hit_event.cpp, lua_patch.cpp, patches/Screens/Commands.post.lua, patches/Screens/Ingame/Hud.post.lua.

Research findings (static: Blur.exe strings + current src), 2026-10-20. Drift inventory checked against ADR 0019. Covered by the acceptance list except: - `race_result.time` is whole seconds today, unlabelled. Under ADR 0019 it becomes `_ms` (e.g. `time_ms`) inside `race_result.standings`. - `powerups` uses `null` slots (`[null,null,null]`), while ADR 0019 says to leave optional fields out. Decide: keep a fixed 3-slot array with `null` = empty slot (positional, document it as an exception), or a compact array of held kinds. Already intended by ADR 0019, no action: ids are local to each instance (match LAN by `serial`), hit `race_ms` is the local racer's clock, no schema version. Current emitters: `src/host/race_feed.cpp`, `game_state.cpp`, `state_ws.mm`, `hit_event.cpp`, `lua_patch.cpp`, `patches/Screens/Commands.post.lua`, `patches/Screens/Ingame/Hud.post.lua`.

mintopia commented

2026-10-20 18:53:56 +00:00

Author

Owner

Decided: powerups keeps null slots; race_result time becomes time_ms in ms. Added to acceptance; ADR 0019 updated.

Decided: `powerups` keeps `null` slots; `race_result` time becomes `time_ms` in ms. Added to acceptance; ADR 0019 updated.

mintopia added a new dependency

2026-10-20 22:34:35 +00:00

#49 JSON Schema for the game-state feed

mintopia referenced this issue

2026-10-20 22:34:39 +00:00

JSON Schema for the game-state feed #49