@drincs/pixi-vn 1.5.13 → 1.5.18

package/dist/core.d.ts

@@ -0,0 +1,399 @@
+import { StepLabelProps, StepLabelResult, GameStepState, HistoryInfo, CharacterInterface } from '@drincs/pixi-vn';
+import { Container, UPDATE_PRIORITY } from 'pixi.js';
+
+type ErrorCodeType = "obsolete_save" | "unknown_element" | "unregistered_element" | "not_json_serializable" | "not_implemented" | "invalid_usage" | "unhandled_error";
+
+declare global {
+    const __VITE__: boolean | undefined;
+    const __ROLLUP_PLUGIN__: boolean | undefined;
+    const __webpack_require__: unknown;
+}
+
+/**
+ * This class is used to create a canvas element to add into a Pixi Application.
+ * You can use {@link canvas.add()} to add this element into the application.
+ * This class should be implemented and the memory method should be overridden.
+ * You must use the {@link canvasComponentDecorator} to register the canvas in the game.
+ * In Ren'Py is a displayable.
+ * @example
+ * ```typescript
+ * const CANVAS_EXAMPLE_ID = "CanvasExample";
+ *
+ * \@canvasComponentDecorator({
+ *     name: CANVAS_EXAMPLE_ID,
+ * })
+ * export class CanvasExample extends Container implements CanvasBaseItem<Memory> {
+ *     get memory(): Memory {
+ *         return {
+ *             pixivnId: CANVAS_EXAMPLE_ID,
+ *             // ... other properties
+ *         }
+ *     }
+ *     async setMemory(value: Memory) {
+ *         // ... set other properties
+ *     }
+ * }
+ * ```
+ */
+declare class CanvasBaseItem<T2 extends CanvasBaseItemMemory> {
+    constructor(..._options: any);
+    /**
+     * This method return the memory of the canvas element.
+     */
+    get memory(): T2;
+    /**
+     * This method set the memory of the canvas element.
+     */
+    setMemory(_value: T2): Promise<void> | void;
+    /**
+     * Get the id of the canvas element. This variable is used in the system to get the canvas element by id
+     */
+    pixivnId: string;
+}
+
+/**
+ * Interface for the canvas base memory
+ */
+interface CanvasBaseItemMemory {
+    pixivnId: string;
+    zIndex?: number;
+}
+
+interface CanvasBaseInterface<T2 extends CanvasBaseItemMemory> extends CanvasBaseItem<T2>, Container {
+}
+
+/**
+ * Result of a {@link StepLabelType} execution.
+ *
+ * - `StepLabelResult`: a structured result consumed by the narration engine.
+ * - `void`: the step completed without returning an explicit result.
+ * - `string`: a simple token or message interpreted by higher-level logic.
+ *
+ * Prefer returning a well-typed {@link StepLabelResult} for anything that
+ * needs to be consumed programmatically. Use plain strings only where a
+ * lightweight, convention-based signal is sufficient and clearly documented
+ * by the surrounding game logic.
+ */
+type StepLabelResultType = StepLabelResult | void | string;
+type StepLabelPropsType<T extends {} = {}> = StepLabelProps & 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>;
+
+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 = StorageElementInternalType | Record<string | number | symbol, StorageElementInternalType> | {
+    [key: string | number | symbol]: StorageElementType;
+} | StorageObjectType[] | (StorageElementPrimaryType | StorageElementInternalType | StorageElementType)[];
+/**
+ * StorageObjectType are all the types that can be stored in the storage
+ */
+type StorageObjectType = Record<string | number | symbol, StorageElementType>;
+
+declare class GameUnifier {
+    static init(options: {
+        /**
+         * The navigate function.
+         * @param path The path to navigate to.
+         * @returns
+         */
+        navigate?: (path: string) => void | Promise<void>;
+        /**
+         * This function returns the current step counter. This counter corresponds to the total number of steps that have been executed so far.
+         *
+         * If your game engine does not have a history of steps, you can return 0.
+         */
+        getStepCounter: () => number;
+        /**
+         * This function sets the current step counter.
+         *
+         * If your game engine does not have a history of steps, you can not set the step counter.
+         */
+        setStepCounter: (value: number) => void;
+        /**
+         * This function returns the current state of the game step.
+         *
+         * If your game engine does not have a history of steps, you can return an empty object.
+         */
+        getCurrentGameStepState: () => GameStepState;
+        /**
+         * This function restores the game step state.
+         *
+         * If your game engine does not have a history of steps, you can return a resolved promise.
+         *
+         * @param state The state to restore.
+         * @param navigate The function to navigate to the restored path.
+         */
+        restoreGameStepState: (state: GameStepState, navigate: (path: string) => void | Promise<void>) => Promise<void>;
+        /**
+         * This function returns the number of opened labels.
+         *
+         * If your game engine does not have a narration system, you can return 0.
+         */
+        getOpenedLabels: () => number;
+        /**
+         * This function is called after the narration.continue() method is executed.
+         * It can be used to force the completion of the ticker in the game engine.
+         */
+        onPreContinue?: () => Promise<void> | void;
+        /**
+         * This function is called to process the pending navigation requests (continue/back).
+         */
+        processNavigationRequests: (navigationRequestsCount: number, props: StepLabelPropsType<any>) => {
+            newValue: number;
+            result: Promise<StepLabelResultType>;
+        };
+        /**
+         * This function returns the value of a variable.
+         * @param key The key of the variable.
+         * @returns The value of the variable.
+         */
+        getVariable: <T extends StorageElementType>(key: string) => T | undefined;
+        /**
+         * This function sets the value of a variable.
+         * @param key The key of the variable.
+         * @param value The value of the variable.
+         */
+        setVariable: (key: string, value: StorageElementType) => void;
+        /**
+         * This function removes a variable.
+         * @param key The key of the variable.
+         */
+        removeVariable: (key: string) => void;
+        /**
+         * This function returns the value of a flag.
+         * @param name The name of the flag.
+         */
+        getFlag: (name: string) => boolean;
+        /**
+         * This function sets the value of a flag.
+         * @param name The name of the flag.
+         * @param value The value of the flag.
+         */
+        setFlag: (name: string, value: boolean) => void;
+        /**
+         * This function is called after the narration.continue() method is executed.
+         *
+         * It can be used to clear old temporary variables.
+         *
+         * @param openedLabelsNumber The number of opened labels.
+         */
+        onLabelClosing?: (openedLabelsNumber: number) => void;
+        /**
+         * Add a history step to the history.
+         *
+         * If your game engine does not have a history of steps, you can return a resolved promise.
+         *
+         * @param historyInfo The history information.
+         * @param opstions Options to add the step.
+         */
+        addHistoryItem(historyInfo?: HistoryInfo, opstions?: {
+            /**
+             * If true, the step will not be added to the history if the current step is the same as the last step.
+             */
+            ignoreSameStep?: boolean;
+        }): void;
+        /**
+         * This function returns the character by its id.
+         * @param id The id of the character.
+         * @returns The character or undefined if it does not exist.
+         */
+        getCharacter: (id: string) => CharacterInterface | undefined;
+        /**
+         * This function is called to animate a component.
+         * @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.
+         * @param priority - The priority of the ticker. @default UPDATE_PRIORITY.NORMAL
+         * @returns The id of tickers.
+         * @template T - The type of Pixi’VN component(s) being animated.
+         */
+        animate: <T extends CanvasBaseInterface<any>>(components: T | string | (string | T)[], keyframes: any, options?: any, priority?: UPDATE_PRIORITY) => string | undefined;
+    }): void;
+    private static _navigate;
+    /**
+     * The navigate function.
+     * @param path The path to navigate to.
+     * @returns
+     */
+    static get navigate(): (path: string) => void | Promise<void>;
+    static set navigate(value: (path: string) => void | Promise<void>);
+    private static _getStepCounter;
+    private static _setStepCounter;
+    /**
+     * Returns the current step counter. This counter corresponds to the total number of steps that have been executed so far.
+     */
+    static get stepCounter(): number;
+    /**
+     * Returns the current state of the game step.
+     */
+    static set stepCounter(value: number);
+    private static _getCurrentGameStepState;
+    /**
+     * Returns the current state of the game step.
+     */
+    static get currentGameStepState(): GameStepState;
+    private static _restoreGameStepState;
+    /**
+     * Restores the game step state.
+     * @param state The state to restore.
+     * @param navigate The function to navigate to the restored path.
+     */
+    static get restoreGameStepState(): (state: GameStepState, navigate: (path: string) => void | Promise<void>) => Promise<void>;
+    private static _getOpenedLabels;
+    /**
+     * Returns the number of opened labels.
+     */
+    static get openedLabels(): number;
+    private static _onPreContinueHandlers;
+    /**
+     * Register a handler to run immediately before a narration "continue" operation.
+     * Handlers are executed in registration order and may be async. Use
+     * `{@link addOnPreContinue}` / `{@link removeOnPreContinue}` to manage them programmatically.
+     */
+    static addOnPreContinue(handler: () => Promise<void> | void): void;
+    static removeOnPreContinue(handler: () => Promise<void> | void): void;
+    static clearOnPreContinueHandlers(): void;
+    static runOnPreContinue(): Promise<void>;
+    static get onPreContinue(): typeof GameUnifier.runOnPreContinue;
+    /**
+     * Number of pending navigation requests (continue/back).
+     * Positive values indicate pending continue requests,
+     * negative values indicate pending back requests.
+     */
+    private static navigationRequestsCount;
+    /**
+     * Promise-based lock to ensure only one processNavigationRequests executes at a time.
+     * This prevents race conditions in the read-modify-write operation.
+     */
+    private static processNavigationLock;
+    /**
+     * This function is called to get the number of pending continue requests.
+     * Returns a positive count of pending continue requests when navigationRequestsCount is positive.
+     * If it is > 0, after the stepsRunning is 0, the next step will be executed.
+     */
+    static get continueRequestsCount(): number;
+    /**
+     * This function is called to increase the number of pending continue requests.
+     * Note: While the increment operation itself is atomic, the overall navigation
+     * processing uses a lock in processNavigationRequests to ensure atomicity of
+     * read-modify-write operations across async boundaries.
+     * @param amount The number of steps to increase. Default is 1.
+     */
+    static increaseContinueRequest(amount?: number): void;
+    /**
+     * This function is called to get the number of pending back requests.
+     * Returns the negation of navigationRequestsCount:
+     * - Positive value (absolute value of navigationRequestsCount) when navigationRequestsCount is negative (back requests pending)
+     * - Negative value when navigationRequestsCount is positive (continue requests pending)
+     * - Zero when navigationRequestsCount is zero (no requests pending)
+     * If it is > 0, after the stepsRunning is 0, the previous step will be executed.
+     */
+    static get backRequestsCount(): number;
+    /**
+     * This function is called to increase the number of pending back requests.
+     * Note: While the decrement operation itself is atomic, the overall navigation
+     * processing uses a lock in processNavigationRequests to ensure atomicity of
+     * read-modify-write operations across async boundaries.
+     * @param amount The number of steps to increase. Default is 1.
+     */
+    static increaseBackRequest(amount?: number): void;
+    private static _processNavigationRequests;
+    /**
+     * This function processes the pending navigation requests (continue/back).
+     */
+    static processNavigationRequests(props: StepLabelPropsType<any>): Promise<StepLabelResultType>;
+    private static _getVariable;
+    /**
+     * This function returns the value of a variable.
+     * @param key The key of the variable.
+     * @returns The value of the variable.
+     */
+    static get getVariable(): <T extends StorageElementType>(key: string) => T | undefined;
+    private static _setVariable;
+    /**
+     * This function sets the value of a variable.
+     * @param key The key of the variable.
+     * @param value The value of the variable.
+     */
+    static get setVariable(): (key: string, value: StorageElementType) => void;
+    private static _removeVariable;
+    /**
+     * This function removes a variable.
+     * @param key The key of the variable.
+     */
+    static get removeVariable(): (key: string) => void;
+    private static _getFlag;
+    /**
+     * This function returns the value of a flag.
+     * @param name The name of the flag.
+     */
+    static get getFlag(): (name: string) => boolean;
+    private static _setFlag;
+    /**
+     * This function sets the value of a flag.
+     * @param name The name of the flag.
+     * @param value The value of the flag.
+     */
+    static get setFlag(): (name: string, value: boolean) => void;
+    private static _onLabelClosing;
+    /**
+     * This function is called after the narration.continue() method is executed
+     * It can be used to clear old temporary variables.
+     * @param openedLabelsNumber The number of opened labels.
+     */
+    static get onLabelClosing(): (openedLabelsNumber: number) => void;
+    private static _addHistoryItem;
+    /**
+     * Add a history step to the history.
+     * @param historyInfo The history information.
+     * @param opstions Options to add the step.
+     */
+    static get addHistoryItem(): (historyInfo?: HistoryInfo, opstions?: {
+        /**
+         * If true, the step will not be added to the history if the current step is the same as the last step.
+         */
+        ignoreSameStep?: boolean;
+    }) => void;
+    /**
+     * Count of currently executing steps.
+     * If a step triggers a narration.continue(), this number is greater than 1.
+     */
+    static runningStepsCount: number;
+    private static _getCharacter;
+    /**
+     * This function returns the character by its id.
+     * @param id The id of the character.
+     * @returns The character or undefined if it does not exist.
+     */
+    static get getCharacter(): (id: string) => CharacterInterface | undefined;
+    static onEnd?: StepLabelType;
+    static onError?: (type: "step", error: any, props: StepLabelPropsType) => void | Promise<void>;
+    private static _animate;
+    /**
+     * This function is called to animate a component.
+     * @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.
+     * @param priority - The priority of the ticker. @default UPDATE_PRIORITY.NORMAL
+     * @returns The id of tickers.
+     * @template T - The type of Pixi’VN component(s) being animated.
+     */
+    static get animate(): <T extends CanvasBaseInterface<any>>(components: T | string | (string | T)[], keyframes: any, options?: any, priority?: UPDATE_PRIORITY) => string | undefined;
+}
+
+declare class PixiError extends Error {
+    code: ErrorCodeType;
+    constructor(code: ErrorCodeType, message: string);
+}
+
+export { type ErrorCodeType, GameUnifier, PixiError };

