twine macro

Twine: HTML5 sound macros

Here's version 1.1.1 of some Twine macros to play sound files with HTML5 audio.

These macros accept either strings or string variables as their first argument. I recommend you set the filenames to specific variables and then use those as arguments to the macros.
<<playsound "carolofthebells.mp3" >> plays the file "carolofthebells.mp3" from the start.
<<loopsound $heartbeat >> starts playing $heartbeat, over and over. Note: currently browsers are not that good at looping audio seamlessly - brief silences between loops may occur.
<<fadeinsound $heartbeat >> is identical to loopsound, but fades in the sound over 2 seconds.
<<unloopsound $heartbeat >> makes $heartbeat no longer repeat when it finishes.
<<stopsound "birds.ogg" >> stops playing "birds.ogg". When <<playsound "birds.ogg" >> is used again, it will start from the beginning.
<<fadeoutsound "birds.ogg" >> is identical to stopsound, but fades out the sound over 2 seconds.
<<pausesound "trees.ogg" >> pauses "trees.ogg" at its current location. Use <<playsound "trees.ogg" >> to resume it.
<<stopallsound>> stops all the sounds.

Important instructions:

  1. This macro does not work if you have ROT13 obfuscation enabled in StorySettings - sorry.
  2. Included with the macros is a script that will preload all of the music files as soon as you begin the game. It does this by searching through all of your passages for anything that resembles a music filename - a string in either single or double quotes that ends with ".ogg", ".mp3", ".wav" or ".webm". Then, it will attempt to load that as a file. I consider this to be simpler and more desired behaviour than explicitly requiring you to put preloader macros at the start of the story, but bear this in mind when you write passages.
  3. For legal and free software advocacy reasons, the Apple and Microsoft browsers (Safari, Internet Explorer) do not support OGG format, whereas the cross-platform browsers (Opera, Firefox) do not support MP3. (Google Chrome supports both.) So, you may have to include your music file in both formats. Give each of these files the same name ("ghost.mp3", "ghost.ogg") and store them in the same directory. You only need to <<playsound>> one of these files - if it can't be played, the other one will be used instead. If you only have the music in one format, consider opening the file in Audacity and saving it using "Export as..." in the File menu.


  4. For short sound effects, it would be safe to use "wav" format for them, but be warned - Wavs don't work in Internet Explorer. So, you may need them in MP3 format too. Again, provided both are available, you only need to use one of them in your <<playsound>> macros.
  5. Implementation-wise, this creates an object, "macros.playsound.soundtracks", which stores Audio objects for every found sound file. I'm not sure if this is the most usable method just yet. This may change in future versions.

There's a lot that can be done to expand on this. Something I might add is a way to bind looping sounds to a specific passage tag. So, you could perhaps write <<tagsound "trees" "Howling_Monkeys.mp3">> and then give a passage a tag of "trees", and it will keep looping "Howling_Monkeys.mp3" if you're at such a passage, and stop it when you leave. Also on the list of possibilities: support for base64-encoded sounds (which no one except me will ever use).


Regard this script as public domain using CC0. I don't really care for attribution - if you're using Twine, you're already running code I wrote. It's welcome if you want, but entirely optional.

Version history:

  1. 29-9-14 - Added CC0 "license".
  2. 29-9-13 - Fixed bug where <<stopallsound>> would crash if one of your sounds wasn't loaded correctly (+ maybe other situations).
  3. 4-3-13 - Added <<fadeinsound>> and <<fadeoutsound>>. 1.1.1 edit: No longer force-restarts or force-starts music that's already looping/stopped.
  4. 15-2-13 - Now play and loop no longer explicitly reset the position to the beginning, so playing something that's already playing won't cause it to reset. (Use stopsound to do this on purpose). This also fixes a bug with the back and forward browser buttons.
  5. 15-2-13 - Initial.
Feel free to report any bugs to @webbedspace.

Twine macro: << timedreplace >>, << timedinsert >>, << timedremove >>, << timedcontinue >>

Similar to my <<replace>> macro, this code causes the passage text in between the <<timedreplace>> and <<becomes>> tags to be replaced with what is between those and the <<endtimedreplace>> tag, after a certain amount of time has elapsed.

