@drincs/pixi-vn 1.5.19 → 1.6.1

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { PlayOptions, Options, Sound as Sound$1, IMediaInstance, SoundLibrary, IMediaContext, Filter, SoundMap } from '@pixi/sound';
+import { IMediaInstance as IMediaInstance$1, PlayOptions, Options, SoundLibrary, Sound } from '@pixi/sound';
 import * as canvasUtils from '@drincs/pixi-vn/canvas';
 import { StoredChoiceInterface, StorageElementType as StorageElementType$1, OpenedLabel as OpenedLabel$1 } from '@drincs/pixi-vn/canvas';
 export * from '@drincs/pixi-vn/canvas';
 import * as characterUtils from '@drincs/pixi-vn/characters';
 export * from '@drincs/pixi-vn/characters';
-import { GameUnifier } from '@drincs/pixi-vn/core';
+import { OnErrorHandler, GameUnifier } from '@drincs/pixi-vn/core';
 export * from '@drincs/pixi-vn/core';
 import * as historyUtils from '@drincs/pixi-vn/history';
 export * from '@drincs/pixi-vn/history';
@@ -19,26 +19,95 @@ import * as storageUtils from '@drincs/pixi-vn/storage';
 export * from '@drincs/pixi-vn/storage';
 import { LRUCache } from 'lru-cache';
 import { CharacterInterface, GameStepState } from '@drincs/pixi-vn';
-import deepDiff from 'deep-diff';
 import { Difference } from 'microdiff';
 import { Devtools } from '@pixi/devtools';
 
+type IMediaInstance = Omit<IMediaInstance$1, "on" | "destroy" | "init" | "off" | "once" | "toString">;
+
 interface SoundOptions extends Omit<Options, "complete" | "loaded" | "sprites" | "source"> {
 }
 interface SoundPlayOptions extends Omit<PlayOptions, "complete" | "loaded"> {
+    /**
+     * The delay in seconds before playback becomes audible or resumes. If specified, the sound will be started immediately but delayed (for example, via pause/unpause) so that it is effectively heard only after the delay. If not specified, the sound will play without any additional delay.
+     */
+    delay?: number;
+}
+interface SoundPlayOptionsWithChannel extends SoundPlayOptions {
+    /**
+     * The alias of the audio channel to play the sound on. If the channel does not exist, it will be created.
+     * If not specified, the sound will be played on the default channel (see `SoundManagerInterface.defaultChannelAlias`).
+     */
+    channel?: string;
+}
+interface ChannelOptions extends Pick<SoundPlayOptions, "filters" | "muted" | "volume"> {
+    /**
+     * Whether this channel is a background channel.
+     * Background channels are special channels. Unlike normal channels, media connected to a background channel does not stop when a scene changes, but continues to play in the background.
+     */
+    background?: boolean;
 }
 
