erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(anim): MultiplyCyclicFramerate — retail mid-cycle speed change

Browse source 
When the server broadcasts a mid-run UpdateMotion with a different
ForwardSpeed (e.g. the player's RunRate changes due to stamina / skill
update), acdream must NOT restart the cycle — that would reset the
footstep cursor and look like a visible twitch. Retail handles this via
Sequence.multiply_cyclic_animation_framerate (ACE
references/ACE/Source/ACE.Server/Physics/Animation/Sequence.cs L277-L287),
which walks the cyclic tail of the queue and scales each node's
framerate by newSpeed / oldSpeed. MotionTable.change_cycle_speed
(MotionTable.cs L372-L379) is the caller from the same-motion path in
GetObjectSequence (L132-L139).

This commit:

1. Adds AnimNode.MultiplyFramerate(factor) — scales a single node's
   framerate. Retail also swapped StartFrame↔EndFrame for negative
   factors; acdream keeps StartFrame ≤ EndFrame as an invariant and
   encodes direction via Framerate sign (see existing comment in
   LoadAnimNode), so we only scale. Valid because callers only ever
   pass positive factors from UpdateMotion ForwardSpeed.

2. Adds AnimationSequencer.MultiplyCyclicFramerate(factor) — walks
   _firstCyclic through the tail and calls node.MultiplyFramerate(factor).
   Also scales each node's Velocity and Omega by the same factor so
   CurrentVelocity / CurrentOmega stay aligned with playback — matches
   ACE's subtract_motion + combine_motion pair in change_cycle_speed.

3. Adds AnimationSequencer.CurrentSpeedMod public property — starts at
   1.0, updated by SetCycle on both restart and mid-cycle rescale.

4. Adds a speed-change fast-path to SetCycle: when the (style, motion)
   pair matches the current cycle and signs agree,
   MultiplyCyclicFramerate(newSpeed/oldSpeed) is called instead of
   rebuilding the queue — the cursor stays where it is and the animation
   continues at the new rate.

5. Wires InterpretedMotionState.ForwardSpeed from UpdateMotion through
   to SetCycle in OnLiveMotionUpdated. ACE omits the ForwardSpeed flag
   when speed == 1.0 (InterpretedMotionState.cs:101-103), so we default
   missing/zero values to 1.0.

Tests: 4 new sequencer tests covering MultiplyCyclicFramerate,
cursor preservation across speed changes, the same-motion-different-speed
fast-path, and the same-motion-same-speed no-op guard. 632 tests green
(was 628).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-04-19 10:26:55 +02:00
parent 63b6922fc2
commit afafefd71f
3 changed files with 250 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

86
src/AcDream.Core/Physics/AnimationSequencer.cs
View file

