@drincs/pixi-vn-json/dist/translator.d.ts

Pixi'VN can be integrated with JSON files to create a visual novel.

import { StorageElementType, CanvasBaseInterface, ImageSprite, ShakeEffectProps, ShowWithDissolveTransitionProps, ShowWithFadeTransitionProps, MoveInOutProps, ZoomInOutProps, PushInOutProps, ImageContainerOptions, ImageSpriteOptions, TextOptions, ImageSpriteMemory, VideoSpriteMemory, ImageContainerMemory, TextMemory, ContainerOptions, ContainerMemory, SoundPlayOptionsWithChannel, MediaInterface, LabelRunModeType, StorageObjectType, StepLabelPropsType } from '@drincs/pixi-vn';
import { KeyframesType, AnimationOptions, ObjectSegment, ObjectSegmentWithTransition, SequenceOptions } from '@drincs/pixi-vn/motion';
import { UPDATE_PRIORITY } from 'pixi.js';

/**
 * A single element that can appear inside a step-switch, which may be a direct value,
 * a conditional statement, or a result-to-combine.
 */
type PixiVNJsonStepSwitchElementType<Then> = Then | PixiVNJsonConditionalStatements<Then> | PixiVNJsonConditionalResultToCombine<Then>;
/**
 * The elements collection of a step-switch — either a plain array or a conditional that produces an array.
 */
type PixiVNJsonStepSwitchElementsType<Then> = PixiVNJsonStepSwitchElementType<Then>[] | PixiVNJsonConditionalStatements<Then[]>;
/**
 * Picks one element at random each time the step is visited.
 */
interface PixiVNJsonRandom<Then> {
    type: "stepswitch";
    choiceType: "random";
    /**
     * The pool of elements to choose from randomly.
     */
    elements: PixiVNJsonStepSwitchElementsType<Then>;
}
/**
 * Picks elements in a random order, advancing through the list across visits (no repeats until exhausted).
 */
interface PixiVNJsonSequentialRandom<Then> {
    type: "stepswitch";
    choiceType: "sequentialrandom";
    /**
     * The pool of elements to iterate through in randomised order.
     */
    elements: PixiVNJsonStepSwitchElementsType<Then>;
    /**
     * When the sequential ends, what should be the value? If undefined, it will return undefined.
     * If "lastItem", it will return the last item in the array.
     */
    end: undefined | "lastItem";
    /**
     * The subId is used for managing nested switches
     */
    nestedId?: string;
}
/**
 * Advances through the elements list one by one on each visit (in order).
 */
interface PixiVNJsonSequential<Then> {
    type: "stepswitch";
    choiceType: "sequential";
    /**
     * The ordered list of elements to iterate through.
     */
    elements: PixiVNJsonStepSwitchElementsType<Then>;
    /**
     * When the sequential ends, what should be the value? If undefined, it will return undefined.
     * If "lastItem", it will return the last item in the array.
     */
    end: undefined | "lastItem";
    /**
     * The subId is used for managing nested switches
     */
    nestedId?: string;
}
/**
 * Loops through the elements list indefinitely, cycling back to the first element after the last.
 */
interface PixiVNJsonLoop<Then> {
    type: "stepswitch";
    choiceType: "loop";
    /**
     * The list of elements to cycle through.
     */
    elements: PixiVNJsonStepSwitchElementsType<Then>;
    /**
     * The subId is used for managing nested switches
     */
    nestedId?: string;
}
/**
 * A step-switch selects one element from a list using a defined strategy (random, sequential, loop, or sequential-random).
 */
type PixiVNJsonStepSwitch<Then> = PixiVNJsonRandom<Then> | PixiVNJsonSequential<Then> | PixiVNJsonLoop<Then> | PixiVNJsonSequentialRandom<Then>;

/**
 * This element is used in case a {@link PixiVNJsonConditionalStatements} gives a result that must be combined with another calculated through other {@link PixiVNJsonConditionalStatements}.
 * in case this possibility is not managed, it will be taken into consideration {@link PixiVNJsonConditionalResultToCombine.firstItem}
 */
type PixiVNJsonConditionalResultToCombine<T> = {
    type: "resulttocombine";
    /**
     * Defines how the two results are combined:
     * - `"cross"` — cartesian product / pairwise combination of both results
     * - `"union"` — concatenation / merge of both results into a single collection
     */
    combine: "cross" | "union";
    /**
     * The first (primary) result item, used as a fallback if the second conditional produces no result.
     */
    firstItem?: T;
    /**
     * The second conditional item(s) whose result will be combined with {@link firstItem}.
     */
    secondConditionalItem?: PixiVNJsonStepSwitchElementType<T>[];
};