* <<timedinsert>> causes its text to be inserted into the page. It doesn't need a <<becomes>> tag to function.
* <<timedremove>> works in a matching fashion, removing its contained text after the time elapses.
* <<timedcontinue>> is similar to <<timedinsert>> but does not require a final <<endtimedcontinue>> - instead, it causes all subsequent text in the passage to appear.
You can also substitute the <<becomes>> tag with <<gains>> to cause the next run of text to appear at the end of the previous run, without replacing it.
If you put multiple <<becomes>> or <<gains>> tags in, the macro will make them appear as well after the same amount of time passes.

Install my <<Replace>> Macro Set to use these macros.

This takes CSS time values, which are decimal numbers ending in "s" (for seconds) or "ms" (for milliseconds).

Usage examples:
* <<timedreplace 2s >>You see nothing. <<becomes>>After 2 seconds, you still see nothing.<<endtimedreplace>>
* <<timedreplace 2s >>You see <<gains>>a dog, <<gains>>a walrus, <<gains>>and a civet.<<endtimedreplace>>
* You search. <<timedinsert 1s>>You find nothing.<<endtimedinsert>>.
* <<timedremove 2.5s >>Something is disappearing... <<endtimedremove>>
* Look <<timedcontinue 3s>>A bird just few by...

Example program.

Implementation details:

* If inserted text appears and descends below the bottom of the screen, the page should automatically scroll down to make it visible.
* Note: due to the way the browser and Twine interact, any changes made by code inside a <<timedreplace>> tag will be forgotten if you use the Back or Forward browser buttons, unless you use this script.

Version history:
* 16/06/2013 - Updated regarding Combined Replace Macro Set.
* 26/04/2013 - Added timedcontinue.
* 05/04/2013 - Added timedinsert and timedremove, as well as downward scrolling.
* 07/03/2013 - Made the transition CSS-based.
* 01/02/2013 - Initial.
Feel free to report any bugs to @webbedspace.

Twine macro: << hoverlink >>

This simple macro produces a usable internal link whose text changes whenever you mouseover it.

