Skip to content

fix: restart a finished appended animation from scratch - #5224

Open
Frank3K wants to merge 1 commit into
google:masterfrom
Frank3K:fix/restart-finished-appended-animation
Open

Frank3K wants to merge 1 commit into
google:masterfrom
Frank3K:fix/restart-finished-appended-animation

Conversation

@Frank3K

@Frank3K Frank3K commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Appending an animation that has already finished is meant to restart it. ModelScene.appendAnimation() only reset the action when action.time == duration, which goes wrong in two ways:

  1. A reverse run is never reset. A reverse run (negative timeScale) finishes at time 0, so the check doesn't match. three.js keeps the loop count of the finished run, so the next run with repetitions stops early. For example, after a reverse run with repetitions: 2, a forward run with repetitions: 2 plays only once and dispatches no loop event.
  2. The time option is undone. The time is applied before the check. With time at the clip's end (the way to start a one-shot reverse run at the end), the check matches and stop() moves the action back to 0, so the reverse run finishes on its first frame. stop() also cancels the fade and warp that were just applied.

Live demo: https://jsfiddle.net/kp6dj8hw/ (uses 4.4.0). Both scenarios fail there:

Scenario 4.4.0 With this fix
1. Forward run with repetitions: 2 after a reverse run (at 2× speed) 0 loop events, 919 ms (one pass) 1 loop event, ~1850 ms
2. One-shot reverse run from the end (at 2× speed) finished after 13 ms ~930 ms

The "with this fix" numbers come from running the same page against a local build of this branch.

Fix

Before the options are applied, stop an action that has finished or was faded out by detachAnimation() (disabled). model-viewer sets clampWhenFinished, so a finished action is paused at exactly 0 or the clip's duration. The new options then apply to a clean run, and the end-of-clip stop() is removed.

It stops the action rather than only calling reset(): reset() leaves the action active in the mixer, so it would count as running and the new loop mode and repetitions would not be applied.

It doesn't stop an action that was halted mid-clip, so that it can be resumed where it was. That means one paused with timeScale: 0 (which !action.isRunning() would have included), and one halted by a warp to 0, which three.js pauses without moving it to either end.

Tests

  • animation-spec.ts: tests that use only the public API (appendAnimation() and the loop/finished events): one for each problem above, plus one checking that new repetitions are applied when a finished animation is appended again.
  • ModelScene-spec.ts: tests that drive the mixer frame by frame. They cover a finished reverse run, the time option, a faded-out animation, new repetitions for a finished animation, and resuming an animation paused with a time scale of 0 or halted by a warp to 0.

Without the fix, the five tests for the two problems fail in Chromium and WebKit; with it, all tests in both spec files pass in both browsers. I couldn't run Firefox locally (the browser failed to start).

@Frank3K
Frank3K force-pushed the fix/restart-finished-appended-animation branch from a443bda to 8d803b3 Compare November 17, 2026 21:44
When an appended animation is appended again, appendAnimation() only
called action.stop() if the action's time equaled the clip's duration.
That check went wrong in two ways:

- It ignored the direction. A reverse run finishes at time 0, so its
  action was never reset. three.js then kept the loop count of the
  previous run, and the next run with repetitions was cut short.
- It undid the time option. The time was applied first, so with
  `time: duration` the check matched, and stop() moved the action back
  to 0. stop() also cancelled the fade and warp that were just applied.

Instead, stop a finished or faded-out (disabled) action before applying
the options. Stopping rather than only resetting it deactivates the
action, so the new loop mode and repetitions are still applied.

A finished action is paused and clamped at exactly 0 or the clip's
duration. Paused alone is not enough: a warp to a time scale of 0 also
pauses the action, mid-clip, and it should resume from there. This
doesn't use !isRunning() either: that is also true for an action paused
with a time scale of 0, which would then jump back to the start when it
is resumed.
@Frank3K
Frank3K force-pushed the fix/restart-finished-appended-animation branch from 8d803b3 to e23142f Compare November 17, 2026 21:49

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant