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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file timelineEvents.ts
* @brief Which stretches of a clip a playhead covered between two times, and
* which authored events that crossed.
*
* @details A fixed step never lands on an event's time, so "did it happen" is a
* question about an INTERVAL, and the interval is not always one piece:
* a looping clip advancing past its end covered the tail and then the
* head, with a discontinuity between them that a single (from, to] span
* reads as a rewind. {@link playheadRuns} is the one place that knows
* the shape of that, so events and root motion answer the same question
* the same way — the alternative is two wrap handlers that agree until
* one of them is fixed.
*
* Pure: no world, no asset state. What a run means in clip time is all
* that is here, so the loop seam is a unit test rather than a frame.
*/
import { WrapMode, TrackType, type TimelineAsset, type ParticleTrack } from './TimelineTypes';
import type { MotionEvent } from '../animation/motion';
/**
* A stretch of clip time the playhead covered, in the direction it covered it —
* `to` below `from` is a ping-pong clip running backwards. `inclusiveStart` marks
* a run that BEGINS an instant rather than continuing one: the frame a state was
* entered, and each lap of a loop.
*/
export interface PlayheadRun {
from: number;
to: number;
inclusiveStart: boolean;
}
/** Where a phase within a ping-pong cycle sits in clip time. */
function pingPongPhase(phase: number, duration: number): number {
const cycle = duration * 2;
const p = phase % cycle;
return p <= duration ? p : cycle - p;
}
/**
* The stretches of clip time a playhead covered going from `from` to `to` (both
* in clip seconds, `to` at or after `from`) under `mode`.
*
* A span at least a whole pass long collapses to ONE covering run: a frame long
* enough to lap the clip twice reporting everything twice is a stutter.
*/
export function playheadRuns(
from: number, to: number, duration: number, mode: WrapMode, inclusiveStart: boolean,
): PlayheadRun[] {
if (duration <= 0 || to < from) return [];
const span = to - from;
if (mode === WrapMode.Once) {
const a = Math.min(Math.max(from, 0), duration);
const b = Math.min(Math.max(to, 0), duration);
return [{ from: a, to: b, inclusiveStart }];
}
if (mode === WrapMode.Loop) {
if (span >= duration) return [{ from: 0, to: duration, inclusiveStart: true }];
const a = from % duration;
// Landing exactly on a lap boundary BEGINS that lap, so an event authored
// at 0 belongs to it — the one case where the caller's half-open window
// would drop an event rather than hand it to the run before.
const opens = inclusiveStart || (a === 0 && from > 0);
const b = a + span;
if (b <= duration) return [{ from: a, to: b, inclusiveStart: opens }];
// The playhead JUMPED from the end to the start; the head of the clip is a
// new lap, so an event authored at 0 belongs to it.
return [
{ from: a, to: duration, inclusiveStart: opens },
{ from: 0, to: b - duration, inclusiveStart: true },
];
}
const cycle = duration * 2;
if (span >= cycle) return [{ from: 0, to: duration, inclusiveStart: true }];
if (span === 0) {
const time = pingPongPhase(from, duration);
return [{ from: time, to: time, inclusiveStart }];
}
const runs: PlayheadRun[] = [];
let phase = from % cycle;
const end = phase + span;
let first = inclusiveStart;
while (phase < end) {
// A turn-around is continuous in clip time — the playhead reaches the end
// and comes back through the same instant — so only the first run of the
// call can be inclusive.
const next = Math.min(end, (Math.floor(phase / duration) + 1) * duration);
runs.push({
from: pingPongPhase(phase, duration),
to: pingPongPhase(next, duration),
inclusiveStart: first,
});
first = false;
phase = next;
}
return runs;
}
/** Whether a moment at `at` falls inside `run`, in the direction it runs. */
export function runCrosses(run: PlayheadRun, at: number): boolean {
const { from, to, inclusiveStart } = run;
if (to > from) return (at > from || (inclusiveStart && at === from)) && at <= to;
if (to < from) return (at < from || (inclusiveStart && at === from)) && at >= to;
return inclusiveStart && at === from;
}
/** Shared by standalone players and animator motions; pose sampling never fires effects. */
export function forEachParticleEvent(
track: ParticleTrack, runs: readonly PlayheadRun[],
emit: (action: ParticleTrack['events'][number]['action']) => void,
): void {
for (const run of runs) {
let first: ParticleTrack['events'][number] | undefined;
let crossed: ParticleTrack['events'] | undefined;
for (const event of track.events) {
if (!runCrosses(run, event.time)) continue;
if (!first) first = event;
else (crossed ??= [first]).push(event);
}
// Most frames cross no key or one key. Only a multi-key crossing needs
// storage and ordering; a reverse run must reach the later key first.
// Stable sort preserves authored order for actions at the same instant.
if (crossed) {
const direction = run.to < run.from ? -1 : 1;
crossed.sort((a, b) => direction * (a.time - b.time));
for (const event of crossed) emit(event.action);
} else if (first) emit(first.action);
}
}
/** The event's numeric payload, or 0 where it carries none. */
function payloadValue(payload: Record<string, unknown> | undefined): number {
const v = payload?.value;
return typeof v === 'number' ? v : 0;
}
/** The event's string payload, or empty where it carries none. */
function payloadText(payload: Record<string, unknown> | undefined): string {
const v = payload?.text;
return typeof v === 'string' ? v : '';
}
/**
* Append every custom event `asset` declares within `runs` to `out`, run by run
* and then in declaration order, so a long frame still reports swing before hit.
* `childPath` is not read: the event happened to the character the clip plays on.
*/
export function collectCustomEvents(
asset: TimelineAsset, runs: readonly PlayheadRun[], out: MotionEvent[],
): void {
for (const run of runs) {
for (const track of asset.tracks) {
if (track.type !== TrackType.CustomEvent) continue;
for (const event of track.events) {
if (!runCrosses(run, event.time)) continue;
out.push({
name: event.name,
value: payloadValue(event.payload),
text: payloadText(event.payload),
});
}
}
}
}