CydandClaude Fable 5
2cfb14ab98
driver.ps1 commands: status/windows, report <Mission> (headless editor mission-load smoke test), editor-start, game-start, shot/shotwin, click, stop. All flows verified live: Coliseum report (248 entities), editor UI screenshot, game console screenshot + Map-tab click. Screenshots dir is gitignored (can capture the operator desktop). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
118 lines
6.6 KiB
Markdown
118 lines
6.6 KiB
Markdown
---
|
||
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).
|