System overview¶
The Retroverse NestrisLTM suite is a set of four projects that run a Classic NES Tetris tournament from capture to broadcast. It replaces clipboards, spreadsheets and manual score entry with automatic, verifiable results.
In one sentence
A small PC next to each NES reads the game from the video signal. An RFID card tells it who is playing. A central host PC collects every game, ranks the players and feeds the stream and the screens in the hall.
Who uses it?¶
| Role | What they get |
|---|---|
| Organisers | One admin UI for players, games, events, stations and the bracket. Cheats and suspicious games are flagged and every change is in an audit log. |
| Players | Register once at the touch terminal and receive a personal card. Tap it at any station: rank and best score appear on the reader's display, and every game can be replayed later. |
| Streamers / casters | Transparent 1080p OBS browser sources: single, 1v1 and 4-player layouts. They show live playfields, score difference and "needs N tetrises". |
| Audience | A full-screen highscore display with live updates, record banners, an animated bracket and a champion celebration. |
The components¶
| Component | What it is | Runs on | Status | Links |
|---|---|---|---|---|
| NestrisLTM | Host app: ingest, database, admin, overlays, displays, updates | Windows 10/11 host PC (headless core also on Linux) | Beta | Repo · Releases |
| nestris-core | Recognition engine (Rust), nestris-station daemon, CLI, desktop and web GUIs | Debian 12/13 stations, Windows, Linux, macOS, browser | Beta | Repo · Releases |
| nestris-terminal | Touch kiosk for registration, player profiles and replays | Windows 10/11 touch PC | Beta | Repo · Releases |
| nestris-rfid-reader | ESP32 card-reader firmware with OLED, protocol v2 | ESP32 DevKit + RC522 + SSD1306 | Preview | Repo · Releases |
The big picture¶
flowchart LR
subgraph STATIONS["Capture stations · one per console"]
direction TB
subgraph S1["Station 1"]
direction LR
N1["<span style='color:#f8fafc'>🎮 NES</span>"]:::hw --> C1["<span style='color:#f8fafc'>USB capture</span>"]:::hw --> ST1["<span style='color:#111111'>nestris-station</span>"]:::core
R1["<span style='color:#111111'>RFID reader</span>"]:::rfid -- USB serial --> ST1
end
subgraph S2["Station n"]
direction LR
N2["<span style='color:#f8fafc'>🎮 NES</span>"]:::hw --> C2["<span style='color:#f8fafc'>USB capture</span>"]:::hw --> ST2["<span style='color:#111111'>nestris-station</span>"]:::core
R2["<span style='color:#111111'>RFID reader</span>"]:::rfid -- USB serial --> ST2
end
end
subgraph HOST["Host PC"]
direction TB
MQ["<span style='color:#ffffff'>Mosquitto<br/>MQTT broker</span>"]:::ext --> LTM["<span style='color:#111111'>NestrisLTM</span>"]:::ltm
LTM <--> DB[("<span style='color:#ffffff'>PostgreSQL</span>")]:::ext
end
subgraph KIOSK["Registration"]
direction LR
R3["<span style='color:#111111'>RFID reader</span>"]:::rfid -- USB serial --> TERM["<span style='color:#111111'>nestris-terminal</span>"]:::term
end
subgraph SCREENS["Outputs"]
direction TB
OBS["<span style='color:#ffffff'>OBS / stream PC</span>"]:::ext
HS["<span style='color:#ffffff'>Highscore & bracket<br/>display</span>"]:::ext
ADM["<span style='color:#ffffff'>Admin browser</span>"]:::ext
end
ST1 & ST2 -- "MQTT 1883" --> MQ
ST1 & ST2 -- "HTTP 7990 · .ngf.gz upload" --> LTM
TERM -- "HTTP 7990 · REST" --> LTM
LTM -- "HTTP / WebSocket 7990" --> OBS & HS & ADM
LTM -. "cmd: rank on reader" .-> MQ
classDef ltm fill:#f5b800,stroke:#7a5c00,color:#111,stroke-width:2px
classDef core fill:#22d3ee,stroke:#0e7490,color:#111,stroke-width:2px
classDef term fill:#a78bfa,stroke:#6d28d9,color:#111,stroke-width:2px
classDef rfid fill:#f472b6,stroke:#be185d,color:#111,stroke-width:2px
classDef ext fill:#64748b,stroke:#334155,color:#fff,stroke-width:2px
classDef hw fill:#1f2937,stroke:#94a3b8,color:#f8fafc,stroke-dasharray:4 3
Design principles¶
-
Local first
Everything runs on the event LAN. No internet connection is needed during the tournament. Updates are fetched only when one is available.
-
Results are evidence
Every game is recorded frame by frame (NGF), validated and checked for cheats. Disputes are settled by replaying the recording.
-
Self-healing
Stations restart capture, reconnect readers and brokers, and resend spooled results by themselves. The host app runs as a tray app with health indicators.
-
Loosely coupled
Components talk through documented contracts: MQTT, REST, serial JSON and NGF. Each part can be tested and replaced on its own.
Where to go next¶
- System architecture: the internals of every component.
- Deployment: from a one-console demo to a full tournament hall.
- Game lifecycle: what happens between "card on the reader" and "score on the stream".
- Event setup guide: a step-by-step checklist for organisers.