acdream/docs/research/2026-05-04-l3-port/10-vector-update-jump.md

# L.3 — VectorUpdate (0xF74E) handler chain + jump pseudocode

Source: `docs/research/named-retail/acclient_2013_pseudo_c.txt` (Sept 2013 EoR PDB-named).

All retail line numbers below refer to that file (`acclient_2013_pseudo_c.txt`).

---

## 1. `CM_Physics::DispatchSB_VectorUpdate` — packet → handler

**Address:** `0x006acd20` (line 692119)

```
006acd20  enum NetBlobProcessedStatus CM_Physics::DispatchSB_VectorUpdate(
              class SmartBox* arg1,
              class NetBlob* arg2)
{
    NetBlob* ebx = arg2;
    if (ebx == 0 || arg1 == 0) return 3;
    uint8_t* buf_     = ebx->buf_;       // body bytes
    uint32_t bufSize_ = ebx->bufSize_;
    if (*(uint32_t*)buf_ != 0xf74e) return 3;          // line 692130 — opcode gate

    uint32_t guid    = *(uint32_t*)(buf_ + 4);          // line 692136 — object id
    arg2 = &buf_[8];

    Vector3 velocity;                                    // line 692139
    AC1Legacy::Vector3::UnPack(&velocity, &arg2, ...);

    Vector3 omega;                                       // line 692141
    AC1Legacy::Vector3::UnPack(&omega, &arg2, ...);

    PhysicsTimestampPack ts;                             // line 692143
    PhysicsTimestampPack::UnPack(&ts, &arg2, ...);

    return SmartBox::HandleVectorUpdate(arg1, ebx, guid, &velocity, &omega, &ts);
}
```

Wire layout: `[opcode:u32 0xF74E][guid:u32][velocity:Vector3][omega:Vector3][ts:PhysicsTimestampPack]`.
The PhysicsTimestampPack carries `ts1` (port-event sequence) and `ts2` (vector
event sequence, used in DoVectorUpdate as `update_times[3]`).

---

## 2. `SmartBox::HandleVectorUpdate` — sequence gate

**Address:** `0x00453480` (line 92195)

```
00453480  enum NetBlobProcessedStatus SmartBox::HandleVectorUpdate(
              SmartBox* this,
              NetBlob* arg2,           // raw blob (re-queued on early)
              uint32_t  arg3,          // guid
              Vector3 const* arg4,     // velocity (world)
              Vector3 const* arg5,     // omega (world)
              PhysicsTimestampPack const* arg6)
{
    int32_t ebp = arg6->ts2;            // vector event ts (line 92199)
    int32_t esi = arg6->ts1;            // port event ts (line 92201)
    CPhysicsObj* obj = CObjectMaint::GetObjectA(this->m_pObjMaint, arg3);

    if (obj != 0)
    {
        int32_t ebx = obj->update_times[8];          // last-seen port-event ts
        // Signed compare across 16-bit wrap (lines 92210-92218 standard
        // wrap-aware "newer?" macro): if ebx == esi → in sync, dispatch.
        if (ebx == esi)
        {
            SmartBox::DoVectorUpdate(this, obj, arg4, arg5, ebp);
            return 1;     // PROCESSED
        }
        if (ebx != esi)
            return 2;     // OUT_OF_ORDER (newer port event hasn't arrived)
    }

    // Object not yet known — queue the blob for later.
    CObjectMaint::QueueBlobForObject(this->m_pObjMaint, arg3, arg2);
    return 4;             // DEFERRED
}
```

Note: VectorUpdate is gated against `update_times[8]` (the
**port-event timestamp**), not `update_times[3]`. This means a VectorUpdate
will *not* be applied unless the latest 0xF748 PortalCellUpdate / position
event has already been processed. This is how retail keeps the velocity
write coherent with the position the server intended.

---

## 3. `SmartBox::DoVectorUpdate` — the actual write

**Address:** `0x004521c0` (line 91208)

