mf-wire v1

Wire protocol between metroforge-native (client) and metroforge-sidecar (sim host) over one WebSocket. PROTOCOL_VERSION = 1 (crates/mf-protocol/src/lib.rs).

Two frame kinds share the socket:

• Text frames — JSON control messages (crates/mf-protocol/src/envelope.rs, types.rs).
• Binary frames — little-endian hot-path payloads (crates/mf-protocol/src/binary.rs). Arrays are copied via chunks_exact(4) / byte copies; the WS buffer is not assumed 4-byte aligned.

Source of truth for layouts and field optionality is the Rust codec in this repo. If a deployed sidecar disagrees, the code that is actually paired wins and this document should be updated.

1. JSON envelope#

Every text frame deserializes as (envelope.rs):

{ "t": "<type>", "seq": 12, "p": { "...": "payload" } }

Serde: #[serde(default, skip_serializing_if = "Option::is_none")] on seq and p.

1.1 Client → sidecar (ToSim)#

InitPayload (camelCase)#

QueryTrackCostPayload#

TransitMode: "bus"\|"tram"\|"metro"\|"rail".
TrackGrade: "surface"\|"elevated"\|"tunnel".
Vec2: { x: f64, y: f64 }.

Command (internally tagged on "kind", camelCase fields)#

1.2 Sidecar → client (FromSimJson)#

CityListEntry is { key, label } plus optional additive fields the city-select screen consumes when present: country?, population?, buildingCount?, sizeKm?, and mapPreview? ({ worldSize, res, water: number[], arterials: number[][] }). Older sidecars that only send {key,label} remain valid; the native client fills gaps from its local catalog. | ready | no | { staticCity: StaticCityJson } | static city geometry, minus the three mask byte arrays (see StaticMask binary frame) | | demand | no | { lines: {x1,y1,x2,y2,weight,share}[], maxWeight: number } | droppable under backpressure | | ui | no | the UiState struct directly as p | sent at 2 Hz; budget, approval, stations/tracks/routes, active events, etc. | | commandResult | yes | { result: { ok: bool, error?: string, createdId?: i64 } } | echoes the command's seq | | trackCost | yes | { cost: number } | echoes the queryTrackCost's seq | | saved | no | { json: string } | reply to requestSave | | replay | no | the ReplayPayload struct directly as p | reply to requestReplay; always includes stateHash | | toast | no | { message: string, tone: "info"\|"warn"\|"good" } | | | pong | no | (none) | reply to ping | | bye | no | (none) | final message before the sidecar closes the socket, in response to shutdown | | hello | no | HelloInfo | Sent immediately on connect, before any client message | | ready | no | { staticCity: StaticCityJson } | Static geometry; masks arrive as binary | | demand | no | DemandPayload | Desire lines + maxWeight | | ui | no | UiState directly as p | 2 Hz (mf-state/src/ui.rs) | | commandResult | echoed | { result: CommandResult } | Echoes command's seq | | trackCost | echoed | { cost: f64 } | Echoes queryTrackCost's seq | | saved | no | { json: string } | Reply to requestSave | | replay | no | ReplayPayload directly as p | Reply to requestReplay | | toast | no | { message, tone } | tone: "info"\|"warn"\|"good" | | pong | no | (none) | Reply to ping | | bye | no | (none) | Final message before close after shutdown |

HelloInfo (camelCase)#

StaticCityJson (camelCase)#

No raw mask bytes in JSON; those arrive as binary StaticMask (0–3 frames) immediately after ready.

UiState (camelCase) — sent as p of t:"ui"#

DayLedger: { fares, subsidy, operations, maintenance, interest } (all f64).

UiStation: id, name, x, y, mode, level, ridership, alightings.

UiTrack: id, mode, grade (string, not TrackGrade enum), points, fromStationId, toStationId.

