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): a looping timeline keeps firing events at the loop seam
esenginef07b14e76a4e
diff --git a/sdk/src/timeline/TimelineDrive.ts b/sdk/src/timeline/TimelineDrive.tsindex 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.tsindex 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,