acdream/docs/research/2026-05-04-l3-port/08-update-object-substep-and-frame.md

L.3 port — update_object substepping + Frame operations

Source: docs/research/named-retail/acclient_2013_pseudo_c.txt (Sept 2013 EoR PDB-named decompilation, BinaryNinja pseudo-C). Cross-checked against ACE's port (references/ACE/Source/ACE.Server/Physics/PhysicsObj.cs, PhysicsGlobals.cs).

This document extracts the per-tick variable-dt substepping algorithm and the Frame composition primitives that drive the per-frame physics integration. It answers:

• What is the substepping algorithm? (HugeQuantum discard → MaxQuantum slicer loop → MinQuantum remainder)
• What happens for very small dt? (early-return at EPSILON, NOT MinQuantum — retail processes every frame)
• How is LastUpdateTime advanced? (always to PhysicsTimer::curr_time after the loop)
• What does process_hooks do? (iterates linked-list of PhysicsObjHooks + anim_hooks per frame, executing & removing finished ones)
• Frame::combine semantics: out = a · b — Frame transform composition (rotate b's origin by a's basis, then add a's origin; quaternion product a.q * b.q for orientation).

The constants MinQuantum/MaxQuantum/HugeQuantum are not directly visible in the BinaryNinja decompiled update_object because the BN decompiler corrupted some immediate floats to 0.0. The constants are recovered cleanly from ACE's PhysicsGlobals.cs, which itself is a faithful port of the same retail binary. The 0.000199999995f (= EPSILON = 0.0002) constant IS visible in the decomp (line 283996) — it's the early-exit tolerance distinct from MinQuantum.

---

1 — CPhysicsObj::update_object (FUN_00515D10) — main per-frame entry

Signature: void __fastcall CPhysicsObj::update_object(CPhysicsObj* this) Source: acclient_2013_pseudo_c.txt:283950-284055

Verbatim relevant pseudo-C (lines 283950-284055)

00515d10  void __fastcall CPhysicsObj::update_object(class CPhysicsObj* this) {

  // Bail-out 1: parented (held by another obj), no cell, or hidden (state & 0x1000000)
  if (this->parent != 0 || this->cell == 0 || (this->state & 0x1000000) != 0) {
      this->transient_state &= 0xffffff7f;     // clear "active" flag
      return;
  }

  // Player-distance update: if a player object exists, compute offset and
  // toggle "active" transient flag based on 96.0f distance gate.
  CPhysicsObj* player = CPhysicsObj::player_object;
  if (player != 0) {
      Vector3 offset;
      Position::get_offset(&player->m_position, &offset, &this->m_position);
      this->player_vector = offset;
      this->player_distance = sqrtf(offset.x*offset.x + offset.y*offset.y + offset.z*offset.z);
      // [actually plain |offset.x| in BN noise; ACE uses .Length()]
      if (this->player_distance >= 96.0f) {
          // beyond the active radius; deactivate
          this = CPhysicsObj::obj_maint;       // this overwritten — BN noise
      }
      if (this->player_distance >= 96.0f || this->part_array == 0) {
          this = this_3;
          CPhysicsObj::set_active(this, 1);
      } else {
          this_3->transient_state &= 0xffffff7f;   // clear active
      }
  }

  // ── dt computation ────────────────────────────────────────────────────────
  double dt = Timer::cur_time - this_3->update_time;
  PhysicsTimer::curr_time = this_3->update_time;       // seed phys clock with this obj's last-update

  // ── Guard 1: dt < EPSILON (0.000199999995f ≈ 0.0002 s) ────────────────────
  // Retail tolerance for "essentially zero" — NOT MinQuantum.
  // If dt < EPSILON, bump update_time and return without any simulation.
  if (dt < 0.000199999995f) {        // line 283996
      this_3->update_time = Timer::cur_time;
      return;
  }

  // ── Guard 2: dt > HugeQuantum (2.0 s) — discard stale dt ─────────────────
  // (Constant 2.0 visible at line 284009 — "long double temp1 = 2.0;")
  if (dt > 2.0) {
      this_3->update_time = Timer::cur_time;
      return;
  }

  // ── Substep loop: while dt > MaxQuantum, slice off MaxQuantum chunks ─────
  // BN corrupted MaxQuantum to "0.0" in the loop body, but the loop structure
  // is unmistakable (line 284031 do-while). ACE's port confirms MaxQuantum=0.1.
  if (dt > 0.0f /* MaxQuantum=0.1 */) {
      do {
          PhysicsTimer::curr_time += /* MaxQuantum */ 0.1;
          CPhysicsObj::UpdateObjectInternal(this_3, /* MaxQuantum */ 0.1f);
          dt -= /* MaxQuantum */ 0.1;
      } while (dt > /* MaxQuantum */ 0.1);
  }

  // ── Final remainder: if dt > MinQuantum (1/30), simulate the leftover ────
  // BN: line 284046 "if (!(p_1) || ... > 0.0) { ... UpdateObjectInternal(remainder)
  // }" — the comparison constant should be MinQuantum=1/30=0.0333f per ACE.
  if (dt > /* MinQuantum */ 0.0333f) {
      PhysicsTimer::curr_time += dt;
      CPhysicsObj::UpdateObjectInternal(this_3, (float)dt);
  }

  // Advance update_time to the consumed phys clock time.
  this_3->update_time = PhysicsTimer::curr_time;
}

Constants — recovered values

From references/ACE/Source/ACE.Server/Physics/PhysicsGlobals.cs:9-43:

Symbol	Hex (float32)	Value	Meaning
EPSILON	0x3949A18A	0.000199999995f ≈ 0.0002 s	"essentially zero" tolerance (visible in retail decomp line 283996)
MinQuantum	0x3D088889	1.0f / 30.0f ≈ 0.03333 s (30 fps)	minimum simulation step
MaxQuantum	0x3DCCCCCD	0.1f (10 fps)	substep cap — BN-corrupted to 0.0 in pseudo-C but confirmed via ACE
HugeQuantum	0x40000000	2.0f (0.5 fps)	upper bound — beyond this, dt is discarded as stale (visible line 284009)

Note on the BN-decomp corruption: lines 284034, 284036-284037, 284049 in the pseudo-C show ((long double)0.0) where retail clearly reads non-zero immediates from .rdata. The decompiler dropped the immediate during constant-folding when sourcing from a global. Cross-reference with ACE confirms these are MaxQuantum=0.1 in the loop body and 0.0333 in the final-remainder guard.

update_object_server — does it exist?

No. Search of acclient_2013_pseudo_c.txt for update_object_server returns zero hits. There is only CPhysicsObj::update_object (the per-frame driver) and CPhysicsObj::UpdateObjectInternal (the per-substep worker). ACE introduced server-side variants that don't exist in retail.

---

2 — CPhysicsObj::UpdateObjectInternal (FUN_005156B0) — per-substep worker

Signature: void __thiscall CPhysicsObj::UpdateObjectInternal(CPhysicsObj* this, float arg2) Source: acclient_2013_pseudo_c.txt:283611-283757

This is the function called once per substep with arg2 = dt (≤ MaxQuantum). Two main branches based on transient_state sign bit (which is Active, 0x80):

005156b0  void UpdateObjectInternal(CPhysicsObj* this, float arg2) {

  // Branch A: obj is INACTIVE (transient_state >= 0, i.e. high bit clear).
  // Just tick particles + scripts; no movement.
  if ((int16_t)this->transient_state >= 0) goto label_5159b8;

  // Branch B: obj is ACTIVE.
  if (this->cell == 0) return;

  // ── Active-mover path ───────────────────────────────────────────────────
  if ((this->transient_state & 0x100) != 0)            // line 283631 — clears Sticky
      CPhysicsObj::set_ethereal(this, 0, 0);
  this->jumped_this_frame = 0;

  // Build a local Frame (stack-allocated, identity quaternion).
  Position offsetPos = { objcell_id=0x796910, qw=1, qx=0,qy=0,qz=0,
                         origin={0,0,0} };
  Frame offsetFrame;                                    // stack
  Frame::cache(&offsetFrame);                           // line 283644

  uint32_t cellId = this->m_position.objcell_id;

  // ── 1) UpdatePositionInternal: integrates velocity/accel into offsetFrame
  st0_1 = CPhysicsObj::UpdatePositionInternal(this, arg2, &offsetFrame);
  // line 283646

  CPartArray* parts = this->part_array;
  uint32_t numSpheres = parts ? CPartArray::GetNumSphere(parts) : 0;

  if (parts != 0 && numSpheres != 0) {
      if (Vector3::operator==(&offsetFrame.origin, &this->m_position.frame.origin) == 0) {
          // origin moved — need a transition (collision sweep)
          uint32_t state = this->state;
          if ((state & 0x100) != 0) {                   // line 283661
              // facing-velocity heading mode
              Vector3 dir;
              AC1Legacy::Vector3::operator-(&offsetFrame.origin, &dir,
                                            &this->m_position.frame.origin);
              Vector3::Normalize(&dir);
              Frame::set_vector_heading(&offsetFrame, &dir);
          }
          else if ((state & "activation type (%s) with '%s' b…" /* a high state-bit */) != 0
                   && AC1Legacy::Vector3::is_zero(&this->m_velocityVector) == 0) {
              float heading = AC1Legacy::Vector3::get_heading(&this->m_velocityVector);
              Frame::set_heading(&offsetFrame, heading);
          }

          // ── COLLISION SWEEP — port of FUN_005148A0 / Transition::FindTransitional… ──
          CTransition* tx = CPhysicsObj::transition(this, &this->m_position,
                                                    &offsetPos /* desired */,
                                                    /*flags*/ 0);

          if (tx == 0) {
              // sweep failed — keep current position, snap to offsetFrame, zero velocity
              CPhysicsObj::set_frame(this, &offsetFrame);
              this->cached_velocity = {0,0,0};
          } else {
              // sweep succeeded — measured velocity = (curr_pos - new_pos)/dt
              Vector3 deltaPos;
              Position::get_offset(&this->m_position, &deltaPos, &tx->sphere_path.curr_pos);
              Vector3 measuredVel;
              Vector3::operator/(&deltaPos, &measuredVel, arg2);
              this->cached_velocity = measuredVel;
              CPhysicsObj::SetPositionInternal(this, tx);    // commits new pos+cell
          }
      } else {
          // origin didn't move — just set frame and clear velocity
          CPhysicsObj::set_frame(this, &offsetFrame);
          this->cached_velocity = {0,0,0};
      }
  } else {
      // No part_array or no spheres — clear "stationary fall" flag if free, set frame, clear velocity
      if (this->movement_manager == 0) {
          uint32_t ts = this->transient_state;
          if ((ts & 2) != 0) this->transient_state = ts & 0xffffff7f;
      }
      CPhysicsObj::set_frame(this, &offsetFrame);
      this->cached_velocity = {0,0,0};
  }

  // ── 2) Per-frame ticks (managers + parts + position interp) ─────────────
  if (this->detection_manager != 0)
      DetectionManager::CheckDetection(this->detection_manager);
  if (this->target_manager != 0)
      TargetManager::HandleTargetting(this->target_manager);
  if (this->movement_manager != 0)
      MovementManager::UseTime(this->movement_manager);   // animation tick
  if (this->part_array != 0)
      CPartArray::HandleMovement(this->part_array);
  if (this->position_manager != 0)
      PositionManager::UseTime(this->position_manager);

label_5159b8:
  // ── 3) Particles + scripts (always, both Active and Inactive branches) ──
  if (this->particle_manager != 0)
      ParticleManager::UpdateParticles(this->particle_manager);
  if (this->script_manager != 0)
      ScriptManager::UpdateScripts(this->script_manager);
}

Key sequencing per substep:

1. Build identity local Frame (offsetFrame).
2. UpdatePositionInternal(this, dt, &offsetFrame) — integrate motion into the frame.
3. If origin changed and we have collidable spheres → run transition() (collision sweep).
4. If sweep succeeds → commit via SetPositionInternal; cached_velocity = (deltaPos / dt).
5. If sweep fails → snap to offsetFrame directly; zero velocity.
6. Tick managers (Detection, Target, Movement, PositionManager).
7. Tick CPartArray::HandleMovement (per-part frame propagation).
8. Tick particle_manager + script_manager.

process_hooks is NOT called here — it lives inside UpdatePositionInternal (see §3).

---

3 — CPhysicsObj::UpdatePositionInternal (FUN_00512C30)

Signature: void UpdatePositionInternal(CPhysicsObj* this, float dt, Frame* outFrame) Source: acclient_2013_pseudo_c.txt:280817-280866

00512c30  void UpdatePositionInternal(CPhysicsObj* this, float dt, Frame* outFrame) {

  // ── Step A: tabula-rasa local frame, zero translation ───────────────────
  Frame localFrame;
  localFrame.qw=1, localFrame.qx=0,qy=0,qz=0;
  localFrame.origin = {0,0,0};
  Frame::cache(&localFrame);     // build l2gv basis from quat

  // ── Step B: animation drives a delta-frame into localFrame ──────────────
  // (Skipped if state & 0x4000 / "static decoration" bit.)
  if ((this->state & 0x4000) == 0) {
      if (this->part_array != 0) {
          // CPartArray::Update walks the AnimSequencer, applies animFrame deltas,
          // adds them onto var_c/var_8/var_4 (the local origin). It also pulls
          // OmegaVector and applies it into the quaternion. After this returns,
          // localFrame.origin holds the local-frame velocity*dt + omega-rotation.
          CPartArray::Update(this->part_array, dt, &localFrame);
      }

      // Scale by m_scale if Sticky flag is set (riding a moving platform).
      // Otherwise zero the local-origin (just keep rotation).
      if ((this->transient_state & 2) /* HasContact */ == 0) {
          localFrame.origin *= 0.0f;       // zero translation
      } else {
          localFrame.origin *= this->m_scale;
      }
  }

  // ── Step C: apply position_manager interpolation offset (smooth catch-up)
  if (this->position_manager != 0)
      PositionManager::adjust_offset(this->position_manager, &localFrame, dt);

  // ── Step D: COMBINE — outFrame = m_position.frame * localFrame ──────────
  // This rotates localFrame.origin by m_position.frame's basis, adds m_position.frame's
  // origin, multiplies the quaternions: outFrame.q = m_position.q * localFrame.q.
  Frame::combine(outFrame, &this->m_position.frame, &localFrame);  // line 280860

  // ── Step E: if not "static decoration", run physics (gravity, friction…)
  if ((this->state & 0x4000) == 0)
      CPhysicsObj::UpdatePhysicsInternal(this, dt, outFrame);

  // ── Step F: dispatch hooks (per-frame scripted callbacks + anim hooks) ──
  CPhysicsObj::process_hooks(this);                     // line 280865
}

This is the function that produces the desired post-tick world frame in outFrame. The caller (UpdateObjectInternal) then routes that through the collision sweep.

---

4 — CPhysicsObj::process_hooks (FUN_00511550)

Signature: void __fastcall CPhysicsObj::process_hooks(CPhysicsObj* this) Source: acclient_2013_pseudo_c.txt:279431-279486

00511550  void process_hooks(CPhysicsObj* this) {

  // ── Linked-list hooks (vtable->Execute) ─────────────────────────────────
  // PhysicsObjHook is a polymorphic interface (translucency-fade, scale-fade,
  // visibility-fade, FPHook, etc). When Execute returns nonzero, the hook is
  // "done" — unlink and delete it.
  PhysicsObjHook* h = this->hooks;
  while (h != 0) {
      PhysicsObjHook* next = h->next;
      if (h->vtable->Execute(this) != 0) {
          // unlink h from doubly-linked list
          if (h->next != 0) h->next->prev = h->prev;
          if (h->prev == 0) this->hooks = h->next;
          else              h->prev->next = h->next;
          h->prev = h->next = 0;
          h->vtable = (vtable_t*)0x7c6b20;     // PhysicsObjHook base vtable
          operator delete(h);
      }
      h = next;
  }

  // ── Anim hooks (one-shot bag, executed and cleared every frame) ─────────
  uint32_t n = this->anim_hooks.m_num;
  if (n > 0) {
      for (uint32_t i = 0; i < this->anim_hooks.m_num; i++)
          this->anim_hooks.m_data[i]->vtable->Execute(this);
      AC1Legacy::SmartArray<CAnimHook*>::shrink(&this->anim_hooks);
      this->anim_hooks.m_num = 0;
  }
}

What it does:

• hooks (linked list): persistent-until-done callbacks (translucency lerp, scale lerp, FPHook for fade events, etc). Each Execute returns done=1 → delete.
• anim_hooks (SmartArray<CAnimHook*>): one-shot per-frame anim events (sound triggers, particle spawns, attack-frame markers fired by AnimationSequencer). Always cleared every frame.

This is invoked once per substep at the END of UpdatePositionInternal. acdream's port has separate routers (AnimationHookRouter, AnimationCommandRouter) but no equivalent of the persistent PhysicsObjHook linked list yet.

---

5 — CPhysicsObj::calc_acceleration (FUN_00510950)

Signature: void __fastcall CPhysicsObj::calc_acceleration(CPhysicsObj* this) Source: acclient_2013_pseudo_c.txt:278533-278560

00510950  void calc_acceleration(CPhysicsObj* this) {
  uint8_t ts = (int8_t)this->transient_state;

  // Special case: Active + HasContact + state-bit-?? → freeze (zero accel + omega).
  // Used for "standing still on a surface" steady-state.
  if ((ts & 1) != 0 && (ts & 2) != 0 && (this->state & 0x100 /* state's high mask */) == 0) {
      this->m_accelerationVector = {0, 0, 0};
      this->m_omegaVector        = {0, 0, 0};
      return;
  }

  // Gravity gate: state bit 0x4 (= GravityFlag).
  if ((this->state & 0x400 /* gravity bit, 0x4 << 8 in BN ushort masking */) == 0) {
      // Gravity OFF — zero acceleration (note: omega NOT zeroed)
      this->m_accelerationVector = {0, 0, 0};
      return;
  }

  // Default: gravity ON → vertical acceleration = PhysicsGlobals::gravity
  this->m_accelerationVector = {0, 0, PhysicsGlobals::gravity};   // gravity ≈ -9.8
}

Per-frame called by UpdatePhysicsInternal (which is called from UpdatePositionInternal step E above). acdream's PhysicsBody.calc_acceleration matches this contract.

---

6 — CPhysicsObj::transition (FUN_00512DC0)

Signature: CTransition const* transition(CPhysicsObj* this, Position const* fromPos, Position const* toPos, int32_t flags) Source: acclient_2013_pseudo_c.txt:280904-280957

00512dc0  CTransition* transition(CPhysicsObj* this, Position* from, Position* to, int32_t flags) {
  CTransition* tx = CTransition::makeTransition();
  if (tx == 0) return 0;

  // Init the object info struct (collidesWith, isMissile, etc) using flags arg
  CTransition::init_object(tx, this, CPhysicsObj::get_object_info(this, tx, flags));

  // Init sphere(s) to sweep — typically 1 humanoid sphere or N for parts
  CPartArray* parts = this->part_array;
  uint32_t n = parts ? CPartArray::GetNumSphere(parts) : 0;
  if (parts == 0 || n == 0) {
      CTransition::init_sphere(tx, 1, &dummy_sphere, 1.0f);
  } else {
      float scale = this->m_scale;
      CSphere* spheres = CPartArray::GetSphere(parts);
      uint32_t nSph = CPartArray::GetNumSphere(parts);
      CTransition::init_sphere(tx, nSph, spheres, scale);
  }

  // Path: from → to in cell `this->cell`
  CTransition::init_path(tx, this->cell, from, to);

  // Stationary-fall mask: tighter checks based on transient_state ContactPlane bits
  uint8_t ts = (int8_t)this->transient_state;
  if ((ts & 0x40) != 0)        tx->collision_info.frames_stationary_fall = 3;
  else if ((ts & 0x20) != 0)   tx->collision_info.frames_stationary_fall = 2;
  else if ((ts & 0x10) != 0)   tx->collision_info.frames_stationary_fall = 1;

  // Run the actual sweep — returns nonzero on success
  int32_t ok = CTransition::find_valid_position(tx);

  // NOTE: BN shows cleanupTransition(tx) BEFORE the success check — this
  // looks wrong but BN's stack-frame analysis is unreliable here. ACE's
  // port (PhysicsObj.transition) calls cleanup AFTER, conditionally.
  CTransition::cleanupTransition(tx);
  return (ok != 0) ? tx : 0;
}

find_valid_position is just an alias that calls find_transitional_position (line 273898). The actual sweep loop is CTransition::find_transitional_position (FUN_0050BDF0) at line 273613, which:

1. Computes step count (calc_num_steps) — dt-derived based on offset length and sphere radius.
2. Loops, advancing the sphere along the offset, calling transitional_insert each step.
3. Each step: cell list → BSP collision → step-up / edge-slide / contact-plane logic.

This is the heart of the "collision sweep" the env-var path currently bypasses.

---

7 — CPhysicsObj::SetPositionInternal overloads

Two overloads exist. The "post-sweep commit" form is FUN_00515BD0, called with (this, ebp /*tx*/):

00515bd0  SetPositionError SetPositionInternal(CPhysicsObj* this, Position* pos,
                                                SetPositionStruct* sps, CTransition* tx) {
  CSphere* localSph = tx->sphere_path.local_sphere;
  if (this->cell == 0) CPhysicsObj::prepare_to_enter_world(this);

  int32_t ecx_2 = (sps->flags >> 5) & 1;       // "AdjustPosition" flag
  CTransition* outTx = nullptr;
  CPhysicsObj::AdjustPosition(pos, localSph, &outTx, ecx_2, 1);

  if (outTx == 0) {
      // Off the map — go to "lost cell"
      CPhysicsObj::prepare_to_leave_visibility(this);
      CPhysicsObj::store_position(this, pos);
      CObjectMaint::GotoLostCell(CPhysicsObj::obj_maint, this, this->m_position.objcell_id);
      this->transient_state &= 0xffffff7f;
  } else {
      // Hooks/Storage/Corpses go through ForceIntoCell
      if (this->weenie_obj != 0) {
          if (weenie_obj->IsHook())    return CPhysicsObj::ForceIntoCell(this, outTx, pos);
          if (weenie_obj->IsStorage()) return CPhysicsObj::ForceIntoCell(this, outTx, pos);
          if (weenie_obj->IsCorpse())  return CPhysicsObj::ForceIntoCell(this, outTx, pos);
      }
      // Honor "do_not_load_cells" sps flag
      if ((sps->flags & 0x20) != 0) tx->cell_array.do_not_load_cells = 1;

      if (CPhysicsObj::CheckPositionInternal(this, outTx, pos, tx, sps) == 0) {
          int32_t r = CPhysicsObj::handle_all_collisions(this, &tx->collision_info, 0, 0);
          return (-r ^ -r ... & 2) + 2;        // BN noise — actually returns 2 or 3
      }
      if (tx->sphere_path.curr_cell == 0) return 3;       // CELL_FAILED
      CPhysicsObj::SetPositionInternal(this, tx);          // 1-arg form: commit
  }
  return 0;        // OK_SPE
}

The 1-arg form (SetPositionInternal(this, tx)) is the one that finally writes the new cell pointer + frame onto the object (it's not in this excerpt — it's the real "commit" routine).

---

8 — CPhysicsObj::SetPosition (FUN_005160C0)

External wrapper that builds a CTransition, runs SetPositionInternal, and returns. Used by NPC teleport / scatter, NOT by update_object.

005160c0  SetPositionError SetPosition(CPhysicsObj* this, SetPositionStruct* sps) {
  CTransition* tx = CTransition::makeTransition();
  if (tx == 0) return 1;
  CTransition::init_object(tx, this, 0);
  // Init sphere(s) — same pattern as transition()
  CTransition::init_sphere(tx, n, spheres, scale);
  SetPositionError r = CPhysicsObj::SetPositionInternal(this, sps, tx);
  CTransition::cleanupTransition(tx);
  return r;
}

9 — CPhysicsObj::SetPositionSimple (FUN_005162B0)

005162b0  SetPositionError SetPositionSimple(CPhysicsObj* this, Position* pos, int32_t teleport) {
  uint32_t flags = teleport ? 0x1012 : 0x1002;
  SetPositionStruct sps;
  SetPositionStruct::SetPositionStruct(&sps);
  SetPositionStruct::SetPosition(&sps, pos);
  SetPositionStruct::SetFlags(&sps, flags);
  SetPositionError r = CPhysicsObj::SetPosition(this, &sps);
  SetPositionStruct::~SetPositionStruct(&sps);
  return r;
}

10 — CPhysicsObj::set_frame (FUN_00514090)

The "no collision check" frame setter — used inside the substep when origin didn't move OR when the sweep failed and we just snap.

00514090  void set_frame(CPhysicsObj* this, Frame* arg2) {
  Frame newFrame;
  Frame::operator=(&newFrame, arg2);
  if (Frame::IsValid(&newFrame) == 0 && Frame::IsValidExceptForHeading(&newFrame) != 0) {
      // NaN-only-in-quaternion edge case → reset rotation (memset to 0)
      newFrame.qw = 0; newFrame.qx = 0; newFrame.qy = 0; newFrame.qz = 0;
  }
  Frame::operator=(&this->m_position.frame, &newFrame);   // store
  if ((this->state & 0x1000 /* "no parts" */) == 0) {
      if (this->part_array != 0)
          CPartArray::SetFrame(this->part_array, &this->m_position.frame);
  }
  CPhysicsObj::UpdateChildrenInternal(this);              // propagate to children
}

---

11 — Frame operations

Memory layout (verbatim from acclient.h / inferred from BN offsets)

class Frame {
  Vector3 m_fOrigin;       // +0x00 (12 bytes)
  float qw, qx, qy, qz;    // +0x0C (16 bytes)
  float m_fl2gv[9];        // +0x1C (36 bytes) — 3x3 local-to-global rotation matrix cache
};                         // total 0x40 = 64 bytes

The matrix cache m_fl2gv is the rotation matrix derived from the quaternion. It's recomputed by Frame::cache whenever the quaternion changes.

Frame::operator= (FUN_00425C30) — line 39761

Plain memberwise copy of all 16 floats (origin + quat + 9 matrix entries):

00425c30  Frame& operator=(Frame* this, Frame const& src) {
  this->m_fOrigin = src.m_fOrigin;
  this->qw = src.qw; this->qx = src.qx; this->qy = src.qy; this->qz = src.qz;
  for (int i = 0; i < 9; i++) this->m_fl2gv[i] = src.m_fl2gv[i];
  return *this;
}

Frame::cache (FUN_00534DF0) — line 319353

Rebuilds the m_fl2gv[9] rotation matrix from (qw, qx, qy, qz). Standard quaternion-to-matrix:

00534df0  void Frame::cache(Frame* this) {
  // Use temp doubles to preserve x87 precision
  double tx = this->qx + this->qx;        // 2qx
  double ty = this->qy + this->qy;        // 2qy
  double tz = this->qz + this->qz;        // 2qz
  double wx = this->qw * tx;              // 2qw·qx
  double wy = this->qw * ty;              // 2qw·qy
  double wz = this->qw * tz;              // 2qw·qz
  double xx = this->qx * tx;              // 2qx·qx
  double xy = this->qx * ty;              // 2qx·qy
  double xz = this->qx * tz;              // 2qx·qz
  double yy = this->qy * ty;              // 2qy·qy
  double yz = this->qy * tz;              // 2qy·qz
  double zz = this->qz * tz;              // 2qz·qz

  // Column-major 3x3 stored row-by-row:
  this->m_fl2gv[0] = 1.0 - yy - zz;        //  R00
  this->m_fl2gv[1] = xy + wz;              //  R10
  this->m_fl2gv[2] = xz - wy;              //  R20
  this->m_fl2gv[3] = xy - wz;              //  R01
  this->m_fl2gv[4] = 1.0 - xx - zz;        //  R11
  this->m_fl2gv[5] = yz + wx;              //  R21
  this->m_fl2gv[6] = xz + wy;              //  R02
  this->m_fl2gv[7] = yz - wx;              //  R12
  this->m_fl2gv[8] = 1.0 - xx - yy;        //  R22
}

This is a standard XYZW-quaternion-to-3x3 matrix, but the layout here is transpose of typical glm/Silk row-major. acdream needs to be careful when consuming.

Frame::combine (FUN_005122E0) — line 280355

Most important — multiplication semantics: out = a · b (compose b on top of a).

005122e0  void Frame::combine(Frame* out, Frame const* a, Frame const* b) {
  // ── Origin: rotate b.origin by a's basis, then add a.origin ─────────────
  out->m_fOrigin.x = a->m_fl2gv[0]*b->origin.x
                   + a->m_fl2gv[3]*b->origin.y
                   + a->m_fl2gv[6]*b->origin.z + a->m_fOrigin.x;
  out->m_fOrigin.y = a->m_fl2gv[1]*b->origin.x
                   + a->m_fl2gv[4]*b->origin.y
                   + a->m_fl2gv[7]*b->origin.z + a->m_fOrigin.y;
  out->m_fOrigin.z = a->m_fl2gv[2]*b->origin.x
                   + a->m_fl2gv[5]*b->origin.y
                   + a->m_fl2gv[8]*b->origin.z + a->m_fOrigin.z;

  // ── Quaternion: a.q * b.q (Hamilton product) ────────────────────────────
  // Note: BN swaps some operand orders, but this is the Hamilton product.
  Frame::set_rotate(out,
      a->qw*b->qw - b->qx*a->qx - b->qy*a->qy - b->qz*a->qz,        // qw
      a->qw*b->qx + b->qz*a->qy + b->qw*a->qx - b->qy*a->qz,        // qx
      b->qy*a->qw - b->qz*a->qx + a->qz*b->qx + a->qy*b->qw,        // qy
      b->qy*a->qx + b->qz*a->qw - a->qy*b->qx + a->qz*b->qw);       // qz
}

Frame::set_rotate then normalizes the quaternion and re-runs Frame::cache to refresh m_fl2gv.

Order: combine(out, a, b) means out = a ∘ b — first apply b in local-frame coords, then rotate-and-translate by a. In UpdatePositionInternal step D, this means: outFrame = m_position.frame * localDelta — i.e. take the local-frame motion and lift it into world.

Frame::set_rotate (FUN_00535080) — line 319453

00535080  void Frame::set_rotate(Frame* this, float qw, float qx, float qy, float qz) {
  // Cache old quaternion in case new one is invalid
  float oldQw=this->qw, oldQx=this->qx, oldQy=this->qy, oldQz=this->qz;

  float invLen = 1.0 / sqrt(qw*qw + qx*qx + qy*qy + qz*qz);
  this->qw = qw * invLen;
  this->qx = qx * invLen;
  this->qy = qy * invLen;
  this->qz = qz * invLen;

  if (Frame::IsValid(this) != 0) {
      Frame::cache(this);          // refresh l2gv matrix
  } else {
      // Restore — new quat had NaN
      this->qw=oldQw; this->qx=oldQx; this->qy=oldQy; this->qz=oldQz;
  }
}

Frame::set_heading (FUN_00535E40) — line 320049

Sets heading from a yaw angle (degrees):

00535e40  void Frame::set_heading(Frame* this, float degrees) {
  // BN noise computes a vector from an existing matrix column — irrelevant
  double rad = degrees * 0.017453292519943295;        // π/180
  float sinR = sin(rad);
  float cosR = cos(rad);
  Vector3 heading = { sinR, cosR, 0 };               // +Y is north; rotate CW
  Frame::set_vector_heading(this, &heading);
}

Frame::set_vector_heading (FUN_00535DB0) — line 320030

Sets heading to face a normalized 2D direction vector (rotation around Z-axis):

00535db0  void Frame::set_vector_heading(Frame* this, Vector3 const* dir) {
  Vector3 d = *dir;
  if (AC1Legacy::Vector3::normalize_check_small(&d) != 0) return;
  // Note: AC's heading convention — angle from north (+Y) measured clockwise.
  // 450 - atan2(x, y) normalizes to [0, 360).
  double yawDeg = 450.0 - atan2(d.x, d.y) * 57.295779513082323;
  yawDeg = fmod(yawDeg, 360.0);
  Frame::euler_set_rotate(this, ..., 0, ..., yawDeg * 0.017453292519943295);
}

Frame::rotate (FUN_004525B0) — line 91477

Applies a small rotation increment in local space (used by omega integration):

004525b0  void Frame::rotate(Frame* this, Vector3 const* localOmegaTimesDt) {
  // Lift the local-axis-angle vector to world by the current basis
  Vector3 worldOmegaDt;
  worldOmegaDt.x = this->m_fl2gv[0]*localOmegaTimesDt->x
                 + this->m_fl2gv[3]*localOmegaTimesDt->y
                 + this->m_fl2gv[6]*localOmegaTimesDt->z;
  worldOmegaDt.y = this->m_fl2gv[1]*localOmegaTimesDt->x
                 + this->m_fl2gv[4]*localOmegaTimesDt->y
                 + this->m_fl2gv[7]*localOmegaTimesDt->z;
  worldOmegaDt.z = this->m_fl2gv[2]*localOmegaTimesDt->x
                 + this->m_fl2gv[5]*localOmegaTimesDt->y
                 + this->m_fl2gv[8]*localOmegaTimesDt->z;
  Frame::grotate(this, &worldOmegaDt);          // global-frame rotation
}

Frame::set_origin — does it exist?

No — search of acclient_2013_pseudo_c.txt finds zero hits for Frame::set_origin. Origin is set by direct member assignment (f.m_fOrigin = newOrigin) or via Frame::operator=. Note: the named PDB does not list a public mutator for origin alone.

Frame::is_zero — does it exist?

No — search returns zero hits for Frame::is_zero. The is_zero method exists on AC1Legacy::Vector3 (e.g. Vector3::is_zero(&this->m_velocityVector) at line 283667), and is applied to Frame::m_fOrigin indirectly via Vector3::operator==(&zeroVec, &frame.origin).

---

12 — Position::ctor, Position::distance, Position::get_offset

Position::Position (FUN_00424AB0) — default ctor

Sets vtable, zero objcell_id, identity Frame.

Position::Position(Position*, uint32_t cellId, Frame*) — line 91542

00452780  void Position::Position(Position* this, uint32_t cellId, Frame* frame) {
  this->vtable     = 0x796910;
  this->objcell_id = cellId;
  Frame::operator=(&this->frame, frame);
}

Position::Position(Position*, Position const*) — line 91655 (copy ctor)

Just calls Frame::operator= on the embedded frame and copies cellId.

Position::get_offset — line 272088

Cell-aware vector offset (this → arg3) in landblock-global coordinates.

00509f60  Vector3* Position::get_offset(Position const* this, Vector3* out, Position const* other) {
  Vector3 blockOffset;
  // Compute the world offset between the two cell origins (uses landblock IDs).
  LandDefs::get_block_offset(&blockOffset, this->objcell_id, other->objcell_id);
  // out = (other.origin + blockOffset) - this.origin
  out->x = (blockOffset.x + other->frame.origin.x) - this->frame.origin.x;
  out->y = (blockOffset.y + other->frame.origin.y) - this->frame.origin.y;
  out->z = (blockOffset.z + other->frame.origin.z) - this->frame.origin.z;
  return out;
}

This is what acdream's Position.GetOffset mirrors. Critical: cells in different landblocks must be reconciled via LandDefs::get_block_offset before subtracting origins.

Position::distance (FUN_005A94B0) — line 438258

005a94b0  Vector3* Position::distance(Position const* this, Position const* other) {
  Vector3 r;
  Position::get_offset(this, &r, other);
  // (BN noise — actually returns sqrtf of the offset squared)
  return r;       // caller takes magnitude
}

Note: the BN decomp shows result->z; result->y; result->x; followed by return result — these dereferences load the floats but don't produce output here. The actual return value is the raw offset vector from get_offset; the caller computes .Length(). ACE's Position.Distance does this correctly.

---

13 — Substepping algorithm summary (the key answer)

dt = currentTime - LastUpdateTime

if (dt < EPSILON)        return;   // < 0.0002s — too small, defer
if (dt > HugeQuantum)    return;   // > 2.0s   — stale, discard, advance update_time

while (dt > MaxQuantum):            // 0.1 s
    PhysicsTimer.curr_time += MaxQuantum
    UpdateObjectInternal(MaxQuantum)
    dt -= MaxQuantum

if (dt > MinQuantum):               // 0.0333 s (1/30)
    PhysicsTimer.curr_time += dt
    UpdateObjectInternal(dt)         // remainder, anywhere in (1/30, 0.1]

LastUpdateTime = PhysicsTimer.curr_time

Observations:

1. Retail processes every frame, not just every 30 Hz. The first guard is EPSILON, not MinQuantum. ACE flipped this to < TickRate (= 1/30) for server CPU savings — that's a divergence, not retail-faithful.
2. dt below MinQuantum but above EPSILON → no simulation that frame, but update_time IS advanced to current time (line 284004). That means the next frame's dt is small again — accumulation is implicit, not explicit. There is no carry-over residue.
3. Between MinQuantum and MaxQuantum: a single substep for the full dt. (60-fps client => dt ≈ 0.0167 s — wait, that's BELOW MinQuantum.) Actually at 60 fps the second guard (> MinQuantum) is also FALSE, so nothing runs. This is consistent with retail running its physics tick at 30 Hz in MainProc. Retail's MainProc ticks at ~30 Hz on most hardware, not 60 Hz. acdream renders at 60 Hz but ticks physics at... whatever wall-clock dt comes through.
4. Between MaxQuantum and HugeQuantum: chunked substepping at fixed 0.1 s, then 1 final remainder if it exceeds MinQuantum. This handles frame-stutter / lag spikes (e.g. world load).
5. process_hooks runs once per substep (inside UpdatePositionInternal), so its rate scales with substep count — important for FPHook fade timers.
6. The collision sweep (transition) runs once per substep, which is why bypassing it (env-var path bug) caused the "staircase" effect on slopes.

What this means for LastUpdateTime advancement

After every substep loop, LastUpdateTime = PhysicsTimer.curr_time. PhysicsTimer.curr_time was incremented inside the loop by MaxQuantum per substep + the final remainder. It accumulates ONLY consumed time — if the early-< EPSILON guard fires, update_time is set to Timer::cur_time directly, dropping any unconsumed micro-fragment.

---

14 — Cross-check against acdream's port

PhysicsBody.update_object (src/AcDream.Core/Physics/PhysicsBody.cs:404-435):

acdream uses the threshold values correctly (MinQuantum=1/30, MaxQuantum=0.1, HugeQuantum=2.0) and has the substep loop. But it gates on dt < MinQuantum for the early return, not < EPSILON. This matches ACE's port (which uses TickRate=1/30) but diverges from retail, which uses EPSILON=0.0002.

Practical effect of the divergence:

At 60 fps (dt = 0.0167 s), retail would: pass the EPSILON gate → fail the loop gate (0.0167 < MaxQuantum=0.1) → fail the remainder gate (0.0167 < MinQuantum=0.0333) → bump update_time and return. No simulation ran, but time was consumed. Next frame: dt = 0.0167 again. Retail effectively sub-samples to 30 Hz, but does it through threshold-based skipping rather than explicit accumulation. Net effect: physics ticks at ~30 Hz on a 60-Hz render loop.

acdream's port: at 60 fps, dt = 0.0167 s, fails first gate (< MinQuantum = 0.0333), returns immediately WITHOUT updating LastUpdateTime. Next frame: dt = 0.0334 s, passes the first gate, runs UpdatePhysicsInternal(0.0334) once. Net effect: physics ticks at ~30 Hz, same outcome, but via accumulation. Equivalent functionally; minor structural divergence.

Recommendation: the acdream port is fine as-is for acdream (no behavioral difference at 30 Hz target), but the comment at line 395 (if dVar1 < MinQuantum → return) should note that retail uses EPSILON; the change is intentional alignment with ACE's optimization.

GameWindow.cs per-tick remote motion path (line 6541-6553):

The comment "rely on PhysicsBody.update_object here — its MinQuantum 30 fps gate" is accurate about acdream's port but slightly misleading about retail's behavior. Retail does NOT have a 30 Hz gate in update_object; it has a substep loop that effectively delivers 30 Hz simulation by way of the inner thresholds. The manual omega integration in GameWindow (line 6553-6559) is a workaround for a different reason — the body's quaternion-omega integration doesn't run when the body's update_object's loop body doesn't run, but acdream's render-tick path needs orientation continuity at 60 fps. This is a legitimate divergence forced by the env-var-path architecture; it's not a retail mismatch.

The real bug (Commit B fix at line 6190): the env-var path was missing the ResolveWithTransition call (port of find_transitional_position) that retail runs once per substep. Restoring it (line 6220) brought the env-var path back in line with retail.

---

15 — Open questions / follow-ups

• Frame::set_origin and Frame::is_zero don't exist as named symbols. The conventions are: direct field write for origin, and Vector3::is_zero on frame.m_fOrigin for the test. Confirm acdream's port uses the same conventions (no need for these methods on the Frame type).
• update_object_server does not exist. ACE's distinction between client and server update is not present in retail. The retail client and the retail server (which acdream emulates) probably both run the same code path; if so, acdream needs only one update_object.
• The early-return gate divergence (EPSILON vs MinQuantum) is functionally invisible at 30 Hz physics target but worth documenting in the port comment so future readers know it's an intentional ACE-style optimization, not a retail-faithful copy.
• process_hooks linked-list (PhysicsObjHook) is not yet ported in acdream. acdream has anim-hook routing (AnimationHookRouter) but no equivalent of FPHook / TranslucencyHook / VisibilityHook persistent linked-list framework. Phase that uses translucency animations or scale fades will need this.