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(sdk): tween composition completes and sprite animation keeps pace

esengineb8e4170f451f
diff --git a/sdk/src/animation/Easing.ts b/sdk/src/animation/Easing.ts
index fe25e2d2c..acd70f668 100644
--- a/sdk/src/animation/Easing.ts
+++ b/sdk/src/animation/Easing.ts
@@ -143,7 +143,9 @@ function cubicBezier(t: number, p1x: number, p1y: number, p2x: number, p2y: numb
const ix = 1 - x;
const cx = 3 * p1x * ix * ix * x + 3 * p2x * ix * x * x + x * x * x - t;
if (Math.abs(cx) < BEZIER_EPSILON) break;
- const dx = 3 * p1x * (1 - 2 * x) * (1 - x)
+ // dX/dx of 3·p1x·(1-x)²·x + 3·p2x·(1-x)·x² + x³. The first term derivative
+ // is 3·p1x·(1-x)·(1-3x) — the (1-3x) factor, not (1-2x).
+ const dx = 3 * p1x * (1 - 3 * x) * (1 - x)
+ 6 * p2x * x * (1 - x)
- 3 * p2x * x * x
+ 3 * x * x;
diff --git a/sdk/src/animation/SpriteAnimator.ts b/sdk/src/animation/SpriteAnimator.ts
index 2dd0f5132..316667b90 100644
--- a/sdk/src/animation/SpriteAnimator.ts
+++ b/sdk/src/animation/SpriteAnimator.ts
@@ -40,7 +40,10 @@ export interface SpriteAnimClip {
}
export function shouldFireEvent(eventFrame: number, prevFrame: number, newFrame: number, totalFrames: number, loop: boolean): boolean {
- if (prevFrame === newFrame && eventFrame === newFrame) return true;
+ // Frame-0 initial apply only. Without the `=== 0`, the completion clamp
+ // (currentFrame overflows → clamped to last, so prev === new === last) re-fires
+ // the last frame's event a second time.
+ if (prevFrame === newFrame && eventFrame === newFrame && newFrame === 0) return true;
if (newFrame > prevFrame) {
return eventFrame > prevFrame && eventFrame <= newFrame;
}
@@ -163,8 +166,12 @@ export class SpriteAnimationAPI {
animator.frameTimer = 0;
}
- const currentFrame = clip.frames[animator.currentFrame];
- const frameDuration = currentFrame?.duration ?? 1.0 / (clip.fps * animator.speed);
+ // Speed scales EVERY frame's duration (not just the fps fallback), and
+ // is guarded: 0/negative would otherwise freeze (Infinity) or run the
+ // timer backward.
+ const speed = Math.max(animator.speed, 1e-4);
+ const durationOf = (i: number): number =>
+ (clip.frames[i]?.duration ?? 1.0 / clip.fps) / speed;
const needsInitialApply = animator.frameTimer === 0 && animator.currentFrame === 0;
const prevFrame = animator.currentFrame;
@@ -172,10 +179,15 @@ export class SpriteAnimationAPI {
animator.frameTimer += deltaTime;
let frameChanged = needsInitialApply;
- if (animator.frameTimer >= frameDuration) {
+ // Advance as MANY frames as elapsed — a fast clip (fps·speed > host fps)
+ // or a lag spike can cross several in one update; a single `if` would
+ // play in slow motion and let frameTimer grow unbounded. Capped at ~one
+ // full loop so a huge dt can't spin forever.
+ let guard = clip.frames.length + 1;
+ let frameDuration = durationOf(animator.currentFrame);
+ while (animator.playing && animator.frameTimer >= frameDuration && guard-- > 0) {
animator.frameTimer -= frameDuration;
animator.currentFrame++;
-
if (animator.currentFrame >= clip.frames.length) {
if (animator.loop && clip.loop) {
animator.currentFrame = 0;
@@ -185,8 +197,8 @@ export class SpriteAnimationAPI {
animator.finished = true;
}
}
-
frameChanged = true;
+ frameDuration = durationOf(animator.currentFrame);
}
if (frameChanged) {
@@ -197,9 +209,15 @@ export class SpriteAnimationAPI {
const frame = clip.frames[animator.currentFrame];
const sprite = world.get(entity, Sprite) as SpriteData;
sprite.texture = frame.texture;
+ // Copy (don't alias the clip's frame objects), and RESET to the full
+ // texture when a frame carries no sub-rect — else a plain frame after
+ // a sheet-cell frame renders through the stale cell window.
if (frame.uvOffset) {
- sprite.uvOffset = frame.uvOffset;
- sprite.uvScale = frame.uvScale!;
+ sprite.uvOffset = { x: frame.uvOffset.x, y: frame.uvOffset.y };
+ sprite.uvScale = frame.uvScale ? { x: frame.uvScale.x, y: frame.uvScale.y } : { x: 1, y: 1 };
+ } else {
+ sprite.uvOffset = { x: 0, y: 0 };
+ sprite.uvScale = { x: 1, y: 1 };
}
world.insert(entity, Sprite, sprite);
}
diff --git a/sdk/src/animation/ValueTween.ts b/sdk/src/animation/ValueTween.ts
index 8e27ca121..b9b859737 100644
--- a/sdk/src/animation/ValueTween.ts
+++ b/sdk/src/animation/ValueTween.ts
@@ -91,17 +91,30 @@ export class ValueTweenManager {
}
}
+ // Reap entries that finished on a PRIOR frame — deferring the sweep to the
+ // NEXT update keeps a just-completed entry queryable for the rest of THIS
+ // frame, so the composition manager (polled after this in TweenAPI.update)
+ // observes Completed instead of a same-frame-deleted → Cancelled.
+ for (const [id, entry] of this.entries_) {
+ if (entry.state === TweenState.Completed || entry.state === TweenState.Cancelled) {
+ this.entries_.delete(id);
+ }
+ }
+
for (const entry of this.entries_.values()) {
if (entry.state !== TweenState.Running) continue;
+ // Per-entry step, NOT the shared `dt` — writing `dt` here would advance
+ // every later entry in this loop by one delay's leftover, not the frame.
+ let step = dt;
if (entry.delay > 0) {
- entry.delay -= dt;
+ entry.delay -= step;
if (entry.delay > 0) continue;
- dt = -entry.delay;
+ step = -entry.delay;
entry.delay = 0;
}
- entry.elapsed += dt;
+ entry.elapsed += step;
const t = Math.min(entry.elapsed / entry.duration, 1);
const easedT = applyEasing(entry.easing, t, entry.bezierPoints ?? undefined);
entry.callback(entry.from + (entry.to - entry.from) * easedT);
@@ -129,15 +142,6 @@ export class ValueTweenManager {
}
}
}
-
- for (const [id, entry] of this.entries_) {
- if (
- entry.state === TweenState.Completed ||
- entry.state === TweenState.Cancelled
- ) {
- this.entries_.delete(id);
- }
- }
}
pause(id: number): void {
diff --git a/sdk/tests/sprite-animator.test.ts b/sdk/tests/sprite-animator.test.ts
index 3c3a52ff8..9933669c7 100644
--- a/sdk/tests/sprite-animator.test.ts
+++ b/sdk/tests/sprite-animator.test.ts
@@ -178,6 +178,33 @@ describe('SpriteAnimator', () => {
expect(sprite.texture).toBe(10);
});
+ it('advances MULTIPLE frames when one dt spans several (no slow-motion)', () => {
+ const entity = world.spawn();
+ world.insert(entity, Sprite, { texture: 10 });
+ world.insert(entity, SpriteAnimator, { clip: 'walk' });
+
+ // fps=10 → 0.1s/frame; 0.25s spans 2.5 frames → reach frame 2 (30), not 1 (20).
+ anim.update(world, 0.25);
+
+ expect((world.get(entity, Sprite) as SpriteData).texture).toBe(30);
+ });
+
+ it('scales an EXPLICIT frame duration by animator.speed', () => {
+ anim.registerClip({
+ name: 'timed', fps: 10, loop: true,
+ frames: [{ texture: 1, duration: 0.1 }, { texture: 2, duration: 0.1 }],
+ });
+ const entity = world.spawn();
+ world.insert(entity, Sprite, { texture: 1 });
+ world.insert(entity, SpriteAnimator, { clip: 'timed', speed: 2 });
+
+ // speed 2 halves the 0.1s frame → 0.06s advances one frame (speed was
+ // previously ignored for explicit durations).
+ anim.update(world, 0.06);
+
+ expect((world.get(entity, Sprite) as SpriteData).texture).toBe(2);
+ });
+
it('should loop back to first frame', () => {
const entity = world.spawn();
world.insert(entity, Sprite, { texture: 10 });
diff --git a/sdk/tests/value-tween.test.ts b/sdk/tests/value-tween.test.ts
index b858aa07e..fd62294fd 100644
--- a/sdk/tests/value-tween.test.ts
+++ b/sdk/tests/value-tween.test.ts
@@ -10,6 +10,7 @@
*/
import { describe, it, expect, vi } from 'vitest';
import { ValueTweenManager, ValueTweenHandle } from '../src/animation/ValueTween';
+import { TweenGroup } from '../src/animation/TweenGroup';
import { TweenState, LoopMode } from '../src/animation/TweenTypes';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
@@ -31,17 +32,36 @@ describe('ValueTweenManager progression', () => {
expect(seen).toEqual([25, 50]);
});
- it('delivers the end value on completion, then evicts the entry that same update', () => {
+ it('delivers the end value, then stays queryable as Completed until the NEXT update', () => {
const m = makeManager();
let last = -1;
const id = m.create(10, 30, 1, (v) => { last = v; });
m.update(1);
expect(last).toBe(30);
- // Completed entries are swept at the end of the update — the state is no
- // longer queryable, so a missing entry reports Cancelled.
+ // Sweep is deferred one frame: a just-completed entry stays queryable as
+ // Completed for the rest of this frame so a composition polling afterwards
+ // observes Completed (not a same-frame-deleted → Cancelled). It's reaped at
+ // the start of the next update.
+ expect(m.getState(id)).toBe(TweenState.Completed);
+ m.update(0.016);
expect(m.getState(id)).toBe(TweenState.Cancelled);
});
+ it('a parallel group of value tweens completes (not stuck as Cancelled)', () => {
+ const m = makeManager();
+ const id = m.create(0, 1, 1, () => {});
+ // How a composition observes a member: a Completable reading the live state.
+ const member = { get state() { return m.getState(id); }, pause() {}, resume() {}, cancel() {} };
+ let done = false;
+ const group = new TweenGroup([member]);
+ group.onComplete(() => { done = true; });
+ // TweenAPI.update order: value manager advances/completes first, THEN the
+ // composition polls. The completed member must read Completed, not Cancelled.
+ m.update(1);
+ expect(group.checkComplete()).toBe(true);
+ expect(done).toBe(true);
+ });
+
it('holds during the delay, then applies the leftover dt once it elapses', () => {
const m = makeManager();
const seen: number[] = [];