@drincs/pixi-vn 0.3.4 → 0.3.6

package/README.md

@@ -1,4 +1,4 @@
-# Pixi'VN - Pixi Visual Novel Engine
+# Pixi'VN - PixiJS Visual Novel Engine
 
 Pixi'VN is a npm package that provides various features for creating visual novels.
 
@@ -9,6 +9,14 @@ Pixi'VN is based on [Pixi.js](https://pixijs.com/), a modern 2D rendering engine
 In addition to managing the Pixi.js "Canvas", Pixi'VN offers the possibility of adding an HTML Element with the same dimensions as the "Canvas" to add interactions with the user.
 This allows the use of systems such as React, Vue, Angular, etc. to create much more complex interfaces with excellent performance.
 
+## Why Pixi'VN?
+
+The reason why Pixi'VN was born is that current systems for creating a visual novel are based on dated systems and have many shortcomings.
+
+## Pivi'VN Templates
+
+* [Pixi’VN template (React + Vite + MUI joy)](https://github.com/DRincs-Productions/pixi-vn-react-template)
+
 ## Get Started
 
 ### Installation
@@ -87,7 +95,3 @@ body {
 ## Wiki
 
 For more information, visit the [Wiki](https://pixivn.readthedocs.io/)
-
-## Why Pixi'VN?
-
-The reason why Pixi'VN was born is that current systems for creating a visual novel are based on dated systems and have many shortcomings.

package/dist/index.d.mts

@@ -193,7 +193,18 @@ type StepHistoryDataType = string;
 /**
  * StepLabel is a function that will be executed as the game continues.
  */
-type StepLabelType = (() => void | Promise<void>);
+type StepLabelType = (() => StepLabelResultType | Promise<StepLabelResultType>);
+/**
+ * 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.
+ */
+type StepLabelResultType = {
+    /**
+     * The new route to navigate to.
+     */
+    newRoute?: string;
+    [key: string]: any;
+} | void;
 
 /**
  * Label is a class that contains a list of steps, which will be performed as the game continues.
@@ -262,11 +273,11 @@ declare class ChoiceMenuOptionLabel {
      */
     constructor(text: string, label: typeof Label, type?: LabelRunModeEnum);
 }
-interface IStoratedChoiceMenuOptionLabel {
+type IStoratedChoiceMenuOptionLabel = {
     text: string;
     label: LabelIdType;
     type: LabelRunModeEnum;
-}
+};
 
 /**
  * Munu is a type that contains a list of Label that a player can choose from.
@@ -284,10 +295,12 @@ declare function Pause(duration: number): PauseType;
 type RepeatType = "Repeat";
 declare const Repeat: RepeatType;
 
+type StorageElementPrimaryType = string | number | boolean | undefined | null | StorageElementPrimaryType[];
+type StorageElementInternalType = StorageElementPrimaryType | Record<string | number | symbol, StorageElementPrimaryType> | StorageElementInternalType[];
 /**
  * StorageElementType are all the types that can be stored in the storage
  */
-type StorageElementType = string | number | boolean | object | undefined | null;
+type StorageElementType = StorageElementInternalType | Record<string | number | symbol, StorageElementInternalType>;
 
 /**
  * Base class for all dialogue models.
@@ -671,16 +684,33 @@ declare class TickerBase<TArgs extends TickerArgsType> implements ITicker<TArgs>
     fn(_t: Ticker, _args: TArgs, _tags: string | string[]): void;
 }
 
+type TickerFadeAlphaProps = {
+    /**
+     * The speed of the fade
+     */
+    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 tag to remove after the fade is done
+     */
+    tagToRemoveAfter?: string[] | string;
+    /**
+     * If true, the fade only starts if the canvas element have a texture
+     */
+    startOnlyIfHaveTexture?: boolean;
+};
+
 /**
  * A ticker that fades the alpha of the canvas element of the canvas.
- * @param args The arguments that are passed to the ticker
- * - speed: The speed of the fade
- * - type: The type of the fade, default is "hide"
- * - limit: The limit of the fade, default is 0 for hide and 1 for show
- * - tagToRemoveAfter?: The tag to remove after the fade is done
- * - startOnlyIfHaveTexture?: If true, the fade only starts if the canvas element have a texture
- * @param duration The duration of the ticker
- * @param priority The priority of the ticker
  * @example
  * ```typescript
  * let bunny = addImage("bunny1", "https://pixijs.com/assets/eggHead.png")
@@ -694,13 +724,7 @@ declare class TickerBase<TArgs extends TickerArgsType> implements ITicker<TArgs>
  * GameWindowManager.addTicker("bunny", ticker)
  * ```
  */
-declare class TickerFadeAlpha extends TickerBase<{
-    speed: number;
-    type?: "hide" | "show";
-    limit?: number;
-    tagToRemoveAfter?: string[] | string;
-    startOnlyIfHaveTexture?: boolean;
-}> {
+declare class TickerFadeAlpha extends TickerBase<TickerFadeAlphaProps> {
     /**
      * The method that will be called every frame to fade the alpha of the canvas element of the canvas.
      * @param delta The delta time
@@ -717,114 +741,16 @@ declare class TickerFadeAlpha extends TickerBase<{
 }
 
 type TickerProgrationType = ITickerProgrationLinear | ITickerProgrationExponential;
-interface ITickerProgrationLinear {
+type ITickerProgrationLinear = {
     amt: number;
     limit?: number;
     type: "linear";
-}
-interface ITickerProgrationExponential {
+};
+type ITickerProgrationExponential = {
     percentage: number;
     limit?: number;
     type: "exponential";
-}
-
-/**
- * A ticker that rotates the canvas element of the canvas.
- * @param args The arguments that are passed to the ticker
- * - speed: The speed of the rotation, default is 0.1
- * - clockwise: The direction of the rotation, default is true
- * - speedProgression: The progression of the speed
- * - startOnlyIfHaveTexture?: If true, the rotation only starts if the canvas element have a texture
- * @param duration The duration of the ticker
- * @param priority The priority of the ticker
- * @example
- * ```typescript
- * let alien = addImage("alien", 'https://pixijs.com/assets/eggHead.png')
- * GameWindowManager.addCanvasElement("alien", alien);
- * const ticker = new TickerRotate({
- *    speed: 0.1,
- *    clockwise: true,
- * }),
- * GameWindowManager.addTicker("alien", ticker)
- */
-declare class TickerRotate extends TickerBase<{
-    speed?: number;
-    clockwise?: boolean;
-    speedProgression?: TickerProgrationType;
-    startOnlyIfHaveTexture?: boolean;
-}> {
-    /**
-     * The method that will be called every frame to rotate the canvas element of the canvas.
-     * @param delta The delta time
-     * @param args The arguments that are passed to the ticker
-     * @param tags The tags of the canvas element that are connected to this ticker
-     */
-    fn(t: Ticker, args: {
-        speed?: number;
-        clockwise?: boolean;
-        speedProgression?: TickerProgrationType;
-        startOnlyIfHaveTexture?: boolean;
-    }, tags: string[]): void;
-}
-
-type CanvasElementTagType = string;
-
-/**
- * Is a decorator that register a canvas element in the game.
- * @param name Name of the canvas element, by default it will use the class name. If the name is already registered, it will show a warning
- * @returns
- */
-declare function canvasElementDecorator(name?: CanvasElementTagType): (target: typeof CanvasBase<any>) => void;
-
-/**
- * Is a function that saves the character. If the character already exists, it will be overwritten.
- * @param character is the character to save
- * @returns
- * @example
- * ```typescript
- * export const liam = new CharacterBaseModel('liam', { name: 'Liam'});
- * export const alice = new CharacterBaseModel('alice', { name: 'Alice'});
- * saveCharacter([liam, alice]);
- * ```
- */
-declare function saveCharacter<T extends CharacterBaseModel = CharacterBaseModel>(character: T | T[]): void;
-/**
- * is a function that returns the character by the id
- * @param id is the id of the character
- * @returns the character
- * @example
- * ```typescript
- * const liam = getCharacterById('liam');
- * ```
- */
-declare function getCharacterById<T extends CharacterBaseModel>(id: string): T | undefined;
-/**
- * is a function that returns all characters
- * @returns all characters
- * @example
- * ```typescript
- * const allCharacters = getAllCharacters();
- * ```
- */
-declare function getAllCharacters<T extends CharacterBaseModel>(): T[];
-
-/**
- * Is a decorator that register a event in the game.
- * Is a required decorator for use the event in the game.
- * Thanks to this decoration the game has the possibility of updating the events to the latest modification and saving the game.
- * @param name is th identifier of the event, by default is the name of the class
- * @returns
- */
-declare function eventDecorator(name?: EventIdType): (target: typeof CanvasEvent<any>) => void;
-
-/**
- * Is a decorator that register a label in the game.
- * Is a required decorator for use the label in the game.
- * Thanks to this decoration the game has the possibility of updating the labels 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 labelDecorator(name?: LabelIdType): (target: typeof Label) => void;
+};
 
 /**
  * is a string that represents a ticker id.
@@ -832,15 +758,6 @@ declare function labelDecorator(name?: LabelIdType): (target: typeof Label) => v
  */
 type TickerIdType = string;
 
-/**
- * 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: typeof TickerBase<any>) => void;
-
 /**
  * IClassWithArgsHistory is a class that contains the name of a class and the arguments that were used to create it.
  */
@@ -996,6 +913,122 @@ interface ITickersSteps {
     steps: (ITickersStep<any> | RepeatType | PauseType)[];
 }
 
+type TickerRotateProps = {
+    /**
+     * The speed of the rotation
+     * @default 0.1
+     */
+    speed?: number;
+    /**
+     * The direction of the rotation
+     * @default true
+     */
+    clockwise?: boolean;
+    /**
+     * The progression of the speed
+     */
+    speedProgression?: TickerProgrationType;
+    /**
+     * If true, the rotation only starts if the canvas element have a texture
+     */
+    startOnlyIfHaveTexture?: boolean;
+};
+
+/**
+ * A ticker that rotates the canvas element of the canvas.
+ * @example
+ * ```typescript
+ * let alien = addImage("alien", 'https://pixijs.com/assets/eggHead.png')
+ * GameWindowManager.addCanvasElement("alien", alien);
+ * const ticker = new TickerRotate({
+ *    speed: 0.1,
+ *    clockwise: true,
+ * }),
+ * GameWindowManager.addTicker("alien", ticker)
+ */
+declare class TickerRotate extends TickerBase<TickerRotateProps> {
+    /**
+     * The method that will be called every frame to rotate the canvas element of the canvas.
+     * @param delta The delta time
+     * @param args The arguments that are passed to the ticker
+     * @param tags The tags of the canvas element that are connected to this ticker
+     */
+    fn(t: Ticker, args: {
+        speed?: number;
+        clockwise?: boolean;
+        speedProgression?: TickerProgrationType;
+        startOnlyIfHaveTexture?: boolean;
+    }, tags: string[]): void;
+}
+
+type CanvasElementTagType = string;
+
+/**
+ * Is a decorator that register a canvas element in the game.
+ * @param name Name of the canvas element, by default it will use the class name. If the name is already registered, it will show a warning
+ * @returns
+ */
+declare function canvasElementDecorator(name?: CanvasElementTagType): (target: typeof CanvasBase<any>) => void;
+
+/**
+ * Is a function that saves the character. If the character already exists, it will be overwritten.
+ * @param character is the character to save
+ * @returns
+ * @example
+ * ```typescript
+ * export const liam = new CharacterBaseModel('liam', { name: 'Liam'});
+ * export const alice = new CharacterBaseModel('alice', { name: 'Alice'});
+ * saveCharacter([liam, alice]);
+ * ```
+ */
+declare function saveCharacter<T extends CharacterBaseModel = CharacterBaseModel>(character: T | T[]): void;
+/**
+ * is a function that returns the character by the id
+ * @param id is the id of the character
+ * @returns the character
+ * @example
+ * ```typescript
+ * const liam = getCharacterById('liam');
+ * ```
+ */
+declare function getCharacterById<T extends CharacterBaseModel>(id: string): T | undefined;
+/**
+ * is a function that returns all characters
+ * @returns all characters
+ * @example
+ * ```typescript
+ * const allCharacters = getAllCharacters();
+ * ```
+ */
+declare function getAllCharacters<T extends CharacterBaseModel>(): T[];
+
+/**
+ * Is a decorator that register a event in the game.
+ * Is a required decorator for use the event in the game.
+ * Thanks to this decoration the game has the possibility of updating the events to the latest modification and saving the game.
+ * @param name is th identifier of the event, by default is the name of the class
+ * @returns
+ */
+declare function eventDecorator(name?: EventIdType): (target: typeof CanvasEvent<any>) => void;
+
+/**
+ * Is a decorator that register a label in the game.
+ * Is a required decorator for use the label in the game.
+ * Thanks to this decoration the game has the possibility of updating the labels 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 labelDecorator(name?: LabelIdType): (target: typeof Label) => 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: typeof TickerBase<any>) => void;
+
 /**
  * Set the dialogue to be shown in the game
  * @param text Text of the dialogue
@@ -1239,15 +1272,18 @@ declare class GameStepManager {
     private static increaseCurrentStepIndex;
     /**
      * Execute the next step and add it to the history.
-     * @returns
+     * @returns StepLabelResultType or undefined.
      * @example
      * ```typescript
      *     function nextOnClick() {
      *     setLoading(true)
      *     GameStepManager.runNextStep()
-     *         .then(() => {
+     *         .then((result) => {
      *             setUpdate((p) => p + 1)
      *             setLoading(false)
+     *             if (result) {
+     *                 // your code
+     *             }
      *         })
      *         .catch((e) => {
      *             setLoading(false)
@@ -1256,34 +1292,56 @@ declare class GameStepManager {
      * }
      * ```
      */
-    static runNextStep(): Promise<void>;
+    static runNextStep(): Promise<StepLabelResultType>;
     /**
      * Execute the current step and add it to the history.
-     * @returns
+     * @returns StepLabelResultType or undefined.
      */
     private static runCurrentStep;
     /**
      * Execute the label and add it to the history.
      * Is a call function in Ren'Py.
      * @param label The label to execute.
-     * @returns
+     * @returns StepLabelResultType or undefined.
+     * @example
+     * ```typescript
+     * GameStepManager.callLabel(StartLabel).then((result) => {
+     *     if (result) {
+     *         // your code
+     *     }
+     * })
+     * ```
      * @example
      * ```typescript
-     * GameStepManager.callLabel(StartLabel)
+     * // if you use it in a step label you should return the result.
+     * return GameStepManager.callLabel(StartLabel).then((result) => {
+     *     return result
+     * })
      * ```
      */
-    static callLabel(label: typeof Label | Label): Promise<void>;
+    static callLabel(label: typeof Label | Label): Promise<StepLabelResultType>;
     /**
      * Execute the label, close all labels and add them to the history.
      * Is a jump function in Ren'Py.
-     * @param label
-     * @returns
+     * @param label The label to execute.
+     * @returns StepLabelResultType or undefined.
      * @example
      * ```typescript
-     * GameStepManager.jumpLabel(StartLabel)
+     * GameStepManager.jumpLabel(StartLabel).then((result) => {
+     *     if (result) {
+     *         // your code
+     *     }
+     * })
+     * ```
+     * @example
+     * ```typescript
+     * // if you use it in a step label you should return the result.
+     * return GameStepManager.jumpLabel(StartLabel).then((result) => {
+     *     return result
+     * })
      * ```
      */
-    static jumpLabel(label: typeof Label | Label): Promise<void>;
+    static jumpLabel(label: typeof Label | Label): Promise<StepLabelResultType>;
     /**
      * Go back to the last step and add it to the history.
      * @param navigate The navigate function.
@@ -1621,4 +1679,4 @@ declare class GameWindowManager {
     static import(data: object): void;
 }
 
-export { CanvasBase, CanvasContainer, CanvasEvent, type CanvasEventNamesType, CanvasImage, CanvasSprite, CanvasText, CharacterBaseModel, type CharacterBaseModelProps, ChoiceMenuOptionLabel, type ChoiceMenuOptionsType, DialogueBaseModel, type ExportedCanvas, type ExportedStep, type ExportedStorage, GameStepManager, GameStorageManager, GameWindowManager, type ICanvasBaseMemory, type ICanvasContainerMemory, type ICanvasImageMemory, type ICanvasSpriteBaseMemory, type ICanvasSpriteMemory, type ICanvasTextMemory as ICanvasTextTextMemory, type IClassWithArgsHistory, type IClassWithArgsHistoryForExport, type IDialogueHistory, type IHistoryStep, type IHistoryStepData, type IOpenedLabel, type ISaveData, type ITextureMemory, type ITicker, type ITickersSteps, Label, LabelRunModeEnum, Pause, type PauseType, PauseValueType, Repeat, type RepeatType, type StepLabelType, type StorageElementType, StoredClassModel, TickerBase, TickerFadeAlpha, type TickerProgrationType, TickerRotate, addImage, canvasElementDecorator, clearAllGameDatas, clearChoiceMenuOptions, clearDialogue, eventDecorator, getAllCharacters, getCharacterById, getChoiceMenuOptions, getDialogue, getDialogueHistory, getFlag, getSaveData, getSaveJson, getTexture, labelDecorator, loadSaveData, loadSaveJson, removeCanvasElement, saveCharacter, setChoiceMenuOptions, setDialogue, setFlag, showCanvasImages, showImageWithDissolveTransition, tickerDecorator };
+export { CanvasBase, CanvasContainer, CanvasEvent, type CanvasEventNamesType, CanvasImage, CanvasSprite, CanvasText, CharacterBaseModel, type CharacterBaseModelProps, ChoiceMenuOptionLabel, type ChoiceMenuOptionsType, DialogueBaseModel, type ExportedCanvas, type ExportedStep, type ExportedStorage, GameStepManager, GameStorageManager, GameWindowManager, type ICanvasBaseMemory, type ICanvasContainerMemory, type ICanvasImageMemory, type ICanvasSpriteBaseMemory, type ICanvasSpriteMemory, type ICanvasTextMemory as ICanvasTextTextMemory, type IClassWithArgsHistory, type IClassWithArgsHistoryForExport, type IDialogueHistory, type IHistoryStep, type IHistoryStepData, type IOpenedLabel, type ISaveData, type ITextureMemory, type ITicker, type ITickersSteps, Label, LabelRunModeEnum, Pause, type PauseType, PauseValueType, Repeat, type RepeatType, type StepLabelResultType, type StepLabelType, type StorageElementType, StoredClassModel, TickerBase, TickerFadeAlpha, type TickerFadeAlphaProps, type TickerProgrationType, TickerRotate, type TickerRotateProps, addImage, canvasElementDecorator, clearAllGameDatas, clearChoiceMenuOptions, clearDialogue, eventDecorator, getAllCharacters, getCharacterById, getChoiceMenuOptions, getDialogue, getDialogueHistory, getFlag, getSaveData, getSaveJson, getTexture, labelDecorator, loadSaveData, loadSaveJson, removeCanvasElement, saveCharacter, setChoiceMenuOptions, setDialogue, setFlag, showCanvasImages, showImageWithDissolveTransition, tickerDecorator };