/**
 * A conditional statement that evaluates to a value of type `Then`.
 * It can be either:
 * - a {@link PixiVNJsonStepSwitch} — selects a result from a list based on a strategy (random, sequential, loop)
 * - a {@link PixiVNJsonIfElse} — evaluates a condition and returns the matching branch result,
 *   which may itself be another conditional or a {@link PixiVNJsonConditionalResultToCombine}
 */
type PixiVNJsonConditionalStatements<Then> = PixiVNJsonStepSwitch<Then> | PixiVNJsonIfElse<Then | PixiVNJsonConditionalStatements<Then> | PixiVNJsonConditionalResultToCombine<Then>>;

/**
 * Retrieves a value from the persistent storage, flag storage, or temporary storage.
 */
type PixiVNJsonStorageGet = {
    type: "value";
    storageOperationType: "get";
    /**
     * Key of the storage
     */
    key: string;
    /**
     * Type of the storage, if it is a flagStorage or a storage.
     * If it is a flagStorage, the value will be get with the function {@link getFlag}
     */
    storageType: "storage" | "flagStorage" | "tempstorage";
};
type PixiVNJsonParamGet = {
    type: "value";
    storageOperationType: "get";
    /**
     * Index of the parameter in the params array.
     */
    key: number;
    storageType: "params";
};
/**
 * Retrieves the number of times a label has been opened.
 */
type PixiVNJsonLabelGet = {
    type: "value";
    storageOperationType: "get";
    /**
     * Id of the label
     */
    label: string;
    /**
     * If it is a label, the value will be get with the function {@link narration.getTimesLabelOpened}
     */
    storageType: "label";
};
/**
 * Retrieves the number of times a specific choice has been selected.
 */
type PixiVNJsonChoiceGet = {
    type: "value";
    storageOperationType: "get";
    /**
     * index of the choice
     */
    index: number;
    /**
     * If it is a choice, the value will be get with the function {@link narration.getTimesChoiceOpened}
     */
    storageType: "choice";
};
/**
 * Retrieves a value from the logic/arithmetic layer (result of a computation or condition).
 */
type PixiVNJsonLogicGet = {
    type: "value";
    storageOperationType: "get";
    /**
     * The arithmetic or conditional operation whose result is the retrieved value.
     */
    operation: PixiVNJsonArithmeticOperations | PixiVNJsonConditions;
    storageType: "logic";
};
/**
 * Union of all "get value" operations — reads from storage, params, labels, choices, or a logic expression.
 */
type PixiVNJsonValueGet = PixiVNJsonStorageGet | PixiVNJsonParamGet | PixiVNJsonLabelGet | PixiVNJsonChoiceGet | PixiVNJsonLogicGet | PixiVNJsonFunction;
/**
 * Invokes a named function and returns its result.
 * Functions are registered in the Pixi'VN runtime and can receive typed arguments.
 */
type PixiVNJsonFunction = {
    type: "function";
    /**
     * The name of the registered function to call.
     */
    functionName: string;
    /**
     * Arguments to pass to the function. Each argument can be a condition, a raw value,
     * a value-get operation, or an arithmetic expression.
     */
    args: (PixiVNJsonConditions | StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations)[];
};
/**
 * Sets a value in either the persistent storage or the temporary (session) storage.
 */
type PixiVNJsonOnlyStorageSet = {
    type: "value";
    storageOperationType: "set";
    /**
     * Key of the storage
     */
    key: string;
    /**
     * Value to be set in the storage
     */
    value: StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations | PixiVNJsonConditionalStatements<StorageElementType>;
    /**
     * Type of the storage, if it is a flagStorage or a storage.
     */
    storageType: "storage" | "tempstorage";
};
/**
 * Sets a positional parameter value in the params temporary storage.
 */
type PixiVNJsonOnlyParamSet = {
    type: "value";
    storageOperationType: "set";
    /**
     * Index of the parameter in the params array to set.
     */
    key: number;
    /**
     * Value to be set at the given param index.
     */
    value: StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations | PixiVNJsonConditionalStatements<StorageElementType>;
    storageType: "params";
};
/**
 * Sets a boolean flag in the flag storage.
 * Flag storage is a dedicated boolean key-value store queried with {@link getFlag}.
 */
