From e23142f50b2e89ac23a18324cbfad93b4473ed91 Mon Sep 17 00:00:00 2001 From: Frank3K <8014077+Frank3K@users.noreply.github.com> Date: Thu, 12 Nov 2026 07:15:12 +0100 Subject: [PATCH] fix: restart a finished appended animation from scratch 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. --- .../src/test/features/animation-spec.ts | 54 ++++++++ .../test/three-components/ModelScene-spec.ts | 126 ++++++++++++++++++ .../src/three-components/ModelScene.ts | 17 ++- 3 files changed, 194 insertions(+), 3 deletions(-) diff --git a/packages/model-viewer/src/test/features/animation-spec.ts b/packages/model-viewer/src/test/features/animation-spec.ts index b1e40771d9..05bd8da101 100644 --- a/packages/model-viewer/src/test/features/animation-spec.ts +++ b/packages/model-viewer/src/test/features/animation-spec.ts @@ -238,6 +238,60 @@ suite('Animation', () => { }); }); + suite('when a finished appended animation is appended again', () => { + // Wave lasts 1.83s; it is sped up to keep the tests short. + const name = 'Wave'; + const speed = 8; + + // Appends the animation and resolves when it has finished. + const playToEnd = async (options: {}) => { + const finished = waitForEvent(element, 'finished'); + element.appendAnimation(name, options); + await finished; + }; + + test('plays all repetitions after a reverse run', async () => { + await playToEnd({repetitions: 2, timeScale: -speed}); + + let loops = 0; + const onLoop = () => loops++; + element.addEventListener('loop', onLoop); + await playToEnd({repetitions: 2, timeScale: speed}); + element.removeEventListener('loop', onLoop); + + expect(loops, 'the second repetition was skipped').to.be.equal(1); + }); + + test('uses the new repetitions', async () => { + await playToEnd({repetitions: 2, timeScale: speed}); + + let loops = 0; + const onLoop = () => loops++; + element.addEventListener('loop', onLoop); + await playToEnd({repetitions: 3, timeScale: speed}); + element.removeEventListener('loop', onLoop); + + expect(loops, 'the previous repetitions were used').to.be.equal(2); + }); + + test('starts at the given time', async () => { + await playToEnd({repetitions: 1, timeScale: speed}); + const duration = + (element[$scene] as any).animationsByName.get(name).duration; + + let finished = false; + const onFinished = () => finished = true; + element.addEventListener('finished', onFinished); + // A reverse run from the end takes the full duration (1.83s). + element.appendAnimation( + name, {repetitions: 1, timeScale: -1, time: duration}); + await timePasses(300); + element.removeEventListener('finished', onFinished); + + expect(finished, 'the reverse run started at 0').to.be.false; + }); + }); + suite('when configured to autoplay', () => { setup(async () => { element.autoplay = true; diff --git a/packages/model-viewer/src/test/three-components/ModelScene-spec.ts b/packages/model-viewer/src/test/three-components/ModelScene-spec.ts index 92acbb702b..add22506ec 100644 --- a/packages/model-viewer/src/test/three-components/ModelScene-spec.ts +++ b/packages/model-viewer/src/test/three-components/ModelScene-spec.ts @@ -97,6 +97,132 @@ suite('ModelScene', () => { expect(scene.markedAnimations).to.be.empty; }); + suite('appending an animation again', () => { + let animationName: string; + let duration: number; + + // The action of the appended animation (on the only model). + const getAction = () => { + const clip = (scene as any).animationsByName.get(animationName); + return (scene as any).mixers[0].existingAction(clip); + }; + + // Advances the animations by the given number of seconds, in frames. + const advance = (seconds: number) => { + const step = 1 / 60; + for (let t = 0; t < seconds; t += step) { + scene.updateAnimation(step); + } + }; + + function append( + repetitionCount: number, + timeScale: number, + time: number|null = null) { + scene.appendAnimation( + animationName, + LoopRepeat, + repetitionCount, + 1, + timeScale, + false, + false, + true, + time); + } + + setup(() => { + animationName = scene.animationNames[0]; + duration = (scene as any).animationsByName.get(animationName).duration; + scene.unpauseAnimation(); + }); + + test('restarts a finished reverse animation from scratch', () => { + append(2, -1); + advance(duration * 3); + expect(getAction().paused, 'reverse run has not finished').to.be.true; + expect(getAction().time).to.be.equal(0); + + append(2, 1); + advance(duration * 1.5); + + expect(getAction().paused, 'second repetition was cut short') + .to.be.false; + expect(getAction().time).to.be.closeTo(duration * 0.5, 0.1); + }); + + test('applies the time option to a finished animation', () => { + append(1, 1); + advance(duration * 1.5); + expect(getAction().paused, 'forward run has not finished').to.be.true; + expect(getAction().time).to.be.equal(duration); + + append(1, -1, duration); + expect(getAction().time).to.be.equal(duration); + + advance(duration * 0.5); + + expect(getAction().paused, 'reverse run has finished').to.be.false; + expect(getAction().time).to.be.closeTo(duration * 0.5, 0.1); + }); + + test('restarts a faded-out animation from scratch', () => { + append(2, 1); + advance(duration * 1.5); + scene.detachAnimation(animationName, 0.1); + advance(0.2); + expect(getAction().enabled, 'fade-out has not finished').to.be.false; + + append(2, 1); + expect(getAction().time).to.be.equal(0); + + advance(duration * 1.5); + + expect(getAction().paused, 'second repetition was cut short') + .to.be.false; + expect(getAction().time).to.be.closeTo(duration * 0.5, 0.1); + }); + + test('resumes an animation paused with a time scale of 0', () => { + append(Infinity, 1); + advance(duration * 0.5); + append(Infinity, 0); + advance(duration * 0.25); + append(Infinity, 1); + + expect(getAction().time).to.be.closeTo(duration * 0.5, 0.1); + }); + + test('applies the new repetitions to a finished animation', () => { + append(1, 1); + advance(duration * 1.5); + expect(getAction().paused, 'forward run has not finished').to.be.true; + + append(3, 1); + advance(duration * 1.5); + + expect(getAction().paused, 'the previous repetitions were used') + .to.be.false; + expect(getAction().time).to.be.closeTo(duration * 0.5, 0.1); + }); + + test('resumes an animation halted by a warp to 0', () => { + append(Infinity, 1); + advance(duration * 0.5); + // Warps from the current time scale (1) to 0 in 0.1s. + scene.appendAnimation( + animationName, LoopRepeat, Infinity, 1, 0, false, 0.1, true, null); + advance(0.2); + expect(getAction().paused, 'warp has not halted the action').to.be.true; + const haltedTime = getAction().time; + + append(Infinity, 1); + + expect(getAction().time).to.be.equal(haltedTime); + expect(getAction().paused).to.be.false; + }); + }); + suite('appendAnimation repetitionCount validation', () => { // Returns the repetitionCount-related warnings emitted while appending the // first animation with the given repetitionCount. diff --git a/packages/model-viewer/src/three-components/ModelScene.ts b/packages/model-viewer/src/three-components/ModelScene.ts index 8700905a62..cd56cecb15 100644 --- a/packages/model-viewer/src/three-components/ModelScene.ts +++ b/packages/model-viewer/src/three-components/ModelScene.ts @@ -1098,6 +1098,20 @@ export class ModelScene extends Scene { const action = mixer.existingAction(animationClip) || mixer.clipAction(animationClip, this._models[i] || this); + // Restart an action that has finished (clamped at either end) or was + // faded out, so that its previous run (e.g. its loop count) does not + // carry over. This happens before the options are applied, so that + // they apply to the new run. Stopping (not just resetting) it makes + // sure the loop mode and repetitions are applied below. An action + // that was halted mid-clip is kept as is, so that it can be resumed: + // either with a time scale of 0, or by a warp to 0, which pauses it. + // A finished action is clamped at exactly 0 or the clip's duration. + const isFinished = action.paused && + (action.time === 0 || action.time === animationClip.duration); + if (isFinished || !action.enabled) { + action.stop(); + } + const currentTimeScale = action.timeScale; if (typeof time === 'number') { @@ -1118,9 +1132,6 @@ export class ModelScene extends Scene { } if (!action.isRunning()) { - if (action.time == animationClip.duration) { - action.stop(); - } action.setLoop(loopMode, repetitionCount); action.paused = false; action.enabled = true;