<!-- Auto-generated by claude-code. Edit the prompt, not this file. -->

# Playing CoGames in Mettascope

## What is Mettascope

Mettascope is the viewer for CoGames — the multi-cog territory-control games used to train AI in
the Metta platform. When you open it you see a top-down grid world populated by cogs, buildings,
resource nodes, and colored territory overlays. You can watch a pre-recorded replay or play live
alongside AI policies.

Mettascope has two view modes:

- **Game mode** — a full-screen map with HUD overlays for scores, resources, and cog controls.
- **Editor mode** — a panel-based layout with a resizable map view alongside inspection panels
  for detailed cog and environment data.

Press **G** or **F10** to switch between them.

---

## Getting Started

### Launching

| Mode | Command |
|------|---------|
| **Web demo** | [metta-ai.github.io/metta/mettascope](https://metta-ai.github.io/metta/mettascope/mettascope.html) |
| **Play** (live) | `uv run cogames play --mission machina_1 --cogs 4` |
| **Play** (with AI policy) | `uv run cogames play -m machina_1 -p class=nlanky` |
| **Replay** | `uv run cogames replay ./path/to/replay.json.z` |

Play mode starts a live simulation where you can control cogs alongside AI policies. Replay mode
loads a pre-recorded game for review.

### Basic navigation

- **Pan** — left-click and drag (or middle-click and drag) on the map.
- **Zoom** — scroll the mouse wheel. Zoom targets the cursor, or the focused cog if focus is
  locked.
- **Minimap** — click or drag on the minimap to jump the camera to that location.
- **Select a cog** — left-click on a cog. Double-click to lock the camera onto it.

---

## Controls Reference

### Keyboard shortcuts

| Key | Action |
|-----|--------|
| **Space** | Play / Pause |
| **\[** | Step back one frame |
| **\]** | Step forward one frame |
| **\-** | Halve playback speed |
| **=** | Double playback speed |
| **G** or **F10** | Toggle Game / Editor mode |
| **F** | Lock camera focus on selected cog |
| **Escape** | Cancel move / queue / repeat toggle modes |
| **W** / **Up** | Move selected cog North (play mode) |
| **S** / **Down** | Move selected cog South (play mode) |
| **A** / **Left** | Move selected cog West (play mode) |
| **D** / **Right** | Move selected cog East (play mode) |
| **X** | Send no-op action to selected cog (play mode) |
| **Enter** | Advance or dismiss tutorial overlay |
| **Cmd+Q** / **Super+Q** | Quit |

### Mouse interactions

| Action | Effect |
|--------|--------|
| **Left-click** | Select entity under cursor |
| **Double-click** | Toggle lock-focus on selected cog |
| **Left-drag** or **Middle-drag** | Pan the map |
| **Scroll wheel** | Zoom in / out |
| **Right-click** or **Ctrl+click** | Issue move order to selected cog (play mode) |
| **Shift+click** | Queue an additional move order |
| **R+click** | Set move order to repeat |
| **Minimap click/drag** | Reposition the camera |

> **Platform note:** On macOS, movement orders use **Cmd+click** instead of **Ctrl+click**.

---

## Understanding the Game

### Cogs and Clips

A **Cog** is a team unit on the grid. Cogs can be AI-controlled or player-controlled. In play
mode you can take direct control of a cog with WASD or right-click while the rest are AI-driven.
In replay mode you watch cogs execute their learned policies.

**Clips** are the automated adversary. They periodically neutralize and capture junctions adjacent
to their own territory, expanding outward in waves. Clips create constant pressure on all teams.

### The map

Games take place on a procedurally generated grid. Key locations:

| Feature | Purpose |
|---------|---------|
| **Hub** | Team home base. Projects territory, stores shared resources, crafts hearts. Cogs regenerate HP and energy inside the hub. |
| **Junctions** | Neutral capture points. Once claimed they project territory. Clips can also take them. |
| **Extractors** | Resource nodes where Miners harvest elements (carbon, oxygen, germanium, silicon). |
| **Gear Stations** | Allow cogs to equip a role by spending resources. |

### Roles

Cogs start as generic units. At a gear station a cog can equip a role, gaining stat bonuses and
abilities. Not all missions use roles. Only one role can be equipped at a time.

| Role | Bonus | Job |
|------|-------|-----|
| **Miner** | +40 cargo capacity, 10× extraction speed | Harvest resources at extractors and deposit at the hub |
| **Aligner** | Carries hearts | Capture neutral junctions (costs 1 heart each) |
| **Scrambler** | +200 HP | Neutralize enemy junctions (costs 1 heart each) |
| **Scout** | +100 energy, +400 HP | Mobile reconnaissance and map pressure |

No single role can win alone — cooperation across roles is essential.

### Economy

Resources flow through a simple chain: **Miners extract elements → deposit at Hub → Hub crafts
hearts → Aligners/Scramblers collect hearts to spend on junctions.**

### Territory

Hubs and aligned junctions project colored territory overlays (10-cell radius). Inside friendly
territory cogs regenerate HP and energy each tick. Outside it they take 1 HP damage per tick and
drain energy from movement.

### Scoring

Each tick, your team's reward equals the number of junctions it holds divided by the total number
of steps in the episode. Holding more junctions for longer yields a higher score.

For a deeper dive into game mechanics, see the
[simulation guide](simulation_guide.md).

---

## UI Panels

### Game mode HUD

| Location | Shows |
|----------|-------|
| **Top-left** | Team score and junction count |
| **Top-right** | Global resource counts (Carbon, Oxygen, Germanium, Silicon) |
| **Bottom-left** | Transport controls (rewind, step, play/pause) and visual toggles (grid, visual range, fog of war) |
| **Bottom-right** | Speed selector, action mode toggles (move, queue, repeat), and vibe buttons |
| **Bottom-center** | Selected cog info — name, team, stat bars (HP/energy), profile portrait, and inventory |
| **Bottom-left corner** | Minimap |

The bottom-right panel has three action mode toggles that modify how you issue orders:

| Toggle | Effect |
|--------|--------|
| **Move** | Enable click-to-move on the map |
| **Queue** | Append orders to the existing path instead of replacing (like holding Shift) |
| **Repeat** | Make the current order loop indefinitely |

Activating **Repeat** automatically enables **Queue** and **Move**; activating **Queue**
automatically enables **Move**.

### Editor mode panels

Editor mode splits the screen into resizable areas. Drag panel tabs between areas and resize
splits by dragging their borders.

| Panel | Purpose |
|-------|---------|
| **Map** | Zoomable, pannable world view (center) |
| **Object** | Properties of the selected entity — health, energy, inventory, tags, territory |
| **Policy Info** | Policy metadata and relative target data for the selected cog |
| **Environment** | Grid cell information and game config |
| **Minimap** | Zoomed-out overview with camera rectangle |
| **Vibes** | Grid of vibe action buttons for the selected cog |
| **Score** | Per-team stats — cog counts, building counts by type, average scores |
| **Monologue** | Narrative transcript or LLM conversation logs for the selected entity |

### Footer bar

The footer bar (visible in both modes) contains:

- **Transport buttons** — rewind to start, step back, play/pause, step forward, skip to end.
  Each button shows a tooltip on hover.
- **Speed selector** — preset speeds from 1× (turtle) through 5×, 10×, 50×, 100×, to 1000×
  (rabbit). You can also use **-** / **=** to halve or double the current speed.
- **Toggle buttons** — lock focus, show resources, show grid, show visual range, show fog of
  war, show heatmap.

### Visual overlays

| Overlay | Toggle | What it shows |
|---------|--------|---------------|
| **Grid** | Grid icon | Tile boundaries |
| **Visual Range** | Eye icon | Circle showing the selected cog's vision radius |
| **Fog of War** | Cloud icon | Darkened areas outside explored territory |
| **Heatmap** | Heatmap icon (editor mode footer) | Intensity map of cog presence over time |
| **Resources** | Heart icon | Resource indicators on cogs and buildings |
| **Territory (AoE)** | Always on | Colored overlays showing each team's controlled area |

---

## Tips

- **Start paused.** When you first load a replay, pause and step through a few frames to orient
  yourself before hitting play.
- **Use lock focus.** Press **F** (or double-click a cog) to pin the camera on a specific cog
  and follow its journey. Press **F** again, click the tack icon, or drag the map to unlock.
- **Slow it down.** Most replays are more readable at 5–10× speed than at 100×+. Use **-** to
  halve the speed.
- **Toggle overlays freely.** Fog of war and visual range show what an individual cog "knows."
  The heatmap shows where cogs spend their time across the full replay.
- **Use Editor mode for inspection.** Game mode gives a clean cinematic view, but Editor mode
  lets you inspect cog inventories, policy states, and environment details while watching.
- **Drag and resize panels.** In Editor mode, drag panel tabs to rearrange the layout and drag
  split borders to resize areas.
- **Watch the territory overlay.** The expanding and contracting colored regions are the clearest
  indicator of which team is winning.
- **Check the center panel.** In Game mode, click any cog or building to see its stats,
  inventory, and profile portrait in the bottom-center panel.
