@drincs/pixi-vn/dist/narration.d.ts

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

import { ChoiceInterface as ChoiceInterface$1 } from '@drincs/pixi-vn';
import { S as StorageObjectType, a as StorageElementType } from './StorageElementType-dAIVJeiw.js';
import { L as LabelIdType, S as StepLabelType, a as LabelRunModeType, C as ChoiceOptionInterface, b as CloseChoiceOptionInterface, c as CloseType, O as OpenedLabel, d as StepLabelPropsType, e as StepLabelResultType, f as StoredIndexedChoiceInterface, D as DialogueInterface, g as StoredChoiceInterface, H as HistoryStep } from './HistoryChoiceMenuOption-BQc_jAe-.js';
export { h as Close, i as HistoryChoiceMenuOption, N as NarrationHistory } from './HistoryChoiceMenuOption-BQc_jAe-.js';
import 'microdiff';

interface LabelProps<T, StepIdType = number> {
    /**
     * Is a function that will be executed before any step is executed.
     * @param stepId Step id
     * @param label Label
     * @returns
     */
    onStepStart?: (stepId: StepIdType, label: T) => void | Promise<void>;
    /**
     * Is a function that will be executed in {@link Label.onStepStart} if the id of the step is 0
     * and when the user laods a save file.
     * When you load a save file, will be executed all onLoadingLabel functions of the {@link narration.openedLabels}.
     * It is useful for example to make sure all images used have been cached
     * @param stepId Step id
     * @param label Label
     * @returns
     * @example
     * ```typescript
     * newLabel("id", [], {
     *     onLoadingLabel: async (stepId, label) => {
     *         await Assets.load('path/to/image1.png')
     *         await Assets.load('path/to/image2.png')
     *     }
     * })
     * ```
     */
    onLoadingLabel?: (stepId: StepIdType, label: T) => void | Promise<void>;
    /**
     * Is a function that will be executed when the step ends.
     * @param stepId Step id
     * @param label Label
     * @returns
     */
    onStepEnd?: (stepId: StepIdType, label: T) => void | Promise<void>;
}

declare abstract class LabelAbstract<TLabel, TProps extends {} = {}, StepIdType = number> implements LabelProps<TLabel, StepIdType> {
    /**
     * @param id is the id of the label
     * @param props is the properties of the label
     */
    constructor(id: LabelIdType, props?: LabelProps<TLabel, StepIdType>);
    /**
     * Get the id of the label. This variable is used in the system to get the label by id, {@link RegisteredLabels.get}
     */
    readonly id: LabelIdType;
    /**
     * Get the number of steps in the label. This variable is used in the system to get the number of steps in the label.
     * @returns The number of steps in the label
     */
    abstract get stepCount(): number;
    /**
     * Get the sha of the step
     * @param index Index of the step
     */
    abstract getStepSha(stepId: StepIdType): string | undefined;
    /**
     * Get the step by id
     * @param stepId Id of the step
     * @return The step or undefined if it does not exist
     */
    abstract getStepById(stepId: StepIdType): StepLabelType<TProps> | undefined;
    private _onStepStart;
    get onStepStart(): ((stepId: StepIdType, label: TLabel) => void | Promise<void>) | undefined;
    private _onLoadingLabel;
    get onLoadingLabel(): ((stepId: StepIdType, label: TLabel) => void | Promise<void>) | undefined;
    private _onStepEnd;
    get onStepEnd(): ((stepId: StepIdType, label: TLabel) => void | Promise<void>) | undefined;
}

/**
 * Label is a class that contains a list of steps, which will be performed as the game continues.
 * For Ren'py this is the equivalent of a label.
 * @example
 * ```typescript
 * const START_LABEL_ID = "StartLabel"
 *
 * export const startLabel = newLabel(START_LABEL_ID,
 *     [
 *         (props) => {
 *             canvas.clear()
 *             narration.dialogue = { character: liam, text: "Which test do you want to perform?" }
 *             narration.choices = [
 *                 newChoiceOption("Events Test", eventsTestLabel),
 *                 newChoiceOption("Show Image Test", showImageTest),
 *             ]
 *         },
 *         (props) => narration.jump(START_LABEL_ID, props),
 *     ]
 * )
 *
 * narration.call(StartLabel)
 * ```
 */