version.extensions.hoverlinkMacro={major:1,minor:1,revision:0};macros.hoverlink={handler:function(a,b,c){var d,l=Wikifier.createInternalLink(a,c[0]);
l.className+=" hoverLink";insertElement(l,"span",null,null,c[1]||c[0]);if(c[2]){d=insertElement(l,"span",null,null,c[2]);"none";}l.onmouseover=function(){if(this.childNodes.length>1){this.childNodes[0].style.display="none";

This uses the << choice >> macro's parameter order - the destination passage name comes first. Then comes the visible label, then the hidden label.

Usage example: <<hoverlink "CryPassage" "Stand and fight, guns blazing" "Sit down and have a cry">>

For obvious reasons, this won't work on iPads!

Implementation details:

* The link has a class of "hoverLink" in addition to the standard internalLink/brokenLink classes.
* Each text label is a <span> inside the <a>, and the mouseover and mouseout events make one or the other visible.

Version history:

  1. 29-1-13 - Shortened name to "hoverlink"
  2. 12-5-13 - Initial.

Feel free to report any bugs to @webbedspace.

Twine macro: << addtag >>, << removetag >>, << toggletag >>

This extends my code for applying Twine tags to passage divs, and extends on it as a mechanism for CSS selection. What these macros do, in order, is add a tag to the current passage's tag attribute, remove a tag, and toggle its presence (remove it if it's there, add it if it isn't). This means that conditional application of CSS, controlled by << if >> statements, is possible.
Usage examples: <<addtag "dream">> <<toggletag "lightworld">> <<removetag "darkworld">>

These are guaranteed to work both inside passages, inside << replace >> macros, and, tantalisingly enough, inside << display >> macros. Interesting, very interesting.

If you're using the latest Twine 1.3.6 Alpha (28-1-13) , use this code:

version.extensions["toggletagMacros"]={major:1,minor:1,revision:0};macros["toggletag"]={handler:function(a,b,c){var p=e(a);var d=document.body;if(p){var t=p.getAttribute("data-tags");var i=t.indexOf(c[0]);if(b!="addtag"&&i>=0){var r=t.replace(c[0],"");p.setAttribute("data-tags",r);d.setAttribute("data-tags",r);}else{if(b!="removetag"&&i<0){var r=t+" "+c[0];p.setAttribute("data-tags",r);d.setAttribute("data-tags",r);}}}function e(f){while(f.parentNode&&!f.classList.contains("passage")){f=f.parentNode;
}if(f!=document&&f.getAttribute("data-tags")){return f;}return null;}}};macros["addtag"]=macros["toggletag"];macros["removetag"]=macros["toggletag"];

If you're using a standard version of Twine, use this code instead:

version.extensions["toggletagMacros"]={major:1,minor:1,revision:0};macros["toggletag"]={handler:function(a,b,c){var p=e(a);var d=document.body;if(p){var t=p.getAttribute("data-tags");var i=t.indexOf(c[0]);if(b!="addtag"&&i>=0){var r=t.replace(c[0],"");p.setAttribute("data-tags",r);d.setAttribute("data-tags",r);}else{if(b!="removetag"&&i<0){var r=t+" "+c[0];p.setAttribute("data-tags",r);d.setAttribute("data-tags",r);}}}else{var t=state.history[0].passage.tags;var i=t.indexOf(c[0]);if(b!="addtag"&&i>=0){t.splice(i,1);
}else{if(b!="removetag"&&i<0){t.push(c[0]);}}d.setAttribute("data-tags",t.join(" "));}function e(f){while(f.parentNode&&!f.classList.contains("passage")){f=f.parentNode;}if(f!=document&&f.getAttribute("data-tags")){return f;}return null;}}};macros["addtag"]=macros["toggletag"];macros["removetag"]=macros["toggletag"];

Version history:

  1. 1.1.0 - Now adjusts tags on the body element as well.
  2. 1.0.1 - Fixed not working in Jonah.
  3. 1.0.0 - Initial.
Feel free to report any bugs to @webbedspace.

Twine macro: << cyclinglink >>

This simply produces a link whose text cycles between a number of values whenever you click on it. It otherwise leads nowhere. You can use it as a silly clicky trinket, a cheap alternative to the <<replace>> macro, or (as detailed below) as an input interface element.

Script code

macros.cyclinglink={handler:function(a,b,c){var rl="cyclingLink";
function toggleText(w){w.classList.remove("cyclingLinkInit");
w.classList.toggle(rl+"Enabled");w.classList.toggle(rl+"Disabled");"none")?"inline":"none")}switch(c[c.length-1]){case"end":var end=true;
c.pop();break;case"out":var out=true;c.pop();break}var v="";if(c.length&&c[0][0]=="$"){v=c[0].slice(1);
c.shift()}var h=state.history[0].variables;if(out&&h[v]===""){return
}var l=Wikifier.createInternalLink(a,null);l.className="internalLink cyclingLink";
l.setAttribute("data-cycle",0);for(var i=0;i<c.length;i++){var on=(i==Math.max(c.indexOf(h[v]),0));
var d=insertElement(null,"span",null,"cyclingLinkInit cyclingLink"+((on)?"En":"Dis")+"abled");
}else{l.appendChild(d)}}l.onclick=function(){var t=this.childNodes;
var u=this.getAttribute("data-cycle")-0;var m=t.length;toggleText(t[u]);
u=(u+1);if(!(out&&u==m)){u%=m;if(v){h[v]=c[u]}}else{h[v]=""}if((end||out)&&u==m-(end?1:0)){if(end){var n=this.removeChild(t[u]);


If the first parameter begins with the "$" sigil, then it will interpret it as a variable to be altered by clicking the link. When the player visits the page or clicks the link, the variable will be changed to match the text of the link. If the variable already has a string value when you load the passage, then the link text that matches the variable will be selected, instead of the first one.

If the last parameter is the word "end", then it will terminate the cycling link at the parameter before last. The containing that text will replace the link element altogether. Similarly, if the last parameter is the word "out", then it will disappear altogether after the final link text is clicked.

Usage examples:
* You look around, but only see <<cyclinglink "grass" "a flower" "a cloud" "the road">>. - This is a purely cosmetic, endlessly cycling link.
* You see a bowl containing <<cyclinglink "3 cookies" "2 cookies" "1 cookie" "a few crumbs" end>>. - This link changes to the words "a few crumbs" when you get to the end.
* You see a dial: <<cyclinglink $heat "off" "low" "high" "fearsome">>. - The $heat variable will be changed to "off" when the page loads (unless it was already set to "high" or "fearsome"), and then sets it to "low", "high" and "fearsome" as the player clicks the link.
* You see a fuel gauge: <<cyclinglink $fuel "100%" "50%" "10%" "0%" end>>.
* You see an air meter: <<cyclinglink $air "********" "******" "****" "**" out>>.

Example program 1 (cosmetic).
Example program 2 (mechanical).
Example program 3 (mechanical with CSS)..

New: Advanced CSS effects

I've gone to the trouble of writing a number of advanced CSS effects for use with this macro. You can see them all and obtain the CSS code for them by clicking here. These use some very recent CSS animation features in unusual combinations, but they've been tested in both Chrome and Firefox.

Implementation details:
* For CSS users: the <a> tag has the class names "cyclingLink" and "internalLink".
* Each option is a <span> inside the <a> tag. Clicking it causes the next one down to have the class "cyclingLinkEnabled", and the others to have the class "cyclingLinkDisabled". New: on passage load, each option also has the class "cyclingLinkInit", which is removed as each is clicked.
* When you click, the "data-cycle" attribute of the <a> tag increases by 1 (wrapping around to 0 at the end). You could select this with CSS, I guess, using [data-cycle=1] or somesuch.

Version history:

  1. 9-8-13 - Added 'cyclingLinkInit' class support.
  2. 27-3-13 - Bugfixes, added "out" parameter.
  3. 4-3-13 - Bugfix.
  4. 27-2-13 - Added CSS hooks and the "end" parameter.
  5. 26-2-13 - Added new variable-setting ability.
  6. 16-2-13 - Fixed typo preventing it from working.
  7. 29-1-13 - Initial.

Feel free to report any bugs to @webbedspace.

Twine macro: << replace >>, << insert >> and << continue >>

Similar to my <<timedreplace>> macro, this macro creates an internal link that, when clicked, vanishes and is replaced with whatever is between the << replace >> and << endreplace >> tags. This could be useful if (just for starters) you want to have a passage that can be modified by clicking specific details inside it.

* You can also use <<insert>>, which is identical but does not remove the link text, instead merely changing it to a bare <span> (as with Jonah's <<choice>> macro.)
* You can use <<continue>> to make all subsequent text appear when it's clicked. It does not need an <<endcontinue>> at the end! Quite useful when you just need the reader to click to continue the passage.
* You can insert <<becomes>> or <<gains>> tags inside the contained text to create multiple "versions" of the replacement text. Clicking the link will display each successive version, stopping only when the last version is reached.
* If you omit the text in the starting tag, then the first "version" will be used as the link instead. This lets you, for instance, make an image into a replaced link. Of course, this requires that multiple <<becomes>> or <<gains>> tags are within the text.

Install my <<Replace>> Macro Set to use this macro.

Usage examples:
You see <<replace "a half-eaten cake">>a plate of crumbs<<endreplace>>
You see <<replace "ten dollars">>five dollars<<becomes>>two dollars<<becomes>>fifty cents<<endreplace>>
You see <<replace>>a //big// boulder!<<becomes>>some pebbles.<<endreplace>>
I find it <<insert "repugnant">>that he's made such comments<<endinsert>>.
You go outside. <<continue "Next.">>The sun blinds you momentarily.<<continue "Next.">>Has it been so long?

A short example program.
Hot hint: if you've got a lot of text, it's good to just put a single << display >> inside a << replace >>, and put the text in a separate passage.

Some notes:
* Code inside << replace >> tags is only executed when you click the link. You may notice that the "mailbox" link in the example program produces different text if you click the "front door" link first.
* If inserted text appears and descends below the bottom of the screen, the page should automatically scroll down to make it visible.
* Note: due to the way the browser and Twine interact, any changes made by code inside a <<timedreplace>> tag will be forgotten if you use the Back or Forward browser buttons, unless you use this script.

For a more powerful version of this macro, see <<revision>>.

Version history:
* 16-6-2013: Updated regarding Combined Replace Macro Set.
* 26-4-2013: Added << continue >> variant.
* 5-4-2013: Added << insert >> variant, scrolling.
* 7-3-2013: Added CSS hooks.
* 28-1-2013: Initial.
Feel free to report any bugs to @webbedspace.

Syndicate content