acdream/tools/cdb/README-a6-probe.md

A6.P1 cdb probe — usage

Phase A6.P1 cdb probe spike (2026-05-21). Captures retail's per-tick BSP collision response state for paired comparison against acdream.

Files

• a6-probe.cdb — the 7-breakpoint cdb script (see comments inside).
• a6-probe-runner.ps1 — PowerShell wrapper that attaches cdb to live retail.

Prerequisites

1. Retail binary matches our PDB. Verify with:

   py tools\pdb-extract\check_exe_pdb.py "C:\Turbine\Asheron's Call\acclient.exe"
   

   Expected: === MATCH: this exe pairs with our acclient.pdb ===

2. cdb installed. Microsoft Store WinDbg installs cdb at C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\cdb.exe. 32-bit required for acclient.exe.

3. Retail running and in-world. Launch retail, log into your character, navigate to the scenario start point.

4. ACE running locally on 127.0.0.1:9000.

Usage

For each of the 9 A6.P1 scenarios:

# 1. Position retail character at scenario start (e.g., outside Holtburg inn).
# 2. Launch the probe with a scenario tag:
.\tools\cdb\a6-probe-runner.ps1 -ScenarioTag "scen1_inn_doorway"

# 3. cdb attaches; "a6-probe armed: BPs 1-7 set" appears in console.
# 4. In the retail client window, perform the scripted walk for this scenario.
# 5. cdb auto-detaches at 50K total hits (cleanly via qd; retail keeps running).
# 6. Log filed at docs\research\2026-05-21-a6-captures\scen1_inn_doorway\retail.log

The 9 scenarios

Per the A6 design spec, in capture order:

#	Tag	Walk script
1	scen1_inn_doorway	Walk forward through door, stop just inside
2	scen2_inn_stairs	Walk up 4 steps, stop on landing
3	scen3_inn_2nd_floor	Walk forward 3 m, sidestep 1 m, walk back
4	scen4_cottage_cellar	Walk to cellar opening, descend 2 steps
5	scen5_sewer_entry	Walk into portal, then walk 2 m forward inside
6	scen6_sewer_first_stair	Walk down full stair flight
7	scen7_sewer_inter_room	Walk through portal, stop 1 m past
8	scen8_sewer_chamber	Walk in, traverse center, walk out other side
9	scen9_sewer_corridor	Walk full length end-to-end

Pairing with acdream

For each scenario, run acdream IN PARALLEL with the same scripted walk:

$env:ACDREAM_DAT_DIR          = "$env:USERPROFILE\Documents\Asheron's Call"
$env:ACDREAM_LIVE             = "1"
$env:ACDREAM_TEST_HOST        = "127.0.0.1"
$env:ACDREAM_TEST_PORT        = "9000"
$env:ACDREAM_TEST_USER        = "testaccount"
$env:ACDREAM_TEST_PASS        = "testpassword"
$env:ACDREAM_DEVTOOLS         = "1"
$env:ACDREAM_PROBE_PUSH_BACK  = "1"
$env:ACDREAM_PROBE_INDOOR_BSP = "1"
$env:ACDREAM_PROBE_CELL       = "1"
$env:ACDREAM_PROBE_CELL_CACHE = "1"
$env:ACDREAM_PROBE_CONTACT_PLANE = "1"

dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 |
    Tee-Object -FilePath "docs\research\2026-05-21-a6-captures\scen1_inn_doorway\acdream.log"

The [push-back], [push-back-disp], [push-back-cell] lines in acdream.log pair with the [BP1]..[BP7] lines in retail.log via scenario tag.

Known watchouts

Per CLAUDE.md:

• High BP hit rates cause retail lag. 50K threshold is the calibrated ceiling that keeps retail responsive without triggering ACE timeout.
• qd (quit detached) is forbidden in BP actions per CLAUDE.md cdb watchout. The a6-probe.cdb script puts qd ONLY in the threshold branch, NOT directly in a BP action's primary command list. Verify this is preserved if editing.
• Killing cdb kills retail. qd detaches cleanly; Stop-Process does not. If you must interrupt mid-capture, press Ctrl-Break in the cdb console.
• acclient.exe is 32-bit + uses thiscall. this is in ecx. Struct field offsets in the script come from docs/research/named-retail/acclient.h.