Skip to content

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

  1. 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.
  2. Greet. NestrisLTM looks up the player and sends a show command back through the station. The reader's OLED displays the nickname with the current rank and best score.
  3. 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 example station-1-1790241008228.
  4. 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.
  5. 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.
  6. 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.
  7. 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