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.

10.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    animatorAvatar.ts
 * @brief   How one rig spells the joints another rig's clips name.
 *
 * @details A clip addresses what it animates by `childPath`, which is the name
 *          whoever exported the model chose. Two characters rigged by two people
 *          therefore share no clip at all, and the corpus shows the cost: an
 *          enemy has to be rigged with the names its clips already use.
 *
 *          An avatar is the translation, and it is a property of the RIG, not of
 *          the controller: one controller drives many characters, and what each
 *          of them calls its left hand is each of their own business.
 *
 *          It applies at the one place a path becomes an entity. There is no
 *          retarget stage and no rewritten clip — a clip is data several rigs can
 *          read at once, and rewriting it on load would make one copy per rig and
 *          a question about which copy a change reached.
 */

import type { Entity } from '../types';
import type { World } from '../ecs/world';
import { resolveChildEntity } from '../ecs/childPath';
import { Transform } from '../ecs/component';
import { q } from '../math/quat';
import type { Pose, PoseWorld } from './pose';
import type { QuatLike } from './quatMix';

/** A rig's own spelling for each joint a clip may name, and how it stands at rest. */
export interface AnimatorAvatar {
    /**
     * The name a clip uses → the `childPath` this rig reaches that joint by. A
     * name with no entry resolves as itself, so a clip authored against this rig
     * keeps working and an avatar can translate only what differs.
     */
    joints: Record<string, string>;
    /**
     * Each joint's rotation in the BIND pose, by the name `joints` uses. What a
     * clip states is where a joint is, and what it MEANS is the offset from where
     * that joint rests — two rigs bound differently need this to read one clip
     * the same way. Absent for a rig nothing is retargeted onto.
     */
    rest?: Record<string, Quat>;
    /**
     * Each joint's PARENT at rest, as a rotation in the rig's own space — what a
     * joint's local values are expressed in. Two rigs whose skeletons stand on
     * different axes (one Z-up under a turned root, one Y-up) read one clip the
     * same way only through this. Absent is the identity.
     */
    space?: Record<string, Quat>;
    /** Each joint's local position at rest: a clip that moves a joint (the hips)
     *  moves it FROM here, so another rig needs its own. */
    restPosition?: Record<string, Vec3>;
    /**
     * Root to the joint furthest from it, at rest — the ONE measure every avatar
     * uses, since two measured differently give a ratio that means nothing. What
     * it buys is displacement: a step authored on a smaller rig slides on a
     * taller one unless it travels further.
     */
    scale?: number;
}

interface Quat { w: number; x: number; y: number; z: number }
interface Vec3 { x: number; y: number; z: number }

/** Finding a joint on a rig, whichever way a clip spelled it. */
export type JointResolver = (root: Entity, path: string) => Entity | null;

/** What a `.esavatar` this build writes claims. */
export const AVATAR_FORMAT_VERSION = 1;

/**
 * Read a parsed `.esavatar`. Throws for a shape that is not one and for a
 * version this build does not know — the same upward guard a controller has, for
 * the same reason: a translation half-read animates the wrong joints in silence.
 */
export function parseAvatar(raw: unknown): AnimatorAvatar {
    if (typeof raw !== 'object' || raw === null) throw new Error('Avatar data must be an object');
    const obj = raw as Record<string, unknown>;
    const version = obj['version'];
    if (version !== undefined && (typeof version !== 'number' || !Number.isInteger(version))) {
        throw new Error('Avatar "version" must be an integer');
    }
    if ((version as number | undefined ?? AVATAR_FORMAT_VERSION) > AVATAR_FORMAT_VERSION) {
        throw new Error(
            `Avatar is version ${version}; this build reads up to ${AVATAR_FORMAT_VERSION}.`,
        );
    }
    const joints = obj['joints'];
    if (typeof joints !== 'object' || joints === null || Array.isArray(joints)) {
        throw new Error('An avatar needs a "joints" object mapping clip names to childPaths');
    }
    const out: Record<string, string> = {};
    for (const [name, path] of Object.entries(joints as Record<string, unknown>)) {
        if (typeof path !== 'string') {
            throw new Error(`Avatar joint "${name}" must map to a childPath string`);
        }
        // An entry mapping a name to itself is what having no entry already means.
        if (path && path !== name) out[name] = path;
    }
    const scale = obj['scale'];
    if (scale !== undefined && (typeof scale !== 'number' || !(scale > 0))) {
        throw new Error('Avatar "scale" must be a positive number');
    }
    const rest = obj['rest'] === undefined ? undefined : readRest(obj['rest']);
    const space = obj['space'] === undefined ? undefined : readRest(obj['space']);
    const restPosition = obj['restPosition'] === undefined ? undefined : readPositions(obj['restPosition']);
    const avatar: AnimatorAvatar = { joints: out };
    if (rest) avatar.rest = rest;
    if (space) avatar.space = space;
    if (restPosition) avatar.restPosition = restPosition;
    if (scale !== undefined) avatar.scale = scale as number;
    return avatar;
}

