acdream/docs/research/2026-07-19-r6-complete-root-frame-pseudocode.md

# R6 complete root Frame cutover — retail pseudocode

Date: 2026-07-19

Scope: the translation and orientation emitted by `CSequence` and consumed by
`CPhysicsObj::UpdatePositionInternal`. This note replaces the former acdream
split between animation root translation and command-derived/manual rotation.

## Named retail oracle

- `Frame::combine` `0x005122E0` (`acclient_2013_pseudo_c.txt:280355`)
- `Frame::set_rotate` `0x00535080`
- `Frame::IsValid` `0x00534ED0`
- `Position::subtract2` (complete relative Position/Frame)
- `CPhysicsObj::UpdatePositionInternal` `0x00512C30` (`:280817`)
- `CPhysicsObj::UpdateObjectInternal` `0x005156B0`
- `CPhysicsObj::SetPositionInternal(CTransition const*)` `0x00515330`
- `CPhysicsObj::change_cell` `0x00513390`
- `CPhysicsObj::remove_shadows_from_cells` `0x00511230`
- `CPhysicsObj::add_shadows_to_cells` `0x00514AE0`
- `CPhysicsObj::update_object` `0x00515D10`
- `CPhysicsObj::prepare_to_enter_world` `0x00511FA0`
- `CPhysicsObj::set_active` `0x0050FC40`
- `CPhysicsObj::animate_static_object` `0x00513DF0`
- `CPhysics::UseTime` `0x00509950` (separate static-object loop)
- `CPartArray::Update` `0x00517DB0` (`:285883`)
- `add_motion` `0x005224B0` (`:298437`)
- `CSequence::apply_physics` `0x00524AB0` (`:300955`)
- `InterpolationManager::InterpolateTo` `0x00555B20`
- `InterpolationManager::adjust_offset` `0x00555D30`

The installed retail portal DAT is a second executable fixture. Motion table
`0x09000001` (Humanoid), global `TurnRight` modifier `0x0000000D`, has
`HasOmega` and literal omega `(0, 0, -1.5)` radians/second. It is not
`-pi/2`, and it is not absent. The fixture is pinned by
`HumanoidMotionTableRootMotionTests`.

ACE cross-reference:
`docs/research/2026-07-02-r2-motiontable/r2-ace-motiontable.md` records the
ACE `MotionTable`/`Sequence` implementation: modifier lookup tries the styled
key then the unstyled key, and `add_motion` writes
`MotionData.Velocity * speed` plus `MotionData.Omega * speed`. ACE agrees with
the named client here. Retail remains the ordering and transform oracle.

## Pseudocode