declare class Label<T extends {} = {}> extends LabelAbstract<Label<T>, T> {
    get stepCount(): number;
    getStepById(stepId: number): StepLabelType<T> | undefined;
    /**
     * @param id is the id of the label
     * @param steps is the list of steps that the label will perform
     * @param props is the properties of the label
     */
    constructor(id: LabelIdType, steps: StepLabelType<T>[] | (() => StepLabelType<T>[]), props?: LabelProps<Label<T>>);
    private _steps;
    /**
     * Get the steps of the label.
     */
    get steps(): StepLabelType<T>[];
    getStepSha(index: number): string;
}

interface ChoiceMenuOptionOptions extends Omit<ChoiceInterface$1, "text" | "label" | "type" | "props" | "closeCurrentLabel"> {
    /**
     * Type of the label to be opened. @default "call"
     */
    type?: LabelRunModeType;
}
/**
 * Function to create a new choice menu option.
 * @example
 * ```typescript
 * newChoiceOption("Hello", HelloLabel, {})
 * ```
 */
declare function newChoiceOption<T extends StorageObjectType>(text: ChoiceInterface$1["text"], label: Label<T> | LabelAbstract<any, T> | LabelIdType, props: T, options?: ChoiceMenuOptionOptions): ChoiceOptionInterface;

interface ChoiceMenuOptionCloseOptions extends Omit<ChoiceInterface$1, "text" | "label" | "type" | "props" | "closeCurrentLabel"> {
    /**
     * If true, the current label will be closed. @default false
     */
    closeCurrentLabel?: boolean;
}
/**
 * Function to create a new choice menu option that will close the menu.
 * @example
 * ```typescript
 * newCloseChoiceOption("Return")
 * ```
 */
declare function newCloseChoiceOption(text: ChoiceInterface$1["text"], options?: ChoiceMenuOptionCloseOptions): CloseChoiceOptionInterface;

type LabelSteps<T extends {}> = [StepLabelType<T>, ...StepLabelType<Partial<T>>[]];

/**
 * Creates a new label and registers it in the system.
 * **This function must be called at least once at system startup to register the label, otherwise the system cannot be used.**
 * @param id The id of the label, it must be unique
 * @param steps The steps of the label
 * @param props The properties of the label
 * @returns The created label
 */
declare function newLabel<T extends {} = {}>(id: LabelIdType, steps: LabelSteps<T> | (() => LabelSteps<T>), props?: LabelProps<Label<T>>): Label<T>;

declare namespace RegisteredLabels {
    /**
     * Gets a label by its id
     * @param id The id of the label
     * @returns The label or undefined if it does not exist
     */
    function get<T = LabelAbstract<any>>(id: LabelIdType): T | undefined;
    /**
     * Saves a label in the system
     * @param label The label to be saved
     */
    function add(label: LabelAbstract<any, any> | LabelAbstract<any, any>[]): void;
    /**
     * Get a list of all labels registered.
     * @returns An array of labels.
     */
    function values(): LabelAbstract<any>[];
    /**
     * Check if a label is registered
     * @param id The id of the label
     * @returns True if the label is registered, false otherwise
     */
    function has(id: string): boolean;
    /**
     * Get a list of all label ids registered.
     * @returns An array of label ids.
     */
    function keys(): string[];
}

interface ChoiceInterface {
    /**
     * Text to be displayed in the menu
     */
    text: string | string[];
    /**
     * Label Id to be opened when the option is selected
     */
    label: LabelIdType | CloseType;
    /**
     * Type of the label to be opened
     */
    type: LabelRunModeType | CloseType;
    /**
     * If this is true, the choice can only be made once.
     */
    oneTime?: boolean;
    /**
     * If this is true, the choice can see only if there are no other choices. For example, all choices are one-time choices and they are already selected.
     */
    onlyHaveNoChoice?: boolean;
    /**
     * If this is true and if is the only choice, it will be automatically selected, and call/jump to the label.
     */
    autoSelect?: boolean;
    /**
     * If true, the current label will be closed
     */
    closeCurrentLabel?: boolean;
    /**
     * Properties to be passed to the label and olther parameters that you can use when get all the choice menu options.
     */
    props?: StorageObjectType;
}

/**
 * Interface exported step data
 */
interface NarrationGameState {
    openedLabels: OpenedLabel[];
    stepCounter: number;
}

