@drincs/pixi-vn/dist/canvas/tickers/index.d.ts

Pixi'VN is a npm package that provides various features for creating visual novels.

import { Ticker, UPDATE_PRIORITY } from 'pixi.js';
import { a as TickerArgs, T as Ticker$1, e as TickerIdType } from '../../TickersSequence-Cf1Vcu22.js';
export { b as TickerHistory, c as TickerInfo, d as TickersSequence } from '../../TickersSequence-Cf1Vcu22.js';
import { ObjectTarget, AnimationOptions, AnimationPlaybackControlsWithThen, ObjectSegment, At, SequenceOptions } from 'motion';

type TickerValue = Ticker;

/**
 * A class is used to create a ticker element to add into a Pixi Application.
 * You can use {@link canvas.addTicker()} to add this element into the application.
 * This class should be extended and the fn method should be overridden.
 * You must use the {@link tickerDecorator} to register the ticker in the game.
 * In Ren'Py is a transform.
 * @template TArgs The type of the arguments that you want to pass to the ticker.
 * @example
 * ```typescript
 * \@tickerDecorator() // this is equivalent to tickerDecorator("RotateTicker")
 * export class RotateTicker extends TickerBase<{ speed?: number }> {
 *     override fn(
 *         t: TickerValue, // the ticker that is calling this method
 *         args: { // the arguments that you passed when you added the ticker
 *             speed?: number,
 *         },
 *         aliases: string[], // the aliases of the canvas elements that are connected to this ticker
 *         tickerId: string, // the id of the ticker. You can use this to get the ticker from the canvas.currentTickers
 *     ): void {
 *         let speed = args.speed === undefined ? 0.1 : args.speed
 *         aliases.forEach((alias) => {
 *                 let element = canvas.find(alias)
 *                 if (element && element instanceof Container) {
 *                     if (clockwise)
 *                         element.rotation += speed * t.deltaTime
 *                     else
 *                         element.rotation -= speed * t.deltaTime
 *                 }
 *             })
 *     }
 * }
 * ```
 */
declare abstract class TickerBase<TArgs extends TickerArgs> implements Ticker$1<TArgs> {
    /**
     * @param args The arguments that you want to pass to the ticker.
     * @param duration The duration of the ticker in seconds. If is undefined, the step will end only when the animation is finished (if the animation doesn't have a goal to reach then it won't finish). @default undefined
     * @param priority The priority of the ticker. @default UPDATE_PRIORITY.NORMAL
     */
    constructor(args: TArgs, duration?: number, priority?: UPDATE_PRIORITY);
    /**
     * Get the id of the ticker. This variable is used in the system to get the ticker by id, {@link RegisteredTickers.getInstance}
     */
    id: TickerIdType;
    args: TArgs;
    duration?: number;
    priority?: UPDATE_PRIORITY;
    protected ticker: Ticker;
    protected tickerId?: string;
    canvasElementAliases: string[];
    /**
     * The method that will be called every frame.
     * This method should be overridden and you can use {@link canvas.add()} to get the canvas element of the canvas, and edit them.
     * @param _ticker The ticker that is calling this method
     * @param _args The arguments that you passed when you added the ticker
     * @param _alias The alias of the canvas elements that are connected to this ticker
     * @param _tickerId The id of the ticker. You can use this to get the ticker from the {@link canvas.currentTickers}
     */
    abstract fn(_ticker: TickerValue, _args: TArgs, _alias: string | string[], _tickerId: string): void;
    protected fnValue?: () => void;
    complete(_options?: {
        ignoreTickerSteps?: boolean;
    }): void;
    stop(): void;
    start(id: string): void;
    pause(): void;
    play(): void;
    get paused(): boolean;
}

type TickerProgrationType = TickerProgrationLinear | TickerProgrationExponential;

interface TickerProgrationLinear {
    /**
     * The amount of the speed to increase every frame.
     */
    amt: number;
    /**
     * The limit of the effect
     */
    limit?: number;
    type: "linear";
}
interface TickerProgrationExponential {
    /**
     * The percentage of the speed to increase every frame. if the percentage is 0.1, the speed will increase by 10% every frame.
     */
    percentage: number;
    /**
     * The limit of the effect
     */
    limit?: number;
    type: "exponential";
}

