Skip to content

NGF recordings

Every game is recorded frame by frame in NGF, the NestrisChamps Game Format (.ngf, usually gzip-compressed as .ngf.gz). nestris-core writes the files, NestrisLTM stores and replays them, and the terminal uses them for player replays. The format is bit-compatible with NestrisChamps.

flowchart LR
    ENG["<span style='color:#111111'>nestris-core engine</span>"]:::core --> REC["<span style='color:#111111'>Recorder<br/>.ngf.part (crash-safe)</span>"]:::core --> GZ["<span style='color:#111111'>.ngf.gz</span>"]:::core
    GZ -- "HTTP PUT + X-NGF-SHA256" --> LTM["<span style='color:#111111'>NestrisLTM<br/>verify · store</span>"]:::ltm
    LTM --> RP["<span style='color:#ffffff'>Replay viewer<br/>admin · terminal · overlay</span>"]:::ext
    GZ --> CLI["<span style='color:#111111'>nestris replay<br/>full statistics</span>"]:::core

    classDef ltm fill:#f5b800,stroke:#7a5c00,color:#111,stroke-width:2px
    classDef core fill:#22d3ee,stroke:#0e7490,color:#111,stroke-width:2px
    classDef ext fill:#64748b,stroke:#334155,color:#fff,stroke-width:2px

File structure

An NGF file is a plain sequence of fixed-size frames, optionally gzip-compressed as a whole. Readers detect gzip by its magic bytes (1f 8b), not by the file extension. The top 3 bits of the first byte hold the frame version:

Version Frame size nestris-core
1 71 bytes read
2 72 bytes read
3 73 bytes read + write

Version 3 frame (big-endian, bit-packed)

Offset Bits Field
0 3 + 2 + 3 version, game_type (0 minimal / 1 classic / 2 DAS trainer), player_num
1–2 16 gameid
3–6 28 + 4 ctime (ms since game start), high nibble of lines
7 8 lines low byte (12 bits total)
8 8 level
9–11 24 score
12 5 + 3 instant_das, preview piece
13 5 + 3 cur_piece_das, cur_piece
14–22 7 × 10 + 2 piece counts T J Z O S L I
23–72 200 × 2 playfield, 4 cells per byte, row-major from top left

Piece codes: T=0 J=1 Z=2 O=3 S=4 L=5 I=6, 7 = none.

Upload to NestrisLTM

PUT /api/stations/station-1/games/station-1-1790241008228/ngf HTTP/1.1
Authorization: Bearer nltm_…
Content-Type: application/gzip
X-NGF-SHA256: 9f86d081884c7d65…
  • Upload jobs survive station restarts. A 404 means the host has not processed the game_end yet, so the station retries. Network errors and 5xx responses back off.
  • The host checks the hash, verifies that the file decodes, stores it and deletes the temporary live frames of that game.
  • Recordings can also be imported and exported in the NestrisLTM admin UI, for example to bring in games from other NGF tools.

Replay

Where How
NestrisLTM admin Every game: 0.25×–8×, scrubbing, frame steps
Player terminal The player's own games, and replays of other players in attract mode
OBS replay scene layout
Command line nestris replay game.ngf.gz --jsonl out.jsonl (full statistics)
Browser GUI Load the file into the nestris-core web app