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 TimelineEvaluator.ts
* @brief Pure-TS timeline sampler — evaluate a TimelineAsset at an absolute
* time and apply its property tracks to the world.
*
* The engine's C++ TimelineSystem is a temporary implementation. This is the
* modern replacement's kernel: ONE
* sample(time) call drives both forward playback (advance the clock, then sample)
* and editor scrubbing (sample at any T) — so the editor gets "scrub ==
* evaluate-at-T" for free, with no separate evaluate/apply paths.
*
* The interpolation math is a 1:1 port of TimelineSystem.cpp::evaluateChannel
* (hermite/linear/step/ease) so playback and editor preview match the C++ path
* numerically, and P4 can delete the C++ runtime with no regression.
*
* The sampler is dependency-injected (world / component lookup / child resolution)
* so it is a pure function: unit-testable without WASM and reusable by both the
* runtime and the editor preview bridge.
*/
import { TrackType, WrapMode, type TimelineAsset, type PropertyChannel } from './TimelineTypes';
import { sampleKeyframes } from '../math/keyframes';
import { setNestedProperty, resolveChildEntity } from './TimelineRuntime';
import { getComponent, type AnyComponentDef } from '../ecs/component';
import type { Pose, PoseTrack, PoseWorld } from '../animation/pose';
import { q } from '../math/quat';
import type { Entity, Quat, Vec3 } from '../types';
import type { World } from '../ecs/world';
const RAD2DEG = 180 / Math.PI;
/** Evaluate a single property channel at `time` (seconds). Endpoints clamp. */
export function evaluateChannel(channel: PropertyChannel, time: number): number {
return sampleKeyframes(channel.keyframes, time);
}
/** Map an absolute time through the clip's wrap mode (for forward playback). */
export function applyWrapMode(
time: number, duration: number, mode: WrapMode,
): { time: number; stopped: boolean } {
if (duration <= 0) return { time: 0, stopped: true };
if (time < 0) return { time: 0, stopped: false };
if (time < duration) return { time, stopped: false };
switch (mode) {
case WrapMode.Loop:
return { time: time % duration, stopped: false };
case WrapMode.PingPong: {
const cycle = duration * 2;
const t = time % cycle;
return { time: t <= duration ? t : cycle - t, stopped: false };
}
case WrapMode.Once:
default:
return { time: duration, stopped: true };
}
}
// ---------------------------------------------------------------------------
// Field application — the reflection writer table
// ---------------------------------------------------------------------------
type FieldWriter = (data: any, value: number) => void;
/**
* Per-field writers for animatable paths whose JS shape differs from the raw
* dot-path, so a generic `setNestedProperty` would corrupt them.
*
* `rotation.angle` is the Z turn in radians, and it COMPOSES: the other two axes
* survive it, so a clip turning a model about Z cannot flatten its pose. The
* four components are written raw, normalized in {@link finishQuaternions}.
*/
const WRITER_OVERRIDES: Record<string, FieldWriter> = {
'Transform.rotation.angle': (data, v) => {
data.rotation = q.setAngleZ(data.rotation, v * RAD2DEG);
},
};
/** Component fields written component-wise that must end up unit length. */
const QUATERNION_FIELDS: Record<string, readonly string[]> = {
Transform: ['rotation'],
};
/**
* Renormalize any quaternion a track wrote component-wise. Interpolating the
* four numbers independently lands INSIDE the unit sphere — about 0.92 halfway
* between two rotations 90° apart — and writing that scales the object.
* Normalized it traces the arc slerp would, differing only in angular speed.
*/
function finishQuaternions(data: any, component: string, touched: Set<string>): void {
for (const field of QUATERNION_FIELDS[component] ?? []) {
if (!touched.has(field)) continue;
data[field] = q.normalize(data[field]);
}
}
function applyField(data: any, component: string, property: string, value: number): boolean {
const override = WRITER_OVERRIDES[`${component}.${property}`];
if (override) {
override(data, value);
return true;
}
return setNestedProperty(data, property, value);
}
// ---------------------------------------------------------------------------
// The root track — where the clip says the ENTITY goes, not how it is posed
// ---------------------------------------------------------------------------
/**
* Whether a channel states the placement of the entity the clip is played ON —
* the whole of root motion: a channel aimed at a child poses a bone, one aimed at
* nothing says where the character travels. Read by both the sampler that leaves
* these out of the pose and the extractor, so the two cannot disagree.
*/
export function isRootPlacementChannel(
childPath: string, component: string, property: string,
): boolean {
return childPath === '' && component === 'Transform'
&& (property.startsWith('position') || property.startsWith('rotation'));
}
/** Where a clip says its entity stands, over a base that states nothing. */
export interface RootPlacement {
position: Vec3;
rotation: Quat;
}
/** A placement holder to sample into; the base is neutral, see below. */
export function createRootPlacement(): RootPlacement {
return { position: { x: 0, y: 0, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 } };
}
function resetRootPlacement(out: RootPlacement): void {
out.position.x = 0; out.position.y = 0; out.position.z = 0;
out.rotation = { w: 1, x: 0, y: 0, z: 0 };
}
/**
* The root placement `asset` states at `time`, into `out`. Over a NEUTRAL base:
* two of these are only ever subtracted, so the entity's own values would cancel
* anyway while making the answer depend on where the character stood.
*
* False when the clip states no root track — not the same as one holding still.
*/
export function sampleRootPlacement(
asset: TimelineAsset, time: number, out: RootPlacement,
): boolean {
resetRootPlacement(out);
let stated = false;
for (const track of asset.tracks) {
if (track.type !== TrackType.Property) continue;
if (track.childPath !== '' || track.component !== 'Transform') continue;
const touched = new Set<string>();
for (const ch of track.channels) {
if (!ch.keyframes || ch.keyframes.length === 0) continue;
if (!isRootPlacementChannel(track.childPath, track.component, ch.property)) continue;
if (applyField(out, 'Transform', ch.property, evaluateChannel(ch, time))) {
touched.add(ch.property.split('.')[0]!);
}
}
if (touched.size > 0) {
finishQuaternions(out, 'Transform', touched);
stated = true;
}
}
return stated;
}
// ---------------------------------------------------------------------------
// Sampler
// ---------------------------------------------------------------------------
/** Minimal world surface the sampler needs (component get/set by definition). */
export interface SampleWorld {
has(entity: Entity, def: AnyComponentDef): boolean;
get(entity: Entity, def: AnyComponentDef): Record<string, unknown>;
set(entity: Entity, def: AnyComponentDef, data: Record<string, unknown>): void;
}
export interface SampleDeps {
world: SampleWorld;
getComponent: (name: string) => AnyComponentDef | undefined;
resolveChild: (root: Entity, childPath: string) => Entity | null;
}
export interface SampleOptions {
/** Return true to skip a channel — the editor uses this for muted tracks. */
skipChannel?: (childPath: string, component: string, property: string) => boolean;
}
/**
* Where a sampled track's values land: the world, for standalone playback and
* the editor preview, or a {@link Pose}, for blending — values already written
* cannot be weighed against each other. One traversal serves both.
*/
export interface SampleSink {
/** The component data to write into, or null to skip this track. */
open(entity: Entity, def: AnyComponentDef): Record<string, unknown> | null;
/** Finish a track whose `touched` top-level fields were written. */
close(
entity: Entity, def: AnyComponentDef,
data: Record<string, unknown>, touched: ReadonlySet<string>,
): void;
}
/** The sink that writes the world directly. */
export function worldSink(world: SampleWorld): SampleSink {
return {
open: (entity, def) => (world.has(entity, def) ? world.get(entity, def) : null),
close: (entity, def, data) => { world.set(entity, def, data); },
};
}
/** The sink that records into a pose for later composition. */
export function poseSink(pose: Pose, world: PoseWorld): SampleSink {
let current: PoseTrack | null = null;
return {
open: (entity, def) => {
current = pose.track(world, entity, def);
return current?.data ?? null;
},
close: (_entity, _def, _data, touched) => {
if (!current) return;
for (const field of touched) current.touched.add(field);
current = null;
},
};
}
/**
* Evaluate every property track at `time` into `sink`. Property tracks only —
* spine, audio, spriteAnim and activation carry side effects a sink cannot hold.
* Each track touches one component on one entity, so it opens that component
* once and folds every channel into a single write.
*/
export function sampleTimelineInto(
asset: TimelineAsset, time: number, rootEntity: Entity,
deps: SampleDeps, sink: SampleSink, opts?: SampleOptions,
): void {
for (const track of asset.tracks) {
if (track.type !== TrackType.Property) continue;
const def = deps.getComponent(track.component);
if (!def) continue;
const entity = deps.resolveChild(rootEntity, track.childPath);
if (entity == null) continue;
const data = sink.open(entity, def);
if (!data) continue;
let changed = false;
const touched = new Set<string>();
for (const ch of track.channels) {
if (!ch.keyframes || ch.keyframes.length === 0) continue;
if (opts?.skipChannel?.(track.childPath, track.component, ch.property)) continue;
const v = evaluateChannel(ch, time);
if (applyField(data, track.component, ch.property, v)) {
changed = true;
touched.add(ch.property.split('.')[0]!);
}
}
if (changed) {
finishQuaternions(data, track.component, touched);
sink.close(entity, def, data, touched);
}
}
}
/** Evaluate every property track at `time` and write the results to the world. */
export function sampleTimeline(
asset: TimelineAsset, time: number, rootEntity: Entity, deps: SampleDeps, opts?: SampleOptions,
): void {
sampleTimelineInto(asset, time, rootEntity, deps, worldSink(deps.world), opts);
}
/**
* Evaluate every property track at `time` into `pose`, touching no component.
* What a motion says, held apart from what the entity becomes.
*/
export function sampleTimelineIntoPose(
asset: TimelineAsset, time: number, rootEntity: Entity,
deps: SampleDeps, pose: Pose, opts?: SampleOptions,
): void {
sampleTimelineInto(asset, time, rootEntity, deps, poseSink(pose, deps.world), opts);
}
/**
* Convenience wrapper binding the real SDK component registry + child resolver.
* The editor preview bridge and the runtime both call this; tests inject mocks
* into {@link sampleTimeline} directly.
*/
export function sampleTimelineInWorld(
asset: TimelineAsset, time: number, world: SampleWorld & Pick<World, 'tryGet'>, rootEntity: Entity, opts?: SampleOptions,
): void {
sampleTimeline(asset, time, rootEntity, {
world,
getComponent,
resolveChild: (root, childPath) => resolveChildEntity(world, root, childPath),
}, opts);
}