@ -121,6 +121,26 @@ internal sealed class AnimNode
Omega = omega;
}
// ── FUN_005267E0 — multiply_framerate ─────────────────────────────────
// Scales this node's framerate by a factor. Used by
// AnimationSequencer.MultiplyCyclicFramerate to retarget an already-queued
// cyclic animation at a new playback speed without restarting.
//
// Retail's implementation additionally swapped StartFrame↔EndFrame for a
// negative factor (so the forward-playback advance loop could traverse
// either direction), but acdream's AnimNode keeps StartFrame ≤ EndFrame
// as an invariant and encodes direction purely via Framerate's sign — the
// Advance loop then checks against StartFrame as the lower bound for
// negative delta. So here we only scale.
//
// Mirrors ACE AnimSequenceNode.multiply_framerate / Sequence.cs L277-L287
// modulo the swap difference. Valid because the callers we care about
// (ForwardSpeed updates from UpdateMotion) only ever pass positive factors.
public void MultiplyFramerate(double factor)
{
Framerate *= factor;
}
// ── FUN_00526880 — GetStartFramePosition ──────────────────────────────
// Returns the initial framePosition cursor for this node.
// speedScale >= 0 → (double)startFrame
@ -200,6 +220,14 @@ public sealed class AnimationSequencer
/// <summary>Current cyclic motion command.</summary>
public uint CurrentMotion { get; private set; }
/// <summary>
/// Speed multiplier currently applied to the cyclic tail. Starts at 1.0
/// and is updated by <see cref="SetCycle"/> when the same motion is
/// re-issued with a different speed (which triggers
/// <see cref="MultiplyCyclicFramerate"/> instead of a cycle restart).
/// </summary>
public float CurrentSpeedMod { get; private set; } = 1f;
/// <summary>
/// World-space per-second velocity from the currently active
/// <see cref="MotionData"/> (Sequence.Velocity in retail). Zero when no
@ -313,10 +341,26 @@ public sealed class AnimationSequencer
break;
}
// Fast-path: already playing this exact motion at the same speed.
// Fast-path: already playing this exact motion.
//
// Retail (ACE MotionTable.cs:132-139): when motion == current and
// sign(speedMod) matches, DON'T restart the cycle — just rescale the
// in-flight cyclic-tail's framerate via multiply_cyclic_animation_framerate.
// This keeps the run/walk loop smooth when a new UpdateMotion arrives
// with a different ForwardSpeed (e.g. when the server broadcasts a
// player's updated RunRate mid-step).
if (CurrentStyle == style && CurrentMotion == motion
&& _firstCyclic != null && _queue.Count > 0)
{
if (MathF.Abs(speedMod - CurrentSpeedMod) > 1e-4f
&& MathF.Sign(speedMod) == MathF.Sign(CurrentSpeedMod)
&& MathF.Abs(CurrentSpeedMod) > 1e-6f)
{
MultiplyCyclicFramerate(speedMod / CurrentSpeedMod);
CurrentSpeedMod = speedMod;
}
return;
}
// Resolve transition link (currentSubstate → adjustedMotion).
MotionData? linkData = CurrentMotion != 0
@ -371,6 +415,45 @@ public sealed class AnimationSequencer
CurrentStyle = style;
CurrentMotion = motion;
CurrentSpeedMod = speedMod;
}
/// <summary>
/// Scale every cyclic node's framerate by <paramref name="factor"/>, mirroring
/// ACE's <c>Sequence.multiply_cyclic_animation_framerate</c>
/// (<c>references/ACE/Source/ACE.Server/Physics/Animation/Sequence.cs</c> L277-L287,
/// retail decompile <c>FUN_00525CE0</c>). Walks <c>_firstCyclic</c> through
/// the tail of the queue and calls <see cref="AnimNode.MultiplyFramerate"/>
/// on each. The non-cyclic head (link frames) is untouched — those drain
/// at their original framerate, which matches retail: the sequencer
/// "catches up" the transition before applying the new run speed.
///
/// <para>
/// Called from <see cref="SetCycle"/> when the same (style, motion) pair
/// is re-issued with a different speedMod — for instance, when a remote
/// player's ForwardSpeed changes mid-run. Does NOT restart the animation,
/// so footsteps keep planting where they are.
/// </para>
/// </summary>
/// <param name="factor">Framerate multiplier (newSpeed / oldSpeed).</param>
public void MultiplyCyclicFramerate(float factor)
{
if (_firstCyclic == null) return;
if (factor < 0f || float.IsNaN(factor) || float.IsInfinity(factor))
return;
for (var node = _firstCyclic; node != null; node = node.Next)
{
node.Value.MultiplyFramerate((double)factor);
// Velocity/Omega carried on the node scale with the framerate, so
// the physics velocity surfaced by CurrentVelocity matches the
// animation playback. (ACE does the same: add_motion sets both
// to the scaled value and multiply_cyclic_animation_framerate is
// preceded by subtract_motion/combine_motion in change_cycle_speed
// to keep them aligned — MotionTable.cs:372-379.)
node.Value.Velocity *= factor;
node.Value.Omega *= factor;
}
}
/// <summary>
@ -654,6 +737,7 @@ public sealed class AnimationSequencer
_rootMotionRot = Quaternion.Identity;
CurrentStyle = 0;
CurrentMotion = 0;
CurrentSpeedMod = 1f;
}
// ── Private helpers ──────────────────────────────────────────────────────