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 timelineSequences.ts
* @brief Which timelines play inside which, and which camera is the view when.
*
* Both are pure functions of (asset, time), so playback, scrubbing and a backwards run all ask the
* same question and get the same answer: nothing here remembers the previous frame.
*/
import { TrackType, type CameraClip, type SequenceClip, type TimelineAsset } from './TimelineTypes';
import type { Entity } from '../types';
/** Timelines nested deeper than this are not played (and the editor refuses to build them). */
export const MAX_SEQUENCE_DEPTH = 4;
/** What a nested timeline sees: its own clock, and the entity its name paths start from. */
export interface SequenceLayer {
/** Stable across frames while the clip plays: which track and clip, down the nesting. */
key: string;
asset: TimelineAsset;
ref: string;
/** The nested timeline's own time. */
time: number;
clip: SequenceClip;
root: Entity;
}
export type SequenceLookup = (ref: string) => TimelineAsset | undefined;
export type ChildResolver = (root: Entity, childPath: string) => Entity | null;
/** The time a nested timeline is at when its parent is at `parentTime`, or null outside the clip. */
export function sequenceLocalTime(clip: SequenceClip, parentTime: number, childDuration: number): number | null {
if (parentTime < clip.start || parentTime >= clip.start + clip.duration) return null;
const raw = (parentTime - clip.start) * clip.speed;
if (childDuration <= 0) return 0;
if (clip.loop) return raw % childDuration;
return raw >= childDuration ? childDuration : raw;
}
/**
* The timelines playing inside `asset` at `time`, outermost first, with each one's own time and root.
* A timeline already on the way down (a loop) or past the depth limit is skipped, not entered.
*/
export function collectSequenceLayers(
asset: TimelineAsset, time: number, root: Entity, resolveChild: ChildResolver, lookup: SequenceLookup,
chain: readonly string[] = [], keyPrefix = '', depth = 0,
): SequenceLayer[] {
if (depth >= MAX_SEQUENCE_DEPTH) return [];
const out: SequenceLayer[] = [];
asset.tracks.forEach((track, ti) => {
if (track.type !== TrackType.Sequence) return;
track.clips.forEach((clip, ci) => {
if (!clip.timeline || chain.includes(clip.timeline)) return;
const child = lookup(clip.timeline);
if (!child) return;
const local = sequenceLocalTime(clip, time, child.duration);
if (local === null) return;
const childRoot = clip.root ? resolveChild(root, clip.root) : root;
if (childRoot == null) return;
const key = `${keyPrefix}${ti}.${ci}/`;
out.push({ key, asset: child, ref: clip.timeline, time: local, clip, root: childRoot });
out.push(...collectSequenceLayers(child, local, childRoot, resolveChild, lookup, [...chain, clip.timeline], key, depth + 1));
});
});
return out;
}
/** Whether `ref` can be played inside `asset` without it ending up inside itself, by whatever route. */
export function wouldNestCycle(host: string, ref: string, lookup: SequenceLookup): boolean {
if (host === ref) return true;
const seen = new Set<string>();
const reaches = (from: string): boolean => {
if (from === host) return true;
if (seen.has(from)) return false;
seen.add(from);
const asset = lookup(from);
if (!asset) return false;
for (const track of asset.tracks) {
if (track.type !== TrackType.Sequence) continue;
for (const clip of track.clips) if (clip.timeline && reaches(clip.timeline)) return true;
}
return false;
};
return reaches(ref);
}
/** The view at one moment: `to` is the camera now, `from` the one it is leaving, `weight` how far across. */
export interface ShotState {
from: string | null;
to: string;
/** 0..1 along the overlap; 1 when there is nothing being left. */
weight: number;
curve: number;
}
/**
* Which camera is the view at `time`. Clips that touch cut; clips that overlap blend over the overlap.
* No clip over `time` is no answer (null): the scene's own camera takes over.
*/
export function resolveShot(clips: readonly CameraClip[], time: number): ShotState | null {
const live = clips
.filter((c) => c.camera && time >= c.start && (time < c.start + c.duration || (c.duration === 0 && time === c.start)))
.sort((a, b) => a.start - b.start);
if (live.length === 0) return null;
const to = live[live.length - 1]!;
const from = live.length > 1 ? live[live.length - 2]! : null;
if (!from) return { from: null, to: to.camera, weight: 1, curve: to.curve ?? 3 };
const overlap = from.start + from.duration - to.start;
const weight = overlap > 0 ? Math.min(1, Math.max(0, (time - to.start) / overlap)) : 1;
return { from: from.camera, to: to.camera, weight, curve: to.curve ?? 3 };
}
/** A shot with its cameras resolved to entities — what the camera director takes. */
export interface ActiveShot {
from: Entity | null;
to: Entity;
weight: number;
curve: number;
}
/**
* The shot at `time` across a timeline and the ones nested in it: the outermost timeline that has a camera
* answer wins, so a parent's cut is not overridden by what a child inside it was doing.
*/
export function resolveActiveShot(
asset: TimelineAsset, time: number, root: Entity, resolveChild: ChildResolver, lookup: SequenceLookup,
): ActiveShot | null {
const tryAsset = (a: TimelineAsset, t: number, r: Entity): ActiveShot | null => {
for (const track of a.tracks) {
if (track.type !== TrackType.Camera) continue;
const shot = resolveShot(track.clips, t);
if (!shot) continue;
const to = resolveChild(r, shot.to);
if (to == null) continue;
const from = shot.from === null ? null : resolveChild(r, shot.from);
return { from: from ?? null, to, weight: from == null ? 1 : shot.weight, curve: shot.curve };
}
return null;
};
const own = tryAsset(asset, time, root);
if (own) return own;
for (const layer of collectSequenceLayers(asset, time, root, resolveChild, lookup)) {
const shot = tryAsset(layer.asset, layer.time, layer.root);
if (shot) return shot;
}
return null;
}