paavohtl Claude Opus 4.6 (1M context) commited on
Commit
095235d
Β·
1 Parent(s): 14c0aff

docs: split CLAUDE.md into focused per-crate files and skills

Browse files

Root CLAUDE.md trimmed from 391 to ~120 lines. Moved content to:
- crates/openwa-core/CLAUDE.md: address registry, FieldRegistry, vtable macros
- crates/openwa-wormkit/CLAUDE.md: hooking patterns, bridge functions, installation
- crates/openwa-test-runner/CLAUDE.md: test isolation, crash detection, env vars
- .claude/skills/desync-debug/SKILL.md: trace-desync, desync methodology

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/skills/desync-debug/SKILL.md ADDED
@@ -0,0 +1,55 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ name: desync-debug
3
+ description: Diagnose replay desync failures using trace-desync, hardware watchpoints, and per-frame analysis. Use ONLY after a headless replay test has already detected a checksum mismatch.
4
+ ---
5
+
6
+ # Desync Debugging
7
+
8
+ **This is a diagnostic workflow, not a testing tool.** Only use after a headless replay test has already failed with a log mismatch. Do NOT run trace-desync speculatively or as part of normal testing.
9
+
10
+ Workflow: test fails -> trace-desync to find divergent frame -> investigate cause.
11
+
12
+ ## Trace-Desync
13
+
14
+ The `trace-desync` subcommand hooks WA's own `GameFrameChecksumProcessor` (0x5329C0) to capture per-frame checksums, runs the game twice (baseline with minimal hooks vs all hooks), and diffs the results:
15
+
16
+ ```bash
17
+ .\trace-desync.ps1 testdata/replays/longbow.WAgame
18
+
19
+ # Or directly:
20
+ openwa-test trace-desync testdata/replays/longbow.WAgame [--no-build] [--wa-path PATH]
21
+ ```
22
+
23
+ Baseline mode (`OPENWA_TRACE_BASELINE=1`) installs only: headless, file_isolation, frame_hook, trace_desync. All gameplay hooks (replay, weapon, sound, constructor, etc.) are skipped, giving a "nearly vanilla" WA reference run.
24
+
25
+ Output reports the first divergent frame or confirms all checksums match. Per-frame hash logs are saved in `testdata/runs/trace-<timestamp>/`.
26
+
27
+ ## Desync Debugging Methodology
28
+
29
+ Replay desyncs (checksum mismatches) can be caused by any code difference -- constructor side effects, hooked function behaviour, missing state, wrong calling conventions, etc. Key methodology:
30
+
31
+ 0. **Start with `trace-desync`**: Run `.\trace-desync.ps1 testdata/replays/<replay>.WAgame` to automatically find the exact frame where baseline and hooked runs diverge.
32
+ 1. **WA uses a single shared RNG** (DDGame+0x45EC, `AdvanceGameRNG` at 0x53F320) for both gameplay AND visual effects. There is no separate "visual RNG." Even purely decorative things like particle sprites affect the game RNG and will cause desyncs in headless mode if handled differently. A secondary effect RNG exists at DDGame+0x45F0 (`advance_effect_rng()`, simpler LCG without frame_counter) -- used by WeaponRelease visual effects. Uses `team_health_ratio[0]` (unused index-0 slot).
33
+ 2. **DDGame flat memory matching is NOT sufficient.** Constructors and hooks have side effects on sub-objects (display, GfxHandler, PCLandscape). Compare all objects pointed to by DDGame AND DDGameWrapper.
34
+ 3. **Use hardware watchpoints** (see "Hardware Watchpoints" in CLAUDE.md) to find what writes a specific field.
35
+ 4. **Per-frame RNG logging** (DDGame+0x45EC) pinpoints the exact frame where simulation diverges. Binary search on frames, not code.
36
+ 5. **Always validate diff methodology** against a known-good frame first. The snapshot system's pointer canonicalization produces false positives.
37
+
38
+ See `docs/re-notes/desync-investigation.md` for a detailed case study.
39
+
40
+ ## Environment Variables
41
+
42
+ - `OPENWA_TRACE_DESYNC=1` -- Enable per-frame checksum logging (hooks GameFrameChecksumProcessor)
43
+ - `OPENWA_TRACE_BASELINE=1` -- Baseline mode: skip all gameplay hooks, keep only infrastructure
44
+ - `OPENWA_TRACE_HASH_PATH=<path>` -- Override frame hash log location (default: frame_hashes.log)
45
+
46
+ See "Hardware Watchpoints" in CLAUDE.md for watchpoint env vars (`OPENWA_WATCH_FRAME`, etc.).
47
+
48
+ ## Key Files
49
+
50
+ - `crates/openwa-wormkit/src/replacements/trace_desync.rs` -- Per-frame checksum logging
51
+ - `crates/openwa-wormkit/src/debug_watchpoint.rs` -- Hardware watchpoint instrumentation
52
+ - `crates/openwa-wormkit/src/replacements/frame_hook.rs` -- Frame hook (watchpoint arming)
53
+ - `crates/openwa-test-runner/` -- Test runner that detects failures
54
+ - `docs/re-notes/desync-investigation.md` -- Detailed case study
55
+ - `trace-desync.ps1` -- Convenience script
CLAUDE.md CHANGED
@@ -1,166 +1,55 @@
1
- # CLAUDE.md
2
-
3
- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
 
5
  ## Project
6
 
7
- OpenWA is an incremental Rust reimplementation of Worms Armageddon 3.8.1 (Steam). The strategy is "parasite" β€” WormKit DLLs injected into the running game that progressively replace functions, starting from self-contained "leaf" functions and working inward.
8
-
9
- **Target:** WA.exe is a 32-bit x86 Windows PE binary built with MSVC 2005 + MFC. All Rust code targets `i686-pc-windows-msvc`.
10
 
11
- ## Build & Test
12
 
13
- ```bash
14
- # Build everything (default target is i686-pc-windows-msvc via .cargo/config.toml)
15
- cargo build --release
16
 
17
- # Build a specific crate
18
- cargo build -p openwa-wormkit --release
 
 
 
 
 
 
19
 
20
- # Run tests (openwa-types is pure Rust, works on any host)
21
- cargo test -p openwa-core
22
 
23
- # Single test
24
- cargo test -p openwa-core -- scheme_parse::parse_beginner_v2
25
- ```
26
 
27
- ## How to run the game with the DLL
28
 
29
- It used to be necessary to copy the built DLLs to the game directory and launch WA.exe. **HOWEVER**, we now have the launcher crate (`openwa-launcher`) that automatically starts the game with the correct DLL injected.
30
 
31
  ## Replay Testing
32
 
