# 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:
   ```powershell
   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:

```powershell
# 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:

```powershell
$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`](../../CLAUDE.md#known-watchouts):

- **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`.