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.

19.1 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    AnimClipLoader.ts
 * @brief   .esanim asset format: parsing, serialization, sheet-grid math, and
 *          per-frame anchor resolution
 */

import type { SpriteAnimClip, SpriteAnimFrame } from './SpriteAnimator';
import { log } from '../util/logger';
import { uvRectFromPixels } from '../render/uvRect';
import {
    sheetCols, sheetRows, sheetCellRect, sheetCellUv, type SheetGrid,
} from '../asset/sheetGrid';

// =============================================================================
// .esanim File Format
// =============================================================================

export const ANIM_CLIP_FORMAT_VERSION = '1.5';

/**
 * A frame's anchor, normalized inside the frame's own rect — EXACTLY the space
 * `Sprite.pivot` uses: (0,0) = bottom-left, (0.5,0.5) = center, (1,1) = top-right.
 * The same numbers travel from the file to the component with no conversion, so
 * "feet on the ground" is `{ x: 0.5, y: 0 }` in both places. Values outside 0–1
 * are allowed (they anchor outside the frame), matching `Sprite.pivot`.
 */
export interface AnimClipPivotData {
    x: number;
    y: number;
}

/** The anchor a clip that authors pivots falls back to — the `Sprite.pivot` default. */
export const DEFAULT_ANIM_CLIP_PIVOT: AnimClipPivotData = { x: 0.5, y: 0.5 };

/** A pair in the clip's own units — world units, which the engine authors at 1 = 1
 *  design pixel. Frame sizes and offsets are both in it. */
export interface AnimClipVec2 {
    x: number;
    y: number;
}

/**
 * Who owns `Sprite.size` while the clip plays. `'entity'` — the default, and what
 * every clip written before format 1.5 does — leaves the entity's size alone, so
 * every frame draws at that one size. `'frame'` hands size to the clip and each
 * frame draws at its own, which is what lets frames of DIFFERENT sizes share a clip.
 */
export type AnimClipSizing = 'entity' | 'frame';

/**
 * Sprite-sheet slicing grid. When present, frames may reference grid cells
 * instead of per-frame textures; all cell frames share `texture`.
 * `pageWidth`/`pageHeight` are baked by the editor from the image's natural
 * size (UV normalization needs them; the runtime never reads the image).
 */
/** A clip's sheet: the cutting geometry every sheet has, plus the image it cuts. */
export interface AnimClipSheetData extends SheetGrid {
    texture: string;
}

export interface AnimClipFrameData {
    /** Per-frame texture ref; absent on sheet-cell frames. */
    texture?: string;
    /** Sheet cell index (row-major, 0-based); requires a `sheet` section. */
    cell?: number;
    duration?: number;
    /**
     * Anchor override for this frame; absent = the clip's `pivot`. Added in format
     * 1.4 — this is what keeps a character's feet planted when the artwork shifts
     * inside the cell from frame to frame.
     */
    pivot?: AnimClipPivotData;
    /**
     * What this frame draws at. Absent = its own natural size (its sheet cell, or
     * its texture's pixels), which is what an author almost always means.
     */
    size?: AnimClipVec2;
    /**
     * Shifts this frame's artwork away from the clip's anchor, in {@link size}'s
     * units, and folded into the frame's pivot at load. Units rather than a
     * normalized pivot because the same offset is the same visual shift on frames
     * of any size — a pivot is not.
     */
    offset?: AnimClipVec2;
    atlasFrame?: {
        x: number;
        y: number;
        width: number;
        height: number;
        pageWidth: number;
        pageHeight: number;
    };
}

/**
 * A frame event: as the playhead crosses `frame`, the runtime fires `name`
 * (with optional `data`) to any listener. Added in format 1.3; the runtime
 * (SpriteAnimator) always supported events, only the format/editor did not.
 */
export interface AnimClipEventData {
    frame: number;
    name: string;
    data?: unknown;
}

