UNPKG

@drincs/pixi-vn

Version:

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

688 lines (668 loc) 27.9 kB
import { N as NarrationGameState } from './NarrationGameState-Cu-OYzph.cjs'; import { StepLabelProps as StepLabelProps$1, StepLabelResult as StepLabelResult$1, ChoiceInterface as ChoiceInterface$1 } from '@drincs/pixi-vn'; import { a as StorageObjectType, S as StorageElementType } from './StorageElementType-DTGcnkzF.cjs'; import { e as LabelIdType, L as LabelRunModeType, a as ChoiceOptionInterface, b as CloseChoiceOptionInterface, C as CloseType, O as OpenedLabel, c as StoredIndexedChoiceInterface, D as DialogueInterface, S as StoredChoiceInterface, H as HistoryStep, d as Close } from './OpenedLabel-Dgkgemkv.cjs'; import { H as HistoryChoiceMenuOption, N as NarrationHistory } from './HistoryChoiceMenuOption-unaLLfKR.cjs'; type StepLabelResultType = StepLabelResult$1 | void; type StepLabelPropsType<T extends {} = {}> = StepLabelProps$1 & T; /** * StepLabel is a function that will be executed as the game continues. */ type StepLabelType<T extends {} = {}> = (props: StepLabelPropsType<T>, info: { /** * The id of the label. */ labelId: string; }) => StepLabelResultType | Promise<StepLabelResultType>; 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>); private _id; /** * Get the id of the label. This variable is used in the system to get the label by id, {@link RegisteredLabels.get} */ get 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.choiceMenuOptions = [ * newChoiceOption("Events Test", eventsTestLabel), * newChoiceOption("Show Image Test", showImageTest), * ] * }, * (props) => narration.jumpLabel(START_LABEL_ID, props), * ] * ) * * narration.callLabel(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; } 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 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 canGoNext: 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.goNext(yourParams) * .then((result) => { * setUpdate((p) => p + 1) * setLoading(false) * if (result) { * // your code * } * }) * .catch((e) => { * setLoading(false) * console.error(e) * }) * } * ``` */ goNext(props: StepLabelPropsType, options?: { /** * The index of the choice made by the player. (This params is used in the choice menu) */ choiceMade?: 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. * @example * ```typescript * narration.callLabel(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.callLabel(startLabel).then((result) => { * return result * }) * ``` */ callLabel<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. * @example * ```typescript * narration.jumpLabel(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.jumpLabel(startLabel).then((result) => { * return result * }) * ``` */ jumpLabel<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 * @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 */ set dialogue(props: DialogueInterface | string | string[] | undefined); /** * The options to be shown in the game * @example * ```typescript * narration.choiceMenuOptions = [ * 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 choiceMenuOptions(): StoredIndexedChoiceInterface[] | undefined; /** * The options to be shown in the game * @example * ```typescript * narration.choiceMenuOptions = [ * 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 choiceMenuOptions(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 = { /** * @deprecated use stepIndexs */ lastStepIndexs?: number[]; stepCounters?: number[]; usedRandomNumbers?: { [minmaxkey: string]: number[]; }; stepSha1: string; }; declare class NarrationManagerStatic { private constructor(); /** * Number of steps function that are running. * If you run a step that have a goNext, this number is > 1. */ static stepsRunning: number; /** * Number of requests to go to the next step. * If it is > 0, after the stepsRunning is 0, the next step will be executed */ static goNextRequests: number; 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. */ 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; type narrationUtils_ChoiceInterface = ChoiceInterface; declare const narrationUtils_ChoiceOptionInterface: typeof ChoiceOptionInterface; declare const narrationUtils_Close: typeof Close; declare const narrationUtils_CloseChoiceOptionInterface: typeof CloseChoiceOptionInterface; declare const narrationUtils_CloseType: typeof CloseType; declare const narrationUtils_DialogueInterface: typeof DialogueInterface; declare const narrationUtils_HistoryChoiceMenuOption: typeof HistoryChoiceMenuOption; declare const narrationUtils_HistoryStep: typeof HistoryStep; type narrationUtils_InputInfo = InputInfo; type narrationUtils_Label<T extends {} = {}> = Label<T>; declare const narrationUtils_Label: typeof Label; type narrationUtils_LabelAbstract<TLabel, TProps extends {} = {}, StepIdType = number> = LabelAbstract<TLabel, TProps, StepIdType>; declare const narrationUtils_LabelAbstract: typeof LabelAbstract; type narrationUtils_LabelProps<T, StepIdType = number> = LabelProps<T, StepIdType>; declare const narrationUtils_LabelRunModeType: typeof LabelRunModeType; type narrationUtils_LabelSteps<T extends {}> = LabelSteps<T>; declare const narrationUtils_NarrationGameState: typeof NarrationGameState; declare const narrationUtils_NarrationHistory: typeof NarrationHistory; type narrationUtils_NarrationManagerInterface = NarrationManagerInterface; type narrationUtils_NarrationManagerStatic = NarrationManagerStatic; declare const narrationUtils_NarrationManagerStatic: typeof NarrationManagerStatic; declare const narrationUtils_OpenedLabel: typeof OpenedLabel; declare const narrationUtils_RegisteredLabels: typeof RegisteredLabels; type narrationUtils_StepLabelProps = StepLabelProps; type narrationUtils_StepLabelPropsType<T extends {} = {}> = StepLabelPropsType<T>; type narrationUtils_StepLabelResult = StepLabelResult; type narrationUtils_StepLabelResultType = StepLabelResultType; type narrationUtils_StepLabelType<T extends {} = {}> = StepLabelType<T>; declare const narrationUtils_StoredChoiceInterface: typeof StoredChoiceInterface; declare const narrationUtils_StoredIndexedChoiceInterface: typeof StoredIndexedChoiceInterface; declare const narrationUtils_narration: typeof narration; declare const narrationUtils_newChoiceOption: typeof newChoiceOption; declare const narrationUtils_newCloseChoiceOption: typeof newCloseChoiceOption; declare const narrationUtils_newLabel: typeof newLabel; declare namespace narrationUtils { export { type narrationUtils_ChoiceInterface as ChoiceInterface, narrationUtils_ChoiceOptionInterface as ChoiceOptionInterface, narrationUtils_Close as Close, narrationUtils_CloseChoiceOptionInterface as CloseChoiceOptionInterface, narrationUtils_CloseType as CloseType, narrationUtils_DialogueInterface as DialogueInterface, narrationUtils_HistoryChoiceMenuOption as HistoryChoiceMenuOption, narrationUtils_HistoryStep as HistoryStep, type narrationUtils_InputInfo as InputInfo, narrationUtils_Label as Label, narrationUtils_LabelAbstract as LabelAbstract, type narrationUtils_LabelProps as LabelProps, narrationUtils_LabelRunModeType as LabelRunModeType, type narrationUtils_LabelSteps as LabelSteps, narrationUtils_NarrationGameState as NarrationGameState, narrationUtils_NarrationHistory as NarrationHistory, type narrationUtils_NarrationManagerInterface as NarrationManagerInterface, narrationUtils_NarrationManagerStatic as NarrationManagerStatic, narrationUtils_OpenedLabel as OpenedLabel, narrationUtils_RegisteredLabels as RegisteredLabels, type narrationUtils_StepLabelProps as StepLabelProps, type narrationUtils_StepLabelPropsType as StepLabelPropsType, type narrationUtils_StepLabelResult as StepLabelResult, type narrationUtils_StepLabelResultType as StepLabelResultType, type narrationUtils_StepLabelType as StepLabelType, narrationUtils_StoredChoiceInterface as StoredChoiceInterface, narrationUtils_StoredIndexedChoiceInterface as StoredIndexedChoiceInterface, narrationUtils_narration as narration, narrationUtils_newChoiceOption as newChoiceOption, narrationUtils_newCloseChoiceOption as newCloseChoiceOption, narrationUtils_newLabel as newLabel }; } export { type ChoiceInterface as C, type InputInfo as I, LabelAbstract as L, type NarrationManagerInterface as N, RegisteredLabels as R, type StepLabelType as S, type StepLabelPropsType as a, narration as b, newChoiceOption as c, newCloseChoiceOption as d, Label as e, newLabel as f, type LabelProps as g, type StepLabelProps as h, type StepLabelResult as i, NarrationManagerStatic as j, type LabelSteps as k, type StepLabelResultType as l, narrationUtils as n };