33
- **Use replay testing to validate assumptions and test theories!** Make a hypothesis, implement it in the DLL, then run replay tests to see if it holds up against the real game. This iterative approach is much faster than trying to get everything right from static analysis alone.
34
-
35
- ### Headless test runner (primary)
36
-
37
- The `openwa-test-runner` crate (`openwa-test` binary) runs all replay tests automatically with concurrent execution:
38
-
39
- ```bash
40
- # Run all tests (builds everything, default 4 concurrent):
41
- .\run-tests.ps1
42
-
43
- # Filter by name, control parallelism:
44
- .\run-tests.ps1 longbow # only tests matching "longbow"
45
- .\run-tests.ps1 -j 1 # serial mode
46
- .\run-tests.ps1 --no-build # skip internal DLL/launcher build
47
- ```
48
-
49
- Each test runs WA.exe in headless `/getlog` mode (pure CPU simulation, no rendering) and compares the output log byte-for-byte against an expected baseline.
50
-
51
- **Test isolation** (all in headless mode only):
52
- - Per-PID temp directory: `.openwa_tmp/{pid}/` for writable files (writetest.txt, mono.tmp, land.dat, landgen.svg, etc.)
53
- - Per-PID named event: `OpenWA_HooksReady_{pid}` for launcher↔DLL synchronization
54
- - Per-PID semaphore: `CreateSemaphoreA("Worms Armageddon")` renamed to `Worms Armageddon_{pid}`
55
- - Per-PID log paths via `OPENWA_LOG_PATH` and `OPENWA_ERRORLOG_PATH` env vars
56
- - Per-PID file redirection via `file_isolation.rs` (CreateFileA hook redirects playback.thm, current.thm, land.dat, landgen.svg to `.openwa_tmp/{pid}/`)
57
- - WA.exe crash dialog suppressed via `/silentcrash` command-line flag
58
- - Batched MinHook enables: all hooks use `queue_enable_hook` + single `apply_queued()` call
59
-
60
- **Crash detection**: Tests that crash show `CRASH` (not `FAIL`) with NTSTATUS name and ERRORLOG.TXT content. ERRORLOG.TXT is redirected to the per-test run directory via `OPENWA_ERRORLOG_PATH`.
61
-
62
- **IMPORTANT:** The `*_expected.log` baselines are ground truth generated from unmodified WA.exe. They must NEVER be deleted or regenerated. If a test fails, the Rust code is wrong.
63
-
64
- Key paths:
65
- - Replay files + expected logs: `testdata/replays/*.WAgame` + `*_expected.log`
66
- - Per-run output: `testdata/runs/<timestamp>/` (gitignored)
67
- - Test runner: `crates/openwa-test-runner/`
68
- - Convenience script: `run-tests.ps1`
69
-
70
- ### Headful replay testing (interactive)
71
 
72
- Use the `/replay-test` skill for interactive testing with graphics and sound:
73
 
74
- ```bash
75
- powershell -ExecutionPolicy Bypass -File replay-test.ps1
76
- powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless testdata/replays/longbow.WAgame
77
- ```
78
-
79
- Headful mode enables fast-forward (50x via DDGame+0x98B0). Use for debugging specific replays or testing visual/audio hooks.
80
-
81
- ### Environment variables
82
-
83
- - `OPENWA_HEADLESS=1` β€” Headless mode: hooks MessageBoxA to auto-dismiss, launcher uses SW_HIDE, file isolation hook active, semaphore renamed per-PID
84
- - `OPENWA_REPLAY_TEST=1` β€” Fast-forward mode for headful testing (50x speed, 120s safety timeout)
85
- - `OPENWA_LOG_PATH=<path>` β€” Override OpenWA.log location (used by test runner for per-instance isolation)
86
- - `OPENWA_ERRORLOG_PATH=<path>` β€” Redirect ERRORLOG.TXT to specified path (used by test runner for crash capture)
87
- - `OPENWA_TRACE_DESYNC=1` β€” Enable per-frame checksum logging (hooks GameFrameChecksumProcessor)
88
- - `OPENWA_TRACE_BASELINE=1` β€” Baseline mode: skip all gameplay hooks, keep only infrastructure
89
- - `OPENWA_TRACE_HASH_PATH=<path>` β€” Override frame hash log location (default: frame_hashes.log)
90
-
91
- ### Trace-desync (automated desync detection)
92
-
93
- The `trace-desync` subcommand hooks WA's own `GameFrameChecksumProcessor` (0x5329C0) to capture per-frame checksums, runs the game twice (baseline with minimal hooks vs all hooks), and diffs the results:
94
 
95
- ```bash
96
- .\trace-desync.ps1 testdata/replays/longbow.WAgame
97
 
98
- # Or directly:
99
- openwa-test trace-desync testdata/replays/longbow.WAgame [--no-build] [--wa-path PATH]
100
- ```
101
-
102
- Baseline mode (`OPENWA_TRACE_BASELINE=1`) installs only: headless, file_isolation, frame_hook, trace_desync. All gameplay hooks (replay, weapon, sound, constructor, etc.) are skipped, giving a "nearly vanilla" WA reference run.
103
-
104
- Output reports the first divergent frame or confirms all checksums match. Per-frame hash logs are saved in `testdata/runs/trace-<timestamp>/`.
105
 
106
- ### Adding new replay tests
107
-
108
- 1. Record a game in WA.exe (the replay `.WAgame` file is saved automatically)
109
- 2. Copy the replay to `testdata/replays/`
110
- 3. Run once with the headless test runner β€” it auto-generates the `*_expected.log` baseline
111
- 4. Subsequent runs compare against this baseline
112
 
113
  ## Debug CLI
114
 
115
- Use the `/debug-cli` skill to inspect live game memory, set frame breakpoints, and capture game state snapshots. The debug server runs inside the DLL; the CLI is a separate binary that connects over TCP.
116
-
117
- ```bash
118
- # Start game in debug mode:
119
- powershell -ExecutionPolicy Bypass -File start-debug.ps1
120
 
121
- # Or with headless replay + frame breakpoint:
122
- OPENWA_BREAK_FRAME=1350 OPENWA_DEBUG_SERVER=1 \
123
- powershell -File replay-test.ps1 -Headless testdata/replays/longbow.WAgame
124
- ```
125
 
126
- Key commands:
127
- - `openwa-debug read "0x7A0884->0xA0->0x488" 0x100` β€” read memory via pointer chains
128
- - `openwa-debug inspect DDGame ddgame` β€” typed struct inspection with named fields
129
- - `openwa-debug inspect CTaskWorm "ddgame->task_land"` β€” follow field-name pointer chains
130
- - `openwa-debug objects` β€” list tracked live objects (DDGame, DDGameWrapper, GameSession)
131
- - `openwa-debug suspend` / `resume` / `step N` β€” frame-level control
132
- - `openwa-debug snapshot` β€” canonicalized game state dump (for diffing)
133
- - `openwa-debug break 1350` β€” set frame breakpoint
134
 
135
- Address syntax: Ghidra VAs (auto-rebased), `abs:` prefix for absolute, `+offset` / `[offset]`, `->` for pointer chains. **Always quote chain addresses** (`"0x7A0884->0xA0->0x488"`).
136
 
137
- ### Symbolic addresses
138
-
139
- Named aliases and field names can be used anywhere an address is accepted:
140
- - `ddgame` β€” resolves to DDGame's runtime address (any tracked live object name works, case-insensitive)
141
- - `ddgame+frame_counter` β€” DDGame base + field offset (no deref)
142
- - `ddgame->task_land` β€” follow the task_land pointer (offset + deref)
143
- - `gamesession->ddgame_wrapper->display` β€” multi-step field chains
144
- - Mixed: `ddgame->0x54C` still works (hex offsets alongside names)
145
-
146
- Field names are resolved via the server's FieldRegistry, including CTask inheritance chains.
147
-
148
- Key env vars:
149
- - `OPENWA_DEBUG_SERVER=1` β€” enable TCP debug server (port 19840)
150
- - `OPENWA_BREAK_FRAME=N` β€” auto-pause at frame N
151
- - `OPENWA_USE_ORIG_CTOR=1` β€” use original WA DDGame constructor (for A/B testing)
152
- - `OPENWA_WATCH_FRAME=N` β€” arm hardware watchpoint on DDGame at frame N
153
- - `OPENWA_WATCH_WRAPPER=1` β€” watchpoint base = DDGameWrapper instead of DDGame
154
- - `OPENWA_WATCH_DISPLAY=1` β€” watchpoint base = display object (DDGameWrapper+0x4D0), armed during constructor
155
-
156
- ## Crate Architecture
157
-
158
- - **`openwa-core`** β€” Types, addresses, parsers, ASLR rebasing, typed WA function wrappers, **and game logic**. The source of truth for all reverse-engineered type layouts, known addresses, and Rust reimplementations of WA functions. Contains `registry` (structured address database + field registries), `rebase` (ASLR delta), `wa_call` (calling convention helpers), `wa/` (typed handle wrappers), and game logic modules (`game/weapon_fire.rs`, `game/weapon_release.rs`, `audio/sound_ops.rs`, `engine/team_ops.rs`).
159
- - **`openwa-derive`** β€” Proc macro crate. Provides `#[derive(FieldRegistry)]` for struct field maps and `#[vtable(...)]` for typed vtable definitions with introspection, calling wrappers, and replacement support.
160
- - **`openwa-wormkit`** β€” Unified WormKit cdylib: thin hook installation shims (trampolines, `usercall_trampoline!`, `install()`) that wire core's game logic into WA.exe via MinHook. Logs to `OpenWA.log`. Runs registry-driven startup checks automatically at load.
161
- - **`openwa-test-runner`** β€” Headless replay test runner (`openwa-test` binary). Discovers replay tests, runs them concurrently via WA.exe's `/getlog` mode, compares output logs. See "Replay Testing" section.
162
- - **`openwa-debug-cli`** β€” CLI tool for live memory inspection (`openwa-debug` binary). Connects to the debug server in the DLL.
163
- - **`openwa-debug-proto`** β€” Shared protocol types (Request/Response enums, MessagePack framing) between CLI and server.
164
 
