acdream/docs/research/2026-05-04-l3-port/01-per-tick.md

L.3 Per-Tick Body Update Pipeline — Retail Reference

Source: docs/research/named-retail/acclient_2013_pseudo_c.txt (Sept 2013 EoR build, PDB-named, Binary Ninja pseudo-C). Scope: How retail advances a CPhysicsObj (player or remote) one physics tick, from the entry call through animation-driven motion, physics integration, and collision resolution. Purpose: Correct the env-var per-tick path in GameWindow.cs (~line 6428+) so it matches retail order-of-operations and behavior, especially for "walking remote" cases where m_velocityVector is supposed to stay zero.

---

Top-level call graph

CPhysicsObj::UpdateObjectInternal(this, dt)            @ 0x005156b0
    └─ CPhysicsObj::UpdatePositionInternal(this, dt, &outFrame)  @ 0x00512c30
    │       ├─ CPartArray::Update(part_array, dt, &localFrame)    @ 0x00517db0
    │       │       └─ CSequence::update(&sequence, dt, &localFrame)  @ 0x00525b80
    │       │               ├─ CSequence::update_internal(...)        // advances anim cursor
    │       │               └─ CSequence::apply_physics(this, frame, dt, dt) @ 0x00524ab0
    │       │                       ├─ frame.m_fOrigin += dt * sequence.velocity  // ROOT MOTION
    │       │                       └─ Frame::rotate(frame, dt * sequence.omega)  // ROOT ROT
    │       ├─ PositionManager::adjust_offset(pos_mgr, &localFrame, dt) @ 0x00555190
    │       │       ├─ InterpolationManager::adjust_offset
    │       │       ├─ StickyManager::adjust_offset
    │       │       └─ ConstraintManager::adjust_offset
    │       ├─ Frame::combine(outFrame, &m_position.frame, &localFrame) @ 0x005122e0
    │       │       // outFrame = m_position.frame ⊗ localFrame (rotate-translate compose)
    │       ├─ CPhysicsObj::UpdatePhysicsInternal(this, dt, outFrame)  @ 0x00510700
    │       │       // Euler integration of m_velocityVector + m_accelerationVector + m_omegaVector
    │       │       // Modifies outFrame.m_fOrigin (translation) and rotation (Frame::grotate)
    │       │       // Modifies m_velocityVector (acceleration step)
    │       └─ CPhysicsObj::process_hooks(this)
    ├─ CPhysicsObj::transition(this, &m_position, &outFrame, 0)   @ 0x00512dc0
    │       └─ CTransition::find_valid_position(...)              // BSP / sphere sweep
    ├─ CPhysicsObj::set_frame(this, &outFrame)            @ 0x00514090   // (failure path)
    │   OR
    ├─ CPhysicsObj::SetPositionInternal(this, transition) @ 0x00515330   // (success path)
    └─ DetectionManager / TargetManager / MovementManager / CPartArray::HandleMovement / PositionManager::UseTime

---

1. CPhysicsObj::UpdateObjectInternal(this, dt) — entry

Address: 0x005156b0 (line 283611) Signature: void __thiscall CPhysicsObj::UpdateObjectInternal(CPhysicsObj* this, float dt)

What it does (plain English)

This is the per-tick entry for a physics object. It branches on transient_state:

• If transient_state has the high bit clear (i.e. >= 0, meaning the object is passive / dormant), it skips physics entirely and only ticks ParticleManager + ScriptManager.
• Otherwise it runs the active path: build a candidate next-frame, sweep collision, commit position, and tick all per-frame managers (Detection, Target, Movement, Position, parts).

Order of operations (active path)

#	Line	What happens
1	283631	If transient_state[1] & 1 → set_ethereal(this, 0, 0)
2	283634	this->jumped_this_frame = 0
3	283635-283643	Local stack Frame var_40 initialized to identity (qw=1, origin=0). Note var_48 holds 0x796910 = Position::vtable.
4	283644	Frame::cache(&var_40) — recompute m_fl2gv[0..8] rotation matrix from quaternion
5	283646	UpdatePositionInternal(this, dt, &var_40) — fills var_40 with the candidate next-frame
6	283651-283655	Check part_array && CPartArray::GetNumSphere(part_array) — does this object have a collision sphere?
7a	283655 (no spheres or zero-translation): set m_position.frame = var_40 directly via set_frame, zero cached_velocity, no transition.
7b	283657 (has spheres AND moved): run transition() collision sweep
7b1	283661-283670	If state[1] & 1 (Hooks?), set heading from translation direction; else if (state & ScaledVelocity) && !is_zero(m_velocityVector), set heading from velocity.
7b2	283673	transition(this, &m_position, &var_48, 0) — sweeps sphere from current pos to candidate pos var_48. Note var_48 here refers to the Position struct that has been built (the local var holds an embedded Position with vtable 0x796910 and frame var_40).
7b3	283675-283696	If transition == nullptr (no valid path): keep current frame via set_frame(&var_40), zero cached_velocity. Otherwise: compute cached_velocity = (final_pos - current_pos) / dt, then SetPositionInternal(this, transition).
8	283733	DetectionManager::CheckDetection
9	283738	TargetManager::HandleTargetting
10	283743	MovementManager::UseTime
11	283748	CPartArray::HandleMovement
12	283753	PositionManager::UseTime
13	283755	goto label_5159b8 → ticks ParticleManager + ScriptManager, then returns

