diff --git a/devTools/sugarcube.d.ts b/devTools/sugarcube.d.ts
index ab02ab3683a558c1c23b60d8e8604270b04fe307..92a0d063ab9e2c1485d77c38018edd1610b91a74 100644
--- a/devTools/sugarcube.d.ts
+++ b/devTools/sugarcube.d.ts
@@ -1,1341 +1,1340 @@
-declare namespace SugarCubeLib {
-
- type navigationOverride = (passageName: string) => any;
- type saveObjectHander = (save: SaveObject) => void;
-
- type DisplayTaskFunction = (taskName: string) => void;
- type RenderTaskFunction = (content: HTMLElement, taskName: string) => void;
-
- export interface StringTMap<T> { [key: string]: T; };
-
- declare interface Config {
- audio: {
- pauseOnFadeToZero: boolean;
- preloadMetadata: boolean;
- };
- history: {
- controls: boolean;
- maxStates: number;
- };
- macros: {
- ifAssignmentError: boolean;
- maxLoopIterations: number;
- };
- navigation: {
- override: navigationOverride;
- };
- passages: {
- descriptions: any;
- /** Determines whether passage titles are combined with the story title, within the browser's/tab's titlebar, when
- * passages are displayed.
- * @default false
- */
- displayTitles: boolean;
- /**
- * Determines whether rendering passages have their leading/trailing newlines removed and all remaining sequences of
- * newlines replaced with single spaces before they're rendered. Equivalent to including the nobr special tag on
- * every passage.
- * @default false
- */
- nobr: boolean;
+declare global {
+ namespace SugarCubeLib {
+
+ type navigationOverride = (passageName: string) => any;
+ type saveObjectHander = (save: SaveObject) => void;
+
+ type DisplayTaskFunction = (taskName: string) => void;
+ type RenderTaskFunction = (content: HTMLElement, taskName: string) => void;
+
+ export interface StringTMap<T> { [key: string]: T; }
+
+ interface Config {
+ audio: {
+ pauseOnFadeToZero: boolean;
+ preloadMetadata: boolean;
+ };
+ history: {
+ controls: boolean;
+ maxStates: number;
+ };
+ macros: {
+ ifAssignmentError: boolean;
+ maxLoopIterations: number;
+ };
+ navigation: {
+ override: navigationOverride;
+ };
+ passages: {
+ descriptions: any;
+ /** Determines whether passage titles are combined with the story title, within the browser's/tab's titlebar, when
+ * passages are displayed.
+ * @default false
+ */
+ displayTitles: boolean;
+ /**
+ * Determines whether rendering passages have their leading/trailing newlines removed and all remaining sequences of
+ * newlines replaced with single spaces before they're rendered. Equivalent to including the nobr special tag on
+ * every passage.
+ * @default false
+ */
+ nobr: boolean;
+
+ /**
+ * Sets the title of the initial passage, the very first passage which will be displayed.
+ *
+ * @default Twine 2: none; Twine 1/Twee: "Start"
+ */
+ start: string;
+
+ /**
+ * Determines whether outgoing passage transitions are enabled. Valid values are the name of the property being
+ * animated, which causes the outgoing passage elements to be removed once that transition animation is complete,
+ * or an integer delay (in milliseconds), which causes the outgoing passage elements to be removed once the delay
+ * has expired.
+ */
+ transitionOut: string | number;
+ };
+
+ saves: {
+ /**
+ * Determines whether the autosave, if it exists, is automatically loaded upon story startup. Valid values are
+ * boolean true, which simply causes the autosave to be loaded, the string "prompt", which prompts the player via a
+ * dialog to load the autosave, or a function, which causes the autosave to be loaded if its return value is truthy.
+
+ NOTE: If the autosave cannot be loaded, for any reason, then the start passage is loaded instead.
+ * @since 2.0.0
+ */
+ autoload: boolean | string | Function;
+
+ /**
+ * Determines whether the autosave is created/updated when passages are displayed. Valid values are boolean true,
+ * which causes the autosave to be updated with every passage, a string, which causes the autosave to be updated for
+ * each passage with a matching tag, or an array of strings, which causes the autosave to be updated for each
+ * passage with at least one matching tag.
+ *
+ * NOTE: When setting the value to boolean true, you will likely also need to use the Config.saves.isAllowed
+ * property to disallow saving on the start passage. Or, if you use the start passage as real part of your story and
+ * allow the player to reenter it, rather than just as the initial landing/cover page, then you might wish to only
+ * disallow saving on the start passage the very first time it's displayed (at story startup).
+ * @since 2.0.0
+ */
+ autosave: boolean | string | string[];
+
+ /**
+ * Sets the story ID associated with saves.
+ * @default slugified story title
+ * @since 2.0.0
+ * @example
+ * Config.saves.id = "a-big-huge-story-part-1";
+ */
+ id: string;
+
+ /**
+ * Determines whether saving is allowed within the current context. The callback is invoked each time a save is
+ * requested. If its return value is false, the save is disallowed. If its return value is truthy, the save is
+ * allowed to continue unperturbed.
+ * @default undefined
+ * @since 2.0.0
+ * @example
+ * Config.saves.isAllowed = function () {
+ * // code
+ * };
+ */
+ isAllowed: Function;
+
+ /**
+ * Performs any required pre-processing before the save data is loaded. The callback is passed one parameter, the
+ * save object to be processed. If it encounters an unrecoverable problem during its processing, it may throw an
+ * exception containing an error message; the message will be displayed to the player and loading of the save will
+ * be terminated.
+ * @default undefined
+ * @since 2.0.0
+ * @example
+ * Config.saves.onLoad = function (save) {
+ * // code
+ * };
+ */
+ onLoad: saveObjectHander;
+
+ /**
+ * Performs any required post-processing before the save data is saved. The callback is passed one parameter, the
+ * save object to be processed.
+ *
+ * NOTE: See the save objects section of the Save API for information on the format of a save.
+ * @default undefined
+ * @since 2.0.0
+ * @example
+ * Config.saves.onSave = function (save) {
+ * // code
+ * };
+ */
+ onSave: saveObjectHander;
+
+ /**
+ * Sets the maximum number of available save slots.
+ * @default 8
+ * @since 2.0.0
+ * @example
+ * Config.saves.slots = 4;
+ */
+ slots: number;
+
+ /**
+ * Sets the version property of saves.
+ *
+ * NOTE: This completely optional property is only for developer use, it is ignored by SugarCube.
+ *
+ * @since 2.0.0
+ * @example
+ * // As an integer
+ * Config.saves.version = 3;
+ * @example
+ * // As a string
+ * Config.saves.version = "v3";
+ */
+ version: any;
+ };
+
+ ui: {
+ /**
+ * Determines whether the UI bar (sidebar) starts in the stowed (shut) state initially. Valid values are boolean
+ * true/false, which causes the UI bar to always/never start in the stowed state, or an integer, which causes the UI
+ * bar to start in the stowed state if the viewport width is less-than-or-equal-to the specified number of pixels.
+ *
+ * @since 2.11.0
+ *
+ * @example
+ * // As a boolean; always start stowed
+ * Config.ui.stowBarInitially = true;
+ *
+ * @example
+ * // As a boolean; never start stowed
+ * Config.ui.stowBarInitially = false;
+ *
+ * @example
+ * // As an integer; start stowed if the viewport is 800px or less
+ * Config.ui.stowBarInitially = 800;
+ */
+ stowBarInitially: boolean | number;
+
+ /**
+ * Determines whether certain elements within the UI bar are updated when passages are displayed. The affected
+ * elements are the story: banner, subtitle, author, caption, and menu.
+ *
+ * NOTE: SugarCube uses the story's title as the basis for the key used to store and load data used when playing the
+ * story and for saves. Because of this, the story title is not included in updates and it is strongly recommended
+ * that you do not add any kind of dynamic code to it.
+ *
+ * @default true
+ * @since 2.0.0
+ * @example
+ * // If you don't need those elements to update
+ * Config.ui.updateStoryElements = false;
+ */
+ updateStoryElements: boolean;
+ };
/**
- * Sets the title of the initial passage, the very first passage which will be displayed.
- *
- * @default Twine 2: none; Twine 1/Twee: "Start"
+ * Determines whether the link-visited class is added to internal passage links which go to previously visited
+ * passages — i.e. the passage already exists within the story history
+ * @default false
+ * NOTE You must provide your own styling for the link-visited class as none is provided by default.
+ * @since 2.0.0
+ * @example
+ * Config.addVisitedLinkClass = true;
+ * // An example style: (Twine 2: goes in Story Stylesheet; Twine 1/Twee: goes in a stylesheet-tagged passage)
+ * .link-visited {
+ * color: purple;
+ * }
*/
- start: string;
+ addVisitedLinkClass: boolean;
/**
- * Determines whether outgoing passage transitions are enabled. Valid values are the name of the property being
- * animated, which causes the outgoing passage elements to be removed once that transition animation is complete,
- * or an integer delay (in milliseconds), which causes the outgoing passage elements to be removed once the delay
- * has expired.
+ * Determines whether the output of the Wikifier is post-processed into more sane markup — i.e. where appropriate, it
+ * tries to transition the plethora of <br> elements into <p> elements.
+ * @default false
+ * @since 2.0.0
+ * @example
+ * Config.cleanupWikifierOutput = true;
*/
- transitionOut: string | number;
- };
+ cleanupWikifierOutput: boolean;
- saves: {
/**
- * Determines whether the autosave, if it exists, is automatically loaded upon story startup. Valid values are
- * boolean true, which simply causes the autosave to be loaded, the string "prompt", which prompts the player via a
- * dialog to load the autosave, or a function, which causes the autosave to be loaded if its return value is truthy.
-
- NOTE: If the autosave cannot be loaded, for any reason, then the start passage is loaded instead.
- * @since 2.0.0
+ * Indicates whether SugarCube is running in test mode, which enables debug views. See Test Mode for more information.
+ *
+ * NOTE: This property is automatically set based on whether you're using a testing mode in a Twine compiler — i.e. Test
+ * mode in Twine 2, Test Play From Here in Twine 1, or the test mode options (-t, --test) in Tweego. You may, however,
+ * forcibly enable it if you need to for some reason — e.g. if you're using another compiler, which doesn't offer a way
+ * to enable test mode.
+ *
+ * @default false
+ * @since 2.2.0
+ * @example
+ * // Forcibly enable test mode
+ * Config.debug = true;
+ *
+ * @example
+ * // Check if test mode is enabled in JavaScript
+ * if (Config.debug) {
+ * // do something debug related
+ * }
+ *
+ * @example
+ * // Check if test mode is enabled via the <<if>> macro
+ * <<if Config.debug>>
+ * // do something debug related
+ * <</if>>
*/
- autoload: boolean | string | Function;
+ debug: boolean;
/**
- * Determines whether the autosave is created/updated when passages are displayed. Valid values are boolean true,
- * which causes the autosave to be updated with every passage, a string, which causes the autosave to be updated for
- * each passage with a matching tag, or an array of strings, which causes the autosave to be updated for each
- * passage with at least one matching tag.
+ * Sets the integer delay (in milliseconds) before the loading screen is dismissed, once the document has signaled its
+ * readiness. Not generally necessary, however, some browsers render slower than others and may need a little extra time
+ * to get a media-heavy page done. This allows you to fine tune for those cases.
*
- * NOTE: When setting the value to boolean true, you will likely also need to use the Config.saves.isAllowed
- * property to disallow saving on the start passage. Or, if you use the start passage as real part of your story and
- * allow the player to reenter it, rather than just as the initial landing/cover page, then you might wish to only
- * disallow saving on the start passage the very first time it's displayed (at story startup).
+ * @default 0
* @since 2.0.0
+ *
+ * @example
+ * // Delay the dismissal of the loading screen by 2000ms (2s)
+ * Config.loadDelay = 2000;
*/
- autosave: boolean | string | string[];
+ loadDelay: number;
+ }
+ interface Dialog {
/**
- * Sets the story ID associated with saves.
- * @default slugified story title
+ * Adds WAI-ARIA-compatible mouse/keyboard event handlers to the target element(s) which open the dialog when
+ * activated.
+ * @param targets The DOM element(s) to attach the handler to—may be either an HTMLElement object, a jQuery object,
+ * or a jQuery-style selector set.
+ * @param options he options object; the currently understood properties are:
+ * top: Top y-coordinate of the dialog (default: 50; in pixels, but without the unit).
+ * opacity: Opacity of the overlay (default: 0.8).
+ * @param tartFn The function to execute at the start of Dialog.addClickHandler(). This is commonly used to setup
+ * the dialog.
+ * @param doneFn The function to execute at the end of Dialog.addClickHandler().
+ * @param closeFn The function to execute whenever the associated dialog is closed.
* @since 2.0.0
* @example
- * Config.saves.id = "a-big-huge-story-part-1";
+ * // Commonly used something like the following.
+ * Dialog.addClickHandler("#some-element", null, function () {
+ * Dialog.setup("My Dialog Title", "my-dialog-class");
+ * Dialog.wiki(Story.get("MyDialogContents").processText());
+ * });
*/
- id: string;
+ addClickHandler(targets: HTMLElement | string, options?: object,
+ tartFn?: () => void, doneFn?: () => void, closeFn?: () => void): void;
/**
- * Determines whether saving is allowed within the current context. The callback is invoked each time a save is
- * requested. If its return value is false, the save is disallowed. If its return value is truthy, the save is
- * allowed to continue unperturbed.
- * @default undefined
- * @since 2.0.0
+ * Appends the given content to the dialog's content area. Returns a reference to the Dialog object for chaining.
+ *
+ * NOTE: If your content contains any SugarCube markup, you'll need to use the Dialog.wiki() method instead.
+ * @param content The content to append. As this method is essentially a shortcut for jQuery(Dialog.body()).append
+ * (…), see jQuery's append() method for the range of valid content types.
+ * @since 2.9.0
* @example
- * Config.saves.isAllowed = function () {
- * // code
- * };
+ * Dialog.append("Cry 'Havoc!', and let slip the <em>ponies</em> of <strong>friendship</strong>.");
+ * Dialog.append( <some DOM nodes> );
*/
- isAllowed: Function;
+ append(content: string | string[]): Dialog;
/**
- * Performs any required pre-processing before the save data is loaded. The callback is passed one parameter, the
- * save object to be processed. If it encounters an unrecoverable problem during its processing, it may throw an
- * exception containing an error message; the message will be displayed to the player and loading of the save will
- * be terminated.
- * @default undefined
+ * Returns a reference to the dialog's content area
* @since 2.0.0
* @example
- * Config.saves.onLoad = function (save) {
- * // code
- * };
+ * jQuery(Dialog.body()).append("Cry 'Havoc!', and let slip the <em>ponies</em> of <strong>friendship</strong>.");
+ * jQuery(Dialog.body()).wiki("Cry 'Havoc!', and let slip the //ponies// of ''friendship''.");
*/
- onLoad: saveObjectHander;
+ body(): HTMLElement;
/**
- * Performs any required post-processing before the save data is saved. The callback is passed one parameter, the
- * save object to be processed.
- *
- * NOTE: See the save objects section of the Save API for information on the format of a save.
- * @default undefined
+ * Closes the dialog. Returns a reference to the Dialog object for chaining.
* @since 2.0.0
- * @example
- * Config.saves.onSave = function (save) {
- * // code
- * };
*/
- onSave: saveObjectHander;
+ close(): Dialog;
/**
- * Sets the maximum number of available save slots.
- * @default 8
+ * Returns whether the dialog is currently open.
+ * @param classNames the space-separated-list of classes to check for when determining the state of the dialog.
+ * Each of built-in dialogs contains a name-themed class which can be tested for in this manner—e.g. the Saves
+ * dialog contains the class saves.
* @since 2.0.0
* @example
- * Config.saves.slots = 4;
+ * if (Dialog.isOpen()) {
+ * // code to execute if the dialog is open...
+ * }
+ * @example
+ * if (Dialog.isOpen("saves")) {
+ * // code to execute if the Saves dialog is open
+ * }
*/
- slots: number;
+ isOpen(classNames?: string): boolean;
/**
- * Sets the version property of saves.
- *
- * NOTE: This completely optional property is only for developer use, it is ignored by SugarCube.
+ * Opens the dialog. Returns a reference to the Dialog object for chaining.
*
+ * NOTE: Call this only after populating the dialog with content.
+ * @param options The options object. @see addClickHandler() for more information.
+ * @param closeFn The function to execute whenever the dialog is closed.
* @since 2.0.0
- * @example
- * // As an integer
- * Config.saves.version = 3;
- * @example
- * // As a string
- * Config.saves.version = "v3";
*/
- version: any;
- };
+ open(options?: object, closeFn?: () => void): Dialog;
- ui: {
/**
- * Determines whether the UI bar (sidebar) starts in the stowed (shut) state initially. Valid values are boolean
- * true/false, which causes the UI bar to always/never start in the stowed state, or an integer, which causes the UI
- * bar to start in the stowed state if the viewport width is less-than-or-equal-to the specified number of pixels.
- *
- * @since 2.11.0
- *
+ * Prepares the dialog for use and returns a reference to its content area.
+ * @param title The title of the dialog.
+ * @param classNames The space-separated-list of classes to add to the dialog.
+ * @since 2.0.0
* @example
- * // As a boolean; always start stowed
- * Config.ui.stowBarInitially = true;
+ * // Basic example.
+ * Dialog.setup();
+ * Dialog.wiki("Blah //blah// ''blah''.");
+ * Dialog.open();
*
* @example
- * // As a boolean; never start stowed
- * Config.ui.stowBarInitially = false;
+ * // Adding a title to the dialog.
+ * Dialog.setup("Character Sheet");
+ * Dialog.wiki(Story.get("PC Sheet").processText());
+ * Dialog.open();
*
* @example
- * // As an integer; start stowed if the viewport is 800px or less
- * Config.ui.stowBarInitially = 800;
+ * // Adding a title and class to the dialog.
+ * Dialog.setup("Character Sheet", "charsheet");
+ * Dialog.wiki(Story.get("PC Sheet").processText());
+ * Dialog.open();
*/
- stowBarInitially: boolean | number;
+ setup(title?: string, classNames?: string): HTMLElement;
/**
- * Determines whether certain elements within the UI bar are updated when passages are displayed. The affected
- * elements are the story: banner, subtitle, author, caption, and menu.
- *
- * NOTE: SugarCube uses the story's title as the basis for the key used to store and load data used when playing the
- * story and for saves. Because of this, the story title is not included in updates and it is strongly recommended
- * that you do not add any kind of dynamic code to it.
+ * Renders the given markup and appends it to the dialog's content area. Returns a reference to the Dialog object
+ * for chaining.
*
- * @default true
- * @since 2.0.0
+ * NOTE: If your content consists of DOM nodes, you'll need to use the @see Dialog.append() method instead.
+ * @param wikiMarkup The markup to render.
+ * @since 2.9.0
* @example
- * // If you don't need those elements to update
- * Config.ui.updateStoryElements = false;
+ * Dialog.wiki("Cry 'Havoc!', and let slip the //ponies// of ''friendship''.");
*/
- updateStoryElements: boolean;
- };
-
- /**
- * Determines whether the link-visited class is added to internal passage links which go to previously visited
- * passages — i.e. the passage already exists within the story history
- * @default false
- * NOTE You must provide your own styling for the link-visited class as none is provided by default.
- * @since 2.0.0
- * @example
- * Config.addVisitedLinkClass = true;
- * // An example style: (Twine 2: goes in Story Stylesheet; Twine 1/Twee: goes in a stylesheet-tagged passage)
- * .link-visited {
- * color: purple;
- * }
- */
- addVisitedLinkClass: boolean;
-
- /**
- * Determines whether the output of the Wikifier is post-processed into more sane markup — i.e. where appropriate, it
- * tries to transition the plethora of <br> elements into <p> elements.
- * @default false
- * @since 2.0.0
- * @example
- * Config.cleanupWikifierOutput = true;
- */
- cleanupWikifierOutput: boolean;
-
- /**
- * Indicates whether SugarCube is running in test mode, which enables debug views. See Test Mode for more information.
- *
- * NOTE: This property is automatically set based on whether you're using a testing mode in a Twine compiler — i.e. Test
- * mode in Twine 2, Test Play From Here in Twine 1, or the test mode options (-t, --test) in Tweego. You may, however,
- * forcibly enable it if you need to for some reason — e.g. if you're using another compiler, which doesn't offer a way
- * to enable test mode.
- *
- * @default false
- * @since 2.2.0
- * @example
- * // Forcibly enable test mode
- * Config.debug = true;
- *
- * @example
- * // Check if test mode is enabled in JavaScript
- * if (Config.debug) {
- * // do something debug related
- * }
- *
- * @example
- * // Check if test mode is enabled via the <<if>> macro
- * <<if Config.debug>>
- * // do something debug related
- * <</if>>
- */
- debug: boolean;
-
- /**
- * Sets the integer delay (in milliseconds) before the loading screen is dismissed, once the document has signaled its
- * readiness. Not generally necessary, however, some browsers render slower than others and may need a little extra time
- * to get a media-heavy page done. This allows you to fine tune for those cases.
- *
- * @default 0
- * @since 2.0.0
- *
- * @example
- * // Delay the dismissal of the loading screen by 2000ms (2s)
- * Config.loadDelay = 2000;
- */
- loadDelay: number;
- };
-
- declare interface Dialog {
- /**
- * Adds WAI-ARIA-compatible mouse/keyboard event handlers to the target element(s) which open the dialog when
- * activated.
- * @param targets The DOM element(s) to attach the handler to—may be either an HTMLElement object, a jQuery object,
- * or a jQuery-style selector set.
- * @param options he options object; the currently understood properties are:
- * top: Top y-coordinate of the dialog (default: 50; in pixels, but without the unit).
- * opacity: Opacity of the overlay (default: 0.8).
- * @param tartFn The function to execute at the start of Dialog.addClickHandler(). This is commonly used to setup
- * the dialog.
- * @param doneFn The function to execute at the end of Dialog.addClickHandler().
- * @param closeFn The function to execute whenever the associated dialog is closed.
- * @since 2.0.0
- * @example
- * // Commonly used something like the following.
- * Dialog.addClickHandler("#some-element", null, function () {
- * Dialog.setup("My Dialog Title", "my-dialog-class");
- * Dialog.wiki(Story.get("MyDialogContents").processText());
- * });
- */
- addClickHandler(targets: HTMLElement | string, options?: object,
- tartFn?: () => void, doneFn?: () => void, closeFn?: () => void): void;
-
- /**
- * Appends the given content to the dialog's content area. Returns a reference to the Dialog object for chaining.
- *
- * NOTE: If your content contains any SugarCube markup, you'll need to use the Dialog.wiki() method instead.
- * @param content The content to append. As this method is essentially a shortcut for jQuery(Dialog.body()).append
- * (…), see jQuery's append() method for the range of valid content types.
- * @since 2.9.0
- * @example
- * Dialog.append("Cry 'Havoc!', and let slip the <em>ponies</em> of <strong>friendship</strong>.");
- * Dialog.append( <some DOM nodes> );
- */
- append(content: string | string[]): Dialog;
+ wiki(wikiMarkup: string): Dialog;
+ }
- /**
- * Returns a reference to the dialog's content area
- * @since 2.0.0
- * @example
- * jQuery(Dialog.body()).append("Cry 'Havoc!', and let slip the <em>ponies</em> of <strong>friendship</strong>.");
- * jQuery(Dialog.body()).wiki("Cry 'Havoc!', and let slip the //ponies// of ''friendship''.");
- */
- body(): HTMLElement;
+ interface Engine {
+ /**
+ * Returns a timestamp representing the last time Engine.play() was called.
+ * @since 2.0.0
+ */
+ lastPlay: number;
- /**
- * Closes the dialog. Returns a reference to the Dialog object for chaining.
- * @since 2.0.0
- */
- close(): Dialog;
+ /**
+ * Returns the current state of the engine ("idle", "playing", "rendering").
+ * States:
+ * "idle": The engine is idle, awaiting the triggering of passage navigation—the default state.
+ * "playing": Passage navigation has been triggered and a turn is being processed.
+ * "rendering": The incoming passage is being rendered and added to the page—takes place during turn processing,
+ * so implies "playing".
+ * @since 2.7.0
+ */
+ state: string;
- /**
- * Returns whether the dialog is currently open.
- * @param classNames the space-separated-list of classes to check for when determining the state of the dialog.
- * Each of built-in dialogs contains a name-themed class which can be tested for in this manner—e.g. the Saves
- * dialog contains the class saves.
- * @since 2.0.0
- * @example
- * if (Dialog.isOpen()) {
- * // code to execute if the dialog is open...
- * }
- * @example
- * if (Dialog.isOpen("saves")) {
- * // code to execute if the Saves dialog is open
- * }
- */
- isOpen(classNames?: string): boolean;
+ /**
+ * Moves backward one moment within the full history (past + future), if possible, activating and showing the
+ * moment moved to. Returns whether the history navigation was successful (should only fail if already at the
+ * beginning of the full history).
+ * @since 2.0.0
+ */
+ backward(): boolean;
- /**
- * Opens the dialog. Returns a reference to the Dialog object for chaining.
- *
- * NOTE: Call this only after populating the dialog with content.
- * @param options The options object. @see addClickHandler() for more information.
- * @param closeFn The function to execute whenever the dialog is closed.
- * @since 2.0.0
- */
- open(options?: object, closeFn?: () => void): Dialog;
+ /**
+ * Moves forward one moment within the full history (past + future), if possible, activating and showing the moment
+ * moved to. Returns whether the history navigation was successful (should only fail if already at the end of the
+ * full history).
+ * @since 2.0.0
+ */
+ forward(): boolean;
- /**
- * Prepares the dialog for use and returns a reference to its content area.
- * @param title The title of the dialog.
- * @param classNames The space-separated-list of classes to add to the dialog.
- * @since 2.0.0
- * @example
- * // Basic example.
- * Dialog.setup();
- * Dialog.wiki("Blah //blah// ''blah''.");
- * Dialog.open();
- *
- * @example
- * // Adding a title to the dialog.
- * Dialog.setup("Character Sheet");
- * Dialog.wiki(Story.get("PC Sheet").processText());
- * Dialog.open();
- *
- * @example
- * // Adding a title and class to the dialog.
- * Dialog.setup("Character Sheet", "charsheet");
- * Dialog.wiki(Story.get("PC Sheet").processText());
- * Dialog.open();
- */
- setup(title?: string, classNames?: string): HTMLElement;
+ /**
+ * Activates the moment at the given offset from the active (present) moment within the full state history and show
+ * it. Returns whether the history navigation was successful (should only fail if the offset from the active
+ * (present) moment is not within the bounds of the full history).
+ * @param offset The offset from the active (present) moment of the moment to go to.
+ * @since 2.0.0
+ */
+ go(offset: number): boolean;
- /**
- * Renders the given markup and appends it to the dialog's content area. Returns a reference to the Dialog object
- * for chaining.
- *
- * NOTE: If your content consists of DOM nodes, you'll need to use the @see Dialog.append() method instead.
- * @param wikiMarkup The markup to render.
- * @since 2.9.0
- * @example
- * Dialog.wiki("Cry 'Havoc!', and let slip the //ponies// of ''friendship''.");
- */
- wiki(wikiMarkup: string): Dialog;
- }
+ /**
+ * Activates the moment at the given index within the full state history and show it. Returns whether the history
+ * navigation was successful (should only fail if the index is not within the bounds of the full history).
+ * @param index The index of the moment to go to.
+ * @since 2.0.0
+ * @example
+ * Engine.goTo(0) // Goes to the first moment
+ * Engine.goTo(9) // Goes to the tenth moment
+ */
+ goTo(index: number): boolean;
- declare interface Engine {
- /**
- * Returns a timestamp representing the last time Engine.play() was called.
- * @since 2.0.0
- */
- lastPlay: number;
+ /**
+ * Returns whether the engine is idle.
+ * @since 2.16.0
+ */
+ isIdle(): boolean;
- /**
- * Returns the current state of the engine ("idle", "playing", "rendering").
- * States:
- * "idle": The engine is idle, awaiting the triggering of passage navigation—the default state.
- * "playing": Passage navigation has been triggered and a turn is being processed.
- * "rendering": The incoming passage is being rendered and added to the page—takes place during turn processing,
- * so implies "playing".
- * @since 2.7.0
- */
- state: string;
+ /**
+ * Returns whether the engine is processing a turn — i.e. passage navigation has been triggered.
+ * @since 2.16.0
+ */
+ isPlaying(): boolean;
- /**
- * Moves backward one moment within the full history (past + future), if possible, activating and showing the
- * moment moved to. Returns whether the history navigation was successful (should only fail if already at the
- * beginning of the full history).
- * @since 2.0.0
- */
- backward(): boolean;
+ /**
+ * Returns whether the engine is rendering the incoming passage.
+ * @since 2.16.0
+ */
+ isRendering(): boolean;
- /**
- * Moves forward one moment within the full history (past + future), if possible, activating and showing the moment
- * moved to. Returns whether the history navigation was successful (should only fail if already at the end of the
- * full history).
- * @since 2.0.0
- */
- forward(): boolean;
+ /**
+ * Renders and displays the passage referenced by the given title, optionally without adding a new moment to the
+ * history.
+ * @param passageTitle The title of the passage to play.
+ * @param noHistory Disables the update of the history (i.e. no moment is added to the history).
+ * @since 2.0.0
+ */
+ play(passageTitle: string, noHistory?: boolean): HTMLElement;
- /**
- * Activates the moment at the given offset from the active (present) moment within the full state history and show
- * it. Returns whether the history navigation was successful (should only fail if the offset from the active
- * (present) moment is not within the bounds of the full history).
- * @param offset The offset from the active (present) moment of the moment to go to.
- * @since 2.0.0
- */
- go(offset: number): boolean;
+ /**
+ * Restarts the story.
+ *
+ * WARNING: The player will not be prompted and all unsaved state will be lost.
+ * NOTE: In general, you should not call this method directly. Instead, call the UI.restart() static method, which
+ * prompts the player with an OK/Cancel dialog before itself calling Engine.restart(), if they accept.
+ * @since 2.0.0
+ */
+ restart(): void;
- /**
- * Activates the moment at the given index within the full state history and show it. Returns whether the history
- * navigation was successful (should only fail if the index is not within the bounds of the full history).
- * @param index The index of the moment to go to.
- * @since 2.0.0
- * @example
- * Engine.goTo(0) // Goes to the first moment
- * Engine.goTo(9) // Goes to the tenth moment
- */
- goTo(index: number): boolean;
+ /**
+ * Renders and displays the active (present) moment's associated passage without adding a new moment to the history.
+ * @since 2.0.0
+ */
+ show(): HTMLElement;
+ }
- /**
- * Returns whether the engine is idle.
- * @since 2.16.0
- */
- isIdle(): boolean;
+ interface LoadScreen {
+ /**
+ * Acquires a loading screen lock and returns its ID. Displays the loading screen, if necessary.
+ * @since 2.15.0
+ */
+ lock(): number;
- /**
- * Returns whether the engine is processing a turn — i.e. passage navigation has been triggered.
- * @since 2.16.0
- */
- isPlaying(): boolean;
+ /**
+ * Releases the loading screen lock with the given ID. Hides the loading screen, if no other locks exist.
+ * @param lockId The loading screen lock ID.
+ * @since 2.15.0
+ * @example
+ * var lockId = LoadScreen.lock();
+ * // Do something whose timing is unpredictable which should be hidden by the loading screen
+ * LoadScreen.unlock(lockId);
+ */
+ unlock(lockId: number): void;
+ }
- /**
- * Returns whether the engine is rendering the incoming passage.
- * @since 2.16.0
- */
- isRendering(): boolean;
+ interface MacroTags {
+ /**
+ * Return the named macro tag's parents array (includes the names of all macros who have registered the tag as a
+ * child), or null on failure.
+ * @param name Name of the macro tag whose parents array should be returned.
+ * @since 2.0.0
+ * @example
+ * Macro.tags.get("else") // For the standard library, returns: ["if"]
+ */
+ get(name: string): string[];
- /**
- * Renders and displays the passage referenced by the given title, optionally without adding a new moment to the
- * history.
- * @param passageTitle The title of the passage to play.
- * @param noHistory Disables the update of the history (i.e. no moment is added to the history).
- * @since 2.0.0
- */
- play(passageTitle: string, noHistory?: boolean): HTMLElement;
+ /**
+ * Returns whether the named macro tag exists.
+ * @param name Name of the macro tag to search for.
+ * @since 2.0.0
+ */
+ has(name: string): boolean;
+ }
- /**
- * Restarts the story.
- *
- * WARNING: The player will not be prompted and all unsaved state will be lost.
- * NOTE: In general, you should not call this method directly. Instead, call the UI.restart() static method, which
- * prompts the player with an OK/Cancel dialog before itself calling Engine.restart(), if they accept.
- * @since 2.0.0
- */
- restart(): void;
+ interface MacroArgsArray extends Array<String> {
+ /**
+ * The current tag's argument string after converting all TwineScript syntax elements into their
+ * native JavaScript counterparts. Equivalent in function to <MacroContext>.args.full.
+ */
+ full: string;
+ /**
+ * The current tag's unprocessed argument string. Equivalent in function to <MacroContext>.args.raw.
+ */
+ raw: string;
+ }
- /**
- * Renders and displays the active (present) moment's associated passage without adding a new moment to the history.
- * @since 2.0.0
- */
- show(): HTMLElement;
- }
+ interface MacroContexObject {
+ /**
+ * Name of the current tag.
+ */
+ name: string;
+ /**
+ * The current tag's argument string parsed into an array of discrete arguments.
+ * Equivalent in function to <MacroContext>.args.
+ */
+ args: MacroArgsArray;
- declare interface LoadScreen {
- /**
- * Acquires a loading screen lock and returns its ID. Displays the loading screen, if necessary.
- * @since 2.15.0
- */
- lock(): number;
+ /**
+ * The current tag's contents—i.e. the text between the current tag and the next.
+ */
+ contents: string;
+ }
- /**
- * Releases the loading screen lock with the given ID. Hides the loading screen, if no other locks exist.
- * @param lockId The loading screen lock ID.
- * @since 2.15.0
- * @example
- * var lockId = LoadScreen.lock();
- * // Do something whose timing is unpredictable which should be hidden by the loading screen
- * LoadScreen.unlock(lockId);
- */
- unlock(lockId: number): void;
- }
+ interface MacroContex {
+ /**
+ * The argument string parsed into an array of discrete arguments.
+ * @since 2.0.0
+ */
+ args: MacroArgsArray;
- declare interface MacroTags {
- /**
- * Return the named macro tag's parents array (includes the names of all macros who have registered the tag as a
- * child), or null on failure.
- * @param name Name of the macro tag whose parents array should be returned.
- * @since 2.0.0
- * @example
- * Macro.tags.get("else") // For the standard library, returns: ["if"]
- */
- get(name: string): string[];
+ /**
+ * The name of the macro.
+ * @since 2.0.0
+ */
+ name: string;
- /**
- * Returns whether the named macro tag exists.
- * @param name Name of the macro tag to search for.
- * @since 2.0.0
- */
- has(name: string): boolean;
- }
+ /**
+ * The current output element.
+ * @since 2.0.0
+ */
+ output: HTMLElement;
- declare interface MacroArgsArray extends Array<String> {
- /**
- * The current tag's argument string after converting all TwineScript syntax elements into their
- * native JavaScript counterparts. Equivalent in function to <MacroContext>.args.full.
- */
- full: string;
- /**
- * The current tag's unprocessed argument string. Equivalent in function to <MacroContext>.args.raw.
- */
- raw: string;
- }
+ /**
+ * The (execution) context object of the macro's parent, or null if the macro has no parent.
+ * @since 2.0.0
+ */
+ parent: object;
- declare interface MacroContexObject {
- /**
- * Name of the current tag.
- */
- name: string;
- /**
- * The current tag's argument string parsed into an array of discrete arguments.
- * Equivalent in function to <MacroContext>.args.
- */
- args: MacroArgsArray;
+ /**
+ * The text of a container macro parsed into discrete payload objects by tag.
+ * @since 2.0.0
+ */
+ payload: MacroContexObject[];
- /**
- * The current tag's contents—i.e. the text between the current tag and the next.
- */
- contents: string;
- }
+ /**
+ * The macro's definition — created via @see Macro.add()
+ * @since 2.0.0
+ */
+ self: object;
+ /**
+ * Returns whether any of the macro's ancestors passed the test implemented by the given
+ * filter function.
+ * @param filter he function used to test each ancestor execution context object, which
+ * is passed in as its sole parameter.
+ * @since 2.0.0
+ */
+ contextHas(filter: (MacroContexObject) => boolean): boolean;
- declare interface MacroContex {
- /**
- * The argument string parsed into an array of discrete arguments.
- * @since 2.0.0
- */
- args: MacroArgsArray;
+ /**
+ * Returns the first of the macro's ancestors which passed the test implemented by the given
+ * filter function or null, if no members pass.
+ * @param filter The function used to test each ancestor execution context object, which is
+ * passed in as its sole parameter.
+ * @since 2.0.0
+ */
+ contextSelect(filter: (MacroContexObject) => boolean): object;
- /**
- * The name of the macro.
- * @since 2.0.0
- */
- name: string;
+ /**
+ * Returns a new array containing all of the macro's ancestors which passed the test implemented
+ * by the given filter function or an empty array, if no members pass.
+ * @since 2.0.0
+ * @param filter
+ */
+ contextSelectAll(filter: (MacroContexObject) => boolean): object[];
- /**
- * The current output element.
- * @since 2.0.0
- */
- output: HTMLElement;
+ /**
+ * Renders the message prefixed with the name of the macro and returns false.
+ * @param message The error message to output.
+ * @since 2.0.0
+ */
+ error(message: string): false;
+ }
- /**
- * The (execution) context object of the macro's parent, or null if the macro has no parent.
- * @since 2.0.0
- */
- parent: object;
+ interface Macro {
+ /**
+ * Add new macro(s).
+ * @param name Name, or array of names, of the macro(s) to add.
+ * @param definition Definition of the macro(s) or the name of an existing macro whose definition to copy.
+ * Definition object:
+ * A macro definition object should have some of the following properties (only handler is absolutely required):
+ * skipArgs: (optional, boolean) Disables parsing argument strings into discrete arguments. Used by macros which
+ * only use the raw/full argument strings.
+ * tags: (optional, null | string array) Signifies that the macro is a container macro—i.e. not self-closing. An
+ * array of the names of the child tags, or null if there are no child tags.
+ * handler: (function) The macro's main function. It will be called without arguments, but with its this set to a
+ * macro context object.
+ * @param deep Enables deep cloning of the definition. Used to give macros separate instances of the same
+ * definition.
+ * @since 2.0.0
+ * @example
+ * // Example of a very simple/naive <<if>>/<<elseif>>/<<else>> macro implementation.
+ * Macro.add('if', {
+ * skipArgs: true,
+ * tags: ['elseif', 'else'],
+ * handler: function () {
+ * try {
+ * for (var i = 0, len = this.payload.length; i < len; ++i) {
+ * if (
+ * this.payload[i].name === 'else' ||
+ * !!Scripting.evalJavaScript(this.payload[i].args.full)
+ * ) {
+ * jQuery(this.output).wiki(this.payload[i].contents);
+ * break;
+ * }
+ * }
+ * }
+ * catch (ex) {
+ * return this.error('bad conditional expression: ' + ex.message);
+ * }
+ * }
+ * });
+ */
+ add(name: string | string[],
+ definition: { handler: (this: MacroContex) => void, tags?: string[], skipArgs?: boolean },
+ deep?: boolean): void;
- /**
- * The text of a container macro parsed into discrete payload objects by tag.
- * @since 2.0.0
- */
- payload: MacroContexObject[];
+ /**
+ * Remove existing macro(s).
+ * @param name Name, or array of names, of the macro(s) to remove.
+ * @since 2.0.0
+ */
+ delete(name: string | string[]): void;
- /**
- * The macro's definition — created via @see Macro.add()
- * @since 2.0.0
- */
- self: object;
+ /**
+ * Return the named macro definition, or null on failure.
+ * @param name Name of the macro whose definition should be returned.
+ * @since 2.0.0
+ */
+ get(name: string): object;
- /**
- * Returns whether any of the macro's ancestors passed the test implemented by the given
- * filter function.
- * @param filter he function used to test each ancestor execution context object, which
- * is passed in as its sole parameter.
- * @since 2.0.0
- */
- contextHas(filter: (MacroContexObject) => boolean): boolean;
+ /**
+ * Returns whether the named macro exists.
+ * @param name Name of the macro to search for.
+ * @since 2.0.0
+ */
+ has(name: string): boolean;
- /**
- * Returns the first of the macro's ancestors which passed the test implemented by the given
- * filter function or null, if no members pass.
- * @param filter The function used to test each ancestor execution context object, which is
- * passed in as its sole parameter.
- * @since 2.0.0
- */
- contextSelect(filter: (MacroContexObject) => boolean): object;
+ /**
+ * @since 2.0.0
+ */
+ tags: MacroTags;
+ }
- /**
- * Returns a new array containing all of the macro's ancestors which passed the test implemented
- * by the given filter function or an empty array, if no members pass.
- * @since 2.0.0
- * @param filter
- */
- contextSelectAll(filter: (MacroContexObject) => boolean): object[];
+ interface Passage {
+ /**
+ * The DOM ID of the passage (created from the slugified passage title).
+ * @since 2.0.0
+ */
+ domId: string;
- /**
- * Renders the message prefixed with the name of the macro and returns false.
- * @param message The error message to output.
- * @since 2.0.0
- */
- error(message: string): false;
- }
+ /**
+ * The tags of the passage.
+ * @since 2.0.0
+ */
+ tags: string[];
- declare interface Macro {
- /**
- * Add new macro(s).
- * @param name Name, or array of names, of the macro(s) to add.
- * @param definition Definition of the macro(s) or the name of an existing macro whose definition to copy.
- * Definition object:
- * A macro definition object should have some of the following properties (only handler is absolutely required):
- * skipArgs: (optional, boolean) Disables parsing argument strings into discrete arguments. Used by macros which
- * only use the raw/full argument strings.
- * tags: (optional, null | string array) Signifies that the macro is a container macro—i.e. not self-closing. An
- * array of the names of the child tags, or null if there are no child tags.
- * handler: (function) The macro's main function. It will be called without arguments, but with its this set to a
- * macro context object.
- * @param deep Enables deep cloning of the definition. Used to give macros separate instances of the same
- * definition.
- * @since 2.0.0
- * @example
- * // Example of a very simple/naive <<if>>/<<elseif>>/<<else>> macro implementation.
- * Macro.add('if', {
- * skipArgs: true,
- * tags: ['elseif', 'else'],
- * handler: function () {
- * try {
- * for (var i = 0, len = this.payload.length; i < len; ++i) {
- * if (
- * this.payload[i].name === 'else' ||
- * !!Scripting.evalJavaScript(this.payload[i].args.full)
- * ) {
- * jQuery(this.output).wiki(this.payload[i].contents);
- * break;
- * }
- * }
- * }
- * catch (ex) {
- * return this.error('bad conditional expression: ' + ex.message);
- * }
- * }
- * });
- */
- add(name: string | string[],
- definition: { handler: (this: MacroContex) => void, tags?: string[], skipArgs?: boolean },
- deep?: boolean): void;
+ /**
+ * The raw text of the passage.
+ * @since 2.0.0
+ */
+ text: string;
- /**
- * Remove existing macro(s).
- * @param name Name, or array of names, of the macro(s) to remove.
- * @since 2.0.0
- */
- delete(name: string | string[]): void;
+ /**
+ * The title of the passage.
+ * @since 2.0.0
+ */
+ title: string;
- /**
- * Return the named macro definition, or null on failure.
- * @param name Name of the macro whose definition should be returned.
- * @since 2.0.0
- */
- get(name: string): object;
+ /**
+ * Returns the description of the passage (created from either an excerpt of the passage or the
+ * Config.passages.descriptions object).
+ * @since 2.0.0
+ */
+ description(): string;
- /**
- * Returns whether the named macro exists.
- * @param name Name of the macro to search for.
- * @since 2.0.0
- */
- has(name: string): boolean;
+ /**
+ * Returns the text of the Passage object (similar to <Passage>.text) after applying nobr tag and image passage
+ * processing to it.
+ * @since 2.0.0
+ */
+ processText(): string;
+ }
- /**
- * @since 2.0.0
- */
- tags: MacroTags;
- }
+ interface SavedMoment {
+ /** The title of the associated passage. */
+ title: string;
+ /** The current variable store object, which contains sigil - less name ⇒ value pairs(e.g.$foo exists as foo). */
+ variables: any;
+ /** The current pull count of SugarCube's seedable PRNG, exists only if enabled. */
+ pull?: number;
+ }
- declare interface Passage {
- /**
- * The DOM ID of the passage (created from the slugified passage title).
- * @since 2.0.0
- */
- domId: string;
+ interface SavedState {
+ /** The array of moment objects. */
+ history: SavedMoment[];
+ /** The index of the active moment. */
+ index: number;
+ /** The array of expired moment passage titles, exists only if any moments have expired. */
+ expired?: string[];
+ /** The seed of SugarCube's seedable PRNG, exists only if enabled. */
+ seed?: string;
+ }
- /**
- * The tags of the passage.
- * @since 2.0.0
- */
- tags: string[];
+ interface SaveObject {
+ /** The story's save ID.*/
+ id: string;
+ /** The marshaled story history(see below for details). */
+ state: SavedState;
+ /** The title of the save. */
+ title: string;
+ /** The date when the save was created(in milliseconds elapsed since epoch). */
+ date: number;
+ /** Save metadata(end - user specified; must be JSON - serializable). */
+ metadata?: any;
+ /** Save version(end - user specified via Config.saves.version). */
+ version?: any;
+ }
+ interface Save {
+ /**
+ * Deletes all slot saves and the autosave, if it's enabled.
+ * @since 2.0.0
+ */
+ clear(): void;
- /**
- * The raw text of the passage.
- * @since 2.0.0
- */
- text: string;
+ /**
+ * Returns the saves object.
+ * @since 2.0.0
+ */
+ get(): object;
- /**
- * The title of the passage.
- * @since 2.0.0
- */
- title: string;
+ /**
+ * Returns whether both the slot saves and autosave are available and ready.
+ * @since 2.0.0
+ */
+ ok(): boolean;
- /**
- * Returns the description of the passage (created from either an excerpt of the passage or the
- * Config.passages.descriptions object).
- * @since 2.0.0
- */
- description(): string;
+ slots: {
+ /**
+ * Returns the total number of available slots.
+ * @since 2.0.0
+ */
+ length: number;
+
+ /**
+ * Returns the total number of filled slots.
+ * @since 2.0.0
+ */
+ count(): number;
+
+ /**
+ * Deletes a save from the given slot.
+ * @param slot Save slot index (0-based).
+ * @since 2.0.0
+ */
+ delete(slot: number): void;
+
+ /**
+ * Returns a save object from the given slot or null, if there was no save in the given slot.
+ * @param slot Save slot index (0-based).
+ * @since 2.0.0
+ */
+ get(slot: number): SaveObject;
+
+ /**
+ * Returns whether the given slot is filled.
+ * @param slot Save slot index (0-based).
+ * @since 2.0.0
+ */
+ has(slot: number): boolean;
+
+ /**
+ * Returns whether there are any filled slots.
+ * @since 2.0.0
+ */
+ isEmpty(): boolean;
+
+ /**
+ * Loads a save from the given slot.
+ * @param slot
+ */
+ load(slot: number): void;
+
+ /**
+ * Returns whether the slot saves are available and ready.
+ * @since 2.0.0
+ */
+ ok(): boolean;
+
+ /**
+ * Saves to the given slot.
+ * @param slot Save slot index (0-based).
+ * @param title The title of the save. If omitted or null, defaults to the passage's description.
+ * @param metadata The data to be stored in the save object's metadata property. Must be JSON-serializable.
+ * @since 2.0.0
+ */
+ save(slot: number, title?: string, metadata?: any): void;
+ }
+
+ autosave: {
+ /**
+ * Deletes the autosave.
+ * @since 2.0.0
+ */
+ delete(): void;
+
+ /**
+ * Returns the save object from the autosave or null, if there was no autosave.
+ * @since 2.0.0
+ */
+ get(): SaveObject;
+
+ /**
+ * Returns whether the autosave is filled.
+ * @since 2.0.0
+ */
+ has(): boolean;
+
+ /**
+ * Loads the autosave.
+ * @since 2.0.0
+ */
+ load(): void;
+
+ /**
+ * Returns whether the autosave is available and ready.
+ * @since 2.0.0
+ */
+ ok(): boolean;
+
+ /**
+ * Saves to the autosave.
+ * @param title The title of the save. If omitted or null, defaults to the passage's description.
+ * @param metadata The data to be stored in the save object's metadata property. Must be JSON-serializable.
+ * @since 2.0.0
+ */
+ save(title?: string, metadata?: any): void;
+ }
- /**
- * Returns the text of the Passage object (similar to <Passage>.text) after applying nobr tag and image passage
- * processing to it.
- * @since 2.0.0
- */
- processText(): string;
- }
+ /**
+ * Saves to disk.
+ * @param filename The base filename of the save, which gets slugified to remove most symbols. Appended to this is a datestamp
+ * (format: YYYMMDD-hhmmss) and the file extension .save. (e.g. "The Scooby Chronicles" would result in the full filename:
+ * the-scooby-chronicles-{datestamp}.save). If omitted or null, defaults to the story's title.
+ * @param metadata The data to be stored in the save object's metadata property. Must be JSON-serializable.
+ * @since 2.8.0
+ */
+ export(filename?: string, metadata?: any): void;
- declare interface SavedMoment {
- /** The title of the associated passage. */
- title: string;
- /** The current variable store object, which contains sigil - less name ⇒ value pairs(e.g.$foo exists as foo). */
- variables: any;
- /** The current pull count of SugarCube's seedable PRNG, exists only if enabled. */
- pull?: number;
- }
+ /**
+ * Loads a save from disk.
+ *
+ * NOTE: You do not call this manually, it must be called by the change event handler of an <input type="file"> element.
+ * @param event The event object which was passed to the change event handler of the associated <input type="file"> element.
+ * @since 2.0.0
+ * @example
+ * // Add file input
+ * var input = document.createElement('input');
+ * input.type = 'file';
+ * input.id = 'saves-import-file';
+ * input.name = 'saves-import-file';
+ * // Set up Save.import() as the event handler for when a file has been chosen
+ * jQuery(input).on('change', Save.import);
+ */
+ import(event: Event): void;
- declare interface SavedState {
- /** The array of moment objects. */
- history: SavedMoment[];
- /** The index of the active moment. */
- index: number;
- /** The array of expired moment passage titles, exists only if any moments have expired. */
- expired?: string[];
- /** The seed of SugarCube's seedable PRNG, exists only if enabled. */
- seed?: string;
- }
+ /**
+ * Returns a save as a serialized string, or null if saving is not allowed within the current context.
+ * @param metadata The data to be stored as metadata. Must be JSON-serializable.
+ * @since 2.21.0
+ */
+ serialize(metadata?: any): string;
- declare interface SaveObject {
- /** The story's save ID.*/
- id: string;
- /** The marshaled story history(see below for details). */
- state: SavedState;
- /** The title of the save. */
- title: string;
- /** The date when the save was created(in milliseconds elapsed since epoch). */
- date: integer;
- /** Save metadata(end - user specified; must be JSON - serializable). */
- metadata?: any;
- /** Save version(end - user specified via Config.saves.version). */
- version?: any;
- }
+ /**
+ * Deserializes the given save string, created via Save.serialize(), and loads the save. Returns the bundled metadata, if any,
+ * or null if the given save could not be deserialized and loaded.
+ * @param saveStr The serialized save string.
+ * @since 2.21.0
+ */
+ deserialize(saveStr: string): any;
+ }
- declare interface Save {
- /**
- * Deletes all slot saves and the autosave, if it's enabled.
- * @since 2.0.0
- */
- clear(): void;
+ interface Settings {
+ /**
+ * Adds a header to the Settings dialog.
+ * @param name Name of the header.
+ * @param desc Description explaining the header in greater detail.
+ * @since 2.7.1
+ */
+ addHeader(name: string, desc?: string): void;
- /**
- * Returns the saves object.
- * @since 2.0.0
- */
- get(): object;
+ /**
+ * Adds the named property to the settings object and a toggle control for it to the Settings dialog.
+ * @param name Name of the settings property to add, which the control will manage.
+ * @param definition Definition of the control.
+ * @since 2.26.0
+ */
+ addToggle(name: string, definition: {
+ label: string,
+ desc?: string,
+ default?: boolean,
+ onInit?: () => void,
+ onChange?: () => void
+ }): void;
- /**
- * Returns whether both the slot saves and autosave are available and ready.
- * @since 2.0.0
- */
- ok(): boolean;
+ /**
+ * Adds the named property to the settings object and a list control for it to the Settings dialog.
+ * @param name Name of the settings property to add, which the control will manage.
+ * @param definition Definition of the control.
+ * @since 2.26.0
+ */
+ addList(name: string, definition: {
+ label: string,
+ list: [],
+ desc?: string,
+ default?: any,
+ onInit?: () => void,
+ onChange?: () => void
+ }): void;
- slots: {
/**
- * Returns the total number of available slots.
+ * Adds the named property to the settings object and a range control for it to the Settings dialog.
+ * @param name Name of the settings property to add, which the control will manage.
+ * @param definition Definition of the control.
* @since 2.0.0
*/
- length: number;
+ addRange(name: string, definition: {
+ /** Label to use for the control. */
+ label: string,
+ /** The minimum value. */
+ min: number,
+ /** The maximum value. */
+ max: number,
+ /** Limits the increments to which the value may be set.It must be evenly divisible into the full range
+ * — i.e.max - min. */
+ step: number,
+ /** Description explaining the control in greater detail. */
+ desc?: string,
+ /** The default value for the setting and default state of the control.Leaving it undefined means to use
+ * the value of max as the default. */
+ default?: number,
+ /** The function to call during initialization. */
+ onInit?: () => void,
+ /** The function to call when the control's state is changed. */
+ onChange?: () => void
+ }): void;
/**
- * Returns the total number of filled slots.
+ * Loads the settings from storage.
+ *
+ * NOTE: The API automatically calls this method at startup, so you should never need to call this method manually.
* @since 2.0.0
*/
- count(): number;
+ load(): void;
/**
- * Deletes a save from the given slot.
- * @param slot Save slot index (0-based).
+ * Resets the setting with the given name to its default value. If no name is given, resets all settings.
+ * @param name Name of the settings object property to reset.
* @since 2.0.0
*/
- delete(slot: number): void;
+ reset(name?: string): void;
/**
- * Returns a save object from the given slot or null, if there was no save in the given slot.
- * @param slot Save slot index (0-based).
+ * Saves the settings to storage.
+ *
+ * NOTE: The controls of the Settings dialog automatically call this method when settings are changed,
+ * so you should normally never need to call this method manually. Only when manually modifying the values
+ * of settings object properties, outside of the controls, would you need to call this method.
* @since 2.0.0
*/
- get(slot: number): SaveObject;
+ save();
+ }
+ interface Story {
/**
- * Returns whether the given slot is filled.
- * @param slot Save slot index (0-based).
+ * The DOM ID of the story (created from the slugified story title).
* @since 2.0.0
*/
- has(slot: number): boolean;
+ domId: string;
/**
- * Returns whether there are any filled slots.
+ * The title of the story.
* @since 2.0.0
*/
- isEmpty(): boolean;
+ title: string;
/**
- * Loads a save from the given slot.
- * @param slot
+ * Returns the Passage object referenced by the given title, or an empty Passage object on failure.
+ * @param passageTitle The title of the Passage object to return.
+ * @since 2.0.0
*/
- load(slot: number): void;
+ get(passageTitle: string): Passage;
/**
- * Returns whether the slot saves are available and ready.
+ * Returns whether a Passage object referenced by the given title exists.
+ * @param passageTitle The title of the Passage object whose existence will be verified.
* @since 2.0.0
*/
- ok(): boolean;
+ has(passageTitle): boolean;
/**
- * Saves to the given slot.
- * @param slot Save slot index (0-based).
- * @param title The title of the save. If omitted or null, defaults to the passage's description.
- * @param metadata The data to be stored in the save object's metadata property. Must be JSON-serializable.
+ * Returns an array of Passage objects each of which must contain a property matching the given name,
+ * whose value matches the given needle, or an empty array, if no matches are made.
+ * @param propertyName The name of property whose value will be compared to the search value.
+ * @param searchValue he value to search for within the matched property. The type of the property determines
+ * how the search occurs; direct comparison for non-arrays, while arrays are iterated over. If the property
+ * value, for non-arrays, or any of the property members' values, for arrays, match, then the Passage object
+ * is added to the results array.
+ * @param sortProperty The property whose value will be used to lexicographically sort the returned array.
+ * If not given, the Passage object's title property is used.
* @since 2.0.0
+ * @example
+ * // Returns all 'forest'-tagged Passage objects, sorted by their titles
+ * Story.lookup("tags", "forest");
*/
- save(slot: number, title?: string, metadata?: any): void;
+ lookup(propertyName: string, searchValue: string | number, sortProperty?: string): Passage[];
+
+ /**
+ * Returns an array of Passage objects which passed the test implemented by the given filter function or
+ * an empty array, if no objects pass.
+ * @param filter The function used to test each Passage object, which is passed in as its sole parameter.
+ * If the function returns true, then the Passage object is added to the results array.
+ * @param sortProperty The property whose value will be used to lexicographically sort the returned array.
+ * If not given, the Passage object's title property is used.
+ * @since 2.11.0
+ */
+ lookupWith(filter: (p: Passage) => boolean, sortProperty?: string): Passage[];
}
- autosave: {
+ interface UI {
/**
- * Deletes the autosave.
+ * Opens the built-in alert dialog, displaying the given message to the player.
+ * @param message The message to display to the player.
+ * @param options The options object. @see Dialog.addClickHandler() for more information.
+ * @param closeFn The function to execute whenever the dialog is closed.
* @since 2.0.0
*/
- delete(): void;
+ alert(message: string, options?: object, closeFn?: () => void): void;
/**
- * Returns the save object from the autosave or null, if there was no autosave.
+ * Opens the built-in jump to dialog, which is populated via the bookmark tag.
+ * @param options The options object. @see Dialog.addClickHandler() for more information.
+ * @param closeFn The function to execute whenever the dialog is closed.
* @since 2.0.0
*/
- get(): SaveObject;
+ jumpto(options: object, closeFn?: () => void): void;
/**
- * Returns whether the autosave is filled.
+ * Opens the built-in restart dialog, prompting the player to restart the story.
+ * @param options The options object. @see Dialog.addClickHandler() for more information.
* @since 2.0.0
*/
- has(): boolean;
+ restart(options?: any): void;
/**
- * Loads the autosave.
+ * Opens the built-in saves dialog.
+ * @param options The options object. See Dialog.addClickHandler() for more information.
+ * @param closeFn The function to execute whenever the dialog is closed.
* @since 2.0.0
*/
- load(): void;
+ saves(options: object, closeFn?: () => void): void;
/**
- * Returns whether the autosave is available and ready.
- * @since 2.0.0
+ * Opens the built-in settings dialog, which is populated from the Setting API.
+ * @param options The options object. See Dialog.addClickHandler() for more information.
+ * @param closeFn The function to execute whenever the dialog is closed.
+ * @sine 2.0.0
+ *
*/
- ok(): boolean;
+ settings(options: object, closeFn?: () => void): void;
/**
- * Saves to the autosave.
- * @param title The title of the save. If omitted or null, defaults to the passage's description.
- * @param metadata The data to be stored in the save object's metadata property. Must be JSON-serializable.
+ * Opens the built-in share dialog, which is populated from the StoryShare passage.
+ * @param options The options object. See Dialog.addClickHandler() for more information.
+ * @param closeFn The function to execute whenever the dialog is closed.
* @since 2.0.0
*/
- save(title?: string, metadata?: any): void;
+ share(options: object, closeFn?: () => void): void;
}
- /**
- * Saves to disk.
- * @param filename The base filename of the save, which gets slugified to remove most symbols. Appended to this is a datestamp
- * (format: YYYMMDD-hhmmss) and the file extension .save. (e.g. "The Scooby Chronicles" would result in the full filename:
- * the-scooby-chronicles-{datestamp}.save). If omitted or null, defaults to the story's title.
- * @param metadata The data to be stored in the save object's metadata property. Must be JSON-serializable.
- * @since 2.8.0
- */
- export(filename?: string, metadata?: any): void;
-
- /**
- * Loads a save from disk.
- *
- * NOTE: You do not call this manually, it must be called by the change event handler of an <input type="file"> element.
- * @param event The event object which was passed to the change event handler of the associated <input type="file"> element.
- * @since 2.0.0
- * @example
- * // Add file input
- * var input = document.createElement('input');
- * input.type = 'file';
- * input.id = 'saves-import-file';
- * input.name = 'saves-import-file';
- * // Set up Save.import() as the event handler for when a file has been chosen
- * jQuery(input).on('change', Save.import);
- */
- import(event: Event): void;
-
- /**
- * Returns a save as a serialized string, or null if saving is not allowed within the current context.
- * @param metadata The data to be stored as metadata. Must be JSON-serializable.
- * @since 2.21.0
- */
- serialize(metadata?: any): string;
-
- /**
- * Deserializes the given save string, created via Save.serialize(), and loads the save. Returns the bundled metadata, if any,
- * or null if the given save could not be deserialized and loaded.
- * @param saveStr The serialized save string.
- * @since 2.21.0
- */
- deserialize(saveStr: string): any;
- }
-
- declare interface Settings {
- /**
- * Adds a header to the Settings dialog.
- * @param name Name of the header.
- * @param desc Description explaining the header in greater detail.
- * @since 2.7.1
- */
- addHeader(name: string, desc?: string): void;
-
- /**
- * Adds the named property to the settings object and a toggle control for it to the Settings dialog.
- * @param name Name of the settings property to add, which the control will manage.
- * @param definition Definition of the control.
- * @since 2.26.0
- */
- addToggle(name: string, definition: {
- label: string,
- desc?: string,
- default?: boolean,
- onInit?: () => void,
- onChange?: () => void
- }): void;
-
- /**
- * Adds the named property to the settings object and a list control for it to the Settings dialog.
- * @param name Name of the settings property to add, which the control will manage.
- * @param definition Definition of the control.
- * @since 2.26.0
- */
- addList(name: string, definition: {
- label: string,
- list: [],
- desc?: string,
- default?: any,
- onInit?: () => void,
- onChange?: () => void
- }): void;
-
- /**
- * Adds the named property to the settings object and a range control for it to the Settings dialog.
- * @param name Name of the settings property to add, which the control will manage.
- * @param definition Definition of the control.
- * @since 2.0.0
- */
- addRange(name: string, definition: {
- /** Label to use for the control. */
- label: string,
- /** The minimum value. */
- min: number,
- /** The maximum value. */
- max: number,
- /** Limits the increments to which the value may be set.It must be evenly divisible into the full range
- * — i.e.max - min. */
- step: numbe,
- /** Description explaining the control in greater detail. */
- desc?: string,
- /** The default value for the setting and default state of the control.Leaving it undefined means to use
- * the value of max as the default. */
- default?: number,
- /** The function to call during initialization. */
- onInit?: () => void,
- /** The function to call when the control's state is changed. */
- onChange?: () => void
- }): void;
-
- /**
- * Loads the settings from storage.
- *
- * NOTE: The API automatically calls this method at startup, so you should never need to call this method manually.
- * @since 2.0.0
- */
- load(): void;
-
- /**
- * Resets the setting with the given name to its default value. If no name is given, resets all settings.
- * @param name Name of the settings object property to reset.
- * @since 2.0.0
- */
- reset(name?: string): void;
-
- /**
- * Saves the settings to storage.
- *
- * NOTE: The controls of the Settings dialog automatically call this method when settings are changed,
- * so you should normally never need to call this method manually. Only when manually modifying the values
- * of settings object properties, outside of the controls, would you need to call this method.
- * @since 2.0.0
- */
- save();
- }
-
- declare interface Story {
- /**
- * The DOM ID of the story (created from the slugified story title).
- * @since 2.0.0
- */
- domId: string;
-
- /**
- * The title of the story.
- * @since 2.0.0
- */
- title: string;
-
- /**
- * Returns the Passage object referenced by the given title, or an empty Passage object on failure.
- * @param passageTitle The title of the Passage object to return.
- * @since 2.0.0
- */
- get(passageTitle: string): Passage;
-
- /**
- * Returns whether a Passage object referenced by the given title exists.
- * @param passageTitle The title of the Passage object whose existence will be verified.
- * @since 2.0.0
- */
- has(passageTitle): boolean;
-
- /**
- * Returns an array of Passage objects each of which must contain a property matching the given name,
- * whose value matches the given needle, or an empty array, if no matches are made.
- * @param propertyName The name of property whose value will be compared to the search value.
- * @param searchValue he value to search for within the matched property. The type of the property determines
- * how the search occurs; direct comparison for non-arrays, while arrays are iterated over. If the property
- * value, for non-arrays, or any of the property members' values, for arrays, match, then the Passage object
- * is added to the results array.
- * @param sortProperty The property whose value will be used to lexicographically sort the returned array.
- * If not given, the Passage object's title property is used.
- * @since 2.0.0
- * @example
- * // Returns all 'forest'-tagged Passage objects, sorted by their titles
- * Story.lookup("tags", "forest");
- */
- lookup(propertyName: string, searchValue: string | number, sortProperty?: string): Passage[];
-
- /**
- * Returns an array of Passage objects which passed the test implemented by the given filter function or
- * an empty array, if no objects pass.
- * @param filter The function used to test each Passage object, which is passed in as its sole parameter.
- * If the function returns true, then the Passage object is added to the results array.
- * @param sortProperty The property whose value will be used to lexicographically sort the returned array.
- * If not given, the Passage object's title property is used.
- * @since 2.11.0
- */
- lookupWith(filter: (p: Passage) => boolean, sortProperty?:string): Passage[];
- }
-
- declare interface UI {
- /**
- * Opens the built-in alert dialog, displaying the given message to the player.
- * @param message The message to display to the player.
- * @param options The options object. @see Dialog.addClickHandler() for more information.
- * @param closeFn The function to execute whenever the dialog is closed.
- * @since 2.0.0
- */
- alert(message: string, options?: object, closeFn?: () => void): void;
-
- /**
- * Opens the built-in jump to dialog, which is populated via the bookmark tag.
- * @param options The options object. @see Dialog.addClickHandler() for more information.
- * @param closeFn The function to execute whenever the dialog is closed.
- * @since 2.0.0
- */
- jumpto(options: object, closeFn?: () => void): void;
-
- /**
- * Opens the built-in restart dialog, prompting the player to restart the story.
- * @param options The options object. @see Dialog.addClickHandler() for more information.
- * @since 2.0.0
- */
- restart(options?: any): void;
-
- /**
- * Opens the built-in saves dialog.
- * @param options The options object. See Dialog.addClickHandler() for more information.
- * @param closeFn The function to execute whenever the dialog is closed.
- * @since 2.0.0
- */
- saves(options: object, closeFn?: () => void): void;
+ interface UIBar {
+ /**
+ * Completely removes the UI bar and all of its associated styles and event handlers.
+ * @since 2.17.0
+ */
+ destroy(): void;
- /**
- * Opens the built-in settings dialog, which is populated from the Setting API.
- * @param options The options object. See Dialog.addClickHandler() for more information.
- * @param closeFn The function to execute whenever the dialog is closed.
- * @sine 2.0.0
- *
- */
- settings(options: object, closeFn?: () => void): void;
+ /**
+ * Stows the UI bar, so that it takes up less space.
+ * @since 2.17.0
+ */
+ stow(): void;
- /**
- * Opens the built-in share dialog, which is populated from the StoryShare passage.
- * @param options The options object. See Dialog.addClickHandler() for more information.
- * @param closeFn The function to execute whenever the dialog is closed.
- * @since 2.0.0
- */
- share(options: object, closeFn?: () => void): void;
- }
+ /**
+ * Unstows UI bar, so that it is fully accessible again.
+ * @since 2.17.0
+ */
+ unstow(): void;
+ }
- declare interface UIBar {
- /**
- * Completely removes the UI bar and all of its associated styles and event handlers.
- * @since 2.17.0
- */
- destroy(): void;
+ interface StoryMoment {
+ title: string;
+ variables: any;
+ }
- /**
- * Stows the UI bar, so that it takes up less space.
- * @since 2.17.0
- */
- stow(): void;
+ interface State {
+ /**
+ * Returns the active (present) moment.
+ * @since 2.0.0
+ */
+ active: StoryMoment;
+ /**
+ * Returns the bottommost (least recent) moment from the full in-play history (past + future).
+ * @since 2.0.0
+ */
+ bottom: StoryMoment;
+ /**
+ * Returns the current moment from the full in-play history (past + future), which is the pre-play version of the active
+ * moment.
+ *
+ * WARNING: State.current is not a synonym for State.active. You will, very likely, never need to use State.current
+ * directly within your code.
+ *
+ * @since 2.8.0
+ */
+ current: StoryMoment;
+ /**
+ * Returns the number of moments within the past in-play history (past only).
+ * @since 2.0.0
+ */
+ length: number;
+ /**
+ * Returns the title of the passage associated with the active (present) moment.
+ * @since 2.0.0
+ */
+ passage: string;
+ /**
+ * Returns the current temporary variables.
+ * @since 2.13.0
+ */
+ temporary: any;
+ /**
+ * Returns the number of moments within the full in-play history (past + future).
+ * @since 2.0.0
+ */
+ size: number;
+ /**
+ * Returns the topmost (most recent) moment from the full in-play history (past + future).
+ *
+ * WARNING: State.top is not a synonym for State.active. You will, very likely, never need to use State.top directly
+ * within your code.
+ * @since 2.0.0
+ */
+ top: StoryMoment;
+ /**
+ * Returns the total number of played moments within the extended past history (expired + past).
+ * @since 2.0.0
+ */
+ turns: number;
+ /**
+ * Returns the variables from the active (present) moment.
+ * @since 2.0.0
+ */
+ variables: any;
+ /**
+ * Returns the value of the story or temporary variable by the given name.
+ * @param varName The name of the story or temporary variable, including its sigil—e.g. $charName.
+ * @since 2.22.0
+ */
+ getVar(varName: string): any;
+ /**
+ * Returns whether any moments with the given title exist within the past in-play history (past only).
+ *
+ * NOTE: State.has() does not check expired moments. If you need to know if the player has ever been to a particular
+ * passage, then you must use the State.hasPlayed() method or the hasVisited() story function.
+ * @param passageTitle The title of the moment whose existence will be verified.
+ * @since 2.0.0
+ */
+ has(passageTitle: string): boolean;
+ /**
+ * Returns whether any moments with the given title exist within the extended past history (expired + past).
+ *
+ * NOTE: If you need to check for multiple passages, the hasVisited() story function will likely be more convenient to
+ * use.
+ * @param passageTitle The title of the moment whose existence will be verified.
+ * @since 2.0.0
+ */
+ hasPlayed(passageTitle: string): boolean;
+ /**
+ * Returns the moment, relative to the bottom of the past in-play history (past only), at the given index.
+ * @param index The index of the moment to return.
+ * @since 2.0.0
+ */
+ index(index: number): StoryMoment;
+ /**
+ * Initializes the seedable pseudo-random number generator (PRNG) and integrates it into the story state and saves.
+ * Once initialized, the State.random() method and story functions, random() and randomFloat(), return results from
+ * the seeded PRNG (by default, they return results from Math.random()).
+ *
+ * NOTE: State.initPRNG() must be called during story initialization, within either a script section (Twine 2: the
+ * Story JavaScript, Twine 1/Twee: a script-tagged passage) or the StoryInit special passage. Additionally, it is
+ * recommended that you do not specify any arguments to State.initPRNG() and allow it to automatically seed itself. If
+ * you should chose to use an explicit seed, however, it is strongly recommended that you also enable additional
+ * entropy, otherwise all playthroughs for all players will be exactly the same.
+ * @param seed The explicit seed used to initialize the pseudo-random number generator.
+ * @param useEntropy Enables the use of additional entropy to pad the specified explicit seed.
+ * @since 2.0.0
+ * @example
+ * State.initPRNG() // Automatically seed the PRNG (recommended)
+ * State.initPRNG("aVeryLongSeed") // Seed the PRNG with "aVeryLongSeed"
+ * State.initPRNG("aVeryLongSeed", true) // Seed the PRNG with "aVeryLongSeed" and pad it with extra entropy
+ */
+ initPRNG(seed?: string, useEntropy?: boolean): void;
+ /**
+ * Returns whether the full in-play history (past + future) is empty.
+ * @since 2.0.0
+ */
+ isEmpty(): boolean;
+ /**
+ * Returns the moment, relative to the top of the past in-play history (past only), at the, optional, offset.
+ * @param offset The offset, from the top of the past in-play history, of the moment to return. If not given, an offset
+ * of 0 is used.
+ */
+ peek(offset?: number): StoryMoment;
+ /**
+ * Returns a pseudo-random real number (floating-point) in the range 0 (inclusive) up to, but not including, 1
+ * (exclusive).
+ *
+ * NOTE: By default, it simply returns results from Math.random(), however, when the seedable PRNG has been enabled,
+ * via State.initPRNG(), it returns results from the seeded PRNG instead.
+ * @since 2.0.0
+ */
+ random(): number;
+ /**
+ * Sets the value of the story or temporary variable by the given name. Returns whether the operation was successful.
+ * @param varName The name of the story or temporary variable, including its sigil—e.g. $charName.
+ * @param value The value to assign.
+ * @since 2.22.0
+ */
+ setVar(varName: string, value: any): boolean;
+ }
+ interface Wikifier {
+ createExternalLink(destination: string, url: string, text: string): HTMLElement;
+ createInternalLink(destination: string, passage: string, text: string, callback: () => void): HTMLElement;
+ evalExpression(code: string, output: any): any;
+ evalStatements(code: string, output: any): any;
+ /**
+ * @see State.getVar
+ */
+ getValue(varName: string): any;
+ /**
+ * @see Story.has
+ * @param link link
+ */
+ isExternalLink(link: string): boolean;
+ parse(text: string): any;
+ /**
+ * @see State.setVar
+ */
+ setValue(varName: string, value: any): boolean;
+ wikifyEval(text: string): string;
+ }
- /**
- * Unstows UI bar, so that it is fully accessible again.
- * @since 2.17.0
- */
- unstow(): void;
- }
+ interface ISugarCube {
+ Config: Config;
+ Dialog: Dialog;
+ Engine: Engine;
+ Macro: Macro;
+ Save: Save;
+ State: State;
+ Story: Story;
+ UI: UI;
+ /**
+ * Player settings object, set up by the author/developer. See Setting API for more information.
+ * @since 2.0.0
+ */
+ settings: any;
+ /**
+ * Object that authors/developers may use to set up various bits of static data.
+ *
+ * Generally, you would use this for data that does not change and should not be stored
+ * within story variables, which would make it part of the history.
+ * @since 2.0.0
+ * */
+ setup: any;
- declare interface StoryMoment {
- title: string;
- variables: any;
+ Wikifier: Wikifier;
+ }
}
- declare interface State {
- /**
- * Returns the active (present) moment.
- * @since 2.0.0
- */
- active: StoryMoment;
- /**
- * Returns the bottommost (least recent) moment from the full in-play history (past + future).
- * @since 2.0.0
- */
- bottom: StoryMoment;
- /**
- * Returns the current moment from the full in-play history (past + future), which is the pre-play version of the active
- * moment.
- *
- * WARNING: State.current is not a synonym for State.active. You will, very likely, never need to use State.current
- * directly within your code.
- *
- * @since 2.8.0
- */
- current: StoryMoment;
- /**
- * Returns the number of moments within the past in-play history (past only).
- * @since 2.0.0
- */
- length: number;
- /**
- * Returns the title of the passage associated with the active (present) moment.
- * @since 2.0.0
- */
- passage: string;
- /**
- * Returns the current temporary variables.
- * @since 2.13.0
- */
- temporary: any;
- /**
- * Returns the number of moments within the full in-play history (past + future).
- * @since 2.0.0
- */
- size: number;
- /**
- * Returns the topmost (most recent) moment from the full in-play history (past + future).
- *
- * WARNING: State.top is not a synonym for State.active. You will, very likely, never need to use State.top directly
- * within your code.
- * @since 2.0.0
- */
- top: StoryMoment;
- /**
- * Returns the total number of played moments within the extended past history (expired + past).
- * @since 2.0.0
- */
- turns: number;
- /**
- * Returns the variables from the active (present) moment.
- * @since 2.0.0
- */
- variables: any;
- /**
- * Returns the value of the story or temporary variable by the given name.
- * @param varName The name of the story or temporary variable, including its sigil—e.g. $charName.
- * @since 2.22.0
- */
- getVar(varName: string): any;
- /**
- * Returns whether any moments with the given title exist within the past in-play history (past only).
- *
- * NOTE: State.has() does not check expired moments. If you need to know if the player has ever been to a particular
- * passage, then you must use the State.hasPlayed() method or the hasVisited() story function.
- * @param passageTitle The title of the moment whose existence will be verified.
- * @since 2.0.0
- */
- has(passageTitle: string): boolean;
- /**
- * Returns whether any moments with the given title exist within the extended past history (expired + past).
- *
- * NOTE: If you need to check for multiple passages, the hasVisited() story function will likely be more convenient to
- * use.
- * @param passageTitle The title of the moment whose existence will be verified.
- * @since 2.0.0
- */
- hasPlayed(passageTitle: string): boolean;
- /**
- * Returns the moment, relative to the bottom of the past in-play history (past only), at the given index.
- * @param index The index of the moment to return.
- * @since 2.0.0
- */
- index(index: number): StoryMoment;
- /**
- * Initializes the seedable pseudo-random number generator (PRNG) and integrates it into the story state and saves.
- * Once initialized, the State.random() method and story functions, random() and randomFloat(), return results from
- * the seeded PRNG (by default, they return results from Math.random()).
- *
- * NOTE: State.initPRNG() must be called during story initialization, within either a script section (Twine 2: the
- * Story JavaScript, Twine 1/Twee: a script-tagged passage) or the StoryInit special passage. Additionally, it is
- * recommended that you do not specify any arguments to State.initPRNG() and allow it to automatically seed itself. If
- * you should chose to use an explicit seed, however, it is strongly recommended that you also enable additional
- * entropy, otherwise all playthroughs for all players will be exactly the same.
- * @param seed The explicit seed used to initialize the pseudo-random number generator.
- * @param useEntropy Enables the use of additional entropy to pad the specified explicit seed.
- * @since 2.0.0
- * @example
- * State.initPRNG() // Automatically seed the PRNG (recommended)
- * State.initPRNG("aVeryLongSeed") // Seed the PRNG with "aVeryLongSeed"
- * State.initPRNG("aVeryLongSeed", true) // Seed the PRNG with "aVeryLongSeed" and pad it with extra entropy
- */
- initPRNG(seed?: string, useEntropy?: boolean): void;
- /**
- * Returns whether the full in-play history (past + future) is empty.
- * @since 2.0.0
- */
- isEmpty(): boolean;
- /**
- * Returns the moment, relative to the top of the past in-play history (past only), at the, optional, offset.
- * @param offset The offset, from the top of the past in-play history, of the moment to return. If not given, an offset
- * of 0 is used.
- */
- peek(offset?: number): StoryMoment;
- /**
- * Returns a pseudo-random real number (floating-point) in the range 0 (inclusive) up to, but not including, 1
- * (exclusive).
- *
- * NOTE: By default, it simply returns results from Math.random(), however, when the seedable PRNG has been enabled,
- * via State.initPRNG(), it returns results from the seeded PRNG instead.
- * @since 2.0.0
- */
- random(): number;
- /**
- * Sets the value of the story or temporary variable by the given name. Returns whether the operation was successful.
- * @param varName The name of the story or temporary variable, including its sigil—e.g. $charName.
- * @param value The value to assign.
- * @since 2.22.0
- */
- setVar(varName: string, value: any): boolean;
- };
-
- declare interface Wikifier {
- createExternalLink(destination: string, url: string, text: string): HTMLElement;
- createInternalLink(destination: string, passage: string, text: string, callback: () => void): HTMLElement;
- evalExpression(code: string, output: any): any;
- evalStatements(code: string, output: any): any;
- /**
- * @see State.getVar
- */
- getValue(varName: string): any;
- /**
- * @see Story.has
- * @param link link
- */
- isExternalLink(link: string): boolean;
- parse(text: string): any;
- /**
- * @see State.setVar
- */
- setValue(varName: string, value: any): boolean;
- wikifyEval(text: string): string;
- };
-
- declare interface ISugarCube {
- Config: Config;
- Engine: Engine;
- Macro: Macro;
- Save: Save;
- State: State;
- Story: Story;
- /**
- * Player settings object, set up by the author/developer. See Setting API for more information.
- * @since 2.0.0
- */
- settings: any;
- /**
- * Object that authors/developers may use to set up various bits of static data.
- *
- * Generally, you would use this for data that does not change and should not be stored
- * within story variables, which would make it part of the history.
- * @since 2.0.0
- * */
- setup: any;
-
- Wikifier: Wikifier;
- };
-}
-
-declare global {
- declare var SugarCube: SugarCubeLib.ISugarCube;
+ var SugarCube: SugarCubeLib.ISugarCube;
- declare let setup = SugarCube.setup;
+ const setup: any;
/**
* A prototype-less generic object whose properties and values are defined by the Setting.addToggle(),
* Setting.addList(), and Setting.addRange() methods.
@@ -1345,40 +1344,40 @@ declare global {
* Setting.save() after having done so.
* @since 2.0.0
*/
- declare let settings = SugarCube.settings;
- declare let Config = SugarCube.Config;
- declare let Macro = SugarCube.Macro;
- declare let State = SugarCube.State;
- declare let Story = SugarCube.Story;
- declare let Wikifier = SugarCube.Wikifier;
+ const settings: SugarCubeLib.Settings;
+ const Config: SugarCubeLib.Config;
+ const Macro: SugarCubeLib.Macro;
+ let State: SugarCubeLib.State;
+ let Story: SugarCubeLib.Story;
+ let Wikifier: SugarCubeLib.Wikifier;
/**
* Executed before the modification of the state history.
* @since 2.0.0
*/
- declare let prehistory: Record<string, SugarCube.DisplayTaskFunction>;
+ let prehistory: Record<string, SugarCubeLib.DisplayTaskFunction>;
/**
* Executed before the rendering of the incoming passage.
* @since 2.0.0
*/
- declare let predisplay: Record<string, SugarCube.DisplayTaskFunction>;
+ let predisplay: Record<string, SugarCubeLib.DisplayTaskFunction>;
/**
* Executed before the rendering of the incoming passage.
* @since 2.0.0
*/
- declare let prerender: Record<string, SugarCube.RenderTaskFunction>;
+ let prerender: Record<string, SugarCubeLib.RenderTaskFunction>;
/**
* Executed after the rendering of the incoming passage.
* @since 2.0.0
*/
- declare let postrender: Record<string, SugarCube.RenderTaskFunction>;
+ let postrender: Record<string, SugarCubeLib.RenderTaskFunction>;
/**
* Executed after the display (i.e. output) of the incoming passage.
* @since 2.0.0
*/
- declare let postdisplay: Record<string, SugarCube.DisplayTaskFunction>;
+ let postdisplay: Record<string, SugarCubeLib.DisplayTaskFunction>;
// SugarCube functions
@@ -1405,7 +1404,7 @@ declare global {
* $foo.id -> Returns: 1
* $bar.id -> Returns: 5
*/
- declare function clone(original: any): any;
+ function clone(original: any): any;
/**
* Returns a random value from its given arguments.
@@ -1428,7 +1427,7 @@ declare global {
* // Using multiple arrays; given: $letters = ["A", "B"] & $numerals = ["1", "2"]
* either($letters, $numerals) -> Returns a random value from the whole list (i.e. "A", "B", "1", "2")
*/
- declare function either(...list: any): any;
+ function either(...list: any): any;
/**
* Returns whether the passage with the given title occurred within the story history. If multiple passage titles are given,
@@ -1441,7 +1440,7 @@ declare global {
* <<if hasVisited("Bar", "Café")>>…has been to both the Bar and Café<</if>>
* <<if not hasVisited("Bar", "Café")>>…has never been to either the Bar, Café, or both…<</if>>
*/
- declare function hasVisited(...passageNames: string | string[]): boolean;
+ function hasVisited(...passageNames: string[]): boolean;
/**
* Returns the number of turns that have passed since the last instance of the passage with the given title occurred within
@@ -1456,7 +1455,7 @@ declare global {
* <<if lastVisited("Bar", "Café") is -1>>…has never been to the Bar, Café, or both…<</if>>
* <<if lastVisited("Bar", "Café") is 2>>…has been to both the Bar and Café, most recently two turns ago…<</if>>
*/
- declare function lastVisited(...passageNames: string | string[]): number;
+ function lastVisited(...passageNames: string[]): number;
/**
* Load and integrate external JavaScript scripts.
@@ -1527,7 +1526,7 @@ declare global {
* console.log(err);
* });
*/
- declare function importScripts(...urls: string | string[]): Promise;
+ function importScripts(...urls: string[]): Promise<any>;
/**
* Load and integrate external CSS stylesheets.
@@ -1583,7 +1582,7 @@ declare global {
* console.log(err);
* });
*/
- declare function importStyles(...urls: string | string[]): Promise;
+ function importStyles(...urls: string[]): Promise<any>;
/**
* Returns the title of the active (present) passage.
@@ -1591,7 +1590,7 @@ declare global {
* @example
* <<if passage() is "Café">>…the current passage is the Café passage…<</if>>
*/
- declare function passage(): string;
+ function passage(): string;
/**
* Returns the title of the most recent previous passage whose title does not match that of the active passage or an empty
@@ -1603,7 +1602,7 @@ declare global {
* // Commonly used as part of a link to return to the most recent non-active passage
* [[Return|previous()]]
*/
- declare function previous(): string;
+ function previous(): string;
/**
* Returns a pseudo-random whole number (integer) within the range of the given bounds (inclusive)—i.e. [min, max].
@@ -1617,7 +1616,8 @@ declare global {
* random(5) // Returns a number in the range 0–5
* random(1, 6) // Returns a number in the range 1–6
*/
- declare function random(min?: number, max: number): number;
+ function random(min: number, max: number): number;
+ function random(max: number): number;
/**
* Returns a pseudo-random real number (floating-point) within the range of the given bounds (inclusive for the minimum,
@@ -1632,7 +1632,8 @@ declare global {
* randomFloat(5.0) // Returns a number in the range 0.0–4.9999999…
* randomFloat(1.0, 6.0) // Returns a number in the range 1.0–5.9999999…
*/
- declare function randomFloat(min?: number, max: number): number;
+ function randomFloat(max: number): number;
+ function randomFloat(min: number, max: number): number;
/**
* Renders the selected passage into the target element, replacing any existing content, and returns the element. If no passages are found and default text is specified, it will be used instead.
@@ -1652,7 +1653,7 @@ declare global {
* // Using an element; given a reference to an existing element: myElement
* setPageElement(myElement, "MyPassage");
*/
- declare function setPageElement(
+ function setPageElement(
idOrElement: string | HTMLElement,
passages: string | string[],
defaultText?: string): HTMLElement | null;
@@ -1666,7 +1667,7 @@ declare global {
* <<if tags().includes("forest")>>…the current passage is part of the forest…<</if>>
* <<if tags("Lonely Glade").includes("forest")>>…the Lonely Glade passage is part of the forest…<</if>>
*/
- declare function tags(...passages?: string | string[]): string[];
+ function tags(...passages: string[]): string[];
/**
* Returns a reference to the current temporary variables store (equivalent to: State.temporary). This is only really useful
@@ -1678,7 +1679,7 @@ declare global {
* // Do something...
* }
*/
- declare function temporary(): object;
+ function temporary(): object;
/**
* Returns the number of milliseconds which have passed since the current passage was rendered to the page.
@@ -1697,7 +1698,7 @@ declare global {
* <</link>> \
* or [[stand your ground|Eaten by a grue]]?
*/
- declare function time(): number;
+ function time(): number;
/**
* Returns the number of passages that the player has visited.
@@ -1705,7 +1706,7 @@ declare global {
* @example
* << print "This is turn #" + turns() >>
*/
- declare function turns(): number;
+ function turns(): number;
/**
* Returns a reference to the active(present) story variables store(equivalent to: State.variables).This is only really
@@ -1717,7 +1718,7 @@ declare global {
* //Do something
* }
*/
- declare function variables(): object;
+ function variables(): object;
/**
* Returns the number of times that the passage with the given title occurred within the story history. If multiple passage
@@ -1731,7 +1732,7 @@ declare global {
* <<if visited("Café") is 1>>…has been to the Café exactly once…<</if>>
* <<if visited("Bar", "Café") is 4>>…has been to both the Bar and Café at least four times…<</if>>
*/
- declare function visited(...passages?: string | string[]): number;
+ function visited(...passages: string[]): number;
/**
* Returns the number of passages within the story history which are tagged with all of the given tags.
@@ -1742,9 +1743,9 @@ declare global {
* <<if visitedTags("forest", "haunted") is 1>>…has been to the haunted part of the forest exactly once…<</if>>
* <<if visitedTags("forest", "burned") is 3>>…has been to the burned part of the forest three times…<</if>>
*/
- declare function visitedTags(...tags: string | string[]): number;
+ function visitedTags(...tags: string[]): number;
- declare interface Array<T> {
+ interface Array<T> {
/**
* Concatenates one or more unique members to the end of the base array and returns the result as a new array. Does not modify the original.
* @param members The members to concatenate. Members which are arrays will be merged—i.e. their members will be concatenated, rather than the array itself.
@@ -1794,7 +1795,7 @@ declare global {
* $fruits.deleteAt(1, 3) → Returns ["Oranges", "Oranges"]; $fruits ["Apples", "Plums"]
* $fruits.deleteAt(0, 2) → Returns ["Apples", "Plums"]; $fruits ["Oranges", "Oranges"]
*/
- deleteAt(...indices: number | number[]): T[];
+ deleteAt(...indices: number[]): T[];
/**
* Removes all of the members that pass the test implemented by the given predicate function from the array and returns
@@ -1857,7 +1858,7 @@ declare global {
* // Given: $search = ["Blueberry", "Pumpkin"]
* <<if $pies.includesAll($search)>>…found Blueberry and Pumpkin pies…<</if>>
*/
- includesAll(...needles: T | T[]): boolean;
+ includesAll(...needles: T[]): boolean;
/**
* Returns whether any of the given members were found within the array.
@@ -1870,7 +1871,7 @@ declare global {
* // Given: $search = ["Blueberry", "Pumpkin"]
* <<if $pies.includesAny($search)>>…found Blueberry or Pumpkin pie…<</if>>
*/
- includesAny(...needles: T | T[]): boolean;
+ includesAny(...needles: T[]): boolean;
/**
* Returns the last member from the array. Does not modify the original.
@@ -1950,7 +1951,7 @@ declare global {
* $fruits.unshiftUnique("Oranges") // Returns 2; $fruits ["Oranges", "Plums"]
* $fruits.unshiftUnique("Apples", "Apples") // Returns 3; $fruits ["Apples", "Oranges", "Plums"]
*/
- unshiftUnique(...members?: T): number;
+ unshiftUnique(...members: T[]): number;
// deprecated members
@@ -2021,7 +2022,7 @@ declare global {
* Math.clamp($stat, 0, 200) // Clamps $stat to the bounds 0–200 and returns the new value
* Math.clamp($stat, 1, 6.6) // Clamps $stat to the bounds 1–6.6 and returns the new value
*/
- static clamp(num: number | string, min: number, max: number): number;
+ clamp(num: number | string, min: number, max: number): number;
/**
* Returns the whole(integer) part of the given number by removing its fractional part, if any. Does not modify the
@@ -2032,14 +2033,13 @@ declare global {
* Math.trunc(12.7) // Returns 12
* Math.trunc(-12.7) // Returns -12
*/
- static trunc(num: number): number;
+ trunc(num: number): number;
}
interface JQuery {
wikiWithOptions(options: any, ...sources): JQuery;
wiki(...sources): JQuery;
- };
-
+ }
}
export { };