type PixiVNJsonFlagSet = {
    type: "value";
    storageOperationType: "set";
    /**
     * Key of the storage
     */
    key: string;
    /**
     * Value to be set in the storage
     */
    value: boolean;
    /**
     * Type of the storage, if it is a flagStorage or a storage.
     */
    storageType: "flagStorage";
};
/**
 * Union of all "set value" operations — writes to storage, flag storage, or params.
 */
type PixiVNJsonValueSet = PixiVNJsonOnlyStorageSet | PixiVNJsonFlagSet | PixiVNJsonOnlyParamSet;

/**
 * Binary arithmetic operation between two values (left OP right).
 */
interface PixiVNJsonArithmeticOperationsArithmetic {
    type: "arithmetic";
    /**
     * Left value of the arithmetic operation
     */
    leftValue: StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations | PixiVNJsonConditionalStatements<StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations>;
    /**
     * Right value of the arithmetic operation
     */
    rightValue: StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations | PixiVNJsonConditionalStatements<StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations>;
    /**
     * Operator of the arithmetic operation:
     * - `"*"` multiplication
     * - `"/"` division
     * - `"+"` addition (concatenation for strings and arrays)
     * - `"-"` subtraction (removal of elements for arrays)
     * - `"%"` modulo
     * - `"POW"` exponentiation
     * - `"RANDOM"` random integer between leftValue and rightValue (inclusive)
     * - `"INTERSECTION"` intersection of two arrays (only elements present in both arrays are included in the result)
     */
    operator: "*" | "/" | "+" | "-" | "%" | "POW" | "RANDOM" | "INTERSECTION";
}
/**
 * Unary arithmetic operation applied to a single value (e.g. INT, FLOOR, FLOAT).
 */
interface PixiVNJsonArithmeticOperationsArithmeticSingle {
    type: "arithmeticsingle";
    /**
     * Left value of the arithmetic operation
     */
    leftValue: StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations | PixiVNJsonConditionalStatements<StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations>;
    /**
     * Operator of the arithmetic operation:
     * - `"INT"` truncates the value to an integer (removes the decimal part)
     * - `"FLOOR"` rounds down to the nearest integer
     * - `"FLOAT"` converts the value to a floating-point number
     */
    operator: "INT" | "FLOOR" | "FLOAT";
}
/**
 * Arithmetic operations for the PixiVNJson
 */
type PixiVNJsonArithmeticOperations = PixiVNJsonArithmeticOperationsArithmeticSingle | PixiVNJsonArithmeticOperationsArithmetic;

/**
 * Combines multiple conditions with a logical AND or OR.
 */
type PixiVNJsonUnionConditionAndOr = {
    type: "union";
    /**
     * The list of conditions to combine.
     */
    conditions: PixiVNJsonConditions[];
    /**
     * - `"and"` — all conditions must be true
     * - `"or"` — at least one condition must be true
     */
    unionType: "and" | "or";
};
/**
 * Negates a single condition with a logical NOT.
 */
type PixiVNJsonUnionConditionNot = {
    type: "union";
    /**
     * The condition to negate.
     */
    condition: PixiVNJsonConditions;
    unionType: "not";
};
/**
 * Union of AND/OR and NOT logical operators over conditions.
 */
type PixiVNJsonUnionCondition = PixiVNJsonUnionConditionAndOr | PixiVNJsonUnionConditionNot;

/**
 * Supported comparison operators.
 * - `"=="` equal
 * - `"!="` not equal
 * - `"<"` less than
 * - `"<="` less than or equal
 * - `">"` greater than
 * - `">="` greater than or equal
 * - `"CONTAINS"` checks whether the left string/array contains the right value, if left and right are arrays, checks if all items in right are included in left
 */
type PixiVNJsonComparationOperatorsType = "==" | "!=" | "<" | "<=" | ">" | ">=" | "CONTAINS";
/**
 * Comparation for PixiVNJson.
 * In this comparation, the values to be converted to string and compared.
 */
type PixiVNJsonComparation = {
    type: "compare";
    /**
     * Left value of the comparation
     */
    leftValue: StorageElementType | PixiVNJsonValueGet | PixiVNJsonConditions;
    /**
     * Right value of the comparation
     */
    rightValue: StorageElementType | PixiVNJsonValueGet | PixiVNJsonConditions;
    /**
     * Operator of the comparation
     */
    operator: PixiVNJsonComparationOperatorsType;
};
/**
 * A plain value condition — truthy/falsy evaluation of a raw value or a value-get result.
 */
