feat(physics): #32 L.5 30Hz physics tick + retail debugger toolchain (#35) + Phase 3 retail-faithful kill_velocity
Three intertwined changes from a single investigation session driven by
attaching cdb to a live retail acclient.exe (v11.4186, Sept 2013 EoR
build) and tracing what retail actually DOES on the steep-roof wedge
scenario the user reported in acdream.
═══════════════════════════════════════════════════════════
1. L.5 — physics-tick MinQuantum gate (PlayerMovementController)
═══════════════════════════════════════════════════════════
Retail's CPhysicsObj::update_object subdivides per-frame dt into 1/30 s
sized integration steps and SKIPS entirely when accumulated dt is below
MinQuantum. Live trace evidence:
update_object = 40,960 calls
UpdatePhysicsInternal = 25,087 calls (61%)
i.e., 39% of update_object calls return early via the MinQuantum gate.
Retail's effective physics tick rate is 30Hz even at 60+ Hz render.
acdream's PlayerMovementController bypassed the existing PhysicsBody.
update_object and called UpdatePhysicsInternal(dt) directly each render
frame, which compressed bounce-energy / gravity-tangent accumulation
into half the time and amplified our steep-roof wedge dynamics.
Fix: add `_physicsAccum` accumulator. Integrate only when accumulated
dt ≥ MinQuantum (clamped to MaxQuantum to bound stale-frame jumps).
HugeQuantum drops accumulated time to discard truly stale frames
(debugger break, GC pause). Render still runs at full rate; only the
physics step is gated.
═══════════════════════════════════════════════════════════
2. Phase 3 reset retail-faithful kill_velocity (TransitionTypes)
═══════════════════════════════════════════════════════════
Retail's reset path (acclient_2013_pseudo_c.txt:273231-273239) gates
kill_velocity on `last_known_contact_plane_valid`:
if (last_known_valid == 0) {
set_collision_normal(step_up_normal); return COLLIDED;
}
kill_velocity(this);
last_known_valid = 0;
return COLLIDED;
Earlier in this session I deviated to "unconditional kill_velocity" as
a hypothesis-driven wedge fix. The live trace then showed the
deviation CAUSED a different wedge by zeroing V every frame, leaving
the body with no tangent momentum to escape (V = (0,0,0) for 169
consecutive frames while position pre/resolved frozen). The retail-
faithful gate is restored.
Note: the gate rarely fires in normal airborne play because our L.2.4
proximity guard clears last_known_valid soon after the body separates
from its remembered floor. Live retail trace also showed
kill_velocity = 0 hits over an entire play session — same behavior. So
acdream's kill_velocity is correct as ported now.
The supporting ObjectInfo.VelocityKilled flag + StopVelocity wiring +
PhysicsEngine.ResolveWithTransition consumer that actually zeros
body.Velocity when the flag is set — these were a no-op stub before
this session and are now correctly wired. Retail anchor:
OBJECTINFO::kill_velocity → CPhysicsObj::set_velocity({0,0,0}, 0) at
acclient_2013_pseudo_c.txt:274467-274475.
═══════════════════════════════════════════════════════════
3. Retail debugger toolchain (#35)
═══════════════════════════════════════════════════════════
When the question is "what does retail actually DO at runtime?" — not
"what does retail's code SAY" — the decomp at docs/research/named-retail/
is invaluable but doesn't capture state interactions across frames.
This commit ships infrastructure to attach Windows' cdb.exe to a live
retail acclient.exe with full PDB symbols and capture state at any
breakpoint.
- tools/pdb-extract/check_exe_pdb.py — reads any PE's CodeView entry
and reports MATCH / MISMATCH against refs/acclient.pdb's GUID.
Always run before attaching cdb. The matching v11.4186 build's
GUID is 9e847e2f-777c-4bd9-886c-22256bb87f32.
- tools/pdb-extract/dump_pdb_info.py — dumps a PDB's expected
build timestamp + GUID + age. Used to figure out which acclient.exe
build pairs with our PDB.
CLAUDE.md gets a Step -1 in the development workflow ("ATTACH cdb
TO RETAIL when behavior is the question, not code") and a full
"Retail debugger toolchain" section with the workflow, sample .cdb
script structure, and watchouts (PDB names use snake_case for some
classes / PascalCase for CPhysicsObj; ; is cdb's command separator;
killing cdb kills the debuggee; high-hit-rate breakpoints lag the game).
memory/project_retail_debugger.md captures the workflow + key findings
so future sessions inherit the toolchain by reading project memory.
═══════════════════════════════════════════════════════════
4. BSPQuery Path 6 slide-tangent restored (b1af56e behavior)
═══════════════════════════════════════════════════════════
After this session's retail-strict experiments showed that retail-
faithful Path 6 (SetCollide + Phase 3 reset chain) produces a
"lands on roof in falling animation, can't slide off" half-state in
acdream — because our acdream port of step_up_slide / cliff_slide is
incomplete for grounded-on-steep movement — the L.4 slide-tangent
deviation from commit b1af56e is restored as the pragmatic ship state.
The deviation: when an airborne sphere hits a polygon whose normal Z
is below FloorZ (≈ 0.6642, slope > ~49°), project the move along the
steep face to remove the into-wall displacement, set CollisionNormal +
SlidingNormal, return Slid. Body never gets ContactPlane on the steep
poly, never gets the half-state, slides off the slope under gravity's
tangent contribution.
Retail-strict requires the deeper step_up_slide / cliff_slide audit
(filed under #32). Until that lands, slide-tangent is the right
deviation — produces user-acceptable "slide off the roof" behavior.
═══════════════════════════════════════════════════════════
Test status: 833/833 green.
Refs:
acclient_2013_pseudo_c.txt:283950 (CPhysicsObj::update_object)
acclient_2013_pseudo_c.txt:273231-273239 (Phase 3 reset path)
acclient_2013_pseudo_c.txt:274467-274475 (OBJECTINFO::kill_velocity)
acclient_2013_pseudo_c.txt:323783-323821 (BSPTREE::find_collisions Path 6)
Closes #35. Updates #32 with L.4/L.5 status.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik
parent
b1af56eb19
commit
235de3322a
8 changed files with 624 additions and 82 deletions
|
|
@ -172,6 +172,32 @@ public sealed class PlayerMovementController
|
|||
public const float HeartbeatInterval = 0.2f; // 200ms
|
||||
public bool HeartbeatDue { get; private set; }
|
||||
|
||||
// L.5 retail physics-tick gate (2026-04-30).
|
||||
//
|
||||
// Retail's CPhysicsObj::update_object subdivides per-frame dt into
|
||||
// MinQuantum (1/30s) sized integration steps, SKIPPING entirely when
|
||||
// accumulated dt is below MinQuantum. The retail debugger trace
|
||||
// confirmed this: UpdatePhysicsInternal fires only ~61% as often as
|
||||
// update_object — i.e., retail's effective physics tick rate is 30Hz
|
||||
// even when the renderer runs at 60+Hz.
|
||||
//
|
||||
// Without this gate our acdream integrates at the full render rate
|
||||
// (60+Hz), which compresses bounce-energy / gravity-tangent
|
||||
// accumulation into half the time. Per-frame V grows ~2x faster than
|
||||
// retail's. On a steep-slope tangent that produces the wedge: V grows
|
||||
// tangent + huge while position reverts each frame, body locks in
|
||||
// place. Retail's slower integration cadence (and larger per-tick
|
||||
// position deltas) lets the body geometrically escape the tangent.
|
||||
//
|
||||
// Source: retail debugger trace 2026-04-30
|
||||
// update_object = 40,960 calls
|
||||
// UpdatePhysicsInternal = 25,087 calls (61%)
|
||||
// ratio implies 39% of frames return early via the MinQuantum gate.
|
||||
//
|
||||
// ACE: PhysicsObj.UpdateObject (Physics.cs).
|
||||
// Named-retail: CPhysicsObj::update_object (acclient_2013_pseudo_c.txt:283950).
|
||||
private float _physicsAccum;
|
||||
|
||||
public PlayerMovementController(PhysicsEngine physics)
|
||||
{
|
||||
_physics = physics;
|
||||
|
|
@ -411,9 +437,34 @@ public sealed class PlayerMovementController
|
|||
}
|
||||
|
||||
// ── 4. Integrate physics (gravity, friction, sub-stepping) ────────────
|
||||
//
|
||||
// L.5 retail-physics-tick gate (2026-04-30): retail's CPhysicsObj::
|
||||
// update_object skips integration when accumulated dt is below
|
||||
// MinQuantum (1/30 s). Effective physics rate is 30 Hz even at 60+ Hz
|
||||
// render. We accumulate per-frame dt and only integrate (with the
|
||||
// accumulated dt) when the threshold is reached. See _physicsAccum
|
||||
// declaration for the full retail trace evidence.
|
||||
var preIntegratePos = _body.Position;
|
||||
_body.calc_acceleration();
|
||||
_body.UpdatePhysicsInternal(dt);
|
||||
_physicsAccum += dt;
|
||||
|
||||
if (_physicsAccum > PhysicsBody.HugeQuantum)
|
||||
{
|
||||
// Stale frame (debugger break, GC pause). Discard accumulated dt.
|
||||
_physicsAccum = 0f;
|
||||
}
|
||||
else if (_physicsAccum >= PhysicsBody.MinQuantum)
|
||||
{
|
||||
// Integrate accumulated dt, clamped to MaxQuantum so a long
|
||||
// pause doesn't produce one giant integration step.
|
||||
float tickDt = MathF.Min(_physicsAccum, PhysicsBody.MaxQuantum);
|
||||
_body.calc_acceleration();
|
||||
_body.UpdatePhysicsInternal(tickDt);
|
||||
_physicsAccum -= tickDt;
|
||||
}
|
||||
// Else: dt below MinQuantum threshold — skip integration. Position
|
||||
// and velocity remain unchanged; Resolve below runs as a zero-distance
|
||||
// sphere sweep (no collision possible) and the rest of the frame
|
||||
// (motion commands, animation, return) runs normally.
|
||||
var postIntegratePos = _body.Position;
|
||||
|
||||
// ── 5. Collision resolution via CTransition sphere-sweep ─────────────
|
||||
|
|
@ -520,32 +571,6 @@ public sealed class PlayerMovementController
|
|||
? !(prevOnWalkable && nowOnWalkable)
|
||||
: (!prevOnWalkable && !nowOnWalkable);
|
||||
|
||||
// L.4-steep-landing-bounce (2026-04-30): also bounce on
|
||||
// landing IF the contact surface is upward-facing but
|
||||
// steeper than walkable (FloorZ ≈ 49°). Per retail and the
|
||||
// user's expectation: jumping onto a steep roof should NOT
|
||||
// result in a landing — the player should bounce off, keep
|
||||
// the falling animation, and slide off.
|
||||
//
|
||||
// Without this: the L.3a base rule suppresses the bounce on
|
||||
// landing transitions (prev air → now ground) to avoid
|
||||
// micro-bounce on flat terrain, but that suppression also
|
||||
// sticks the player to too-steep roofs they shouldn't land
|
||||
// on. This carve-out re-enables the bounce specifically for
|
||||
// steep upward-facing surfaces.
|
||||
//
|
||||
// Range `0 < N.Z < FloorZ` means "facing upward but too
|
||||
// steep" — excludes walls (N.Z ≈ 0) which are handled by the
|
||||
// existing prevAirborne+nowAirborne rule, and ceilings
|
||||
// (N.Z < 0) which the body shouldn't bounce off the same way.
|
||||
if (!applyBounce
|
||||
&& resolveResult.CollisionNormalValid
|
||||
&& resolveResult.CollisionNormal.Z > 0f
|
||||
&& resolveResult.CollisionNormal.Z < PhysicsGlobals.FloorZ)
|
||||
{
|
||||
applyBounce = true;
|
||||
}
|
||||
|
||||
// L.4-diag (2026-04-30): per-frame bounce trace for steep-roof bug.
|
||||
bool diagSteep = Environment.GetEnvironmentVariable("ACDREAM_DUMP_STEEP_ROOF") == "1";
|
||||
if (diagSteep && resolveResult.CollisionNormalValid)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue