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.

8.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import {
    wrapModeFromName,
    TrackType,
    TIMELINE_FORMAT_VERSION,
    type TimelineAsset,
    type Track,
    type PropertyTrack,
    type SpineTrack,
    type SpriteAnimTrack,
    type AudioTrack,
    type ParticleTrack,
    type ActivationTrack,
    type MarkerTrack,
    type CustomEventTrack,
    type AnimFramesTrack,
    type CameraTrack,
    type SequenceTrack,
} from './TimelineTypes';
import { log } from '../util/logger';

const STEP_TANGENT_THRESHOLD = 1e5;

type MigrationFn = (raw: any) => void;

const MIGRATIONS: [string, string, MigrationFn][] = [
    ['1.0', '1.1', (raw: any) => {
        for (const track of raw.tracks ?? []) {
            if (track.type === TrackType.Property) {
                for (const ch of track.channels ?? []) {
                    for (const kf of ch.keyframes ?? []) {
                        if (kf.interpolation) continue;
                        if (Math.abs(kf.outTangent) >= STEP_TANGENT_THRESHOLD) {
                            kf.interpolation = 'step';
                            kf.outTangent = 0;
                        }
                    }
                }
            }
        }
    }],
    // `rotation.z` named the Z EULER angle, not the quaternion's z component —
    // the name a 3D rotation channel needs. The angle keeps its meaning under
    // the name that says so, and a document written before this reads the same.
    ['1.1', '1.2', (raw: any) => {
        for (const track of raw.tracks ?? []) {
            if (track.type !== TrackType.Property) continue;
            for (const ch of track.channels ?? []) {
                if (ch.property === 'rotation.z') ch.property = 'rotation.angle';
            }
        }
    }],
    // Camera and sequence tracks arrived without changing what an older document means.
    ['1.2', '1.3', () => undefined],
];

function migrateAsset(raw: any): void {
    let version = raw.version ?? '1.0';

    for (const [from, to, fn] of MIGRATIONS) {
        if (version === from) {
            fn(raw);
            version = to;
        }
    }

    raw.version = TIMELINE_FORMAT_VERSION;
}

const finite = (v: unknown, fallback: number): number => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);

function parseTrack(raw: any): Track {
    const base = {
        name: raw.name ?? '',
        childPath: raw.childPath ?? '',
    };

    switch (raw.type) {
        case TrackType.Property:
            return {
                ...base,
                type: TrackType.Property,
                component: raw.component ?? '',
                channels: (raw.channels ?? []).map((ch: any) => ({
                    property: ch.property,
                    // Default missing tangents to 0: a hand-authored keyframe without
                    // them hits the Hermite evaluator path where `undefined * dt` is
                    // NaN, poisoning the animated field.
                    keyframes: (ch.keyframes ?? []).map((kf: any) => ({
                        ...kf,
                        inTangent: kf.inTangent ?? 0,
                        outTangent: kf.outTangent ?? 0,
                    })),
                })),
            } as PropertyTrack;

        case TrackType.Spine:
            return {
                ...base,
                type: TrackType.Spine,
                clips: raw.clips ?? [],
                blendIn: raw.blendIn ?? 0,
            } as SpineTrack;

        case TrackType.SpriteAnim:
            return {
                ...base,
                type: TrackType.SpriteAnim,
                clip: raw.clip ?? '',
                startTime: raw.startTime ?? 0,
            } as SpriteAnimTrack;

        case TrackType.Audio:
            return {
                ...base,
                type: TrackType.Audio,
                events: raw.events ?? [],
            } as AudioTrack;

        case TrackType.Activation:
            return {
                ...base,
                type: TrackType.Activation,
                ranges: raw.ranges ?? [],
            } as ActivationTrack;

        case TrackType.Marker:
            return {
                ...base,
                type: TrackType.Marker,
                markers: raw.markers ?? [],
            } as MarkerTrack;

        case TrackType.Particle:
            return { ...base, type: TrackType.Particle, events: (raw.events ?? []).filter((e: any) =>
                Number.isFinite(e.time) && e.time >= 0 && ['play', 'stop', 'reset'].includes(e.action))
                .map((e: any) => ({ time: e.time, action: e.action })) } as ParticleTrack;

        case TrackType.CustomEvent:
            return {
                ...base,
                type: TrackType.CustomEvent,
                events: (raw.events ?? []).map((e: any) => ({
                    time: e.time ?? 0,
                    name: e.name ?? '',
                    payload: e.payload ?? {},
                })),
            } as CustomEventTrack;

        case TrackType.AnimFrames:
            return {
                ...base,
                type: TrackType.AnimFrames,
                frames: (raw.animFrames ?? []).map((f: any) => ({
                    texture: f.texture ?? '',
                    duration: f.duration,
                })),
            } as AnimFramesTrack;

        case TrackType.Camera:
            return {
                ...base,
                childPath: '',
                type: TrackType.Camera,
                clips: (raw.clips ?? []).map((c: any) => ({
                    start: finite(c.start, 0),
                    duration: Math.max(0, finite(c.duration, 0)),
                    camera: typeof c.camera === 'string' ? c.camera : '',
                    ...(typeof c.curve === 'number' ? { curve: c.curve } : {}),
                })),
            } as CameraTrack;

        case TrackType.Sequence:
            return {
                ...base,
                childPath: '',
                type: TrackType.Sequence,
                clips: (raw.clips ?? []).map((c: any) => ({
                    start: finite(c.start, 0),
                    duration: Math.max(0, finite(c.duration, 0)),
                    timeline: typeof c.timeline === 'string' ? c.timeline : '',
                    root: typeof c.root === 'string' ? c.root : '',
                    speed: finite(c.speed, 1) || 1,
                    loop: c.loop === true,
                })),
            } as SequenceTrack;

        default:
            log.warn('timeline', `Unknown track type: ${raw.type}, skipping`);
            return null as any;
    }
}

export function parseTimelineAsset(rawJson: unknown): TimelineAsset {
    const raw = (rawJson ?? {}) as Record<string, any>;
    migrateAsset(raw);

    return {
        version: TIMELINE_FORMAT_VERSION,
        type: 'timeline',
        duration: raw.duration ?? 0,
        wrapMode: wrapModeFromName(raw.wrapMode),
        tracks: (raw.tracks ?? []).map(parseTrack).filter((t: Track | null) => t !== null),
    };
}

export interface TimelineAssetPaths {
    audio: string[];
    animClips: string[];
    textures: string[];
    /** The timelines its sequence clips play. */
    timelines: string[];
}

export function extractTimelineAssetPaths(asset: TimelineAsset): TimelineAssetPaths {
    const audio = new Set<string>();
    const animClips = new Set<string>();
    const textures = new Set<string>();
    const timelines = new Set<string>();

    for (const track of asset.tracks) {
        if (track.type === TrackType.Audio) {
            for (const event of track.events) {
                audio.add(event.clip);
            }
        } else if (track.type === TrackType.SpriteAnim) {
            if (track.clip) {
                animClips.add(track.clip);
            }
        } else if (track.type === TrackType.Sequence) {
            for (const clip of track.clips) if (clip.timeline) timelines.add(clip.timeline);
        } else if (track.type === TrackType.AnimFrames) {
            for (const frame of track.frames) {
                if (frame.texture) {
                    textures.add(frame.texture);
                }
            }
        }
    }

    return {
        audio: Array.from(audio),
        animClips: Array.from(animClips),
        textures: Array.from(textures),
        timelines: Array.from(timelines),
    };
}