threepipe/lib/utils/AnimationObject.d.ts

A modern 3D viewer framework built on top of three.js, written in TypeScript, designed to make creating high-quality, modular, and extensible 3D experiences on the web simple and enjoyable.

import { ValOrFunc } from 'ts-browser-helpers';
import { IUiConfigContainer, UiObjectConfig, UiObjectType } from 'uiconfig.js';
import { AnimationOptions, Easing } from '@repalash/popmotion';
import { EasingFunctionType } from './animation';
import { ThreeViewer } from '../viewer';
import { AnimationResult } from '../plugins';
import { EventDispatcher } from 'three';
export type TUpdaterType = (() => void);
export interface IAnimationObject<V> {
    access?: string;
    duration?: number;
    delay?: number;
    ease?: Easing | EasingFunctionType;
    updater?: (TUpdaterType)[];
    animSet?: IAnimSet;
    animSetParallel?: boolean;
    name?: string;
    options: AnimationOptions<V>;
    values: V[];
    offsets?: number[];
    animate?: (delay?: number, canComplete?: boolean) => AnimationResult;
    result?: AnimationResult;
    uiRef?: UiObjectConfig;
    uiObjectType?: UiObjectType;
    targetObject?: Record<string, any>;
}
export type IAnimSet = (IAnimationObject<any>)[];
export declare function extractAnimationKey(o: IAnimationObject<any>, extraGetters?: Record<string, (key: string, acc: string[]) => {
    tar: any;
    acc: string[];
    onChange?: () => void;
} | undefined>): {
    key: undefined;
    tar: any;
    onChange?: undefined;
} | {
    key: string;
    tar: any;
    onChange: (() => void) | undefined;
};
export interface AnimationObjectEventMap {
    'animationAdd': {
        animation: AnimationObject;
    };
    'animationRemove': {
        animation: AnimationObject;
        fromChild: boolean;
    };
    'update': object;
}
/**
 * AnimationObject - An object for containing keyframe-based animation for properties
 *
 * AnimationObject extends popmotion and interfaces with the {@link ThreeViewer} to provide a keyframe animation system that can animate any accessible property
 * on objects, materials, or the viewer itself. It supports complex timing, easing, and serialization.
 *
 * It is used in {@link AnimationObjectPlugin}.
 *
 * Key Features:
 * - **Property Access**: Uses dot-notation strings to access nested properties (e.g., 'position.x', 'material.roughness')
 * - **Keyframe System**: Define multiple keyframes with custom timing and values
 * - **Easing Support**: Built-in easing functions or custom easing functions
 * - **Timeline Integration**: Seamlessly works with viewer's global timeline
 * - **Serialization**: Automatically saves/loads with scene data
 * - **UI Integration**: Generates UI controls and supports interactive editing
 * - **Hierarchical**: Can contain child animations for complex choreography
 *
 * @example Basic Animation
 * ```typescript
 * const anim = new AnimationObject(myObject)
 * anim.access = 'position.y'
 * anim.values = [0, 5, 0]
 * anim.offsets = [0, 0.5, 1]
 * anim.duration = 2000
 * anim.ease = (x: number) => 1 - Math.cos(x * Math.PI / 2) // Custom easeOutSine
 * anim.updateTarget = true
 * ```
 *
 * @example Complex Animation with Multiple Keyframes
 * ```typescript
 * const colorAnim = new AnimationObject(material)
 * colorAnim.access = 'color'
 * colorAnim.values = ['#ff0000', '#00ff00', '#0000ff', '#ff0000']
 * colorAnim.offsets = [0, 0.33, 0.66, 1]
 * colorAnim.duration = 4000
 * anim.ease = 'easeInOutSine'
 * colorAnim.delay = 500
 * ```
 *
 */
export declare class AnimationObject<V = any> extends EventDispatcher<AnimationObjectEventMap> implements IAnimationObject<V>, IUiConfigContainer {
    uuid: string;
    setDirty: () => void;
    name: string;
    access: string;
    values: V[];
    offsets: number[];
    options: AnimationOptions<V>;
    duration: number;
    delay: number;
    /**
     * Number of times to repeat the animation.
     * Doesn't work right now
     */
    repeat: number;
    /**
     * Delay between repeats in milliseconds.
     * Doesn't work right now
     */
    repeatDelay: number;
    /**
     * Type of repeat behavior.
     * - 'loop': repeats the animation from the beginning.
     * - 'reverse': plays the animation in reverse after it completes.
     * - 'mirror': plays the animation in reverse after it completes. todo only mirrors the time, not values?
     *
     * Doesn't work right now
     */
    repeatType: 'loop' | 'reverse' | 'mirror';
    ease: EasingFunctionType;
    updater: TUpdaterType[];
    uiObjectType?: UiObjectType;
    get targetObject(): Record<string, any> | undefined;
    updateScene: boolean;
    updateCamera: boolean;
    updateViewer: boolean;
    updateTarget: boolean;
    target?: Record<string, any>;
    readonly viewer?: ValOrFunc<ThreeViewer | undefined>;
    getViewer(): ThreeViewer | undefined;
    constructor(target?: object | undefined, viewer?: ValOrFunc<ThreeViewer | undefined>, name?: string);
    fromJSON(data1: any, meta?: any): this;
    private _lastAccess;
    private _lastTarget;
    protected _onAccessChanged(): void;
    private _thisValueCloner;
    addKeyframe(time: number): {
        undo: () => void;
        redo: () => void;
    } | undefined;
    updateKeyframe(index: number): {
        undo: () => void;
        redo: () => void;
    } | undefined;
    isValueSame(index: number): any;
    refreshUi(): void;
    parent?: AnimationObject;
    add(o: AnimationObject): void;
    remove(o: AnimationObject, fromChild?: boolean): void;
    private _upfn;
    animate(delay?: number, canComplete?: boolean): AnimationResult;
    result: AnimationResult | undefined;
    stop(): void;
    removeFromParent2(): Promise<void>;
    removeFromParent(): void;
    animSetParallel: boolean;
    animSet: AnimationObject[];
    addAnimation(): AnimationObject<any>;
    uiConfig: UiObjectConfig;
}
//# sourceMappingURL=../src/utils/AnimationObject.d.ts.map