Side effects

• this->m_position.frame ← committed final pose (via set_frame or SetPositionInternal)
• this->cell ← may change (cell crossing)
• this->cached_velocity ← actual delta achieved this tick / dt (used elsewhere for collision profiles, etc.)
• this->m_velocityVector ← updated by UpdatePhysicsInternal (acceleration integration)
• this->jumped_this_frame ← cleared
• this->contact_plane, this->sliding_normal, this->transient_state bits 1/4/8 ← updated by SetPositionInternal

Key conditions

• Spheres-and-moved gate at line 283655 + 283657: transition() is only called when the object has a sphere AND the candidate frame's origin moved (!operator==(zero_vec, m_position.frame.m_fOrigin)). The x here is a stack zero vector compared against current origin — if origin is at world-zero it skips. Wait, re-reading: actually x was overwritten on line 283641 to 0f, then operator== between &x (stack zero) and &this->m_position.frame.m_fOrigin. This is checking "did UpdatePositionInternal move us off m_position.frame.m_fOrigin"? No — it's comparing the local stack vector x (zero) against m_position. This is effectively is_zero(m_position) which is almost always false. Re-read more carefully: at line 283641 float x = 0f; is just initializing 3 stack floats (Vector3 x/y/z). The compare is "is the player at world origin (0,0,0)?". That's a degenerate check. So the practical interpretation: spheres-with-collision is the gate, and the no-sphere path just commits var_40 directly.

---

2. CPhysicsObj::UpdatePositionInternal(this, dt, outFrame) — build candidate frame

Address: 0x00512c30 (line 280817) Signature: void __thiscall CPhysicsObj::UpdatePositionInternal(CPhysicsObj* this, float dt, Frame* outFrame)

What it does (plain English)

Builds the candidate next-tick frame in outFrame. Three contributions, in order:

1. Animation root motion — CPartArray::Update calls CSequence::apply_physics, which writes localFrame.origin = dt * sequence.velocity and rotates localFrame by dt * sequence.omega. This is the per-cycle baked velocity from the current MotionData (e.g., RunForward emits ~4 m/s on +Y in body local).
2. Position-manager offset — PositionManager::adjust_offset lets InterpolationManager, StickyManager, ConstraintManager mutate the local frame.
3. Compose with current world pose — Frame::combine(outFrame, &this->m_position.frame, &localFrame) rotates the local-frame translation into world space and adds it to current world pos; multiplies quaternions.
4. Physics integration on the composed frame — UpdatePhysicsInternal Euler-integrates m_velocityVector and m_omegaVector into the same outFrame (this is the only place generalized velocity is consumed — see §4).

Order of operations

#	Line	What happens
1	280820-280826	Init local var_40 = identity Frame, plus var_c/var_8/var_4 = 0 (these are 3 floats that look like a Vector3 localTranslation slot).
2	280827	Frame::cache(&var_40) — populate rotation matrix m_fl2gv[0..8] (will be re-cached after apply_physics).
3	280829	If (state[1] & 0x40) == 0 (i.e. PartsArray::Frozen flag NOT set):
3a	280834	CPartArray::Update(part_array, dt, &var_40) — anim root motion goes into var_40
3b	280836-280848	If transient_state & 2 (Stuck/Active?), scale the captured var_c/var_8/var_4 (looks like a velocity scratch vector) by m_scale; else zero them. This branch's effect on var_40 is unclear from the decomp — possibly dead/diagnostic code.
4	280853-280857	If position_manager != nullptr → PositionManager::adjust_offset(pm, &var_40, dt)
5	280860	Frame::combine(outFrame, &this->m_position.frame, &var_40) — outFrame = world-pose ⊗ local-frame
6	280862	If NOT (state[1] & 0x40) → UpdatePhysicsInternal(this, dt, outFrame) (Euler step on the composed frame)
7	280865	process_hooks(this) — runs queued FP-hooks (scale fade, translucency fade, etc.)

