Requirements. Returns the bundled metadata, if any, or null if the given save could not be deserialized and loaded. Executes its contents while the given conditional expression evaluates to true. Several UI API methods have moved to the new Dialog API. For example, the following is the data URI of a Base64-encoded PNG image of a red dot (): Generally, it's expected that you will use a compiler that supports the automatic creation of media passages, however, they may be created manually. There are cases, however, where things get a bit more complicated, namely: instances where you need to pass the name of a variable as an argument, rather than its value, and those where you want to pass the result of an expression as argument. Generates no output. Determines whether certain elements within the UI bar are updated when passages are displayed. Roughly equivalent to the :passagestart event. Starts playback of the selected tracks and fades them between the specified starting and destination volume levels over the specified number of seconds. Its contents are treated as raw HTML markupi.e., none of SugarCube's special HTML processing is performed. Returns whether a fade is in-progress on the track. Due to a flaw in the current release of Twine1/Twee (v1.4.2), if you rename the directory included in the archive (or simply copy its contents to your current SugarCube v2 install), then you must ensure that the file with the extension .py (the story format's custom Twine1 Header class file) within is named the same as the directoryi.e., the name of the directory and .py file must match. Outputs the contents of the passage with the given name, optionally wrapping it within an HTML element. depending on the age of your browser, you may also see a list of all current variables when interacting with the Add field. Note: Creates a single-use link that deactivates itself and appends its contents to its link text when clicked. You will also need to specify a .link-visited style that defines the properties visited links should have. Load and integrate external JavaScript scripts. For example, a common use of <
> is to perform various actions before forwarding the player to another passage. Note: For example: While every valid expressioneven those you might not expectyields a value, there are essentially two types of expressions: those with side effects and those without. See Engine API for more information. Passage display. Returns a random member from the array or array-like object. It is unlikely that you will ever want to disable this setting. Causes leading/trailing newlines to be removed and all remaining sequences of newlines to be replaced with single spaces before the passage is rendered. Unsupported object types, either native or custom, will need to implement .clone() method to be properly supported by the clone() functionwhen called on such an object, it will simply defer to the local method; see the Non-generic object types (a.k.a. Make sure to keep the files together if you move them out of the included directory. See the <
> macro for its replacement. Expressions are simply units of code that yield values when evaluated. Deletes the audio group with the given group ID. Story API. Zorkish Sugarcube 6. Warning: Selects the element that contains passage elements. The story metadata, like saves, is tied to the specific story it was generated with. Harlowe is the default style for Twine 2.0 and uses a syntax that is different than Sugarcube. Outputs a copy of the contents of the selected element(s). Returns an AudioRunner instance for the tracks matching the given selector. However, I've tried to use elements in these arrays, like this: $y=$z [0] [2] and it doesn't seem to work. The debug views may be toggled via the Views button. The debug bar (bottom right corner of the page) allows you to: watch the values of story and temporary variables, toggle the debug views, and jump to any moment/turn within the history. See Config.macros.maxLoopIterations for more information. Note: Wikifies the given content source(s) and discards the result. The variable watch panel may be toggled via the Watch button. The cycling options are populated via <> and/or <>. This does not alter the volume level. This is not an exhaustive list. Tip: The new l10nStrings object has a simpler, flatter, set of properties and better support for replacement strings. Loop variables are perfect candidates for the use of temporary variablese.g.. To ensure that line-breaks end up where you want them, or not, extra care may be required. For example: That probably won't be very pleasing to the eye, however, so you will likely need several styles to make something that looks half-decent. If the condition evaluates to false and an <> or <> exists, then other contents can be executed. Generates no output. Opens the built-in alert dialog, displaying the given message to the player. Each moment contains data regarding the active passage and the state of all story variablesthat is, the ones you use the $ sigil to interact withas they exist when the moment is created. Returns the value associated with the specified key from the story metadata store. Player settings object, set up by the author/developer. In SugarCube you can convert them if you need to. State.has() does not check expired moments. For example, let's return to the example above and change it again: You'll see that setup.y is being set to 1 and displayed properly regardless of whether you load a saved story or not, because it is not part of the state. To pass expressions or the results of functions to macros as an argument, you must wrap the expression in backquotes (`). Tip: They serve the same basic purpose as the <> macro, but are run each time passage navigation occurs. See the Test Mode guide for more information. SugarCube features a configurable autosave system. most recent commit 3 months ago. Returns a reference to the UIBar object for chaining. Stops playback of the track and forces it to drop any existing data. Creates a link that navigates forward to a previously visited passage. Displays the loading screen until all currently registered audio has either loaded to a playable state or aborted loading due to errors. In addition to the history, there is also the active momenti.e., presentand expired momentsi.e., moments that had been played, but have expired from the history, thus cannot be navigated to. This method has been deprecated and should no longer be used. If its return value is falsy, the override is cancelled and navigation to the original destination continues unperturbed. For those versions that do, the updates are normally completely elective and may be addressed at your leisure, or not at all. Unlike other code or text in a Passage, variables most commonly start with either the dollar sign ($) or the underscore ( _) in the Harlowe and SugarCube story formats. It consists of one or more right angle brackets, each additional one beyond the first signifying a level of nested blockquote. When the story is restarted by SugarCube rather than refreshed via the browser, the playthrough session, if any, is not loaded. And feedback from the folks over at the Twine Games Discord Server. May be called with either the link text and passage name as separate arguments, a link markup, or an image markup. Warning: This setting exists because it's unlikely that you'll ever want to actually perform an assignment within a conditional expression and typing = when you meant === (or ==) is a fairly easy to mistake makeeither from a finger slip or because you just don't know the difference between the operators. This method has been deprecated and should no longer be used. Returns a save object from the given slot or null, if there was no save in the given slot. Does not modify the original. Several State API methods have moved to the new Engine API. In Harlowe, the same operation will yield an error: You must convert the values to the same type in Harlowe. Begins playback of the playlist or, failing that, sets the playlist to begin playback as soon as the player has interacted with the document. If your content contains any SugarCube markup, you'll need to use the Dialog.wiki() method instead. Executes its contents and outputs the result, after removing leading/trailing newlines and replacing all remaining sequences of newlines with single spaces. Config.saves.autosave setting, Config.saves.autoload setting, and Save API: Autosave. The audio subsystem that supports the audio macros comes with some built-in limitations and it is strongly recommended that you familiarize yourself with them. Story variables are a part of the story history and exist for the lifetime of a playthrough session. The story's title is part of the story project. Attaches single-use event handlers to the selected tracks. Warning: In the above, the second (set:) macro is never run, and the $count variable remains at 0. 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. Activates the moment at the given offset from the active (present) moment within the full state history and show it. By convention, properties starting with an underscoree.g., _warningIntroLackingare used as templates, only being included within other localized strings. All properties of Passage objects should be treated as if they were read-only, as modifying them could result in unexpected behavior. Mobile browsers can be fickle, so saving to disk may not work as expected in all browsers. LoadScreen API. Valid values are the name of the property being animated, which causes the outgoing passage element to be removed once that transition animation is complete, or an integer delay (in milliseconds), which causes the outgoing passage element to be removed once the delay has expired. The strings API object has been replaced by the l10nStrings object. This macro is an alias for <>. The callback is invoked each time a save is requested. The config API has been renamed Config for better consistency with the other APIs. This section offers a list of SugarCube-specific events, triggered at various points during story operation. Creates a radio button, used to modify the value of the variable with the given name. Deprecated: SugarCube preserves the state of the story as it's being played in a number of ways to both prevent the loss of progress and allow players to save stories. The story metadata store is not, and should not be used as, a replacement for saves. Assignment: The expression causes an assignment to occure.g., A backquote is also known as a grave and is often paired with the tilde (. Additional elements, aside from the #passages element, may include either the data-init-passage or data-passage content attribute, whose value is the name of the passage used to populate the elementthe passage will be processed as normal, meaning that markup and macros will work as expected. Used for post-passage-display tasks, like redoing dynamic changes (happens after the rendering and display of each passage). Finally, one of three things happen (in order): the existing playthrough session is restored, if it exists, else the autosave is loaded, if it exists and is configured to do so, else the starting passage is run. Gets or sets the track's current time in seconds. Does not modify the original. Any passage may be chosen as the starting passage by selecting it via the Start Story Here passage context-menu itemn.b. Happens after the displayi.e., outputof the incoming passage. Note: Equivalent to including the nobr special tag on every passage. The Macros API object has been renamed to Macro and several of its methods have also changed, for better consistency with the other APIs. Furthermore, it is no longer instantiated into the legacy macros objectwhich still exists, so SugarCube-compatible legacy macros will continue to work. Note: Does not modify the original. Determines whether the audio subsystem attempts to preload track metadatameaning information about the track (e.g., duration), not its audio frames. To control aspects of your project based on the values contained within variables, see the <> and <> macros. It is passed an abbreviated version of the associated passage's Passage instancecontaining only the tags, text, and title properties. Returns the topmost (most recent) moment from the full in-play history (past + future). SugarCube 1.x - The legacy version . Caches an audio track for use by the other audio macros. classes) revival code and associated data within the revive wrapper, which should be returned from an object instance's .toJSON() method, so that the instance may be properly revived upon deserialization. Returns a reference to the UIBar object for chaining. String: The expression yields a string valuee.g.. CSS styles cascade in order of load, so if you use multiple stylesheet tagged passages, then it is all too easy for your styles to be loaded in the wrong order, since Twine1/Twee gives you no control over the order that multiple stylesheet tagged passages load. This is an estimate calculated by the browser based upon the currently downloaded data and the download rate. Thus, if you need either to be recoverable, then you'll have to handle that yourself. Triggered before the rendering of the incoming passage. This macro has been deprecated and should no longer be used. All special names listed herein are case sensitive, so their spelling and capitalization must be, When the active passage, it would become the ID. This allows you to fine tune for those cases. Returns whether the engine is processing a turni.e., passage navigation has been triggered. Starts playback of the track and fades it from the specified volume level to 1 (loudest) over the specified number of seconds. Note: Removes all of the members from the array that pass the test implemented by the given predicate function and returns a new array containing the removed members. A version of the above code in SugarCube might look like this: Where Harlowe uses its hook syntax (square brackets) to associate a macro with its contents, SugarCube instead uses "container" macrosmacros that can have content associated with them have opening and closing tags. Attaches fullscreen error event handlers. See the Save.onSave.add() method for its replacement. Passing the name of a variable as an argument is problematic because variable substitution occurs automatically in SugarCube macros. Strings are iterated by Unicode code point, however, due to historic reasons they are comprised of, and indexed by, individual UTF-16 code units. Local event triggered on the typing wrapper when the typing of a section stops. The SimpleAudio APIs use events internally for various pieces of functionality. Returns whether there are any filled slots. Only useful when you have an asynchronous callback that invokes code/content that needs to access story and/or temporary variables shadowed by <>. Returns the playlist's total playtime in seconds, Infinity if it contains any streams, or NaN if no metadata exists. State.current is not a synonym for State.active. See: Playlists are useful for playing tracks in a sequencei.e., one after another. If SugarCube is reloaded by one of its own built-in restart methods, then the session is. Instead, the macro is passed a receiver variable which is set to the value input by the user. For example: See: API members dealing with the history work upon either the active momenti.e., presentor one of the history subsets: the full in-play historyi.e., past + futurethe past in-play subseti.e., past onlyor the extended past subseti.e., expired + past. Because of the additional HTML elements added by the debug views, some nested markup and selectors may be broken. Warning: Used for pre-passage-display tasks, like redoing dynamic changes (happens before the rendering of each passage). Starts playback of the playlist and fades the currently playing track from the specified volume level to 0 (silent) over the specified number of seconds. Collects tracks, which must be set up via <>, into a group via its <> children. Normally, there will be only one such passage per turn, however, during passage navigation there may briefly be twothe incoming (a.k.a. See the :passagedisplay event for its replacement. Attaches fullscreen change event handlers. For the template that should be used as the basis of localizations, see the locale/l10n-template.js file @github.com. Randomly removes the given number of members from the base array and returns the removed members as a new array. This property is automatically set based on whether you're using a testing mode in a Twine compileri.e., Test mode in Twine2, Test Play From Here in Twine1, or the test mode option (-t, --test) in Tweego. The autosave is, for the most part, a normal save slot, but with a few special features built in. IDs and classes automatically generated from passage names and tags are normalized to kebab case with all lowercase letterswhich entails: removing characters that are not alphanumerics, underscores, hyphens, en-/em-dashes, or whitespace, then replacing any remaining non-alphanumeric characters with hyphens, one per group, and finally converting the result to lowercase. Resets the setting with the given name to its default value. Gets or sets the track's repeating playback state (default: false). To affect multiple tracks and/or groups at once, see the SimpleAudio.select() method. postrender tasks have been deprecated and should no longer be used. Each value in an array is assigned an index, which is a number that corresponds to the position of that item or element. The player will not be prompted and all unsaved state will be lost. Returns the AudioList instance with the given list ID, or null on failure. The exactly equivalent call is: .flat(Infinity). To avoid this problem, it's suggested that you use the separate argument form of the <> as there are often better and easier ways to forward the player. The data-init-passage attribute causes the element to be updated once at initialization, while the data-passage attribute causes the element to be updated upon each passage navigation. The documentation for each macro will tell you what it expects. Gets or sets the playlist's volume level (default: 1). Normally, the values of its properties are automatically managed by their associated Settings dialog control. This only affects test mode. Does not modify the original. AudioTrack API, AudioRunner API, and AudioList API. Note: 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. It is not a mechanism for moving data between stories. Moves backward one moment within the full history (past + future), if possible, activating and showing the moment moved to. Navigating back to a previous passage, for whatever reason, can be problematic. Note: Hides the UI bar. When a saved story is loaded, the state loaded from the save replaces the current state. Dialog API. Happens after the rendering of the incoming passage. When used to set the loop state, returns a reference to the current AudioTrack instance for chaining. In my version of Twine, the dialog box looks like this: In this dialog box, select the SugarCube alternative with the latest version number (SugarCube 2.x.x, the higher the numbers the better). The document element. Returns a reference to the active (present) story variables store (equivalent to: State.variables). There are two primary branches of Twine2 as far as SugarCube is concerned: Regardless of the version of Twine2 you're using, follow these instructions to install a local copy of SugarCube v2: Note: Gets or sets the playlist's volume mute state (default: false). To delete all current watches, click the button. The active passage's tags will be added to its data-tags attribute and classes (see: Passage Conversions). NOTE: You do not call this manually, it must be called by the change event handler of an > macros can also accept the link markup as an argument: Note: Request that the browser toggle fullscreen modei.e., enter or exit as appropriate. The core audio subsystem and backend for the audio macros. Removes and returns a random member from the base array. When used to set the mute state, returns a reference to the current AudioList instance for chaining. Note: Returns the value associated with the specified key from the story metadata store or, if no such key exists, the specified default value, if any. Creates a link that silently executes its contents when clicked, optionally forwarding the player to another passage. The pull count is automatically included within saves and sessions, so this is not especially useful outside of debugging purposes. The core of what it does is simply to wrap a call to, This method has been deprecated in favor of the, This method has been deprecated and should no longer be used. Creates a single-use link that deactivates itself and prepends its contents to its link text when clicked. See Also: If you need to run the same code on multiple passages, consider using the PassageDone special passage or, for a JavaScript/TwineScript solution, a :passagedisplay event instead. Closes the dialog. 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. SugarCube automatically stores the current playthrough state to the browser's session storage whenever a new moment is created. Note: Payload objects have the following properties: The macro's definitioncreated via Macro.add(). Once the code has been fully executed, the contents of the buffer, if any, will be output. Returns the description of the passage, created from either an excerpt of the passage or the Config.passages.descriptions setting. Deprecated: The majority of newer SugarCube versions do not have any changes that would require an update. See the Save API docs for more information. See Passage API for more information. Twine2: Unused. Fullscreen API. Returns whether the given substring was found within the string, starting the search at position. Those that bundle SugarCube v2: Any series of Twine2 with a version 2.1. . Passage, tag, and variable names that have special meaning to SugarCube. Intended to be mnemonically better for uses where the expression is arbitrary code, rather than variables to seti.e., <> to run code, <> to set variables. The very first, and mandatory, character is their sigil, which denotes whether they are a story or temporary variable. They are defined via the Template API. Sets the selected tracks' volume mute state (default: false). Global event triggered as the first step in opening the dialog when Dialog.open() is called. You may, however, simply use the Test Play From Here context menu item on the Start passage to achieve the same result. Note: Alias for jQuery, by default. Examples of good uses: achievement tracking, new game+ data, playthrough statistics, etc. Warning: Sylen. Shorthand for jQuery's .off() method applied to the audio element. Returns the playlist's current time in seconds, or NaN if no metadata exists. You should virtually never need to use the verbatim HTML markup. Multiple <> macros may be set up to modify the same variable, which makes them part of a radio button group. May be terminated by a <> macro. Save API. A right angle bracket (>) that begins a line defines the blockquote markup. If you wish to use custom backgrounds, either simply colors or with images, then you should place them on the body element. Performs any required processing before the save data is saved. There are many ways to use and interact with variables. Track event triggered when a fade starts. Many of the commonly used native non-generic object types are already fully compatible with and supported for use within story variablese.g., Array, Date, Map, and Set. Functions, including statici.e., non-instancemethods, due to a few issues. Registers the passage as a VTT passage. The State.display() methodformerly state.display()is no longer overridable, meaning it cannot be wrappede.g., the "StoryRegions" 3rd-party add-ons do this. The _args special variable is used internally to store arguments passed to the widgetas zero-based indices; i.e., _args[0] is the first parsed argument, _args[1] is the second, etcand the full argument string in raw and parsed formsaccessed via the _args.raw and _args.full properties. Loading is done asynchronously at run time, so if the stylesheet must be available within a tight time frame, then you should use the Promise returned by the function to ensure that the stylesheet is loaded before it is needed.