---
name: run-firestorm
description: Run, launch, drive, screenshot, or smoke-test BattleTech FireStorm — the game (MW4.exe, fullscreen), the mission editor (MW4Ed2.exe, windowed), or a headless mission-load report. Use for "run the game", "start the editor", "screenshot the app", "verify a mission loads".
---

# Run FireStorm (game + mission editor)

All paths relative to the repo root (`c:\VWE\firestorm`). Everything is driven through
**`.claude\skills\run-firestorm\driver.ps1`** — do not poke the exes directly; the driver
handles working directories, single-instance guards, window discovery, and screenshots.

**This is the operator's real desktop, not a headless box.** The game takes the primary
display fullscreen (800×600 16-bit). A human may be using the machine — prefer the headless
`report` path or the windowed editor unless you actually need the game UI.

## Prerequisites

Already satisfied on this machine: the deployed game at `MW4\`, the editor installed in
place at `Gameleap\mw4\MW4Ed2.exe`, and the per-path `DWM8And16BitMitigation` AppCompat
shims. On a fresh machine, follow `RECOVERY.md` first, then `build-env\deploy-mw4.ps1` and
`build-env\deploy-editor.ps1` (they re-apply the shims — AppCompat is keyed on exe path).

## Agent path — the driver

```
powershell -ExecutionPolicy Bypass -File .claude\skills\run-firestorm\driver.ps1 <command> [args]
```

| Command | What it does |
|---|---|
| `status` / `windows` | List FireStorm processes and their top-level windows (how you detect modal dialogs) |
| `report <Mission>` | **Headless smoke test**: editor loads the mission hidden, writes `Gameleap\mw4\<Mission>.report` (entity counts etc.), driver prints it. ~1–2 min. Mission = folder name under `Gameleap\mw4\Content\Missions` |
| `editor-start` | Launch the windowed mission editor; waits (≤180 s) for its UI |
| `game-start` | Launch the fullscreen game; waits for the `BattleTech Firestorm` window |
| `shot [name]` | Screenshot the **primary screen** → `.claude\skills\run-firestorm\shots\<name>.png`, prints mean brightness (≈0 = dead capture) |
| `shotwin <titleRegex> [name]` | Screenshot cropped to one app window (foregrounds it first) — use for the editor |
| `click <x> <y>` | Left-click at screen coords; restores+foregrounds the app first (fullscreen game: screen coords = game coords at 800×600) |
| `stop` | Kill MW4Ed2 / MW4 / MW4pro |

### Verified flows (each of these ran end-to-end)

Headless mission check — the fastest "does the content pipeline still work":

```
powershell -ExecutionPolicy Bypass -File .claude\skills\run-firestorm\driver.ps1 report Coliseum
```

→ `editor exit code: 1` (normal — see Gotchas) and a report: `Total Entities=248`, per-class counts.

Editor UI + screenshot:

```
powershell -ExecutionPolicy Bypass -File .claude\skills\run-firestorm\driver.ps1 editor-start
powershell -ExecutionPolicy Bypass -File .claude\skills\run-firestorm\driver.ps1 shotwin 'Mission Editor' editor-main
powershell -ExecutionPolicy Bypass -File .claude\skills\run-firestorm\driver.ps1 stop
```

Game UI + interaction + screenshot (grabs the display — coordinate with the operator):

```
powershell -ExecutionPolicy Bypass -File .claude\skills\run-firestorm\driver.ps1 game-start
powershell -ExecutionPolicy Bypass -File .claude\skills\run-firestorm\driver.ps1 shot game-shell
powershell -ExecutionPolicy Bypass -File .claude\skills\run-firestorm\driver.ps1 click 617 64
powershell -ExecutionPolicy Bypass -File .claude\skills\run-firestorm\driver.ps1 shot game-map-tab
powershell -ExecutionPolicy Bypass -File .claude\skills\run-firestorm\driver.ps1 stop
```

The game boots into the **BattleTech Console V5.07** lobby (player roster + Mission/Map
tabs); `click 617 64` switches to the Map tab.

## Human path

- Game: run `MW4\MW4.exe` (fullscreen; Alt-Tab minimizes it).
- Editor: `Gameleap\mw4\run-editor.bat`.

## Build / rebuild (separate concern)

Code builds via VC6 (`Gameleap\code\mw4\Code\MechWarrior4.dsw`), resources via
`build-env\build-resources.ps1`, deploy via `build-env\deploy-mw4.ps1` — see `CLAUDE.md`
STEP 3/4 and `build-env\RESOURCE-BUILD.md`. Not needed just to run what's deployed.

## Gotchas (all hit while building this skill)

- **`-report` always `exit(1)`**, success or not — the editor's code literally ends with
  `exit(1)`. Judge success by the `.report` file content (`UnLoadable` = failed load). The
  report lands in `Gameleap\mw4\` (the exe's CWD); delete it after reading — don't commit it.
- **The game window title is `BattleTech Firestorm`** — not "MechWarrior", not "MW4". There
  is also a second 640×480 helper window `DirectDrawDeviceWnd` (ignore it).
- **Fullscreen game minimizes the instant it loses focus** (fullscreen-exclusive DDraw), and
  the desktop reverts to native resolution — a `shot` taken then captures the desktop, not
  the game. `click` restores + refocuses and waits ~2.5 s for the mode switch back.
- **Editor window titles randomly carry a `[DDrawCompat] ` prefix** (the compat layer
  retitles); enumeration shows both variants. Match titles loosely (`'Mission Editor'`).
- **Both exes are single-instance** (editor via mutex → modal "already running" message box
  that hangs automation). The driver refuses to double-launch; `stop` first.
- **Editor startup is slow (~30–60 s)**: it loads/validates the whole content tree (a
  "Building Resources..." window appears first) and LAB builds **STOP with a modal dialog on
  the first broken content file** — if `editor-start` times out, check `windows` for a STOP
  dialog before assuming a hang.
- **Running either app dirties tracked runtime logs** (`Gameleap\mw4\DebugLog.txt`,
  `DDrawCompat-MW4Ed2.log` — this repo mirrors everything). `git restore` them afterwards.
- **`driver.ps1` must stay pure ASCII** — PowerShell 5.1 reads BOM-less files as ANSI; a
  single em-dash produces "Missing closing '}'" parse errors.
- **Screenshots can capture the operator's desktop** (second monitor, minimized-game
  moments). `shots\` is gitignored — never commit them, and `shot` deliberately captures
  only the primary screen.

## Troubleshooting

- `Game window did not appear within 120 s` but the process exists → the wait pattern didn't
  match a retitled window; run `status` to see the real title.
- `report`: "No report file produced" → the editor hit a content STOP before `MakeReport`;
  run `editor-start` and `windows` to read the STOP dialog text.
- Driver parse errors mentioning `—` → someone re-saved it with non-ASCII characters; see
  Gotchas.
- Game shows `[DDrawCompat] Fatal Error` → DDrawCompat's `ddraw.dll` leaked next to a game
  exe; it belongs only in `Gameleap\mw4` for the editor (see `deploy-*.ps1` skip rules).