Verbatim retail snippets

// Line 280827-280834
Frame::cache(&var_40);
if ((this->state[1] & 0x40) == 0) {
    CPartArray* part_array = this->part_array;
    if (part_array != 0)
        CPartArray::Update(part_array, dt, &var_40);
    ...
}

// Line 280853-280860 — order-critical: adjust_offset BEFORE combine
if (position_manager != 0)
    PositionManager::adjust_offset(position_manager, &var_40, dt);
Frame::combine(outFrame, &this->m_position.frame, &var_40);

// Line 280862-280865 — physics integration AFTER compose, hooks last
if ((this->state[1] & 0x40) == 0)
    CPhysicsObj::UpdatePhysicsInternal(this, dt, outFrame);
CPhysicsObj::process_hooks(this);

Side effects

• outFrame ← fully populated candidate next-tick world frame
• m_velocityVector, m_omegaVector ← updated inside UpdatePhysicsInternal
• m_position.frame ← NOT TOUCHED here (commit happens in set_frame/SetPositionInternal)

Critical observation: state.0x40 ("Frozen") double-gate

The Frozen flag both:

• Skips animation root motion (CPartArray::Update)
• Skips physics integration (UpdatePhysicsInternal)

But still runs Frame::combine against the (now-empty) localFrame. Net effect: a frozen object's outFrame == m_position.frame (no motion).

---

3. CSequence::apply_physics(seq, frame, dt, dt) — animation root motion source

Address: 0x00524ab0 (line 300955) Signature: void __thiscall CSequence::apply_physics(const CSequence* this, Frame* arg2, double arg3, double arg4)

What it does

Writes the animation's baked locomotion into frame. This is the only code path that produces translation for "walking" remotes — m_velocityVector stays at zero for them and UpdatePhysicsInternal's Euler-translation step is a no-op.

Pseudocode (plain)

double scale = fabs(arg3);                      // dt magnitude
if (arg4 < 0) scale = -scale;                   // sign from arg4
frame->origin.x += scale * sequence->velocity.x;
frame->origin.y += scale * sequence->velocity.y;
frame->origin.z += scale * sequence->velocity.z;
Vector3 omegaScaled = scale * sequence->omega;
Frame::rotate(frame, &omegaScaled);             // local-frame quaternion rotate