165
  ## ASLR Rebasing
166
 
@@ -185,180 +74,25 @@ These are critical β€” wrong conventions cause stack corruption and crashes.
185
  - **Always check `RET imm16`** in disassembly to verify stack parameter count. The immediate value = bytes of params cleaned by callee (stdcall/thiscall). `RET 0x10` = 16 bytes = 4 params.
186
  - **MSVC `__usercall`**: Some functions pass implicit params in registers (e.g., FrontendChangeScreen uses ESI for dialog pointer). These need `#[unsafe(naked)]` trampolines.
187
 
188
- ## Hooking Patterns
189
-
190
- Hooks use the `minhook` crate. Two patterns:
191
-
192
- 1. **Passthrough hook** (logging only): Call original via trampoline, log result. See `replacements/scheme.rs`.
193
- 2. **Full replacement**: Reimplement the function in Rust, call WA functions via `wa_call` helpers. See `replacements/frontend.rs`.
194
-
195
- For `__usercall` functions, use a naked trampoline to capture register params before calling the Rust impl. **ECX preservation**: The standard `reg = ecx` trampoline variants do NOT preserve ECX across the cdecl impl call. MSVC-generated callers often loop calling thiscall functions without re-setting ECX between iterations (relying on the original function preserving it). Use the `preserve_ecx` variant for thiscall hooks where callers may rely on ECX being preserved: `usercall_trampoline!(fn name; impl_fn = path; reg = ecx; stack_params = N; ret_bytes = "0xN"; preserve_ecx)`.
196
-
197
- 3. **Vtable method replacement**: Use `vtable_replace!` to patch vtable slots at runtime. Write the replacement as `unsafe extern "thiscall" fn`. For base-class call-through, either save the original via `[ORIG_STATIC]` syntax, or call `broadcast_message()` for CTask::HandleMessage. See `replacements/task/cloud.rs`.
198
- 4. **Trap hook** (`install_trap!`): For functions whose only caller is now ported Rust. Panics if called unexpectedly. Used for FireWeapon (0x51EE60) after WeaponRelease was ported.
199
-
200
- ### Bridge function patterns
201
-
202
- When calling unported WA functions from Rust, use naked asm bridges. **Always pass the runtime target address as a cdecl parameter** (e.g., `rb(va::FUNC_ADDR)` as the last arg). Do NOT use `sym` + `jmp [ptr]` indirection through static pointers β€” this causes crashes due to relocation/PIC issues on x86 DLLs.
203
-
204
- When a register param (e.g., EAX) must be set for the target function, load the call target into a **different** register (EBX, etc.) before the `call`. Do not use EAX for the target if EAX is also a parameter.
205
-
206
- ## Desync Debugging
207
-
208
- Replay desyncs (checksum mismatches) can be caused by any code difference β€” constructor side effects, hooked function behaviour, missing state, wrong calling conventions, etc. Key methodology:
209
-
210
- 0. **Start with `trace-desync`**: Run `.\trace-desync.ps1 testdata/replays/<replay>.WAgame` to automatically find the exact frame where baseline and hooked runs diverge. This replaces manual per-frame RNG logging as the first diagnostic step.
211
- 1. **WA uses a single shared RNG** (DDGame+0x45EC, `AdvanceGameRNG` at 0x53F320) for both gameplay AND visual effects. There is no separate "visual RNG." Even purely decorative things like particle sprites affect the game RNG and will cause desyncs in headless mode if handled differently. A secondary effect RNG exists at DDGame+0x45F0 (`advance_effect_rng()`, simpler LCG without frame_counter) β€” used by WeaponRelease visual effects. Uses `team_health_ratio[0]` (unused index-0 slot).
212
- 2. **DDGame flat memory matching is NOT sufficient.** Constructors and hooks have side effects on sub-objects (display, GfxHandler, PCLandscape). Compare all objects pointed to by DDGame AND DDGameWrapper.
213
- 3. **Use hardware watchpoints** (`debug_watchpoint.rs`) with stack traces to find what writes a specific field. DR0–DR3 + VEH handler gives "who wrote this byte?" answers without an external debugger.
214
- 4. **Per-frame RNG logging** (DDGame+0x45EC) pinpoints the exact frame where simulation diverges. Binary search on frames, not code.
215
- 5. **Always validate diff methodology** against a known-good frame first. The snapshot system's pointer canonicalization produces false positives.
216
-
217
- See `docs/re-notes/desync-investigation.md` for a detailed case study.
218
 
219
- ## Hardware Watchpoint Debugger
220
 
221
- `crates/openwa-wormkit/src/debug_watchpoint.rs` β€” self-contained x86 debug register instrumentation. Sets DR0–DR3 write watchpoints on DDGame offsets via an INT3β†’VEH trick (no external debugger needed). Logs symbolicated stack traces via `registry::format_va()` (e.g., `CONSTRUCT_DD_GAME+0x220` instead of raw hex).
222
-
223
- **Usage:** Call `prepare()` + `on_ddgame_alloc(ptr)` around the constructor, `teardown()` after. For the original WA constructor, use `prepare_with_malloc_hook()` which intercepts `wa_malloc(0x98D8)` to arm watchpoints from inside the constructor. Configure offsets in `WATCH_OFFSETS` (max 4 per run, hardware limit).
224
-
225
- Currently dormant β€” no hooks wired up. Activate by adding calls in `game_session.rs`.
226
-
227
- ## Key Files
228
-
229
- - `crates/openwa-core/src/address.rs` β€” Known WA.exe addresses (segment boundaries + re-exports from home modules)
230
- - `crates/openwa-core/src/registry.rs` β€” Structured address registry, field registries (`ValueKind`), live object tracker, query API
231
- - `crates/openwa-core/src/field_format.rs` β€” `FieldFormatter` trait, `format_field()`, default formatters for all `ValueKind` variants
232
- - `crates/openwa-core/src/macros.rs` β€” `define_addresses!`, `vcall!`, and `vtable_replace!` macros
233
- - `crates/openwa-core/src/mem.rs` β€” Pointer classification and `identify_pointer()` for debug tools
234
- - `crates/openwa-core/src/wa_call.rs` β€” Helpers for calling WA functions (thiscall, stdcall wrappers)
235
- - `crates/openwa-core/src/rebase.rs` β€” ASLR delta computation
236
- - `crates/openwa-core/src/wa/` β€” Typed WA function wrappers (MFC, frontend, registry, DDGame)
237
- - `crates/openwa-core/src/task/base.rs` β€” CTask<V>, CTaskVtable (7 slots), Task trait, SharedDataTable, broadcast_message
238
- - `crates/openwa-core/src/task/worm.rs` β€” CTaskWorm, CTaskWormVTable (20 slots), WormState enum (all gaps filled)
239
- - `crates/openwa-core/src/game/weapon.rs` β€” Weapon enum, WeaponEntry, FireType/FireMethod/SpecialFireSubtype enums, WeaponFireParams
240
- - `crates/openwa-core/src/audio/sound.rs` β€” SoundId packed type (low 16 = slot, bit 16 = loop, bit 17 = raw volume) + KnownSoundId enum (1-126 SFX)
241
- - `crates/openwa-core/src/audio/sound_ops.rs` β€” Sound queue, PlaySoundLocal/Global, worm sound (stop/play), 3D distance attenuation, streaming dispatch
242
- - `crates/openwa-core/src/engine/team_arena.rs` β€” TeamArenaState, WormEntry, TeamHeader, TeamArenaRef
243
- - `crates/openwa-core/src/engine/team_ops.rs` β€” Team/worm state accessors (alliance counting, health, state checks)
244
- - `crates/openwa-core/src/engine/ddgame_constructor.rs` β€” DDGame constructor (create_ddgame, init_graphics_and_resources)
245
- - `crates/openwa-core/src/game/weapon_fire.rs` β€” FireWeapon dispatch, ammo management, 20+ special weapon handlers, projectile creation
246
- - `crates/openwa-core/src/game/weapon_release.rs` β€” WeaponRelease (0x51C3D0), SpawnEffect (0x547C30) β€” fully ported
247
- - `crates/openwa-wormkit/src/replacements/sound.rs` β€” Hook trampolines for sound functions (thin shim over sound_ops)
248
- - `crates/openwa-wormkit/src/replacements/frame_hook.rs` β€” TurnManager_ProcessFrame hook, debug_sync, watchpoint arming (always installed)
249
- - `crates/openwa-wormkit/src/replacements/replay_test.rs` β€” Fast-forward + gameplay milestones (headful replay testing only)
250
- - `crates/openwa-wormkit/src/replacements/trace_desync.rs` β€” Per-frame checksum logging for desync bisection
251
- - `crates/openwa-wormkit/src/replacements/` β€” Function replacements (one file per subsystem)
252
- - `crates/openwa-wormkit/src/replacements/task/` β€” Vtable method replacements (cloud, filter, ...)
253
- - `docs/re-notes/` β€” Reverse engineering documentation (task hierarchy, memory map, frontend screens)
254
- - `docs/plans/` β€” Design docs and implementation plans
255
 