type PixiVNJsonValueCondition = StorageElementType | PixiVNJsonValueGet;
/**
 * Union of all condition types supported by PixiVNJson:
 * - {@link PixiVNJsonComparation} — binary comparison between two values
 * - {@link PixiVNJsonValueCondition} — truthy/falsy check on a plain value
 * - {@link PixiVNJsonUnionCondition} — logical AND, OR, or NOT of other conditions
 * - {@link PixiVNJsonArithmeticOperations} — arithmetic result used as a boolean (non-zero = true)
 */
type PixiVNJsonConditions = PixiVNJsonComparation | PixiVNJsonValueCondition | PixiVNJsonUnionCondition | PixiVNJsonArithmeticOperations;

/**
 * If-Else condition for PixiVNJson
 */
interface PixiVNJsonIfElse<Then> {
    type: "ifelse";
    /**
     * The list of conditions to be checked.
     *
     * if is a {@link StorageElementType} or a {@link PixiVNJsonValueGet}:
     * - if is a array or object, the condition is true if not empty
     * - if is a string, the condition is true if not empty
     * - if is a number, the condition is true if not zero
     * - if is a boolean, the condition is true if true
     * - if is null or undefined, the condition is false
     */
    condition: PixiVNJsonConditions;
    /**
     * The value to be returned if the condition is true.
     */
    then: Then | PixiVNJsonIfElse<Then>;
    /**
     * The value to be returned if the condition is false.
     */
    else?: Then | PixiVNJsonIfElse<Then>;
}

/**
 * Animates one or more canvas elements simultaneously using keyframe-based animation.
 */