export interface AnimClipAssetData {
    version: string;
    type: 'animation-clip';
    fps?: number;
    loop?: boolean;
    /**
     * Clip-wide anchor every frame inherits (frames override it per frame) — the
     * same fallback relationship `fps` has with per-frame `duration`. Absent means
     * the clip does not author anchors at all and playback leaves `Sprite.pivot`
     * exactly as the entity authored it.
     */
    pivot?: AnimClipPivotData;
    /** Who owns `Sprite.size` — see {@link AnimClipSizing}. Absent = `'entity'`. */
    frameSizing?: AnimClipSizing;
    sheet?: AnimClipSheetData;
    frames: AnimClipFrameData[];
    events?: AnimClipEventData[];
}

// =============================================================================
// Sheet grid math
// =============================================================================

// The arithmetic is asset/sheetGrid.ts's; these four are its `.esanim` spellings,
// kept because the flipbook's own code reads them. New callers take the neutral
// names — a sprite should not have to call itself an anim clip to find a cell.

/** @see sheetCols */
export function animClipSheetCols(sheet: AnimClipSheetData): number {
    return sheetCols(sheet);
}

/** @see sheetRows */
export function animClipSheetRows(sheet: AnimClipSheetData): number {
    return sheetRows(sheet);
}

/** @see sheetCellRect */
export function animClipCellRect(
    sheet: AnimClipSheetData,
    cell: number,
): { x: number; y: number; width: number; height: number } {
    return sheetCellRect(sheet, cell);
}

/** @see sheetCellUv */
export function animClipCellUv(
    sheet: AnimClipSheetData,
    cell: number,
): { uvOffset: { x: number; y: number }; uvScale: { x: number; y: number } } {
    return sheetCellUv(sheet, cell);
}

// =============================================================================
// Frame geometry — size and anchor
// =============================================================================

/**
 * Does this clip author anchors at all? True as soon as the clip OR any single
 * frame declares one. All-or-nothing on purpose: a clip that anchored only some
 * frames would leave the last override standing on the plain ones — the same
 * staleness the UV window has to reset away.
 *
 * An offset counts: it IS an anchor, written in units instead of fractions.
 */
export function animClipDrivesPivot(data: AnimClipAssetData): boolean {
    return data.pivot !== undefined
        || data.frames.some(f => f.pivot !== undefined || f.offset !== undefined);
}

/**
 * Does this clip own `Sprite.size`? The mode says so outright, an authored frame
 * size says so by existing — and so does an offset, which needs the size it is a
 * fraction of. Left to the entity, one clip on two entities would shift by two
 * different amounts, the very drift offsets exist to remove.
 */
export function animClipDrivesSize(data: AnimClipAssetData): boolean {
    return data.frameSizing === 'frame'
        || data.frames.some(f => f.size !== undefined || f.offset !== undefined);
}

/**
 * The size a frame renders at: its own override, else its natural size (the
 * caller's — a sheet cell, or the texture's pixels) — or `null` when the clip
 * does not own size, which leaves `Sprite.size` as the entity authored it.
 */
export function animClipFrameSize(
    data: AnimClipAssetData,
    frame: AnimClipFrameData,
    natural?: AnimClipVec2 | null,
): AnimClipVec2 | null {
    if (frame.size) return { x: frame.size.x, y: frame.size.y };
    if (!animClipDrivesSize(data)) return null;
    return natural ? { x: natural.x, y: natural.y } : null;
}

/**
 * The anchor a frame actually renders with: its own override, else the clip
 * default, else centered — or `null` when the clip authors no anchors, which is
 * the signal to leave `Sprite.pivot` exactly as the entity set it.
 *
 * The one place this resolution lives: the runtime bake, the edit-mode viewport
 * projection, and the editor's drag handle all read it here.
 */
