Game lifecycle¶
This page follows one game through the whole system, from the card on the reader to the final result in the database and the recording that backs it up.
Sequence¶
sequenceDiagram
autonumber
actor P as Player
participant R as RFID reader
participant S as nestris-station
participant B as Mosquitto
participant L as NestrisLTM
participant D as PostgreSQL
participant O as Overlay / display
P->>R: taps card
R->>S: card present (uid, name)
S->>B: player (retained)
B->>L: player
L->>B: cmd show (rank, best)
B->>S: cmd
S->>R: show
R-->>P: OLED shows nickname, rank, best score
P->>S: starts a game on the NES
Note over S: engine recognises the in-game screen<br/>(after min_game_frames)
S->>B: event/game_start (durable)
B->>L: game_start
L->>D: insert game (idempotent by game_id)
loop every NES frame (up to 60 Hz)
S->>B: live · score, lines, level, playfield
B->>L: live
L->>O: WebSocket push
end
opt Select score trick detected
S->>B: event/cheat (durable)
B->>L: cheat → game flagged
end
Note over S: game over / reset / signal lost
S->>B: event/game_end (durable, final result + validation)
B->>L: game_end
L->>D: store result
L->>O: highscore / round update
S->>L: HTTP PUT …/games/{game_id}/ngf (gzip recording)
L->>D: store recording, drop temporary live frames
Step by step¶
- Identify. The reader reports the card within about 300 ms. The station publishes the player as a retained MQTT message, so every new subscriber knows who is at the station.
- Greet. NestrisLTM looks up the player and sends a
showcommand back through the station. The reader's OLED displays the nickname with the current rank and best score. - Start. As soon as the engine has seen enough in-game frames, the station sends
event/game_start. The game ID is the station ID plus a timestamp, for examplestation-1-1790241008228. - Live. Every change is published on
live, up to once per NES frame. Overlays get it via WebSocket and draw the playfield in NES-accurate level colours. - Integrity. Score gains are checked against the NES scoring rules. A flat +10 000 without a matching line clear is the Select trick and is reported as
event/cheat. The game still counts but carries a flag. - End. On game over, console reset, signal loss or shutdown, the station sends
event/game_end. It contains the final score, lines, levels, clear counts, tetris rate, burn, drought, pieces and a validation block. - Evidence. The station uploads the complete recording (
.ngf.gz, every frame). NestrisLTM verifies it, stores it and drops the temporary live frames. The game can now be replayed from any admin page or from the terminal.
Reliability guarantees¶
| Failure | What happens |
|---|---|
| Network or broker down during a game | Durable events are kept in the station's on-disk spool and resent until the broker acknowledges them (PUBACK). |
| Host restarted mid-tournament | MQTT persistent session plus Mosquitto persistence: queued results are delivered when the host is back. |
| Duplicate delivery | The host deduplicates by game_id and topic, so writes are idempotent. |
| Capture stick unplugged | The station reports waiting_for_device and resumes automatically. |
| No picture for 30 s mid-game | The game is closed with end_reason: signal_lost. |
| Station crash | systemd restarts it within seconds, and a watchdog catches a hung main loop. |
| Recording upload fails | Upload jobs survive restarts and retry with backoff, for up to 48 h. |
Validation codes¶
Every game_end carries valid: true|false and a list of issues. Errors mark a game for review. Warnings are informational.
| Code | Severity | Meaning |
|---|---|---|
partial_game |
error | Capture joined a game that was already running |
score_reconcile |
error | Final score does not match the recognised clears plus cheats |
lines_clears_mismatch |
error | Clears do not add up to the lines played |
value_range |
error | Impossible value (for example level > 255) |
engine_restart |
error | Engine was rebuilt mid-game |
signal_lost |
warning / error | No usable picture (≥ 2 s warning, ≥ 10 s error) |
low_confidence |
warning / error | Too many low-confidence frames |
level_mismatch |
warning | Final level does not follow NES level progression |
level_score_mismatch |
warning | Level digit probably misread; the score itself is consistent |
score_unexplained |
warning | Score gains that matched no scoring event |
plausibility_corrections |
warning | Many rejected readings during the game |