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 AnimatorControllerAssetLoader.ts
* @brief Loads a `.esanimator` into the controller store under every ref a
* component may spell it as, so an Animator resolves it at runtime.
*
* Mirrors {@link file://./FsmAssetLoader.ts}: published by its slot, so a
* retiring era cannot take the newer one out from under the same name.
*/
import type {
AssetLoader, LoadContext, AnimatorControllerResult, RegistryAssetLoader,
} from '../AssetLoader';
import type { RegistryEra } from '../registryAssets';
import { animatorScopes } from '../../animation/Animator';
import type { AnimatorControllerDef, AnimatorState } from '../../animation/Animator';
import { isBlend1D, isBlend2D, type AnimatorMotion } from '../../animation/motion';
import { migrateAnimatorController } from '../../animation/animatorMigrate';
import { resolveDocumentRef } from '../documentRef';
/**
* Motion kinds whose `clip` names an ASSET, and the type it loads as. A sprite
* clip and a spine animation are names their own runtime already holds, so they
* are absent rather than mapped to nothing.
*/
const MOTION_ASSET_TYPES: Readonly<Record<string, string>> = {
timeline: 'timeline',
};
/** Every motion in the controller, across its layers, blends and sub-machines. */
function* motionsOf(states: readonly AnimatorState[]): Generator<AnimatorMotion> {
for (const state of states) {
if (state.motion) yield* flatten(state.motion);
if (state.stateMachine) yield* motionsOf(state.stateMachine.states);
}
}
/** Across every layer: a clip only a layer plays is a clip a game plays. */
function* motionsOfController(def: AnimatorControllerDef): Generator<AnimatorMotion> {
for (const scope of animatorScopes(def)) yield* motionsOf(scope.states);
}
function* flatten(motion: AnimatorMotion): Generator<AnimatorMotion> {
yield motion;
if (isBlend1D(motion)) {
for (const stop of motion.thresholds) yield* flatten(stop.motion);
} else if (isBlend2D(motion)) {
for (const point of motion.points) yield* flatten(point.motion);
}
}
export class AnimatorControllerAssetLoader implements AssetLoader<AnimatorControllerResult> {
readonly type = 'animatorcontroller';
readonly extensions = ['.esanimator'];
readonly registry: RegistryAssetLoader<AnimatorControllerResult> = {
prepare: async (path: string, ctx: LoadContext): Promise<RegistryEra<AnimatorControllerResult>> => {
const text = await ctx.loadText(ctx.catalog.getBuildPath(path));
const { def } = migrateAnimatorController(JSON.parse(text));
await acquireMotionAssets(def, path, ctx);
return {
published: def,
value: { controllerId: path },
};
},
};
}
/**
* Load what the graph's motions play and the avatar its clips were authored on,
* resolving each ref IN PLACE: discovery walks components, which a controller's
* refs are not, and each is looked up by the name it carries. Without the avatar
* no retarget ever runs.
*/
async function acquireMotionAssets(
def: AnimatorControllerDef, path: string, ctx: LoadContext,
): Promise<void> {
const wanted = new Map<string, string>();
for (const motion of motionsOfController(def)) {
if (isBlend1D(motion) || isBlend2D(motion)) continue;
const type = MOTION_ASSET_TYPES[motion.kind];
if (!type || !motion.clip) continue;
motion.clip = resolveDocumentRef(path, motion.clip);
wanted.set(motion.clip, type);
}
if (def.avatar) {
def.avatar = resolveDocumentRef(path, def.avatar);
wanted.set(def.avatar, 'avatar');
}
// Leases are recorded against the scope loading this controller, which is
// what releases them when the scene that wanted it goes.
await Promise.all([...wanted].map(([ref, type]) => ctx.acquireAsset(type, ref)));
}