Skip to content

Run Replay Import

Server operators and maintainers can backfill historical run replays into GOKZ.TOP with the backend importer.

Supported Inputs

  • Individual .replay files
  • Directories, scanned recursively for .replay, .zip, and .7z inputs
  • .zip archives
  • .7z archives

Command

Run the importer from backend/:

UV_CACHE_DIR=../.uv-cache uv run python -m app.import_run_replays /path/to/replays

You can pass multiple input paths in one command.

Matching Rules

Each replay is parsed from the GOKZ run replay header and matched to an existing record by:

  • exact player Steam identity
  • exact mode
  • exact map name
  • exact stage / course
  • exact run time at the stored 3-decimal precision
  • record.created_at within 24 hours of the replay timestamp

If more than one record matches, the importer picks the record whose created_at is closest to the replay timestamp. If there is still a tie, the replay is reported as ambiguous and skipped.

For v2-format run replays, only NRM style replays are accepted.

Storage

Matched replay files are stored under:

REPLAY_STORAGE_DIR/runs/<normalized-map-name>/<record-uuid>.replay

The stored filename is always the UUIDv7 of the matched record, not the original replay filename.

Idempotency

If the destination replay file already exists for a matched record, the importer skips that replay instead of overwriting it.

Useful Options

  • --dry-run: parse and match without writing files
  • --limit N: stop after scanning N replay files
  • --fail-fast: abort on the first failed replay

API Visibility

After a replay is imported, /v1 record-shaped responses expose is_replay_available: true for the matched record and any v1 surfaces that reuse that record payload.