```text
add_motion(sequence, motionData, speed):
    if motionData is null:
        return

    sequence.velocity = motionData.velocity * speed
    sequence.omega    = motionData.omega    * speed
    for animation in motionData.animations:
        sequence.append_animation(animation * speed)

apply_physics(sequence, frame, magnitudeQuantum, signSource):
    signedQuantum = abs(magnitudeQuantum)
    if signSource < 0:
        signedQuantum = -signedQuantum

    frame.origin += sequence.velocity * signedQuantum
    frame.rotate(sequence.omega * signedQuantum)

CPartArray.Update(dt, localFrame):
    sequence.update(dt, localFrame)

CPhysicsObj.prepare_to_enter_world(now):
    update_time = now
    remove object and children from lost/destroy queues
    if not Static:
        transient_state.Active = true

CPhysicsObj.update_object(now):
    if parent exists or cell is null or Frozen:
        transient_state.Active = false
        return without consuming update_time

    if player_object exists:
        player_vector = offset(player.position, object.position)
        player_distance = length(player_vector)
        if player_distance <= 96 world units or partArray is null:
            set_active(true)
        else:
            transient_state.Active = false
    // With no player_object, retain the prior Active state.

    elapsed = now - update_time
    if elapsed <= F_EPSILON or elapsed > HugeQuantum:
        update_time = now
        return

    while elapsed > MaxQuantum:
        UpdateObjectInternal(MaxQuantum)
        update_time += MaxQuantum
        elapsed -= MaxQuantum

    if elapsed > MinQuantum:
        UpdateObjectInternal(elapsed)
        update_time = now
    // A remainder at or below MinQuantum stays pending.

CPartArray.InitDefaults(setup):
    if setup.DefaultAnimation != 0:
        sequence.clear_animations()
        sequence.append_animation(
            animation = setup.DefaultAnimation,
            low = 0,
            high = -1,
            framerate = 30)
    owner.InitDefaults(setup)

CPhysicsObj.InitDefaults(setup):
    if setup.DefaultScript != 0:
        play_script_internal(setup.DefaultScript)
    install setup default motion/sound/physics-script tables
    if state has Static:
        if setup.DefaultAnimation != 0:
            state |= HasDefaultAnim
        if setup.DefaultScript != 0:
            state |= HasDefaultScript
        if state has HasDefaultAnim or HasDefaultScript:
            CPhysics.AddStaticAnimatingObject(this)

CPhysicsObj.animate_static_object(now):
    if cell is null:
        return
    elapsed = now - update_time
    if elapsed <= F_EPSILON or elapsed > 2 seconds:
        update_time = now
        return
    if partArray exists:
        if state has HasDefaultAnim:
            partArray.Update(elapsed, null)
            // Retail passes the stored vector directly; no elapsed multiply.
            position.frame.grotate(angularVelocity)
            UpdatePartsInternal()
            UpdateChildrenInternal()
        if state has HasDefaultScript and scriptManager exists:
            scriptManager.UpdateScripts()
        if particleManager exists:
            particleManager.UpdateParticles()
        process_hooks()
    update_time = now

CPhysics.UseTime(now):
    for object in ordinary object table:
        object.update_object(now)
    for object in static_animating_objects:
        object.animate_static_object(now)
    // These are separate ownership/workset paths. InitDefaults registers any
    // physics-Static object carrying Setup DefaultAnimation/DefaultScript,
    // including a server-created live object.

CPhysicsObj.UpdatePositionInternal(dt, outputWorldFrame):
    localFrame = identity

    if not Hidden:
        if partArray exists:
            partArray.Update(dt, localFrame)

        if OnWalkable:
            localFrame.origin *= objectScale
        else:
            localFrame.origin *= 0
        // Orientation is never cleared or scaled by this gate.

    if positionManager exists:
        positionManager.adjust_offset(localFrame, dt)

    outputWorldFrame = combine(position.frame, localFrame)

    if not Hidden:
        UpdatePhysicsInternal(dt, outputWorldFrame)

    process_hooks()

Frame.combine(output, current, delta):
    output.origin = current.origin + rotate(current.orientation, delta.origin)
    output.set_rotate(current.orientation * delta.orientation)

Frame.set_rotate(candidate):
    previous = orientation
    orientation = normalize(candidate)
    if not Frame.IsValid():
        orientation = previous

InterpolationManager.adjust_offset(delta, dt):
    if no Position node or body is not in Contact:
        return without mutating delta
    relative = Position.subtract2(target, current)
    relative.origin = clamp_to_catchup_distance(relative.origin, dt)
    if manager.keep_heading:
        relative.frame.set_heading(0)
    delta = relative.frame // replaces both origin and orientation

CPhysicsObj.SetPositionInternal(transition):
    if transition.current_cell is null:
        prepare_to_leave_visibility()
        store_position(transition.current_position)
        object_maintenance.goto_lost_cell()
        clear Active
        return

    if current cell differs:
        change_cell(transition.current_cell)
    else:
        commit the new full objcell id to the object, PartArray, and children
    set_frame(transition.current_position.frame)
    commit contact plane, OnWalkable, sliding normal, and collision callbacks
    if transition has a non-empty crossed-cell array:
        remove_shadows_from_cells()
        add_shadows_to_cells(transition.cell_array)
```

