Skip to content

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