type CommonTickerProps = {
    /**
     * The alias to remove after the effect is done
     * @default []
     */
    aliasToRemoveAfter?: string[] | string;
    /**
     * If true, the effect only starts if the canvas element have a texture
     * @default false
     */
    startOnlyIfHaveTexture?: boolean;
    /**
     * The alias to resume after the effect is done
     * @default []
     */
    tickerAliasToResume?: string[] | string;
    /**
     * The id of the ticker to resume after the effect is done
     * @default []
     */
    tickerIdToResume?: string[] | string;
    /**
     * If set to `true`, the game will force the animation to complete before moving to the next step.
     * @default false
     */
    forceCompleteBeforeNext?: boolean;
};

/**
 * @deprecated
 */
type FadeAlphaTickerProps = {
    /**
     * @deprecated use speed instead
     * @default 1
     */
    duration?: number;
    /**
     * The speed of the effect (1 alpha per 10 second)
     * @default 5
     */
    speed?: number;
    /**
     * The type of the fade
     * @default "hide"
     */
    type?: "hide" | "show";
    /**
     * The limit of the fade
     * @default type === "hide" ? 0 : 1
     */
    limit?: number;
    /**
     * The progression of the speed
     */
    speedProgression?: TickerProgrationType;
} & CommonTickerProps;

/**
 * A ticker that fades the alpha of the canvas element of the canvas.
 * This ticker can be used on all canvas elements that extend the {@link PixiContainer} class.
 * @deprecated Use {@link canvas.animate}
 * @example
 * ```typescript
 * let bunny = addImage("bunny1", "https://pixijs.com/assets/eggHead.png")
 * await bunny.load()
 * canvas.add("bunny", bunny);
 * // ...
 * const ticker = new FadeAlphaTicker({
 *     duration: 4, // 4 seconds
 *     type: "hide",
 * }),
 * canvas.addTicker("bunny", ticker)
 * ```
 */
declare class FadeAlphaTicker extends TickerBase<FadeAlphaTickerProps> {
    constructor(args?: FadeAlphaTickerProps, duration?: number, priority?: UPDATE_PRIORITY);
    fn(ticker: TickerValue, args: FadeAlphaTickerProps, aliases: string[], _tickerId: string): void;
    onComplete(alias: string | string[], _tickerId: string, args: FadeAlphaTickerProps): void;
    private getLimit;
    private speedConvert;
    complete(options?: {
        ignoreTickerSteps?: boolean;
    }): void;
}

/**
 * @deprecated
 */
type MoveTickerProps = {
    /**
     * The speed of the movement (1 pixels per 0.1 second)
     * @default 10
     */
    speed?: number | {
        x: number;
        y: number;
    };
    /**
     * The destination of the movement
     */
    destination: {
        /**
         * The type of the destination. Possible values are "pixel", "percentage" and "align":
         * - "pixel": The destination is in pixel
         * - "percentage": The destination is in percentage
         * - "align": The destination is in align
         * @default "pixel"
         */
        type?: "pixel" | "percentage" | "align";
        y: number;
        x: number;
    };
    /**
     * The progression of the speed
     */
    speedProgression?: TickerProgrationType;
} & CommonTickerProps;

/**
 * A ticker that moves the canvas element of the canvas.
 * This ticker can be used on all canvas elements that extend the {@link PixiContainer} class.
 * @deprecated Use {@link canvas.animate}
 * @example
 * ```typescript
 * let alien = addImage("alien", 'https://pixijs.com/assets/eggHead.png')
 * canvas.add("alien", alien);
 * const ticker = new MoveTicker({
 *    speed: 0.1,
 *    destination: { x: 100, y: 100 },
 * }),
 * ```
 */
declare class MoveTicker extends TickerBase<MoveTickerProps> {
    fn(ticker: TickerValue, args: MoveTickerProps, aliases: string[], _tickerId: string): void;
    onComplete(alias: string | string[], _tickerId: string, args: MoveTickerProps): void;
    private speedConvert;
    complete(options?: {
        ignoreTickerSteps?: boolean;
    }): void;
}