type PixiVNJsonAnimateBase<T extends CanvasBaseInterface<any>> = {
    type: "animate";
    /**
     * Alias (or list of aliases) of the canvas elements to animate.
     */
    alias: string | string[];
    /**
     * The keyframes that define the animation values over time.
     */
    keyframes: KeyframesType<T>;
    /**
     * Additional options controlling the animation (duration, easing, repeat, etc.).
     */
    options?: AnimationOptions;
    /**
     * Pixi.js update priority for this animation ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Animates a canvas element using a sequence of segments (timeline-based animation).
 */
type PixiVNJsonAnimateSequence<T extends CanvasBaseInterface<any>> = {
    type: "animate-sequence";
    /**
     * Alias of the canvas element to animate.
     */
    alias: string;
    /**
     * Ordered list of animation segments, each optionally including a transition.
     */
    sequence: (ObjectSegment<T> | ObjectSegmentWithTransition<T>)[];
    /**
     * Additional options controlling the sequence playback.
     */
    options?: SequenceOptions;
    /**
     * Pixi.js update priority for this animation ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Union of all canvas animation operations — keyframe-based or sequence-based.
 */
type PixiVNJsonCanvasAnimate<T extends CanvasBaseInterface<any> = ImageSprite> = PixiVNJsonAnimateBase<T> | PixiVNJsonAnimateSequence<T>;

/**
 * Applies a shake effect to a canvas element.
 */
type PixiVNJsonEffectShake = {
    type: "shake";
    /**
     * Alias of the canvas element to apply the shake effect to.
     */
    alias: string;
    /**
     * Configuration properties for the shake effect (amplitude, duration, etc.).
     */
    props: ShakeEffectProps;
    /**
     * Pixi.js update priority for the effect ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Union of all canvas visual effects.
 */
type PixiVNJsonCanvasEffect = PixiVNJsonEffectShake;

/**
 * Cross-dissolve transition — blends the element in or out by gradually changing its opacity.
 */
type DissolveTransition = {
    type: "dissolve";
    /**
     * Configuration options for the dissolve transition.
     */
    props?: ShowWithDissolveTransitionProps;
    /**
     * Pixi.js update priority for the transition ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Fade transition — fades the element in or out by animating its alpha value.
 */
type FadeTransition = {
    type: "fade";
    /**
     * Configuration options for the fade transition.
     */
    props?: ShowWithFadeTransitionProps;
    /**
     * Pixi.js update priority for the transition ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Move-in / Move-out transition — slides the element into or out of the viewport.
 */
type MoveInOutTransition = {
    type: "movein" | "moveout";
    /**
     * Configuration options for the move transition (direction, duration, easing, etc.).
     */
    props?: MoveInOutProps;
    /**
     * Pixi.js update priority for the transition ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Zoom-in / Zoom-out transition — scales the element into or out of view.
 */
type ZoomInOutTransition = {
    type: "zoomin" | "zoomout";
    /**
     * Configuration options for the zoom transition (scale, duration, easing, etc.).
     */
    props?: ZoomInOutProps;
    /**
     * Pixi.js update priority for the transition ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Push-in / Push-out transition — pushes the element onto or off the viewport, displacing the current content.
 */
type PushInOutTransition = {
    type: "pushin" | "pushout";
    /**
     * Configuration options for the push transition (direction, duration, easing, etc.).
     */
    props?: PushInOutProps;
    /**
     * Pixi.js update priority for the transition ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Union of all supported canvas media transitions.
 */
type PixiVNJsonMediaTransiotions = DissolveTransition | FadeTransition | MoveInOutTransition | ZoomInOutTransition | PushInOutTransition;

/**
 * Shows an image or video asset on the canvas.
 */
type PixiVNJsonCanvasImageVideoShow = {
    type: "image" | "video";
    operationType: "show";
    /**
     * Unique identifier (alias) used to reference this element on the canvas.
     */
    alias: string;
    /**
     * The url of the image or video.
     * If the url is not provided, the url will be set to the alias.
     */
    url?: string;
    /**
     * Display options (position, scale, alpha, etc.) for the image or video sprite.
     */
    props?: ImageSpriteOptions;
    /**
     * Optional transition effect applied when the element appears on screen.
     */
    transition?: PixiVNJsonMediaTransiotions;
};
/**
 * Shows an image container (a group of layered images) on the canvas.
 */
type PixiVNJsonCanvasImageContainerShow = {
    type: "imagecontainer";
    operationType: "show";
    /**
     * Unique identifier (alias) used to reference this element on the canvas.
     */
    alias: string;
    /**
     * The ordered list of image URLs that compose the container layers.
     */
    urls: string[];
    /**
     * Display options for the image container.
     */
    props?: ImageContainerOptions<ImageSprite>;
    /**
     * Optional transition effect applied when the element appears on screen.
     */
    transition?: PixiVNJsonMediaTransiotions;
};
/**
 * Shows a text element on the canvas.
 */
type PixiVNJsonCanvasTextShow = {
    type: "text";
    operationType: "show";
    /**
     * Unique identifier (alias) used to reference this element on the canvas.
     */
    alias: string;
    /**
     * The string content to display.
     */
    text: string;
    /**
     * Display options (font, style, position, etc.) for the text element.
     */
    props?: TextOptions;
    /**
     * Optional transition effect applied when the element appears on screen.
     */
    transition?: PixiVNJsonMediaTransiotions;
};
/**
 * Edits the properties of an existing image sprite on the canvas.
 */
type PixiVNJsonImageEdit = {
    type: "image";
    operationType: "edit";
    /**
     * Alias of the canvas element to edit.
     */
    alias: string;
    /**
     * Partial memory/state properties to update on the image sprite.
     */
    props?: Partial<ImageSpriteMemory>;
};
/**
 * Edits the properties of an existing video sprite on the canvas.
 */
type PixiVNJsonVideoEdit = {
    type: "video";
    operationType: "edit";
    /**
     * Alias of the canvas element to edit.
     */
    alias: string;
    /**
     * Partial memory/state properties to update on the video sprite.
     */
    props?: Partial<VideoSpriteMemory>;
};
/**
 * Edits the properties of an existing image container on the canvas.
 */
type PixiVNJsonImageContainerEdit = {
    type: "imagecontainer";
    operationType: "edit";
    /**
     * Alias of the canvas element to edit.
     */
    alias: string;
    /**
     * Partial memory/state properties to update on the image container.
     */
    props?: Partial<ImageContainerMemory>;
};
/**
 * Edits the properties of an existing text element on the canvas.
 */
type PixiVNJsonTextEdit = {
    type: "text";
    operationType: "edit";
    /**
     * Alias of the canvas element to edit.
     */
    alias: string;
    /**
     * Partial memory/state properties to update on the text element.
     */
    props?: Partial<TextMemory>;
};
/**
 * Edits the properties of an unknown/generic canvas element.
 * Use this when the specific element type is not one of the built-in kinds.
 */
type PixiVNJsonUnknownEdit<T extends ContainerOptions<any>> = {
    type: "canvaselement";
    operationType: "edit";
    /**
     * Alias of the canvas element to edit.
     */
    alias: string;
    /**
     * Partial options/properties to update on the canvas element.
     */
    props?: Partial<T>;
};
/**
 * Removes a canvas element from the stage, optionally with a transition.
 */
type PixiVNJsonCanvasRemove = {
    type: "image" | "video" | "imagecontainer" | "canvaselement" | "text";
    operationType: "remove";
    /**
     * Alias of the canvas element to remove.
     */
    alias: string;
    /**
     * Optional transition effect applied while the element disappears.
     */
    transition?: PixiVNJsonMediaTransiotions;
};
/**
 * Pauses or resumes playback of a video sprite on the canvas.
 */
type PixiVNJsonVideoPauseResume = {
    type: "video";
    operationType: "pause" | "resume";
    /**
     * Alias of the video element to pause or resume.
     */
    alias: string;
};
/**
 * Loads or lazy-loads asset bundles or individual assets into memory.
 */
type PixiVNJsonAssetsLoad = {
    type: "assets" | "bundle";
    operationType: "load" | "lazyload";
    /**
     * List of asset aliases (or bundle names) to load.
     */
    aliases: string[];
};
type PixiVNJsonCanvasShow = PixiVNJsonCanvasImageContainerShow | PixiVNJsonCanvasImageVideoShow | PixiVNJsonCanvasTextShow;
/**
 * Union of all canvas-element edit operations.
 */
type PixiVNJsonCanvasEdit = PixiVNJsonImageEdit | PixiVNJsonVideoEdit | PixiVNJsonImageContainerEdit | PixiVNJsonTextEdit | PixiVNJsonUnknownEdit<ImageSpriteMemory | VideoSpriteMemory | ContainerMemory | TextMemory>;
/**
 * Union of all canvas operations — show, edit, remove, animate, apply effects, and asset loading.
 */
type PixiVNJsonCanvas = PixiVNJsonCanvasShow | PixiVNJsonCanvasEdit | PixiVNJsonCanvasRemove | PixiVNJsonVideoPauseResume | PixiVNJsonAssetsLoad | PixiVNJsonCanvasAnimate | PixiVNJsonCanvasEffect;

/**
 * Requests user input during the narrative.
 * When this operation is encountered, the engine pauses and waits for the player to provide a value.
 */
type PixiVNJsonInputRequest = {
    type: "input";
    operationType: "request";
    /**
     * The expected value type for the input (e.g. `"string"`, `"number"`, `"boolean"`).
     * Used by the engine to validate or cast the player's answer.
     */
    valueType?: string;
    /**
     * A default value that will be used if the player does not provide any input.
     */
    defaultValue?: any;
};
/**
 * Clears (resets) the current dialogue state.
 * This is typically used to wipe any displayed text before showing new content.
 */
type PixiVNJsonDialogue = {
    type: "dialogue";
    operationType: "clean";
};
/**
 * Narration operation — either a dialogue clear or a user-input request.
 */
type PixiVNJsonNarration = PixiVNJsonDialogue | PixiVNJsonInputRequest;

/**
 * Starts playback of a sound asset.
 */
type PixiVNJsonSoundPlay = {
    type: "sound";
    operationType: "play";
    /**
     * Unique identifier (alias) used to reference this sound.
     */
    alias: string;
    /**
     * URL of the sound file. If omitted, the alias is used as the URL.
     */
    url?: string;
    /**
     * Playback options such as volume, loop, channel, and start offset.
     */
    props?: SoundPlayOptionsWithChannel;
};
/**
 * Stops a playing sound and removes it from the audio context.
 */
type PixiVNJsonSoundRemove = {
    type: "sound";
    operationType: "stop";
    /**
     * Alias of the sound to stop.
     */
    alias: string;
};
/**
 * Pauses or resumes a sound, a channel, or all audio.
 */
type PixiVNJsonSoundPauseResume = {
    type: "sound" | "channel";
    operationType: "pause" | "resume";
    /**
     * Alias of the sound or channel to pause/resume.
     */
    alias: string;
} | {
    type: "all";
    operationType: "pause" | "resume" | "stop";
};
/**
 * Edits the properties of a currently playing sound (volume, speed, muted, loop, etc.).
 */
type PixiVNJsonSoundEdit = {
    type: "sound";
    operationType: "edit";
    /**
     * Alias of the sound to edit.
     */
    alias: string;
    /**
     * Partial set of properties to apply to the sound.
     */
    props: Partial<Pick<MediaInterface, "speed" | "muted" | "loop" | "paused"> & Pick<SoundPlayOptionsWithChannel, "volume">>;
};
/**
 * Union of all sound operations — play, stop, pause/resume, and edit.
 */
type PixiVNJsonSound = PixiVNJsonSoundPlay | PixiVNJsonSoundRemove | PixiVNJsonSoundPauseResume | PixiVNJsonSoundEdit;

/**
 * An operation string that holds a list of string/value fragments to be concatenated at runtime.
 * Used internally to represent string interpolation expressions before they are fully resolved.
 */
type PixiVNJsonOperationString = {
    type: "operationtoconvert";
    /**
     * The ordered list of string fragments and/or value-get expressions to concatenate.
     */
    values: (string | PixiVNJsonValueGet | PixiVNJsonConditionalStatements<string | PixiVNJsonValueGet>)[];
};
/**
 * A single resolved operation — a value set, canvas operation, sound operation,
 * narration operation, or function call — optionally annotated with an origin string.
 */
type PixiVNJsonOperation = (PixiVNJsonValueSet | PixiVNJsonCanvas | PixiVNJsonSound | PixiVNJsonNarration | PixiVNJsonFunction) & {
    /**
     * This value is used by the system to know where this operation is from, for example, if is generated from a string operation.
     */
    $origin?: string;
};
/**
 * A conditional operation — either a plain operation, an if-else that resolves to one,
 * or an operation-string (string interpolation expression).
 */
type PixiVNJsonConditionalOperation = PixiVNJsonOperation | PixiVNJsonIfElse<PixiVNJsonOperation> | PixiVNJsonOperationString;

/**
 * A player-presentable choice in a menu.
 */
type PixiVNJsonChoice = {
    /**
     * The text to be displayed.
     */
    text: PixiVNJsonDialogText;
    /**
     * The label id to be opened.
     */
    label: string;
    /**
     * Label opening mode
     */
    type: LabelRunModeType;
    /**
     * The properties to be passed to the label.
     */
    props: StorageObjectType;
    /**
     * 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;
};
/**
 * A list of choices (possibly conditional) that are shown to the player as a menu.
 */
type PixiVNJsonChoices = (PixiVNJsonChoice | PixiVNJsonConditionalStatements<PixiVNJsonChoice>)[];
/**
 * The text content of a dialogue line.
 * Can be a plain string, a dynamic value-get, a conditional expression, or an array of any of these
 * (which will be concatenated into a single string at runtime).
 */
type PixiVNJsonDialogText = string | PixiVNJsonValueGet | PixiVNJsonConditionalStatements<string | PixiVNJsonValueGet | string[]> | (string | PixiVNJsonValueGet | PixiVNJsonConditionalStatements<string | PixiVNJsonValueGet | string[]>)[];
/**
 * A dialogue line, optionally attributed to a character.
 * When a plain `Text` value is used, no character attribution is included.
 */
type PixiVNJsonDialog<Text = string> = {
    /**
     * The character id that will speak.
     */
    character: string;
    /**
     * The text to be displayed.
     */
    text: Text;
} | Text;
/**
 * Describes a label that should be opened (called or jumped to) during a step.
 */
type PixiVNJsonLabelToOpen<T extends {} = object> = {
    /**
     * The id of the label to open.
     */
    label: string | PixiVNJsonValueGet;
    /**
     * Label opening mode
     */
    type: LabelRunModeType;
    /**
     * The properties to be passed to the label. if you don't want to pass a object, but a list of parameters, you can use the {@link PixiVNJsonLabelToOpen.params} attribute.
     */
    props?: StepLabelPropsType<T>;
    /**
     * **It is not recommended to use it, use it only if necessary**. The parameters to be passed to the label. If you want to pass an object, use the {@link PixiVNJsonLabelToOpen.props} attribute.
     * "params" attribute will be stored in the temp storage with the key: {@link PIXIVNJSON_PARAM_ID} + ({@link narration.openedLabels.length} - 1).
     */
    params?: unknown[];
};
/**
 * Steps of a label.
 * Order of operations:
 * 1. run all {@link PixiVNJsonLabelStep.operations}
 * 2. set {@link PixiVNJsonLabelStep.choices}, {@link PixiVNJsonLabelStep.dialogue}, {@link PixiVNJsonLabelStep.glueEnabled}
 * 3. open {@link PixiVNJsonLabelStep.labelToOpen}
 * 4. go to next step if {@link PixiVNJsonLabelStep.goNextStep} is true
 * 5. end the label if {@link PixiVNJsonLabelStep.end} is "label_end"
 */
type PixiVNJsonLabelStep = {
    /**
     * Operations to execute at the start of this step (storage writes, canvas updates, sound, etc.).
     */
    operations?: PixiVNJsonConditionalOperation[];
    /**
     * Variable used to display a choice menu.
     */
    choices?: PixiVNJsonChoices | PixiVNJsonConditionalStatements<PixiVNJsonChoices>;
    /**
     * Variable used to display a dialog.
     */
    dialogue?: PixiVNJsonDialog<PixiVNJsonDialogText> | PixiVNJsonConditionalStatements<PixiVNJsonDialog<PixiVNJsonDialogText>>;
    /**
     * 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
     */
    glueEnabled?: boolean | PixiVNJsonConditionalStatements<boolean>;
    /**
     * Variable used to open a label.
     */
    labelToOpen?: PixiVNJsonLabelToOpen | PixiVNJsonConditionalStatements<PixiVNJsonLabelToOpen> | (PixiVNJsonLabelToOpen | PixiVNJsonConditionalStatements<PixiVNJsonLabelToOpen>)[];
    /**
     * If is true, the next step will be executed automatically.
     */
    goNextStep?: boolean | PixiVNJsonConditionalStatements<boolean>;
    /**
     * Variable used to end some elements of the narrative.
     * - game_end: ends the game
     * - label_end: ends the label
     */
    end?: "game_end" | "label_end" | PixiVNJsonConditionalStatements<"game_end" | "label_end">;
    /**
     * If set, this step is replaced by the result of evaluating the given conditional statement.
     * Allows an entire step to be chosen at runtime based on a condition or step-switch strategy.
     */
    conditionalStep?: PixiVNJsonConditionalStatements<PixiVNJsonLabelStep | PixiVNJsonLabelStep[]>;
};

/**
 * Manages the translation pipeline for all text displayed by pixi-vn-json.
 *
 * The pipeline applies three optional hooks in order:
 * 1. `beforeToTranslate` – pre-processes the key before translation.
 * 2. `translate` – the main translation function (identity by default).
 * 3. `afterToTranslate` – post-processes the translated string.
 *
 * Use {@link TranslatorManager.t} to translate a key or array of keys.
 */
declare class TranslatorManager {
    private static _beforeToTranslate;
    private static _translate;
    private static _afterToTranslate;
    /**
     * Translates a single key or an array of keys using the registered pipeline.
     * Returns the same type (`string` or `string[]`) as the input.
     *
     * @param key - The string key or array of string keys to translate.
     * @returns The translated string(s).
     */
    static t<T = string | string[]>(key: T): T;
    /**
     * Sets a hook that runs **before** the main translation function.
     * Useful for key normalization (e.g. trimming, lowercasing).
     */
    static set beforeToTranslate(value: (key: string) => string);
    /**
     * Sets the main translation function.
     * Defaults to an identity function (returns the key unchanged).
     *
     * @example
     * ```ts
     * translator.translate = (key) => i18n.t(key);
     * ```
     */
    static set translate(value: (key: string) => string);
    /** Returns the composed translation pipeline (before → translate → after). */
    static get translate(): (key: string) => string;
    /**
     * Sets a hook that runs **after** the main translation function.
     * Useful for post-processing translated strings (e.g. replacing placeholders).
     */
    static set afterToTranslate(value: (key: string) => string);
    private static addKey;
    private static getConditionalsThenElse;
    /**
     * Generates a JSON translation object from the provided labels.
     * @param labels The labels to translate.
     * @param json The JSON object to populate with translations.
     * @param options Options for translation, including default value handling.
     * @returns The populated JSON object with translations.
     */
    static generateJsonTranslation(labels: PixiVNJsonLabelStep[], json?: object, options?: {
        /**
         * Default value to use when a key is not found.
         * - "empty_string": Use an empty string as the default value.
         * - "copy_key": Use the key itself as the default value.
         * @default "copy_key"
         */
        defaultValue?: "empty_string" | "copy_key";
        operationStringConvert?: (value: string, step: PixiVNJsonLabelStep, props: StepLabelPropsType | {}) => Promise<PixiVNJsonOperation | undefined>;
    }): Promise<object>;
}

declare const translator: typeof TranslatorManager;

export { translator };