Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(animation): keep paused sprite motions out of exit transitions

yhh0a631870ef84
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 68b6483ed..c15aef1d9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Paused sprite motions wait for actual completion before exit transitions.** Animator exit-time checks require the matching SpriteAnimator completion latch and stopped playback. Pausing or seeking to a stopped frame preserves the current state; resumed one-shot playback can complete normally, while a pending replay does not count as an ended clip.
+
- **Measured lists locate visible items without scanning every preceding row.** Ordered cached offsets use binary searches for both viewport boundaries. Non-monotone or non-finite offsets retain the existing scan semantics. Failed measurements do not publish a completed cache, and list synchronization stays dirty after errors so a subsequent update can retry.
- **Plain-text wrapping avoids repeated whole-line glyph measurements.** The atlas-backed wrap path appends glyph advances in their original order while sharing the greedy wrap decisions with arbitrary string measurement. Long words and wide lines stay linear in glyph queries; spaces, supplementary characters and signed spacing preserve prior line breaks and geometry. Canvas string measurement retains its existing behavior.
diff --git a/sdk/src/animation/spriteMotion.ts b/sdk/src/animation/spriteMotion.ts
index 3db631906..0794f1354 100644
--- a/sdk/src/animation/spriteMotion.ts
+++ b/sdk/src/animation/spriteMotion.ts
@@ -37,8 +37,7 @@ export const spriteMotionDriver: MotionDriver<AnimatorClipMotion> = {
isFinished({ world, entity }, motion) {
if (!world.has(entity, SpriteAnimator)) return false;
const sp = world.get(entity, SpriteAnimator) as SpriteAnimatorData;
- // Playing THIS clip and stopped — not merely stopped, which is also true
- // on the frame before the clip has been applied at all.
- return sp.clip === motion.clip && sp.clip !== '' && !sp.playing;
+ // Completion belongs to this clip; pause and a pending replay are not completion.
+ return sp.clip === motion.clip && sp.clip !== '' && sp.finished && !sp.playing;
},
};
diff --git a/sdk/tests/animator-substate.test.ts b/sdk/tests/animator-substate.test.ts
index c95b33020..04d911cb2 100644
--- a/sdk/tests/animator-substate.test.ts
+++ b/sdk/tests/animator-substate.test.ts
@@ -184,7 +184,7 @@ describe('AnimatorControllerAPI.update — nested machine', () => {
ctrl.setTrigger(E, 'attack');
ctrl.update(world); // → Combat/Swing (swing clip applied, loop:false)
// Simulate the swing clip finishing so its exit-time edge can fire.
- world.update(E, SpriteAnimator, (sp: SpriteAnimatorData) => { sp.playing = false; });
+ world.update(E, SpriteAnimator, (sp: SpriteAnimatorData) => { sp.playing = false; sp.finished = true; });
ctrl.update(world);
expect(animPath(world)).toBe('Combat/Recover');
expect(clip(world)).toBe('recover');
diff --git a/sdk/tests/animator.test.ts b/sdk/tests/animator.test.ts
index b3af54aba..3573dbdca 100644
--- a/sdk/tests/animator.test.ts
+++ b/sdk/tests/animator.test.ts
@@ -282,10 +282,8 @@ describe('AnimatorControllerAPI.update', () => {
ctrl.update(world);
expect((world.get(E, Animator) as AnimatorData).currentState).toBe('attack');
- // Simulate the non-looping clip ending (SpriteAnimationAPI clears playing).
- const sp = world.get(E, SpriteAnimator) as SpriteAnimatorData;
- sp.playing = false;
- world.insert(E, SpriteAnimator, sp);
+ // Simulate the completion latch written by SpriteAnimationAPI.
+ world.update(E, SpriteAnimator, (sp: SpriteAnimatorData) => { sp.playing = false; sp.finished = true; });
ctrl.update(world); // exit time met → idle
expect((world.get(E, Animator) as AnimatorData).currentState).toBe('idle');
diff --git a/sdk/tests/animatorMotion.test.ts b/sdk/tests/animatorMotion.test.ts
index c0e518cef..fc9d51f32 100644
--- a/sdk/tests/animatorMotion.test.ts
+++ b/sdk/tests/animatorMotion.test.ts
@@ -6,7 +6,7 @@
*/
import { describe, it, expect } from 'vitest';
import {
- Animator, AnimatorControllerAPI, SpriteAnimator, motionOf,
+ Animator, AnimatorControllerAPI, SpriteAnimator, SpriteAnimationAPI, motionOf,
type AnimatorData, type AnimatorControllerDef, type AnimatorMotion,
type AnimatorState, type SpriteAnimatorData,
} from '../src/animation';
@@ -35,6 +35,9 @@ function makeWorld() {
return m;
};
return {
+ getCppRegistry: () => null, getWasmModule: () => null,
+ resolveGetter: () => null, resolveSetter: () => null,
+ isEntityActive: () => true,
insert(e: number, c: unknown, data: unknown) { mapOf(c).set(e, data); },
get(e: number, c: unknown) { return mapOf(c).get(e); },
has(e: number, c: unknown) { return mapOf(c).has(e); },
@@ -212,7 +215,7 @@ describe('exit time is the motion’s answer, whatever kind it is', () => {
return ctrl;
};
- it('waits for a sprite clip to stop', () => {
+ it('waits for a sprite clip to complete', () => {
const world = makeWorld();
const ctrl = new AnimatorControllerAPI();
ctrl.registerController('atk', oneShot({ kind: 'sprite', clip: 'attack', loop: false }));
@@ -226,11 +229,31 @@ describe('exit time is the motion’s answer, whatever kind it is', () => {
ctrl.update(world, 0.016);
expect(stateOf(world)).toBe('Attack');
- world.update(E, SpriteAnimator, (sp: SpriteAnimatorData) => { sp.playing = false; });
+ world.update(E, SpriteAnimator, (sp: SpriteAnimatorData) => { sp.playing = false; sp.finished = true; });
ctrl.update(world, 0.016);
expect(stateOf(world)).toBe('Idle');
});
+ it('keeps a paused sprite in its state until resumed playback actually completes', () => {
+ const world = makeWorld();const ctrl = new AnimatorControllerAPI();const sprites = new SpriteAnimationAPI();
+ sprites.registerClip({ name: 'attack', fps: 10, loop: false, frames: [{ texture: 1 }, { texture: 2 }] });
+ ctrl.registerController('atk', oneShot({ kind: 'sprite', clip: 'attack', loop: false }));
+ seed(world, 'atk');world.insert(E, SpriteAnimator, spriteData());
+ ctrl.update(world, 0);sprites.update(world, 0.05);
+ const sp = world.get(E, SpriteAnimator) as SpriteAnimatorData;
+ expect(sp.currentFrame).toBe(0);expect(sp.frameTimer).toBeCloseTo(0.05);
+ world.update(E, SpriteAnimator, (draft: SpriteAnimatorData) => { draft.playing = false; });
+ for (let i = 0; i < 5; i++) { sprites.update(world, 0.5);ctrl.update(world, 0.5); }
+ expect(stateOf(world)).toBe('Attack');expect(sp.finished).toBe(false);
+ expect(sp.frameTimer).toBeCloseTo(0.05);
+ world.update(E, SpriteAnimator, (draft: SpriteAnimatorData) => { draft.playing = true; });
+ sprites.update(world, 0.1);ctrl.update(world, 0.1);
+ expect(stateOf(world)).toBe('Attack');expect(sp.currentFrame).toBe(1);
+ sprites.update(world, 0.06);
+ expect(sp.finished).toBe(true);expect(sp.playing).toBe(false);
+ ctrl.update(world, 0.06);expect(stateOf(world)).toBe('Idle');
+ });
+
it('waits out a non-looping timeline on the animator’s own clock', () => {
const world = makeWorld();
const ctrl = timelineCtrl('attack.estimeline', holdAt(1, 0.5, WrapMode.Once));
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index a19c94f29..75dcfb613 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(animation): keep paused sprite motions out of exit transitions':
+ { note: 'Paused sprite motions wait for actual completion before exit transitions.' },
'perf(ui): search measured list bounds and retry failed syncs':
{ note: 'Measured lists locate visible items without scanning every preceding row.' },
'feat(viewport): combine transform handles in a universal tool':