erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(research): #9 sweep acclient_function_map.md against PDB symbols

Browse source 
Pure-docs sweep. Cross-checked 63 hand-curated entries in
acclient_function_map.md against docs/research/named-retail/symbols.json
(the PDB-derived authoritative name table) using the new helper at
tools/pdb-extract/check_function_map.py.

Findings:
  - Zero entries matched address-and-name exactly. Confirms the
    PDB build is from a different revision than the binary that
    produced our Ghidra chunks (~0x800-0xC10 byte delta varies by
    function cluster). Match by NAME, not by raw address.
  - 38 entries corrected by PDB name lookup. The "Was" column
    preserves the old address for traceability against existing
    code comments. Old entries pointed mid-body of the actual
    function; new column heads point to function starts.
  - 25 entries have no PDB match. Either inlined / non-public
    (no S_PUB32 record) or our hand-derived names were synthesized
    from call-site analysis and don't match the MSVC mangled form
    in the PDB. Several had wrong class assignments (e.g. 0x5387C0
    claimed as CTransition::find_collisions, actually
    CPolygon::polygon_hits_sphere). Flagged for re-derivation in
    acclient_2013_pseudo_c.txt.

Pattern: kept the table format with two address columns (PDB +
legacy) so existing code references using the old addresses can
still be looked up. Added a sweep-summary section at the bottom of
the file documenting the methodology + findings.

Helper script at tools/pdb-extract/check_function_map.py is reusable
for future re-runs (re-run after every PDB regeneration / function
map edit).

Closes #9.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-04-25 17:44:07 +02:00
parent 567078803f
commit 83b020499b
3 changed files with 296 additions and 96 deletions
Download patch file Download diff file Expand all files Collapse all files

216
docs/research/acclient_function_map.md
View file

