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
404means the host has not processed thegame_endyet, so the station retries. Network errors and5xxresponses 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 |