@drincs/pixi-vn 1.9.2 → 1.9.4

package/dist/tickers.d.cts

@@ -0,0 +1,555 @@
+import * as _drincs_pixi_vn_pixi_js from '@drincs/pixi-vn/pixi.js';
+import { UPDATE_PRIORITY, Ticker as Ticker$1 } from '@drincs/pixi-vn/pixi.js';
+
+interface TickerArgs {
+}
+
+interface Ticker<TArgs extends TickerArgs> {
+    /**
+     * Arguments to pass to the ticker
+     */
+    args: TArgs;
+    /**
+     * Duration in seconds to run the ticker
+     */
+    duration?: number;
+    /**
+     * Priority of the ticker
+     */
+    priority?: UPDATE_PRIORITY;
+    /**
+     * Get the alias of the ticker class. This variable is used in the system to get the ticker class by id, {@link RegisteredTickers.getInstance}
+     */
+    readonly alias: string;
+    /**
+     * The id of the ticker. Must be unique for each ticker instance.
+     */
+    readonly id: string;
+    /**
+     * The aliases of the canvas elements that are connected to this ticker
+     */
+    canvasElementAliases: string[];
+    /**
+     * Completes the animation and applies the final state.
+     */
+    complete: (options?: {
+        ignoreTickerSteps?: boolean;
+    }) => Promise<void> | void;
+    /**
+     * Stops the animation at its current state, and prevents it from resuming when the animation is played again.
+     */
+    stop: () => void;
+    /**
+     * Starts the ticker. This will start the ticker and begin the animation.
+     */
+    start: () => void;
+    /**
+     * Pauses the animation.
+     */
+    pause: () => void;
+    /**
+     * Plays the animation.
+     */
+    play: () => void;
+    /**
+     * Checks if the ticker is paused.
+     * @returns true if the ticker is paused, false otherwise.
+     */
+    readonly paused: boolean;
+}
+
+type TickerValue = Ticker$1;
+
+/**
+ * A class is used to create a ticker element to add into a Pixi Application.
+ * You can use `tickers.add()` (from `@drincs/pixi-vn`) 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
+ * ```ts
+ * \@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 tickers.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<TArgs> {
+    /**
+     * @param args The arguments that you want to pass to the ticker.
+     * @param options The options of the ticker.
+     */
+    constructor(args: TArgs, options?: {
+        /**
+         * 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
+         */
+        duration?: number;
+        /**
+         * The priority of the ticker. @default UPDATE_PRIORITY.NORMAL
+         */
+        priority?: UPDATE_PRIORITY;
+        /**
+         * The id of the ticker. This param is used by the system when will ber restoring the tickers from a save. If not provided, a random id will be generated. @default undefined
+         */
+        id?: string;
+        /**
+         * The aliases of the canvas elements that are connected to this ticker. This is used by the system to know which canvas elements are connected to this ticker, and to pass them to the fn method. @default []
+         */
+        canvasElementAliases?: string[];
+    });
+    readonly alias: string;
+    readonly id: string;
+    args: TArgs;
+    duration?: number;
+    priority?: UPDATE_PRIORITY;
+    protected ticker: _drincs_pixi_vn_pixi_js.Ticker;
+    canvasElementAliases: string[];
+    private generateTickerId;
+    /**
+     * The method that will be called every frame.
+     * This method should be overridden and you can use `canvas.find()` (from `@drincs/pixi-vn/canvas`)
+     * 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 `tickers.currentTickers`
+     */
+    abstract fn(_ticker: TickerValue, _args: TArgs, _alias: string | string[], _tickerId: string): void;
+    protected fnValue?: () => void;
+    complete(_options?: {
+        ignoreTickerSteps?: boolean;
+    }): void;
+    stop(): void;
+    start(): void;
+    pause(): void;
+    play(): void;
+    get paused(): boolean;
+}
+
+/**
+ * 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?: string): (target: {
+    new (args: any, options?: {
+        duration?: number;
+        priority?: UPDATE_PRIORITY;
+        id?: string;
+        canvasElementAliases?: string[];
+    }): Ticker<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, options?: {
+            duration?: number;
+            priority?: UPDATE_PRIORITY;
+            id?: string;
+            canvasElementAliases?: string[];
+        }): Ticker<any>;
+    }, name?: string): void;
+    /**
+     * Get a ticker by the id.
+     * @param canvasId The id of the ticker.
+     * @returns The ticker type.
+     */
+    function get<T = Ticker<any>>(tickerId: string): 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: string, args: TArgs, options?: {
+        duration?: number;
+        priority?: UPDATE_PRIORITY;
+        id?: string;
+        canvasElementAliases?: string[];
+    }): Ticker<TArgs> | undefined;
+    /**
+     * Get a list of all tickers registered.
+     * @returns An array of tickers.
+     */
+    function values(): {
+        new (args: any, options?: {
+            duration?: number;
+            priority?: UPDATE_PRIORITY;
+            id?: string;
+            canvasElementAliases?: string[];
+        }): Ticker<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;
+    /**
+     * Get a list of all ticker ids registered.
+     * @returns An array of label ids.
+     */
+    function keys(): string[];
+}
+
+/**
+ * TickerHistory is a class that contains the name of a class and the arguments that were used to create it.
+ */
+interface TickerInfo<TArgs extends TickerArgs> {
+    /**
+     * If this ticker was created by steps
+     */
+    createdByTicketSteps?: {
+        canvasElementAlias: string;
+        id: string;
+    };
+    ticker: Ticker<TArgs>;
+}
+interface TickerHistory<TArgs extends TickerArgs> {
+    id: string;
+    args: TArgs;
+    /**
+     * The aliases of the canvas elements that are connected to this ticker
+     */
+    canvasElementAliases: string[];
+    priority?: UPDATE_PRIORITY;
+    duration?: number;
+    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";
+}
+
+interface TickersStep<TArgs extends TickerArgs> {
+    /**
+     * Ticker class name
+     */
+    ticker: string;
+    /**
+     * Duration in seconds. If is undefined, the step will end only when the animation is finished.
+     */
+    duration?: number;
+    /**
+     * Arguments to pass to the ticker
+     */
+    args: TArgs;
+    /**
+     * Priority of the ticker
+     */
+    priority?: UPDATE_PRIORITY;
+}
+/**
+ * The steps of the tickers
+ */
+interface TickersSequence {
+    /**
+     * The step number
+     */
+    currentStepNumber: number;
+    /**
+     * The steps of the tickers
+     */
+    steps: TickersStep<any>[];
+}
+
+interface TickersInterface {
+    /**
+     * Transfer the tickers from an old alias to a new alias.
+     * @param oldAlias Old alias
+     * @param newAlias New alias
+     * @param mode If "move", the old alias will be removed from the ticker. If "duplicate", the old alias will be kept in the ticker.
+     */
+    transfer(oldAlias: string, newAlias: string, mode?: "move" | "duplicate"): void;
+    /**
+     * Currently tickers that are running.
+     */
+    readonly currentTickers: Map<string, TickerInfo<any>>;
+    /**
+     * The steps of the tickers
+     */
+    readonly currentTickersSteps: Map<string, Map<string, TickersSequence>>;
+    /**
+     * Find a ticker by its id.
+     * @param tickerId The id of the ticker to be found.
+     * @param args The args of the ticker.
+     * @returns The ticker if found, undefined otherwise.
+     */
+    find<TArgs extends TickerArgs>(tickerId: string, args?: TArgs): Ticker<TArgs> | undefined;
+    /**
+     * Run a ticker. You can run multiple add with the same alias and different tickerClasses.
+     * If you run a ticker with the same alias and tickerClass, the old ticker will be removed.
+     * If already exists a sequence of tickers with the same alias, it will be removed.
+     * @param canvasElementAlias The alias of the canvas element that will use the ticker.
+     * @param ticker The ticker class to be run.
+     * @returns The id of the ticker that was added.
+     * @example
+     * ```ts
+     * tickers.add("alien", new RotateTicker({ speed: 0.2 }))
+     * ```
+     */
+    add<TArgs extends TickerArgs>(canvasElementAlias: string | string[], ticker: Ticker<TArgs>): string | undefined;
+    /**
+     * Run a sequence of tickers.
+     * @param alias The alias of canvas element that will use the tickers.
+     * @param steps The steps of the tickers.
+     * @param currentStepNumber The current step number. It is used to continue the sequence of tickers.
+     * @returns The id of tickers.
+     * @example
+     * ```ts
+     * tickers.addSequence("alien", [
+     *     new RotateTicker({ speed: 0.1, clockwise: true }, 2), // runs for 2 seconds
+     *     new RotateTicker({ speed: 0.2, clockwise: false }, 2),
+     * ])
+     * ```
+     * @deprecated
+     */
+    addSequence(alias: string, steps: Ticker<any>[], currentStepNumber?: number): string | undefined;
+    /**
+     * Remove a connection between a canvas element and a ticker.
+     * And remove the ticker if there is no canvas element connected to it.
+     * @param alias The alias of the canvas element that will use the ticker.
+     * @param ticker The ticker class to be removed.
+     * @example
+     * ```ts
+     * tickers.unlinkComponent("alien", RotateTicker)
+     * ```
+     */
+    unlinkComponent(alias: string | string[], ticker?: {
+        new (): Ticker<any>;
+    } | string): void;
+    /**
+     * Remove all tickers from the canvas.
+     */
+    removeAll(): void;
+    /**
+     * Remove a ticker by the id.
+     * @param tickerId The id or an array of ids of the ticker to be removed.
+     */
+    remove(tickerId: string | string[]): void;
+    /**
+     * Pause a ticker. If a paused ticker have a time to be removed, it will be removed after the time.
+     * @param filters The filters to pause the ticker.
+     * @returns The ids of the paused tickers.
+     */
+    pause(filters: {
+        /**
+         * The alias of the canvas element that will use the ticker.
+         * Will pause all tickers that are connected to this canvas element.
+         */
+        canvasAlias: string;
+        /**
+         * Ticker ids excluded from the pause. If not provided, all tickers will be paused.
+         */
+        tickerIdsExcluded?: string[];
+    } | {
+        /**
+         * The id of the ticker to be paused. If provided, only this ticker will be paused.
+         */
+        id: string | string[];
+    }): string[];
+    /**
+     * Resume a ticker.
+     * @param filters The filters to resume the ticker.
+     */
+    resume(filters: {
+        /**
+         * The alias of the canvas element that will use the ticker.
+         * Will resume all tickers that are connected to this canvas element.
+         */
+        canvasAlias: string;
+    } | {
+        /**
+         * The id of the ticker to be resumed. If provided, only this ticker will be resumed.
+         */
+        id: string | string[];
+    }): void;
+    /**
+     * Check if a ticker is paused.
+     * @param alias The alias of the canvas element that will use the ticker.
+     * @param tickerId The ticker that will be checked.
+     * @returns If the ticker is paused.
+     */
+    isPaused(alias: string, tickerId?: string): boolean;
+    /**
+     * Add a ticker that must be completed before the next step.
+     * This method is used for example into a transition between scenes.
+     * @param step The step that the ticker must be completed before the next step.
+     */
+    completeOnStepEnd(step: {
+        /**
+         * The id of the step.
+         */
+        id: string;
+        /**
+         * If is a sequence of tickers, the alias of the sequence of tickers.
+         */
+        alias?: string;
+    }): void;
+    /**
+     * This method force the completion of the tickers that are running.
+     * This funcions is called in the next step.
+     * @param id The id of the ticker. If the alias provided, the id is the id of the sequence of tickers.
+     * @param alias The alias of the sequence of tickers.
+     */
+    forceCompletion(id: string, alias?: string): Promise<void>;
+    onComplete(tickerId: string, options: {
+        aliasToRemoveAfter: string[];
+        tickerAliasToResume: string[];
+        tickerIdToResume: string[];
+        ignoreTickerSteps?: boolean;
+        stopTicker?: boolean;
+    }): void;
+}
+
+interface TickerTimeoutHistory {
+    aliases: string[];
+    ticker: string;
+    canBeDeletedBeforeEnd: boolean;
+}
+
+type CommonTickerProps = {
+    /**
+     * An array of strings containing the aliases of the canvas components to remove after the animation completes.
+     * @default []
+     */
+    aliasToRemoveAfter?: string[] | string;
+    /**
+     * If true, the effect only starts if the canvas element have a texture
+     * @default false
+     */
+    startOnlyIfHaveTexture?: boolean;
+    /**
+     * If you want to resume tickers that were previously paused, provide the aliases of the canvas components whose tickers should be resumed.
+     * @default []
+     */
+    tickerAliasToResume?: string[] | string;
+    /**
+     * A string containing the ticker ID to resume after the animation completes.
+     * @default []
+     */
+    tickerIdToResume?: string[] | string;
+    /**
+     * A boolean indicating whether the animation must complete before the next `step` of the game. If `true`, the game will force the animation to finish before proceeding.
+     * When true, calling `narration.continue()` forces the current content to complete before advancing to the next narrative step.
+     * @default false
+     */
+    completeOnContinue?: boolean;
+};
+
+/**
+ * Static, module-scoped ticker bookkeeping - moved out of `CanvasManagerStatic` (formerly
+ * `CanvasManagerStatic`'s "Edit Tickers Methods" section) so the `tickers` module can own its own
+ * state without importing `@drincs/pixi-vn/canvas`.
+ */
+declare namespace TickersManagerStatic {
+    function currentTickersWithoutCreatedBySteps(): {
+        [k: string]: TickerHistory<any>;
+    };
+    const _currentTickers: Map<string, TickerInfo<any>>;
+    const _currentTickersSequence: Map<string, Map<string, TickersSequence>>;
+    function currentTickersSequence(): {
+        [alias: string]: {
+            [tickerId: string]: TickersSequence;
+        };
+    };
+    const _currentTickersTimeouts: Map<string, TickerTimeoutHistory>;
+    const _tickersToCompleteOnStepEnd: {
+        tikersIds: {
+            id: string;
+        }[];
+        stepAlias: {
+            id: string;
+            alias: string;
+        }[];
+    };
+    function generateTickerId(...args: any[]): string;
+    function addTickerTimeoutInfo(aliases: string | string[], ticker: string, timeout: string, canBeDeletedBeforeEnd: boolean): void;
+    function removeTickerTimeoutInfo(timeout: NodeJS.Timeout | string): void;
+    function removeTickerTimeout(timeout: NodeJS.Timeout | string): void;
+    function removeTickerTimeoutsByAlias(alias: string, checkCanBeDeletedBeforeEnd: boolean): void;
+}
+
+/**
+ * Runs (or resumes) a single step of a ticker sequence. Exported (beyond the {@link tickers} public
+ * surface) because `CanvasManager.restore()` reconstructs sequences from serialized save data at a
+ * lower level than {@link addSequence} operates at.
+ */
+declare function runTickersSequence<TArgs extends TickerArgs>(alias: string, key: string): void;
+/**
+ * Removes one or more tickers by id, with an extra `stopTicker` option beyond what
+ * {@link tickers}.remove exposes - kept as its own named export for `CanvasManager`'s deprecated
+ * `removeTicker(tickerId, options)` flat method, which historically supported it.
+ */
+declare function removeTicker(tickerId: string | string[], options?: {
+    stopTicker?: boolean;
+}): void;
+/**
+ * Drains the `completeOnStepEnd` queue, returning what was in it. Used by `canvas/index.ts`'s
+ * pre-continue handler, which used to reach into `CanvasManagerStatic._tickersToCompleteOnStepEnd`
+ * directly - draining through this function keeps that state fully encapsulated in this module.
+ */
+declare function drainCompleteOnStepEndQueue(): {
+    tikersIds: {
+        id: string;
+    }[];
+    stepAlias: {
+        id: string;
+        alias: string;
+    }[];
+};
+/**
+ * Namespace for operations on tickers - the frame-by-frame animation primitive every Pixi'VN
+ * animation (`canvas.animate`, transitions, custom `TickerBase` subclasses) is built on.
+ */
+declare const tickers: TickersInterface;
+
+export { type CommonTickerProps, RegisteredTickers, type Ticker, type TickerArgs, TickerBase, type TickerHistory, type TickerInfo, type TickerProgrationExponential, type TickerProgrationLinear, type TickerProgrationType, type TickerTimeoutHistory, type TickerValue, type TickersInterface, TickersManagerStatic, type TickersSequence, drainCompleteOnStepEndQueue, removeTicker, runTickersSequence, tickerDecorator, tickers };