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): preserve value tween callback control

yhh21c4e7ff0fdb
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7dd75b50e..ff3d9f13f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Value tween callbacks preserve playback control.** Callback-created tweens start on the next update, recursive updates cannot advance the same pass twice, and callback cancellation or pause is not overwritten by completion or sequence handoff. Existing sequence members still resume in the same frame, without allocating a snapshot of the tween map.
+
- **Animation callbacks respect entity activity immediately.** Disabling an animator, entity or ancestor during a frame event stops remaining callbacks and sprite writes; later entries disabled by an earlier callback keep their playback position. Re-enabling applies deferred geometry without replaying handled events or restarting a completed one-shot.
- **Text submission preserves callback-selected focus.** A submit handler can focus the next field without the previous field's default blur clearing it. Submission still closes the editing session when the handler leaves focus unchanged.
diff --git a/sdk/src/animation/Tween.ts b/sdk/src/animation/Tween.ts
index fdc9b974f..4a44461dc 100644
--- a/sdk/src/animation/Tween.ts
+++ b/sdk/src/animation/Tween.ts
@@ -127,6 +127,7 @@ export class TweenAPI {
private readonly registry_: CppRegistry;
private readonly valueManager_: ValueTweenManager;
private readonly compositionManager_: TweenCompositionManager;
+ private updating_ = false;
constructor(module: AnimCore, registry: CppRegistry) {
this.module_ = module;
@@ -177,9 +178,13 @@ export class TweenAPI {
}
update(deltaTime: number): void {
- this.module_.anim_updateTweens?.(this.registry_, deltaTime);
- this.valueManager_.update(deltaTime);
- this.compositionManager_.update();
+ if (this.updating_) return;
+ this.updating_ = true;
+ try {
+ this.module_.anim_updateTweens?.(this.registry_, deltaTime);
+ this.valueManager_.update(deltaTime);
+ this.compositionManager_.update();
+ } finally { this.updating_ = false; }
}
// ---- Composition builders -------------------------------------------------
diff --git a/sdk/src/animation/ValueTween.ts b/sdk/src/animation/ValueTween.ts
index 1ce252bca..1814afcd5 100644
--- a/sdk/src/animation/ValueTween.ts
+++ b/sdk/src/animation/ValueTween.ts
@@ -44,6 +44,7 @@ interface ValueTweenEntry {
export class ValueTweenManager {
private entries_ = new Map<number, ValueTweenEntry>();
private nextId_ = 1;
+ private updating_ = false;
private cppSequences_ = new Map<number, number>();
private readonly module_: AnimCore;
private readonly registry_: CppRegistry;
@@ -82,6 +83,14 @@ export class ValueTweenManager {
}
update(dt: number): void {
+ if (this.updating_) return;
+ this.updating_ = true;
+ try { this.updateEntries_(dt); }
+ finally { this.updating_ = false; }
+ }
+
+ private updateEntries_(dt: number): void {
+ const lastId = this.nextId_ - 1;
for (const [cppEntity, jsTweenId] of this.cppSequences_) {
const cppState = this.module_.anim_getTweenState?.(
this.registry_, cppEntity as Entity,
@@ -103,6 +112,9 @@ export class ValueTweenManager {
}
for (const entry of this.entries_.values()) {
+ // The live Map can grow inside a callback. Newly created entries
+ // start next frame; existing chained entries still resume this frame.
+ if (entry.id > lastId) break;
if (entry.state !== TweenState.Running) continue;
// Per-entry step, NOT the shared `dt` — writing `dt` here would advance
@@ -119,6 +131,7 @@ export class ValueTweenManager {
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);
+ if (entry.state !== TweenState.Running) continue;
if (t >= 1) {
if (entry.loop !== LoopMode.None) {
diff --git a/sdk/tests/value-tween.test.ts b/sdk/tests/value-tween.test.ts
index a744185d6..7bb80423d 100644
--- a/sdk/tests/value-tween.test.ts
+++ b/sdk/tests/value-tween.test.ts
@@ -14,6 +14,7 @@ import { TweenGroup } from '../src/animation/TweenGroup';
import { TweenState, LoopMode } from '../src/animation/TweenTypes';
import type { CppRegistry } from '../src/wasm';
import type { AnimCore } from '../src/animation/Tween';
+import { TweenAPI } from '../src/animation/Tween';
// The manager only ever calls module.anim_getTweenState (for C++ sequences);
// everything else is pure JS. A closure-controlled stub covers that one seam.
@@ -24,6 +25,64 @@ function makeManager(cppState: () => number = () => TweenState.Running) {
}
describe('ValueTweenManager progression', () => {
+ it('does not recursively step the native engine through TweenAPI.update', () => {
+ const nativeStep = vi.fn();
+ const api = new TweenAPI({ anim_updateTweens: nativeStep } as unknown as AnimCore, {} as CppRegistry);
+ let nested = false;
+ api.value(0, 1, 1, () => {
+ if (!nested) { nested = true; api.update(.25); }
+ });
+ api.update(.25);
+ expect(nativeStep).toHaveBeenCalledOnce();
+ });
+ it('defers tweens created by a callback until the next update', () => {
+ const m = makeManager(), child = vi.fn();
+ let created = false;
+ m.create(0, 1, 1, () => {
+ if (!created) { created = true; m.create(0, 1, 1, child); }
+ });
+ m.update(.5);
+ expect(child).not.toHaveBeenCalled();
+ m.update(.25);
+ expect(child).toHaveBeenCalledWith(.25);
+ });
+
+ it('does not recursively advance playback from an update callback', () => {
+ const m = makeManager();
+ let nested = false;
+ const values: number[] = [];
+ m.create(0, 1, 1, value => {
+ values.push(value);
+ if (!nested) { nested = true; m.update(.25); }
+ });
+ m.update(.25);
+ expect(values).toEqual([.25]);
+ });
+
+ it.each(['cancel', 'pause'] as const)('preserves callback %s at completion and leaves the sequence paused', action => {
+ const m = makeManager(), next = vi.fn();
+ const id = m.create(0, 1, 1, () => m[action](id));
+ const child = m.create(0, 1, 1, next);
+ m.setSequenceNext(id, child);
+ m.update(1);
+ expect(m.getState(id)).toBe(action === 'cancel' ? TweenState.Cancelled : TweenState.Paused);
+ expect(m.getState(child)).toBe(TweenState.Paused);
+ expect(next).not.toHaveBeenCalled();
+ });
+
+ it('releases the update guard when a callback throws', () => {
+ const m = makeManager();
+ let fail = true;
+ const values: number[] = [];
+ m.create(0, 1, 1, value => {
+ if (fail) { fail = false; throw new Error('callback failed'); }
+ values.push(value);
+ });
+ expect(() => m.update(.25)).toThrow('callback failed');
+ m.update(.25);
+ expect(values).toEqual([.5]);
+ });
+
it('drives the callback with the linearly-eased value', () => {
const m = makeManager();
const seen: number[] = [];
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index f8296b4d9..7ca9a2454 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): preserve value tween callback control':
+ { note: 'Value tween callbacks preserve playback control.' },
'fix(animation): honor activity changes during frame callbacks':
{ note: 'Animation callbacks respect entity activity immediately.' },
'fix(ui): preserve focus selected by text submit handlers':