The ordering consequence is important: a delta translates through the old
orientation and only then applies its relative rotation. A large elapsed frame
must run multiple complete object quanta in time order. A render fragment below
the strict minimum does not advance CSequence at all; it stays in the object
clock until a later admitted quantum.

## Port mapping

- `MotionDeltaFrame.Combine` implements the retail composition and scales only
  the incoming origin.
- One incarnation-stable `RetailObjectQuantumClock` is shared by local,
  remote, Hidden, and projectile components of each live object. It admits
  complete object quanta; the local animation callback writes one reusable
  `MotionDeltaFrame` only after admission. `prepare_to_enter_world` clears the
  retained fragment and immediately restores Active only for non-Static
  objects, so their next elapsed frame can run; Static objects retain the
  inactive state established by initialization/leave-visibility. It does not
  invent a second reactivation frame.
- `CPartArray::InitDefaults` installs Setup DefaultAnimation for every
  setup-backed PartArray, independent of Static. Static controls only the
  additional `static_animating_objects -> animate_static_object` workset.
  Both DAT-hydrated statics and server-created objects whose final physics
  state is Static enter that workset when their Setup carries a
  DefaultAnimation. Default animation bypasses the MotionTable and installs
  the Setup animation directly over `0..last` at 30 frames/second. A short
  cell-less interval remains on the owner's clock and catches up after
  re-entry; an interval above two seconds is rebased and discarded. Script-only
  static owners still use acdream's shared PhysicsScriptRunner and are covered
  by TS-51 rather than entering an empty animation scan.
  A live static workset entry binds the exact PartArray and PhysicsBody already
  owned by its `LiveEntityRecord`; it never constructs a second sequencer or
  body. The raw angular-velocity vector is applied without multiplying by
  elapsed time, exactly as the named function does. A changed root commits the
  entity, effect pose, and multipart collision shadow together. Zero omega does
  not trigger a collision reflood, and a Hidden/nonresident object cannot have
  its suspended shadow restored by this animation path.
- Animation hooks are captured after `UpdatePhysicsInternal` and before the
  transition/manager tail. Semantic `AnimationDone` executes there, matching
  `CPhysicsObj::process_hooks`. Other pose-dependent router sinks remain
  deferred until final root/part/equipped-child pose publication; that known
  residual is registered as TS-50 rather than claimed as exact ordering.
  Static owners retain their semantic hook tail until final root, part, and
  attached-child publication, matching `animate_static_object`'s later
  `process_hooks` call. A residency change invalidates both the prepared pose
  and that pending tail.
- Retail session dispatch and `CPhysics::UseTime` are single-threaded FIFO
  operations. App therefore wraps complete packet and object-frame operations
  in `RetailInboundEventDispatcher`: a callback-triggered packet queues behind
  the current operation instead of recursively interleaving with its tail.
  Position, State, Vector, and Movement keep separate authority versions;
  Position/Vector/Movement additionally share only a velocity-write version.
  Never replace these with one global body-mutation token: that incorrectly
  discards independent accepted channels (for example State during Position).
  The direct packet/frame path carries state into a cached static callback and
  allocates nothing; only genuinely nested work receives a retained FIFO node.
- Projectile `BeginQuantum` is candidate-only. It restores the canonical begin
  frame/dynamics before returning; `CompleteQuantum` may commit only while the
  exact live record, projectile runtime, entity, spatial owner, and prediction
  version remain current. Any accepted Position, Vector, or State invalidates
  the candidate without rolling back the authoritative mutation.
- Animation-hook batches capture the pose owner's monotonic lifetime before
  running semantic AnimationDone. Capture rechecks it before every completion,
  and drain rechecks that lifetime and root pose before every routed hook,
  because either AnimationDone or an earlier sink can delete the owner and
  reuse the same local ID synchronously.
