Skip to content

Commit

Permalink
RELEASE: v2.31.0
Browse files Browse the repository at this point in the history
## Changelog:

* Fixed an issue that would cause resetting the settings to default to throw an error.
* Updated the audio macros' "play" actions to use the `SimpleAudio` APIs' various `.playWhenAllowed()` methods.
* Minor internal cleanup.
tmedwards authored Apr 6, 2020
2 parents a2373dd + 66c1445 commit 7e13f26
Showing 13 changed files with 325 additions and 136 deletions.
2 changes: 1 addition & 1 deletion dist/format.js

Large diffs are not rendered by default.

40 changes: 20 additions & 20 deletions docs/core/events.md
Original file line number Diff line number Diff line change
@@ -25,12 +25,12 @@ For standard browser/DOM events, see the <a href="https://developer.mozilla.org/

<!-- *********************************************************************** -->

### `:dialogclosed` event {#events-dialog-event-dialogclosed}
### `:dialogclosed` event<!-- legacy --><span id="dialog-api-event-dialogclosed"></span><!-- /legacy --> {#events-dialog-event-dialogclosed}

Global event triggered as the last step in closing the dialog when [`Dialog.close()`](#dialog-api-method-close) is called.

<p role="note" class="warning"><b>Warning:</b>
You cannot obtain data about the closing dialog from the dialog itself—e.g., title or classes—when using the <code>:dialogclosed</code> 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 <a href="#dialog-api-event-dialogclosing"><code>:dialogclosing</code> event</a> instead.
You cannot obtain data about the closing dialog from the dialog itself—e.g., title or classes—when using the <code>:dialogclosed</code> 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 <a href="#events-dialog-event-dialogclosing"><code>:dialogclosing</code> event</a> instead.
</p>

#### Since:
@@ -59,7 +59,7 @@ $(document).one(':dialogclosed', function (ev) {

<!-- *********************************************************************** -->

### `:dialogclosing` event {#events-dialog-event-dialogclosing}
### `:dialogclosing` event<!-- legacy --><span id="dialog-api-event-dialogclosing"></span><!-- /legacy --> {#events-dialog-event-dialogclosing}

Global event triggered as the first step in closing the dialog when [`Dialog.close()`](#dialog-api-method-close) is called.

@@ -89,7 +89,7 @@ $(document).one(':dialogclosing', function (ev) {

<!-- *********************************************************************** -->

### `:dialogopened` event {#events-dialog-event-dialogopened}
### `:dialogopened` event<!-- legacy --><span id="dialog-api-event-dialogopened"></span><!-- /legacy --> {#events-dialog-event-dialogopened}

Global event triggered as the last step in opening the dialog when [`Dialog.open()`](#dialog-api-method-open) is called.

@@ -119,7 +119,7 @@ $(document).one(':dialogopened', function (ev) {

<!-- *********************************************************************** -->

### `:dialogopening` event {#events-dialog-event-dialogopening}
### `:dialogopening` event<!-- legacy --><span id="dialog-api-event-dialogopening"></span><!-- /legacy --> {#events-dialog-event-dialogopening}

Global event triggered as the first step in opening the dialog when [`Dialog.open()`](#dialog-api-method-open) is called.

@@ -151,7 +151,7 @@ $(document).one(':dialogopening', function (ev) {
<!-- ***************************************************************************
Navigation Events & Tasks
**************************************************************************** -->
## Navigation Events &amp; Tasks {#events-navigation}
## Navigation Events &amp; Tasks<!-- legacy --><span id="navigation-events-tasks"></span><span id="navigation-overview"></span><span id="navigation-events"></span><span id="navigation-tasks"></span><!-- /legacy --> {#events-navigation}

Navigation events, and tasks, allow the execution of JavaScript code at specific points during passage navigation.

@@ -186,7 +186,7 @@ In order of processing: *(for reference, this also shows tasks and various speci

<!-- *********************************************************************** -->

### `:passageinit` event {#events-navigation-event-passageinit}
### `:passageinit` event<!-- legacy --><span id="navigation-event-passageinit"></span><!-- /legacy --> {#events-navigation-event-passageinit}

Triggered before the modification of the state history.

@@ -214,7 +214,7 @@ $(document).one(':passageinit', function (ev) {

<!-- *********************************************************************** -->

### `:passagestart` event {#events-navigation-event-passagestart}
### `:passagestart` event<!-- legacy --><span id="navigation-event-passagestart"></span><!-- /legacy --> {#events-navigation-event-passagestart}

Triggered before the rendering of the incoming passage.

@@ -257,7 +257,7 @@ $(document).on(':passagestart', function (ev) {

<!-- *********************************************************************** -->

### `:passagerender` event {#events-navigation-event-passagerender}
### `:passagerender` event<!-- legacy --><span id="navigation-event-passagerender"></span><!-- /legacy --> {#events-navigation-event-passagerender}

Triggered after the rendering of the incoming passage.

@@ -300,7 +300,7 @@ $(document).on(':passagerender', function (ev) {

<!-- *********************************************************************** -->

### `:passagedisplay` event {#events-navigation-event-passagedisplay}
### `:passagedisplay` event<!-- legacy --><span id="navigation-event-passagedisplay"></span><!-- /legacy --> {#events-navigation-event-passagedisplay}

Triggered after the display—i.e., output—of the incoming passage.

@@ -344,7 +344,7 @@ $(document).on(':passagedisplay', function (ev) {

<!-- *********************************************************************** -->

### `:passageend` event {#events-navigation-event-passageend}
### `:passageend` event<!-- legacy --><span id="navigation-event-passageend"></span><!-- /legacy --> {#events-navigation-event-passageend}

Triggered at the end of passage navigation.

@@ -388,7 +388,7 @@ $(document).on(':passageend', function (ev) {

<!-- *********************************************************************** -->

### `prehistory` tasks {#events-navigation-task-prehistory}
### `prehistory` tasks<!-- legacy --><span id="navigation-task-prehistory"></span><!-- /legacy --> {#events-navigation-task-prehistory}

Executed before the modification of the state history.

@@ -414,7 +414,7 @@ prehistory["Some Task Name"] = function (taskName) {

<!-- *********************************************************************** -->

### `predisplay` tasks {#events-navigation-task-predisplay}
### `predisplay` tasks<!-- legacy --><span id="navigation-task-predisplay"></span><!-- /legacy --> {#events-navigation-task-predisplay}

Executed before the rendering of the incoming passage.

@@ -440,7 +440,7 @@ predisplay["Some Task Name"] = function (taskName) {

<!-- *********************************************************************** -->

### `prerender` tasks {#events-navigation-task-prerender}
### `prerender` tasks<!-- legacy --><span id="navigation-task-prerender"></span><!-- /legacy --> {#events-navigation-task-prerender}

Executed before the rendering of the incoming passage.

@@ -467,7 +467,7 @@ prerender["Some Task Name"] = function (content, taskName) {

<!-- *********************************************************************** -->

### `postrender` tasks {#events-navigation-task-postrender}
### `postrender` tasks<!-- legacy --><span id="navigation-task-postrender"></span><!-- /legacy --> {#events-navigation-task-postrender}

Executed after the rendering of the incoming passage.

@@ -494,7 +494,7 @@ postrender["Some Task Name"] = function (content, taskName) {

<!-- *********************************************************************** -->

### `postdisplay` tasks {#events-navigation-task-postdisplay}
### `postdisplay` tasks<!-- legacy --><span id="navigation-task-postdisplay"></span><!-- /legacy --> {#events-navigation-task-postdisplay}

Executed after the display—i.e., output—of the incoming passage.

@@ -532,7 +532,7 @@ To add or remove event listeners to audio tracks managed by the <a href="#simple

<!-- *********************************************************************** -->

### `:faded` event {#events-simpleaudio-event-faded}
### `:faded` event<!-- legacy --><span id="audiotrack-api-event-faded"></span><!-- /legacy --> {#events-simpleaudio-event-faded}

Track event triggered when a fade completes normally.

@@ -558,7 +558,7 @@ someTracks.on(':faded', function (ev) {

<!-- *********************************************************************** -->

### `:fading` event {#events-simpleaudio-event-fading}
### `:fading` event<!-- legacy --><span id="audiotrack-api-event-fading"></span><!-- /legacy --> {#events-simpleaudio-event-fading}

Track event triggered when a fade starts.

@@ -584,7 +584,7 @@ someTracks.on(':fading', function (ev) {

<!-- *********************************************************************** -->

### `:stopped` event {#events-simpleaudio-event-stopped}
### `:stopped` event<!-- legacy --><span id="audiotrack-api-event-stopped"></span><!-- /legacy --> {#events-simpleaudio-event-stopped}

Track event triggered when playback is stopped after [`<AudioTrack>.stop()`](#audiotrack-api-prototype-method-stop) or [`<AudioRunner>.stop()`](#audiorunner-api-prototype-method-stop) is called—either manually or as part of another process.

@@ -643,7 +643,7 @@ $(document).one(':storyready', function (ev) {

<!-- *********************************************************************** -->

### `:enginerestart` event {#events-system-event-enginerestart}
### `:enginerestart` event<!-- legacy --><span id="engine-api-event-enginerestart"></span><!-- /legacy --> {#events-system-event-enginerestart}

Global event triggered once just before the page is reloaded when [`Engine.restart()`](#engine-api-method-restart) is called.

2 changes: 1 addition & 1 deletion docs/core/markup.md
Original file line number Diff line number Diff line change
@@ -614,7 +614,7 @@ A set of four hyphen/minus characters (`-`) that begins a line defines the horiz
<!-- ***************************************************************************
Verbatim Text
**************************************************************************** -->
## Verbatim Text {#markup-verbatim-text}
## Verbatim Text<!-- legacy --><span id="markup-verbatim"></span><!-- /legacy --> {#markup-verbatim-text}

The verbatim text markup disables processing of *all* markup contained within—both SugarCube and HTML—passing its contents directly into the output as plain text.

8 changes: 4 additions & 4 deletions docs/core/special-names.md
Original file line number Diff line number Diff line change
@@ -20,7 +20,7 @@ Passage, tag, and variable names that have special meaning to SugarCube.

### `PassageDone` {#special-passage-passagedone}

Used for post-passage-display tasks, like redoing dynamic changes (happens after the rendering and display of each passage). Roughly equivalent to the [`:passagedisplay` event](#navigation-event-passagedisplay).
Used for post-passage-display tasks, like redoing dynamic changes (happens after the rendering and display of each passage). Roughly equivalent to the [`:passagedisplay` event](#events-navigation-event-passagedisplay).

#### Since:

@@ -30,7 +30,7 @@ Used for post-passage-display tasks, like redoing dynamic changes (happens after

### `PassageFooter` {#special-passage-passagefooter}

Appended to each rendered passage. Roughly equivalent to the [`:passagerender` event](#navigation-event-passagerender).
Appended to each rendered passage. Roughly equivalent to the [`:passagerender` event](#events-navigation-event-passagerender).

#### Since:

@@ -40,7 +40,7 @@ Appended to each rendered passage. Roughly equivalent to the [`:passagerender`

### `PassageHeader` {#special-passage-passageheader}

Prepended to each rendered passage. Roughly equivalent to the [`:passagestart` event](#navigation-event-passagestart).
Prepended to each rendered passage. Roughly equivalent to the [`:passagestart` event](#events-navigation-event-passagestart).

#### Since:

@@ -50,7 +50,7 @@ Prepended to each rendered passage. Roughly equivalent to the [`:passagestart`

### `PassageReady` {#special-passage-passageready}

Used for pre-passage-display tasks, like redoing dynamic changes (happens before the rendering of each passage). Roughly equivalent to the [`:passagestart` event](#navigation-event-passagestart).
Used for pre-passage-display tasks, like redoing dynamic changes (happens before the rendering of each passage). Roughly equivalent to the [`:passagestart` event](#events-navigation-event-passagestart).

#### Since:

12 changes: 6 additions & 6 deletions docs/guides/guide-code-updates.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- ***********************************************************************************************
Guide: Code Updates
************************************************************************************************ -->
# Guide: Code Updates {#guide-code-updates}
# Guide: Code Updates<!-- legacy --><span id="guide-upgrading"></span><!-- /legacy --> {#guide-code-updates}

This is a reference on how to update existing SugarCube code to work with newer versions of SugarCube.

@@ -172,7 +172,7 @@ All changes within this version are elective changes that you may address at you
<!-- ***************************************************************************
Updating to any version ≥2.15.0 from a lesser version
**************************************************************************** -->
## Updating to any version ≥2.15.0 from a lesser version {#guide-code-updates-2.15.0}
## Updating to any version ≥2.15.0 from a lesser version<!-- legacy --><span id="guide-upgrading-2.15.0"></span><!-- /legacy --> {#guide-code-updates-2.15.0}

All changes within this version are elective changes that you may address at your leisure.

@@ -197,7 +197,7 @@ All changes within this version are elective changes that you may address at you
<!-- ***************************************************************************
Updating to any version ≥2.10.0 from a lesser version
**************************************************************************** -->
## Updating to any version ≥2.10.0 from a lesser version {#guide-code-updates-2.10.0}
## Updating to any version ≥2.10.0 from a lesser version<!-- legacy --><span id="guide-upgrading-2.10.0"></span><!-- /legacy --> {#guide-code-updates-2.10.0}

All changes within this version are elective changes that you may address at your leisure.

@@ -237,7 +237,7 @@ The `strings` API object has been replaced by the `l10nStrings` object. See the
<!-- ***************************************************************************
Updating to any version ≥2.8.0 from a lesser version
**************************************************************************** -->
## Updating to any version ≥2.8.0 from a lesser version {#guide-code-updates-2.8.0}
## Updating to any version ≥2.8.0 from a lesser version<!-- legacy --><span id="guide-upgrading-2.8.0"></span><!-- /legacy --> {#guide-code-updates-2.8.0}

All changes within this version are elective changes that you may address at your leisure.

@@ -274,7 +274,7 @@ All changes within this version are elective changes that you may address at you
<!-- ***************************************************************************
Updating to any version ≥2.5.0 from a lesser version
**************************************************************************** -->
## Updating to any version ≥2.5.0 from a lesser version {#guide-code-updates-2.5.0}
## Updating to any version ≥2.5.0 from a lesser version<!-- legacy --><span id="guide-upgrading-2.5.0"></span><!-- /legacy --> {#guide-code-updates-2.5.0}

All changes within this version are elective changes that you may address at your leisure.

@@ -368,7 +368,7 @@ Several `UI` API methods have moved to the new `Dialog` API. See the [`Dialog`
<!-- ***************************************************************************
Updating to any version ≥2.0.0 from a lesser version
**************************************************************************** -->
## Updating to any version ≥2.0.0 from a lesser version {#guide-code-updates-2.0.0}
## Updating to any version ≥2.0.0 from a lesser version<!-- legacy --><span id="guide-upgrading-2.0.0"></span><!-- /legacy --> {#guide-code-updates-2.0.0}

<p role="note" class="warning"><b>Warning:</b>
All changes within this version are <strong>breaking changes</strong> that you <strong><em>must</em></strong> address immediately.
12 changes: 12 additions & 0 deletions docs/guides/guide-installation.md
Original file line number Diff line number Diff line change
@@ -69,6 +69,18 @@ file:///C:/Users/soandso/Documents/Twine/StoryFormats/SugarCube-2/format.js
```


<!-- ***************************************************************************
Online Installation For Twine 2
**************************************************************************** -->
## Online Install For Twine&nbsp;2 {#guide-installation-twine2-online}

The online SugarCube install, delivered by the [jsDelivr CDN](https://www.jsdelivr.com/), supports only versions of Twine&nbsp;2 ≥2.1.

Copy the following URL and paste it into the *Add a New Format* tab of the *Formats* menu, from Twine&nbsp;2's sidebar.

**URL:** [https://cdn.jsdelivr.net/gh/tmedwards/sugarcube-2/dist/format.js](https://cdn.jsdelivr.net/gh/tmedwards/sugarcube-2/dist/format.js)


<!-- ***************************************************************************
Local Installation For Twine 1/Twee
**************************************************************************** -->
21 changes: 11 additions & 10 deletions docs/table-of-contents.md
Original file line number Diff line number Diff line change
@@ -250,16 +250,16 @@
* [`:dialogopened`](#events-dialog-event-dialogopened)
* [`:dialogopening`](#events-dialog-event-dialogopening)
* [Navigation Events &amp; Tasks](#events-navigation)
* [`:passageinit`](#navigation-event-passageinit)
* [`:passagestart`](#navigation-event-passagestart)
* [`:passagerender`](#navigation-event-passagerender)
* [`:passagedisplay`](#navigation-event-passagedisplay)
* [`:passageend`](#navigation-event-passageend)
* [`prehistory`](#navigation-task-prehistory)
* [`predisplay`](#navigation-task-predisplay)
* [`prerender`](#navigation-task-prerender)
* [`postrender`](#navigation-task-postrender)
* [`postdisplay`](#navigation-task-postdisplay)
* [`:passageinit`](#events-navigation-event-passageinit)
* [`:passagestart`](#events-navigation-event-passagestart)
* [`:passagerender`](#events-navigation-event-passagerender)
* [`:passagedisplay`](#events-navigation-event-passagedisplay)
* [`:passageend`](#events-navigation-event-passageend)
* [`prehistory`](#events-navigation-task-prehistory)
* [`predisplay`](#events-navigation-task-predisplay)
* [`prerender`](#events-navigation-task-prerender)
* [`postrender`](#events-navigation-task-postrender)
* [`postdisplay`](#events-navigation-task-postdisplay)
* [`SimpleAudio` Events](#events-simpleaudio)
* [`:faded`](#events-simpleaudio-event-faded)
* [`:fading`](#events-simpleaudio-event-fading)
@@ -639,6 +639,7 @@

* [Local Install For Tweego](#guide-installation-tweego)
* [Local Install For Twine&nbsp;2](#guide-installation-twine2)
* [Online Install For Twine&nbsp;2](#guide-installation-twine2-online)
* [Local Install For Twine&nbsp;1/Twee](#guide-installation-twine1-twee)

## [Guide: Code Updates](#guide-code-updates)
Loading

0 comments on commit 7e13f26

Please sign in to comment.