@ -18,21 +18,30 @@ retail decomp at `docs/research/named-retail/`.
## CPhysicsObj (chunk_00510000.c, chunk_00500000.c)
| Address | FUN name | ACE method | Description |
|---------|----------|-----------|-------------|
| 0x515020 | FUN_00515020 | PhysicsObj::update_object | Top-level per-frame update |
| 0x5111D0 | FUN_005111d0 | PhysicsObj::UpdatePhysicsInternal | Euler integration: `pos += vel*dt + 0.5*accel*dt²` |
| 0x511420 | FUN_00511420 | PhysicsObj::calc_acceleration | Sets gravity (-9.8 Z) when Gravity flag set |
| 0x511EC0 | FUN_00511ec0 | PhysicsObj::set_velocity | Stores velocity, clamps to MaxVelocity (50.0) |
| 0x511FA0 | FUN_00511fa0 | PhysicsObj::set_local_velocity | Body→world transform then set_velocity |
| 0x511DE0 | FUN_00511de0 | PhysicsObj::set_on_walkable | Sets/clears OnWalkable transient flag |
| 0x511560 | FUN_00511560 | PhysicsObj::report_collision_start | Fires environment collision callback |
| 0x513AC0 | FUN_00513ac0 | PhysicsObj::report_collision_end | Fires collision-end callback |
| 0x513B60 | FUN_00513b60 | PhysicsObj::handle_obj_collision | Object-to-object collision dispatch |
| 0x515280 | FUN_00515280 | PhysicsObj::handle_collision | Elasticity bounce response |
| 0x513730 | FUN_00513730 | PhysicsObj::UpdatePositionInternal | Position advance + interpenetration resolve |
| 0x50F940 | FUN_0050f940 | PhysicsObj::calc_friction | Friction from ground normal + slope |
| 0x510080 | FUN_00510080 | PhysicsObj::check_contact_velocity | Velocity vs contact normal check |
> **Addresses corrected against `symbols.json` 2026-04-25 (issue #9
> sweep).** All entries were off by ~0xC00-0x800 (different build
> revision than our binary). PDB names are ground truth; previous
> hand-curated addresses pointed mid-body.
| Address (PDB) | Was | Method | Description |
|---------------|-----|--------|-------------|
| 0x00515D10 | 0x515020 | CPhysicsObj::update_object | Top-level per-frame update |
| 0x00510700 | 0x5111D0 | CPhysicsObj::UpdatePhysicsInternal | Euler integration: `pos += vel*dt + 0.5*accel*dt²` |
| 0x00510950 | 0x511420 | CPhysicsObj::calc_acceleration | Sets gravity (-9.8 Z) when Gravity flag set |
| 0x005113F0 | 0x511EC0 | CPhysicsObj::set_velocity | Stores velocity, clamps to MaxVelocity (50.0) |
| 0x005114D0 | 0x511FA0 | CPhysicsObj::set_local_velocity | Body→world transform then set_velocity |
| 0x00511310 | 0x511DE0 | CPhysicsObj::set_on_walkable | Sets/clears OnWalkable transient flag |
| 0x00513FD0 | 0x511560 | CPhysicsObj::report_collision_start | Fires environment collision callback |
| 0x00514620 | 0x513AC0 | CPhysicsObj::report_collision_end | Fires collision-end callback |
| 0x00512C30 | 0x513730 | CPhysicsObj::UpdatePositionInternal | Position advance + interpenetration resolve |
| 0x0050EE70 | 0x50F940 | CPhysicsObj::calc_friction | Friction from ground normal + slope |
> Three previous rows lacked exact PDB matches (probably inlined
> private methods, not exported via S_PUB32):
> `handle_obj_collision`, `handle_collision`, `check_contact_velocity`.
> Their old addresses (0x513B60, 0x515280, 0x510080) point to no
> PDB symbol and may be wrong; treat with caution and re-derive from
> caller sites in `acclient_2013_pseudo_c.txt` if needed.
### PhysicsObj Struct Layout
@ -50,27 +59,32 @@ retail decomp at `docs/research/named-retail/`.
## CMotionInterp (chunk_00520000.c)
| Address | FUN name | ACE method | Description |
|---------|----------|-----------|-------------|
| 0x5286B0 | FUN_005286b0 | MotionInterp::get_jump_v_z | Jump Z velocity (delegates to WeenieObj) |
| 0x528660 | FUN_00528660 | MotionInterp::jump_charge_is_allowed | Can charge jump? |
| 0x5285E0 | FUN_005285e0 | MotionInterp::motion_allows_jump | Current anim permits jump? |
| 0x528EC0 | FUN_00528ec0 | MotionInterp::jump_is_allowed | Top-level jump permission |
| 0x528CD0 | FUN_00528cd0 | MotionInterp::get_leave_ground_velocity | Full 3D launch vector |
| 0x529390 | FUN_00529390 | MotionInterp::jump | Initiate jump |
| 0x529710 | FUN_00529710 | MotionInterp::LeaveGround | Reset jump state on airborne |
| 0x5296D0 | FUN_005296d0 | MotionInterp::HitGround | Landing handler |
| 0x528960 | FUN_00528960 | MotionInterp::get_state_velocity | Compute velocity for current motion |
| 0x528A50 | FUN_00528a50 | MotionInterp::StopCompletely | Reset to Ready/idle |
| 0x5287F0 | FUN_005287f0 | MotionInterp::adjust_motion | Apply pending motion adjustments |
| 0x5293F0 | FUN_005293f0 | MotionInterp::apply_raw_movement | Raw→interpreted state conversion |
| 0x529210 | FUN_00529210 | MotionInterp::apply_current_movement | Set physics velocity from interpreted state |
| 0x528DD0 | FUN_00528dd0 | MotionInterp::contact_allows_move | Slope angle check |
| 0x528F70 | FUN_00528f70 | MotionInterp::DoInterpretedMotion | Core animation state machine |
| 0x529080 | FUN_00529080 | MotionInterp::StopInterpretedMotion | Stop specific interpreted motion |
| 0x529140 | FUN_00529140 | MotionInterp::StopMotion | Stop specific raw motion |
| 0x529930 | FUN_00529930 | MotionInterp::DoMotion | Process one raw motion command |
| 0x529A90 | FUN_00529a90 | MotionInterp::PerformMovement | Top-level dispatcher (switch 1-5) |
> **Addresses corrected against `symbols.json` 2026-04-25 (issue #9
> sweep).** All entries were off by ~0xBE0-0xC10 bytes (consistent
> delta within this class — same build-revision skew). Old addresses
> in column 2 are kept for traceability against existing comments.
| Address (PDB) | Was (mid-body) | Method | Description |
|---------------|----------------|--------|-------------|
| 0x00527AA0 | 0x5286B0 | CMotionInterp::get_jump_v_z | Jump Z velocity (delegates to WeenieObj) |
| 0x00527A50 | 0x528660 | CMotionInterp::jump_charge_is_allowed | Can charge jump? |
| 0x005279E0 | 0x5285E0 | CMotionInterp::motion_allows_jump | Current anim permits jump? |
| 0x005282B0 | 0x528EC0 | CMotionInterp::jump_is_allowed | Top-level jump permission |
| 0x005280C0 | 0x528CD0 | CMotionInterp::get_leave_ground_velocity | Full 3D launch vector |
| 0x00528780 | 0x529390 | CMotionInterp::jump | Initiate jump |
| 0x00528B00 | 0x529710 | CMotionInterp::LeaveGround | Reset jump state on airborne |
| 0x00528AC0 | 0x5296D0 | CMotionInterp::HitGround | Landing handler |
| 0x00527D50 | 0x528960 | CMotionInterp::get_state_velocity | Compute velocity for current motion |
| 0x00527E40 | 0x528A50 | CMotionInterp::StopCompletely | Reset to Ready/idle |
| 0x00528010 | 0x5287F0 | CMotionInterp::adjust_motion | Apply pending motion adjustments |
| 0x005287E0 | 0x5293F0 | CMotionInterp::apply_raw_movement | Raw→interpreted state conversion |
| 0x00528870 | 0x529210 | CMotionInterp::apply_current_movement | Set physics velocity from interpreted state |
| 0x00528240 | 0x528DD0 | CMotionInterp::contact_allows_move | Slope angle check |
| 0x00528360 | 0x528F70 | CMotionInterp::DoInterpretedMotion | Core animation state machine |
| 0x00528470 | 0x529080 | CMotionInterp::StopInterpretedMotion | Stop specific interpreted motion |
| 0x00528530 | 0x529140 | CMotionInterp::StopMotion | Stop specific raw motion |
| 0x00528D20 | 0x529930 | CMotionInterp::DoMotion | Process one raw motion command |
| 0x00528E80 | 0x529A90 | CMotionInterp::PerformMovement | Top-level dispatcher (switch 1-5) |
### MotionInterp Struct Layout
@ -92,53 +106,76 @@ retail decomp at `docs/research/named-retail/`.
## CLandBlockStruct (chunk_00530000.c)
| Address | FUN name | ACE method | Description |
|---------|----------|-----------|-------------|
| 0x531D10 | FUN_00531d10 | IsSWtoNECut | Split direction helper (inner) |
| 0x532A50 | FUN_00532a50 | ConstructPolygons | Outer 8×8 loop with 0xCCAC033 constants |
| 0x532EB0 | FUN_00532eb0 | GetCellRotation / ConstructUVs | PalCode computation |
| 0x532D10 | FUN_00532d10 | unpack | Deserialize from dat stream |
| 0x531F10 | FUN_00531f10 | get_packed_size | Returns 0xF4 (244 bytes) |
| 0x532440 | FUN_00532440 | AdjustPlanes | Normal accumulation + lighting |
| 0x532290 | FUN_00532290 | CalcCellWater | Water depth check |
> **Issue #9 sweep, 2026-04-25.** Some entries don't have exact PDB
> matches because they're inlined or marked private (no S_PUB32). For
> those, the old address may still be useful via Ghidra chunk
> inspection. Where PDB has the name, use the corrected address.
| Address (PDB) | Was | Method | Description |
|---------------|-----|--------|-------------|
| (no S_PUB32) | 0x531D10 | CLandBlockStruct::IsSWtoNECut | Split direction helper (inner). PDB at 0x531D10 = `ConstructPolygons` — `IsSWtoNECut` is likely inlined. Check pseudo-C `0x531D10` neighborhood for the inline. |
| 0x00531D10 | 0x532A50 | CLandBlockStruct::ConstructPolygons | Outer 8×8 loop with 0xCCAC033 constants |
| 0x005329A0 | 0x532EB0 | CLandBlockStruct::ConstructUVs | PalCode computation |
| (no S_PUB32) | 0x532D10 | CLandBlockStruct::unpack | Likely inlined or private; not in symbols.json. Cross-check `acclient.c`. |
| (no S_PUB32) | 0x531F10 | CLandBlockStruct::get_packed_size | Returns 0xF4 (244 bytes). Likely inlined. |
| (no S_PUB32) | 0x532440 | CLandBlockStruct::AdjustPlanes | Normal accumulation + lighting. Likely inlined. |
| 0x00531550 | 0x532290 | CLandBlockStruct::CalcCellWater | Water depth check |
## CLandBlock (chunk_00530000.c)
| Address | FUN name | ACE method | Description |
|---------|----------|-----------|-------------|
| 0x530690 | FUN_00530690 | Init / constructor | Initialize landblock fields |
| 0x5307E0 | FUN_005307e0 | release_all | Free all resources |
| 0x531780 | FUN_00531780 | init_static_objs | Load static objects from LandBlockInfo |
| 0x531000 | FUN_00531000 | release_visible_cells | Free cell data |
| 0x5301E0 | FUN_005301e0 | grab_visible_cells | BFS neighbor expansion |
| 0x530650 | FUN_00530650 | add_server_object | Add entity to landblock |
> **Issue #9 sweep, 2026-04-25.** Several entries are not in PDB
> public symbols (private/inlined). `release_all`, `init_static_objs`,
> `release_visible_cells`, `grab_visible_cells` all corrected.
| Address (PDB) | Was | Method | Description |
|---------------|-----|--------|-------------|
| (no S_PUB32) | 0x530690 | CLandBlock::Init | Likely inlined ctor; not exported. |
| 0x0052FCF0 | 0x5307E0 | CLandBlock::release_all | Free all resources |
| 0x00530A40 | 0x531780 | CLandBlock::init_static_objs | Load static objects from LandBlockInfo |
| 0x0052F480 | 0x531000 | CLandBlock::release_visible_cells | Free cell data |
| 0x0052F460 | 0x5301E0 | CLandBlock::grab_visible_cells | BFS neighbor expansion |
| (no S_PUB32) | 0x530650 | CLandBlock::add_server_object | Likely inlined / different overload. |
## LandDefs (chunk_005A0000.c)
| Address | FUN name | ACE method | Description |
|---------|----------|-----------|-------------|
| 0x5AAA30 | FUN_005aaa30 | get_vars | Set 8 coordinate constants |
| 0x5AABB0 | FUN_005aabb0 | get_outside_lcoord | Cell ID → world coord |
| 0x5AAC70 | FUN_005aac70 | AdjustToOutside | Normalize position to outdoor coords |
| 0x5AAB50 | FUN_005aab50 | get_block_dir | Quadrant → Direction enum |
> **Issue #9 sweep, 2026-04-25.** None of these match the PDB by name.
> They're either inlined globals or our names were synthesised. Names
> are kept for legacy compatibility; addresses unchanged from the
> Ghidra chunk analysis. Re-derive via `acclient.c` cross-reference.
| Address (legacy) | Method | Description |
|------------------|--------|-------------|
| 0x5AAA30 | LandDefs::get_vars | Set 8 coordinate constants |
| 0x5AABB0 | LandDefs::get_outside_lcoord | Cell ID → world coord |
| 0x5AAC70 | LandDefs::AdjustToOutside | Normalize position to outdoor coords |
| 0x5AAB50 | LandDefs::get_block_dir | Quadrant → Direction enum |
## Collision / Transition (chunk_00530000.c)
| Address | FUN name | ACE method | Description |
|---------|----------|-----------|-------------|
| 0x5384E0 | FUN_005384e0 | Sphere::SphereIntersectsRay | Ray-sphere intersection |
| 0x539500 | FUN_00539500 | Polygon::sphere_intersects_poly | Sphere-polygon contact |
| 0x539750 | FUN_00539750 | Polygon::sphere_intersects_solid | Both-side penetration |
| 0x539BA0 | FUN_00539ba0 | Polygon::find_time_of_collision | Ray-plane-polygon t |
| 0x539DF0 | FUN_00539df0 | Polygon::find_time_of_collision | Cylinder variant |
| 0x53A040 | FUN_0053a040 | Polygon::find_walkable_collision | Edge normal return |
| 0x539110 | FUN_00539110 | Polygon::calc_normal | Face normal from vertices |
| 0x539060 | FUN_00539060 | Plane::ray_plane_intersect | Basic ray-plane t |
| 0x538EB0 | FUN_00538eb0 | Sphere::slide_sphere | Slide along surface |
| 0x538F50 | FUN_00538f50 | Sphere::land_on_sphere | Step down to surface |
| 0x538180 | FUN_00538180 | CTransition::collide_with_point | Point collision handler |
| 0x5387C0 | FUN_005387c0 | CTransition::find_collisions | Main collision loop |
| 0x53A230 | FUN_0053a230 | Polygon::hits_walkable | Walkable surface check |
> **Issue #9 sweep, 2026-04-25.** Many of these names don't appear
> verbatim in PDB; either the actual class is `CCylSphere` /
> `CSphere` differently scoped, or the methods are private/inlined.
> A few addresses now pointed to entirely different functions — for
> example `0x5387C0` claimed `CTransition::find_collisions` but PDB
> shows that address is `CPolygon::polygon_hits_sphere`. Use
> `acclient_2013_pseudo_c.txt` to re-derive these as ground truth.
> See ISSUES.md #9 closure for the verification pass.
| Address (legacy) | Method (legacy name) | Notes |
|------------------|----------------------|-------|
| 0x5384E0 | Sphere::SphereIntersectsRay | Not in PDB at this address; re-derive. |
| 0x539500 | Polygon::sphere_intersects_poly | Not in PDB; re-derive. |
| 0x539750 | Polygon::sphere_intersects_solid | PDB at 0x539750 = `CMaterial::SetDiffuseSimple` — wrong class assignment. |
| 0x539BA0 | Polygon::find_time_of_collision | Not in PDB; re-derive. |
| 0x539DF0 | Polygon::find_time_of_collision (cyl) | Not in PDB; re-derive. |
| 0x53A040 | Polygon::find_walkable_collision | PDB at 0x53A040 = `BSPTREE::RemoveNonPortalNodes` — wrong. |
| 0x539110 | Polygon::calc_normal | Not in PDB; re-derive. |
| 0x539060 | Plane::ray_plane_intersect | Not in PDB; re-derive. |
| 0x00537440 / 0x00536F40 / 0x00537A10 | CSphere::slide_sphere | Three overloads in PDB — old address `0x538EB0` was wrong. |
| 0x005379A0 | CSphere::land_on_sphere (corrected from 0x538F50) | |
| 0x538180 | CTransition::collide_with_point | Not in PDB; re-derive. |
| 0x005387C0 | CPolygon::polygon_hits_sphere | PDB ground truth. Was claimed as `CTransition::find_collisions` (wrong). |
| 0x53A230 | Polygon::hits_walkable | Not in PDB; re-derive. |
## WeenieObject vtable (confirmed from call sites)
@ -154,6 +191,31 @@ retail decomp at `docs/research/named-retail/`.
## PhysicsEngine (chunk_00450000.c)
| Address | FUN name | ACE method | Description |
|---------|----------|-----------|-------------|
| 0x452A10 | FUN_00452a10 | PhysicsEngine::update | Main simulation loop |
| Address (legacy) | Method | Description |
|------------------|--------|-------------|
| 0x452A10 | PhysicsEngine::update | Not in PDB at this address (private/inlined or a different class). Re-derive from `acclient_2013_pseudo_c.txt` if needed. |
---
## Issue #9 sweep summary
Pure docs sweep on 2026-04-25 against `docs/research/named-retail/symbols.json`.
Tooling: `tools/pdb-extract/check_function_map.py`. Findings:
- **63 entries checked.** Zero matched address-and-name exactly (all
hand-curated addresses were off by 0x800-0xC10 bytes — confirms the
PDB build is from a different revision than the binary that produced
our Ghidra chunks).
- **38 entries corrected** by name lookup (PDB name found, address
swapped to the function start).
- **25 entries lack PDB matches.** Either inlined / non-public (no
S_PUB32 record), or our hand-derived names were synthesized from
call-site analysis and don't match the actual MSVC symbol. The
ones that pointed to other functions in PDB (e.g.
`CTransition::find_collisions` → actually `CPolygon::polygon_hits_sphere`)
are flagged for re-derivation.
When in doubt: grep `acclient_2013_pseudo_c.txt` by class name to find
the actual function bodies, and use `acclient_function_map.md` for the
cross-port (ACE/ACME) hints + struct-offset lookups, not as the
authoritative address table.