/**
 * How far a clip authored against `source` should travel on `target`. One where
 * either rig does not state its size — a ratio against a guess would move a
 * character by an amount nobody chose.
 */
export function travelRatio(
    source: AnimatorAvatar | null, target: AnimatorAvatar | null,
): number {
    const from = source?.scale;
    const to = target?.scale;
    return from && to ? to / from : 1;
}

/** The bind pose, one rotation per joint. A joint listed without a usable
 *  rotation is refused rather than defaulted: an identity nobody meant would
 *  rebase every clip through a pose the rig is not in. */
function readRest(raw: unknown): Record<string, Quat> {
    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
        throw new Error('Avatar "rest" must be an object of joint rotations');
    }
    const out: Record<string, Quat> = {};
    for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
        const q = value as Partial<Quat> | null;
        if (!q || ['w', 'x', 'y', 'z'].some((k) => typeof q[k as 'w'] !== 'number')) {
            throw new Error(`Avatar rest pose for "${name}" must be a quaternion`);
        }
        out[name] = { w: q.w!, x: q.x!, y: q.y!, z: q.z! };
    }
    return out;
}

/** Rest positions, one per joint; a joint listed without all three is refused. */
function readPositions(raw: unknown): Record<string, Vec3> {
    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
        throw new Error('Avatar "restPosition" must be an object of joint positions');
    }
    const out: Record<string, Vec3> = {};
    for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
        const v = value as Partial<Vec3> | null;
        if (!v || ['x', 'y', 'z'].some((k) => typeof v[k as 'x'] !== 'number')) {
            throw new Error(`Avatar rest position for "${name}" must be a vector`);
        }
        out[name] = { x: v.x!, y: v.y!, z: v.z! };
    }
    return out;
}

/** A blank avatar, which translates nothing and resolves every path as itself. */
export function emptyAvatar(): AnimatorAvatar & { version: number } {
    return { version: AVATAR_FORMAT_VERSION, joints: {} };
}

/**
 * The resolver a rig with `avatar` uses. Null for no avatar rather than an
 * identity one, so the common case reaches {@link resolveChildEntity} with
 * nothing in between.
 */
export function avatarResolver(
    world: Pick<World, 'tryGet'>, avatar: AnimatorAvatar | null,
): JointResolver {
    if (!avatar) return (root, path) => resolveChildEntity(world, root, path);
    return (root, path) => resolveChildEntity(world, root, avatar.joints[path] ?? path);
}

/**
 * Re-state `pose` as this rig would stand it: a clip means a joint's turn off its
 * rest in rig space, `D = Sₚ·stated·(Sₚ·rest)⁻¹`, which the target stands on its own
 * rest as `Tₚ⁻¹·D·Tₚ·targetRest` (Sₚ, Tₚ each rig's parent space). A moved joint
 * moves by the same rig-space displacement, scaled by the rigs' sizes.
 */
export function rebasePose(
    pose: Pose, root: Entity, source: AnimatorAvatar, target: AnimatorAvatar,
    resolveJoint: JointResolver, world: PoseWorld,
): void {
    const rests = source.rest;
    const targetRests = target.rest;
    if (!rests || !targetRests) return;
    const ratio = travelRatio(source, target);
    for (const [joint, sourceRest] of Object.entries(rests)) {
        const targetRest = targetRests[joint];
        if (!targetRest) continue;
        const entity = resolveJoint(root, joint);
        if (entity === null) continue;
        const track = pose.track(world, entity, Transform);
        if (!track || !track.touched.has('rotation')) continue;
        const stated = track.data.rotation as QuatLike | undefined;
        if (!stated) continue;
        const sp = source.space?.[joint] ?? IDENTITY;
        const tp = target.space?.[joint] ?? IDENTITY;
        const turn = q.mul(q.mul(sp, stated), q.conjugate(q.mul(sp, sourceRest)));
        const rebased = q.normalize(q.mul(q.mul(q.conjugate(tp), q.mul(turn, tp)), targetRest));
        track.data.rotation = { w: rebased.w, x: rebased.x, y: rebased.y, z: rebased.z };

        const from = source.restPosition?.[joint];
        const onto = target.restPosition?.[joint];
        const moved = track.touched.has('position') ? track.data.position as Vec3 | undefined : undefined;
        if (from && onto && moved) {
            const away = q.rotate(q.conjugate(tp), q.rotate(sp, {
                x: moved.x - from.x, y: moved.y - from.y, z: moved.z - from.z,
            }));
            track.data.position = { x: onto.x + away.x * ratio, y: onto.y + away.y * ratio, z: onto.z + away.z * ratio };
        }
    }
}

const IDENTITY: Quat = { w: 1, x: 0, y: 0, z: 0 };