Add replay subcommand

Author: john-b-yang

codeclash/arenas/battlesnake/replay.py

@@ -0,0 +1,136 @@
+"""BattleSnake replay renderer.
+
+Parses a recorded ``sim_*.jsonl`` (v1 API state frames) into normalized playback data
+and draws the board — snakes with heads/eyes, food, hazards, per-snake health.
+Ported from the former ``scripts/replay_battlesnake.py``.
+
+The jsonl format: per-turn v1 state frames ({game, turn, board, you}) and a final result
+line ({winnerName, isDraw}).
+"""
+
+from __future__ import annotations
+
+import json
+
+from codeclash.replay.base import ReplayData, ReplayRenderer
+
+PALETTE = ["#3B78FF", "#E5484D", "#30A46C", "#F5A623", "#8E4EC6", "#12A594", "#E93D82", "#F76B15"]
+
+DRAW_JS = """
+const ARENA = (function(){
+  let W, H, CELL, PAD, px, py;
+  function setup(cv, G){
+    W = G.w; H = G.h;
+    CELL = Math.max(18, Math.min(44, Math.floor(560 / Math.max(W, H)))); PAD = CELL * 0.12;
+    cv.width = W * CELL; cv.height = H * CELL;
+    px = (x) => x * CELL; py = (y) => (H - 1 - y) * CELL;  // v1 y-up -> canvas y-down
+  }
+  function draw(ctx, cv, G, i){
+    const f = G.frames[i], COL = G.colors;
+    ctx.clearRect(0, 0, cv.width, cv.height);
+    ctx.strokeStyle = '#21262d';
+    for(let x=0;x<=W;x++){ctx.beginPath();ctx.moveTo(x*CELL,0);ctx.lineTo(x*CELL,H*CELL);ctx.stroke();}
+    for(let y=0;y<=H;y++){ctx.beginPath();ctx.moveTo(0,y*CELL);ctx.lineTo(W*CELL,y*CELL);ctx.stroke();}
+    f.hazards.forEach(([x,y])=>{ctx.fillStyle='rgba(245,166,35,0.15)';ctx.fillRect(px(x),py(y),CELL,CELL);});
+    f.food.forEach(([x,y])=>{ctx.fillStyle='#ff5252';ctx.beginPath();ctx.arc(px(x)+CELL/2,py(y)+CELL/2,CELL*0.22,0,7);ctx.fill();});
+    f.snakes.forEach(s=>{
+      const c = COL[s.name] || '#888';
+      s.body.forEach(([x,y],j)=>{
+        ctx.fillStyle=c; ctx.globalAlpha=j===0?1:0.85;
+        const r=j===0?CELL*0.5:CELL*0.32;
+        ctx.beginPath(); ctx.roundRect(px(x)+PAD,py(y)+PAD,CELL-2*PAD,CELL-2*PAD, r); ctx.fill();
+      });
+      ctx.globalAlpha=1;
+      const [hx,hy]=s.body[0]; ctx.fillStyle='#0d1117';
+      ctx.beginPath();ctx.arc(px(hx)+CELL*0.62,py(hy)+CELL*0.38,CELL*0.08,0,7);ctx.fill();
+    });
+  }
+  function side(G, i){
+    const f = G.frames[i], COL = G.colors;
+    const alive = new Set(f.snakes.map(s=>s.name));
+    return Object.keys(COL).map(nm=>{
+      const s = f.snakes.find(x=>x.name===nm); const hp = s?s.health:0; const dead = !alive.has(nm);
+      return `<div class="sn ${dead?'dead':''}"><span class="sw" style="background:${COL[nm]}"></span>
+        <span style="min-width:80px">${nm}</span>
+        <span class="hb"><span class="hf" style="width:${hp}%;background:${COL[nm]}"></span></span>
+        <span>${dead?'\\u2620':hp}</span></div>`;
+    }).join('');
+  }
+  return {setup, draw, side};
+})();
+"""
+
+
+class BattleSnakeReplayer(ReplayRenderer):
+    arena = "BattleSnake"
+    sim_glob = "sim_*.jsonl"
+    DRAW_JS = DRAW_JS
+
+    def parse(self, raw: bytes, players=None) -> ReplayData:
+        rows = [json.loads(line) for line in raw.decode().splitlines() if line.strip()]
+        # per-turn board states (dedupe: keep the last frame seen for each turn)
+        by_turn = {}
+        for r in rows:
+            if isinstance(r, dict) and "board" in r and "turn" in r:
+                by_turn[r["turn"]] = r["board"]
+        turns = sorted(by_turn)
+        result = next((r for r in reversed(rows) if isinstance(r, dict) and "winnerName" in r), {})
+        if not turns:
+            return ReplayData(w=0, h=0, frames=[], winner=result.get("winnerName"), draw=result.get("isDraw", False))
+
+        # stable color per snake name (prefer the snake's own color from the log if present)
+        names, colors = [], {}
+        for t in turns:
+            for s in by_turn[t]["snakes"]:
+                if s["name"] not in names:
+                    names.append(s["name"])
+        for i, nm in enumerate(names):
+            colors[nm] = PALETTE[i % len(PALETTE)]
+        for t in turns:
+            for s in by_turn[t]["snakes"]:
+                if s.get("color"):
+                    colors[s["name"]] = s["color"]
+
+        b0 = by_turn[turns[0]]
+        frames = []
+        for t in turns:
+            b = by_turn[t]
+            frames.append(
+                {
+                    "turn": t,
+                    "food": [[c["x"], c["y"]] for c in b.get("food", [])],
+                    "hazards": [[c["x"], c["y"]] for c in b.get("hazards", [])],
+                    "snakes": [
+                        {
+                            "name": s["name"],
+                            "health": s.get("health", 0),
+                            "body": [[c["x"], c["y"]] for c in s["body"]],
+                        }
+                        for s in b["snakes"]
+                    ],
+                }
+            )
+        return ReplayData(
+            w=b0["width"],
+            h=b0["height"],
+            frames=frames,
+            winner=result.get("winnerName"),
+            draw=result.get("isDraw", False),
+            extra={"colors": colors},
+        )
+
+    def ascii(self, data: ReplayData) -> str:
+        out = []
+        for f in data.frames:
+            grid = [["." for _ in range(data.w)] for _ in range(data.h)]
+            for fx, fy in f["food"]:
+                grid[fy][fx] = "*"
+            for s in f["snakes"]:
+                ch = s["name"][0].upper()
+                for j, (x, y) in enumerate(s["body"]):
+                    grid[y][x] = ch if j else ch.lower()  # head lowercase-ish marker
+            out.append(f"\n--- turn {f['turn']} ---  " + "  ".join(f"{s['name']}:{s['health']}" for s in f["snakes"]))
+            for row in reversed(grid):  # y-up: print top row last
+                out.append(" ".join(row))
+        out.append(f"\nWinner: {'TIE' if data.draw else data.winner}")
+        return "\n".join(out)

