1.7 KiB
Lost Cities Match Record v1
Last verified: 2026-07-12
coolrl.lost-cities.match.v1 is the canonical portable record for one complete
or in-progress classic Lost Cities match. Files use UTF-8 JSON Lines (.jsonl)
so metadata can be inspected without loading the full replay and steps can be
streamed in order.
Row 1: metadata
The first row has type: "metadata" and format: "coolrl.lost-cities.match.v1". It records creation time, classic rules,
initial seed, human seat, opponent identity, and completion status. Producers
may add fields; v1 readers must ignore unknown metadata fields.
Rows 2+: steps
Every remaining row has type: "step" and a contiguous zero-based index.
Step 0 is the initial position and has null actor, phase_before, and
action_id. Later steps contain:
actor: player that took the action (0or1).phase_before:cardordraw.action_id: the classic engine unified action ID.state: completeGameState.to_snapshot()output after the action.public_hands: cards known to be in each player's hand because they were drawn from a discard pile. Entries use{color, value, count}; wagers have value 0 and numbered cards use their printed value.
Full state snapshots intentionally include hidden hands and deck order. A match record is therefore suitable for post-game analysis and deterministic replay, but must not be exposed to a player during a live match.
Compatibility
Readers must reject an unknown format value rather than guessing. New
optional fields may be added within v1. Any incompatible change to action IDs,
state encoding, or required row semantics requires v2.
The reference reader, writer, and validator are in
src/coolrl_lost_cities/games/classic/match_record.py.