export function animClipFramePivot(
    data: AnimClipAssetData,
    frame: AnimClipFrameData,
    size?: AnimClipVec2 | null,
): AnimClipPivotData | null {
    const base = frame.pivot
        ?? (animClipDrivesPivot(data) ? (data.pivot ?? DEFAULT_ANIM_CLIP_PIVOT) : null);
    if (!frame.offset) return base ? { x: base.x, y: base.y } : null;
    // Moving the artwork one way is the anchor moving the other. With no size to
    // divide by the shift is dropped rather than guessed; animClipDrivesSize is
    // what keeps that from happening on a clip that authors offsets.
    if (!size || size.x <= 0 || size.y <= 0) return base ? { x: base.x, y: base.y } : null;
    const b = base ?? DEFAULT_ANIM_CLIP_PIVOT;
    return { x: b.x - frame.offset.x / size.x, y: b.y - frame.offset.y / size.y };
}

// =============================================================================
// Parsing / serialization
// =============================================================================

const DEFAULT_FPS = 12;

function posInt(v: unknown, fallback: number): number {
    return typeof v === 'number' && Number.isInteger(v) && v > 0 ? v : fallback;
}

function nonNeg(v: unknown, fallback: number): number {
    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : fallback;
}

/** A `{x,y}` anchor, or undefined when the field is missing or not a finite pair.
 *  Deliberately unclamped: an anchor outside 0–1 is legal on `Sprite.pivot` too. */
function pivotOf(v: unknown): AnimClipPivotData | undefined {
    const p = v as { x?: unknown; y?: unknown } | null | undefined;
    if (!p || typeof p.x !== 'number' || typeof p.y !== 'number') return undefined;
    if (!Number.isFinite(p.x) || !Number.isFinite(p.y)) return undefined;
    return { x: p.x, y: p.y };
}

/** A `{x,y}` in clip units, or undefined. `positive` rejects a zero/negative size,
 *  which would divide an offset by nothing and blank the sprite. */
function vec2Of(v: unknown, positive: boolean): AnimClipVec2 | undefined {
    const p = v as { x?: unknown; y?: unknown } | null | undefined;
    if (!p || typeof p.x !== 'number' || typeof p.y !== 'number') return undefined;
    if (!Number.isFinite(p.x) || !Number.isFinite(p.y)) return undefined;
    if (positive && (p.x <= 0 || p.y <= 0)) return undefined;
    return { x: p.x, y: p.y };
}

