Skip to content

NestrisLTM Local Tournament Manager

Latest release CI Platform Python Beta

NestrisLTM is the host application of the tournament and the heart of the suite. It runs on the host PC and receives every station's live data and results over MQTT. It keeps players, games and events in PostgreSQL, and it serves everything people see: the admin UI, the OBS overlays, the highscore and bracket display, and the API for the player terminal.

Repository Download latest

Features

  • Admin UI (German / English)

    • Dashboard: database, broker, stations, running games, log
    • Players: create, edit, merge, search; several cards per player
    • Games: filter by event, station, cheat or invalid; edit, re-assign, hide
    • Events with time windows; exactly one is active
    • Stations, Tournament console, Scenes, Audit log
    • Settings: admin accounts and API tokens; Updates
  • Highscore & bracket display

    /view/highscore is a full-screen display. Running games appear live with a green dot. It animates list ↔ bracket transitions and shows banners for a new record, a lead change and milestones, a score train, a CRT effect and a champion celebration.

  • Tournament console

    A single-elimination bracket for 2–64 players with byes and a third-place match. Click to set winners; FIX, RESET and UNSEED. It also remote-controls the display: font size, autoscroll, effects, transparency, celebration. The bracket state survives restarts.

  • OBS scenes

    Each scene has a fixed URL /o/<slug> with a layout and one station per slot, as a 1920×1080 transparent overlay. See Streaming & OBS.

  • Replays

    Every game is stored as a frame-perfect NGF recording. Replay at 0.25×–8× with scrubbing and frame steps. Games can be imported and exported as NGF.

  • Integrity & audit

    Cheat and invalid games still count but carry a badge and have their own filter. Every change is logged with before/after values. All write APIs need scoped tokens.

Architecture at a glance

flowchart LR
    ST["<span style='color:#111111'>Stations</span>"]:::core -- "MQTT" --> MQ["<span style='color:#ffffff'>Mosquitto</span>"]:::ext --> ING["<span style='color:#111111'>Ingest</span>"]:::ltm
    ST -- "PUT .ngf.gz" --> API
    ING --> HUB["<span style='color:#111111'>LiveHub</span>"]:::ltm --> WS["<span style='color:#111111'>WebSocket hub</span>"]:::ltm
    ING --> SP["<span style='color:#111111'>Spool → worker</span>"]:::ltm --> DB[("<span style='color:#ffffff'>PostgreSQL</span>")]:::ext
    DB <--> API["<span style='color:#111111'>FastAPI :7990</span>"]:::ltm
    WS --> API
    API --> ADM["<span style='color:#ffffff'>Admin UI</span>"]:::ext
    API --> OV["<span style='color:#ffffff'>Overlays /o/…</span>"]:::ext
    API --> HS["<span style='color:#ffffff'>/view/highscore</span>"]:::ext
    API --> TAPI["<span style='color:#111111'>/api/terminal/v1</span>"]:::term
    API -. "cmd show" .-> 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 ext fill:#64748b,stroke:#334155,color:#fff,stroke-width:2px

Details: System architecture.

Rounds & versus numbers

Scenes work in rounds. When the game on a slot ends, that slot's result freezes. Further games on that slot are ignored until the crew starts a new round, by hand ("Neue Runde"), automatically ("Auto-Runde") or from a Stream Deck. "Slot zurücksetzen" lets one slot play again.

The server computes the versus figures so every overlay shows the same numbers:

  • score difference and a live difference graph
  • lead in tetrises: lead ÷ (1200 × (level + 1)) of the trailing player
  • pace projected to level 29
  • "needs N tetrises" for the trailing player

Installation

  1. Download NestrisLTM-Setup-<version>.exe from the latest release and run it with admin rights.
  2. The wizard installs PostgreSQL 18 and Mosquitto 2.1.2 if they are missing (official downloads, SHA-256 checked) or reuses existing installations. It sets both services to start automatically and adds firewall rules for TCP 7990 and 1883, limited to the local subnet.
  3. On first start, create the first admin account. This is only possible on the host PC itself.
  4. Under Einstellungen → API-Tokens, create tokens for the stations (scope stations) and the terminal (scope terminal).
  5. Create an event and activate it. The dashboard shows each station as soon as it connects.

The full checklist is in the event setup guide.

Tray icon

Colour Meaning
🟢 green Database and broker OK
🟠 orange Database or broker unreachable
🔴 red Core not running (for example port 7990 in use)

Closing the window keeps NestrisLTM running in the tray. Beenden stops it cleanly and writes any buffered live frames first.

Command line

The install folder contains the tray app NestrisLTM.exe and the CLI nestris-ltm.exe:

Command Purpose
nestris-ltm check Checks database, broker and port, and names the program blocking a port
nestris-ltm configure … Changes connection settings, for example --db-password, --http-port
nestris-ltm autostart on\|off\|status Starts in the tray at sign-in
nestris-ltm set-admin-password Resets an admin password
nestris-ltm migrate Runs database migrations
nestris-ltm config-path Prints the config file location
nestris-ltm --headless Runs the core without the Qt shell
nestris-ltm simulate Replays NGF recordings as simulated MQTT stations (testing without hardware)

Configuration

The config lives in %APPDATA%\NestrisLTM\config.toml. Unknown keys are rejected. Environment variables NESTRIS_LTM__<SECTION>__<KEY> override the file.

config.toml (excerpt)
[database]
host = "127.0.0.1"
port = 5432
name = "nestrisltm"

[mqtt]
host = "127.0.0.1"
port = 1883
topic_prefix = "retroverse/nestris"

[http]
host = "0.0.0.0"
port = 7990

[updates]
enabled = true
channel = "stable"      # or "beta"
check_interval_h = 24
Section Keys
top level data_dir
[database] host, port, user, password, name, pool_size, connect_timeout_s
[mqtt] enabled, host, port, username, password, topic_prefix, client_id, keepalive_s, reconnect_max_s
[http] host, port
[log] level, to_file, buffer_size
[updates] enabled, channel, owner, repo, token, check_interval_h, pg_dump

Logs, the spool and update backups live under %APPDATA%\NestrisLTM\.

Release artifacts

File Purpose
NestrisLTM-Setup-<v>.exe Installer (German / English), also used for updates
NestrisLTM-<v>-portable.zip Portable folder build
SHA256SUMS.txt / .sig Checksums and Ed25519 signature

See Downloads for verification and Updates for the built-in update manager.