= when you meant === (or ==) is a fairly easy to mistake make—either from a finger slip or because you just don't know the difference between the operators.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -133,7 +133,7 @@ Sets the maximum number of iterations allowed before the [`<script or stylesheet tagged passages, for Twine 1/Twee, or the Story JavaScript or Story Stylesheet sections, for Twine 2.
-#### Since:
+#### History:
* `v2.19.0`: Introduced.
@@ -309,7 +309,7 @@ Does not affect script or stylesheet tagged passages,
The function will be called just before the built-in no-break passage processing if you're also using that—see the Config.passages.nobr setting and nobr special tag.
-#### Since:
+#### History:
* `v2.30.0`: Introduced.
@@ -328,7 +328,7 @@ Config.passages.onProcess = function (p) {
Sets the starting passage, the very first passage that will be displayed.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -348,7 +348,7 @@ Determines whether outgoing passage transitions are enabled. Valid values are t
If using an integer delay, ideally, it should probably be slightly longer than the outgoing transition delay that you intend to use—e.g., an additional 10ms or so should be sufficient.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -405,7 +405,7 @@ Determines whether the autosave, if it exists, is automatically loaded upon stor
If the autosave cannot be loaded, for any reason, then the start passage is loaded instead.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -434,7 +434,7 @@ Determines whether the autosave is created/updated when passages are displayed.
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 may wish to only disallow saving on the start passage the very first time it's displayed—i.e., at story startup.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.30.0`: Added function values and deprecated string values.
@@ -460,7 +460,7 @@ Config.saves.autosave = function () {
Sets the story ID associated with saves.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -476,7 +476,7 @@ Config.saves.id = "a-big-huge-story-part-1";
Determines whether saving is allowed within the current context. The callback is invoked each time a save is requested. If its return value is falsy, the save is disallowed. If its return value is truthy, the save is allowed to continue unperturbed.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -494,7 +494,7 @@ Config.saves.isAllowed = function () {
Performs any required pre-processing before the save data is loaded—e.g., upgrading out-of-date save data. 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.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -522,7 +522,7 @@ Config.saves.onLoad = function (save) {
Performs any required post-processing before the save data is saved. The callback is passed two parameters, the save object to be processed and save operation details object.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.33.0`: Added save operation details object parameter to the callback function.
@@ -581,7 +581,7 @@ Config.saves.onSave = function (save, details) {
Sets the maximum number of available save slots.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -601,7 +601,7 @@ Sets the `version` property of saves.
This setting is only used to set the version property of saves. Thus, it is only truly useful if you plan to upgrade out-of-date saves via a Config.saves.onLoad callback.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -627,7 +627,7 @@ Config.saves.version = "v3";
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:
+#### History:
* `v2.11.0`: Introduced.
@@ -654,7 +654,7 @@ Determines whether certain elements within the UI bar are updated when passages
The story title is not included in updates because SugarCube uses it as the basis for the key used to store and load data used when playing the story and for saves.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -681,7 +681,7 @@ Determines whether the `link-visited` class is added to internal passage links t
You must provide your own styling for the link-visited class as none is provided by default.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -707,7 +707,7 @@ You will also need to specify a `.link-visited` style that defines the propertie
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 `` elements.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -727,7 +727,7 @@ Indicates whether SugarCube is running in test mode, which enables debug views.
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 option (-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.
Dialog.wiki() method instead.
-#### Since:
+#### History:
* `v2.9.0`: Introduced.
@@ -35,7 +35,7 @@ Dialog.append( /* some DOM nodes */ );
Returns a reference to the dialog's content area.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -55,7 +55,7 @@ jQuery(Dialog.body()).wiki("Cry 'Havoc!', and let slip the //ponies// of ''frien
Closes the dialog. Returns a reference to the `Dialog` object for chaining.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -73,7 +73,7 @@ Dialog.close();
Returns whether the dialog is currently open.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -103,7 +103,7 @@ Opens the dialog. Returns a reference to the `Dialog` object for chaining.
Call this only after populating the dialog with content.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -130,7 +130,7 @@ Dialog.open();
Prepares the dialog for use and returns a reference to its content area.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -168,7 +168,7 @@ Renders the given [markup](#markup) and appends it to the dialog's content area.
If your content consists of DOM nodes, you'll need to use the Dialog.append() method instead.
-#### Since:
+#### History:
* `v2.9.0`: Introduced.
@@ -190,7 +190,7 @@ Dialog.wiki("Cry 'Havoc!', and let slip the //ponies// of ''friendship''.");
This method has been deprecated and should no longer be used. The core of what it does is simply to wrap a call to Dialog.open() within a call to <jQuery>.ariaClick(), which can be done directly and with greater flexibility.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.29.0`: Deprecated.
diff --git a/docs/api/api-engine.md b/docs/api/api-engine.md
index fc0db95..bd6746c 100644
--- a/docs/api/api-engine.md
+++ b/docs/api/api-engine.md
@@ -9,7 +9,7 @@
Returns a timestamp representing the last time `Engine.play()` was called.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -25,7 +25,7 @@ Engine.lastPlay → The timestamp at which Engine.play() was last called
Returns the current state of the engine (`"idle"`, `"playing"`, `"rendering"`).
-#### Since:
+#### History:
* `v2.7.0`: Introduced.
@@ -47,7 +47,7 @@ Engine.state → Returns the current state of the engine
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:
+#### History:
* `v2.0.0`: Introduced.
@@ -65,7 +65,7 @@ Engine.backward() → Rewinds the full history by one moment—i.e., undoes the
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:
+#### History:
* `v2.0.0`: Introduced.
@@ -83,7 +83,7 @@ Engine.forward() → Fast forwards the full history by one moment—i.e., redoe
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).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -104,7 +104,7 @@ Engine.go(-4) → Rewinds the full history by four moments—i.e., undoes the m
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).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -125,7 +125,7 @@ Engine.goTo(9) → Goes to the tenth moment
Returns whether the engine is idle.
-#### Since:
+#### History:
* `v2.16.0`: Introduced.
@@ -143,7 +143,7 @@ Engine.isIdle() → Returns whether the engine is idle
Returns whether the engine is processing a turn—i.e., passage navigation has been triggered.
-#### Since:
+#### History:
* `v2.16.0`: Introduced.
@@ -161,7 +161,7 @@ Engine.isPlaying() → Returns whether the engine is playing
Returns whether the engine is rendering the incoming passage.
-#### Since:
+#### History:
* `v2.16.0`: Introduced.
@@ -179,7 +179,7 @@ Engine.isRendering() → Returns whether the engine is rendering
Renders and displays the passage referenced by the given title, optionally without adding a new moment to the history.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -209,7 +209,7 @@ The player will not be prompted and all unsaved state will be lost.
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:
+#### History:
* `v2.0.0`: Introduced.
@@ -227,7 +227,7 @@ Engine.restart() → Restarts the story
Renders and displays the active (present) moment's associated passage without adding a new moment to the history.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
diff --git a/docs/api/api-fullscreen.md b/docs/api/api-fullscreen.md
index 0879690..83a53a5 100644
--- a/docs/api/api-fullscreen.md
+++ b/docs/api/api-fullscreen.md
@@ -35,7 +35,7 @@ The Fullscreen API comes with some built-in limitations:
Returns the current fullscreen element or, if fullscreen mode is not active, `null`.
-#### Since:
+#### History:
* `v2.31.0`: Introduced.
@@ -51,7 +51,7 @@ Fullscreen.element → The current fullscreen element
Returns whether fullscreen is both supported and enabled.
-#### Since:
+#### History:
* `v2.31.0`: Introduced.
@@ -69,7 +69,7 @@ Fullscreen.isEnabled() → Whether fullscreen mode is available
Returns whether fullscreen mode is currently active.
-#### Since:
+#### History:
* `v2.31.0`: Introduced.
@@ -91,7 +91,7 @@ Request that the browser enter fullscreen mode.
Backgrounds and limitations.
-#### Since:
+#### History:
* `v2.31.0`: Introduced.
@@ -135,7 +135,7 @@ Fullscreen.request({ navigationUI : "show" }, myElement);
Request that the browser exit fullscreen mode.
-#### Since:
+#### History:
* `v2.31.0`: Introduced.
@@ -154,7 +154,7 @@ Fullscreen.exit();
Request that the browser toggle fullscreen mode—i.e., enter or exit as appropriate.
-#### Since:
+#### History:
* `v2.31.0`: Introduced.
@@ -185,7 +185,7 @@ Fullscreen.toggle({ navigationUI : "show" }, myElement);
Attaches fullscreen change event handlers.
-#### Since:
+#### History:
* `v2.31.0`: Introduced.
@@ -220,7 +220,7 @@ Fullscreen.onChange(function (ev) {
Removes fullscreen change event handlers.
-#### Since:
+#### History:
* `v2.31.0`: Introduced.
@@ -263,7 +263,7 @@ Fullscreen.offChange(originalHandlerFn, myElement);
Attaches fullscreen error event handlers.
-#### Since:
+#### History:
* `v2.31.0`: Introduced.
@@ -298,7 +298,7 @@ Fullscreen.onError(function (ev) {
Removes fullscreen error event handlers.
-#### Since:
+#### History:
* `v2.31.0`: Introduced.
diff --git a/docs/api/api-loadscreen.md b/docs/api/api-loadscreen.md
index 8f3273a..117553f 100644
--- a/docs/api/api-loadscreen.md
+++ b/docs/api/api-loadscreen.md
@@ -13,7 +13,7 @@ To simply add a delay to the dismissal of the loading screen to hide initial fla
Acquires a loading screen lock and returns its ID. Displays the loading screen, if necessary.
-#### Since:
+#### History:
* `v2.15.0`: Introduced.
@@ -31,7 +31,7 @@ LoadScreen.lock() → Locks the loading screen and returns the lock ID
Releases the loading screen lock with the given ID. Hides the loading screen, if no other locks exist.
-#### Since:
+#### History:
* `v2.15.0`: Introduced.
diff --git a/docs/api/api-macro.md b/docs/api/api-macro.md
index 3da1a78..f3a8aa7 100644
--- a/docs/api/api-macro.md
+++ b/docs/api/api-macro.md
@@ -13,7 +13,7 @@
Add new macro(s).
-#### Since:
+#### History:
* `v2.0.0`: Introduced
* `v2.33.0`: Obsoleted the `deep` parameter.
@@ -67,7 +67,7 @@ Macro.add('if', {
Remove existing macro(s).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -88,7 +88,7 @@ Macro.delete(["amacro", "bmacro"])
Return the named macro definition, or `null` on failure.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -108,7 +108,7 @@ Macro.get("print")
Returns whether the named macro exists.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -128,7 +128,7 @@ Macro.has("print")
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.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -148,7 +148,7 @@ Macro.tags.get("else") → For the standard library, returns: ["if"]
Returns whether the named macro tag exists.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
diff --git a/docs/api/api-macrocontext.md b/docs/api/api-macrocontext.md
index fe9690c..0fbffee 100644
--- a/docs/api/api-macrocontext.md
+++ b/docs/api/api-macrocontext.md
@@ -15,7 +15,7 @@ Macro handlers are called with no arguments, but with their `this` set to a macr
The argument string parsed into an array of discrete arguments.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -35,7 +35,7 @@ this.args[2] → Returns 'c'
The argument string after converting all TwineScript syntax elements into their native JavaScript counterparts.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -52,7 +52,7 @@ this.args.full → Returns '"a" === "b"'
The unprocessed argument string.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -69,7 +69,7 @@ this.args.raw → Returns '"a" is "b"'
The name of the macro.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -86,7 +86,7 @@ this.name → Returns 'someMacro'
The current output element.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -96,7 +96,7 @@ The current output element.
The (execution) context object of the macro's parent, or `null` if the macro has no parent.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -106,7 +106,7 @@ The (execution) context object of the macro's parent, or `null` if the macro has
The parser instance that generated the macro call.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -122,7 +122,7 @@ The text of a container macro parsed into discrete payload objects by tag. Payl
* **`args.raw`:** (*string*) The current tag's unprocessed argument string. Equivalent in function to [`<<capture>>. If you don't know what that means, then this API is likely not for you.
-#### Since:
+#### History:
* `v2.14.0`: Introduced.
* `v2.23.3`: Fixed an issue where shadows would fail for multiple layers of nested asynchronous code due to loss of context.
@@ -269,7 +269,7 @@ $someElement.on('some_event', this.createShadowWrapper(
Renders the message prefixed with the name of the macro and returns `false`.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
diff --git a/docs/api/api-passage.md b/docs/api/api-passage.md
index c7676cb..2fad5bd 100644
--- a/docs/api/api-passage.md
+++ b/docs/api/api-passage.md
@@ -13,7 +13,7 @@ All properties of `Passage` objects should be treated as if they were ***read-on
The DOM ID of the passage, created from the slugified passage title.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -23,7 +23,7 @@ The DOM ID of the passage, created from the slugified passage title.
The tags of the passage.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -33,7 +33,7 @@ The tags of the passage.
The raw text of the passage.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -43,7 +43,7 @@ The raw text of the passage.
The title of the passage.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -53,7 +53,7 @@ The title of the passage.
Returns the description of the passage, created from either an excerpt of the passage or the [`Config.passages.descriptions` setting](#config-api-property-passages-descriptions).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -73,7 +73,7 @@ passage.description() → Returns the description of "The Ducky" passage
Returns the processed text of the passage, created from applying `nobr` tag and image passage processing to its raw text.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
diff --git a/docs/api/api-save.md b/docs/api/api-save.md
index ef6f465..d7ef0b7 100644
--- a/docs/api/api-save.md
+++ b/docs/api/api-save.md
@@ -55,7 +55,7 @@ Each **`moment`** object has the following properties:
Deletes all slot saves and the autosave, if it's enabled.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -77,7 +77,7 @@ Returns the saves object.
**NOTE:** Using `storage.get("saves")` to retrieve the saves object could return `null`, since an empty saves object does not get stored. This method, which guarantees the return of a saves object, should be used instead.
-->
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -95,7 +95,7 @@ Save.get()
Returns whether both the slot saves and autosave are available and ready.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -121,7 +121,7 @@ if (Save.ok()) {
Returns the total number of available slots.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -137,7 +137,7 @@ Save.slots.length
Returns the total number of filled slots.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -155,7 +155,7 @@ Save.slots.count()
Deletes a save from the given slot.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -175,7 +175,7 @@ Save.slots.delete(5) → Deletes the sixth slot save
Returns a save object from the given slot or `null`, if there was no save in the given slot.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -195,7 +195,7 @@ Save.slots.get(5) → Returns the sixth slot save
Returns whether the given slot is filled.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -217,7 +217,7 @@ if (Save.slots.has(5)) {
Returns whether there are any filled slots.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -235,7 +235,7 @@ Save.slots.isEmpty() → Effectively returns: Save.slots.count() === 0
Loads a save from the given slot.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -255,7 +255,7 @@ Save.slots.load(5) → Load the sixth slot save
Returns whether the slot saves are available and ready.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -275,7 +275,7 @@ if (Save.slots.ok()) {
Saves to the given slot.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -313,7 +313,7 @@ Save.slots.save(5, "Midgar", someMetadata)
Deletes the autosave.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -331,7 +331,7 @@ Save.autosave.delete() → Deletes the autosave
Returns the save object from the autosave or `null`, if there was no autosave.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -349,7 +349,7 @@ Save.autosave.get() → Returns the autosave
Returns whether the autosave is filled.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -369,7 +369,7 @@ if (Save.autosave.has()) {
Loads the autosave.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -387,7 +387,7 @@ Save.autosave.load() → Load the autosave
Returns whether the autosave is available and ready.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -407,7 +407,7 @@ if (Save.autosave.ok()) {
Saves to the autosave.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -444,7 +444,7 @@ Save.autosave.save("Midgar", someMetadata)
Saves to disk.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.8.0`: Added `metadata` parameter.
@@ -478,7 +478,7 @@ Loads a save from disk.
**NOTE:** You do not call this manually, it *must* be called by the `change` event handler of an `` element.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -544,7 +544,7 @@ jQuery(input).on('change', function (ev) {
Returns a save as a serialized string, or `null` if saving is not allowed within the current context.
-#### Since:
+#### History:
* `v2.21.0`: Introduced.
@@ -574,7 +574,7 @@ if (myGameState === null) {
Deserializes the given save string, created via [`Save.serialize()`](#save-api-method-serialize), and loads the save. Returns the bundled metadata, if any, or `null` if the given save could not be deserialized and loaded.
-#### Since:
+#### History:
* `v2.21.0`: Introduced.
diff --git a/docs/api/api-setting.md b/docs/api/api-setting.md
index d8ebb1e..4ff3ff7 100644
--- a/docs/api/api-setting.md
+++ b/docs/api/api-setting.md
@@ -11,7 +11,7 @@ Manages the Settings dialog and [`settings` object](#setting-api-object-settings
Adds a header to the Settings dialog.
-#### Since:
+#### History:
* `v2.7.1`: Introduced.
@@ -36,7 +36,7 @@ Setting.addHeader("Content Settings", "Settings controlling what content is made
Adds the named property to the `settings` object and a toggle control for it to the Settings dialog.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.26.0`: Added `desc` property to definition object.
@@ -101,7 +101,7 @@ html.widescreen #passages {
Adds the named property to the `settings` object and a list control for it to the Settings dialog.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.26.0`: Added `desc` property to definition object.
@@ -180,7 +180,7 @@ $("html")
Adds the named property to the `settings` object and a range control for it to the Settings dialog.
-#### Since:
+#### History:
* `v2.26.0`: Introduced.
@@ -233,7 +233,7 @@ Loads the settings from storage.
The API automatically calls this method at startup, so you should never need to call this method manually.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -251,7 +251,7 @@ Setting.load();
Resets the setting with the given name to its default value. If no name is given, resets all settings.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -279,7 +279,7 @@ Saves the settings to storage.
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:
+#### History:
* `v2.0.0`: Introduced.
@@ -299,6 +299,6 @@ A prototype-less generic object whose properties and values are defined by the [
Normally, the values of its properties are automatically managed by their associated Settings dialog control. If necessary, however, you may manually change their values—n.b. you'll need to call the [`Setting.save()`](#setting-api-method-save) after having done so.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
diff --git a/docs/api/api-simpleaudio-audiolist.md b/docs/api/api-simpleaudio-audiolist.md
index 1fd4be2..92daf8e 100644
--- a/docs/api/api-simpleaudio-audiolist.md
+++ b/docs/api/api-simpleaudio-audiolist.md
@@ -15,7 +15,7 @@ Audio lists (playlists) are useful for playing tracks in a sequence—i.e., one
Returns the playlist's total playtime in seconds, `Infinity` if it contains any streams, or `NaN` if no metadata exists.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -37,7 +37,7 @@ Starts playback of the playlist and fades the currently playing track between th
The Config.audio.pauseOnFadeToZero setting (default: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
* `v2.29.0`: Updated to return a `Promise`.
@@ -61,7 +61,7 @@ aList.fade(6, 1, 0);
Starts playback of the playlist and fades the currently playing track from the specified volume level to `1` (loudest) over the specified number of seconds.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
* `v2.29.0`: Updated to return a `Promise`.
@@ -88,7 +88,7 @@ Starts playback of the playlist and fades the currently playing track from the s
The Config.audio.pauseOnFadeToZero setting (default: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
* `v2.29.0`: Updated to return a `Promise`.
@@ -115,7 +115,7 @@ Interrupts an in-progress fade of the currently playing track, or does nothing i
This does not alter the volume level.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -133,7 +133,7 @@ aList.fadeStop();
Returns whether playback of the playlist has ended.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -153,7 +153,7 @@ if (aList.isEnded()) {
Returns whether a fade is in-progress on the currently playing track.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -173,7 +173,7 @@ if (aList.isFading()) {
Returns whether playback of the playlist has been paused.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -193,7 +193,7 @@ if (aList.isPaused()) {
Returns whether the playlist is playing.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -213,7 +213,7 @@ if (aList.isPlaying()) {
Returns whether playback of the playlist has been stopped.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -237,7 +237,7 @@ Pauses playback of the playlist and, if they're not already in the process of lo
This should not be done lightly if your audio sources are on the network, as it forces players to begin downloading them.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -255,7 +255,7 @@ aList.load();
Gets or sets the playlist's repeating playback state (default: `false`). When used to set the loop state, returns a reference to the current `AudioList` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -282,7 +282,7 @@ aList.loop(false);
Gets or sets the playlist's volume mute state (default: `false`). When used to set the mute state, returns a reference to the current `AudioList` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -309,7 +309,7 @@ aList.mute(false);
Pauses playback of the playlist.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -327,7 +327,7 @@ aList.pause();
Begins playback of the playlist.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
* `v2.29.0`: Updated to return a `Promise`.
@@ -360,7 +360,7 @@ aList.play()
Begins playback of the playlist or, failing that, sets the playlist to begin playback as soon as the player has interacted with the document.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -378,7 +378,7 @@ aList.playWhenAllowed();
Returns how much remains of the playlist's total playtime in seconds, `Infinity` if it contains any streams, or `NaN` if no metadata exists.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -396,7 +396,7 @@ var listRemains = aList.remaining();
Gets or sets the playlist's randomly shuffled playback state (default: `false`). When used to set the shuffle state, returns a reference to the current `AudioList` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -423,7 +423,7 @@ aList.shuffle(false);
Skips ahead to the next track in the playlist, if any.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -441,7 +441,7 @@ someTrack.skip();
Stops playback of the playlist.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -459,7 +459,7 @@ someTrack.stop();
Returns the playlist's current time in seconds, or `NaN` if no metadata exists.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -481,7 +481,7 @@ Stops playback of the playlist and forces its tracks to drop any existing data.
Once unloaded, playback cannot occur until the track's data is loaded again.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -499,7 +499,7 @@ aList.unload();
Gets or sets the playlist's volume level (default: `1`). When used to set the volume, returns a reference to the current `AudioList` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
diff --git a/docs/api/api-simpleaudio-audiorunner.md b/docs/api/api-simpleaudio-audiorunner.md
index 019295e..75f2f17 100644
--- a/docs/api/api-simpleaudio-audiorunner.md
+++ b/docs/api/api-simpleaudio-audiorunner.md
@@ -19,7 +19,7 @@ Starts playback of the selected tracks and fades them between the specified star
The Config.audio.pauseOnFadeToZero setting (default: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -42,7 +42,7 @@ someTracks.fade(6, 1, 0);
Starts playback of the selected tracks and fades them from the specified volume level to `1` (loudest) over the specified number of seconds.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -68,7 +68,7 @@ Starts playback of the selected tracks and fades them from the specified volume
The Config.audio.pauseOnFadeToZero setting (default: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -94,7 +94,7 @@ Interrupts an in-progress fade of the selected tracks, or does nothing if no fad
This does not alter the volume level.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -116,7 +116,7 @@ Pauses playback of the selected tracks and, if they're not already in the proces
This should not be done lightly if your audio sources are on the network, as it forces players to begin downloading them.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -134,7 +134,7 @@ someTracks.load();
Sets the selected tracks' repeating playback state (default: `false`). Returns a reference to the current `AudioRunner` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -158,7 +158,7 @@ someTracks.loop(false);
Sets the selected tracks' volume mute state (default: `false`). Returns a reference to the current `AudioRunner` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -190,7 +190,7 @@ Shorthand for jQuery's .off()
The SimpleAudio APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -221,7 +221,7 @@ Shorthand for jQuery's .on() me
The SimpleAudio APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -254,7 +254,7 @@ Shorthand for jQuery's .one()
The SimpleAudio APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -279,7 +279,7 @@ someTracks.one('ended.myEvents', function () {
Pauses playback of the selected tracks.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -297,7 +297,7 @@ someTracks.pause();
Begins playback of the selected tracks.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -315,7 +315,7 @@ someTracks.play();
Begins playback of the selected tracks or, failing that, sets the tracks to begin playback as soon as the player has interacted with the document.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -333,7 +333,7 @@ someTracks.playWhenAllowed();
Stops playback of the selected tracks.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -351,7 +351,7 @@ someTracks.stop();
Sets the selected tracks' current time in seconds. Returns a reference to the current `AudioRunner` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -376,7 +376,7 @@ Stops playback of the selected tracks and forces them to drop any existing data.
Once unloaded, playback cannot occur until the selected tracks' data is loaded again.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -394,7 +394,7 @@ someTracks.unload();
Sets the selected tracks' volume level (default: `1`). Returns a reference to the current `AudioRunner` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
diff --git a/docs/api/api-simpleaudio-audiotrack.md b/docs/api/api-simpleaudio-audiotrack.md
index b2b3bf7..ccbe422 100644
--- a/docs/api/api-simpleaudio-audiotrack.md
+++ b/docs/api/api-simpleaudio-audiotrack.md
@@ -15,7 +15,7 @@ Audio tracks encapsulate and provide a consistent interface to an audio resource
Returns a new independent copy of the track.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -33,7 +33,7 @@ var trackCopy = aTrack.clone();
Returns the track's total playtime in seconds, `Infinity` for a stream, or `NaN` if no metadata exists.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -55,7 +55,7 @@ Starts playback of the track and fades it between the specified starting and des
The Config.audio.pauseOnFadeToZero setting (default: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -78,7 +78,7 @@ aTrack.fade(6, 1, 0);
Starts playback of the track and fades it from the specified volume level to `1` (loudest) over the specified number of seconds.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
* `v2.29.0`: Updated to return a `Promise`.
@@ -105,7 +105,7 @@ Starts playback of the track and fades it from the specified volume level to `0`
The Config.audio.pauseOnFadeToZero setting (default: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
* `v2.29.0`: Updated to return a `Promise`.
@@ -132,7 +132,7 @@ Interrupts an in-progress fade of the track, or does nothing if no fade is progr
This does not alter the volume level.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -154,7 +154,7 @@ Returns whether enough data has been loaded to play the track through to the end
This is an estimate calculated by the browser based upon the currently downloaded data and the download rate.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -174,7 +174,7 @@ if (aTrack.hasData()) {
Returns whether, at least, the track's metadata has been loaded.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -194,7 +194,7 @@ if (aTrack.hasMetadata()) {
Returns whether none of the track's data has been loaded.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -218,7 +218,7 @@ Returns whether, at least, some of the track's data has been loaded.
The <AudioTrack>.hasData() method is generally more useful.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -238,7 +238,7 @@ if (aTrack.hasSomeData()) {
Returns whether any valid sources were registered.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -258,7 +258,7 @@ if (aTrack.hasSource()) {
Returns whether playback of the track has ended.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -278,7 +278,7 @@ if (aTrack.isEnded()) {
Returns whether a fade is in-progress on the track.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -298,7 +298,7 @@ if (aTrack.isFading()) {
Returns whether an error has occurred.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -318,7 +318,7 @@ if (aTrack.isFailed()) {
Returns whether the track is loading data.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -340,7 +340,7 @@ Returns whether playback of the track has been paused.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -360,7 +360,7 @@ if (aTrack.isPaused()) {
Returns whether the track is playing.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -380,7 +380,7 @@ if (aTrack.isPlaying()) {
Returns whether the track is seeking.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -400,7 +400,7 @@ if (aTrack.isSeeking()) {
Returns whether playback of the track has been stopped.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -420,7 +420,7 @@ if (aTrack.isStopped()) {
Returns whether the track is currently unavailable for playback. Possible reasons include: no valid sources are registered, no sources are currently loaded, an error has occurred.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -440,7 +440,7 @@ if (aTrack.isUnavailable()) {
Returns whether the track's sources are currently unloaded.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -464,7 +464,7 @@ Pauses playback of the track and, if it's not already in the process of loading,
This should not be done lightly if your audio sources are on the network, as it forces players to begin downloading them.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -482,7 +482,7 @@ aTrack.load();
Gets or sets the track's repeating playback state (default: `false`). When used to set the loop state, returns a reference to the current `AudioTrack` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -509,7 +509,7 @@ aTrack.loop(false);
Gets or sets the track's volume mute state (default: `false`). When used to set the mute state, returns a reference to the current `AudioTrack` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -544,7 +544,7 @@ Shorthand for jQuery's .off()
The SimpleAudio APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -575,7 +575,7 @@ Shorthand for jQuery's .on() me
The SimpleAudio APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -608,7 +608,7 @@ Shorthand for jQuery's .one()
The SimpleAudio APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -633,7 +633,7 @@ aTrack.one('ended.myEvents', function () {
Pauses playback of the track.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -651,7 +651,7 @@ aTrack.pause();
Begins playback of the track.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -683,7 +683,7 @@ aTrack.play()
Begins playback of the track or, failing that, sets the track to begin playback as soon as the player has interacted with the document.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -701,7 +701,7 @@ aTrack.playWhenAllowed();
Returns how much remains of the track's total playtime in seconds, `Infinity` for a stream, or `NaN` if no metadata exists.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -719,7 +719,7 @@ var trackRemains = aTrack.remaining();
Stops playback of the track.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -737,7 +737,7 @@ someTrack.stop();
Gets or sets the track's current time in seconds. When used to set a value, returns a reference to the current `AudioTrack` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -768,7 +768,7 @@ Stops playback of the track and forces it to drop any existing data.
Once unloaded, playback cannot occur until the track's data is loaded again.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -786,7 +786,7 @@ aTrack.unload();
Gets or sets the track's volume level (default: `1`). When used to set the volume, returns a reference to the current `AudioTrack` instance for chaining.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
diff --git a/docs/api/api-simpleaudio.md b/docs/api/api-simpleaudio.md
index ba14767..c733627 100644
--- a/docs/api/api-simpleaudio.md
+++ b/docs/api/api-simpleaudio.md
@@ -34,7 +34,7 @@ Pauses playback of *all* currently registered tracks and, if they're not already
This should not be done lightly if your audio sources are on the network, as it forces players to begin downloading them.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -56,7 +56,7 @@ Displays the loading screen until *all* currently registered audio tracks have e
This should not be done lightly if your audio sources are on the network, as it forces players to begin downloading them.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -74,7 +74,7 @@ SimpleAudio.loadWithScreen();
Gets or sets the mute state for the master volume (default: `false`).
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -101,7 +101,7 @@ SimpleAudio.mute(false);
Gets or sets the mute-on-hidden state for the master volume (default: `false`). The mute-on-hidden state controls whether the master volume is automatically muted/unmuted when the story's browser tab loses/gains visibility. Loss of visibility is defined as when the browser window is either switched to another tab or minimized.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -128,7 +128,7 @@ SimpleAudio.muteOnHidden(false);
Returns an [`AudioRunner` instance](#audiorunner-api) for the tracks matching the given selector.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -176,7 +176,7 @@ SimpleAudio.select(":all:not(:ui)").volume(0.40);
Stops playback of *all* currently registered tracks.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -198,7 +198,7 @@ Stops playback of *all* currently registered tracks and force them to drop any e
Once a track has been unloaded, playback cannot occur until it is reloaded.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -216,7 +216,7 @@ SimpleAudio.unload();
Gets or sets the master volume level (default: `1`).
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -246,7 +246,7 @@ SimpleAudio.volume(0.75);
Adds an audio track with the given track ID.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -281,7 +281,7 @@ Deletes all audio tracks.
Cannot delete tracks solely under the control of a playlist.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -307,7 +307,7 @@ Cannot delete tracks solely under the control of a playlist.
Does not currently remove the track from either groups or playlists. Thus, any groups or playlists containing the deleted track should be rebuilt.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -331,7 +331,7 @@ Returns the [`AudioTrack` instance](#audiotrack-api) with the given track ID, or
To affect multiple tracks and/or groups at once, see the SimpleAudio.select() method.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -360,7 +360,7 @@ SimpleAudio.tracks.get("swamped").volume(1).play();
Returns whether an audio track with the given track ID exists.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -392,7 +392,7 @@ Adds an audio group with the given group ID. Groups are useful for applying act
If you want to play tracks in a sequence, then you want a playlist instead.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -418,7 +418,7 @@ Deletes all audio groups.
Only deletes the groups themselves, does not affect their component tracks.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -440,7 +440,7 @@ Deletes the audio group with the given group ID.
Only deletes the group itself, does not affect its component tracks.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -464,7 +464,7 @@ Returns the array of track IDs with the given group ID, or `null` on failure.
To actually affect multiple tracks and/or groups, see the SimpleAudio.select() method.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -484,7 +484,7 @@ SimpleAudio.groups.get(":ui") → Returns the array of track IDs matching ":ui"
Returns whether an audio group with the given group ID exists.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -516,7 +516,7 @@ Adds a playlist with the given list ID. Playlists are useful for playing tracks
If you simply want to apply actions to multiple tracks simultaneously, then you want a group instead.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
* `v2.29.0`: Changed descriptor object `copy` property to `own`.
@@ -609,7 +609,7 @@ SimpleAudio.lists.add("bgm_lacuna",
Deletes all playlists.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -627,7 +627,7 @@ SimpleAudio.lists.clear();
Deletes the playlist with the given list ID.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -647,7 +647,7 @@ SimpleAudio.lists.delete("bgm_lacuna");
Returns the [`AudioList` instance](#audiolist-api) with the given list ID, or `null` on failure.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
@@ -676,7 +676,7 @@ SimpleAudio.lists.get("bgm_lacuna").volume(1).loop(true).play();
Returns whether a playlist with the given list ID exists.
-#### Since:
+#### History:
* `v2.28.0`: Introduced.
diff --git a/docs/api/api-state.md b/docs/api/api-state.md
index 69c1aaf..9bf54eb 100644
--- a/docs/api/api-state.md
+++ b/docs/api/api-state.md
@@ -19,7 +19,7 @@ Returns the active (present) moment.
Using State.active directly is generally unnecessary as there exist a number of shortcut properties, State.passage and State.variables, and story functions, passage() and variables(), which grant access to its normal properties.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -36,7 +36,7 @@ State.active.variables → The variables of the present moment
Returns the bottommost (least recent) moment from the full in-play history (past + future).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -57,7 +57,7 @@ Returns the current moment from the full in-play history (past + future), which
State.current is not a synonym for State.active. You will, very likely, never need to use State.current directly within your code.
-#### Since:
+#### History:
* `v2.8.0`: Introduced.
@@ -74,7 +74,7 @@ State.current.variables → The variables of the current moment within the full
Returns the number of moments within the past in-play history (past only).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -92,7 +92,7 @@ if (State.length === 0) {
Returns the title of the passage associated with the active (present) moment.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -108,7 +108,7 @@ State.passage → The passage title of the present moment
Returns the number of moments within the full in-play history (past + future).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -128,7 +128,7 @@ if (State.size === 0) {
Returns the current temporary variables.
-#### Since:
+#### History:
* `v2.13.0`: Introduced.
@@ -148,7 +148,7 @@ Returns the topmost (most recent) moment from the full in-play history (past + f
State.top is not a synonym for State.active. You will, very likely, never need to use State.top directly within your code.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -165,7 +165,7 @@ State.top.variables → The variables of the most recent moment within the full
Returns the total number (count) of played moments within the extended past history (expired + past).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -183,7 +183,7 @@ if (State.turns === 1) {
Returns the variables from the active (present) moment.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -199,7 +199,7 @@ State.variables → The variables of the present moment
Returns the value of the story or temporary variable by the given name.
-#### Since:
+#### History:
* `v2.22.0`: Introduced.
@@ -223,7 +223,7 @@ Returns whether any moments with the given title exist within the past in-play h
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.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -247,7 +247,7 @@ Returns whether any moments with the given title exist within the extended past
If you need to check for multiple passages, the hasVisited() story function will likely be more convenient to use.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -267,7 +267,7 @@ State.hasPlayed("The Ducky") → Returns whether a moment matching "The Ducky"
Returns the moment, relative to the bottom of the past in-play history (past only), at the given index.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -289,7 +289,7 @@ State.index(State.length - 1) → Returns the most recent moment within the pas
Returns whether the full in-play history (past + future) is empty.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -309,7 +309,7 @@ if (State.isEmpty()) {
Returns the moment, relative to the top of the past in-play history (past only), at the, optional, offset.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -332,7 +332,7 @@ State.peek(State.length - 1) → Returns the least recent moment within the pas
Returns the size of the story metadata store—i.e., the number of stored pairs.
-#### Since:
+#### History:
* `v2.30.0`: Introduced.
@@ -351,7 +351,7 @@ if (State.metadata.size > 0) {
Empties the story metadata store.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -370,7 +370,7 @@ State.metadata.clear();
Removes the specified key, and its associated value, from the story metadata store.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -391,7 +391,7 @@ State.metadata.delete('achievements');
Returns the value associated with the specified key from the story metadata store.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -412,7 +412,7 @@ var playerAchievements = State.metadata.get('achievements');
Returns whether the specified key exists within the story metadata store.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -447,7 +447,7 @@ The story metadata store is not, and should not be use
This feature is largely incompatible with private browsing modes, which cause all in-browser storage mechanisms to either persist only for the lifetime of the browsing session or fail outright.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -476,7 +476,7 @@ Initializes the seedable pseudo-random number generator (PRNG) and integrates it
State.prng.init() 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 strongly recommended that you do not specify any arguments to State.prng.init() 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.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -499,7 +499,7 @@ State.prng.init("aVeryLongSeed", true) → Seed the PRNG with "aVeryLongSeed" a
Returns whether the [seedable PRNG](#state-api-method-prng-init) has been enabled.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -519,7 +519,7 @@ Returns the current pull count—i.e., how many requests have been made—from t
The pull count is automatically included within saves and sessions, so this is not especially useful outside of debugging purposes.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -539,7 +539,7 @@ Returns the seed from the [seedable PRNG](#state-api-method-prng-init) or, if th
The seed is automatically included within saves and sessions, so this is not especially useful outside of debugging purposes.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -559,7 +559,7 @@ Returns a pseudo-random decimal number (floating-point) in the range `0` (inclus
By default, it simply returns non-deterministic results from Math.random(), however, when the seedable PRNG has been enabled, via State.prng.init(), it returns deterministic results from the seeded PRNG instead.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -577,7 +577,7 @@ State.random() → Returns a pseudo-random floating-point number in the range [
Sets the value of the story or temporary variable by the given name. Returns whether the operation was successful.
-#### Since:
+#### History:
* `v2.22.0`: Introduced.
@@ -600,7 +600,7 @@ State.setVar("$charName", "Jane Doe") → Assigns the string "Jane Doe" to $cha
This method has been deprecated and should no longer be used. See the State.prng.init() method for its replacement.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.29.0`: Deprecated in favor of `State.prng.init()`.
diff --git a/docs/api/api-story.md b/docs/api/api-story.md
index 6b776c0..609d775 100644
--- a/docs/api/api-story.md
+++ b/docs/api/api-story.md
@@ -9,7 +9,7 @@
The DOM ID of the story, created from the slugified story title.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -19,7 +19,7 @@ The DOM ID of the story, created from the slugified story title.
The IFID (Interactive Fiction IDentifier) of the story, if any.
-#### Since:
+#### History:
* `v2.5.0`: Introduced.
@@ -29,7 +29,7 @@ The IFID (Interactive Fiction IDentifier) of the story, if any.
The title of the story.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -43,7 +43,7 @@ Returns the `Passage` object referenced by the given title, or an empty `Passage
This method will not return "code" passages—i.e., script, stylesheet, and widget passages.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -67,7 +67,7 @@ Returns whether a `Passage` object referenced by the given title exists.
This method will not detect "code" passages—i.e., script, stylesheet, and widget passages.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -91,7 +91,7 @@ Returns a new array filled with all `Passage` objects that contain the given pro
This method will not return "code" passages—i.e., script, stylesheet, and widget passages.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -118,7 +118,7 @@ Returns a new array filled with all `Passage` objects that pass the test impleme
This method will not return "code" passages—i.e., script, stylesheet, and widget passages.
-#### Since:
+#### History:
* `v2.11.0`: Introduced.
diff --git a/docs/api/api-template.md b/docs/api/api-template.md
index 400f3ac..8335cbe 100644
--- a/docs/api/api-template.md
+++ b/docs/api/api-template.md
@@ -9,7 +9,7 @@
Returns the number of existing templates.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -27,7 +27,7 @@ if (Template.size === 0) {
Add new template(s).
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -88,7 +88,7 @@ Template.add(['color', 'Color'], function () {
Remove existing template(s).
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -112,7 +112,7 @@ Template.delete(['yolo', 'nolf']);
Return the named template definition, or `null` on failure.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -133,7 +133,7 @@ var yolo = Template.get('yolo');
Returns whether the named template exists.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
diff --git a/docs/api/api-ui.md b/docs/api/api-ui.md
index 70d6c09..6bf82b9 100644
--- a/docs/api/api-ui.md
+++ b/docs/api/api-ui.md
@@ -9,7 +9,7 @@
Opens the built-in alert dialog, displaying the given message to the player.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -31,7 +31,7 @@ UI.alert("You smell of elderberries!");
Opens the built-in jump to dialog, which is populated via the [`bookmark` tag](#special-tag-bookmark).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -52,7 +52,7 @@ UI.jumpto();
Opens the built-in restart dialog, prompting the player to restart the story.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -72,7 +72,7 @@ UI.restart();
Opens the built-in saves dialog.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -93,7 +93,7 @@ UI.saves();
Opens the built-in settings dialog, which is populated from the [`Setting` API](#setting-api).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -114,7 +114,7 @@ UI.settings();
Opens the built-in share dialog, which is populated from the [`StoryShare` passage](#special-passage-storyshare).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
diff --git a/docs/api/api-uibar.md b/docs/api/api-uibar.md
index 691f3a3..8bae4f7 100644
--- a/docs/api/api-uibar.md
+++ b/docs/api/api-uibar.md
@@ -9,7 +9,7 @@
Completely removes the UI bar and all of its associated styles and event handlers.
-#### Since:
+#### History:
* `v2.17.0`: Introduced.
@@ -31,7 +31,7 @@ Hides the UI bar. Returns a reference to the `UIBar` object for chaining.
This does not reclaim the space reserved for the UI bar. Thus, a call to UIBar.stow() may also be necessary. Alternatively, if you simply want the UI bar gone completely and permanently, either using UIBar.destroy() or the StoryInterface special passage may be a better choice.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -57,7 +57,7 @@ UIBar.hide().stow();
Returns whether the UI bar is currently hidden.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -81,7 +81,7 @@ if (!UIBar.isHidden()) {
Returns whether the UI bar is currently stowed.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -105,7 +105,7 @@ if (!UIBar.isStowed()) {
Shows the UI bar. Returns a reference to the `UIBar` object for chaining.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -131,7 +131,7 @@ UIBar.unstow().show();
Stows the UI bar, so that it takes up less space. Returns a reference to the `UIBar` object for chaining.
-#### Since:
+#### History:
* `v2.17.0`: Introduced.
* `v2.29.0`: Added returned `UIBar` chaining reference.
@@ -160,7 +160,7 @@ UIBar.stow(true);
Unstows the UI bar, so that it is fully accessible again. Returns a reference to the `UIBar` object for chaining.
-#### Since:
+#### History:
* `v2.17.0`: Introduced.
* `v2.29.0`: Added returned `UIBar` chaining reference.
@@ -193,7 +193,7 @@ Updates all sections of the UI bar that are populated by special passages—e.g.
As all special passage populated sections are updated it is recommended that UIBar.update() be used sparingly. Ideally, if you need to update UI bar content outside of the normal passage navigation update, then you should update only the specific areas you need to rather than the entire UI bar.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
diff --git a/docs/core/events.md b/docs/core/events.md
index 2018e5a..a943d90 100644
--- a/docs/core/events.md
+++ b/docs/core/events.md
@@ -33,7 +33,7 @@ Global event triggered as the last step in closing the dialog when [`Dialog.clos
You cannot obtain data about the closing dialog from the dialog itself—e.g., title or classes—when using the :dialogclosed event, as the dialog has already closed and been reset by the time the event is fired. If you need that kind of information from the dialog itself, then you may use the :dialogclosing event instead.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -63,7 +63,7 @@ $(document).one(':dialogclosed', function (ev) {
Global event triggered as the first step in closing the dialog when [`Dialog.close()`](#dialog-api-method-close) is called.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -93,7 +93,7 @@ $(document).one(':dialogclosing', function (ev) {
Global event triggered as the last step in opening the dialog when [`Dialog.open()`](#dialog-api-method-open) is called.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -123,7 +123,7 @@ $(document).one(':dialogopened', function (ev) {
Global event triggered as the first step in opening the dialog when [`Dialog.open()`](#dialog-api-method-open) is called.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -190,7 +190,7 @@ In order of processing: *(for reference, this also shows tasks and various speci
Triggered before the modification of the state history.
-#### Since:
+#### History:
* `v2.20.0`: Introduced.
@@ -218,7 +218,7 @@ $(document).one(':passageinit', function (ev) {
Triggered before the rendering of the incoming passage.
-#### Since:
+#### History:
* `v2.20.0`: Introduced.
@@ -261,7 +261,7 @@ $(document).on(':passagestart', function (ev) {
Triggered after the rendering of the incoming passage.
-#### Since:
+#### History:
* `v2.20.0`: Introduced.
@@ -304,7 +304,7 @@ $(document).on(':passagerender', function (ev) {
Triggered after the display—i.e., output—of the incoming passage.
-#### Since:
+#### History:
* `v2.20.0`: Introduced.
* `v2.31.0`: Added `content` property to event object.
@@ -348,7 +348,7 @@ $(document).on(':passagedisplay', function (ev) {
Triggered at the end of passage navigation.
-#### Since:
+#### History:
* `v2.20.0`: Introduced.
* `v2.31.0`: Added `content` property to event object.
@@ -394,7 +394,7 @@ $(document).on(':passageend', function (ev) {
prehistory tasks have been deprecated and should no longer be used. See the :passageinit event for its replacement.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.31.0`: Deprecated.
@@ -407,7 +407,7 @@ $(document).on(':passageend', function (ev) {
predisplay tasks have been deprecated and should no longer be used. See the :passagestart event for its replacement.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.31.0`: Deprecated.
@@ -420,7 +420,7 @@ $(document).on(':passageend', function (ev) {
prerender tasks have been deprecated and should no longer be used. See the :passagestart event for its replacement.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.31.0`: Deprecated.
@@ -433,7 +433,7 @@ $(document).on(':passageend', function (ev) {
postrender tasks have been deprecated and should no longer be used. See the :passagerender event for its replacement.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.31.0`: Deprecated.
@@ -446,7 +446,7 @@ $(document).on(':passageend', function (ev) {
postdisplay tasks have been deprecated and should no longer be used. See the :passagedisplay event for its replacement.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.31.0`: Deprecated.
@@ -473,7 +473,7 @@ To add or remove event listeners to audio tracks managed by the ended and pause for information on somewhat similar native events.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -563,7 +563,7 @@ System events allow the execution of JavaScript code at specific points during s
Global event triggered once just before the dismissal of the loading screen at startup.
-#### Since:
+#### History:
* `v2.31.0`: Introduced.
@@ -584,7 +584,7 @@ $(document).one(':storyready', function (ev) {
Global event triggered once just before the page is reloaded when [`Engine.restart()`](#engine-api-method-restart) is called.
-#### Since:
+#### History:
* `v2.23.0`: Introduced.
@@ -617,7 +617,7 @@ Global event triggered when all `<<<type>> macro invocations after a :typingcomplete event has been fired will cause another event to eventually be generated, since you're creating a new sequence of typing.
-#### Since:
+#### History:
* `v2.32.0`: Introduced.
@@ -638,7 +638,7 @@ $(document).on(':typingcomplete', function (ev) {
Local event triggered on the typing wrapper when the typing of a section starts.
-#### Since:
+#### History:
* `v2.32.0`: Introduced
* `v2.33.0`: Changed to a local event that bubbles up the DOM tree.
@@ -660,7 +660,7 @@ $(document).on(':typingstart', function (ev) {
Local event triggered on the typing wrapper when the typing of a section stops.
-#### Since:
+#### History:
* `v2.32.0`: Introduced
* `v2.33.0`: Changed to a local event that bubbles up the DOM tree.
diff --git a/docs/core/functions.md b/docs/core/functions.md
index d5bdaab..4db42e8 100644
--- a/docs/core/functions.md
+++ b/docs/core/functions.md
@@ -13,7 +13,7 @@ Returns a deep copy of the given value.
Only the primitives, generic objects, some JavaScript natives (specifically: Array, Date, Map, RegExp, and Set), and DOM node objects are supported by default. Unsupported object types, either native or custom, will need to implement .clone() method to be properly supported by the cone() function—when called on such an object, it will simply defer to the local method; see the Non-generic object types (a.k.a. classes) guide for more information.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -43,7 +43,7 @@ $bar.id → Returns: 5
Returns a random value from its given arguments.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -77,7 +77,7 @@ Removes the specified key, and its associated value, from the story metadata sto
memorize(), recall().
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -97,7 +97,7 @@ Removes the specified key, and its associated value, from the story metadata sto
Returns whether the passage with the given title occurred within the story history. If multiple passage titles are given, returns the logical-AND aggregate of the set—i.e., `true` if all were found, `false` if any were not found.
-#### Since:
+#### History:
* `v2.7.0`: Introduced.
@@ -120,7 +120,7 @@ Returns whether the passage with the given title occurred within the story histo
Returns the number of turns that have passed since the last instance of the passage with the given title occurred within the story history or `-1` if it does not exist. If multiple passage titles are given, returns the lowest count (which can be `-1`).
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -152,7 +152,7 @@ Loading is done asynchronously at run time, so if the script must be available w
A script section (Twine 2: the Story JavaScript; Twine 1/Twee: a script-tagged passage) is normally the best place to call importScripts().
-#### Since:
+#### History:
* `v2.16.0`: Introduced.
@@ -240,7 +240,7 @@ Loading is done asynchronously at run time, so if the stylesheet must be availab
A script section (Twine 2: the Story JavaScript; Twine 1/Twee: a script-tagged passage) is normally the best place to call importStyles().
-#### Since:
+#### History:
* `v2.16.0`: Introduced.
@@ -322,7 +322,7 @@ This feature is largely incompatible with private browsing modes, which cause al
forget(), recall().
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -347,7 +347,7 @@ This feature is largely incompatible with private browsing modes, which cause al
Returns the title of the active (present) passage.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -365,7 +365,7 @@ Returns the title of the active (present) passage.
Returns the title of the most recent previous passage whose title does not match that of the active passage or an empty string, if there is no such passage.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -390,7 +390,7 @@ Returns a pseudo-random whole number (integer) within the range of the given bou
By default, it uses Math.random() as its source of (non-deterministic) randomness, however, when the seedable PRNG has been enabled, via State.prng.init(), it uses that (deterministic) seeded PRNG instead.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -416,7 +416,7 @@ Returns a pseudo-random decimal number (floating-point) within the range of the
By default, it simply returns non-deterministic results from Math.random(), however, when the seedable PRNG has been enabled, via State.prng.init(), it returns deterministic results from the seeded PRNG instead.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -442,7 +442,7 @@ Returns the value associated with the specified key from the story metadata stor
forget(), memorize().
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -467,7 +467,7 @@ Returns the value associated with the specified key from the story metadata stor
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.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -497,7 +497,7 @@ setPageElement(myElement, "MyPassage");
Returns a new array consisting of all of the tags of the given passages.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -518,7 +518,7 @@ Returns a new array consisting of all of the tags of the given passages.
Returns a reference to the current temporary variables store (equivalent to: [`State.temporary`](#state-api-getter-temporary)). This is only really useful within pure JavaScript code, as within TwineScript you may simply access temporary variables natively.
-#### Since:
+#### History:
* `v2.19.0`: Introduced.
@@ -539,7 +539,7 @@ if (temporary().selection === 'Zagnut Bar') {
Returns the number of milliseconds that have passed since the current passage was rendered to the page.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -568,7 +568,7 @@ or [[stand your ground|Eaten by a grue]]?
Returns the total number (count) of played turns currently in effect—i.e., the number of played moments up to the present moment; future (rewound/undone) moments are not included within the total.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -586,7 +586,7 @@ Returns the total number (count) of played turns currently in effect—i.e., the
Returns a reference to the active (present) story variables store (equivalent to: [`State.variables`](#state-api-getter-variables)). This is only really useful within pure JavaScript code, as within TwineScript you may simply access story variables natively.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -607,7 +607,7 @@ if (variables().hasGoldenKey) {
Returns the number of times that the passage with the given title occurred within the story history. If multiple passage titles are given, returns the lowest count.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -630,7 +630,7 @@ Returns the number of times that the passage with the given title occurred withi
Returns the number of passages within the story history that are tagged with all of the given tags.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
diff --git a/docs/core/macros.md b/docs/core/macros.md
index 239044b..a99a730 100644
--- a/docs/core/macros.md
+++ b/docs/core/macros.md
@@ -66,7 +66,7 @@ Captures story $variables and temporary \_variables, creating localized versions
Use of this macro is only necessary when you need to localize a variable's value for use with an asynchronous macro—i.e., a macro whose contents are executed at some later time, rather than when it's invoked; e.g., interactive macros, <<repeat>>, <<timed>>. Generally, this means only when the variable's value will change between the time the asynchronous macro is invoked and when it's activated—e.g., a loop variable.
-#### Since:
+#### History:
* `v2.14.0`: Introduced.
@@ -100,7 +100,7 @@ Use of this macro is only necessary when you need to localize a variabl
Sets story $variables and temporary \_variables based on the given expression.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -193,7 +193,7 @@ Sets story $variables and temporary \_variables based on the given expression.
Unsets story $variables and temporary \_variables.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -216,7 +216,7 @@ Unsets story $variables and temporary \_variables.
This macro has been deprecated and should no longer be used. See the memorize() and recall() functions for its replacement.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.29.0`: Deprecated in favor of `memorize()` and `recall()`.
@@ -229,7 +229,7 @@ This macro has been deprecated and should no longer be used. See the forget() function for its replacement.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.29.0`: Deprecated in favor of `forget()`.
@@ -256,7 +256,7 @@ Silently executes its contents as *pure* JavaScript code—i.e., it performs no
The predefined variable output, which is a reference to a local content buffer, is available for use within the macro's code contents. Once the code has been fully executed, the contents of the buffer, if any, will be output.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -293,7 +293,7 @@ Outputs the result of the given expression. This macro is an alias for [`<nobr special tag and Config.passages.nobr setting applies the same processing to an entire passage or all passages, respectively. The line continuation markup performs a similar function, though in a slightly different way.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -409,7 +409,7 @@ Outputs the result of the given expression.
If you only need to print the value of a TwineScript variable, then you may simply include it in your normal passage text and it will be printed automatically via the naked variable markup.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -433,7 +433,7 @@ You weigh <Config.macros.typeSkipKey, Config.macros.typeVisitedPassages, <<type>> Events.
-#### Since:
+#### History:
* `v2.32.0`: Introduced.
* `v2.33.0`: Added `class`, `element`, and `id` options and `macro-type-done` class.
@@ -560,7 +560,7 @@ The default cursor is the block element character **Right Half Block (U+2590)**
This macro has been deprecated and should no longer be used. See the <<include>> macro for its replacement.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.15.0`: Deprecated in favor of `<<<if>> macros, so that authors don't have to resort to various kludges to get whitespace where they want it. This means, however, that extra care must be taken when writing them to ensure that unwanted whitespace is not created within the final output.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -784,7 +784,7 @@ Repeatedly executes its contents. There are three forms: a conditional-only form
<<break>> and <<continue>>.
-##### Since:
+##### History:
* `v2.0.0`: Introduced.
* `v2.20.0`: Added range form.
@@ -898,7 +898,7 @@ Strings are iterated by Unicode code point, however, due to historic reasons the
Used within [`<<<default>> macros, so that authors don't have to resort to various kludges to get whitespace where they want it. However, this means that extra care must be taken when writing them to ensure that unwanted whitespace is not created within the final output.
-#### Since:
+#### History:
* `v2.7.2`: Introduced.
@@ -997,7 +997,7 @@ Creates a button that silently executes its contents when clicked, optionally fo
This macro is functionally identical to <<link>>, save that it uses a button element (<button>) rather than an anchor element (<a>).
-#### Since:
+#### History:
* `v2.8.0`: Introduced.
@@ -1040,7 +1040,7 @@ Creates a checkbox, used to modify the value of the variable with the given name
Interactive macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.32.0`: Added `autocheck` keyword.
@@ -1101,7 +1101,7 @@ Creates a cycling link, used to modify the value of the variable with the given
Interactive macro warning.
-#### Since:
+#### History:
* `v2.29.0`: Introduced.
@@ -1191,7 +1191,7 @@ Creates a link that silently executes its contents when clicked, optionally forw
If you simply need a passage link that modifies variables, both the link markup and image markup offer setter variants.
-#### Since:
+#### History:
* `v2.8.0`: Introduced.
@@ -1234,7 +1234,7 @@ Creates a single-use link that deactivates itself and appends its contents to it
Interactive macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -1264,7 +1264,7 @@ Creates a single-use link that deactivates itself and prepends its contents to i
Interactive macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -1294,7 +1294,7 @@ Creates a single-use link that deactivates itself and replaces its link text wit
Interactive macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -1324,7 +1324,7 @@ Creates a listbox, used to modify the value of the variable with the given name.
Interactive macro warning.
-#### Since:
+#### History:
* `v2.26.0`: Introduced.
* `v2.27.0`: Added `autoselect` keyword.
@@ -1414,7 +1414,7 @@ Creates a number input box, used to modify the value of the variable with the gi
Interactive macro warning.
-#### Since:
+#### History:
* `v2.32.0`: Introduced.
@@ -1451,7 +1451,7 @@ Creates a radio button, used to modify the value of the variable with the given
Interactive macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.32.0`: Added `autocheck` keyword.
@@ -1511,7 +1511,7 @@ Creates a multiline text input block, used to modify the value of the variable w
Interactive macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -1543,7 +1543,7 @@ Creates a text input box, used to modify the value of the variable with the give
Interactive macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -1578,7 +1578,7 @@ What's your favorite pie? <<<link>> macro for its replacement.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.8.0`: Deprecated in favor of `<>`.
@@ -1595,7 +1595,7 @@ This macro has been deprecated and should no longer be used. See the <<return>> macro or the previous() function.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -1701,7 +1701,7 @@ Creates a single-use passage link that deactivates itself and all other `<<<back>> macro.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -1831,7 +1831,7 @@ Adds classes to the selected element(s).
DOM macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -1858,7 +1858,7 @@ Executes its contents and appends the output to the contents of the selected ele
DOM macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.25.0`: Added `transition` and `t8n` keywords.
@@ -1915,7 +1915,7 @@ Most interactive elements—e.g., passage links, i
DOM macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -1952,7 +1952,7 @@ Executes its contents and prepends the output to the contents of the selected el
DOM macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.25.0`: Added `transition` and `t8n` keywords.
@@ -2009,7 +2009,7 @@ Removes the selected element(s).
If you simply want to empty the selected element(s), not remove them outright, you should use an empty <<replace>> macro instead.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -2042,7 +2042,7 @@ Removes classes from the selected element(s).
DOM macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -2070,7 +2070,7 @@ Executes its contents and replaces the contents of the selected element(s) with
DOM macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.25.0`: Added `transition` and `t8n` keywords.
@@ -2123,7 +2123,7 @@ Toggles classes on the selected element(s)—i.e., adding them if they don't exi
DOM macro warning.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
@@ -2169,7 +2169,7 @@ The <<audio>> macro cannot affect playlist tracks that
The Config.audio.pauseOnFadeToZero setting (default: true) controls whether tracks that have been faded to 0 volume (silent) are automatically paused.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.1.0`: Added `fadeoverto` action.
@@ -2303,7 +2303,7 @@ Caches an audio track for use by the other audio macros.
The StoryInit special passage is normally the best place to set up tracks.
-#### Since:
+#### History:
* `v2.0.0`: Introduced.
* `v2.28.0`: Deprecated the old optional format specifier syntax in favor of a new syntax (`formatId|`).
@@ -2339,7 +2339,7 @@ Collects tracks, which must be set up via [`<StoryInit special passage is normally the best place to set up groups.
-#### Since:
+#### History:
* `v2.19.0`: Introduced.
@@ -2379,7 +2379,7 @@ Collects tracks, which must be set up via [`<StoryInit special passage is normally the best place to set up playlists.
-#### Since:
+#### History:
* `v2.8.0`: Introduced.
* `v2.29.0`: Deprecated `<