/** Parse arbitrary JSON into a normalized {@link AnimClipAssetData} (tolerant of missing fields). */
export function parseAnimClipAsset(rawJson: unknown): AnimClipAssetData {
    const raw = rawJson as Record<string, any> | null | undefined;
    let sheet: AnimClipSheetData | undefined;
    const rs = raw?.sheet;
    if (rs && typeof rs.texture === 'string' && rs.texture) {
        sheet = {
            texture: rs.texture,
            cellWidth: posInt(rs.cellWidth, 32),
            cellHeight: posInt(rs.cellHeight, 32),
            margin: nonNeg(rs.margin, 0),
            spacing: nonNeg(rs.spacing, 0),
            pageWidth: posInt(rs.pageWidth, 1),
            pageHeight: posInt(rs.pageHeight, 1),
        };
    }
    const frames: AnimClipFrameData[] = [];
    for (const f of Array.isArray(raw?.frames) ? raw.frames : []) {
        if (!f) continue;
        const duration = typeof f.duration === 'number' && f.duration > 0 ? f.duration : undefined;
        const framePivot = pivotOf(f.pivot);
        const frameSize = vec2Of(f.size, true);
        const frameOffset = vec2Of(f.offset, false);
        if (sheet && typeof f.cell === 'number' && Number.isInteger(f.cell) && f.cell >= 0) {
            frames.push({
                cell: f.cell,
                ...(duration !== undefined ? { duration } : {}),
                ...(framePivot ? { pivot: framePivot } : {}),
                ...(frameSize ? { size: frameSize } : {}),
                ...(frameOffset ? { offset: frameOffset } : {}),
            });
        } else if (typeof f.texture === 'string' && f.texture) {
            const frame: AnimClipFrameData = { texture: f.texture };
            if (duration !== undefined) frame.duration = duration;
            if (framePivot) frame.pivot = framePivot;
            if (frameSize) frame.size = frameSize;
            if (frameOffset) frame.offset = frameOffset;
            const af = f.atlasFrame;
            if (af && [af.x, af.y, af.width, af.height, af.pageWidth, af.pageHeight]
                .every((n: unknown) => typeof n === 'number' && Number.isFinite(n))) {
                frame.atlasFrame = {
                    x: af.x, y: af.y, width: af.width, height: af.height,
                    pageWidth: af.pageWidth, pageHeight: af.pageHeight,
                };
            }
            frames.push(frame);
        }
    }
    const events: AnimClipEventData[] = [];
    for (const e of Array.isArray(raw?.events) ? raw.events : []) {
        if (e && typeof e.name === 'string' && e.name
            && typeof e.frame === 'number' && Number.isInteger(e.frame) && e.frame >= 0) {
            events.push({ frame: e.frame, name: e.name, ...(e.data !== undefined ? { data: e.data } : {}) });
        }
    }
    const clipPivot = pivotOf(raw?.pivot);
    const sizing: AnimClipSizing | undefined = raw?.frameSizing === 'frame' ? 'frame'
        : raw?.frameSizing === 'entity' ? 'entity' : undefined;
    return {
        version: typeof raw?.version === 'string' ? raw.version : ANIM_CLIP_FORMAT_VERSION,
        type: 'animation-clip',
        fps: posInt(raw?.fps, DEFAULT_FPS),
        loop: typeof raw?.loop === 'boolean' ? raw.loop : true,
        ...(clipPivot ? { pivot: clipPivot } : {}),
        ...(sizing ? { frameSizing: sizing } : {}),
        ...(sheet ? { sheet } : {}),
        frames,
        ...(events.length ? { events } : {}),
    };
}

/**
 * Serialize an {@link AnimClipAssetData} to a plain JSON-ready object (drops
 * empty/undefined). Stamps the CURRENT format version: whatever the file said when
 * it was read, this writer produced what is on disk now — a clip that gained 1.4
 * anchors must not keep claiming 1.3.
 */
export function serializeAnimClip(asset: AnimClipAssetData): Record<string, unknown> {
    return {
        version: ANIM_CLIP_FORMAT_VERSION,
        type: 'animation-clip',
        fps: asset.fps ?? DEFAULT_FPS,
        loop: asset.loop ?? true,
        ...(asset.pivot ? { pivot: { ...asset.pivot } } : {}),
        ...(asset.frameSizing ? { frameSizing: asset.frameSizing } : {}),
        ...(asset.sheet ? { sheet: { ...asset.sheet } } : {}),
        frames: asset.frames.map(f => ({
            ...f,
            ...(f.pivot ? { pivot: { ...f.pivot } } : {}),
            ...(f.size ? { size: { ...f.size } } : {}),
            ...(f.offset ? { offset: { ...f.offset } } : {}),
        })),
        ...(asset.events && asset.events.length ? { events: asset.events.map(e => ({ ...e })) } : {}),
    };
}

/** A fresh sheet-sliced clip over a texture (no frames yet). */
export function createAnimClip(
    texture: string,
    cellWidth: number,
    cellHeight: number,
    pageWidth: number,
    pageHeight: number,
): AnimClipAssetData {
    return {
        version: ANIM_CLIP_FORMAT_VERSION,
        type: 'animation-clip',
        fps: DEFAULT_FPS,
        loop: true,
        sheet: { texture, cellWidth, cellHeight, margin: 0, spacing: 0, pageWidth, pageHeight },
        frames: [],
    };
}