```
004521c0  void SmartBox::DoVectorUpdate(
              SmartBox* this,
              CPhysicsObj* arg2,
              Vector3 const* arg3,    // velocity (world)
              Vector3 const* arg4,    // omega (world)
              uint16_t arg5)          // ts2 (vector-event ts)
{
    int32_t esi = arg2->update_times[3];      // last vector ts on object
    int32_t edi = arg5;
    // Wrap-aware "edi newer than esi" check (lines 91217-91227).
    // The decompiler's flag arithmetic collapses to 0 here; the real
    // gate is `edi != esi`.
    if (edi != esi)
    {
        arg2->update_times[3] = edi;                   // line 91229

        if (arg2 != this->player)
        {
            CPhysicsObj::set_velocity(arg2, arg3, 1);  // line 91233 — REMOTE
            CPhysicsObj::set_omega   (arg2, arg4, 1);
        }
        else if (this->cmdinterp->vtable->UsePositionFromServer() != 0)
        {
            CPhysicsObj::set_velocity(arg2, arg3, 1);  // line 91238 — LOCAL only when server-driven
            CPhysicsObj::set_omega   (arg2, arg4, 1);
        }
    }
}
```

**Critical observations** (relevant to acdream's K-fix15 question):

1. **Retail does NOT set the Gravity flag here.** It does not touch
   `state` at all. It only writes `m_velocityVector` (via set_velocity)
   and `m_omegaVector` (via set_omega). Gravity is already-on for
   creatures by default (set when the body enters the world via
   `enter_default_state` → `LeaveGround`); VectorUpdate does not
   need to re-set it.
2. **Retail does NOT clear Contact / OnWalkable here.** The
   transient-state bits stay whatever they were. Clearing them is the
   job of `set_on_walkable(false)` which fires from
   `CMotionInterp::jump` (local jumps only), or from the next physics
   tick when the sphere-sweep finds no contact plane.
3. **Retail just writes the velocity.** The next per-tick
   `CPhysicsObj::UpdateObjectInternal` reads `m_velocityVector`,
   adds gravity acceleration (computed by `calc_acceleration`),
   integrates position, and the sphere-sweep handles contact.

So acdream's `OnLiveVectorUpdated` (GameWindow.cs:3246-3304) is doing
*more* than retail: it also clears Contact/OnWalkable + sets Gravity
when v.Z > 0.5. The reason this is necessary in acdream is that
acdream's per-tick path (`UpdatePhysicsInternal`) gates gravity on
`!OnWalkable` rather than reading the `state.Gravity` bit — see
`PhysicsBody.calc_acceleration` and the per-tick velocity integration.
Retail's per-tick reads `state & GRAVITY` (always set for creatures)
AND `transient_state & (CONTACT | ON_WALKABLE)` to short-circuit
acceleration to zero (see calc_acceleration below).

`set_velocity(arg3, /*arg3=*/1)` clamps |v| ≤ 50 (MaxVelocity) and
sets `transient_state.Active`. The `arg3=1` flag distinguishes
network-source (1) from local-source (0); only used to gate
update_time refresh.

---

## 4. `CPhysicsObj::set_velocity`

**Address:** `0x005113f0` (line 279361)

```
005113f0  void CPhysicsObj::set_velocity(
              CPhysicsObj* this, Vector3 const* arg2, int32_t arg3)
{
    if (Vector3::operator!=(arg2, &this->m_velocityVector) != 0)   // line 279364
    {
        this->m_velocityVector = *arg2;                             // 279366-368
        // Magnitude clamp to 50 (MaxVelocity squared = 2500).
        long double mag2 = vx*vx + vy*vy + vz*vz;                   // 279372
        if (50f*50f < mag2)                                         // 279377
        {
            AC1Legacy::Vector3::normalize(&this->m_velocityVector); // 279383
            this->m_velocityVector.x *= 50f;                        // 279384
            this->m_velocityVector.y *= 50f;
            this->m_velocityVector.z *= 50f;
        }
        this->jumped_this_frame = 1;                                // 279389 ★
    }

    // Set Active transient flag (bit 7 = 0x80) when state.Gravity bit not set.
    if ((this->state & 1) == 0)                                     // line 279392 ★
    {
        if (this->transient_state >= 0)
        {
            this->update_time = Timer::cur_time;                    // 279398-399
        }
        this->transient_state |= 0x80;                              // 279402 — Active
    }
}
```

Two side effects beyond the velocity write:
- **`jumped_this_frame = 1`** (offset +0x9C). Skips contact resolution
  this frame; gives gravity room to lift the body off the floor before
  the sweep clamps it back. Critical for jump start — without this, the
  +Z velocity gets immediately killed by the floor sweep on frame N+1.
- **`transient_state |= Active (0x80)`**. Marks the object for
  per-tick processing (UpdateObjectInternal early-outs if Active is
  not set).

Note line 279392: `(this->state & 1)` is testing bit 0, which is the
**Static** flag, not Gravity. Retail only blocks the Active bit-set
on static objects.

---

## 5. `CPhysicsObj::set_local_velocity`

**Address:** `0x005114d0` (line 279408)

```
005114d0  void CPhysicsObj::set_local_velocity(
              CPhysicsObj* this, Vector3 const* arg2, int32_t arg3)
{
    // Multiply local-frame velocity by orientation matrix (frame.m_fl2gv,
    // 9 floats at offset 0x...). worldX = m_fl2gv[0]*lx + m_fl2gv[3]*ly + m_fl2gv[6]*lz
    Vector3 worldVel = orientation × arg2;
    CPhysicsObj::set_velocity(this, &worldVel, arg3);
}
```

Used by `CMotionInterp::LeaveGround` to convert the body-local launch
vector (forward/right/up relative to facing) into a world vector.

---

## 6. `OBJECTINFO::kill_velocity` (clear_velocity equivalent)

**Address:** `0x0050cfe0` (line 274467)

```
0050cfe0  void OBJECTINFO::kill_velocity(OBJECTINFO* this)
{
    CPhysicsObj* obj = this->object;
    Vector3 zero = (0, 0, 0);
    CPhysicsObj::set_velocity(obj, &zero, 0);    // arg3=0 (local source)
}
```

Retail does not have a separate `clear_velocity` — it just zeros via
set_velocity. Called from collision handlers when a wall hit kills
forward motion (lines 272567, 273237).

---

## 7. `CMotionInterp::LeaveGround` — outbound jump trigger

**Address:** `0x00528b00` (line 306022)

```
00528b00  void CMotionInterp::LeaveGround(CMotionInterp* this)
{
    if (!this->physics_obj) return;

    // Creature gate: only run for creatures (or when no weenie).
    CWeenieObject* w = this->weenie_obj;
    bool isCreature = w == 0 ? true : w->vtable->IsCreature();
    if (!(w == 0 || isCreature)) return;

    CPhysicsObj* po = this->physics_obj;
    // Only if state.Gravity bit set (state & 4 — line 306037).
    if ((po->state & 4) == 0) return;                  // ★ Gravity gate

    Vector3 leaveVel;                                  // line 306039
    CMotionInterp::get_leave_ground_velocity(this, &leaveVel);
    CPhysicsObj::set_local_velocity(po, &leaveVel, 1); // line 306041

    this->standing_longjump = 0;                       // 306043
    this->jump_extent       = 0f;                      // 306044 ★ extent reset

    CPhysicsObj::RemoveLinkAnimations(po);             // 306045
    CMotionInterp::apply_current_movement(this, 0, 0); // 306046
}
```

**Order matters:** `get_leave_ground_velocity` is called BEFORE
`jump_extent` is zeroed. After LeaveGround returns, calling
`get_jump_v_z()` returns 0 (because the extent gate at the top
fires). acdream's `PlayerMovementController` correctly captures
`jumpVz` before calling `LeaveGround` for that reason
(PlayerMovementController.cs:440).

LeaveGround does NOT clear Contact / OnWalkable — that already
happened upstream in `CMotionInterp::jump` via
`CPhysicsObj::set_on_walkable(po, 0)` (line 305811).

---

## 8. `CMotionInterp::HitGround` — landing trigger

**Address:** `0x00528ac0` (line 305996)

```
00528ac0  void CMotionInterp::HitGround(CMotionInterp* this)
{
    if (!this->physics_obj) return;

    CWeenieObject* w = this->weenie_obj;
    bool isCreature = w == 0 ? true : w->vtable->IsCreature();
    if (!(w == 0 || isCreature)) return;

    CPhysicsObj* po = this->physics_obj;
    if ((po->state & 4) == 0) return;                  // Gravity gate

    CPhysicsObj::RemoveLinkAnimations(po);             // 306013
    CMotionInterp::apply_current_movement(this, 0, 0); // 306014 — re-pose
}
```

**HitGround does NOT touch velocity.** It only clears the link-anim
and re-applies the current motion (which routes back through
`apply_current_movement → get_state_velocity → set_local_velocity`,
which writes the new ground velocity back to the body).

---

## 9. `MovementManager::HitGround` / `LeaveGround` — wrappers

**HitGround:** `0x00524300` (line 300425)
**LeaveGround:** `0x00524320` (line 300444)

```
00524300  void MovementManager::HitGround(MovementManager* this)
{
    if (this->motion_interpreter)
        CMotionInterp::HitGround(this->motion_interpreter);
    if (this->moveto_manager)
        MoveToManager::HitGround(this->moveto_manager);
}
```

LeaveGround mirrors this. These are the public entry points; the
**caller is `CPhysicsObj::set_on_walkable`**.

---

## 10. `CPhysicsObj::set_on_walkable` — the trigger source

**Address:** `0x00511310` (line 279287)

```
00511310  void CPhysicsObj::set_on_walkable(CPhysicsObj* this, int32_t arg2)
{
    uint32_t ts = this->transient_state;
    uint32_t newTs = (arg2 == 0) ? (ts & ~0x2) : (ts | 0x2);
    this->transient_state = newTs;

    if ((ts & 0x2) == 0)                  // was NOT on-walkable
    {
        if (arg2 != 0)                    // → becoming on-walkable
        {
            if (this->movement_manager)
                MovementManager::HitGround(this->movement_manager);   // ★ LANDING
        }
    }
    else if (arg2 == 0)                   // was on-walkable, becoming off
    {
        if (this->movement_manager)
        {
            MovementManager::LeaveGround(this->movement_manager);     // ★ LAUNCH
            CPhysicsObj::calc_acceleration(this);
            return;
        }
    }
    CPhysicsObj::calc_acceleration(this);
}
```

So the **edge detector** lives here:
- `OnWalkable: 0 → 1` fires `HitGround` (landing).
- `OnWalkable: 1 → 0` fires `LeaveGround` (launch).

`set_on_walkable` itself is called from two places:

1. **`CMotionInterp::jump`** (line 305811): `set_on_walkable(po, 0)` —
   forces the launch edge.
2. **`CPhysicsObj::set_frame`** ground-floor sphere-sweep result
   (lines 283474-283509). After the per-tick sphere-sweep stores its
   resulting collision_info, this block walks contact_plane.N.z vs
   `PhysicsGlobals::floor_z` (the cosine of max walkable slope, ≈
   0.66 → 49°). If the contact plane is steep enough, `set_on_walkable(0)`;
   if walkable, `set_on_walkable(1)`. **This is how landing detection
   fires automatically in retail** — the per-tick sweep finds a walkable
   surface under the body, set_on_walkable flips 0→1, HitGround fires.

So the answer to "how does retail's HitGround fire" is: **from
`set_frame` (called by the per-tick sphere sweep)**, not from a
separate trigger. The sweep computes the new contact plane; if it
classifies as walkable, the edge fires HitGround.

---

## 11. `CMotionInterp::jump` — the entry point

**Address:** `0x00528780` (line 305792)

```
00528780  uint32_t CMotionInterp::jump(CMotionInterp* this, float arg2, int32_t* arg3)
{
    CPhysicsObj* po = this->physics_obj;
    if (po == 0) return 8;

    CPhysicsObj::interrupt_current_movement(po);             // 305800
    uint32_t result = CMotionInterp::jump_is_allowed(this, arg2, arg3);
    if (result != 0) {
        this->standing_longjump = 0;                          // 305805
        return result;                                        // failure code
    }

    this->jump_extent = arg2;                                 // 305810 ★ extent
    CPhysicsObj::set_on_walkable(po, 0);                      // 305811 ★ launch
    return 0;
}
```

The launch sequence is:
1. `jump_is_allowed` validates (returns 0 on success).
2. Store extent.
3. `set_on_walkable(false)` → triggers `LeaveGround` via the wrapper
   chain in step 10 above. LeaveGround reads `jump_extent` to compose
   `get_leave_ground_velocity` and writes it via `set_local_velocity`.
4. Returns to caller (PlayerInputControl::Event_Jump_NonAutonomous,
   line 376264) which sends 0xF61C MoveToState + 0xF74E VectorUpdate
   (via Event_Jump → JumpPack).

---

## 12. `CMotionInterp::get_jump_v_z` — vertical component

**Address:** `0x00527aa0` (line 304953)

```
00527aa0  float CMotionInterp::get_jump_v_z(CMotionInterp const* this)
{
    float extent = this->jump_extent;                       // 304957
    if (extent < 0.000199999995f) return 0.0f;              // 304959 (epsilon)
    if (extent > 1.0f) extent = 1.0f;                       // 304968-973 clamp

    CWeenieObject* w = this->weenie_obj;                    // 304975
    if (w == 0) return /* fallback */;                      // returns last-result reg (10.0f from DAT)

    return w->vtable->InqJumpVelocity(extent, ...);         // 304980
}
```

`InqJumpVelocity` is the per-character jump-skill curve. Returns
the actual launch v_z in m/s (e.g. extent=1.0 with jump-skill 300
→ ~7.8 m/s peak from PlayerWeenie).

---

## 13. `CMotionInterp::get_leave_ground_velocity` — full launch vector

**Address:** `0x005280c0` (line 305404)

```
005280c0  void CMotionInterp::get_leave_ground_velocity(
              CMotionInterp* this, Vector3* arg2)
{
    CMotionInterp::get_state_velocity(this, arg2);          // 305408 — XY (body-local)
    arg2->z = CMotionInterp::get_jump_v_z(this);            // 305409+305411

    // If all three components are |x| < 0.0002 (near-zero):
    if (|arg2->x| < eps && |arg2->y| < eps && |arg2->z| < eps)
    {
        // Project current world velocity into body-local frame via the
        // transposed orientation matrix m_fl2gv.
        // (lines 305434-305440)
        arg2->x = m_fl2gv[0]*velX + m_fl2gv[1]*velY + m_fl2gv[2]*velZ;
        arg2->y = m_fl2gv[3]*velX + m_fl2gv[4]*velY + m_fl2gv[5]*velZ;
        arg2->z = m_fl2gv[6]*velX + m_fl2gv[7]*velY + m_fl2gv[8]*velZ;
    }
}
```

The fast-path is the common case: `get_state_velocity` writes (X=strafe,
Y=forward, Z=0); then we overwrite Z with v_z. The fallback only fires
when state-velocity AND jump_v_z are all near zero (e.g. zero-extent
jump while standing still); it preserves residual world velocity.

---

## 14. `CMotionInterp::jump_is_allowed`

**Address:** `0x005282b0` (line 305509)

```
005282b0  uint32_t CMotionInterp::jump_is_allowed(
              CMotionInterp* this, float arg2, int32_t* arg3)
{
    CPhysicsObj* po = this->physics_obj;
    if (po == 0) return 0x24;                               // (no obj) GeneralFail

    // Creature path:
    CWeenieObject* w = this->weenie_obj;
    bool wIsCreature = w ? w->vtable->IsCreature() : true;
    if (w != 0 && !wIsCreature)
    {
        // Non-creature — always allowed-ish, fall through to weenie checks.
        goto label_5282f6;
    }

    // Creature: require Gravity flag set AND grounded (Contact + OnWalkable).
    if ((po->state & 4) == 0) return 0x24;                  // 305561 — no gravity, can't jump
    uint8_t ts = po->transient_state;
    if (!((ts & 0x1) && (ts & 0x2))) return 0x24;           // 305566 — not grounded → 0x24

label_5282f6:
    if (CPhysicsObj::IsFullyConstrained(po)) return 0x47;   // 305524

    // Pending-queue check.
    LListData* head = this->pending_motions.head_;
    uint32_t pendingErr = head ? head->jumpErr : 0;
    if (head == 0 || pendingErr == 0)
    {
        pendingErr = CMotionInterp::jump_charge_is_allowed(this);
        if (pendingErr == 0)
        {
            uint32_t mErr = CMotionInterp::motion_allows_jump(this,
                            this->interpreted_state.forward_command);
            if (mErr != 0) return mErr;
            if (this->weenie_obj == 0) return mErr;        // 0
            // Stamina cost check.
            if (w->vtable->JumpStaminaCost(arg2, arg3) != 0)
                return 0;
            return 0x47;                                    // not enough stamina
        }
    }
    return pendingErr;
}
```

Error codes:
- `0x00` = success
- `0x24` = `CantJumpInAir` / general motion failure
- `0x47` = `CantJumpFromPosition` (constrained, weenie-blocked, or stamina)
- `0x48` = `CantJumpFromMotion` (motion command blocks jump — emote, etc.)
- `0x49` = weenie-blocked (load-down)

---

## 15. `CMotionInterp::contact_allows_move`

**Address:** `0x00528240` (line 305471)

```
00528240  int32_t CMotionInterp::contact_allows_move(
              CMotionInterp const* this, uint32_t arg2)
{
    if (this->physics_obj == 0) return 0;
    // Always allow these "anchor" commands regardless of grounding:
    if (arg2 == 0x40000015 || arg2 == 0x40000011) return 1;  // (305481-482)
    if (arg2 >= 0x6500000d && arg2 <= 0x6500000e) return 1;  // (305478) — sidestep cmds
    // Non-creature → allow.
    CWeenieObject* w = this->weenie_obj;
    if (w != 0 && !w->vtable->IsCreature()) return 1;        // (305490)
    // No gravity → allow.
    if ((this->physics_obj->state & 4) == 0) return 1;       // (305495)
    // Grounded (Contact + OnWalkable) → allow.
    uint8_t ts = this->physics_obj->transient_state;
    if ((ts & 0x1) && (ts & 0x2)) return 1;                  // (305500)
    return 0;
}
```

This is the per-command grounding check. Walk/run only succeed when
grounded; emotes/sidesteps always succeed.

---

## 16. `CPhysicsObj::calc_acceleration` — gravity application

**Address:** `0x00510950` (line 278533)

```
00510950  void CPhysicsObj::calc_acceleration(CPhysicsObj* this)
{
    uint8_t ts = this->transient_state;
    // Grounded: zero accel (and zero omega). Tests Contact && OnWalkable
    // && (state & "Hooked-from-floor" bit). Real semantics: grounded creature
    // gets no gravity acceleration.
    if ((ts & 1) && (ts & 2) && (this->state & 0x???) == 0)
    {
        accel = (0, 0, 0);
        omega = (0, 0, 0);
        return;
    }
    // Gravity flag NOT set: zero accel.
    if ((this->state & 4) == 0)              // line 278549 — Gravity bit (state & 4)
    {
        accel = (0, 0, 0);
        return;
    }
    // Airborne with gravity: apply downward gravity.
    accel = (0, 0, PhysicsGlobals::gravity);  // line 278559 (gravity = -9.8 m/s²)
}
```

So the **state.Gravity bit (0x4)** is what enables gravity application
in retail. It's set when the creature enters the world and stays set;
it does NOT need to be re-set on each jump. Acdream's `OnLiveVectorUpdated`
explicitly setting `State |= Gravity` is defensive — if your remote-tracking
code preserved the bit from the moment the body was created, this would
be a no-op.

---

## 17. State writes during a complete jump arc — answers to the brief

| Phase | What happens | Who writes what |
|---|---|---|
| **Pre-jump** | Standing, OnWalkable=1, Contact=1, Gravity=set, vel=0 | initial state |
| **Player jump start** | `MotionInterp::jump(extent)` succeeds | `jump_extent = extent`; `set_on_walkable(0)` (clears OnWalkable=2 bit) |
| ↳ via set_on_walkable | edge 1→0 fires `MovementManager::LeaveGround` | TransientState OnWalkable bit cleared; calc_acceleration recalcs (now (0,0,-9.8) since !grounded) |
| ↳ via LeaveGround | computes launch vector | `set_local_velocity(leaveVel)` → `set_velocity(worldVel)` writes m_velocityVector + sets Active + sets `jumped_this_frame=1`; clears `jump_extent=0` |
| **Per-tick airborne** | UpdateObjectInternal | reads m_velocityVector, integrates pos += vel·dt + ½·accel·dt²; vel.Z += accel.Z·dt |
| **Mid-arc** | sphere-sweep finds no walkable plane | OnWalkable stays 0 |
| **Server VectorUpdate** | `0xF74E` arrives | Only `m_velocityVector` + `m_omegaVector` overwritten. Contact/OnWalkable/Gravity untouched. |
| **Landing (sweep finds floor)** | `set_frame` block 283474-283509 reclassifies contact_plane | If N.z ≥ floor_z: `set_on_walkable(true)` |
| ↳ edge 0→1 | fires `MovementManager::HitGround` | TransientState OnWalkable bit set; calc_acceleration → (0,0,0); HitGround calls RemoveLinkAnimations + apply_current_movement (which re-poses + writes new ground velocity via get_state_velocity → set_local_velocity) |

**Mid-arc UPs from server:** retail does NOT have a separate "snap" or
"integrate" path. A server PortalCellUpdate (0xF748) during flight will
just write the new position via `CPhysicsObj::SetPositionInternal` (same
sequence-gate logic in `CObjectMaint::QueuePortalCellUpdate`), and the
sphere-sweep that next tick decides if landing happened. The arc is
purely client-integrated; server position events override it
authoritatively when they arrive.

**Cycle transition Falling → Ready/Walk/Run on landing:** retail does NOT
explicitly transition. `HitGround` calls `apply_current_movement` which
re-pushes the existing `interpreted_state.forward_command`. If the player
is still holding W, that's RunForward, and the cycle naturally reverts.
The Falling animation is layered as a link-animation that
`RemoveLinkAnimations` clears at HitGround. (acdream's
`SetCycle(landingCmd)` in GameWindow.cs:3487 is a more explicit
re-pose; equivalent effect.)

---

## 18. Cross-check vs acdream

| acdream method | retail counterpart | Match? |
|---|---|---|
| `MotionInterpreter.jump` (line 691) | `CMotionInterp::jump` 0x00528780 | ✅ matches: jump_is_allowed, JumpExtent, set_on_walkable(false) |
| `MotionInterpreter.get_jump_v_z` (722) | 0x00527aa0 | ✅ matches: epsilon gate, clamp, weenie call |
| `MotionInterpreter.get_leave_ground_velocity` (759) | 0x005280c0 | ✅ matches incl. fallback projection |
| `MotionInterpreter.LeaveGround` (901) | 0x00528b00 | ✅ matches order (vel-before-extent-reset) |
| `MotionInterpreter.HitGround` (924) | 0x00528ac0 | ✅ matches |
| `MotionInterpreter.jump_is_allowed` | 0x005282b0 | ✅ matches |
| `MotionInterpreter.contact_allows_move` | 0x00528240 | ✅ matches |
| `PhysicsBody.set_velocity` (206) | 0x005113f0 | ⚠️ **MISSING `jumped_this_frame = 1`** + missing transient_state.Active gate on `state & 1` (Static) |
| `PhysicsBody.set_local_velocity` (236) | 0x005114d0 | ✅ matches (Quaternion equivalent of matrix multiply) |
| `GameWindow.OnLiveVectorUpdated` (3246) | `SmartBox::DoVectorUpdate` 0x004521c0 | ⚠️ **acdream sets Gravity / clears Contact+OnWalkable; retail does NOT.** Acdream's behavior is defensive; retail relies on the bits already being correct from launch. |

### Issues / divergences worth filing

1. **`PhysicsBody.set_velocity` is missing `jumped_this_frame = 1`.**
   Without this flag the next-tick collision sweep clamps the +Z
   velocity to zero before gravity can lift the body. Effective bug:
   first-frame after launch the body may be re-clamped to floor.
   Acdream may be papering over this elsewhere (e.g. by deferring
   sweep until N+2) — worth verifying whether per-tick code reads a
   `JumpedThisFrame` member.

2. **Acdream `OnLiveVectorUpdated` extra writes vs retail.** Acdream
   sets `State |= Gravity` and clears Contact+OnWalkable when v.Z>0.5.
   Retail's `SmartBox::DoVectorUpdate` does only set_velocity + set_omega.
   The reason acdream needs the extra writes is that acdream's per-tick
   integrator gates gravity on `!OnWalkable` instead of `state & Gravity`.
   If we ported `calc_acceleration` faithfully (state.Gravity bit set
   at body creation, persists across jumps), the OnLiveVectorUpdated
   bit-setting would become unnecessary.

3. **K-fix15 question (airborne + IsOnGround + Velocity.Z<=0):** retail's
   landing detection has nothing to do with Velocity.Z. It uses the
   sphere-sweep's contact plane (per `CPhysicsObj::set_frame`
   collision_info path) and compares `contact_plane.N.z` against
   `floor_z`. Acdream's velocity-Z-based landing heuristic in
   `OnLivePositionUpdated` is a pragmatic shortcut (we don't have a
   full sphere-sweep on remotes), but is materially divergent from
   retail. Long-term, when remote sphere-sweep lands, swap to the
   N.z gate.

---

## File written

`docs/research/2026-05-04-l3-port/10-vector-update-jump.md`