@drincs/pixi-vn-ink/dist/mapper.d.ts

Pixi'VN gives you the ability to write your own narrative using Ink

import { PixiVNJsonStepSwitch, PixiVNJson } from '@drincs/pixi-vn-json/schema';

/**
 * Generates an instance of a Choice. Its exact behaviour depends on its flags. It doesn't contain any text itself, since choice text is generated at runtime and added to the evaluation stack. When a ChoicePoint is encountered, it pops content off the evaluation stack according to its flags, which indicate which texts are needed.
 *
 * A ChoicePoint object's structure in JSON is:
 * ```json
 * {
 *     "*": "path.when.chosen",
 *     "flg": 18
 * }
 * ```
 * The path when chosen is the target path of a Container of content, and is assigned when calling ChooseChoiceIndex.
 */
type ChoicePoint = {
    "*": string;
    /**
     * The flg field is a bitfield of flags:
     * - 0x1 - Has condition?: Set if the story should pop a value from the evaluation stack in order to determine whether a choice instance should be created at all.
     * - 0x2 - Has start content? - According to square bracket notation, is there any leading content before any square brackets? If so, this content should be popped from the evaluation stack.
     * - 0x4 - Has choice-only content? - According to square bracket notation, is there any content between the square brackets? If so, this content should be popped from the evaluation stack.
     * - 0x8 - Is invisible default? - When this is enabled, the choice isn't provided to the game (isn't presented to the player), and instead is automatically followed if there are no other choices generated.
     * - 0x10 - Once only? - Defaults to true. This is the difference between the * and + choice bullets in ink. If once only (*), the choice is only displayed if its target container's read count is zero.
     */
    flg: number;
};

type ChoiceInfo = {
    s: RootParserItemType[];
};

type StandardDivert = {
    "->": string;
    var?: true;
    c?: boolean;
    /**
     * my property to store the parameters
     */
    params?: any[];
};
type DivertFunction = {
    "f()": string;
    c?: boolean;
};
type DivertTunnel = {
    "->t->": string;
    var?: true;
    c?: boolean;
    /**
     * my property to store the parameters
     */
    params?: any[];
};
type DivertExternalFunction = {
    "x()": string;
    exArgs: number;
    c?: boolean;
};
/**
 * https://github.com/inkle/ink/blob/master/Documentation/ink_JSON_runtime_format.md#divert
 *
 * Diverts can take the following forms:
 *
 * - {"->": "path.to.target"} - a standard divert to content at a particular path.
 * - {"->": "variableTarget", "var": true} - as above, except that var specifies that the target is the name of a variable containing a divert target value.
 * - {"f()": "path.to.func"} - a function-call, which is defined as a divert that pushes an element to the callstack. Note that it doesn't necessarily correspond directly to an ink function, since choices use them internally too.
 * - {"->t->": "path.tunnel"} - a tunnel, which works similarly to a function call by pushing an element to the callstack. The only difference is that the callstack is aware of the type of element that was pushed, for error checking.
 * - {"x()": "externalFuncName", "exArgs": 5} - an external (game-side) function call, that optionally takes the specified number of arguments.
 *
 * Additionally, a "c" property set to true indicates that the divert is conditional, and should therefore pop a value off the evaluation stack to determine whether the divert should actually happen.
 */
type Divert = StandardDivert | DivertFunction | DivertTunnel | DivertExternalFunction;

/**
 * Represented with a leading ^ to differentiate from other string-based objects. e.g. "^Hello world" is used in JSON to represent the text Hello world, and "^^ up there ^" would be the text ^ up there ^. No ^ is needed for a newline, so it's just "\n".
 */
type TextType = string;

type ContainerTypeN = {
    "#n": string;
};

/**
 * https://github.com/inkle/ink/blob/master/Documentation/ink_JSON_runtime_format.md#control-commands
 *
 * Control commands are special instructions to the text engine to perform various actions. They are all represented by a particular text string:
 *
 * - "ev" - Begin logical evaluation mode. In evaluation mode, objects that are encountered are added to an evaluation stack, rather than simply echoed into the main text output stream. As they're pushed onto the stack, they may be processed by other commands, functions, etc.
 * - "/ev" - End logical evaluation mode. Future objects will be appended to the output stream rather than to the evaluation stack.
 * - "out" - The topmost object on the evaluation stack is popped and appended to the output stream (main story output).
 * - "pop" - Pops a value from the evaluation stack, without appending to the output stream.
 * - "->->" and "~ret" pop the callstack - used for returning from a tunnel or function respectively. They are specified independently for error checking, since the callstack is aware of whether each element was pushed as a tunnel or function in the first place.
 * - "du" - Duplicate the topmost object on the evaluation stack. Useful since some commands consume objects on the evaluation stack.
 * - "str" - Begin string evaluation mode. Adds a marker to the output stream, and goes into content mode (from evaluation mode). Must have already been in evaluation mode when this is encountered. See below for explanation.
 * - "/str" - End string evaluation mode. All content after the previous Begin marker is concatenated together, removed from the output stream, and appended as a string value to the evaluation stack. Re-enters evaluation mode immediately afterwards.
 * - "nop" - No-operation. Does nothing, but is useful as an addressable piece of content to divert to.
 * - "choiceCnt" - Pushes an integer with the current number of choices to the evaluation stack.
 * - "turn" - Pushes an integer with the current turn number to the evaluation stack.
 * - "turns" - Pops from the evaluation stack, expecting to see a divert target for a knot, stitch, gather or choice. Pushes an integer with the number of turns since that target was last visited by the story engine.
 * - "visit" - Pushes an integer with the number of visits to the current container by the story engine.
 * - "seq" - Pops an integer, expected to be the number of elements in a sequence that's being entered. In return, it pushes an integer with the next sequence shuffle index to the evaluation stack. This shuffle index is derived from the number of elements in the sequence, the number of elements in it, and the story's random seed from when it was first begun.
 * - "thread" - Clones/starts a new thread, as used with the <- knot syntax in ink. This essentially clones the entire callstack, branching it.
 * - "done" - Tries to close/pop the active thread, otherwise marks the story flow safe to exit without a loose end warning.
 * - "end" - Ends the story flow immediately, closes all active threads, unwinds the callstack, and removes any choices that were previously created.
 */