/**
 * A fresh clip over a sequence of per-frame textures — the shape a flipbook of
 * separate images is. Owns size from the start: images drawn at one shared size
 * is the thing an image sequence is authored to avoid.
 */
export function createAnimClipFromTextures(textures: string[]): AnimClipAssetData {
    return {
        version: ANIM_CLIP_FORMAT_VERSION,
        type: 'animation-clip',
        fps: DEFAULT_FPS,
        loop: true,
        frameSizing: 'frame',
        frames: textures.filter(t => !!t).map(texture => ({ texture })),
    };
}

// =============================================================================
// Runtime clip resolution
// =============================================================================

export function extractAnimClipTexturePaths(data: AnimClipAssetData): string[] {
    const paths = new Set<string>();
    if (data.sheet?.texture) {
        paths.add(data.sheet.texture);
    }
    for (const frame of data.frames) {
        if (frame.texture) {
            paths.add(frame.texture);
        }
    }
    return Array.from(paths);
}

function uvFromRect(
    rect: { x: number; y: number; width: number; height: number },
    pageWidth: number,
    pageHeight: number,
): Pick<SpriteAnimFrame, 'uvOffset' | 'uvScale'> {
    return uvRectFromPixels(rect, pageWidth, pageHeight);
}

/**
 * Bake a parsed clip into what the runtime plays. @p textureSizes carries each
 * frame texture's pixel size, which is the natural size of a per-texture frame —
 * without it a clip that owns size has nothing to fall back to and says so.
 */
export function parseAnimClipData(
    clipPath: string,
    data: AnimClipAssetData,
    textureHandles: Map<string, number>,
    textureSizes?: Map<string, AnimClipVec2>,
): SpriteAnimClip {
    const sheet = data.sheet;
    const cellCount = sheet ? animClipSheetCols(sheet) * animClipSheetRows(sheet) : 0;
    const drivesSize = animClipDrivesSize(data);
    let missingNatural = 0;
    const clip: SpriteAnimClip = {
        name: clipPath,
        fps: data.fps ?? DEFAULT_FPS,
        loop: data.loop ?? true,
        ...(data.events?.length ? { events: data.events.map(e => ({ frame: e.frame, name: e.name, data: e.data })) } : {}),
        frames: data.frames.map(f => {
            // Resolved once at load: at runtime a frame either carries the size and
            // anchor it renders with, or the clip authors none and playback leaves
            // the entity's own standing.
            const natural = sheet && f.cell !== undefined
                ? { x: sheet.cellWidth, y: sheet.cellHeight }
                : textureSizes?.get(f.texture ?? '');
            const size = animClipFrameSize(data, f, natural);
            if (drivesSize && !size) missingNatural++;
            const pivot = animClipFramePivot(data, f, size);
            if (sheet && f.cell !== undefined) {
                if (f.cell >= cellCount) {
                    log.warn('asset', `${clipPath}: frame cell ${f.cell} outside the ${cellCount}-cell sheet grid; clamped`);
                }
                const frame: SpriteAnimFrame = {
                    texture: textureHandles.get(sheet.texture) ?? 0,
                    duration: f.duration,
                    ...(pivot ? { pivot } : {}),
                    ...(size ? { size } : {}),
                    ...animClipCellUv(sheet, f.cell),
                };
                return frame;
            }
            const frame: SpriteAnimFrame = {
                texture: textureHandles.get(f.texture ?? '') ?? 0,
                duration: f.duration,
                ...(pivot ? { pivot } : {}),
                ...(size ? { size } : {}),
            };
            if (f.atlasFrame) {
                const af = f.atlasFrame;
                Object.assign(frame, uvFromRect(af, af.pageWidth, af.pageHeight));
            }
            return frame;
        }),
    };
    if (missingNatural > 0) {
        log.warn('asset', `${clipPath}: ${missingNatural} frame(s) own their size but no natural size was available; they draw at the entity's`);
    }
    return clip;
}