256
  ## Ghidra MCP
257
 
258
  A Ghidra MCP bridge is configured in `.mcp.json`. When using Ghidra tools:
 
259
  - **Prefer batch tools** (`batch_create_labels`, `batch_rename_function_components`) β€” single-item tools have address parsing bugs.
260
  - WA.exe is loaded at image base 0x400000 in Ghidra.
261
  - When you encounter unnamed functions, globals or structs, name them in Ghidra if you know their purpose. Even a guess is helpful for future reference, but add `_Maybe` suffix if uncertain.
262
  - Remove `_Maybe` suffix when you confirm the purpose.
263
  - When you learn more about a function or address, update both the Ghidra database (rename function / label and update signature) and the corresponding Rust code.
264
 
265
- ## Third-Party RE Sources
266
-
267
- - `C:\koodia\worms-re\thirdparty\wkJellyWorm\` β€” Extensive RE data: task hierarchy, vtables, enums, weapon structs
268
- - `C:\koodia\worms-re\thirdparty\WormKit\` β€” Modding framework, game state structures
269
 
270
- ## Address Registry & Pointer Identification
271
-
272
- The `registry` module in `openwa-core` provides a structured, queryable database of known addresses. Three systems work together:
273
-
274
- ### `define_addresses!` macro
275
-
276
- Defines known WA.exe addresses with metadata (kind, calling convention, class name). Generates both `pub const` values and `inventory`-collected `AddrEntry` items for runtime queries. Supports class blocks and standalone entries:
277
-
278
- ```rust
279
- crate::define_addresses! {
280
- class "CTaskWorm" {
281
- vtable CTASK_WORM_VTABLE = 0x0066_44C8;
282
- ctor CTASK_WORM_CONSTRUCTOR = 0x0050_BFB0;
283
- }
284
- fn/Fastcall ADVANCE_GAME_RNG = 0x0053_F320;
285
- global G_GAME_SESSION = 0x007A_0884;
286
- }
287
- ```
288
-
289
- **Distributed definitions**: Each module defines its own addresses via `define_addresses!`. `address.rs` re-exports them into `mod va` for backward compatibility (`va::CTASK_WORM_VTABLE` still works). When adding new addresses, place the `define_addresses!` block in the home module, then add a `pub use` re-export in `address.rs`.
290
-
291
- ### `#[derive(FieldRegistry)]`
292
-
293
- Auto-generates a field map for `#[repr(C)]` structs using `offset_of!()`. Fields prefixed `_unknown`/`_pad` are skipped. Applied to all key structs (DDGame, CTask, CTaskWorm, etc.). Enables runtime offset β†’ field name lookups.
294
-
295
- Each field gets a `ValueKind` for typed formatting, auto-inferred from the Rust type:
296
- - `u8/u16/u32/i8/i16/i32` β†’ scalar variants, `bool` β†’ `Bool`, `Fixed` β†’ `Fixed`
297
- - `*mut T` / `*const T` β†’ `Pointer`, `ClassType` β†’ `Enum`
298
- - Arrays and unknown types β†’ `Raw`
299
- - Override with `#[field(kind = "CString")]` for null-terminated string fields, etc.
300
-
301
- ```rust
302
- #[derive(FieldRegistry)]
303
- #[repr(C)]
304
- pub struct CTask { ... }
305
- // Generates: CTask::field_registry() -> &'static StructFields
306
- // Also registers in global inventory for struct_fields_for("CTask")
307
-
308
- // String fields use #[field(kind = "...")] override:
309
- #[field(kind = "CString")]
310
- pub worm_name: [u8; 0x11], // Displays as "Ainsley" instead of raw hex
311
- ```
312
-
313
- ### Field formatting (`field_format.rs`)
314
-
315
- `format_field(&mut dyn fmt::Write, data, field, ctx)` writes human-readable values based on `ValueKind`: scalars as decimal, Fixed as float (e.g., `388.43`), pointers resolved via registry (e.g., `DDDisplay*`), CString as quoted strings. Zero allocations β€” writes to any `fmt::Write` target.
316
-
317
- Custom formatters can be registered via `inventory::submit!(Box::new(MyFormatter) as Box<dyn FieldFormatter>)` from any crate. The `FieldFormatter` trait has `handles() -> &[ValueKind]` and `format_field(&mut dyn Write, ...)`.
318
-
319
- ### Query API (`registry::*`)
320
-
321
- - `lookup_va(ghidra_va)` β€” find address entry by VA (exact or nearest-below)
322
- - `vtable_class_name(ghidra_vtable)` β€” vtable address β†’ class name
323
- - `format_va(ghidra_va)` β€” human-readable name string
324
- - `struct_fields_for("DDGame")` / `struct_fields_for_vtable(va)` β€” get field map
325
- - `field_at_inherited("CTaskWorm", offset)` β€” inheritance-aware field lookup (walks CTaskWorm β†’ CGameTask β†’ CTask)
326
- - `identify_pointer(value, delta)` β†’ `PointerIdentity` β€” full pointer identification (static addresses, live objects, vtable-based object detection)
327
- - `register_live_object()` / `identify_live_pointer()` β€” track heap objects for field-level pointer resolution
328
- - `vtable_info_for("PaletteVtable")` β€” vtable slot metadata (name, index, doc)
329
-
330
- ### `#[vtable(...)]` attribute macro
331
-
332
- Defines typed vtable structs from sparse slot definitions. The macro generates the full `#[repr(C)]` struct with `usize` gap-fillers, registry metadata, a companion `bind_!` macro, and optional address constants.
333
-
334
- ```rust
335
- #[openwa_core::vtable(size = 38, va = 0x0066_A218, class = "DDDisplay")]
336
- pub struct DDDisplayVtable {
337
- /// set layer color
338
- #[slot(4)]
339
- pub set_layer_color: fn(this: *mut DDDisplay, layer: i32, color: i32),
340
- /// set active layer, returns layer context ptr
341
- #[slot(5)]
342
- pub set_active_layer: fn(this: *mut DDDisplay, layer: i32) -> *mut u8,
343
- }
344
-
345
- // Generate calling wrappers on the class struct
346
- bind_DDDisplayVtable!(DDDisplay, vtable);
347
- ```
348
-
349
- Key features:
350
- - **`#[slot(N)]`** for sparse vtables β€” gaps auto-filled with `usize`. Optional when all slots are declared sequentially.
351
- - **`fn(...)` shorthand** β€” auto-normalized to `unsafe extern "thiscall" fn(...)`.
352
- - **Named parameters** β€” `fn(this: *mut T, mode: u32)` flows through to generated wrappers as `fn set_mode(&mut self, mode: u32)`. The `this` param becomes `&mut self` (or `&self` for `*const`).
353
- - **`bind_XxxVtable!`** β€” companion macro generates method wrappers on the class struct.
354
- - **`vtable_replace!`** β€” type-safe vtable slot patching for `install()` functions. Accepts method names (resolved via `offset_of!`) or slot indices:
355
-
356
- ```rust
357
- vtable_replace!(DSSoundVtable, va::DS_SOUND_VTABLE, {
358
- play_sound [originals::PLAY] => my_play_sound, // save original + replace
359
- load_wav => my_load_wav, // pure replace
360
- })?;
361
- ```
362
 