UiRoute: required fields plus optional sim-depth liveCrowding, operatingCost, farebox (each #[serde(default)]).

display_hour() (types.rs): prefers finite hourOfDay; else (tick % 1200) / 1200 * 24 (TICKS_PER_DAY = 1200).

DemandPayload#

CommandResult#

ReplayPayload (camelCase)#

1.3 ScenarioRules (camelCase)#

2. Binary frames#

Common prefix: byte 0 = msgType (u8), byte 1 = version (u8). All multi-byte scalars are little-endian.

decode_binary dispatches on byte 0 (binary.rs).

msgType=1: FrameSnapshot (every 50 ms sim tick)#

Wire version: 1 only. Header = 24 bytes.

Client paint: mf-render/src/vehicles.rs ignores colorTable hex values and indexes palette::vivid_route_color by routeColorIdx.

msgType=2: Fields (init, then every 7 sim-days)#

Wire version: 1 only. Header = 16 bytes.

N = fieldW * fieldH from the latest StaticCityJson; this frame carries no grid dimensions.

msgType=3: Traffic#

Wire version: 1 only. Header = 32 bytes.

Decoded and tested; mf-state does not mirror it into a resource (plugin.rs leaves Traffic for direct consumers).

msgType=4: StaticMask (0–3 frames after ready)#

Wire version: 1 only. Header = 12 bytes.

One frame per has*Mask flag that is true in ready. Procedural cities may send zero. mf-game's Loading gate waits for every flagged mask (CurrentCity::masks_complete).

msgType=5: StaticBuildings (sent once; additive)#

Wire versions: 1 and 2 accepted on decode; encode always emits version 2. Does not bump PROTOCOL_VERSION (FromSimMsg::Buildings / binary.rs docs). Not a loading gate (CurrentCity::masks_complete ignores it).

Header = 12 bytes:

Per building, fixed header then vertices:

Version 1 header (4 bytes):

Version 2 header (6 bytes): version 1 header + trailing u16 minHeightDm. On v1 decode, min_height_dm is filled as 0.

Then vertexCount vertices × 4 bytes: i16 xHalfM, i16 yHalfM (LE). Decode converts to meters: x = xHalfM / 2.0, y = yHalfM / 2.0. height_dm / min_height_dm stay in decimeters (renderer converts).

height_dm == 0 means "unknown; renderer may use density formula" (BuildingFootprint docs).

3. Handshake, liveness, shutdown#

client                                   sidecar
  |                                          |
  |  spawn (--port 0) + stdout handshake     |
  |  <--- {"mf":"sidecar","protocolVersion", |
  |        "port", "pid"}  (one stdout line) |
  |                                          |
  |----------------- WS connect -----------> |
  |  <---------------- hello ----------------|  HelloInfo
  |----------------- hello ----------------> |  {clientProtocolVersion}
  |     (abort if protocolVersion mismatch)  |
  |                                          |
  |----------------- init -----------------> |
  |  <---------------- ready ----------------|
  |  <------------ StaticMask x(0..3) -------|
  |  <---------- StaticBuildings? -----------|  optional, msgType=5
  |  <---------------- fields ---------------|
  |  <---------------- ui -------------------|  2 Hz
  |  <---------------- frame ----------------|  every 50 ms
  |                                          |
  |----------------- ping ------------------>|  every 5 s (mf-net)
  |  <---------------- pong -----------------|
  |                                          |
  |----------------- shutdown -------------->|
  |  <---------------- bye ------------------|
  X------------ socket closes --------------X

• The sidecar always sends its hello first, unprompted, immediately on connect.
• The client validates protocolVersion === 1 and aborts the connection attempt on mismatch rather than trying to negotiate.
• Liveness: no inbound traffic (of any kind, including pongs) for 5 seconds and the client declares the sim dead. Process exit is detected immediately via Child::try_wait and distinguished from websocket silence in SidecarDeathReason. mf-net's reconnect policy then respawns the sidecar and reconnects with backoff starting at 500 ms, doubling up to a 4 s cap, for up to 3 attempts. Mid-game, recovery re-handshakes, restores from the latest autosave (or re-inits the current city), and resumes InGame under a "Reconnecting to simulation" overlay — it does not bounce to MainMenu. After 3 failures the client shows a diagnostics screen (log tail + copy button).
• The client pings every 2.5 seconds (half the silence window) so an idle menu screen does not spuriously look dead.
• Clean shutdown: the client sends shutdown; the sidecar stops its tick loop, replies bye, closes the socket, and exits with code 0. SidecarProcess::drop is the backstop: if the child doesn't exit within a reasonable window, it is killed directly.

Client state machine (mf-game/src/state.rs):

1. Boot — spawn sidecar, connect WS (SimLink::spawn_and_connect).
2. ConnectingSim — send client hello; on matching sidecar hello → MainMenu.
3. Loading — send init (or load-save path); gate on masks_complete() && LatestFields && LatestUi → InGame. Does not wait for Frame, StaticBuildings, or demand.

Liveness (ws_transport.rs + plugin.rs + reconnect.rs):

• Client pings every 5 s.
• No inbound traffic for 10 s → is_alive() == false.
• Reconnect: backoff 500 ms, doubling up to 4 s cap, 5 attempts, then NetStatus::Fatal. Game shell maps Fatal → MainMenu.

Clean shutdown: client sends shutdown; SidecarProcess::drop kills the child as backstop.

4. Sidecar process resolution (mf-net/src/sidecar.rs)#

SidecarProcess::spawn(headless_speed) always appends --port 0 (OS-assigned port). Optional --headless-speed <n> if headless_speed is Some.

Stdout is piped; stderr inherited; stdin null. Handshake: one JSON line within 15 s:

Binary / launch lookup order#

1. $MF_SIDECAR_PATH — if set and the path is_file(), run that exact binary. If set but not a file, warn and fall through.
2. Next to the running exe — {exe_dir}/metroforge-sidecar (or metroforge-sidecar.exe on Windows).
3. Dev fallback — bun run sidecar/index.ts with cwd = <repo>/sim (resolved from the crate's CARGO_MANIFEST_DIR), only if <repo>/sim/sidecar/index.ts exists. Bun is resolved via PATH, else $HOME/.bun/bin/bun, else the string "bun".

On Windows, spawn uses CREATE_NO_WINDOW so a second console does not appear.

5. Versioning and additive-fields policy#

Bump PROTOCOL_VERSION when a change would break an older peer talking to a newer one: removing/reordering required JSON fields; changing binary layouts for msgTypes 1–4; changing message semantics without a compatible shape.

Do not bump for additive, optional data (code-documented):

• JSON fields with #[serde(default)] / Option (e.g. UiState sim-depth fields, UiRoute::{liveCrowding,operatingCost,farebox}) — old sidecars stay parseable.
• msgType=5 StaticBuildings as a whole — optional; absence is valid; FromSimMsg::Buildings docs: does not bump PROTOCOL_VERSION.
• msgType=5 wire version 2 — only adds trailing minHeightDm per building; v1 payloads still decode (min_height_dm = 0).

A client that receives a hello with an unrecognized protocolVersion aborts; there is no negotiation in v1.