PRODUCT NOTES · OGN 1
Behind the AIWe did not want a replay button. We wanted a game record.
The request sounded small: can we save a game so someone can tell us whether Petra missed a height tile?
But the useful answer could not be “here is some JSON.” A final board is often a crime scene after the tactical moment has disappeared. To judge a move, a player needs the pre-state, the actual hand, the physical construction, the score receipts, and the rules that made the state legal. A developer needs an exact machine state that can be replayed without trusting the explanation attached to it.
Those are related jobs. They are not the same file.
The design target: a table record you can actually read
We called the readable format OverGrid Game Notation, or OGN 1. It is designed to answer a specific social question: what happened in this game, and can another player follow it without learning an orientation-code vocabulary or asking the original player to narrate every turn?
That ruled out a few tempting shortcuts:
- No orientation IDs. A placement prints its five physical cube locations and levels:
T [c3-e3@1, d2@1, d3@2].@1means the cube rests on the board; no one has to decode a rotation matrix at dinner. - No map-name dependency. The record contains the square-tile map itself, with north, coordinates, terrain, height requirements, starting claims, homes, voids, islands, and cutouts. A weird future map should still be readable when its catalog entry has vanished.
- No score mystery. Every committed turn shows the acting hand and construction, territory claimed or captured, height and timer awards, each player’s score change, cumulative score, and a state checksum.
- No pretend move history. Camera nudges, draft placements, and abandoned attempts are not turns. Committed actions are the record; territory prose and score lines are derived receipts.
2. B Petra AI — hand L W Z
L [a9@1-3, a11-a10@1]
W [c11-d11@1, b10-c10@1, b9@1]
Z [a8-a6@2, a8@1, a6@3]
→ claimed a11, c11, d11, c10, a9, b9, a8, a7
Δ A 0 · B +80 [territory +60, height +20, timer 0]
Score: A 100 · B 100 · C 20
Checksum: #e74c2c81
That is intentionally denser than a screenshot and gentler than raw reducer state. You can ask whether the shape could have reached the circled tile. You can see which height award was banked and whether the rule was “on claim” or “on capture.” You can also quote a turn in a bug report without turning the report into a game of telephone.
Two artifacts, two responsibilities
A checksum detects alteration; it does not make a record a signed server result. Draft placements and camera movement are intentionally absent from both records.
OGN is the public reading copy. The exact .overgrid.json bundle is the machine authority. It carries the versioned reducer state, registered map snapshot, deterministic seed, turn chain, generated OGN, and—when local—scoped AI decision receipts.
The important design choice is the arrow in the figure, not the file extension: when an exact replay is uploaded, OverGrid does not take its prose at face value. It parses defensively, checks the registered map, reverses and replays the committed territory chain, recomputes state hashes and score deltas, and regenerates the notation. The player previews that verified result before a separate confirmation can replace the active local game.
The format therefore has a useful asymmetry:
| Question | OGN 1 answers it | Exact replay answers it |
|---|---|---|
| “What did Petra place, from which hand, and what did it score?” | directly, in a readable turn receipt | by replaying the authoritative state |
| “Can I share this analysis in a group chat?” | usually: it contains committed public actions | only after the game, or with trusted participants |
| “Did someone edit the human-readable text?” | checksum flags a mismatch | replay verification regenerates the derived text |
| “Can the application restore the exact game?” | no: it is intentionally explanatory | yes, after validation and confirmation |
Privacy was a product requirement, not a footnote
Determinism makes replay powerful and awkward. The exact bundle contains the seed and full reducer state; in an unfinished game, that state can reveal future deals. An export format that is perfect for debugging can therefore be terrible as a casual mid-game share link.
So the Game archive says the quiet but important thing: share an exact replay after the game. Use OGN for a readable account of the committed public record. Local AI diagnostics are a separate audit stream, not a stealth addition to a player-facing move record.
Checksums make accidental or casual alteration visible. They do not make OGN a signed tournament transcript or prove who authored it. That is deliberately future work: a server-authoritative, signed record can add provenance without forcing players to abandon the human-readable action grammar.
The player-report workflow
The practical habit is simple. When a move looks wrong, open the archive before three more automatic turns erase the evidence.
- Save the readable OGN so the map, rules, hand, and committed action travel with the question.
- Save the exact replay if you need someone to reproduce it locally.
- Phrase the objection in board terms: “could this legal construction have banked the two-dot height?” is better than “Petra avoids height.”
- Ask what the best public reply would have been before calling the apparent alternative a blunder.
That last step is why this is game design infrastructure, not merely customer support. A good record lets a player make a sharp claim; a good replay lets us test it; a good audit lets us separate a rules bug, a candidate-coverage miss, a bad evaluation, and a move that only looked free from the final board.
OGN turned anecdotes into research inputs
OGN did not make Petra stronger by itself. It made research less willing to invent a story after the fact.
The immediate use case was the one a player gave us: a suspected missed height opportunity. The durable payoff is broader. We can preserve a public pre-state, compare the move that was selected with a legal alternative, replay the actual consequences through the canonical reducer, and say exactly what evidence is missing if the answer is still uncertain.
That is the standard we want for every “the AI did something silly” report. Not a screenshot trial. Not a clever confidence score. A compact public record, an exact verification path, and enough humility to say when the board still has the last word.
<details> <summary>What OGN 1 records</summary>Format, rules, and engine versions; a self-describing map and coordinate frame; stable seats and display names; advanced ending and timing rules; committed turns with physical cube locations, score and timing receipts, and checksums; plus the final or current position and its finish reason. Files continue from z to aa, ab, and beyond.