CTF Arena Replays · CTF 夺旗竞技场复盘

▶ Live site / 在线观看：https://casper015.github.io/ctf-replay-viewer/

English · 中文

---

English

Turn-by-turn replays of AI agents playing capture the flag. Pick a match in the lobby, scrub to any turn, follow any unit, and see where each game was won. The interface is available in English and Chinese and works on phones.

What you can do

• Watch any turn. Play at 0.25× to 4×, step turn by turn, or jump to any capture from the timeline (team-colored ticks mark every capture).
• Read the board at a glance. Each team has its own color and shape. Units show health rings, the way they last moved, and a gold flag and trail while carrying.
• Zoom and follow. Pinch, scroll or double-tap to zoom; tap a unit to see its health, order and respawn timer, then press Follow to keep the camera on it.
• Understand the game. Live standings, a score-race chart (lines or orbit view), a feed of key moments, and per-team stats (captures, kills, assists, deaths, KDA) that add up as the match plays.
• Share a moment. The URL keeps the match and turn (match.html?m=g2&t=378).
• AI commentary booth. A caster, a color commentator and an analyst comment on the match turn by turn, written by any LLM or offline, in Chinese, English or any language you add. Lines appear in the Commentary panel and as captions on the board, and the crowd's bullet comments (弹幕) fly across it. See commentary/README.md.

Run it locally

Everything is static HTML, CSS and JavaScript. There is nothing to install or build.

git clone https://github.com/Casper015/ctf-replay-viewer.git
cd ctf-replay-viewer
python3 tools/serve.py          # then open http://localhost:8000

Double-clicking site/index.html won't work: browsers block JavaScript modules on file:// pages. Always use a local server.

Add a new competition

A match needs two files: the replay (what happened each turn) and the metadata (the title and description shown in the lobby, in both languages). tools/add_match.py creates both for you.

1. Get the replay JSON. Use the arena engine's recorder, or any tool that writes the replay format. If you have the private ctf-stress-pack, tools/build_replays.py can re-simulate scheduled games.

2. Add it.

# One match. The key becomes the URL: match.html?m=g4_spring_final
python3 tools/add_match.py add path/to/replay.json --key g4_spring_final --id sz04-m012345

# A whole competition at once: every .json in the folder becomes a match (key = file name)
python3 tools/add_match.py add path/to/spring_cup/

The script:

• checks that each replay is valid and stops with a clear message if it isn't
• copies it to site/data/matches/<key>.json
• writes content/matches/<key>.json, with a title and description drafted in both languages from the replay's facts (who won, the score, comebacks, the deciding turn)
• rebuilds site/data/catalog.json, so the match is in the lobby right away

3. Check the text. Open content/matches/<key>.json and improve the drafted text if you like. See Writing match text. To check facts such as scores and turn numbers:

python3 tools/build_catalog.py --report   # prints scores and lead changes for every match
python3 tools/build_catalog.py            # run again after editing content/matches/*.json

4. Preview. Run python3 tools/serve.py and open http://localhost:8000/match.html?m=<key>.

5. Run the checks. These are the same checks CI runs before deploying:

python3 tools/build_catalog.py --check
node tools/check.mjs

6. Commit and open a pull request with these three paths:

content/matches/<key>.json
site/data/matches/<key>.json
site/data/catalog.json

CI runs the checks on the pull request. When it's merged to main, the site redeploys automatically.

Write the text first (optional)

If you'd rather write the title yourself before adding the match:

python3 tools/add_match.py draft path/to/replay.json --key g4_spring_final -o my_match.json
# edit my_match.json (same fields as tools/templates/match.json)
python3 tools/add_match.py add path/to/replay.json --meta my_match.json

Any text field left as "auto" or empty is drafted for you.

Other commands

Command	What it does
python3 tools/add_match.py list	List matches in lobby order (* = featured)
python3 tools/add_match.py add replay.json --featured	Show this match in the lobby hero (unfeatures the current one)
python3 tools/add_match.py add replay.json --order 15	Put it at a specific place in the list (low numbers first)
python3 tools/add_match.py add replay.json --key g2 --force	Replace an existing match
python3 tools/add_match.py add replay.json --dry-run	Preview what would be added, write nothing
python3 tools/add_match.py remove g4_spring_final	Delete a match

Writing match text

Each content/matches/<key>.json has tag, title and desc, each with zh and en:

{
  "key": "g4_duel",
  "id": "sz04-m016157",
  "order": 70,
  "featured": false,
  "tag":   { "zh": "末回合绝杀", "en": "Last-turn winner" },
  "title": { "zh": "Player5 第 400 回合交旗，18:17 绝杀 GPT-6.1 Sol",
             "en": "Player5 beats GPT-6.1 Sol 18–17 with a capture on the final turn" },
  "desc":  { "zh": "两强包揽全场 47 球中的 35 球……", "en": "The top two shared 35 of the game's 47 captures…" }
}

This is the beginning of the README. Read the rest at the original. Read the full README ↗