codeclash/arenas/robotrumble/replay.py

@@ -0,0 +1,181 @@
+"""RobotRumble replay renderer.
+
+Parses a raw RobotRumble sim JSON (``rumblebot run term --raw``) into normalized playback
+data and draws the grid — terrain/walls, units colored by team with health-as-brightness,
+move/attack indicators, per-team unit + health totals. Ported from the former
+``scripts/replay_robotrumble.py``.
+
+The raw JSON: a single object {winner, errors, turns:[...]}. Each turn has ``state.objs``
+(grid objects: Terrain/Wall and Unit/Soldier, each with ``coords`` [x,y], ``team``,
+``health``), a ``state.turn`` index, and ``robot_actions`` (unit id ->
+{"Ok": {"type": "Move"|"Attack", "direction": ...}} or {"Ok": "None"}). Blue is the first
+(blue) bot, Red is the second.
+"""
+
+from __future__ import annotations
+
+import json
+
+from codeclash.replay.base import ReplayData, ReplayRenderer
+
+MAX_HEALTH = 5
+TEAM_COLORS = {"Blue": "#3B78FF", "Red": "#E5484D"}
+
+DRAW_JS = """
+const ARENA = (function(){
+  let W, H, CELL, PAD, COL, NAMES, MAXHP, WALLS, px, py;
+  const DIRV = {North:[0,-1], South:[0,1], East:[1,0], West:[-1,0]};
+  function setup(cv, G){
+    W = G.w; H = G.h; COL = G.colors; NAMES = G.names; MAXHP = G.maxhp; WALLS = G.walls;
+    CELL = Math.max(16, Math.min(40, Math.floor(640 / Math.max(W, H)))); PAD = CELL * 0.14;
+    cv.width = W * CELL; cv.height = H * CELL;
+    px = (x) => x * CELL; py = (y) => y * CELL;  // RobotRumble: y=0 at top, render straight down
+  }
+  function draw(ctx, cv, G, i){
+    const f = G.frames[i];
+    ctx.clearRect(0, 0, cv.width, cv.height);
+    ctx.strokeStyle = '#21262d'; ctx.lineWidth = 1;
+    for(let x=0;x<=W;x++){ctx.beginPath();ctx.moveTo(x*CELL,0);ctx.lineTo(x*CELL,H*CELL);ctx.stroke();}
+    for(let y=0;y<=H;y++){ctx.beginPath();ctx.moveTo(0,y*CELL);ctx.lineTo(W*CELL,y*CELL);ctx.stroke();}
+    ctx.fillStyle = '#2d333b';
+    WALLS.forEach(([x,y])=>{ctx.fillRect(px(x)+1,py(y)+1,CELL-2,CELL-2);});
+    f.units.forEach(u=>{
+      const base = COL[u.team] || '#888';
+      const frac = Math.max(0.28, u.hp / MAXHP);  // health -> opacity (full hp brightest)
+      ctx.globalAlpha = frac;
+      ctx.fillStyle = base;
+      const r = CELL * 0.28;
+      ctx.beginPath(); ctx.roundRect(px(u.x)+PAD,py(u.y)+PAD,CELL-2*PAD,CELL-2*PAD,r); ctx.fill();
+      ctx.globalAlpha = 1;
+      const cx = px(u.x)+CELL/2, cy = py(u.y)+CELL/2;
+      if(u.act === 'Attack'){
+        ctx.strokeStyle = '#ffd21f'; ctx.lineWidth = 2;
+        ctx.beginPath(); ctx.arc(cx,cy,CELL*0.42,0,7); ctx.stroke();
+        const d = DIRV[u.dir]; if(d){
+          ctx.fillStyle = '#ffd21f';
+          ctx.beginPath(); ctx.arc(cx+d[0]*CELL*0.5, cy+d[1]*CELL*0.5, CELL*0.12,0,7); ctx.fill();
+        }
+      }
+      if(u.act === 'Move'){
+        const d = DIRV[u.dir];
+        if(d){
+          ctx.strokeStyle = 'rgba(255,255,255,0.85)'; ctx.lineWidth = 2;
+          ctx.beginPath(); ctx.moveTo(cx,cy); ctx.lineTo(cx+d[0]*CELL*0.28, cy+d[1]*CELL*0.28); ctx.stroke();
+        }
+      }
+      const bw = CELL-2*PAD, bx = px(u.x)+PAD, by = py(u.y)+CELL-PAD*0.5;
+      ctx.fillStyle = 'rgba(0,0,0,0.45)'; ctx.fillRect(bx,by-3,bw,3);
+      ctx.fillStyle = '#eafff0'; ctx.fillRect(bx,by-3,bw*(u.hp/MAXHP),3);
+    });
+  }
+  function side(G, i){
+    const f = G.frames[i], COL = G.colors, NAMES = G.names, MAXHP = G.maxhp;
+    const agg = {Blue:{n:0,hp:0}, Red:{n:0,hp:0}};
+    f.units.forEach(u=>{ if(agg[u.team]){ agg[u.team].n++; agg[u.team].hp += u.hp; } });
+    return ['Blue','Red'].map(tm=>{
+      const a = agg[tm], dead = a.n===0, maxhp = 8*MAXHP;
+      return `<div class="team ${dead?'tdead':''}">
+        <div class="tname"><span class="sw" style="background:${COL[tm]}"></span>${NAMES[tm]} <span class="muted">(${tm})</span></div>
+        <div class="stat"><span>units</span><b>${a.n}</b></div>
+        <div class="stat"><span>total health</span><b>${a.hp}</b></div>
+        <div class="hb"><span class="hf" style="width:${Math.min(100,100*a.hp/maxhp)}%;background:${COL[tm]}"></span></div>
+      </div>`;
+    }).join('') + '<div class="row muted" style="font-size:12px">move arrow \\u00b7 \\u2726 attacking \\u00b7 health = brightness</div>';
+  }
+  return {setup, draw, side};
+})();
+"""
+
+
+class RobotRumbleReplayer(ReplayRenderer):
+    arena = "RobotRumble"
+    sim_glob = "sim*.json"  # matches both sim_<i>.json and an ad-hoc flat sim.json
+    DRAW_JS = DRAW_JS
+
+    def parse(self, raw: bytes, players=None) -> ReplayData:
+        data = json.loads(raw.decode())
+        turns_raw = data.get("turns", [])
+        blue_name = players[0]["name"] if players and len(players) > 0 else None
+        red_name = players[1]["name"] if players and len(players) > 1 else None
+
+        # Walls (terrain) are static across the game — grab them from the first frame.
+        walls = []
+        max_x = max_y = 0
+        if turns_raw:
+            for o in turns_raw[0]["state"]["objs"].values():
+                x, y = o["coords"]
+                max_x, max_y = max(max_x, x), max(max_y, y)
+                if o["obj_type"] == "Terrain":
+                    walls.append([x, y])
+
+        frames = []
+        for t in turns_raw:
+            objs = t["state"]["objs"]
+            actions = t.get("robot_actions") or {}
+            units = []
+            for oid, o in objs.items():
+                if o["obj_type"] != "Unit":
+                    continue
+                act = actions.get(oid)
+                atype, adir = None, None
+                if isinstance(act, dict) and "Ok" in act:
+                    ok = act["Ok"]
+                    if isinstance(ok, dict):
+                        atype, adir = ok.get("type"), ok.get("direction")
+                units.append(
+                    {
+                        "team": o.get("team"),
+                        "hp": o.get("health", 0),
+                        "x": o["coords"][0],
+                        "y": o["coords"][1],
+                        "act": atype,
+                        "dir": adir,
+                    }
+                )
+            frames.append({"turn": t["state"].get("turn"), "units": units})
+
+        winner_raw = data.get("winner")
+        names = {"Blue": blue_name or "Blue", "Red": red_name or "Red"}
+        if winner_raw in ("Blue", "Red"):
+            winner, draw = names[winner_raw], False
+        else:
+            winner, draw = None, True
+
+        return ReplayData(
+            w=max_x + 1,
+            h=max_y + 1,
+            frames=frames,
+            winner=winner,
+            draw=draw,
+            extra={
+                "walls": walls,
+                "names": names,
+                "colors": TEAM_COLORS,
+                "maxhp": MAX_HEALTH,
+                "errors": data.get("errors", {}),
+            },
+        )
+
+    def ascii(self, data: ReplayData) -> str:
+        W, H = data.w, data.h
+        names = data.extra["names"]
+        wall_set = {(x, y) for x, y in data.extra["walls"]}
+        out = []
+        for f in data.frames:
+            grid = [["#" if (x, y) in wall_set else "." for x in range(W)] for y in range(H)]
+            for u in f["units"]:
+                grid[u["y"]][u["x"]] = "B" if u["team"] == "Blue" else "R"
+            counts = {"Blue": 0, "Red": 0}
+            hp = {"Blue": 0, "Red": 0}
+            for u in f["units"]:
+                counts[u["team"]] += 1
+                hp[u["team"]] += u["hp"]
+            out.append(
+                f"\n--- turn {f['turn']} ---  "
+                f"{names['Blue']}(B): {counts['Blue']} units / {hp['Blue']} hp   "
+                f"{names['Red']}(R): {counts['Red']} units / {hp['Red']} hp"
+            )
+            for row in grid:
+                out.append(" ".join(row))
+        out.append(f"\nWinner: {'TIE' if data.draw else data.winner}")
+        return "\n".join(out)