/**
 * A ticker that rotates the canvas element of the canvas. For centre rotation, set the anchor of the canvas element to 0.5.
 * This ticker can be used on all canvas elements that extend the {@link PixiContainer} class.
 * @deprecated Use {@link canvas.animate}
 * @example
 * ```typescript
 * let alien = addImage("alien", 'https://pixijs.com/assets/eggHead.png')
 * alien.anchor.set(0.5);
 * canvas.add("alien", alien);
 * const ticker = new RotateTicker({
 *    speed: 0.1,
 *    clockwise: true,
 * }),
 * canvas.addTicker("alien", ticker)
 * ```
 */
declare class RotateTicker extends TickerBase<RotateTickerProps> {
    constructor(args?: RotateTickerProps, duration?: number, priority?: UPDATE_PRIORITY);
    fn(ticker: TickerValue, args: RotateTickerProps, aliases: string[], _tickerId: string): void;
    onComplete(alias: string | string[], _tickerId: string, args: RotateTickerProps): void;
    private speedConvert;
    complete(options?: {
        ignoreTickerSteps?: boolean;
    }): void;
}

/**
 * A ticker that zooms the canvas element of the canvas.
 * This ticker can be used on all canvas elements that extend the {@link PixiContainer} class.
 * @deprecated Use {@link canvas.animate}
 * @example
 * ```typescript
 * let alien = addImage("alien", 'https://pixijs.com/assets/eggHead.png')
 * alien.anchor.set(0.5);
 * canvas.add("alien", alien);
 * const ticker = new ZoomTicker({
 *    speed: 0.1,
 * }),
 * canvas.addTicker("alien", ticker)
 * ```
 */
declare class ZoomTicker extends TickerBase<ZoomTickerProps> {
    constructor(args?: ZoomTickerProps, duration?: number, priority?: UPDATE_PRIORITY);
    fn(ticker: TickerValue, args: ZoomTickerProps, alias: string[], _tickerId: string): void;
    private speedConvert;
    onComplete(alias: string | string[], _tickerId: string, args: ZoomTickerProps): void;
    private getLimit;
    complete(options?: {
        ignoreTickerSteps?: boolean;
    }): void;
}

/**
 * Is a decorator that register a ticker in the game.
 * Is a required decorator for use the ticker in the game.
 * Thanks to this decoration the game has the possibility of updating the tickers to the latest modification and saving the game.
 * @param name is th identifier of the label, by default is the name of the class
 * @returns
 */
declare function tickerDecorator(name?: TickerIdType): (target: {
    new (args: any, duration?: number, priority?: UPDATE_PRIORITY): Ticker$1<any>;
}) => void;
declare namespace RegisteredTickers {
    /**
     * Register a ticker in the game.
     * @param target The class of the ticker.
     * @param name Name of the ticker, by default it will use the class name. If the name is already registered, it will show a warning
     */
    function add(target: {
        new (args: any, duration?: number, priority?: UPDATE_PRIORITY): Ticker$1<any>;
    }, name?: TickerIdType): void;
    /**
     * Get a ticker by the id.
     * @param canvasId The id of the ticker.
     * @returns The ticker type.
     */
    function get<T = Ticker$1<any>>(tickerId: TickerIdType): T | undefined;
    /**
     * Get a ticker instance by the id.
     * @param tickerId The id of the ticker.
     * @param args The arguments that you want to pass to the ticker.
     * @param duration The duration of the ticker. If is undefined, the ticker will be called every frame.
     * @param priority The priority of the ticker. If is undefined, the priority will be UPDATE_PRIORITY.NORMAL.
     * @returns The instance of the ticker
     */
    function getInstance<TArgs extends TickerArgs>(tickerId: TickerIdType, args: TArgs, duration?: number, priority?: UPDATE_PRIORITY): Ticker$1<TArgs> | undefined;
    /**
     * Get a list of all tickers registered.
     * @returns An array of tickers.
     */
    function values(): {
        new (args: any, duration?: number, priority?: UPDATE_PRIORITY): Ticker$1<any>;
    }[];
    /**
     * Check if a ticker is registered.
     * @param id The id of the ticker.
     * @returns True if the ticker is registered, false otherwise.
     */
    function has(id: string): boolean;
}

