Skip to content

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.

3.9 KB
Raw Blame
// 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)));
}