- Remote animation advances into one reusable DAT `Frame`; both components are
  passed to `RemotePhysicsUpdater` and applied through the same
  `PositionManager` frame.
- A body-backed animated object without a MovementManager now commits its
  complete Frame through `LiveEntityOrdinaryPhysicsUpdater`: root translation
  is admitted only while OnWalkable, orientation remains live, the resulting
  candidate runs through Transition/SetPositionInternal, and the same record is
  rebucketed without recreating resources. Callback deletion/replacement is
  revalidated before every commit.
- The resolved body and `WorldEntity` root/full-cell frame are committed before
  the canonical rebucket callback, matching SetPositionInternal's frame/contact
  commit before its final shadow replacement. A loaded-to-pending rebucket (or
  same-GUID replacement during its visibility callback) invalidates the caller
  before shadow or manager-tail publication. Non-projectile shadow residency is
  symmetric in `LiveEntityPresentationController`, including the pending-first
  case whose initial false edge precedes collision registration; projectiles
  retain their dedicated residency owner.
- Local projection and both authoritative remote UpdatePosition tails use the
  same post-rebucket exact-owner gate. Remote collision refresh is forced by a
  cell change or by a changed complete pose (translation or sign-invariant
  quaternion), so offset/multipart Setup shapes rotate in place and a same-pose
  cell crossing cannot retain an old flood seed.
- A retained projectile remains the same CPhysicsObj when Missile clears. With
  no MovementManager it continues through the ordinary one-sphere transition
  owner; with a MovementManager the owner transfers exactly once to remote
  motion. Projection re-entry restores its retained collision shadow on the
  visibility edge, before any later simulation quantum.
- Active interpolation preserves the target's complete quaternion and replaces
  the PartArray Frame. The already-close `InterpolateTo` branch applies only
  the target heading, matching `CPhysicsObj::set_heading`. `keep_heading` is
  manager-wide, not a per-node flag; each near enqueue replaces it.
- `FrameOps.SetRotate` rejects zero, non-finite, and otherwise invalid
  quaternion candidates by restoring the prior orientation.
- Spawn, teleport, correction, and outbound movement/position serialization
  read the authoritative body quaternion directly; none round-trips through
  the horizontal `Yaw` projection.
- `MotionTableDispatchSink` only dispatches motion-table commands. It no longer
  reports turn callbacks.
- `RemoteMotion.ObservedOmega`, the player/NPC multiplication-order fork, and
  `AnimationSequencer.SetCycle`'s synthetic `pi/2` turn omega are deleted.
- A controller deliberately constructed without a `PartArray` retains a
  Humanoid-only fallback at the DAT-pinned `1.5` radians/second. A normal GUI
  client does not enter that path.

## Conformance gates

- `MotionDeltaFrameTests`: exact `FrameOps.Combine` equivalence, scale affects
  origin only, and temporal turn-then-move composition.
- `RetailObjectQuantumClockTests`: strict bounds, retained remainder,
  MaxQuantum subdivision, HugeQuantum discard, `set_active` rebasing, and
  Static-aware `prepare_to_enter_world` reset.
- `RetailObjectActivityGateTests` and `LiveEntityRuntimeTests`: the 96-unit
  PartArray gate, parent/cell/Frozen suspension, loaded rebucket retention,
  pending re-entry rebasing, body/clock Active synchronization, and GUID-reuse
  clock isolation.
- `LiveEntityAnimationSchedulerTests`: the canonical live-object workset also
  advances objects without a render animation, consumes their queued near
  UpdatePosition correction, applies complete generic root
  Frames, transfers a retained missile body exactly once when classification
  clears, and stops catch-up immediately when a callback deletes, withdraws,
  or replaces an incarnation.
