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 timelineMotion.ts
* @brief The `timeline` motion kind: an animator state driving an `.estimeline`.
*
* @details This is what lets one animator graph animate a skinned model. A
* skeletal clip IS a timeline - property tracks writing each joint
* entity's Transform - so this driver samples the same asset with the
* same evaluator, and what it produces is a pose rather than a write.
* The path from joint Transform to MeshSkin is unchanged: the animator
* adds no second owner of a bone pose.
*
* It does not touch TimelinePlayer. That component carries a clip's own
* clock for standalone playback, and one clock cannot serve two clips
* at once - which crossfade needs. The animator keeps the time and
* hands it in; TimelinePlayer stays what a timeline plays on when no
* animator is involved.
*/
import type {
MotionDriver, AnimatorClipMotion, MotionContext, MotionSpan, MotionEvent, RootMotionDelta,
} from '../animation/motion';
import type { Pose } from '../animation/pose';
import { getComponent } from '../ecs/component';
import {
applyWrapMode, sampleTimelineIntoPose, isRootPlacementChannel,
sampleRootPlacement, createRootPlacement, type SampleDeps, type SampleOptions,
} from './TimelineEvaluator';
import { playheadRuns, collectCustomEvents, forEachParticleEvent } from './timelineEvents';
import { applyTimelineEvent, resolveChildEntity, TimelineEventType } from './TimelineRuntime';
import { TrackType, WrapMode, type TimelineAsset } from './TimelineTypes';
import type { ParticleAPI } from '../particle/ParticleAPI';
import { q } from '../math/quat';
import type { TimelineAPI } from './TimelineControl';
export const TIMELINE_MOTION = 'timeline';
/** How the motion wants the clip wrapped; unstated leaves the clip's own. */
function wrapOf(motion: AnimatorClipMotion, asset: TimelineAsset): WrapMode {
if (motion.loop === undefined) return asset.wrapMode;
return motion.loop ? WrapMode.Loop : WrapMode.Once;
}
const speedOf = (motion: AnimatorClipMotion): number => Math.max(motion.speed ?? 1, 1e-4);
/**
* What the pose must not state while the animator is taking the root track as
* displacement. Not a filter the animator passes in: which channels those are is
* the evaluator's own answer, and the extractor reads the same one.
*/
const WITHOUT_ROOT: SampleOptions = { skipChannel: isRootPlacementChannel };
/**
* The driver, over the app's own {@link TimelineAPI}: which clip a name resolves
* to is per App, so this is built per App rather than being a module value.
*/
export interface TimelineMotionEffects {
/** Resolve lazily: a module may be installed after the timeline plugin. Per App. */
particle?: () => Pick<ParticleAPI, 'play' | 'stop' | 'reset'> | null;
}
export function createTimelineMotionDriver(timeline: TimelineAPI, effects: TimelineMotionEffects = {}): MotionDriver<AnimatorClipMotion> {
// Two placements, reused: extraction runs per animated entity per frame, and
// one of these per call is an allocation the steady state does not need.
const before = createRootPlacement();
const after = createRootPlacement();
/** The span in the CLIP's own time, split where its wrap makes it discontinuous. */
const runsOf = (asset: TimelineAsset, motion: AnimatorClipMotion, span: MotionSpan) => {
const speed = speedOf(motion);
return playheadRuns(
span.from * speed, span.to * speed,
asset.duration, wrapOf(motion, asset), span.inclusiveStart,
);
};
// One deps record, re-aimed per call. The sampler asks it for the world and
// the child resolver; both are the same for every entity in a frame except
// the world reference, which the context supplies.
const deps: SampleDeps = {
world: null!,
getComponent,
resolveChild: (root, childPath) => resolveChildEntity(deps.world as never, root, childPath),
};
return {
sample(ctx: MotionContext, motion: AnimatorClipMotion, time: number, pose: Pose): boolean {
const asset = timeline.getAsset(motion.clip);
if (!asset) return false;
const local = applyWrapMode(time * speedOf(motion), asset.duration, wrapOf(motion, asset));
deps.world = ctx.world;
// Through the animator's resolver: a rig with an avatar spells its
// joints its own way, and a driver reaching for childPath directly
// would drive the joints of whoever exported the clip.
deps.resolveChild = ctx.resolveJoint;
sampleTimelineIntoPose(
asset, local.time, ctx.entity, deps, pose,
ctx.extractRootMotion ? WITHOUT_ROOT : undefined,
);
return true;
},
events(
ctx: MotionContext, motion: AnimatorClipMotion, span: MotionSpan, out: MotionEvent[],
): void {
const asset = timeline.getAsset(motion.clip);
if (!asset) return;
const runs = runsOf(asset, motion, span);
collectCustomEvents(asset, runs, out);
const particle = effects.particle?.();
if (!particle) return;
for (const track of asset.tracks) {
if (track.type !== TrackType.Particle) continue;
const target = ctx.resolveJoint(ctx.entity, track.childPath);
if (target === null) continue;
forEachParticleEvent(track, runs, action => {
applyTimelineEvent(ctx.world, null, TimelineEventType.ParticleAction, target, 0, 0, action, particle);
});
}
},
/**
* The clip's own displacement over the span, summed run by run: a lap
* boundary is a jump in clip time and a difference across it would read
* as the character teleporting back to where the clip starts.
*/
rootMotion(
_ctx: MotionContext, motion: AnimatorClipMotion,
span: MotionSpan, out: RootMotionDelta,
): boolean {
const asset = timeline.getAsset(motion.clip);
if (!asset || !sampleRootPlacement(asset, 0, before)) return false;
out.position.x = 0; out.position.y = 0; out.position.z = 0;
let turn = { w: 1, x: 0, y: 0, z: 0 };
for (const run of runsOf(asset, motion, span)) {
sampleRootPlacement(asset, run.from, before);
sampleRootPlacement(asset, run.to, after);
out.position.x += after.position.x - before.position.x;
out.position.y += after.position.y - before.position.y;
out.position.z += after.position.z - before.position.z;
turn = q.mul(q.mul(after.rotation, q.conjugate(before.rotation)), turn);
}
out.rotation.w = turn.w; out.rotation.x = turn.x;
out.rotation.y = turn.y; out.rotation.z = turn.z;
return true;
},
/** In the animator's own seconds, which is why the speed divides out. */
duration(_ctx: MotionContext, motion: AnimatorClipMotion): number {
return (timeline.getAsset(motion.clip)?.duration ?? 0) / speedOf(motion);
},
loops(_ctx: MotionContext, motion: AnimatorClipMotion): boolean {
const asset = timeline.getAsset(motion.clip);
return asset ? wrapOf(motion, asset) !== WrapMode.Once : false;
},
};
}