type ObjectSegmentWithTransition<O extends {} = {}> = [
    O,
    ObjectTarget<O>,
    AnimationOptions & At & {
        ticker?: Ticker;
    }
];
/**
 * Animate a PixiJS component or components using [motion's animate](https://motion.dev/docs/animate) function.
 * This function integrates with the PixiJS ticker to ensure smooth animations.
 *
 * Pixi’VN will **not** keep track of the animation state of this function (This feature is intended for animating PixiJS components used for UI.).
 * If you want Pixi'VN to save the animation state in saves, use the {@link canvas.animate} function instead.
 * @param components - The PixiJS component(s) to animate.
 * @param keyframes - The keyframes to animate the component(s) with.
 * @param options - Additional options for the animation, including duration, easing, and ticker.
 * @returns An animation playback control object that can be used to start, stop, or control the animation.
 * @template T - The type of PixiJS component(s) being animated.
 */
declare function animate<T extends {}>(components: T | T[], keyframes: ObjectTarget<T>, options?: AnimationOptions & {
    ticker?: Ticker;
}): AnimationPlaybackControlsWithThen;
/**
 * Animate a sequence of PixiJS components with transitions using [motion's animate](https://motion.dev/docs/animate) function.
 * This function allows for complex animations involving multiple components and transitions.
 * It integrates with the PixiJS ticker to ensure smooth animations.
 * This function is intended for animating PixiJS components used for UI.
 *
 * Pixi’VN will **not** keep track of the animation state of this function (This feature is intended for animating PixiJS components used for UI.).
 * If you want Pixi'VN to save the animation state in saves, use the {@link canvas.animate} function instead
 *
 * @param sequence An array of segments to animate, where each segment is an array containing:
 * - The PixiJS component to animate.
 * - The keyframes to animate the component with.
 * - An options object that can include animation options and a ticker.
 * @param options Additional options for the sequence, such as duration and repeat count.
 * @returns An animation playback control object that can be used to start, stop, or control the animation.
 * @template T - The type of PixiJS component(s) being animated.
 */
declare function animate<T extends {}>(sequence: (ObjectSegment<T> | ObjectSegmentWithTransition<T>)[], options?: SequenceOptions): AnimationPlaybackControlsWithThen;

interface TickerTimeoutHistory {
    aliases: string[];
    ticker: string;
    canBeDeletedBeforeEnd: boolean;
}

/**
 * @deprecated
 */
type RotateTickerProps = {
    /**
     * The speed of the rotation (360 degree per 10 second)
     * @default 1
     */
    speed?: number;
    /**
     * The direction of the rotation
     * @default true
     */
    clockwise?: boolean;
    /**
     * The limit of the rotation, is specified in degree
     * @default undefined
     */
    limit?: number;
    /**
     * The progression of the speed
     */
    speedProgression?: TickerProgrationType;
} & CommonTickerProps;

/**
 * @deprecated
 */
type ZoomTickerProps = {
    /**
     * The speed of the zoom effect (100% zoom per 10 second)
     * @default 10
     */
    speed?: number | {
        x: number;
        y: number;
    };
    /**
     * The type of the zoom effect
     * @default "zoom"
     */
    type?: "zoom" | "unzoom";
    /**
     * The limit of the effect
     * @default type === "zoom" ? Infinity : 0
     */
    limit?: number | {
        x: number;
        y: number;
    };
    /**
     * The progression of the speed.
     * There are two types of progression: linear and exponential.
     * - Linear: The speed will increase by the amount of `amt` every frame.
     * - Exponential: The speed will increase by the percentage of the current speed every frame.
     * @default undefined
     */
    speedProgression?: TickerProgrationType;
    /**
     * Is a special prop used in the zoom in/out transition.
     * @default false
     */
    isZoomInOut?: {
        pivot: {
            x: number;
            y: number;
        };
        position: {
            x: number;
            y: number;
        };
    };
} & CommonTickerProps;

export { type CommonTickerProps, FadeAlphaTicker, type FadeAlphaTickerProps, MoveTicker, type MoveTickerProps, RegisteredTickers, RotateTicker, type RotateTickerProps, Ticker$1 as Ticker, TickerArgs, TickerBase, type TickerProgrationExponential, type TickerProgrationLinear, type TickerProgrationType, type TickerTimeoutHistory, type TickerValue, ZoomTicker, type ZoomTickerProps, animate, tickerDecorator };