- `RetailStaticAnimatingObjectSchedulerTests` and
  `AnimationSequencerTests`: unconditional Setup DefaultAnimation installation,
  DAT/live physics-Static workset membership, direct 30-fps playback,
  short-residency-gap catch-up, canonical PartArray/body reuse, raw (not
  elapsed-scaled) omega, synchronized multipart shadow rotation, zero-omega
  no-op commits, callback-safe removal, and the retail greater-than-two-second
  discard. `StaticLiveRootCommitter` coverage proves Hidden omega cannot
  resurrect a suspended shadow.
- `RemoteInboundMotionDispatcherTests`: one animation-optional owner preserves
  retail packet-head/style/type-0/sticky ordering with a null PartArray sink;
  unknown movement types execute the head and never enter the case-0 funnel;
  supersession during interrupt prevents every later packet side effect.
- `LiveEntityOrdinaryPhysicsUpdaterTests`: complete root Frames cross cells and
  landblocks through Transition, while hook-side deletion prevents stale body,
  shadow, pose, or spatial commits.
- `ProjectileControllerTests`: pending-cell hydration restores the same body's
  Active/InWorld/shadow residency immediately and does not replay logical
  creation; the destination cell is canonical before suspension and after
  hydration, and authoritative Position/Vector/State between prediction halves
  discards only the stale candidate.
- `RetailInboundEventDispatcherTests`, `LiveEntityPresentationControllerTests`,
  `RemoteTeleportControllerTests`, and `EntityEffectPoseRegistryTests`: nested
  packet arrival drains after the complete older tail, independent State and
  Position both survive resolver callbacks, newer Position supersedes older
  placement, Hidden-to-Visible recursion remains FIFO, and hook batches cannot
  cross deletion/local-ID reuse during capture or drain. The FIFO's nonnested
  state path is pinned at zero allocations after warmup.
- `PlayerMovementControllerTests`: full-frame local composition, large-frame
  equivalence, hidden/airborne gates, hook cadence, and proof that
  animation-backed turns are not integrated twice.
- `InterpolationManagerTests`: complete relative target orientation,
  keep-heading, and already-close heading-only behavior.
- `RemotePhysicsUpdaterTests` and `LiveEntityPresentationControllerTests`:
  translation uses the pre-turn orientation and the same frame then rotates the
  body; cross-cell loaded-to-pending commits the destination root before the
  callback boundary, suspends rather than re-adds collision, restores on
  hydration, and isolates old shadows across callback GUID reuse. Direct
  authoritative rebuckets and initial-pending materialization cover the same
  symmetric collision-residency contract; same-position rotation and cell-only
  changes refresh collision while unchanged/sign-flipped quaternion poses do
  not reflood.
- `LiveEntityRuntimeTests`: update iteration and render-ID classification copy
  only concrete spatial animation owners through reusable storage with zero
  steady-state allocations.
- `MotionTableDispatchSinkTests`: Branch-4 turn preserves the locomotion cycle,
  contributes literal DAT omega, and unwinds on stop.
- `RemoteChaseEndToEndHarnessTests`: turn, chase, re-arm, action completion, and
  sticky following run through the complete Frame plus retail manager tail.
- `HumanoidMotionTableRootMotionTests`: installed retail walk displacement and
  exact Humanoid `TurnRight` omega `-1.5` radians/second.
- `MovementManagerTests` and `PlayerMovementControllerTests`:
  `PerformMovement` invokes `set_active(1)` before request validation, while a
  Static physics object preserves retail's no-op activation behavior.

## Registered residual

The ordinary/static object worksets and their root/animation clocks are now
retail-shaped, but acdream's shared particle and PhysicsScript managers still
advance once per render frame after every owner has run. Retail advances those
tails inside each admitted object update (and inside
`animate_static_object`). This timing difference is deliberately registered as
TS-51; it is not part of the R6 conformance claim.

Final automated gate (2026-07-20): three independent retail-conformance,
architecture/integration, and adversarial re-reviews reported no actionable
finding after correction; Release build completed with zero warnings; the full
solution passed 6,446 tests with 5 intentional skips.