a9a01d8ba2
Move the high-value retail RE artifacts from refs/ (per-developer
download cache, gitignored) into committed paths so subagents +
post-compaction sessions inherit them without round-tripping:
- docs/research/named-retail/acclient_2013_pseudo_c.txt (62 MB,
Binary Ninja named pseudo-C, 99.6% function-name recovery —
18,366 named functions out of 18,598 public symbols)
- docs/research/named-retail/acclient.h (1.7 MB / 70,719 lines,
IDA-decompiled retail struct definitions verbatim — Attribute,
SecondaryAttribute, AttributeCache, Attribute2ndTable, SkillFormula,
Enchantment, CEnchantmentRegistry with _mult_list/_add_list/_vitae,
CSpellBook, MotionState, RawMotionState, MoveToStatePack, CACQualities,
CPhysicsObj — every retail object-model layout we'd otherwise have
to guess at)
- docs/research/named-retail/acclient.c (46 MB, secondary named
decomp — IDA full-binary export with mixed FUN_/named functions
plus named struct fields the chunked Ghidra output lacks)
- docs/research/data/spells.csv (3,956 spells × 35 cols including
Family for buff stacking — issue #6 unblocked)
actestclient-master vendored at references/actestclient/ (extracted
from refs/actestclient-master-2019-01-10.zip; contains the canonical
machine-readable wire-schema messages.xml). Covered by existing
references/ gitignore — per-developer reference, not committed.
Repo precedent for committing decompiled retail content was set at
commit 4d36756 (18 MB Ghidra chunks). This adds ~110 MB more of the
same qualitative content. Ripgrep handles it in <1s.
Foundation for the named-retail workflow change in CLAUDE.md (next
commit). Plan at C:/Users/erikn/.claude/plans/ticklish-conjuring-cake.md
Phase A.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
70 lines
4.1 KiB
Markdown
70 lines
4.1 KiB
Markdown
# Named-retail decompilation reference
|
|
|
|
**This is the primary reference for any AC-specific algorithm, formula,
|
|
constant, wire format, or coordinate convention.** Every retail symbol
|
|
question goes here first — _before_ touching `docs/research/decompiled/`
|
|
(the older Ghidra `FUN_xxx` chunks, which remain a fallback for
|
|
chunk-by-chunk address-range navigation).
|
|
|
|
## Contents
|
|
|
|
| File | Source | Use for |
|
|
|------|--------|---------|
|
|
| `acclient_2013_pseudo_c.txt` | Binary Ninja pseudo-C export of the Sept 2013 EoR `acclient.exe` build. 1,437,645 lines. **99.6% function-name recovery** (54,873 named, 232 still `sub_*`). Class names + method names + many struct field names recovered. | **Primary symbol lookup.** Grep by `class::method` to find function bodies. Address-prefixed lines: `00<address> <return-type> __<conv> Class::Method(args)`. |
|
|
| `acclient.h` | IDA-decompiled retail headers. 70,719 lines / 1.7 MB. Full struct + class definitions for the entire AC client object model: `Attribute`, `SecondaryAttribute`, `AttributeCache`, `Attribute2ndTable`, `SkillFormula`, `Enchantment`, `CEnchantmentRegistry` (with `_mult_list` / `_add_list` / `_vitae`), `CSpellBook`, `MotionState`, `RawMotionState`, `MoveToStatePack`, `CACQualities`, `CPhysicsObj`. | **Struct field names + offsets.** When you need to know what a field is actually called, grep this file. |
|
|
| `acclient.c` | Ghidra (or IDA) full-binary decomp export. 1,327,522 lines / 46 MB. Mixed naming: ~5,100 named methods + ~8,553 still `FUN_xxx`. Has named struct types like `_max_health`, `_add_list` that the chunked Ghidra export under `decompiled/` lacks. | **Secondary cross-reference.** Useful when pseudo-C body is corrupt / packed and you need a different decompiler's view. |
|
|
| `symbols.json` | Generated by `tools/pdb-extract/` from `refs/acclient.pdb`. 18,366 entries: `{"address", "name", "obj_module"}`. | **Programmatic symbol lookup.** `jq '.[] | select(.name == "...")'` returns the start address. |
|
|
| `types.json` | Generated by `tools/pdb-extract/`. 3,172 named struct/class type records with field offsets + sizes. | **Programmatic type-layout queries.** |
|
|
|
|
## Workflow — grep first, decompile second
|
|
|
|
The `CLAUDE.md` "Development workflow" mandates **Step 0: GREP NAMED FIRST**
|
|
before any decompilation work. Concretely:
|
|
|
|
```bash
|
|
# Find a function by class::method:
|
|
grep -n "CEnchantmentRegistry::EnchantAttribute" docs/research/named-retail/acclient_2013_pseudo_c.txt
|
|
|
|
# Find a struct definition:
|
|
grep -n "^struct.*CEnchantmentRegistry" docs/research/named-retail/acclient.h
|
|
|
|
# Find by raw address (PDB and pseudo-C addresses match):
|
|
grep -n "^00594570" docs/research/named-retail/acclient_2013_pseudo_c.txt
|
|
|
|
# Programmatic symbol lookup:
|
|
cat docs/research/named-retail/symbols.json | jq '.[] | select(.name == "CEnchantmentRegistry::EnchantAttribute")'
|
|
```
|
|
|
|
Only fall back to `docs/research/decompiled/chunk_*.c` (Ghidra `FUN_xxx`
|
|
chunks) when the named pseudo-C lacks a function — rare; covers only the
|
|
obfuscated/packed minority.
|
|
|
|
## Origin
|
|
|
|
- **PDB**: `refs/acclient.pdb` — Sept 2013 End-of-Retail (EoR) build, MSVC
|
|
7.00 program database, 29 MB. Build root: `d:\ac1_sep13\`.
|
|
- **pseudo-C**: Binary Ninja export of the `acclient_2013-2024-09-11.bndb`
|
|
database (also in `refs/`). 99.6% naming via PDB-overlay analysis.
|
|
- **acclient.h**: IDA-decompiled headers from a parallel RE effort.
|
|
- **acclient.c**: full-binary IDA/Ghidra decomp export (different from our
|
|
Ghidra chunks under `decompiled/`).
|
|
|
|
The `refs/` directory is gitignored (per-developer download cache); these
|
|
extracts are committed so subagents and post-compaction sessions inherit
|
|
them automatically.
|
|
|
|
## Address mapping caveat
|
|
|
|
The PDB is from a slightly different build run than the binary that
|
|
produced our Ghidra chunks (~0xC00 byte delta on some functions). When
|
|
correcting addresses in `docs/research/acclient_function_map.md`, **match
|
|
by name, not by raw address.**
|
|
|
|
## Regenerating `symbols.json` / `types.json`
|
|
|
|
```powershell
|
|
py tools\pdb-extract\pdb_extract.py refs\acclient.pdb
|
|
```
|
|
|
|
Outputs land in `docs/research/named-retail/symbols.json` and
|
|
`docs/research/named-retail/types.json`. See `tools/pdb-extract/README.md`.
|