-declare class Sound extends Sound$1 {
-    alias?: string;
-    pause(): this;
-    resume(): this;
-    destroy(): void;
-    stop(): this;
-    play(options?: string | SoundPlayOptions): IMediaInstance | Promise<IMediaInstance>;
+interface AudioChannelInterface {
+    /**
+     * The alias of the audio channel. This is used to reference the channel when playing sounds. The alias must be unique among all channels.
+     */
+    readonly alias: string;
+    /**
+     * Plays a sound.
+     * @param alias The media and sound (asset) alias reference.
+     * @param options The options
+     * @return The sound instance,
+     *        this cannot be reused after it is done playing. Returns a Promise if the sound
+     *        has not yet loaded.
+     */
+    play(alias: string, options?: SoundPlayOptions): Promise<IMediaInstance>;
+    /**
+     * Plays a sound.
+     * @param mediaAlias The media alias reference.
+     * @param soundAlias The sound (asset) alias reference.
+     * @param options The options
+     * @return The sound instance,
+     *        this cannot be reused after it is done playing. Returns a Promise if the sound
+     *        has not yet loaded.
+     */
+    play(mediaAlias: string, soundAlias: string, options?: SoundPlayOptions): Promise<IMediaInstance>;
+    /**
+     * The volume of the audio channel, between 0 and 1. This is multiplied with the volume of each sound played through this channel.
+     */
+    volume: number;
+    /**
+     * Whether the audio channel is muted. This is combined with the muted state of each sound played through this channel.
+     */
+    muted: boolean;
     /**
-     * https://github.com/pixijs/sound/blob/main/src/Sound.ts#L235
+     * The MediaInstances currently playing through this channel. This is read-only and cannot be modified directly. Use the play method to add new MediaInstances to this channel.
      */
-    static from(source: string | string[] | SoundOptions | ArrayBuffer | HTMLAudioElement | AudioBuffer): Sound;
+    readonly mediaInstances: IMediaInstance[];
+    /**
+     * Whether this channel is a background channel.
+     * Background channels are special channels. Unlike normal channels, media connected to a background channel does not stop when a scene changes, but continues to play in the background.
+     */
+    readonly background: boolean;
+    /**
+     * Stops all media currently playing through this channel.
+     * @return Instance for chaining.
+     */
+    stopAll(): this;
+    /**
+     * Pauses any playing sounds.
+     * @return Instance for chaining.
+     */
+    pauseAll(): this;
+    /**
+     * Resumes any sounds.
+     * @return Instance for chaining.
+     */
+    resumeAll(): this;
+    /**
+     * Toggle muted property for all sounds.
+     * @return `true` if all sounds are muted.
+     */
+    toggleMuteAll(): boolean;
 }
 
 type DistortionFilter = {
@@ -95,76 +164,121 @@ interface ExportedSoundPlay extends SoundPlay {
  * Interface exported sounds
  */
 interface SoundGameState {
-    soundAliasesOrder: string[];
     filters?: SoundFilterMemory[];
-    soundsPlaying: {
-        [key: string]: ExportedSoundPlay;
-    };
     /**
      * @deprecated
      */
-    playInStepIndex?: {
-        [key: string]: SoundPlay;
+    soundsPlaying?: {
+        [key: string]: ExportedSoundPlay;
     };
-    /**
-     * @deprecated
-     */
-    sounds?: ExportedSoundOld;
-}
-interface ExportedSoundOld {
-    [key: string]: {
-        options: SoundOptions;
-        filters?: SoundFilterMemory[];
+    mediaInstances: {
+        [key: string]: {
+            channelAlias: string;
+            soundAlias: string;
+            stepCounter: number;
+            options: Omit<SoundPlayOptions, "filters"> & {
+                filters?: SoundFilterMemory[];
+            };
+            paused: boolean;
+        };
     };
 }
 
-declare class SoundManager extends SoundLibrary {
-    constructor();
-    get context(): IMediaContext;
-    get filtersAll(): Filter[];
-    set filtersAll(filtersAll: Filter[]);
-    get supported(): boolean;
-    /**
-     * https://github.com/pixijs/sound/blob/main/src/SoundLibrary.ts#L187
-     */
-    private getOptions;
-    add(alias: string, options: SoundOptions | string): Sound;
-    /**
-     * @deprecated: Use `add(alias: string, options: Options | string | ArrayBuffer | AudioBuffer | HTMLAudioElement | Sound): Sound;` instead.
-     */
-    add(map: any, globalOptions?: SoundOptions): SoundMap;
-    get useLegacy(): boolean;
-    set useLegacy(legacy: boolean);
-    get disableAutoPause(): boolean;
-    set disableAutoPause(autoPause: boolean);
-    remove(alias: string): this;
-    get volumeAll(): number;
-    set volumeAll(volume: number);
-    get speedAll(): number;
-    set speedAll(speed: number);
-    togglePauseAll(): boolean;
+interface SoundManagerInterface extends Omit<SoundLibrary, "init" | "close" | "add" | "play" | "volume" | "speed" | "remove" | "exists" | "find" | "stop" | "pause" | "resume" | "pauseAll" | "resumeAll" | "muteAll" | "unmuteAll" | "stopAll" | "removeAll" | "togglePauseAll"> {
+    /**
+     * @deprecated You can define sound assets directly in `PIXI.Assets`
+     */
+    add(alias: string, options: string): Sound;
+    /**
+     * Plays a sound.
+     * @param alias The media and sound (asset) alias reference.
+     * @param options The options
+     * @return The sound instance,
+     *        this cannot be reused after it is done playing. Returns a Promise if the sound
+     *        has not yet loaded.
+     */
+    play(alias: string, options?: SoundPlayOptionsWithChannel): Promise<IMediaInstance>;
+    play(mediaAlias: string, soundAlias: string, options?: SoundPlayOptionsWithChannel): Promise<IMediaInstance>;
+    /**
+     * Find a media by alias.
+     * @param alias - The media alias reference.
+     * @return Media object.
+     */
+    find(alias: string): IMediaInstance | undefined;
+    /**
+     * Stops a media and removes it from the manager.
+     * @param alias - The media alias reference.
+     */
+    stop(alias: string): void;
+    /**
+     * Pauses a media.
+     * @param alias - The media alias reference.
+     * @return Media object.
+     */
+    pause(alias: string): IMediaInstance | undefined;
+    /**
+     * Resumes a media.
+     * @param alias - The media alias reference.
+     * @return Media object.
+     */
+    resume(alias: string): IMediaInstance | undefined;
+    /**
+     * Edits the options of an existing sound (asset).
+     * If the asset is not yet loaded, it will be loaded with the new options.
+     */
+    edit(alias: string, options: SoundOptions): Promise<void>;
+    /**
+     * Pauses any playing sounds.
+     * @return Instance for chaining.
+     */
     pauseAll(): this;
+    /**
+     * Resumes any sounds.
+     * @return Instance for chaining.
+     */
     resumeAll(): this;
-    toggleMuteAll(): boolean;
+    /**
+     * Mutes all playing sounds.
+     * @return Instance for chaining.
+     */
     muteAll(): this;
+    /**
+     * Unmutes all playing sounds.
+     * @return Instance for chaining.
+     */
     unmuteAll(): this;
-    removeAll(): this;
+    /**
+     * Stops all sounds.
+     * @return Instance for chaining.
+     */
     stopAll(): this;
-    exists(alias: string, assert?: boolean): boolean;
-    isPlaying(): boolean;
-    find(alias: string): Sound;
-    play(alias: string, options?: SoundPlayOptions | string): IMediaInstance | Promise<IMediaInstance>;
-    stop(alias: string): Sound;
-    pause(alias: string): Sound;
-    resume(alias: string): Sound;
-    volume(alias: string, volume?: number): number;
-    speed(alias: string, speed?: number): number;
-    duration(alias: string): number;
-    close(): this;
+    load(alias: string | string[]): Promise<void>;
+    backgroundLoad(alias: string | string[]): Promise<void>;
+    backgroundLoadBundle(alias: string): Promise<void>;
     clear(): void;
+    /**
+     * Adds a new audio channel with the specified alias(es).
+     * @param alias The alias or aliases for the new channel.
+     * @returns The created AudioChannelInterface instance, or undefined if a channel with the alias already exists.
+     */
+    addChannel(alias: string | string[], options?: ChannelOptions): AudioChannelInterface | undefined;
+    /**
+     * Finds and returns the audio channel associated with the given alias. If the channel does not exist, it will be created.
+     * @param alias The alias of the audio channel to find.
+     * @returns The AudioChannelInterface instance associated with the alias.
+     */
+    findChannel(alias: string): AudioChannelInterface;
+    /**
+     * Returns an array of all existing audio channels.
+     */
+    readonly channels: AudioChannelInterface[];
+    /**
+     * The default channel alias to use when playing a sound without specifying a channel.
+     * By default, this is set to `GENERAL_CHANNEL` ("general"), but it can be changed to any string; if the channel does not yet exist, it will be created on demand when used.
+     */
+    defaultChannelAlias: string;
     export(): SoundGameState;
-    removeOldSoundAndExport(): SoundGameState;
-    restore(data: object): void;
+    restore(data: object): Promise<void>;
 }
 
 declare class CachedMap<K extends {}, V extends {}> implements Map<K, V> {
@@ -277,10 +391,12 @@ declare class CanvasBaseItem<T2 extends CanvasBaseItemMemory> {
     constructor(..._options: any);
     /**
      * This method return the memory of the canvas element.
+     * @throws {PixiError} when the method is not overridden in the subclass.
      */
     get memory(): T2;
     /**
      * This method set the memory of the canvas element.
+     * @throws {PixiError} when the method is not overridden in the subclass.
      */
     setMemory(_value: T2): Promise<void> | void;
     /**
@@ -294,19 +410,17 @@ declare class CanvasBaseItem<T2 extends CanvasBaseItemMemory> {
  */
 interface CanvasBaseItemMemory {
     pixivnId: string;
-    zIndex?: number;
-}
-
-type PauseTickerType = {
     /**
-     * Ticker ids excluded
+     * The index of the container in its parent, if it has one
      */
-    tickerIdsExcluded?: string[];
+    index?: number;
     /**
-     * Ticker ids included
+     * The label of the parent container, if it has one
      */
-    tickerIdsIncluded?: string[];
-};
+    parentLabel?: string;
+    label?: string;
+    zIndex?: number;
+}
 
 /**
  * Interface exported canvas
@@ -328,12 +442,6 @@ interface CanvasGameState {
      * @deprecated
      */
     elementAliasesOrder: string[];
-    /**
-     * @deprecated
-     */
-    tickersOnPause: {
-        [alias: string]: PauseTickerType;
-    };
     tickersToCompleteOnStepEnd: {
         tikersIds: {
             id: string;
@@ -425,29 +533,85 @@ interface ContainerMemory<C extends ContainerChild = ContainerChild> extends Con
      * The elements contained in this container
      */
     elements: CanvasBaseItemMemory[];
-    /**
-     * The index of the container in its parent, if it has one
-     */
-    index?: number;
-    /**
-     * The label of the parent container, if it has one
-     */
-    parentLabel?: string;
 }
 
-var version = "1.5.19";
+var version = "1.6.1";
 
+/**
+ * @deprecated
+ */
 declare const Repeat: RepeatType;
 /**
  * Pause the tickers for a duration.
  * @param duration Duration in seconds
  * @returns The pause object
+ * @deprecated
  */
 declare function Pause(duration: number): PauseType;
 /**
  * Is a special alias to indicate the game layer.
  */
 declare const CANVAS_APP_GAME_LAYER_ALIAS = "__game_layer__";
+/**
+ * The default audio channel for sounds that don't specify one.
+ */
+declare const GENERAL_CHANNEL = "general";
+declare const SYSTEM_RESERVED_STORAGE_KEYS: {
+    /**
+     * The key of the current dialogue memory
+     */
+    CURRENT_DIALOGUE_MEMORY_KEY: string;
+    /**
+     * The key of step counter of the current dialogue memory
+     */
+    LAST_DIALOGUE_ADDED_IN_STEP_MEMORY_KEY: string;
+    /**
+     * The key of the current menu options memory
+     */
+    CURRENT_MENU_OPTIONS_MEMORY_KEY: string;
+    /**
+     * The key of the last menu options added in the step memory
+     */
+    LAST_MENU_OPTIONS_ADDED_IN_STEP_MEMORY_KEY: string;
+    /**
+     * The key of the input memory. This value can be read by pixi-vn json importer
+     */
+    CURRENT_INPUT_VALUE_MEMORY_KEY: string;
+    /**
+     * The key of the last input added in the step memory
+     */
+    LAST_INPUT_ADDED_IN_STEP_MEMORY_KEY: string;
+    /**
+     * The key of the current input info
+     */
+    CURRENT_INPUT_INFO_MEMORY_KEY: string;
+    /**
+     * The key of the characters memory
+     */
+    CHARACTER_CATEGORY_KEY: string;
+    /**
+     * This variable is used to add the next dialog text into the current dialog memory.
+     * This value was added to introduce Ink Glue functionality https://github.com/inkle/ink/blob/master/Documentation/WritingWithInk.md#glue
+     */
+    ADD_NEXT_DIALOG_TEXT_INTO_THE_CURRENT_DIALOG_FLAG_KEY: string;
+    /**
+     * The key of a list of all labels that have been opened during the progression of the steps.
+     */
+    OPENED_LABELS_COUNTER_KEY: string;
+    /**
+     * The key of a list of all choices that have been made during the progression of the steps.
+     */
+    ALL_CHOICES_MADE_KEY: string;
+    /**
+     * The key of the current step times counter.
+     * This value was added to introduce Ink Sequences, cycles and other alternatives https://github.com/inkle/ink/blob/master/Documentation/WritingWithInk.md#sequences-cycles-and-other-alternatives
+     */
+    CURRENT_STEP_TIMES_COUNTER_KEY: string;
+    /**
+     * The key of the last dialogue step glued in the step memory
+     */
+    LAST_STEP_GLUED: string;
+};
 
 type StorageElementPrimaryType = string | number | boolean | undefined | null | StorageElementPrimaryType[];
 type StorageElementInternalType = StorageElementPrimaryType | Record<string | number | symbol, StorageElementPrimaryType> | StorageElementInternalType[];
@@ -470,12 +634,20 @@ interface StorageGameStateItem<T = StorageElementType> {
  * Interface exported storage data
  */
 type StorageGameState = {
-    base: StorageGameStateItem[];
-    temp: StorageGameStateItem[];
+    /**
+     * @deprecated
+     */
+    base?: StorageGameStateItem[];
+    /**
+     * @deprecated
+     */
+    temp?: StorageGameStateItem[];
     tempDeadlines: StorageGameStateItem<number>[];
-    flags: string[];
-} | StorageGameStateItem[] | {
-    [key: string]: StorageElementType;
+    /**
+     * @deprecated
+     */
+    flags?: string[];
+    main: StorageGameStateItem[];
 };
 
 /**
@@ -502,7 +674,7 @@ interface HistoryStep {
     /**
      * The difference between the previous step and the current step.
      */
-    diff?: deepDiff.Diff<GameStepState, GameStepState>[] | Difference[];
+    diff?: Difference[];
     /**
      * The label id of the current step.
      */
@@ -519,10 +691,6 @@ interface HistoryStep {
      * The data of the step of the label.
      */
     labelStepIndex: number | null;
-    /**
-     * @deprecated
-     */
-    dialoge?: StoredDialogue;
     /**
      * Dialogue to be shown in the game
      */
@@ -610,6 +778,7 @@ interface GameStepStateData {
  * This function is used to create a deep copy of the element
  * @param element The element to be copied
  * @returns The copied element
+ * @throws {PixiError} when the element is not JSON serializable (e.g. contains functions or class instances).
  */
 declare function createExportableElement<T>(element: T): T;
 
@@ -679,6 +848,13 @@ declare namespace Game {
      * @param navigate The function to navigate to a path
      */
     function restoreGameState(data: GameState, navigate: (path: string) => void | Promise<void>): Promise<void>;
+    /**
+     * Start the game with a label. This function will clear the canvas, stop all sounds and start the narration with the given label.
+     * @param label The label to start the game with. It can be a string or a LabelAbstract instance. If it is a string, it will be used as the id of the label to start. If it is a LabelAbstract instance, it will be used directly. If the label is not found, an error will be thrown.
+     * @param props The properties to pass to the label. It will be passed to the {@link StepLabelType} of the label when it is executed.
+     * @returns The result of the label execution. It can be a {@link StepLabelResultType} or a Promise that resolves to a {@link StepLabelResultType}.
+     */
+    function start<T extends {} = {}>(label: narrationUtils.LabelAbstract<any, T> | string, props: narrationUtils.StepLabelPropsType<T>): Promise<narrationUtils.StepLabelResultType>;
     /**
      * Convert a JSON string to a save data
      * @param json The JSON string
@@ -696,43 +872,39 @@ declare namespace Game {
      */
     function onEnd(value: narrationUtils.StepLabelType): void;
     /**
-     * Function to be executed when an error occurs in the step.
-     * Supports both synchronous and asynchronous error handlers.
+     * @deprecated Game.onError is deprecated. Use Game.addOnError / Game.removeOnError to register multiple handlers.
+     */
+    function onError(handler: (type: "step", error: any, props: narrationUtils.StepLabelPropsType) => void | Promise<void>): () => void;
+    /**
+     * Register an error handler. Multiple handlers can be registered; they
+     * will be executed in registration order.
      * @example
      * ```typescript
-     * // Synchronous error handler
-     * Game.onError((type, error, props) => {
+     * // Register a synchronous error handler
+     * Game.addOnError((error, props) => {
      *    props.notify("An error occurred")
      *    // send a notification to GlitchTip, Sentry, etc...
      * })
      *
-     * // Asynchronous error handler
-     * Game.onError(async (type, error, props) => {
+     * // Register an asynchronous error handler
+     * Game.addOnError(async (error, props) => {
      *    await logErrorToServer(error)
      *    props.notify("An error occurred")
      * })
      *
-     * // Error handler with step restoration/rollback
-     * Game.onError(async (type, error, props) => {
+     * // Register an error handler with step restoration/rollback
+     * Game.addOnError(async (error, props) => {
      *    // Restore the game state to the previous step
      *    await stepHistory.back(props)
      *    props.notify("An error occurred, returning to previous step")
      * })
      * ```
      */
-    function onError(value: (
-    /**
-     * The type of error. Currently, only "step" type is supported.
-     */
-    type: "step", 
-    /**
-     * The error object
-     */
-    error: any, 
+    function addOnError(value: OnErrorHandler): () => void;
     /**
-     * The step label properties
+     * Remove a previously registered error handler.
      */
-    props: narrationUtils.StepLabelPropsType) => void | Promise<void>): void;
+    function removeOnError(handler: OnErrorHandler): void;
     /**
      * Is a function that will be executed before any step is executed.
      * @param stepId Step id
@@ -786,7 +958,7 @@ declare namespace Game {
 declare const _default: {
     canvas: canvasUtils.CanvasManagerInterface;
     narration: narrationUtils.NarrationManagerInterface;
-    sound: SoundManager;
+    sound: SoundManagerInterface;
     storage: storageUtils.StorageManagerInterface;
     history: historyUtils.HistoryManagerInterface;
     Game: typeof Game;
@@ -802,4 +974,4 @@ declare const _default: {
     PIXIVN_VERSION: string;
 };
 
-export { CANVAS_APP_GAME_LAYER_ALIAS, CachedMap, Game, type GameState, type GameStepStateData, version as PIXIVN_VERSION, Pause, Repeat, createExportableElement, _default as default };
+export { CANVAS_APP_GAME_LAYER_ALIAS, CachedMap, GENERAL_CHANNEL, Game, type GameState, type GameStepStateData, version as PIXIVN_VERSION, Pause, Repeat, SYSTEM_RESERVED_STORAGE_KEYS, createExportableElement, _default as default };