interface NarrationManagerInterface {
    /**
     * Counter of execution times of the current step. Current execution is also included. Starts from 1.
     *
     * **Attention**: if the step index is edited or the code of step is edited, the counter will be reset.
     *
     * You can restart the counter in this way:
     * ```typescript
     * narration.currentStepTimesCounter = 0
     * ```
     */
    currentStepTimesCounter: number;
    /**
     * Get a random number between min and max.
     * @param min The minimum number.
     * @param max The maximum number.
     * @param options The options.
     * @returns The random number or undefined. If options.onceonly is true and all numbers between min and max have already been generated, it will return undefined.
     */
    getRandomNumber(min: number, max: number, options?: {
        /**
         * If true, the number will be generated only once on the current step of the label.
         * @default false
         */
        onceOnly?: boolean;
    }): number | undefined;
    /**
     * This counter corresponds to the total number of steps that have been executed so far.
     *
     * **Not is the {@link history.stepsHistory}.length - 1.**
     */
    readonly stepCounter: number;
    /**
     * The stack of the opened labels.
     */
    readonly openedLabels: OpenedLabel[];
    /**
     * currentLabel is the current label that occurred during the progression of the steps.
     */
    readonly currentLabel: LabelAbstract<any> | undefined;
    /**
     * Close the current label and add it to the history.
     * @returns
     */
    closeCurrentLabel(): void;
    /**
     * Close all labels and add them to the history. **Attention: This method can cause an unhandled game ending.**
     */
    closeAllLabels(): void;
    /**
     * Check if the label is already completed.
     * @param label The label to check.
     * @returns True if the label is already completed.
     */
    isLabelAlreadyCompleted(label: LabelIdType | LabelAbstract<any>): boolean;
    /**
     * Get the choices already made in the current step. **Attention**: if the choice step index is edited or the code of choice step is edited, the result will be wrong.
     * @returns The choices already made in the current step. If there are no choices, it will return undefined.
     */
    readonly alreadyCurrentStepMadeChoices: number[] | undefined;
    /**
     * Check if the current step is already completed.
     * @returns True if the current step is already completed.
     */
    readonly isCurrentStepAlreadyOpened: boolean;
    /**
     * Get times a label has been opened
     * @returns times a label has been opened
     */
    getTimesLabelOpened(label: LabelIdType): number;
    /**
     * Get times a choice has been made in the current step.
     * @param index The index of the choice.
     * @returns The number of times the choice has been made.
     */
    getTimesChoiceMade(index: number): number;
    /**
     * Save the current step to the history.
     */
    addCurrentStepToHistory(): void;
    /**
     * Return if can go to the next step.
     * @returns True if can go to the next step.
     */
    readonly canContinue: boolean;
    /**
     * Execute the next step and add it to the history. If a step is already running, it will put the request in the queue,
     * and when the step is finished, it will execute the next step.
     * @param props The props to pass to the step.
     * @param options The options.
     * @returns StepLabelResultType or undefined.
     * @example
     * ```typescript
     *     function nextOnClick() {
     *     setLoading(true)
     *     narration.continue(yourParams)
     *         .then((result) => {
     *             setUpdate((p) => p + 1)
     *             setLoading(false)
     *             if (result) {
     *                 // your code
     *             }
     *         })
     *         .catch((e) => {
     *             setLoading(false)
     *             console.error(e)
     *         })
     * }
     * ```
     */
    continue: (props: StepLabelPropsType, options?: {
        /**
         * The number of steps to advance. Must be a valid finite number greater than 0.
         * If NaN, Infinity, or a value less than or equal to 0 is provided, the implementation
         * will emit a warning and return early without advancing steps. @default 1
         */
        steps?: number;
        /**
         * If true, ignore the running step, ignore the choice menu/required input and run the next step immediately.
         */
        runNow?: boolean;
    }) => Promise<StepLabelResultType>;
    /**
     * Execute the label and add it to the history. (It's similar to Ren'Py's call function)
     * @param label The label to execute or the id of the label
     * @param props The props to pass to the label.
     * @returns StepLabelResultType or undefined.
     * @throws {PixiError} when the label is not found in the registered labels.
     * @example
     * ```typescript
     * narration.call(startLabel, yourParams).then((result) => {
     *     if (result) {
     *         // your code
     *     }
     * })
     * ```
     * @example
     * ```typescript
     * // if you use it in a step label you should return the result.
     * return narration.call(startLabel).then((result) => {
     *     return result
     * })
     * ```
     */
    call<T extends {} = {}>(label: LabelAbstract<any, T> | LabelIdType, props: StepLabelPropsType<T>): Promise<StepLabelResultType>;
    /**
     * Execute the label, close the current label, execute the new label and add the new label to the history. (It's similar to Ren'Py's jump function)
     * @param label The label to execute.
     * @param props The props to pass to the label or the id of the label
     * @returns StepLabelResultType or undefined.
     * @throws {PixiError} when the label is not found in the registered labels.
     * @example
     * ```typescript
     * narration.jump(startLabel, yourParams).then((result) => {
     *     if (result) {
     *         // your code
     *     }
     * })
     * ```
     * @example
     * ```typescript
     * // if you use it in a step label you should return the result.
     * return narration.jump(startLabel).then((result) => {
     *     return result
     * })
     * ```
     */
    jump<T extends {}>(label: LabelAbstract<any, T> | LabelIdType, props: StepLabelPropsType<T>): Promise<StepLabelResultType>;
    /**
     * Select a choice from the choice menu. and close the choice menu.
     * @param item
     * @param props
     * @returns
     * @throws {PixiError} when the choice type is not `"call"`, `"jump"`, or `"close"`.
     * @example
     * ```typescript
     * narration.selectChoice(item, {
     *     navigate: navigate,
     *     // your props
     *     ...item.props
     * })
     *     .then(() => {
     *         // your code
     *     })
     *     .catch((e) => {
     *         // your code
     *     })
     * ```
     */
    selectChoice<T extends {}>(item: StoredIndexedChoiceInterface, props: StepLabelPropsType<T>): Promise<StepLabelResultType>;
    /** Old Step Methods */
    /**
     * Dialogue to be shown in the game
     */
    get dialogue(): DialogueInterface | undefined;
    /**
     * Dialogue to be shown in the game
     * @throws {PixiError} when the dialogue contains functions or class instances that cannot be serialized to JSON.
     */
    set dialogue(props: DialogueInterface | string | string[] | undefined);
    /**
     * The options to be shown in the game
     * @example
     * ```typescript
     * narration.choices = [
     *     newChoiceOption("Events Test", EventsTestLabel, {}),
     *     newChoiceOption("Show Image Test", ShowImageTest, { image: "imageId" }, "call"),
     *     newChoiceOption("Ticker Test", TickerTestLabel, {}),
     *     newChoiceOption("Tinting Test", TintingTestLabel, {}, "jump"),
     *     newChoiceOption("Base Canvas Element Test", BaseCanvasElementTestLabel, {})
     * ]
     * ```
     */
    get choices(): StoredIndexedChoiceInterface[] | undefined;
    /**
     * The options to be shown in the game
     * @throws {PixiError} when a choice contains functions or class instances that cannot be serialized to JSON.
     * @example
     * ```typescript
     * narration.choices = [
     *     newChoiceOption("Events Test", EventsTestLabel, {}),
     *     newChoiceOption("Show Image Test", ShowImageTest, { image: "imageId" }, "call"),
     *     newChoiceOption("Ticker Test", TickerTestLabel, {}),
     *     newChoiceOption("Tinting Test", TintingTestLabel, {}, "jump"),
     *     newChoiceOption("Base Canvas Element Test", BaseCanvasElementTestLabel, {})
     * ]
     * ```
     */
    set choices(data: StoredChoiceInterface[] | undefined);
    /**
     * If true, the next dialogue text will be added to the current dialogue text.
     */
    dialogGlue: boolean;
    /**
     * The input value to be inserted by the player.
     */
    inputValue: StorageElementType;
    /**
     * If true, the player must enter a value.
     */
    readonly isRequiredInput: boolean;
    readonly inputType: string | undefined;
    /**
     * Request input from the player.
     * @param info The input value to be inserted by the player.
     * @param defaultValue The default value to be inserted.
     */
    requestInput(info: Omit<InputInfo, "isRequired">, defaultValue?: StorageElementType): void;
    /**
     * Remove the input request.
     */
    removeInputRequest(): void;
    /**
     * Clear all narration data
     */
    clear(): void;
    /**
     * Export the narration to an object.
     * @returns The narration in an object.
     */
    export(): NarrationGameState;
    /**
     * Restore the narration from an object.
     * @param data The narration in an object.
     */
    restore(data: object, lastHistoryStep: Omit<HistoryStep, "diff"> | null): Promise<void>;
}