sequence->velocity and sequence->omega are updated as the AnimSequenceNodes advance (CSequence::update_internal handles cursor advancement; apply_physics consumes the current cycle's baked velocity). This is the data driven via MotionData fields — e.g. RunForward MotionData has Velocity = (0, 4.0, 0) baked in, scaled by speed multiplier.

Why this matters for L.3

The spec says m_velocityVector stays at 0 for walking remotes — verify

Confirmed. For locomotion-driven remotes:

1. Server sends UpdateMotion(RunForward, speed=N).
2. Sequencer enters the RunForward cycle.
3. CSequence::apply_physics writes dt * (0, 4*N, 0) to the local frame's origin every tick.
4. Frame::combine rotates that body-local +Y into world space using m_position.frame.m_fl2gv and adds to world pos.
5. UpdatePhysicsInternal runs but with m_velocityVector ≈ 0 (no physics push) → its Euler-translation step adds nothing meaningful. It still does the omega-rotate step using m_omegaVector if non-zero.

This is why acdream's apply_current_movement → body.Velocity → UpdatePhysicsInternal chain is the wrong shape for remotes. Retail does NOT push locomotion through m_velocityVector. It pushes locomotion through the sequencer's baked-velocity → local frame → combine.

---

4. CPhysicsObj::UpdatePhysicsInternal(this, dt, frame) — physics integration

Address: 0x00510700 (line 278460) Signature: void __thiscall CPhysicsObj::UpdatePhysicsInternal(CPhysicsObj* this, float dt, Frame* frame)

What it does (plain English)

Runs Euler integration of m_velocityVector + m_accelerationVector + m_omegaVector on the supplied frame. This is what advances physics-driven motion (gravity falls, jump arcs, knockbacks). Walking locomotion does NOT flow through here.

Order of operations

#	Line	What happens
1	278463-278467	Compute var_28 = velocity.x² + velocity.y² + velocity.z²
2	278473	If var_28 > 0 (i.e. velocity is non-zero, the FP comparison machinery checks this):
2a	278475-278487	If var_28 > 50² (terminal speed cap), normalize velocity and scale to magnitude 50.
2b	278490	calc_friction(this, dt, var_28) — friction adjusts velocity
2c	278491-278502	If var_28 < 0.0625 + 0.0002 (≈ 0.25² threshold), zero velocity (deadband).
2d	278505-278511	Euler translation: frame.origin += dt * velocity + 0.5 * dt² * acceleration (per-axis)
3	278513-278518	else if (movement_manager == 0 && transient_state & 2) — clear 0x80 from transient_state
4	278521-278523	Velocity step: velocity += dt * acceleration
5	278524-278528	Omega rotation: build var_18.. = dt * omegaVector, then Frame::grotate(frame, &dtOmega) (global-frame rotate by axis-angle, sin/cos applied to half-angle, quat multiply)

Verbatim retail snippets

// Line 278505-278511 — translation update (per axis)
float var_20 = (acceleration.y * 0.5f) * dt * dt;
... // similar for x, z
frame->origin.x += (dt * velocity.x) + (acceleration.x * 0.5f * dt * dt);
frame->origin.y += (dt * velocity.y) + var_20;
frame->origin.z += (dt * velocity.z) + (acceleration.z * 0.5f * dt * dt);

// Line 278521-278523 — velocity step (always runs, even when velocity was 0)
velocity.x += dt * acceleration.x;
velocity.y += dt * acceleration.y;
velocity.z += dt * acceleration.z;

// Line 278524-278528 — angular rotation (always runs)
Vector3 dtOmega = dt * omegaVector;
Frame::grotate(frame, &dtOmega);

Critical observations

1. Translation step is gated — only runs when velocity² > 0. For a walking remote with m_velocityVector == 0, this entire block is skipped. The animation's baked velocity (already in frame.origin from apply_physics + combine) is preserved.
2. Velocity step always runs — even when initial velocity was zero, gravity (acceleration.z = PhysicsGlobals::gravity when state[1] & 4, i.e. Gravity) accumulates velocity.z -= 9.8 * dt per tick.
3. Omega step always runs — uses m_omegaVector (NOT sequencer omega). This is for knockback spin / scripted rotation; sequencer omega is consumed inside apply_physics.
4. Zero-velocity deadband at |v| < 0.25 applies AFTER friction. Friction-decayed velocity below 0.25 m/s snaps to 0.

---

5. CPhysicsObj::transition(this, fromPos, toPos, flags) — collision sweep

Address: 0x00512dc0 (line 280904) Signature: const CTransition* __thiscall CPhysicsObj::transition(CPhysicsObj* this, const Position* fromPos, const Position* toPos, int32_t flags)

What it does

Allocates a CTransition (collision-sweep workspace), initializes it with the object's spheres + path (fromPos → toPos in cell), tunes "frames stationary fall" from transient_state, calls find_valid_position, cleans up the transition workspace, returns the resolved CTransition* if successful or nullptr if no valid position.

Order of operations

#	Line	What happens
1	280907	CTransition* result = CTransition::makeTransition()
2	280911	init_object(result, this, get_object_info(this, result, flags)) — copies state flags into CTransition::object_info
3	280915-280936	If has spheres → init_sphere(result, count, spheres, scale); else → init_sphere(result, 1, &dummy_sphere, 1.0)
4	280939	init_path(result, this->cell, fromPos, toPos) — sets up SpherePath
5	280940-280947	Set frames_stationary_fall from transient_state high bits: 0x40→3, 0x20→2, 0x10→1
6	280949	int valid = CTransition::find_valid_position(result) — runs full sweep
7	280950	cleanupTransition(result) — releases sphere copies / scratch state
8	280952-280953	Return result if valid != 0, else 0

Side effects on caller

The returned CTransition* carries:

• result->sphere_path.curr_pos — final resolved Position (cell + frame)
• result->sphere_path.curr_cell — final cell (may differ from start, may be null = lost)
• result->collision_info.contact_plane — current ground plane
• result->collision_info.contact_plane_valid, contact_plane_is_water, contact_plane_cell_id
• result->collision_info.sliding_normal, sliding_normal_valid
• result->cell_array — list of cells visited during the sweep

These all flow into SetPositionInternal.

---

6. CPhysicsObj::SetPositionInternal(this, transition) — commit

Address: 0x00515330 (line 283399) Signature: int32_t __thiscall CPhysicsObj::SetPositionInternal(CPhysicsObj* this, const CTransition* arg2)

What it does

Commits the transition's resolved position back into the physics object: copies the final frame, updates cell membership, updates contact plane / sliding normal / transient_state walkable bits, recalculates acceleration based on the new ground state, and fires handle_all_collisions for any contact reports.

Order of operations

#	Line	What happens
1	283402-283403	Capture transient_state, curr_cell
2	283405-283410	If curr_cell == nullptr (lost): prepare_to_leave_visibility + store_position(curr_pos) + GotoLostCell + clear transient_state & 0x80
3	283414-283456	If same cell: update m_position.objcell_id and child cell ids; else change_cell(curr_cell)
4	283458	set_frame(this, &curr_pos.frame) — commit final frame to m_position.frame and propagate to part array
5	283459-283464	Copy contact_plane (N + d) and contact_plane_cell_id
6	283465-283473	If contact_plane_valid → transient_state |= 1 (Contact); else &= ~1
7	283474	calc_acceleration(this) — reset to gravity or zero based on Contact + Gravity flags
8	283475-283483	If contact_plane_is_water → transient_state |= 8; else &= ~8
9	283485-283510	If now Contact: branch on contact_plane.N.z >= PhysicsGlobals::floor_z → set_on_walkable(true) else (false). Else (not on contact): clear transient_state & 2 (Active) — call MovementManager::LeaveGround if was active — then calc_acceleration again.
10	283512-283523	Copy sliding_normal + flag bit 4 (SlidingNormal)
11	283524	handle_all_collisions(this, &collision_info, oldContact, oldActive) — fires Weenie collision callbacks
12	283526-283538	If has cell + state has 0x10000 (HasPhysicsBSP) → calc_cross_cells; else → remove_shadows_from_cells + add_shadows_to_cells(&cell_array)

floor_z constant

PhysicsGlobals::floor_z is the cosine of the steepest walkable angle. Standard retail value is around 0.66417414 (≈ cos 49°). The check at line 283501-283506 is "is this slope steep enough that we are NOT on walkable ground?" — if contact_plane.N.z < floor_z, the slope is too steep, set OnWalkable = false.

---

7. Frame::combine(out, a, b) — frame composition

Address: 0x005122e0 (line 280355) Signature: void Frame::combine(Frame* out, const Frame* a, const Frame* b)

What it does (plain English)

Composes two frames: out = a then b in the sense of "apply a's transform, then add b in a's local space."

out.origin = a.origin + a.m_fl2gv * b.origin    // rotate b's translation by a's matrix, add to a's origin
out.quaternion = a.quaternion * b.quaternion    // standard quat multiply

The matrix m_fl2gv is the local-to-global rotation matrix, populated by Frame::cache from the quaternion. m_fl2gv[0..8] is column-major (with [0]/[3]/[6] = row 0, etc., based on the index pattern at line 280358).

Side effects

• out.m_fOrigin, out.qw/qx/qy/qz ← computed
• out.m_fl2gv ← repopulated (via set_rotate which calls cache)

Important: combine reads a.m_fl2gv directly

If a.m_fl2gv is stale (quaternion changed without Frame::cache), combine produces garbage translation. This is why Frame::cache(&var_40) is called explicitly at line 280827 in UpdatePositionInternal before any operation that reads the matrix.

---

8. Frame::cache(this) — quat → rotation matrix

Address: 0x00534df0 (line 319353) Signature: void __fastcall Frame::cache(Frame* this)

What it does

Populates m_fl2gv[0..8] (a 3×3 rotation matrix) from qw/qx/qy/qz. Standard quat-to-matrix formula:

m_fl2gv[0] = 1 - 2*(qy² + qz²)     m_fl2gv[3] = 2*(qx*qy - qw*qz)     m_fl2gv[6] = 2*(qx*qz + qw*qy)
m_fl2gv[1] = 2*(qx*qy + qw*qz)     m_fl2gv[4] = 1 - 2*(qx² + qz²)     m_fl2gv[7] = 2*(qy*qz - qw*qx)
m_fl2gv[2] = 2*(qx*qz - qw*qy)     m_fl2gv[5] = 2*(qy*qz + qw*qx)     m_fl2gv[8] = 1 - 2*(qx² + qy²)

Why it matters

Every time the quaternion changes (e.g., omega-rotate or set_rotate), the cached matrix MUST be refreshed before another combine/localtoglobal reads it. Retail's Frame::set_rotate calls Frame::cache internally; manual quaternion edits do not.

---

9. CPhysicsObj::set_frame(this, frame) — commit frame to object

Address: 0x00514090 (line 282139)

What it does

Validates the frame, copies it to this->m_position.frame, propagates to part_array (unless state[1] & 0x10 = Particle flag), and updates children.

Order

1. Frame::operator=(local_var_40, arg2) — copy
2. If IsValid(local) == 0 && IsValidExceptForHeading(local) != 0 → reset rotation to identity (origin preserved). This protects against NaN quats from numerical drift.
3. Frame::operator=(this->m_position.frame, local) — final assign
4. If NOT (state[1] & 0x10) → CPartArray::SetFrame(part_array, &this->m_position.frame)
5. UpdateChildrenInternal(this) — recurse to attached children

Why a SEPARATE local copy?

So the validity-fix can run before committing. If we wrote directly into m_position.frame and then noticed it's invalid, we'd have already corrupted the live state.

---

10. PositionManager::adjust_offset(pm, frame, dt) — three-manager pass

Address: 0x00555190 (line 352090)

What it does

Calls adjust_offset(frame, dt) on each of three optional managers in order:

1. InterpolationManager — smooths network-bursty position deltas
2. StickyManager — locks position to a target object (e.g., aetheria attaches)
3. ConstraintManager — clamps within a region

Each is null-checked. For most remotes, all three are null, so this is a no-op.

---

11. CPartArray::Update(arr, dt, frame) & CSequence::update

Addresses: 0x00517db0 (CPartArray::Update, line 285883), 0x00525b80 (CSequence::update, line 302402)

What they do

CPartArray::Update is a thin wrapper that calls CSequence::update(&this->sequence, dt, frame).

CSequence::update:

• If anim_list.head_ != 0: calls update_internal (advance cursor through anim chain) AND apricot (drop completed anims). Apricot does NOT call apply_physics. The local frame writes happen INSIDE update_internal via its own apply_physics calls.
• Else (no anims queued): calls apply_physics(this, frame, dt, dt) directly with the current sequence.velocity / sequence.omega.

This means: even with no animation queued, the sequencer keeps emitting baked velocity (the cycle's resting motion). This is how a stationary idle character could still tick velocity.

What CPartArray::UpdateParts is NOT

CPartArray::UpdateParts(arr, frame) at 0x005190f0 (line 287281) is a separate function that COMPOSES per-part frames from the current AnimFrame.frame array against the parent frame argument. It is called from a different path — CPhysicsObj::UpdateChild and CPartArray::SetFrame — not from the per-tick UpdateObjectInternal pipeline.

---

12. Compact pseudocode of the whole pipeline

void CPhysicsObj::UpdateObjectInternal(float dt) {
    if (transient_state high bit set /* dormant */) {
        ParticleManager::UpdateParticles();
        ScriptManager::UpdateScripts();
        return;
    }

    if (cell == 0) return;

    if (transient_state[1] & 1) set_ethereal(0, 0);
    jumped_this_frame = 0;

    Frame candidate = identity;  Frame::cache(&candidate);

    UpdatePositionInternal(dt, &candidate);
    // After this: candidate = m_position.frame ⊗ animRoot ⊗ posMgrAdjust ⊗ physicsEuler

    if (has_collision_sphere) {
        if (state[1] & 1)
            Frame::set_vector_heading(&candidate, dir_of_translation);
        else if ((state & ScaledVel) && !is_zero(m_velocityVector))
            Frame::set_heading(&candidate, get_heading(m_velocityVector));

        Position toPos = { vtable=Position, frame=candidate, cell=current };
        CTransition* t = transition(&m_position, &toPos, 0);
        if (t == null) {
            set_frame(&candidate);  // fall back: commit unswept candidate
            cached_velocity = (0,0,0);
        } else {
            cached_velocity = (t.curr_pos - m_position) / dt;
            SetPositionInternal(t);  // commits curr_pos, updates contact plane, walkable, etc.
        }
    } else {
        // No sphere — commit candidate directly.
        if (movement_manager == null && (transient_state & 2))
            transient_state &= ~0x80;
        set_frame(&candidate);
        cached_velocity = (0,0,0);
    }

    DetectionManager::CheckDetection();
    TargetManager::HandleTargetting();
    MovementManager::UseTime();
    CPartArray::HandleMovement();
    PositionManager::UseTime();
    ParticleManager::UpdateParticles();
    ScriptManager::UpdateScripts();
}

void CPhysicsObj::UpdatePositionInternal(float dt, Frame* outFrame) {
    Frame local = identity; Frame::cache(&local);

    if (!(state[1] & 0x40 /* Frozen */)) {
        if (part_array)
            CPartArray::Update(part_array, dt, &local);
            // → CSequence::apply_physics writes:
            //     local.origin += dt * sequence.velocity
            //     Frame::rotate(&local, dt * sequence.omega)
    }

    if (position_manager)
        PositionManager::adjust_offset(position_manager, &local, dt);

    Frame::combine(outFrame, &m_position.frame, &local);
    // outFrame.origin = m_position.origin + m_position.m_fl2gv * local.origin
    // outFrame.quat   = m_position.quat * local.quat

    if (!(state[1] & 0x40))
        UpdatePhysicsInternal(dt, outFrame);

    process_hooks();
}

void CPhysicsObj::UpdatePhysicsInternal(float dt, Frame* frame) {
    float v2 = velocity.x² + velocity.y² + velocity.z²;
    if (v2 > 0) {
        if (v2 > 50²) {           // terminal speed cap
            normalize(velocity); velocity *= 50;
        }
        calc_friction(dt, v2);
        if (v2 < 0.25² + ε)        // deadband
            velocity = 0;
        // Euler position step
        frame.origin += dt * velocity + 0.5 * dt² * acceleration;
    } else if (movement_manager == null && (transient_state & 2)) {
        transient_state &= ~0x80;
    }

    velocity += dt * acceleration;          // ALWAYS runs (gravity accumulation)
    Vector3 dtOmega = dt * omegaVector;
    Frame::grotate(frame, &dtOmega);        // ALWAYS runs
}

---

13. Cross-reference: acdream GameWindow.cs ~6428+

What acdream does today (legacy / non-env-var path)

// Lines 6488-6650 (annotated):
1. Force OnWalkable + Contact + Active.
2. apply_current_movement → body.Velocity = sequencer.GetStateVelocity (rotated by Orientation).
3. body.Omega = 0.
4. If ObservedOmega non-zero: integrate Orientation manually (from server-derived rate).
5. body.calc_acceleration().
6. body.UpdatePhysicsInternal(dt).         ← Euler-step on body.Position
7. ResolveWithTransition(prePos, postPos)  ← BSP/terrain sweep
8. Body.Position = resolveResult.Position.

Mismatches with retail

#	Retail	acdream	Impact
1	Locomotion via sequencer baked velocity consumed by CSequence::apply_physics (writes to local frame)	Locomotion via body.Velocity = apply_current_movement output consumed by Euler step in UpdatePhysicsInternal	acdream double-counts: sequencer gets ticked AND body.Velocity is set. If both contribute, motion overshoots. If only the body path runs (sequencer Advance returns frames but doesn't drive translation), animation plays without baked-velocity contribution.
2	Order: anim-root → posMgr-offset → combine with world pose → physics Euler on composed frame → collision sweep on composed frame	Order: apply_current_movement (sets velocity) → manual omega-integrate orientation → physics Euler on body (independent of frame composition) → collision sweep	Acceleration term 0.5 * dt² * a is applied to body.Position, but in retail it's applied to the post-combine frame. For grounded remotes (acceleration ≈ 0) the difference is small; for jumping/falling remotes the half-accel term is in the wrong reference frame.
3	m_velocityVector for walking remotes ≈ 0	body.Velocity for walking remotes = world-rotated locomotion vector (e.g. ~4 m/s)	Direct port question: should body.Velocity be zero for grounded locomotion, with motion coming entirely from sequencer baked velocity? Yes per retail. This is the L.3 fix.
4	Frame::grotate always runs in UpdatePhysicsInternal using m_omegaVector	body.Omega = 0 to skip integration; manual quat rotate from ObservedOmega outside body	acdream's manual path is functionally equivalent provided ObservedOmega is the right rate; retail's path uses the body's own omega field. Replacing acdream's manual integration with body.Omega = derived_rate and letting UpdatePhysicsInternal do grotate would be more retail-faithful.
5	Velocity-deadband at |v| < 0.25 and terminal-cap at |v| < 50 are inside UpdatePhysicsInternal	Not implemented (or implemented at higher level)	Minor; only matters for friction-decayed bodies and ragdoll-speed clamps.
6	Translation step is GATED on velocity² > 0	acdream Euler-integrates unconditionally	Means a stationary remote with non-zero acceleration (gravity) gets a Z-step in acdream that retail would skip until velocity itself becomes non-zero (gravity makes velocity.z negative on the next velocity-update step). 1-tick lag in retail; immediate in acdream.
7	set_frame validates the frame and resets-to-identity if quat is invalid	acdream commits without explicit IsValid check	NaN-quat protection missing; can't be triggered in normal play but a single packet-decode bug could stick a remote with a corrupted orientation forever.
8	Anim-frame combine + posMgr-offset happen before physics integration	acdream skips the local-frame compose entirely; physics on body.Position is independent	This is THE structural mismatch driving L.3.

Why the L.2 PositionManager attempt regressed (per CLAUDE.md note)

The note says:

the env-var path drops the per-tick collision sweep (ResolveWithTransition) that the default path retains, causing a visible "staircase" pattern when remotes run up/down slopes

Retail does NOT drop ResolveWithTransition — transition() runs every tick after UpdatePositionInternal builds the candidate. The bug was integrating PositionManager but skipping transition()/SetPositionInternal in the env-var branch. Retail's structure makes both mandatory.

The shape L.3 should produce

void TickRemote(rm, dt) {
    // 1. Build candidate frame in local space.
    Frame local = Frame.Identity;
    sequencer.ApplyPhysicsToFrame(ref local, dt);   // ← retail apply_physics: writes baked velocity & omega
    positionMgr.AdjustOffset(ref local, dt);        // null for normal remotes; placeholder for L.4

    // 2. Compose with world pose.
    Frame candidate = Frame.Combine(rm.Body.WorldFrame, local);

    // 3. Physics integration on the composed frame (gravity, knockback, terminal cap).
    rm.Body.UpdatePhysicsInternal(dt, ref candidate);   // mutates m_velocity, candidate.origin (only if v² > 0), candidate.quat (always)

    // 4. Collision sweep candidate → resolved.
    if (rm.Body.HasCollisionSphere && candidate.Origin != rm.Body.Position) {
        var transition = _physicsEngine.Transition(rm.Body.WorldPos, candidate, rm.CellId);
        if (transition == null) {
            rm.Body.SetFrame(candidate);    // fall back to unswept candidate
            rm.CachedVelocity = Vector3.Zero;
        } else {
            rm.CachedVelocity = (transition.CurrPos - rm.Body.WorldPos) / dt;
            rm.Body.SetPositionFromTransition(transition);  // commits frame, contact_plane, walkable, sliding_normal
        }
    } else {
        rm.Body.SetFrame(candidate);
    }

    // 5. Per-tick managers.
    rm.DetectionManager?.Check();
    rm.TargetManager?.Tick();
    rm.MovementManager?.UseTime();
    rm.PartArray.HandleMovement();
    rm.PositionManager?.UseTime();
    rm.ParticleManager?.Update();
    rm.ScriptManager?.Update();
}

The key insight: for walking remotes, m_velocityVector stays zero, locomotion enters via the sequencer's apply_physics writing into local, and Frame::combine rotates that body-local vector into world space using the current orientation. This matches CSequence::apply_physics's documented behavior and matches what we observe — animation cycles produce locomotion because the cycle's MotionData has baked velocity, not because the network hands us a velocity.

---

14. Open questions for L.3 implementation

1. Where does omega come from for remotes? Retail's m_omegaVector is set by CMotionInterp::DoInterpretedMotion via the cycle's MotionData (TurnLeft/TurnRight bake omega). Our local player path already has this; verify the remote path reads from the same source instead of ObservedOmega (which is server-derived and lossy).

2. Does CSequence::apply_physics always run, even on idle? Re-reading line 302413-302419: if anim_list.head_ == 0 AND arg3 != 0, apply_physics runs with the current sequence.velocity / sequence.omega. Idle cycles have zero baked velocity → apply_physics is a no-op. So idle remotes get no spurious motion.

3. Frame.IsValid check in SetFrame: minor robustness item. Worth adding when porting set_frame.

4. Friction: calc_friction gets called inside UpdatePhysicsInternal whenever velocity² > 0. We don't currently port friction. For grounded velocity-driven motion (knockbacks) it matters; for animation-driven motion (m_velocityVector ≈ 0) it doesn't.

5. PhysicsBody.update_object's MinQuantum gate: GameWindow.cs ~6633 has a long comment explaining why it bypasses update_object and calls UpdatePhysicsInternal directly. Retail's UpdateObjectInternal is the entry; our top-level entry mirrors that. The 30 Hz quantum gate is in retail (see MinQuantum=1/30s); retail addresses it by NOT subticking — UpdateObjectInternal is called at the engine tick rate (~30 Hz for retail's render loop, see CLAUDE.md retail debugger notes). Our 60 Hz tick may want a sub-step gate or to halve dt per accumulated frame to match retail integration cadence.