codeclash/cli/app.py

@@ -5,6 +5,7 @@
     codeclash ladder make <config>    build a ladder (round-robin ranking)
     codeclash ladder run <config>     send a model up a ranked ladder
     codeclash rank {win-rate,elo,matrix} ...   compute standings from logs
+    codeclash replay <log-folder>     browse/animate recorded games
 """
 
 import getpass
@@ -19,6 +20,7 @@
 from codeclash import CONFIG_DIR
 from codeclash.cli.ladder import ladder_app
 from codeclash.cli.rank import rank_app
+from codeclash.cli.replay import replay
 from codeclash.constants import LOCAL_LOG_DIR
 from codeclash.tournaments.pvp import PvpTournament
 from codeclash.utils.aws import is_running_in_aws_batch
@@ -27,11 +29,13 @@
 app = typer.Typer(
     no_args_is_help=True,
     add_completion=False,
+    rich_markup_mode="rich",  # enables the [dim] markup used in the Examples blocks
     context_settings={"help_option_names": ["-h", "--help"]},
     help="CodeClash: run coding-game tournaments, build ladders, and rank players.",
 )
 app.add_typer(ladder_app, name="ladder", help="Build and run CC:Ladder tournaments.")
 app.add_typer(rank_app, name="rank", help="Compute player standings from game logs.")
+app.command("replay")(replay)
 
 
 @app.command()
@@ -44,7 +48,11 @@ def run(
         False, "--keep-containers", "-k", help="Do not remove containers after games/agent finish."
     ),
 ):
-    """Run a PvP tournament from a config file."""
+    """Run a PvP tournament from a config file.
+
+    [dim]• codeclash run configs/test/battlesnake_pvp_test.yaml[/dim]
+    [dim]• codeclash run path/to/config.yaml -c -o out/  # cleanup + custom output dir[/dim]
+    """
     yaml_content = config_path.read_text()
     preprocessed_yaml = resolve_includes(yaml_content, base_dir=CONFIG_DIR)
     config = yaml.safe_load(preprocessed_yaml)

codeclash/cli/ladder.py

@@ -13,15 +13,21 @@
 from codeclash.utils.yaml_utils import resolve_includes
 
 ladder_app = typer.Typer(
-    no_args_is_help=True, add_completion=False, context_settings={"help_option_names": ["-h", "--help"]}
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",  # enables the [dim] markup used in the Examples blocks
+    context_settings={"help_option_names": ["-h", "--help"]},
 )
 
 
 @ladder_app.command("make")
 def make(
     config_path: Path = typer.Argument(..., help="Path to the ladder (round-robin) config file."),
 ):
-    """Build a ladder: run PvP tournaments across all pairs of players (for ranking)."""
+    """Build a ladder: run PvP tournaments across all pairs of players (for ranking).
+
+    [dim]• codeclash ladder make configs/ablations/ladder/make_battlesnake.yaml[/dim]
+    """
     yaml_content = config_path.read_text()
     preprocessed_yaml = resolve_includes(yaml_content, base_dir=CONFIG_DIR)
     config = yaml.safe_load(preprocessed_yaml)
@@ -58,7 +64,10 @@ def run(
         False, "--keep-containers", "-k", help="Do not remove containers after games/agent finish."
     ),
 ):
-    """Send a model up a ranked ladder, rung by rung, until it loses."""
+    """Send a model up a ranked ladder, rung by rung, until it loses.
+
+    [dim]• codeclash ladder run path/to/ladder_config.yaml -c  # clean up after each rung[/dim]
+    """
     yaml_content = config_path.read_text()
     preprocessed_yaml = resolve_includes(yaml_content, base_dir=CONFIG_DIR)
     config = yaml.safe_load(preprocessed_yaml)