/**
 * StepLabelPropsType is the type of the props that will be passed to the StepLabel.
 * You can override this interface to add your own props.
 * @example
 * ```typescript
 * // pixi-vn.d.ts
 * declare module '@drincs/pixi-vn' {
 *     interface StepLabelProps {
 *         navigate: (route: string) => void,
 *         [key: string]: any
 *     }
 * }
 * ```
 */
interface StepLabelProps {
}

/**
 * StepLabelResultType is the return type of the StepLabel function.
 * It can be useful for returning to the information calling function to perform other operations that cannot be performed within the StepLabel.
 * You can override this interface to add your own return types.
 * @example
 * ```typescript
 * // pixi-vn.d.ts
 * declare module '@drincs/pixi-vn' {
 *     interface StepLabelResult {
 *         newRoute?: string,
 *         [key: string]: any
 *     }
 * }
 * ```
 */
interface StepLabelResult {
}

type ChoicesMadeType = {
    /**
     * The label id of the current step.
     */
    labelId: LabelIdType;
    /**
     * The index of the step in the history.
     */
    stepIndex: number;
    /**
     * The index of the choice made by the player.
     */
    choiceIndex: number;
    /**
     * The sha1 of the step function.
     */
    stepSha1: string;
    /**
     * The number of times the player made a choice for this step.
     */
    madeTimes: number;
};