363
  ## Design Conventions
364
 
@@ -368,9 +102,7 @@ vtable_replace!(DSSoundVtable, va::DS_SOUND_VTABLE, {
368
  - **Generic CTask<V> for typed vtables**: `CTask<V: Vtable = *const c_void>` and `CGameTask<V: Vtable = *const c_void>` take a vtable pointer type parameter. Subclasses specify their typed vtable: `CTaskTeam { base: CTask<*const CTaskTeamVTable> }`. The `Vtable` marker trait is auto-implemented by the `#[vtable]` macro. `FieldRegistry` derive supports generics by substituting type params with their defaults for `offset_of`/`size_of`.
369
  - **`Task` trait**: Provides `task()`, `ddgame()`, `as_task_ptr()`, `as_task_ptr_mut()`, and `broadcast_message()` on all CTask subclasses. Eliminates `.base.base` chains. Implemented for all task types in `task/mod.rs`.
370
  - **`broadcast_message()` / `broadcast_message_raw()`**: Pure Rust port of CTask::HandleMessage (0x562F30). Iterates the sparse children array and calls each child's vtable[2]. Uses `read_volatile` for `children_watermark` and `children_data` β€” **required** because LLVM caches these reads across virtual dispatch calls even through `*mut`. Prefer `CTask::broadcast_message_raw(ptr, ...)` over `(*ptr).broadcast_message(...)` β€” see noalias rule above.
371
- - **Typed vtable structs via `#[vtable(...)]`**: Use the attribute macro to define vtable structs with `fn(this: *mut T, ...)` shorthand and `#[slot(N)]` for sparse layouts. The macro handles `unsafe extern "thiscall"`, gap-filling, registry metadata, generates `bind_!` calling wrappers, and implements the `Vtable` marker trait. See the `#[vtable(...)]` section above.
372
  - **CTask base vtable**: 7 slots (not 8). ProcessFrame is slot 6. Slots 7+ are class-specific extensions. CGameTask adds no virtuals.
373
- - **`bind_XxxVtable!`**: Generated by `#[vtable(...)]`, creates both `&mut self` method wrappers AND `_raw` associated functions (raw pointers) on the class struct. Supports dotted field paths for inherited vtables: `bind_CTaskTeamVTable!(CTaskTeam, base.vtable)`.
374
  - **Noalias rule β€” ALWAYS use `_raw` methods on WA objects**: `bind_!` methods with `&mut self` give LLVM noalias guarantees that WA bridge calls violate, causing silent miscompilation. **Always use `Type::method_raw(ptr, args)` instead of `(*ptr).method(args)`**. Similarly use `CTask::ddgame_raw(ptr)` instead of `(*ptr).ddgame()`, and `CTask::broadcast_message_raw(ptr, ...)` instead of `(*ptr).broadcast_message(...)`. For `as_task_ptr`, just cast: `worm as *mut CTask`.
375
  - **`vcall!` macro**: Still available for raw-pointer vtable dispatch without bind wrappers. Expands to `((*(*obj).vtable).method)(obj, args...)`.
376
 
@@ -378,11 +110,10 @@ vtable_replace!(DSSoundVtable, va::DS_SOUND_VTABLE, {
378
 
379
  Add type safety incrementally where it's beneficial β€” this is a reverse engineering project, not a greenfield codebase. Perfect types aren't always possible, but small improvements compound.
380
 
381
- - **Wrapper structs over raw values**: Create `#[repr(C)]` structs for known memory layouts. Access fields by name, not pointer arithmetic. Even partially-known structs (with `_unknown_XX` padding) are better than raw offsets.
382
- - **Handle newtypes for opaque pointers**: When a pointer's target layout is unknown, wrap it in a newtype (e.g., `WavPlayerHandle(u32)`, `CWndHandle(u32)`) with methods that encapsulate the unsafe calls. This keeps inline asm and raw pointer work out of hook logic.
383
- - **Typed pointers over integers**: Prefer `*mut DDGame` over `u32` for pointer parameters. Use `*const c_char` for C string pointers, not `*const u8`.
384
- - **Constants over magic numbers**: Name addresses (`va::FESFX_WAV_PLAYER`), sizes (`MAX_PATH`), and offsets. Magic numbers in code should be rare and commented. Use typed enums (`Weapon`, `KnownSoundId`, `FireType`, `SpecialFireSubtype`) and `Fixed` for volume/pitch instead of raw `u32`/`i32`.
385
- - **SoundId pattern**: `SoundId(u32)` is a transparent newtype for any sound ID (WA uses IDs > 126 for speech). `KnownSoundId` is the typed enum for known SFX (1-126). Sound functions accept `impl Into<SoundId>` so both work. Never reject unknown IDs in hooks β€” speech/voice lines use high IDs.
386
  - **Wrap inline asm in safe-to-call functions**: Isolate `asm!` / `naked_asm!` blocks in small dedicated functions (e.g., `get_team_config_name()`, `wav_player_stop_raw()`). Hook functions should read like normal Rust, calling into asm wrappers only when needed.
387
  - **ESI/EDI are LLVM-reserved on x86**: Cannot use `in("esi")` or `in("edi")` in `core::arch::asm!`. Use `#[unsafe(naked)]` functions with `naked_asm!` when these registers are needed.
388
  - **`heapless::CString<N>`** for stack-allocated null-terminated path buffers (auto nul terminator, `as_ptr()` returns `*const c_char`).
 
1
+ # OpenWA
 
 
2
 
3
  ## Project
4
 
5
+ OpenWA (short for "Open Worms Armageddon") is an incremental Rust reimplementation of Worms Armageddon 3.8.1 (Steam). The replacement strategy is the same as was used in OpenRCT2: a custom launcher (`openwa-launcher`) injects a DLL (`openwa-wormkit`) into a suspended game process, which replaces game functions with Rust implementations (from `openwa-core`).
 
 
6
 
7
+ The original WA.exe is a 32-bit x86 Windows PE binary built with MSVC 2005 + MFC. All Rust code targets `i686-pc-windows-msvc`.
8
 
9
+ ## Crate Architecture
 
 
10
 
11
+ - **`openwa-core`** β€” Types, addresses, parsers, ASLR rebasing, typed WA function wrappers, **and game logic**. The source of truth for all reverse-engineered type layouts, known addresses, and Rust reimplementations of WA functions. Contains `registry` (structured address database + field registries), `rebase` (ASLR delta), `wa_call` (calling convention helpers), `wa/` (typed handle wrappers), and game logic modules (`game/weapon_fire.rs`, `game/weapon_release.rs`, `audio/sound_ops.rs`, `engine/team_ops.rs`).
12
+ - **`openwa-derive`** β€” Proc macro crate. Provides `#[derive(FieldRegistry)]` for struct field maps and `#[vtable(...)]` for typed vtable definitions with introspection, calling wrappers, and replacement support.
13
+ - **`openwa-wormkit`** β€” Unified WormKit cdylib: thin hook installation shims (trampolines, `usercall_trampoline!`, `install()`) that wire core's game logic into WA.exe via MinHook. Logs to `OpenWA.log`. Runs registry-driven startup checks automatically at load.
14
+ - **`openwa-test-runner`** β€” Headless replay test runner (`openwa-test` binary). Discovers replay tests, runs them concurrently via WA.exe's `/getlog` mode, compares output logs. See "Replay Testing" section.
15
+ - **`openwa-launcher`** β€” Launches WA.exe with the DLL injected via CREATE_SUSPENDED + remote thread.
16
+ - **`openwa-debugui`** β€” In-process egui debug window (entity census, struct inspector, cheats). Enabled via `OPENWA_DEBUG_UI=1` + `debug-ui` cargo feature.
17
+ - **`openwa-debug-cli`** β€” CLI tool for live memory inspection (`openwa-debug` binary). Connects to the debug server in the DLL.
18
+ - **`openwa-debug-proto`** β€” Shared protocol types (Request/Response enums, MessagePack framing) between CLI and server.
19
 
20
+ ## Build & Test
 
21
 
22
+ Build: `cargo build --release` (default target is `i686-pc-windows-msvc` via `.cargo/config.toml`).
 
 
23
 
24
+ Unit tests: `cargo test`. These are standard Rust tests covering parsers and type logic.
25
 
26
+ **Replay tests are the primary verification method** β€” see below.
27
 
28
  ## Replay Testing
29
 
30
+ WA.exe can deterministically replay recorded games (`.WAgame` files). Each replay test runs the game with the injected DLL and checks that the output matches a baseline log (`*_expected.log`) captured from unmodified WA.exe.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
31
 
32
+ **Headless** (`.\run-tests.ps1`): Pure CPU simulation, no rendering. Fast, runs in parallel (default 4 concurrent). Validates game logic β€” a log mismatch means the Rust code caused a desync. Spurious flakes from race conditions can occur; retry with `-j 1` to confirm.
33
 
34
+ **Headful** (`/replay-test` skill): Runs with graphics and sound. Requires user interaction. Needed to validate visual/audio hooks β€” code can pass headless but crash headful (or vice versa) since rendering and sound paths are only exercised headfully.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
35
 
36
+ **Use replay testing to validate assumptions and test theories.** Implement a hypothesis, run tests, iterate. You can add temporary log statements and see their results by running replay tests.
 
37
 
38
+ **IMPORTANT:** The `*_expected.log` baselines are ground truth from unmodified WA.exe. They must NEVER be deleted or regenerated. If a test fails, the Rust code is wrong.
 
 
 
 
 
 
39
 
40
+ See `crates/openwa-test-runner/CLAUDE.md` for test isolation, crash detection, adding new tests, and env vars. Use `/desync-debug` skill after a test failure to diagnose.
 
 
 
 
 
41
 
42
  ## Debug CLI
43
 
44
+ Use the `/debug-cli` skill for live memory inspection, struct inspection, frame-level control, and pointer chain traversal.
 
 
 
 
45
 
46
+ ## Hardware Watchpoints
 
 
 
47
 
48
+ `crates/openwa-wormkit/src/debug_watchpoint.rs` β€” x86 debug register instrumentation (DR0-DR3) for answering "who writes this memory?" without an external debugger. Uses INT3β†’VEH trick, logs symbolicated stack traces via `registry::format_va()`. Max 4 watchpoints per run (hardware limit).
 
 
 
 
 
 
 
49
 
50
+ **API:** `arm_watchpoint(base_ptr, offset, size)` sets a write watchpoint. `prepare()` initializes the VEH handler, `teardown()` removes it. Can be armed at any point during execution β€” on object allocation, at a specific frame via env var, or manually from debug server commands.
51
 
52
+ **Env vars:** `OPENWA_WATCH_FRAME=N` (arm at frame N), `OPENWA_WATCH_WRAPPER=1` (base=DDGameWrapper), `OPENWA_WATCH_DISPLAY=1` (base=display object).
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
53
 
54
  ## ASLR Rebasing
55
 
 
74
  - **Always check `RET imm16`** in disassembly to verify stack parameter count. The immediate value = bytes of params cleaned by callee (stdcall/thiscall). `RET 0x10` = 16 bytes = 4 params.
75
  - **MSVC `__usercall`**: Some functions pass implicit params in registers (e.g., FrontendChangeScreen uses ESI for dialog pointer). These need `#[unsafe(naked)]` trampolines.
76
 
77
+ ## Hooking & Desync Debugging
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
78
 
79
+ See `crates/openwa-wormkit/CLAUDE.md` for hooking patterns (passthrough, full replacement, vtable, trap), bridge function patterns, `usercall_trampoline!` macro, and hook installation details.
80
 
81
+ Use the `/desync-debug` skill for desync diagnosis (trace-desync, per-frame analysis). Only after a headless test has already detected a failure.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
82
 
83
  ## Ghidra MCP
84
 
85
  A Ghidra MCP bridge is configured in `.mcp.json`. When using Ghidra tools:
86
+
87
  - **Prefer batch tools** (`batch_create_labels`, `batch_rename_function_components`) β€” single-item tools have address parsing bugs.
88
  - WA.exe is loaded at image base 0x400000 in Ghidra.
89
  - When you encounter unnamed functions, globals or structs, name them in Ghidra if you know their purpose. Even a guess is helpful for future reference, but add `_Maybe` suffix if uncertain.
90
  - Remove `_Maybe` suffix when you confirm the purpose.
91
  - When you learn more about a function or address, update both the Ghidra database (rename function / label and update signature) and the corresponding Rust code.
92
 
93
+ ## Address Registry, FieldRegistry & Vtable Macros
 
 
 
94
 
95
+ See `crates/openwa-core/CLAUDE.md` for the full reference on `define_addresses!`, `#[derive(FieldRegistry)]`, `#[vtable(...)]`, `vtable_replace!`, and the registry query API.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
96
 
97
  ## Design Conventions
98
 
 
102
  - **Generic CTask<V> for typed vtables**: `CTask<V: Vtable = *const c_void>` and `CGameTask<V: Vtable = *const c_void>` take a vtable pointer type parameter. Subclasses specify their typed vtable: `CTaskTeam { base: CTask<*const CTaskTeamVTable> }`. The `Vtable` marker trait is auto-implemented by the `#[vtable]` macro. `FieldRegistry` derive supports generics by substituting type params with their defaults for `offset_of`/`size_of`.
103
  - **`Task` trait**: Provides `task()`, `ddgame()`, `as_task_ptr()`, `as_task_ptr_mut()`, and `broadcast_message()` on all CTask subclasses. Eliminates `.base.base` chains. Implemented for all task types in `task/mod.rs`.
104
  - **`broadcast_message()` / `broadcast_message_raw()`**: Pure Rust port of CTask::HandleMessage (0x562F30). Iterates the sparse children array and calls each child's vtable[2]. Uses `read_volatile` for `children_watermark` and `children_data` β€” **required** because LLVM caches these reads across virtual dispatch calls even through `*mut`. Prefer `CTask::broadcast_message_raw(ptr, ...)` over `(*ptr).broadcast_message(...)` β€” see noalias rule above.
 
105
  - **CTask base vtable**: 7 slots (not 8). ProcessFrame is slot 6. Slots 7+ are class-specific extensions. CGameTask adds no virtuals.
 
106
  - **Noalias rule β€” ALWAYS use `_raw` methods on WA objects**: `bind_!` methods with `&mut self` give LLVM noalias guarantees that WA bridge calls violate, causing silent miscompilation. **Always use `Type::method_raw(ptr, args)` instead of `(*ptr).method(args)`**. Similarly use `CTask::ddgame_raw(ptr)` instead of `(*ptr).ddgame()`, and `CTask::broadcast_message_raw(ptr, ...)` instead of `(*ptr).broadcast_message(...)`. For `as_task_ptr`, just cast: `worm as *mut CTask`.
107
  - **`vcall!` macro**: Still available for raw-pointer vtable dispatch without bind wrappers. Expands to `((*(*obj).vtable).method)(obj, args...)`.
108
 
 
110
 
111
  Add type safety incrementally where it's beneficial β€” this is a reverse engineering project, not a greenfield codebase. Perfect types aren't always possible, but small improvements compound.
112
 
113
+ - **Structs over raw memory**: Create `#[repr(C)]` structs for known memory layouts. Access fields by name, not pointer arithmetic. Even partially-known structs (with `_unknown_XX` padding) are better than raw offsets.
114
+ - **Constant improvements**: Adding a new struct or a missing field (by splitting an existing `_unknown` field), renaming a field from `_unknown` to a descriptive name, replacing an integer or void pointer with a better type, or labeling a function in Ghidra are ALWAYS welcome improvements. Small improvements to documentation and type safety should NEVER be considered out of scope. Improving the codebase is more important than keeping change sets small.
115
+ - **Typed pointers over integers**: Function signatures (ported functions, FFI wrappers, hook impls) MUST use pointer types for pointer arguments, never `u32`. If the pointee struct exists in Rust, use it (`*mut DDGame`, `*mut PaletteContext`). If it doesn't exist yet, strongly consider adding an incomplete `#[repr(C)]` struct with `_unknown_XX` padding β€” even a stub enables typed field access later. Use `*mut u8` / `*const u8` ONLY when the pointee is truly untyped (generic memory like `memcpy`, raw byte buffers). Use `*const c_char` for C string pointers. Note: on our target (`i686-pc-windows-msvc`), `u32 == usize == *const T == *mut T` are all 4 bytes, so casts between them are always safe and zero-cost.
116
+ - **Constants over magic numbers**: Name addresses (`va::FESFX_WAV_PLAYER`), sizes (`MAX_PATH`), and offsets. Magic numbers in code should be rare and commented. Use typed enums (`Weapon`, `KnownSoundId`, `FireType`, `SpecialFireSubtype`) and newtypes (`Fixed`, `SoundId`) instead of raw `u32`/`i32`.
 
117
  - **Wrap inline asm in safe-to-call functions**: Isolate `asm!` / `naked_asm!` blocks in small dedicated functions (e.g., `get_team_config_name()`, `wav_player_stop_raw()`). Hook functions should read like normal Rust, calling into asm wrappers only when needed.
118
  - **ESI/EDI are LLVM-reserved on x86**: Cannot use `in("esi")` or `in("edi")` in `core::arch::asm!`. Use `#[unsafe(naked)]` functions with `naked_asm!` when these registers are needed.
119
  - **`heapless::CString<N>`** for stack-allocated null-terminated path buffers (auto nul terminator, `as_ptr()` returns `*const c_char`).
crates/openwa-core/CLAUDE.md ADDED
@@ -0,0 +1,94 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # openwa-core
2
+
3
+ Types, addresses, parsers, ASLR rebasing, typed WA function wrappers, and game logic. The source of truth for all reverse-engineered type layouts, known addresses, and Rust reimplementations of WA functions.
4
+
5
+ See root `CLAUDE.md` for project-wide rules: calling conventions, design conventions, FFI style.
6
+
7
+ ## Address Registry & Pointer Identification
8
+
9
+ The `registry` module provides a structured, queryable database of known addresses. Three systems work together:
10
+
11
+ ### `define_addresses!` macro
12
+
13
+ Defines known WA.exe addresses with metadata (kind, calling convention, class name). Generates both `pub const` values and `inventory`-collected `AddrEntry` items for runtime queries. Supports class blocks and standalone entries:
14
+
15
+ ```rust
16
+ crate::define_addresses! {
17
+ class "CTaskWorm" {
18
+ vtable CTASK_WORM_VTABLE = 0x0066_44C8;
19
+ ctor CTASK_WORM_CONSTRUCTOR = 0x0050_BFB0;
20
+ }
21
+ fn/Fastcall ADVANCE_GAME_RNG = 0x0053_F320;
22
+ global G_GAME_SESSION = 0x007A_0884;
23
+ }
24
+ ```
25
+
26
+ **Distributed definitions**: Each module defines its own addresses via `define_addresses!`. `address.rs` re-exports them into `mod va` for backward compatibility (`va::CTASK_WORM_VTABLE` still works). When adding new addresses, place the `define_addresses!` block in the home module, then add a `pub use` re-export in `address.rs`.
27
+
28
+ ### `#[derive(FieldRegistry)]`
29
+
30
+ Auto-generates a field map for `#[repr(C)]` structs using `offset_of!()`. Fields prefixed `_unknown`/`_pad` are skipped. Applied to all key structs (DDGame, CTask, CTaskWorm, etc.). Enables runtime offset -> field name lookups.
31
+
32
+ Each field gets a `ValueKind` for typed formatting, auto-inferred from the Rust type:
33
+
34
+ - `u8/u16/u32/i8/i16/i32` -> scalar variants, `bool` -> `Bool`, `Fixed` -> `Fixed`
35
+ - `*mut T` / `*const T` -> `Pointer`, `ClassType` -> `Enum`
36
+ - Arrays and unknown types -> `Raw`
37
+ - Override with `#[field(kind = "CString")]` for null-terminated string fields, etc.
38
+
39
+ ```rust
40
+ #[derive(FieldRegistry)]
41
+ #[repr(C)]
42
+ pub struct CTask { ... }
43
+ // Generates: CTask::field_registry() -> &'static StructFields
44
+ // Also registers in global inventory for struct_fields_for("CTask")
45
+
46
+ // String fields use #[field(kind = "...")] override:
47
+ #[field(kind = "CString")]
48
+ pub worm_name: [u8; 0x11], // Displays as "Ainsley" instead of raw hex
49
+ ```
50
+
51
+ ### Query API (`registry::*`)
52
+
53
+ - `lookup_va(ghidra_va)` -- find address entry by VA (exact or nearest-below)
54
+ - `vtable_class_name(ghidra_vtable)` -- vtable address -> class name
55
+ - `format_va(ghidra_va)` -- human-readable name string
56
+ - `struct_fields_for("DDGame")` / `struct_fields_for_vtable(va)` -- get field map
57
+ - `field_at_inherited("CTaskWorm", offset)` -- inheritance-aware field lookup (walks CTaskWorm -> CGameTask -> CTask)
58
+ - `identify_pointer(value, delta)` -> `PointerIdentity` -- full pointer identification (static addresses, live objects, vtable-based object detection)
59
+ - `register_live_object()` / `identify_live_pointer()` -- track heap objects for field-level pointer resolution
60
+ - `vtable_info_for("PaletteVtable")` -- vtable slot metadata (name, index, doc)
61
+
62
+ ### `#[vtable(...)]` attribute macro
63
+
64
+ Defines typed vtable structs from sparse slot definitions. The macro generates the full `#[repr(C)]` struct with `usize` gap-fillers, registry metadata, a companion `bind_!` macro, and optional address constants.
65
+
66
+ ```rust
67
+ #[openwa_core::vtable(size = 38, va = 0x0066_A218, class = "DDDisplay")]
68
+ pub struct DDDisplayVtable {
69
+ /// set layer color
70
+ #[slot(4)]
71
+ pub set_layer_color: fn(this: *mut DDDisplay, layer: i32, color: i32),
72
+ /// set active layer, returns layer context ptr
73
+ #[slot(5)]
74
+ pub set_active_layer: fn(this: *mut DDDisplay, layer: i32) -> *mut u8,
75
+ }
76
+
77
+ // Generate calling wrappers on the class struct
78
+ bind_DDDisplayVtable!(DDDisplay, vtable);
79
+ ```
80
+
81
+ Key features:
82
+
83
+ - **`#[slot(N)]`** for sparse vtables -- gaps auto-filled with `usize`. Optional when all slots are declared sequentially.
84
+ - **`fn(...)` shorthand** -- auto-normalized to `unsafe extern "thiscall" fn(...)`.
85
+ - **Named parameters** -- `fn(this: *mut T, mode: u32)` flows through to generated wrappers as `fn set_mode(&mut self, mode: u32)`. The `this` param becomes `&mut self` (or `&self` for `*const`).
86
+ - **`bind_XxxVtable!`** -- companion macro generates method wrappers on the class struct.
87
+ - **`vtable_replace!`** -- type-safe vtable slot patching for `install()` functions. Accepts method names (resolved via `offset_of!`) or slot indices:
88
+
89
+ ```rust
90
+ vtable_replace!(DSSoundVtable, va::DS_SOUND_VTABLE, {
91
+ play_sound [originals::PLAY] => my_play_sound, // save original + replace
92
+ load_wav => my_load_wav, // pure replace
93
+ })?;
94
+ ```
crates/openwa-test-runner/CLAUDE.md ADDED
@@ -0,0 +1,38 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # openwa-test-runner
2
+
3
+ Headless replay test runner (`openwa-test` binary). Discovers replay tests in `testdata/replays/`, runs them concurrently via WA.exe's `/getlog` mode, and compares output logs byte-for-byte against expected baselines.
4
+
5
+ ## Test Isolation
6
+
7
+ All isolation mechanisms are active in headless mode only:
8
+
9
+ - Per-PID temp directory: `.openwa_tmp/{pid}/` for writable files (writetest.txt, mono.tmp, land.dat, landgen.svg, etc.)
10
+ - Per-PID named event: `OpenWA_HooksReady_{pid}` for launcher-DLL synchronization
11
+ - Per-PID semaphore: `CreateSemaphoreA("Worms Armageddon")` renamed to `Worms Armageddon_{pid}`
12
+ - Per-PID log paths via `OPENWA_LOG_PATH` and `OPENWA_ERRORLOG_PATH` env vars
13
+ - Per-PID file redirection via `file_isolation.rs` (CreateFileA hook redirects playback.thm, current.thm, land.dat, landgen.svg to `.openwa_tmp/{pid}/`)
14
+ - WA.exe crash dialog suppressed via `/silentcrash` command-line flag
15
+ - Batched MinHook enables: all hooks use `queue_enable_hook` + single `apply_queued()` call
16
+
17
+ ## Crash Detection
18
+
19
+ Tests that crash show `CRASH` (not `FAIL`) with NTSTATUS name and ERRORLOG.TXT content. ERRORLOG.TXT is redirected to the per-test run directory via `OPENWA_ERRORLOG_PATH`.
20
+
21
+ ## Adding New Replay Tests
22
+
23
+ 1. Record a game in WA.exe (the replay `.WAgame` file is saved automatically)
24
+ 2. Copy the replay to `testdata/replays/`
25
+ 3. Run once with the headless test runner β€” it auto-generates the `*_expected.log` baseline
26
+ 4. Subsequent runs compare against this baseline
27
+
28
+ ## Environment Variables
29
+
30
+ - `OPENWA_HEADLESS=1` β€” Headless mode: hooks MessageBoxA to auto-dismiss, launcher uses SW_HIDE, file isolation hook active, semaphore renamed per-PID
31
+ - `OPENWA_LOG_PATH=<path>` β€” Override OpenWA.log location (used for per-instance isolation)
32
+ - `OPENWA_ERRORLOG_PATH=<path>` β€” Redirect ERRORLOG.TXT to specified path (crash capture)
33
+
34
+ ## Key Paths
35
+
36
+ - Replay files + expected logs: `testdata/replays/*.WAgame` + `*_expected.log`
37
+ - Per-run output: `testdata/runs/<timestamp>/` (gitignored)
38
+ - Convenience script: `run-tests.ps1`
crates/openwa-wormkit/CLAUDE.md ADDED
@@ -0,0 +1,46 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # openwa-wormkit
2
+
3
+ Unified WormKit cdylib (`wkOpenWA.dll`). Contains thin hook installation shims that wire `openwa-core` game logic into WA.exe via MinHook. Game logic itself lives in `openwa-core` β€” this crate is purely the wiring layer.
4
+
5
+ See the root `CLAUDE.md` for project-wide rules: architecture, calling conventions, ASLR rebasing, FFI style, design conventions.
6
+
7
+ ## Hooking Patterns
8
+
9
+ Hooks use the `minhook` crate. Four patterns:
10
+
11
+ 1. **Passthrough hook** (logging only): Call original via trampoline, log result.
12
+ 2. **Full replacement**: Reimplement the function in Rust.
13
+
14
+ For `__usercall` functions, use a naked trampoline to capture register params before calling the Rust impl. **ECX preservation**: The standard `reg = ecx` trampoline variants do NOT preserve ECX across the cdecl impl call. MSVC-generated callers often loop calling thiscall functions without re-setting ECX between iterations (relying on the original function preserving it). Use the `preserve_ecx` variant for thiscall hooks where callers may rely on ECX being preserved: `usercall_trampoline!(fn name; impl_fn = path; reg = ecx; stack_params = N; ret_bytes = "0xN"; preserve_ecx)`.
15
+
16
+ 3. **Vtable method replacement**: Use `vtable_replace!` to patch vtable slots at runtime. Write the replacement as `unsafe extern "thiscall" fn`. Save the original via `[ORIG_STATIC]` syntax if you need to call through. See `replacements/task/cloud.rs`.
17
+ 4. **Trap hook** (`install_trap!`): For functions whose only caller is now ported Rust. Panics if called unexpectedly.
18
+
19
+ ### Bridge function patterns
20
+
21
+ When calling unported WA functions from Rust, use naked asm bridges. **Always pass the runtime target address as a cdecl parameter** (e.g., `rb(va::FUNC_ADDR)` as the last arg). Do NOT use `sym` + `jmp [ptr]` indirection through static pointers β€” this causes crashes due to relocation/PIC issues on x86 DLLs.
22
+
23
+ When a register param (e.g., EAX) must be set for the target function, load the call target into a **different** register (EBX, etc.) before the `call`. Do not use EAX for the target if EAX is also a parameter.
24
+
25
+ ## Hook Installation
26
+
27
+ `replacements/mod.rs` orchestrates all hook installation via `install_all()`:
28
+
29
+ 1. **Infrastructure hooks** (always installed): `headless`, `file_isolation`, `frame_hook`, `trace_desync`
30
+ 2. **Baseline mode** (`OPENWA_TRACE_BASELINE=1`): returns early after infrastructure, skipping all gameplay hooks. Used by trace-desync for a "nearly vanilla" reference run.
31
+ 3. **Gameplay hooks** (normal mode): all remaining subsystems β€” display, game_session, frontend, scheme, config, weapon, team, render, sprite, sound, speech, ddgame_init, replay, task, weapon_release, etc.
32
+
33
+ All hooks use `queue_enable_hook` + single `apply_queued()` call for batched MinHook enables (avoids repeated MH_EnableHook overhead).
34
+
35
+ ## Key Files
36
+
37
+ - `src/hook.rs` β€” MinHook helpers: `install()`, `install_trap!`, `usercall_trampoline!` macro, `queue_enable_hook` + `apply_queued()`
38
+ - `src/lib.rs` β€” DLL entry point (`DllMain`), startup checks, `install_all()` call
39
+ - `src/replacements/mod.rs` β€” `install_all()` orchestration, infrastructure vs gameplay split
40
+ - `src/replacements/*.rs` β€” Per-subsystem hook shims (one file per WA subsystem)
41
+ - `src/replacements/task/` β€” Vtable method replacements (cloud, filter, ...)
42
+ - `src/replacements/frame_hook.rs` β€” TurnManager_ProcessFrame hook, debug_sync, watchpoint arming (always installed)
43
+ - `src/replacements/trace_desync.rs` β€” Per-frame checksum logging for desync bisection
44
+ - `src/debug_server.rs` β€” TCP debug server (port 19840)
45
+ - `src/debug_watchpoint.rs` β€” Hardware watchpoint instrumentation (DR0-DR3)
46
+ - `src/snapshot.rs` β€” Game state snapshot for diffing