acdream/docs/research/2026-07-02-r2-motiontable/r2-ace-motiontable.md

ACE MotionTable / MotionTableManager port — cross-reference map

Files read in full:

• references/ACE/Source/ACE.Server/Physics/Animation/MotionTable.cs (615 lines)
• references/ACE/Source/ACE.Server/Physics/Managers/MotionTableManager.cs (251 lines)
• references/ACE/Source/ACE.Server/Physics/Animation/AnimNode.cs (16 lines)
• references/ACE/Source/ACE.DatLoader/Entity/MotionData.cs (34 lines)
• Cross-refs: PhysicsObj.cs (L296-300, L653-657, L899-902), MovementManager.cs (L118-121), MotionInterp.cs (L210-231, L260), PartArray.cs (L52-56, L72-76, L135, L253-293, L425-435, L577-586), WeenieObject.cs (L256-259)

NOTE (important for the parent report): ACE has TWO parallel "pending motion" trackers that both descend from a PhysicsObj, and they are easy to conflate:

1. MotionTableManager.PendingAnimations (LinkedList<AnimNode>) — driven by Table.DoObjectMotion/GetObjectSequence (the interpreted-command / high-level motion path). Its AnimationDone/CheckForCompletedMotions are the ones requested for this doc.
2. MotionInterp.PendingMotions — a separate list inside MotionInterp.cs (not covered file, but referenced at MotionInterp.cs:210-231) that also has a MotionDone(bool success) method. MovementManager.MotionDone calls MotionInterpreter.MotionDone(success), i.e. the raw motion-interp side, NOT MotionTableManager.AnimationDone. MotionTableManager and MotionInterp are wired independently; MotionTableManager lives under PartArray, while MotionInterp lives under MovementManager. Both ultimately get fed by PhysicsObj.MotionDone but through different owner objects (PartArray.MotionTableManager vs MovementManager.MotionInterpreter), and only one of the two is authoritative depending on whether the object is server-simulated purely by object-broadcast Motion commands (uses MotionTableManager via PartArray) vs. by the mover's own physics timestep + MoveToManager (uses MotionInterp). Do not assume MotionTableManager.AnimationDone is "the" MotionDone path for player-driven movement — cross-check which owner actually gets ticked for the acdream use case before porting.

---

MotionTable.cs (ACE.Server.Physics.Animation.MotionTable)

Fields

uint ID
Dictionary<uint,uint> StyleDefaults              // style -> default substate
Dictionary<uint,MotionData> Cycles               // key = (style<<16)|substate  -> cycle anim data
Dictionary<uint,MotionData> Modifiers            // key = (style<<16)|modifierID or just modifierID -> modifier anim data
Dictionary<uint,Dictionary<uint,MotionData>> Links   // key = (style<<16)|fromSubstate -> { toMotion -> transition MotionData }
uint DefaultStyle
static ConcurrentDictionary<uint,float> WalkSpeed / RunSpeed / TurnSpeed   // per-motionTableID cache

Constructed either empty (Allocator()) or from the dat-loaded DatLoader.FileTypes.MotionTable (straight field copy, no transform — L40-48).

DoObjectMotion(motion, currState, sequence, speedMod, ref numAnims)

Trivial forwarder: return GetObjectSequence(motion, currState, sequence, speedMod, ref numAnims, stopModifiers: false); (L55-58)

GetObjectSequence(motion, currState, sequence, speedMod, ref numAnims, stopModifiers) — L60-257

The core state-transition dispatcher. numAnims is reset to 0 up front.

Early-out: if currState.Style == 0 || currState.Substate == 0 → false (uninitialized state).

Looks up substate = StyleDefaults[currState.Style] (the default substate for the current style, e.g. "Standing" under style "NonCombat").