type AllOpenedLabelsType = {
    [key: LabelIdType]: {
        biggestStep: number;
        openCount: number;
    };
};
type CurrentStepTimesCounterMemotyData = {
    stepCounters?: number[];
    usedRandomNumbers?: {
        [minmaxkey: string]: number[];
    };
    stepSha1: string;
};
declare class NarrationManagerStatic {
    private constructor();
    static choiceMadeTemp: undefined | number;
    static lastHistoryStep: Omit<HistoryStep, "diff"> | null;
    /**
     * is a list of all labels that have been opened during the progression of the steps.
     * the key is the label id and the biggest step opened.
     */
    static get allOpenedLabels(): AllOpenedLabelsType;
    static set allOpenedLabels(value: AllOpenedLabelsType);
    static getCurrentStepTimesCounterData(nestedId?: string): CurrentStepTimesCounterMemotyData | null;
    private static setCurrentStepTimesCounterData;
    static getCurrentStepTimesCounter(nestedId?: string): number;
    static getRandomNumber(min: number, max: number, options?: {
        onceOnly?: boolean;
        nestedId?: string;
    }): number | undefined;
    static resetCurrentStepTimesCounter(nestedId?: string): void;
    /**
     * is a list of all choices made by the player during the progression of the steps.
     */
    static get allChoicesMade(): ChoicesMadeType[];
    static set allChoicesMade(value: ChoicesMadeType[]);
    static _stepCounter: number;
    /**
     * Increase the last step index that occurred during the progression of the steps.
     */
    static increaseStepCounter(): void;
    private static _openedLabels;
    static get openedLabels(): OpenedLabel[];
    static set openedLabels(value: OpenedLabel[]);
    private static _originalOpenedLabels;
    static get originalOpenedLabels(): OpenedLabel[];
    static set originalOpenedLabels(value: OpenedLabel[]);
    static get _currentLabel(): Label | undefined;
    /**
     * currentLabelId is the current label id that occurred during the progression of the steps.
     */
    static get currentLabelId(): LabelIdType | undefined;
    static get currentLabelStepIndex(): number | null;
    /**
     * Add a label to the history.
     * @param label The label to add to the history.
     * @param stepIndex The step index of the label.
     */
    static addLabelHistory(label: LabelIdType, stepIndex: number): void;
    static addChoicesMade(label: LabelIdType, stepIndex: number, stepSha: string, choiceMade: number): void;
    /**
     * Add a label to the history.
     * @param label The label to add to the history.
     * @throws {PixiError} when the label is not found in the registered labels.
     */
    static pushNewLabel(label: LabelIdType): void;
    /**
     * Increase the current step index of the current label.
     */
    static increaseCurrentStepIndex(): void;
    private static _onStepStart?;
    static set onStepStart(value: (stepId: number, label: LabelAbstract<any>) => void | Promise<void>);
    static get onStepStart(): ((stepId: number, label: LabelAbstract<any>) => Promise<void[]>) | undefined;
    static onLoadingLabel?: (stepId: number, label: LabelAbstract<any>) => void | Promise<void>;
    static onStepEnd?: (stepId: number, label: LabelAbstract<any>) => void | Promise<void>;
}

type InputInfo = {
    isRequired?: boolean;
    type?: string;
};

declare const narration: NarrationManagerInterface;

export { type ChoiceInterface, ChoiceOptionInterface, CloseChoiceOptionInterface, CloseType, DialogueInterface, HistoryStep, type InputInfo, Label, LabelAbstract, type LabelProps, LabelRunModeType, type LabelSteps, type NarrationGameState, type NarrationManagerInterface, NarrationManagerStatic, OpenedLabel, RegisteredLabels, type StepLabelProps, StepLabelPropsType, type StepLabelResult, StepLabelResultType, StepLabelType, StoredChoiceInterface, StoredIndexedChoiceInterface, narration, newChoiceOption, newCloseChoiceOption, newLabel };