package/dist/core.mjs

@@ -0,0 +1 @@
+var p=Object.defineProperty;var g=(r,t,o)=>t in r?p(r,t,{enumerable:true,configurable:true,writable:true,value:o}):r[t]=o;var i=(r,t,o)=>g(r,typeof t!="symbol"?t+"":t,o);var a;(l=>(l.log=(s,...m)=>console.log(`[Pixi\u2019VN] ${s}`,...m),l.warn=(s,...m)=>console.warn(`[Pixi\u2019VN] ${s}`,...m),l.error=(s,...m)=>console.error(`[Pixi\u2019VN] ${s}`,...m),l.info=(s,...m)=>console.info(`[Pixi\u2019VN] ${s}`,...m)))(a||(a={}));var n=class extends Error{constructor(o,u){super(`[Pixi\u2019VN] ${u}`);i(this,"code");this.code=o;}};var e=class e{static init(t){t.navigate&&(e._navigate=t.navigate),e._getStepCounter=t.getStepCounter,e._setStepCounter=t.setStepCounter,e._getCurrentGameStepState=t.getCurrentGameStepState,e._restoreGameStepState=t.restoreGameStepState,e._getOpenedLabels=t.getOpenedLabels,t.onPreContinue&&e.addOnPreContinue(t.onPreContinue),e._processNavigationRequests=t.processNavigationRequests,e._getVariable=t.getVariable,e._setVariable=t.setVariable,e._removeVariable=t.removeVariable,e._getFlag=t.getFlag,e._setFlag=t.setFlag,t.onLabelClosing&&(e._onLabelClosing=t.onLabelClosing),e._addHistoryItem=t.addHistoryItem,e._getCharacter=t.getCharacter,e._animate=t.animate;}static get navigate(){return e._navigate}static set navigate(t){e._navigate=t;}static get stepCounter(){return e._getStepCounter()}static set stepCounter(t){e._setStepCounter(t);}static get currentGameStepState(){return e._getCurrentGameStepState()}static get restoreGameStepState(){return e._restoreGameStepState}static get openedLabels(){return e._getOpenedLabels()}static addOnPreContinue(t){e._onPreContinueHandlers.push(t);}static removeOnPreContinue(t){e._onPreContinueHandlers=e._onPreContinueHandlers.filter(o=>o!==t);}static clearOnPreContinueHandlers(){e._onPreContinueHandlers=[];}static async runOnPreContinue(){let t=e._onPreContinueHandlers.slice();await Promise.all(t.map(o=>o()));}static get onPreContinue(){return e.runOnPreContinue}static get continueRequestsCount(){return e.navigationRequestsCount}static increaseContinueRequest(t=1){e.navigationRequestsCount+=t;}static get backRequestsCount(){return  -1*e.navigationRequestsCount}static increaseBackRequest(t=1){e.navigationRequestsCount-=t;}static async processNavigationRequests(t){let o=e._processNavigationRequests(e.navigationRequestsCount,t);return e.navigationRequestsCount=o.newValue,await o.result}static get getVariable(){return e._getVariable}static get setVariable(){return e._setVariable}static get removeVariable(){return e._removeVariable}static get getFlag(){return e._getFlag}static get setFlag(){return e._setFlag}static get onLabelClosing(){return e._onLabelClosing}static get addHistoryItem(){return e._addHistoryItem}static get getCharacter(){return e._getCharacter}static get animate(){return e._animate}};i(e,"_navigate",()=>{a.warn("Navigate function not initialized. You should add the navigate function in the Game.init() method.");}),i(e,"_getStepCounter",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"_setStepCounter",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"_getCurrentGameStepState",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"_restoreGameStepState",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"_getOpenedLabels",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"_onPreContinueHandlers",[]),i(e,"navigationRequestsCount",0),i(e,"processNavigationLock",Promise.resolve()),i(e,"_processNavigationRequests",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"_getVariable",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"_setVariable",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"_removeVariable",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"_getFlag",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"_setFlag",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"_onLabelClosing",()=>{}),i(e,"_addHistoryItem",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")}),i(e,"runningStepsCount",0),i(e,"_getCharacter",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented.")}),i(e,"onEnd"),i(e,"onError"),i(e,"_animate",()=>{throw a.error("Method not implemented, you should initialize the Game: Game.init()"),new n("not_implemented","Method not implemented, you should initialize the Game: Game.init()")});var d=e;export{d as GameUnifier,n as PixiError};