Guard (L73-74): if motion == substate (i.e. caller is asking to enter the style's own default substate) AND !stopModifiers AND current substate already has the Modifier bit set (CommandMask.Modifier) → return true immediately (no-op — already effectively there via a modifier).

Then four command-mask branches, checked with plain OR semantics — NOT else-if. Each branch can independently fire and return true from inside if it succeeds; falling out of a branch (motionData null, is_allowed false, etc.) falls through to the next mask check.

CommandMask.Style branch (L76-120) — motion requests a stance/style change (e.g. switch combat stance):

• If currState.Style == motion already → true (no-op).
• If substate != currState.Substate: compute motionData = get_link(currState.Style, currState.Substate, currState.SubstateMod, substate, speedMod) — the transition INTO the new style's default substate from the current substate.
• If substate != 0: look up cycles = Cycles[(motion<<16)|substate] — the cycle anim for the new style's default substate.
  • If found:
    • (cycles.Bitfield & 1) != 0 → currState.clear_modifiers() (bit 1 = "clears modifiers on entry", e.g. entering a stance that can't carry over swimming/etc modifiers).
    • link = get_link(currState.Style, substate, currState.SubstateMod, motion, speedMod) — transition from (old style, NEW style's default substate) to the target style itself.
    • Fallback chain if link == null and currState.Style != motion: re-resolve via DefaultStyle — link = get_link(currState.Style, substate, 1.0f, DefaultStyle, 1.0f), then motionData_ = get_link(DefaultStyle, StyleDefaults[DefaultStyle], 1.0f, motion, 1.0f). This is the "no direct link exists, route through the global default style" path (e.g. Standing).
    • sequence.clear_physics(); sequence.remove_cyclic_anims(); — wipe outstanding velocity/ omega contributions and any looping cycle anims before splicing in the new chain.
    • Append in strict order: add_motion(motionData), add_motion(link), add_motion(motionData_), add_motion(cycles) — i.e. [transition-to-default-substate] → [transition-to-target-style] → [fallback-via-default-style, usually null] → [new cycle]. Each add_motion no-ops silently on null motionData.
    • Commits state: currState.Substate = substate; currState.Style = motion; currState.SubstateMod = speedMod;
    • re_modify(sequence, currState) — replays any still-active modifiers (see below) on top of the newly spliced sequence.
    • numAnims = sum of each non-null MotionData's Anims.Count, minus 1 (the -1 is because the queue entry itself represents completion of ONE playthrough of the LAST appended motion's cycle, not a raw anim count — cross-check against add_to_queue in MotionTableManager, which stores this count as AnimNode.NumAnims, i.e. the number of "hook" firings, one per queued sub-anim minus a terminal borrow).
    • Returns true.

CommandMask.SubState branch (L121-188) — motion requests a substate change within the current style (e.g. Standing → Crouching), OR a coalesced-speed no-op update to the CURRENT cycle:

• motionID = motion & 0xFFFFFF (strip command-class bits).
• motionData = Cycles[(currState.Style<<16)|motionID], falling back to Cycles[(DefaultStyle<<16)|motionID] if the current style doesn't define that substate.
• If found and is_allowed(motion, motionData, currState) (see below):
  • Speed-only fast path (L132-139): if motion == currState.Substate AND sequence.HasAnims() AND Math.Sign(speedMod) == Math.Sign(currState.SubstateMod) — i.e. caller is re-issuing the SAME substate at a new speed, same direction of travel (fwd vs reverse) — then: change_cycle_speed (rescale the already-playing cyclic anim's framerate), subtract_motion (remove the old velocity/omega contribution at the old speed), combine_motion (add back at the new speed), update currState.SubstateMod = speedMod, return true. No new anims queued, no sequence splice — this is the "already running, just changing speed" branch (e.g. walk→run without breaking stride).
  • Otherwise (new substate, or sign flip == direction reversal):
    • (motionData.Bitfield & 1) != 0 → currState.clear_modifiers().
    • link = get_link(currState.Style, currState.Substate, currState.SubstateMod, motion, speedMod) — direct transition from current substate to target substate.
    • Fallback (L145-151): if link == null OR the sign of speedMod differs from currState.SubstateMod (direction reversal, e.g. forward↔backward) — route through the style's default substate: link = get_link(currState.Style, currState.Substate, currState.SubstateMod, defaultMotion, 1.0f) (transition out to default), motionData_ = get_link(currState.Style, defaultMotion, 1.0f, motion, speedMod) (transition from default into target).
    • sequence.clear_physics(); sequence.remove_cyclic_anims();
    • If motionData_ != null (fallback path taken): append link at currState.SubstateMod, then motionData_ at speedMod.
    • Else (direct link path): newSpeedMod = speedMod, but flip sign if currState.SubstateMod < 0 && speedMod > 0 (i.e. reversing FROM negative — asymmetric handling, only corrects one direction of sign mismatch, not both) — append link at newSpeedMod.
    • Always append motionData (the new cycle) at speedMod.
    • Modifier carry-over (L170-176): if the OLD substate differs from the new motion AND the old substate had the Modifier bit set, AND the old substate isn't just the style's default motion, re-add it as an active modifier via currState.add_modifier_no_check (i.e. modifiers riding on a substate survive a substate change unless they equal the new target or the style default).
    • Commit currState.SubstateMod = speedMod; currState.Substate = motion;, then re_modify.
    • numAnims = motionData.Anims.Count + link.Anims.Count + motionData_.Anims.Count - 1 (nulls treated as 0).
    • Returns true.

CommandMask.Action branch (L189-233) — one-shot action motions (attacks, jumps, etc, things layered on TOP of a cycle without replacing it):

• cycleKey = (currState.Style<<16)|(currState.Substate & 0xFFFFFF); motionData = Cycles[cycleKey] (the CURRENT cycle, must exist).
• If found:
  • link = get_link(currState.Style, currState.Substate, currState.SubstateMod, motion, speedMod).
  • If link != null (direct action link exists): currState.add_action(motion, speedMod) (push onto the action stack — see MotionState, not read this pass), clear physics/cyclic, append link at speedMod then re-append motionData (the ORIGINAL cycle, at the OLD currState.SubstateMod — i.e. resume the cycle after the action plays), re_modify, numAnims = link.Anims.Count (note: NOT including motionData's count here — only the action-link portion counts toward completion tracking, the re-appended base cycle is presumably a normal looping anim not subject to the same "done" semantics).
  • Else (no direct action link — fallback via style default, L209-231): motionData = get_link(currState.Style, currState.Substate, currState.SubstateMod, substate, 1.0f) (transition current substate → style's own default substate) as a NEW motionData (shadows the cycle lookup above). If that resolves: link = get_link(currState.Style, substate, 1.0f, motion, speedMod) (default substate → action), and re-fetch cycles = Cycles[cycleKey] (original cycle again). If link != null and cycles found: motionData_ = get_link(currState.Style, substate, 1.0f, currState.Substate, currState.SubstateMod) (default substate → back to original substate, for resuming after). currState.add_action(...), clear physics/cyclic, append in order motionData (→default), link (default→action), motionData_ (default→back), cycles (resume original cycle at currState.SubstateMod). re_modify. numAnims = motionData.Anims.Count + link.Anims.Count + (motionData_ != null ? motionData.Anims.Count : 0) — NOTE: this last term reads motionData.Anims.Count again, NOT motionData_.Anims.Count — looks like a copy- paste bug in ACE's port (compare to the Style/SubState branches which correctly sum each distinct MotionData). Flag this explicitly when cross-checking against 2013 retail — likely a genuine ACE divergence, not a retail behavior to replicate.

CommandMask.Modifier branch (L234-255) — continuous modifiers layered on the current cycle (e.g. sneaking, aiming overlay) that don't interrupt it:

• styleKey = currState.Style<<16; cycles = Cycles[styleKey|(currState.Substate&0xFFFFFF)] (current cycle must exist).
• If found AND (cycles.Bitfield & 1) == 0 (cycle does NOT forbid modifiers):
  • motionData = Modifiers[styleKey|(motion&0xFFFFFF)], falling back to Modifiers[motion&0xFFFFFF] (style-agnostic modifier) if not found.
  • If found:
    • if (!currState.add_modifier(motion, speedMod)) — if the state rejects adding this modifier (e.g. already present / list full):
      • StopSequenceMotion(motion, 1.0f, currState, sequence, ref numAnims) — force-remove it first, then retry add_modifier. If STILL fails, return false.
    • combine_motion(sequence, motionData, speedMod) — layer the modifier's velocity/omega + anims onto the sequence WITHOUT clearing physics or cyclic anims (additive, unlike the other three branches which splice/replace).
    • Returns true. No numAnims write here — stays whatever it was reset to (0) at entry, i.e. modifiers are not tracked for animation-completion purposes.

Falls through all four branches unmatched → return false.

Get(uint motionTableID) — static factory, L259-264

Directly DatManager.PortalDat.ReadFromDat<FileTypes.MotionTable>(id) wrapped in new MotionTable(...). Comment //return ObjCache.GetMotionTable(mtableID); — retail apparently caches motion tables by ID; ACE re-reads from dat every call (no caching layer here, though the dat reader itself likely caches file reads elsewhere).

SetDefaultState(state, sequence, ref numAnims) — L266-291

Resets to the table's global default (style, substate) pair:

• defaultSubstate = StyleDefaults[DefaultStyle]; if missing → false.
• state.clear_modifiers(); state.clear_actions();
• cycle = (DefaultStyle<<16)|defaultSubstate; motionData = Cycles[cycle]; if missing → false.
• numAnims = motionData.Anims.Count - 1.
• state.Style = DefaultStyle; state.Substate = defaultSubstate; state.SubstateMod = 1.0f;
• sequence.clear_physics(); sequence.clear_animations(); (note: clear_animations, not remove_cyclic_anims — a harder reset, used only here and presumably at spawn/enter-world).
• add_motion(sequence, motionData, 1.0f).

StopObjectCompletely(currState, sequence, ref numAnims) — L293-313

Iterates and removes ALL active modifiers via StopSequenceMotion (loop drains currState.Modifiers.First until empty — relies on StopSequenceMotion removing the head each call), tracking whether ANY modifier stop succeeded (success). Then stops the current substate itself: StopSequenceMotion(currState.Substate, currState.SubstateMod, ...). Returns true if EITHER the substate-stop succeeded OR any earlier modifier-stop succeeded (success || substateStopSucceeded, though written as an if/else that returns true whenever the final substate-stop call returns non-... — re-read: if (!StopSequenceMotion(...)) return success; else return true; — i.e. final result is true unless the LAST stop call fails, in which case it falls back to whatever success was from the modifier loop).

StopObjectMotion / StopSequenceMotion — L315-356

StopObjectMotion is a trivial forwarder to StopSequenceMotion.

StopSequenceMotion(motion, speed, currState, sequence, ref numAnims):

• numAnims = 0.
• SubState case: if (motion & CommandMask.SubState) != 0 && currState.Substate == motion — i.e. caller wants to stop the CURRENT substate → resolve the style's default substate and re-enter it via GetObjectSequence(style, currState, sequence, 1.0f, ref numAnims, stopModifiers: true) (recursion into the main dispatcher with stopModifiers=true, which suppresses the early "already at default via modifier" guard at L73). Returns true unconditionally after this call (return value of the inner GetObjectSequence is discarded).
• Non-modifier, non-matching-substate case: if (motion & CommandMask.Modifier) == 0 → false (nothing to stop — motion isn't a substate-stop or a modifier).
• Modifier case: linear-scan currState.Modifiers linked list for a node whose .ID == motion. On match:
  • key = (currState.Style<<16)|(motion&0xFFFFFF); Modifiers[key], falling back to Modifiers[motion&0xFFFFFF]. If neither resolves → false.
  • subtract_motion(sequence, motionData, modifier.Value.SpeedMod) — reverse the modifier's velocity/omega contribution using its ORIGINAL speed (not the speed parameter passed in — speed param appears unused in this branch; only used implicitly via the SubState-case call above). currState.remove_modifier(modifier). Returns true.
  • No match found after scanning entire list → false.

add_motion / combine_motion / subtract_motion / change_cycle_speed — L358-393

• add_motion(sequence, motionData, speed): no-op if motionData == null. Otherwise sequence.SetVelocity(motionData.Velocity * speed), sequence.SetOmega(motionData.Omega * speed) (REPLACES, not adds — "Set" not "Combine"), then for each anim in motionData.Anims wraps as new AnimData(anim, speed) and sequence.append_animation(animData).
• combine_motion(sequence, motionData, speed): no-op if null. Otherwise sequence.CombinePhysics(motionData.Velocity * speed, motionData.Omega * speed) — additive variant used by the Modifier branch (doesn't touch the anim queue at all, only velocity/omega).
• subtract_motion(sequence, motionData, speed): no-op if null. sequence.subtract_physics (motionData.Velocity * speed, motionData.Omega * speed) — inverse of combine, used when removing a modifier or an old-speed cycle contribution.
• change_cycle_speed(sequence, motionData, substateMod, speedMod): if |substateMod| > PhysicsGlobals.EPSILON → sequence.multiply_cyclic_animation_framerate (speedMod/substateMod) (rescale by the RATIO of new to old speed). Else-if |speedMod| < EPSILON → multiply_cyclic_animation_framerate(0) (freeze the anim — old speed was ~0 so no ratio is definable, new speed is also ~0). Gap: if substateMod ~0 AND speedMod is NON-zero, neither branch fires — no framerate change is applied. Worth checking against retail whether this is a real edge case (resuming a stopped cycle at nonzero speed without a ratio) — could be a silent no-op bug carried from retail or an ACE gap.

get_link(style, substate, substateSpeed, motion, speed) — L395-426

Direction-aware transition lookup with two symmetric lookup CHAINS depending on sign of the speeds:

• If EITHER speed < 0 or substateSpeed < 0 (reverse-direction transition): look up Links[(style<<16)|(motion&0xFFFFFF)] (keyed by DESTINATION motion) then .TryGetValue (substate, ...) (indexed by SOURCE substate) — i.e. reversed key order vs the forward case. If that fails, fall back through StyleDefaults[style] and Links[(style<<16)|(substate&0xFFFFFF)] → .TryGetValue(defaultMotion, ...).
• Else (forward / non-negative speeds): look up Links[(style<<16)|(substate&0xFFFFFF)] (keyed by SOURCE substate) then .TryGetValue(motion, ...) (indexed by DESTINATION). Fallback: Links[style<<16] (style-wide, substate-agnostic) → .TryGetValue(motion, ...).
• Returns null if nothing resolves in either chain. This encodes retail's dat-side Links table having asymmetric (from,to) vs (to,from) storage depending on animation reversibility — reverse playback (e.g. walking backward) reuses the FORWARD anim's link table keyed the other way around rather than storing a mirrored copy.

is_allowed(motion, motionData, state) — L428-438

false if motionData == null. true if (motionData.Bitfield & 2) == 0 (bit 2 = "always allowed" flag) OR motion == state.Substate (re-entering the same substate is always allowed regardless of the bit). Otherwise: only allowed if the CURRENT substate IS the style's own default substate (StyleDefaults[state.Style] == state.Substate) — i.e. bit-2-gated substates can only be entered FROM the style's default/neutral substate, not chained from an arbitrary other substate.

re_modify(sequence, pstate) — L440-458

No-op if pstate.Modifiers.First == null. Otherwise snapshots pstate into a NEW MotionState state = new MotionState(pstate) (deep-ish copy incl. its own Modifiers list), then drains pstate's modifier list one node at a time: pops speedMod/motion off pstate.Modifiers.First, removes the SAME logical entry from BOTH pstate and the snapshot state (odd double-removal — removing from the snapshot copy seems purposeless unless MotionState's copy ctor shares the underlying list nodes, in which case this is defensive against aliasing), then calls GetObjectSequence(motion, pstate, sequence, speedMod, ref numAnims, stopModifiers: false) to RE-APPLY each modifier on top of the now-current (post-transition) pstate. This is how the Style/SubState branches "carry forward" active modifiers across a cycle-changing transition — after splicing the new base cycle in, re_modify walks the still-active modifier list (which at that point is whatever the branch didn't already clear) and re-runs each one through the full dispatcher so its layered anims/physics get re-appended onto the NEW sequence.

Static helpers (L460-613)

• GetAttackFrames(motionTableId, stance, motion) — dat-lookup passthrough to DatLoader.FileTypes.MotionTable.GetAttackFrames (not in this file). Returns cached emptyList for motionTableId == 0.
• GetAnimationLength(motionTableId, stance, motion, speed=1) / the 2-motion overload that also takes currentMotion — the latter, if motion has the Style bit set and currentMotion != Ready, first adds the Ready→currentMotion transition length, forces currentMotion = Ready, THEN adds currentMotion→motion. Divides everything by speed.
• GetCycleLength — dat passthrough / speed.
• GetRunSpeed(motionTableID) — cached in static RunSpeed dict. Computes via GetMotionData(id, MotionCommand.RunForward) → GetAnimDist(motionData).
• GetTurnSpeed(motionTableID) — cached in static TurnSpeed dict. Math.Abs(GetMotionData(id, MotionCommand.TurnRight).Omega.Z).
• GetMotionData(motionTableID, motion, currentStyle=null) — resolves currentStyle to motionTable.DefaultStyle if unspecified, strips command bits (motion & 0xFFFFFF), looks up Cycles[(style<<16)|motionID].
• GetLinkData(motionTableID, motion, currentStyle=null) — looks up Links[(style<<16)|((int)MotionCommand.Ready & 0xFFFF)] (NOTE: masks with 0xFFFF here, NOT 0xFFFFFF like everywhere else in this file — inconsistent mask width, likely harmless since MotionCommand.Ready's low bits fit in 16 bits, but worth flagging as an ACE inconsistency if porting verbatim), then .TryGetValue(motion, ...).
• GetAnimDist(motionData) — sums frame.Origin across every PosFrames frame of every anim in motionData.Anims (reads each Animation fresh from dat by anim.AnimId), takes .Length() of the summed offset vector, divides by totalFrames, multiplies by motionData.Anims[0].Framerate → "distance per second". Returns 0 if the vector length is 0.
• HasDefaultScript(motionTableID, motion, currentStyle) — GetLinkData then scans every anim's PartFrames[*].Hooks for AnimationHookType.DefaultScript.

---

MotionTableManager.cs (ACE.Server.Physics.Managers.MotionTableManager) — owned by PartArray

Fields

PhysicsObj PhysicsObj
MotionTable Table
MotionState State
uint AnimationCounter
LinkedList<AnimNode> PendingAnimations

AnimNode { uint Motion; uint NumAnims; } (trivial struct-like class, AnimNode.cs).

AnimationDone(bool success) — L28-61

Called from PartArray.AnimationDone ← PhysicsObj.Hook_AnimDone() (fired when a per-frame animation HOOK signals completion — the frame-based Hook_AnimDone callback, NOT a polling check). Logic:

• If PendingAnimations.First == null → no-op (nothing pending).
• AnimationCounter++ (one hook fired, counts toward the FIRST queued AnimNode's NumAnims threshold).
• Loop while node != null:
  • entry = node.Value. If entry.NumAnims > AnimationCounter → break (head entry hasn't accumulated enough hook-fires yet — stop, this increment wasn't enough to finish it).
  • If entry's motion has the Action bit set → State.remove_action_head() (pop the action stack — the completed queue entry was an action, so remove its tracking entry from MotionState).
  • motionID = entry.Motion; PhysicsObj.MotionDone(motionID, success) — fires the completion callback chain (→ MovementManager.MotionDone → MotionInterpreter.MotionDone, see note at top: this is the OTHER pending-motion tracker, decoupled from this one except by sharing the PhysicsObj "owner").
  • AnimationCounter -= entry.NumAnims (consume the threshold — any EXCESS hooks beyond this entry's requirement roll over to satisfy the NEXT queued entry, hence the outer do...while loop can complete MULTIPLE queue entries from ONE AnimationDone call if AnimationCounter still exceeds the next entry's NumAnims).
  • If PendingAnimations.First != null → RemoveFirst() (dequeue the just-completed entry).
  • If PhysicsObj.WeenieObj != null → WeenieObj.OnMotionDone(motionID, success) (separate weenie-level hook, forwards to WorldObject.HandleMotionDone — the game-logic-facing callback, distinct from the physics-level PhysicsObj.MotionDone).
  • node = PendingAnimations.First (re-check for another completable entry).
• After the loop: if AnimationCounter != 0 && node == null (queue fully drained but counter still has leftover) → reset AnimationCounter = 0 (defensive clamp — discards any leftover hook-credit once nothing remains queued, rather than carrying it forward to a future add_to_queue call).

CheckForCompletedMotions() — L63-85

Called from PartArray.CheckForCompletedMotions ← PhysicsObj.CheckForCompletedMotions() — this one is POLLED (search found no evidence of a per-frame automatic caller within these two files; likely ticked once per physics update from PhysicsObj.UpdateObjectInternal or similar, not confirmed in this pass — flag for follow-up if the caller chain matters). Distinct from AnimationDone: this drains any HEAD entries whose NumAnims == 0 already (i.e. entries that never needed any hook fires to complete — e.g. zero-length transitions), NOT counter-driven:

• Loop while PendingAnimations.First != null:
  • If pendingAnimation.Value.NumAnims != 0 → return (head isn't a zero-length entry — stop, do NOT touch AnimationCounter, this is purely for immediate 0-anim entries).
  • Otherwise: pop the same way as AnimationDone (Action-bit → RemoveActionHead, PhysicsObj.MotionDone(motionID, true) (always success=true here — no success param on this method), remove from list, WeenieObj.OnMotionDone(motionID, true).
  • Continues looping (could drain several consecutive 0-NumAnims entries in one call).

PerformMovement(mvs, seq) — L116-145

Dispatches on mvs.Type (MovementStruct.Type):

• Table == null → WeenieError.NoAnimationTable.
• InterpretedCommand: Table.DoObjectMotion(mvs.Motion, State, seq, mvs.Params.Speed, ref counter); if it returns false → WeenieError.NoMtableData. Else add_to_queue(mvs.Motion, counter, seq), return None.
• StopInterpretedCommand: Table.StopObjectMotion(mvs.Motion, mvs.Params.Speed, State, seq, ref counter); failure → NoMtableData. Success → add_to_queue((uint)MotionCommand.Ready, counter, seq) (note: queues under MotionCommand.Ready, NOT mvs.Motion — a stop always enqueues completion-tracking keyed to Ready, regardless of what was stopped).
• StopCompletely: Table.StopObjectCompletely(State, seq, ref counter) (return value ignored), add_to_queue((uint)MotionCommand.Ready, counter, seq), return None unconditionally.
• default: WeenieError.None (comment // ?? — ACE itself flags this as uncertain; other MovementType values like RawCommand/StopRawCommand fall through here untouched by this manager, presumably handled instead by MotionInterp.PerformMovement).

SetMotionTableID(mtableID) — Table = MotionTable.Get(mtableID); return Table != null;

UseTime() — CheckForCompletedMotions(); — the manager's per-tick entry point (called

from PartArray.cs:265, itself presumably ticked from PhysicsObj's per-update pass — same follow-up caveat as above).

add_to_queue(motion, num_anims, sequence) — L163-167

PendingAnimations.AddLast(new AnimNode(motion, num_anims)), then immediately remove_redundant_links(sequence) — every enqueue triggers a redundancy pass over the WHOLE list (not just checking the new tail against its immediate predecessor blindly; see below).

initialize_state(sequence) — L169-177

numAnims = 0; if Table != null → Table.SetDefaultState(State, sequence, ref numAnims). Always add_to_queue((uint)MotionCommand.Ready, numAnims, sequence) regardless of whether SetDefaultState succeeded (numAnims stays 0 on failure, so this enqueues a same-tick-complete Ready entry).

remove_redundant_links(sequence) — L179-205

Walks PendingAnimations from tail to head (node = PendingAnimations.Last, then node.Previous). For each entry with NumAnims != 0:

• If the entry's motion does NOT have the SubState bit set, OR it DOES have the Modifier bit set (i.e. it's a Style/Action/Modifier-class entry, not a plain substate cycle): only proceed if it also has the Style bit set (entry.Motion & CommandMask.Style), else return (stop scanning entirely — non-style, non-substate-eligible entries block further redundancy checking). If Style-bit set: call remove_redundant_links_inner(node, sequence, first: true); if it returns true → return (done, something was truncated).
• Else (a plain substate-cycle entry): remove_redundant_links_inner(node, sequence, first: false); if true → return.
• Otherwise continue to node = node.Previous (walk further back toward the head).

remove_redundant_links_inner(node, sequence, first) — L207-231

Scans BACKWARD from node.Previous looking for an earlier entry with the SAME Motion value:

• motion = first ? 0x70000000 : 0xB0000000 — these are raw CommandMask-shaped bit patterns used as an early-abort guard (0x70000000 covers Style|SubState|Action bits per typical AC command-mask layout; 0xB0000000 a different combination — exact bit semantics live in CommandMask enum, not read this pass, but functionally: differing abort masks depending on whether we're scanning for a Style-class or SubState-class duplicate).
• While walking back (prev = prev.Previous each iteration):
  • If prevEntry.Motion == entry.Motion AND (first is true, OR prevEntry.NumAnims != 0) → found a duplicate → trancuate_animation_list(prev, sequence), return true.
  • Else if prevEntry.NumAnims != 0 && (prevEntry.Motion & motion) != 0 → an intervening entry of the "abort mask" class with pending anims blocks the search → return true WITHOUT truncating (stops the outer loop but did nothing — prevents redundancy removal across a still-animating Style/Action boundary).
  • Else continue.
• If the walk exhausts (prev == null) without matching → return false (caller's outer loop continues scanning further back from the ORIGINAL node).

trancuate_animation_list(node, sequence) — L233-249 (note: "trancuate" — misspelling of

"truncate" preserved verbatim from ACE source, matches the mismatched name used at the call site remove_redundant_links_inner) Walks from PendingAnimations.Last backward toward (but not including) node: sums every visited entry's NumAnims into totalAnims, then zeroes each entry's NumAnims in place (entry.Value.NumAnims = 0 — does NOT remove them from the list, just neuters their completion-tracking contribution). Finally sequence.remove_link_animations(totalAnims) — tells the Sequence to physically drop that many trailing "link" animations from its playback queue (the actual anim-clip splice), while PendingAnimations keeps the now-inert AnimNode entries in place with NumAnims=0 (they'll be silently skipped/instantly-completed by CheckForCompletedMotions's 0-check, or bypass AnimationDone's counter entirely since their threshold is unreachable-but-trivially-satisfied at 0... actually re-check: AnimationDone's break condition is entry.NumAnims > AnimationCounter; with NumAnims == 0 this is never true, so a zeroed entry always immediately qualifies for completion processing on the NEXT AnimationDone call, consistent with CheckForCompletedMotions also draining 0-count heads).

---

MotionDone hook chain (full call graph, both trackers)

PhysicsObj.Hook_AnimDone()                         [per-frame anim-hook fire from Sequence/AFrame dispatch]
  -> PartArray.AnimationDone(true)
     -> MotionTableManager.AnimationDone(true)      [drains PendingAnimations by counter]
        -> PhysicsObj.MotionDone(motionID, success)
           -> MovementManager.MotionDone(motion, success)
              -> MotionInterpreter.MotionDone(success)   [SEPARATE tracker: MotionInterp.PendingMotions]
        -> PhysicsObj.WeenieObj.OnMotionDone(motionID, success)
           -> WorldObject.HandleMotionDone(motionID, success)   [game-logic level]

PhysicsObj.CheckForCompletedMotions()              [polled, presumably per physics tick]
  -> PartArray.CheckForCompletedMotions()
     -> MotionTableManager.CheckForCompletedMotions()  [drains 0-NumAnims heads only]
        -> (same PhysicsObj.MotionDone / WeenieObj.OnMotionDone chain as above)

MotionInterp.MotionDone(success)  [the OTHER path — NOT reached via MotionTableManager]
  -> pops MotionInterp.PendingMotions.First
  -> if Action bit set: PhysicsObj.unstick_from_object(), InterpretedState.RemoveAction(),
     RawState.RemoveAction()
  -> PhysicsObj.IsAnimating = PendingMotions.Count > 0

Key divergence risk for acdream: MovementManager.MotionDone ALWAYS routes to MotionInterpreter.MotionDone, never to MotionTableManager. The two trackers are fed by DIFFERENT owners (PartArray.MotionTableManager vs MovementManager.MotionInterpreter) and PhysicsObj.MotionDone(motion, success) only calls the MovementManager one (PhysicsObj.cs:899-902). MotionTableManager.AnimationDone/CheckForCompletedMotions DO call PhysicsObj.MotionDone internally (feeding MotionInterp), but nothing in these two files calls BACK from MotionInterp into MotionTableManager — i.e. MotionTableManager is upstream of MotionInterp in the completion-notification chain, not a peer. When porting to acdream's CMotionInterp-based unification (per the D6.2a work already landed), confirm which ACE class maps to which acdream responsibility — likely MotionTableManager ≈ acdream's discrete-command completion queue (attached per-PartArray/per-object), MotionInterp ≈ acdream's CMotionInterp-normalized local-player path (attached per-MovementManager). Do not assume they merge into one queue — ACE keeps them structurally separate even though both trace back to the same PhysicsObj.

Flagged ACE-side oddities (verify against 2013 retail decomp before porting verbatim)

1. Action-branch numAnims miscalculation (GetObjectSequence L227): fallback Action path sums motionData.Anims.Count TWICE instead of once for motionData and once for motionData_ — looks like a copy-paste error in ACE's port, not necessarily retail-faithful.
2. change_cycle_speed silent no-op gap (L372-379): when substateMod ≈ 0 AND speedMod is nonzero, neither branch fires — no framerate adjustment applied. Check retail's change_cycle_speed equivalent for a third branch.
3. GetLinkData mask width inconsistency (L562): uses & 0xFFFF where every other motion-ID mask in this file uses & 0xFFFFFF. Likely harmless (Ready's ID fits in 16 bits) but inconsistent.
4. StopObjectCompletely return-value semantics (L293-313): returns true unless the FINAL substate-stop call fails, in which case it falls back to whatever success was from the modifier-draining loop — easy to misport if simplified to a single boolean accumulate.
5. re_modify double-removal from both pstate and a snapshot state (L440-458): only makes sense if MotionState's copy constructor shares the underlying LinkedList<Motion> nodes with the source, which would make the second state.remove_modifier(...) call either redundant or (if lists are NOT shared) load-bearing to unlink from the snapshot's OWN list — not verifiable without reading MotionState.cs's copy ctor (out of scope this pass).

Files NOT read this pass (would need separate grep if pursued)

• MotionState.cs (referenced constantly: .Modifiers, .add_modifier, .add_modifier_no_check, .remove_modifier, .clear_modifiers, .add_action, .remove_action_head, .clear_actions, copy constructor semantics)
• MotionInterp.cs full file (only L190-260 read; PendingMotions, enter_default_state, apply_current_movement, get_leave_ground_velocity not traced)
• Sequence.cs (SetVelocity, SetOmega, CombinePhysics, subtract_physics, append_animation, clear_physics, remove_cyclic_anims, clear_animations, remove_link_animations, multiply_cyclic_animation_framerate, HasAnims, remove_all_link_animations)
• CommandMask enum exact bit values (Style/SubState/Action/Modifier)
• WeenieObject.HandleMotionDone in AC.Server (game-logic side, outside Physics/)