type ControlCommands = "ev" | "/ev" | "out" | "pop" | "->->" | "~ret" | "du" | "str" | "/str" | "nop" | "choiceCnt" | "turn" | "turns" | "visit" | "seq" | "thread" | "done" | "end";

/**
 * https://github.com/inkle/ink/blob/master/Documentation/ink_JSON_runtime_format.md#native-functions
 *
 * These are mathematical and logical functions that pop 1 or 2 arguments from the evaluation stack, evaluate the result, and push the result back onto the evaluation stack. The following operators are supported:
 *
 * "+", "-", "/", "*", "%" (mod), "_" (unary negate), "==", ">", "<", ">=", "<=", "!=", "!" (unary 'not'), "&&", "||", "MIN", "MAX"
 *
 * Booleans are supported only in the C-style - i.e. as integers where non-zero is treated as "true" and zero as "false". The true result of a boolean operation is pushed to the evaluation stack as 1.
 */
type NativeFunctions = "+" | "-" | "/" | "*" | "%" | "_" | "==" | ">" | "<" | ">=" | "<=" | "!=" | "!" | "&&" | "||" | "MIN" | "MAX";

/**
 * https://github.com/inkle/ink/blob/master/Documentation/ink_JSON_runtime_format.md#read-count
 *
 * Obtain the read count of a particular named knot, stitch, choice or gather. Note that this is implemented as a Variable Reference with particular flag in the C# ink runtime.
 *
 * Example:
 *
 * {"CNT?": "the_hall.light_switch"} - gets the read count of the container at the given path. For example, it might be a stitch named light_switch in a knot called the_hall.
 */
type ReadCount = {
    "CNT?": string;
};

type VariableAssignmentVar = {
    "VAR=": any;
    re: true;
};
type VariableAssignmentTem = {
    "temp=": string;
};
/**
 * https://github.com/inkle/ink/blob/master/Documentation/ink_JSON_runtime_format.md#variable-assignment
 *
 * Pops a value from the evaluation stack, and assigns it to a named variable, either globally or locally (in a temp, or a passed parameter). The "re" property being set indicates that it's a re-assignment rather than a brand new declaration.
 *
 * Examples:
 * - {"VAR=": "money", "re": true} - Pop a value from the evaluation stack, and assign it to the already-declared global variable money.
 * - {"temp=": "x"} - Pop a value from the evaluation stack, and assign it to a newly declared temporary variable named x.
 */
type VariableAssignment = VariableAssignmentVar | VariableAssignmentTem;

/**
 * https://github.com/inkle/ink/blob/master/Documentation/ink_JSON_runtime_format.md#variable-reference
 *
 * Obtain the current value of a named variable, and push it to the evaluation stack.
 *
 * Example:
 *
 * {"VAR?": "danger"} - Get an existing global or temporary variable named danger and push its value to the evaluation stack.
 */
type VariableReference = {
    "VAR?": string;
};

type RootParserItemType = null | RootParserItemType[] | ChoiceInfo | ChoicePoint | ControlCommands | Divert | NativeFunctions | TextType | VariableAssignment | VariableReference | ReadCount | ContainerTypeN;

type InkRootType = {
    [labelId: string]: RootParserItemType[];
};

type InkStoryType = {
    inkVersion: number;
    listDefs: {};
    root: InkRootType[];
};

type MapperSharedType = {
    labelToRemove: string[];
    initialVarsToRemove: string[];
    functions: {
        name: string;
        args: number;
    }[];
    enums: {
        [key: string]: Record<string, number>;
    };
    externalSwitch?: PixiVNJsonStepSwitch<string>;
    preDialog: {
        [label: string]: {
            text: string;
            glue: boolean;
        };
    };
    du?: NativeFunctions | ReadCount;
    params?: object;
};

declare namespace InkMapper {
    function inkToJson(obj: InkStoryType, shared?: Partial<MapperSharedType>): PixiVNJson | undefined;
}

export { InkMapper };