# tools

Node tools need `npm install` here once (iced-x86). Module paths are passed
explicitly (`<Sacred 2 Gold>\system\s2logic.dll`, ...); VAs are at the
module's preferred base, as in Ghidra. In Git Bash, arguments starting with
`/` are rewritten as paths: set `MSYS_NO_PATHCONV=1` for `/regex/` and pass
module paths as `D:/...`.

| Tool | Purpose |
|---|---|
| `exports.mjs <module> [regex]` | exported functions/data with VAs, by decorated name (`exports.mjs s2logic.dll "@cQuestMgr@@"`) |
| `exports.mjs <module> 0xVA` | the nearest export at or before a VA |
| `disasm.mjs <module> <va> [n]` | disassemble at an address, ignoring Ghidra's function boundaries |
| `find-imm.mjs <module> <value...>` | every instruction using an immediate value (e.g. `1024 768`) |
| `find-imm.mjs <module> /regex/` | every instruction whose text matches |
| `rtti.mjs <module> <Class>` | vtables of an MSVC class via RTTI |
| `decompile.ps1 <module> <addr\|symbol...>` | decompile from the persistent Ghidra project `ghidra/` |
| `rename.ps1` | apply `names.txt` (`module 0xADDR Name`) to the Ghidra project |
| `game-input.ps1` | dot-source: `Start-Sacred2`, `Focus-Sacred2`, `Get-GameWindows`, clicks, keys, `Save-Screen`, `Stop-Sacred2` |

## Driving the game

Started from a background process, the game window doesn't get the
foreground; `Focus-Sacred2` (synthetic Alt + `SetForegroundWindow`) brings it
up. The intro videos run ~50 s before the main menu. Synthetic clicks reach
the menu only sometimes (2026-10-31: "Beenden" opened its dialog once, the
dialog's "Ja" never reacted); `$game.CloseMainWindow()` quits the game
cleanly. Don't touch mouse/keyboard while a script drives the game.

## Persistent Ghidra project (`ghidra/`, not in git)

One project `sacred2` with a program per module, created once (Ghidra's own
analysis; exports give most functions their names and MSVC 8 RTTI is
recognised):

```powershell
$env:GHIDRA_HEADLESS_MAXMEM = "12G"
$sys = "<Sacred 2 Gold>\system"
& "$env:GHIDRA_INSTALL_DIR\support\analyzeHeadless.bat" ghidra sacred2 -import "$sys\sacred2.exe" "$sys\orcSystem.dll" "$sys\s2core.dll" "$sys\s2logic.dll" "$sys\s2logicai.dll" "$sys\s2render.dll" -analysisTimeoutPerFile 7200
```

```powershell
.\tools\decompile.ps1 orcSystem.dll 0x10018c60 -ReadOnly
.\tools\decompile.ps1 s2logic.dll "?advanceTime@cQuestMgr@@QAEXM@Z" -ReadOnly
```