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): a looping timeline keeps firing events at the loop seam

esenginef07b14e76a4e
diff --git a/sdk/src/timeline/TimelineDrive.ts b/sdk/src/timeline/TimelineDrive.ts
index 09dadc6fa..a56ec56da 100644
--- a/sdk/src/timeline/TimelineDrive.ts
+++ b/sdk/src/timeline/TimelineDrive.ts
@@ -49,9 +49,14 @@ export interface FiredEvent {
export function detectTimelineEvents(
asset: TimelineAsset, state: TimelineState,
resolveChild: (root: Entity, childPath: string) => Entity | null, root: Entity,
+ // Monotone edge-detection interval(s). Defaults to the single (prevTime, time]
+ // span; on a loop wrap the caller passes the two seam segments so a trigger
+ // near the loop boundary still fires (one interval is empty when time < prevTime).
+ // Level tracks (Spine, Activation) read `state.time` directly and ignore this.
+ segments: ReadonlyArray<readonly [number, number]> = [[state.prevTime, state.time]],
): FiredEvent[] {
const out: FiredEvent[] = [];
- const { time, prevTime } = state;
+ const { time } = state;
for (let i = 0; i < asset.tracks.length; i++) {
const track = asset.tracks[i];
@@ -80,15 +85,20 @@ export function detectTimelineEvents(
break;
}
case TrackType.SpriteAnim: {
- if (prevTime <= track.startTime && time >= track.startTime && time > prevTime) {
- out.push({ kind: TimelineEventType.SpriteAnimPlay, entity: target, intParam: 0, floatParam: 0, str: track.clip });
+ for (const [from, to] of segments) {
+ if (to > from && from <= track.startTime && track.startTime <= to) {
+ out.push({ kind: TimelineEventType.SpriteAnimPlay, entity: target, intParam: 0, floatParam: 0, str: track.clip });
+ break; // fire at most once across the seam segments
+ }
}
break;
}
case TrackType.Audio: {
- for (const e of track.events) {
- if (e.time > prevTime && e.time <= time) {
- out.push({ kind: TimelineEventType.AudioPlay, entity: target, intParam: 0, floatParam: e.volume, str: e.clip });
+ for (const [from, to] of segments) {
+ for (const e of track.events) {
+ if (e.time > from && e.time <= to) {
+ out.push({ kind: TimelineEventType.AudioPlay, entity: target, intParam: 0, floatParam: e.volume, str: e.clip });
+ }
}
}
break;
@@ -185,7 +195,15 @@ export function advanceTimelineTS(
sampleTimeline(asset, state.time, root, ctx.deps, ctx.sampleOpts);
ctx.onPropertyApplied?.(root, asset);
- for (const e of detectTimelineEvents(asset, state, ctx.deps.resolveChild, root)) {
+ // On a loop wrap the playhead ran prevTime → duration → 0 → time; split edge
+ // detection across both seam segments so triggers near the loop boundary keep
+ // firing each loop (the plain (prevTime, time] span is empty when time < prevTime).
+ const segments: ReadonlyArray<readonly [number, number]> =
+ state.wrapMode === WrapMode.Loop && advanced >= asset.duration && asset.duration > 0
+ ? [[state.prevTime, asset.duration], [0, state.time]]
+ : [[state.prevTime, state.time]];
+
+ for (const e of detectTimelineEvents(asset, state, ctx.deps.resolveChild, root, segments)) {
applyTimelineEvent(ctx.deps.world, ctx.audio ?? null, e.kind, e.entity, e.intParam, e.floatParam, e.str);
}
diff --git a/sdk/tests/timeline-drive.test.ts b/sdk/tests/timeline-drive.test.ts
index 853c943fb..f24eab9cb 100644
--- a/sdk/tests/timeline-drive.test.ts
+++ b/sdk/tests/timeline-drive.test.ts
@@ -14,6 +14,7 @@ import { TimelineEventType } from '../src/timeline/TimelineRuntime';
import { TimelineAPI } from '../src/timeline/TimelineControl';
import { WrapMode, TrackType, InterpType, type TimelineAsset } from '../src/timeline/TimelineTypes';
import type { SampleDeps } from '../src/timeline/TimelineEvaluator';
+import type { AudioAPI } from '../src/audio/Audio';
const ROOT = 1 as const;
const resolveRoot = (root: number, childPath: string) => (childPath ? null : root);
@@ -63,6 +64,37 @@ describe('detectTimelineEvents (1:1 with C++ evaluateEventTracks)', () => {
expect(detectTimelineEvents(asset, s, resolveRoot, ROOT)).toEqual([]);
});
+ it('audio: a loop-seam event fires via the split wrap segments, not the empty single span', () => {
+ const asset: TimelineAsset = {
+ version: '1.1', type: 'timeline', duration: 5, wrapMode: WrapMode.Loop,
+ tracks: [{ type: TrackType.Audio, name: 'SFX', childPath: '', events: [{ time: 0.05, clip: 'step', volume: 1 }] }],
+ };
+ const s = createTimelineState(WrapMode.Loop);
+ s.prevTime = 4.9; s.time = 0.1; // a frame that wrapped 4.9 → 5.1 → 0.1
+ // (prevTime, time] = (4.9, 0.1] is empty — the pre-fix single span misses the seam event.
+ expect(detectTimelineEvents(asset, s, resolveRoot, ROOT)).toEqual([]);
+ // The two seam segments advanceTimelineTS passes on a wrap DO cross t=0.05:
+ expect(detectTimelineEvents(asset, s, resolveRoot, ROOT, [[4.9, 5], [0, 0.1]])).toEqual([
+ { kind: TimelineEventType.AudioPlay, entity: ROOT, intParam: 0, floatParam: 1, str: 'step' },
+ ]);
+ });
+
+ it('advanceTimelineTS: a looping clip keeps firing a near-start event every loop', () => {
+ const asset: TimelineAsset = {
+ version: '1.1', type: 'timeline', duration: 1, wrapMode: WrapMode.Loop,
+ tracks: [{ type: TrackType.Audio, name: 'SFX', childPath: '', events: [{ time: 0.05, clip: 'step', volume: 1 }] }],
+ };
+ const s = createTimelineState(WrapMode.Loop);
+ s.playing = true;
+ const deps: SampleDeps = { world: {} as SampleDeps['world'], getComponent: () => undefined, resolveChild: resolveRoot };
+ const plays: string[] = [];
+ const audio = { playSFX: (clip: string) => { plays.push(clip); } } as unknown as AudioAPI;
+ // 0.9s/frame: f1 0→0.9 crosses 0.05; f2 0.9→1.8→wrap→0.8 crosses 0.05 on the SEAM.
+ advanceTimelineTS(asset, ROOT, s, 0.9, { deps, audio });
+ advanceTimelineTS(asset, ROOT, s, 0.9, { deps, audio });
+ expect(plays).toEqual(['step', 'step']); // fired on BOTH loops (2nd is the wrap seam)
+ });
+
it('spriteAnim: fires once when startTime is crossed', () => {
const asset: TimelineAsset = {
version: '1.1', type: 'timeline', duration: 2, wrapMode: WrapMode.Once,