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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(sdk): tween composition completes and sprite animation keeps pace
esengineb8e4170f451f
diff --git a/sdk/src/animation/Easing.ts b/sdk/src/animation/Easing.tsindex 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: numbconst 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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[] = [];