firestorm/.claude/skills/run-firestorm/SKILL.md

name, description

name	description
run-firestorm	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).