<<audio "song" play>>Sound, like sweeping changes to [[background]], requires some advanced editing in Twine.
(Tired of the music on this page? <<link "Click here to stop it">><<audio "song" stop>><</link>>.)
* Save your audio file to the same folder as your Twine .html files. //Wherever possible, use .mp3 files, as these are standard across most browsers.//
* Create a special passage named "<a target="_blank" href="https://www.motoslave.net/sugarcube/2/docs/#special-passage-storyinit">StoryInit</a>".
<img src=storyinit.png>
* Cache the audio using the {{{<<cacheaudio>>}}} macro in the StoryInit passage. Use the code {{{<<cacheaudio "soundID" "filename.mp3">>}}} to load the sound as soon as the game loads.
<img src=cacheaudio.png>
The second term is the sound file's ID (which will be important in the next step), and the last is the actual filename of the sound you are calling.
* Now, go to the passage where you want to use sound, and use the "<a target="_blank"
href="https://www.motoslave.net/sugarcube/2/docs/#macros-macro-audio">audio</a>" macro to play the sound: {{{<<audio "soundID" play>>}}}
<img src=audio.png>
//Make sure you get the file name correct—it's easiest to select it in its directory, and copy-paste into your Twine passage.//
''Testing audio'': to test that your audio works, you'll need to "Publish to File" (the same as you do when you <<link "save your Story">>
<<script>>
Dialog.setup("saving", "info");
Dialog.wiki(Story.get("saving").processText());
Dialog.open();
<</script>>
<</link>>), then load the saved html file in your Internet browser.
All good? Try some other functions, like <<link"images">><<audio "song" stop>><<goto [[images]]>><</link>>, <<link"styling">><<audio "song" stop>><<goto [background]]>><</link>>, or just return to <<link"start">><<audio "song" stop>><<goto [[Start]]>><</link>>.Changing background colors, font types, and other general changes to the look of your story/game may require some CSS styling. If you only want to change a line or two, in-line styling as described [[here|colors]] is fine. But if you want consistent changes throughout the story/game, you might want to start up a <a target="_blank" href="http://twinery.org/wiki/stylesheet">CSS stylesheet</a>.
Here are the basics:
* On the Twine menu, click "Story", then "# Stylesheet".
<img src=stylesheet.png>
* Let's start with changing the background of the entire site.
<img src=cssbg.png>
* You'll see in the above image that we've also already added the code for the background change, under the "body {" selector:
{{{background-color:blue;}}}
* You can use whatever color you like—here are some resources <a target="_blank" href="http://www.w3schools.com/cssref/css_colornames.asp">by color name</a> or by <a target="_blank" href="http://www.colorpicker.com/">hexadecimal color picker</a>.
* This changes the background of ALL your passages.
<img src=bluebg.png>
Want to [[change the background of only SOME passages|background2]]?
Or return to [[start|Start]].
To add images you've found online, first make sure they are available for you to use (i.e., saved under a <a target="_blank" href="http://creativecommons.org">Creative Commons license</a>, under public domain, or you've obtained permission from the owner). Then make sure you <a href="IP_Record.docx">log all the information you'll need to credit the source</a>.
//Tip: Google Images can search just for images that are okay to use. Click "Tools", then "Usage Rights" and "Creative Commons licenses".//
<img src=gimg.png>
Find the URL for the image you want to use. Usually, you can find this by right-clicking the image and selecting "Copy Image URL" or "Copy Image Address":
<img src=copyimgurl.png>
Or keep clicking on the image until the URL in your address bar ends with an image tag (.jpg, .png, .gif), then copy the entire URL:
<img src=imgurl.png>
Then, to insert your image, you can either use Sugarcube notation {{{[img[URL]]}}} OR you can use standard <a target="_blank" href="https://www.w3schools.com/html/html_images.asp">HTML notation</a>:
<img src=webimg.png>
Now [[test play|testBuild]] your story, and see where the images show up!
Want to add [[images you've saved to your computer|ImgSaved]], [[sound]], [[external links|ExtLinks]], or change [[background]] or [[colors]]?
You can also review the basics starting [[here|Start]].[[Start Page|Start]]
[[The Basics|firstStep]]
<<link "Saving">>
<<script>>
Dialog.setup("saving", "info");
Dialog.wiki(Story.get("saving").processText());
Dialog.open();
<</script>>
<</link>>
[[Testing|testBuild]]
[[Internal Links|IntLinks]]
[[External Links|ExtLinks]]
[[Colors|colors]]
[[CSS Basics|background]]
[[Images|images]]
[[Sound|sound]]
[[Sharing & Publishing|sharing]]
[[Other Tutorials|tutorials]]
To download this tutorial's source file:
* Right-click (Mac: Cmd-click) anywhere on this page and select "Save As..."
* Save the .html file, then open it in Twine: "Import From File"Creating links to external websites is pretty easy—you just use HTML coding! All HTML coding works in Twine.
Use <a href="https://www.w3schools.com/html/html_links.asp" target="_blank">HTML "link" notation</a>:
<img src=extlink.png>
Now maybe you want to try something more complicated, like adding [[images]] or [[sound]], or changing [[background]] or [[colors]]. Don't forget to [[save and test your story|testBuild]]!If you want to change elements of only SOME passages, you'll need to use //Tagged Passages// and the //Story Stylesheet//.
For this tutorial, we'll use the background property as an example, but you can do this with any element of these tagged passages, including fonts, colors, images, and more.
* Tag the passages where you want the changed elements to occur by clicking "+ Tag" and typing in the tag. //Make sure the tag is the same on each passage it is used!//
<img src=tag1.png>
<img src=tag2.png>
* For changes to occur in only tagged passages, open Story > Stylesheet, and create properties for them by appending the property title with ".tag". In this example, the tag is "yellow"; in order to change //body// elements of these passages, the CSS code is
"body.yellow":
<img src=yellow.png>
<img src=yellowshow.png>
You can do this with any CSS element, and mix and match tags throughout the passages.
Now, how about other features, like [[sound]], [[images]], and other [[tutorials]]? Or, you could just return to [[start|Start]].Now you'll want to link your created passages together. Here's where you're going to start coding!
Double-click on a passage to edit it, or create a new passage. When you give your new passages titles, make sure to keep them short and simple.
To link from one passage to another, you use a simple bit of coding: two square brackets.
<img src=intlinks.png>
This passage shows two ways to create internal Twine links:
<ol>
<li>Simply place a set of square brackets around the title of the destination passage.</li>
<li>Or if you want the <em>linked</em> text to be different from the title of the destination passage, use this notation: {{{[[link text|passageTitle]]}}}. That's two square brackets, the text you want your reader to click, a vertical line (on most keyboards, this is located as part of the forward-slash key), the title of the passage you're linking to, then two square brackets.</li>
</ol>
When it is published in a browser, that passage will look like this:
<img src=intlinkspub.png>
//Note: If you link to a passage title that doesn't exist yet, Twine will create the passage for you automatically. This is a quick way to create the passages your story needs.//
This brings up an important point: coding is picky! You have to get the sequence JUST RIGHT for it to work -- that means capitalizations, spaces, spelling, symbols... //everything//.
[[So now let's test that it worked!|testBuild]]The first step is to access <a target="_blank" href="http://twinery.org/">Twine</a>. You can either download it to your computer, or use it in your Internet browser.
This is the current (as of 5 Oct 2022) Twine website:
<img src=twineweb.png>
Click "Use in your browser", and it will open Twine right in the same page. This is the Twine home screen or <strong>Stories Library</strong>:
<img src=twinehome.png>
<em>Note: it may use a light or dark theme depending on your settings, and may or may not have the <<link "save">>
<<script>>
Dialog.setup("saving", "info");
Dialog.wiki(Story.get("saving").processText());
Dialog.open();
<</script>>
<</link>> warning.</em>
To start a new story, click the <img class="button" alt="+Story" src=newstory.png> button. Name your story, and click "Create".
<img src=namestory.png>
Your story will open in the Twine interface. This is Twine's basic working area or ''canvas''.
<img src=canvas.png>
These are Twine's menus, with all the options:
<img src=menu.png>
First, let's set the Story Format to match this tutorial. (<<link "Click here to find out why.">>
<<script>>
Dialog.setup("Sugarcube", "info");
Dialog.wiki(Story.get("sugarcube").processText());
Dialog.open();
<</script>>
<</link>>) On the menu, click "Twine", then "Story Formats".
Select the latest version of Sugarcube, then go ''Back'' to the Stories Library.
<img src=sugarcube.png>
[[Now we can start creating a story!|passages]]Let's make a Twine story. The basics are pretty easy!
In fact, this tutorial was completely written in Twine, and you can download the source file to see how it was done! Just right-click (Mac: Cmd-click) anywhere on this page and select "Save As..." Save the .html file, then open it in Twine.
[[Start from the bare basics|firstStep]]
[[Learn how to create links to other passages|IntLinks]]
[[Learn how to create links to external websites|ExtLinks]]
[[Learn how to change the colors|colors]]
[[Learn how to add images|images]]
[[Learn how to add sound|sound]]
[[See the list of other useful tutorials and resources|tutorials]]
/%See how this text is in gray, and it doesn't show up in the story when you test/build it? That's because it's a "comment" - it appears when you're coding the story, but not in the final version itself. You can use these comments to write notes to yourself.%/
You can easily change the colors of the text in each passage by using the following CSS coding:
{{{@@color:red;Red text!@@}}}
Which will look like this:
@@color:red;Red text!@@
You can use whatever color you like -- here are some resources <a target="_blank" href="http://www.w3schools.com/cssref/css_colornames.asp">by color name</a> or by <a target="_blank" href="http://www.colorpicker.com/">hexadecimal color picker</a>.
You can also change the spacing of the letters, the type and size of the font, and other <a target="_blank" href="http://www.w3schools.com/cssref/default.asp">CSS inline elements</a>:
{{{@@color:red;letter-spacing:3px;font-size:1.5em;Red text!@@}}}
@@color:red;letter-spacing:3px;font-size:1.5em;Red text!@@
To change the background color of a line, use the following code:
{{{@@background-color:red;Red background!@@}}}
@@background-color:red;Red background!@@
These are inline changes—if you want to make general changes to your story/game, it would be better to use a <a target="_blank" href="http://twinery.org/wiki/stylesheet">CSS stylesheet</a>.
The basics of CSS stylesheets are described [[here|background]], or you can go back to the [[Start|Start]] for other functions.The text and coding you're putting into the Twine canvas is not what your readers will actually see once you publish your story—this is the case with any website, game, or app.
So, as a digital developer, you'll want to regularly check that your //published// piece works and looks the way you designed it to. Twine has an easy way to do this.
* First, make sure you <<link "save your work">>
<<script>>
Dialog.setup("saving", "info");
Dialog.wiki(Story.get("saving").processText());
Dialog.open();
<</script>>
<</link>>.
* Now to test the story, go to the Twine menu and click "Build" then "Play".
<img src=play.png>
If you are using the browser version, this will simply add a new tab with your game in it. If you are using the desktop version, this will open a default Twine browser window.
* Once it's opened in your browser, you can play it and see if it's looking and working like you want it to.
<img src=testplay.png>
* Once you're happy with your story, you can [[publish and share it|sharing]].
So those are the basics—you can build a story using nothing more than these tools.
You can also change the look of your [[text|colors]] and [[background]], and add things like [[images|images]], [[sounds|sound]], and [[external links|ExtLinks]].//Note: ''Only'' use this option if you will be [[publishing|sharing]] your Twine Story to your own server (e.g., you have your own website). If you don't have your own server and will be publishing through a Twine server such as <a target="_blank" href="http://itch.io/">itch.io</a>, ''all'' of your resources (images, sounds, etc.) will need to be <<link "hosted online">>
<<script>>
Dialog.setup("resourceHosting", "info");
Dialog.wiki(Story.get("resourceHosting").processText());
Dialog.open();
<</script>>
<</link>>, and you'll need to use the [[steps for adding online images|ImgOnline]].//
* To add images you've saved to your computer, first make sure they're <<link "saved">>
<<script>>
Dialog.setup("saving", "info");
Dialog.wiki(Story.get("saving").processText());
Dialog.open();
<</script>>
<</link>> to the same folder as your Twine story's .html file.
//If they're not in the same folder as the .html file, then they won't show up when you publish your story.//
* Then, to insert your image, you just enter in the following code:
{{{<img src=blerg.jpg>}}}
That's just one square bracket, the text "img", another square bracket, the name of the image file, then two closing square brackets.
* Now [[test play|testBuild]] your story, and see where the images show up!
Want to add [[images you've found online|ImgOnline]], [[sound]], [[external links|ExtLinks]], or change [[background]] or [[colors]]?
You can also review the basics starting [[here|Start]].If you thought adding images was going to be more complicated than adding links, you were so wrong. It's almost easier!
There are two categories of images you can include in your Twine story: [[images saved on your computer|ImgSaved]] or [[images you've found online|ImgOnline]] //(don't forget to write all necessary information down about other people's images you find online—you'll want to include a credits passage to give them their fair dues!)//.
<div class="title">Lyle's Twine Basics</div>
<span class="subt1">Twine 2.5.1/Sugarcube 2.36.1</span>
<span class="subt2">Updated Oct. 2022</span>
<div class="title"><a target="_blank" href="http://lyleskains.com/">Dr. Lyle Skains</a></div>Here are some other excellent tutorials and resources you can use to build your Twine stories:
* <a target="_blank" href="https://twinery.org/cookbook/">The Twine Cookbook</a>—a resource of examples of different things you can do in Twine.
* <a target="_blank" href="https://www.motoslave.net/sugarcube/2/docs/">Sugarcube 2 Documentation</a>—all the things you can do in Twine's Sugarcube 2 Story Format.
* <a target="_blank" href="http://www.adamhammond.com/twineguide/">Adam Hammond's Twine Guide</a>—a great starting tutorial, including ''videos''.
* <a target="_blank" href="http://twinery.org/questions/">Twine Q&A</a>—a forum where people ask and answer questions about worknig in Twine. //A bit old now, but still a useful resource if you search.//
* <a target="_blank" href="https://twinery.org/forum/discussion/1528/css-is-your-friend-the-basics-of-changing-twines-default-appearance-for-newbs">CSS is Your Friend: The Basics of Changing Twine's Default Appearance For Newbs</a>—Also getting a bit dated, but CSS basics don't change much.
* <a target="_blank" href="http://pastebin.com/Lb7KrHrZ">Some good CSS pointers (sample CSS stylesheet)</a>
* <a target="_blank" href="http://www.w3schools.com/cssref/default.asp">CSS Properties Reference</a>
* <a target="_blank" href="http://www.w3schools.com/cssref/css_selectors.asp">CSS Selectors Reference</a>
* <a target="_blank" href="http://www.colorpicker.com/">Color Picker (Hexadecimal)</a>
* <a target="_blank" href="http://ifdb.tads.org/">The Interactive Fiction Database</a>—find Twine stories/games to play, and post your own!
* <a target="_blank" href="http://itch.io">itch.io</a>—an indie game publishing site that features a lot of Twine games. You can also publish your games here.
Looking for more? I keep a running list of more <a target="_blank" href="https://www.evernote.com/pub/roseslug/twine">advanced Twine tricks here</a>.
Return to [[start|Start]].When you access Twine for the first time, it offers you this warning:
<img src=twineSaveMsg.png>
<div class="info">Twine saves your work two ways: //Autosave to cache// and //Publish to file//.
//Autosave to cache// just means Twine is automatically saving everything you do to a temporary cache file. If you're working in the online version, it's saving to your browser's history cache. If you're working in the desktop version, it's saving to a cache on your hard drive.
''These autosaves are easily wiped out!!!'' So you'll want to make sure you are frequently publishing to file:
On the Twine menu, click "Build" then "Publsh to File".
<img src=pubtofile.png>
This will prompt you to save the .html file to your computer. You can name it anything you want, though it's easy enough to keep it as the story name. Save it somewhere you know you can find it.
//Note: once you start adding images and other file types to your story, you'll want to save them in the same location (folder or directory) as your .html file.//</div>The "Untitled Passage" box you see here is a //passage//. Double-click on it, and you'll be able to edit it:
<img src=passage.png>
Each passage will need a title and text in the passage.
Click "Rename" to title your passage.
<img src=passagetitle1.png>
Name your passage something useful, keeping it short and memorable, and click "OK".
<img src=passagetitle2.png>
Then add text to your passage!
<img src=titletext.png>
You can enter as much text as you like—each Twine passage is like a page in a story or website.
Play around with creating a few passages in Twine by clicking the "+New" button.
<img src=addpassage.png>
[[Once you have a few passages, you'll need to link them together...|IntLinks]]
/%See how I've put in an external html link here to Twine? That's the
basic html coding for links - two square brackets, followed by the text
that will be the linking word, a vertical line, linked location, and two
closing square brackets:
[[linking text|http://URLtoweb.com]]
%/What's the point of creating a game if no one can play it, right? So let's publish our games so we can share them with friends.
* When your game is ready to publish, <<link "Publish it to File">>
<<script>>
Dialog.setup("saving", "info");
Dialog.wiki(Story.get("saving").processText());
Dialog.open();
<</script>>
<</link>> just as you do when saving your game.
* If you have your own web hosting service, you can use that to post the html files. If not, move on to the next step.
* [[itch.io|http://itch.io]] is pretty much the only venue left (that I'm aware of) to publish your game for free without needing your own server space.
//Note that if your Twine game incorporates images, audio, or other files outside of the exported html file, you'll need to [[host these online somewhere|resourceHosting]].//
* Upload your html file, and retrieve the web address.If you don't have a webserver you can publish your Twine game to, any external assets like images and sounds will need to be hosted somewhere. You'll be sharing your Twine HTML file, but this doesn't automatically include offline image and sound files.
So if you're using external assets (images, sound), you'll need to host them somewhere else online, using a hosting service such as:
''All File Types''
* <a target="_blank" href="https://www.dropbox.com/">Dropbox</a>
* <a target="_blank" href="https://drive.google.com">Google Drive</a>
* <a target="_blank" href="https://www.4shared.com/">4shared</a>
''For Images''
* <a target="_blank" href="https://www.google.com/photos/about/">Google Photos</a>
* <a target="_blank" href="http://imgur.com/">Imgur</a>
* <a target="_blank" href="https://www.flickr.com/">Flickr</a>
* <a target="_blank" href="http://www.freeimagehosting.net/">Free Image Hosting</a>
* <a target="_blank" href="http://postimage.org/">PostImage</a>
* <a target="_blank" href="http://imageshack.us/">ImageShack</a>
* <a target="_blank" href="http://photobucket.com/">PhotoBucket</a>
* <a target="_blank" href="http://www.500px.com/">500 Pixels</a>
* <a target="_blank" href="https://imgbox.com/">ImgBox</a>
Upload your file to one of these services, and locate its web URL.
For images, you can locate the web URL by right-clicking on the image and selecting "Copy Image Address". The file address //must// end in an appropriate file extension for the type of resource it is. Typically, these are .jpg, .png, .gif
<img src=imgaddress.png>
Use this link in place of the filename when adding your image to a Twine passage.
<img src=imgaddress2.png>
For sound files, you'll need to use a file-sharing service like Dropbox or Google Drive.
''For Dropbox''
* Upload the file to Dropbox, then <a target="_blank" href="https://www.dropbox.com/help/files-folders/view-only-access">share it so you get a sharing link</a>. Copy this link.
* The end of the sharing link should be "dl=0". Change the 0 to a 1.
* Use this link in place of the filename when adding your sound to the "cacheaudio" micro in your StoryInit file.
<img src=soundlink.png>
For Google Drive, follow <a target="_blank" href="https://www.labnol.org/internet/direct-links-for-google-drive/28356/">these instructions</a> to get the URL to put into the "cacheaudio" macro.<<cacheaudio "song" "RetroMusiciStock_000011160348Wav44100.mp3">>Sugarcube is the most powerful of the Twine story formats (to date), and most advanced Twine developers work in Sugarcube. That's because it includes the most options for making things work, and integrates more advanced coding (HTML, CSS, JavaScript) more seamlessly than the other formats.
A lot of Twine beginners work with Harlowe, which includes more of a WYSIWYG (What You See Is What You Get) interface, where you don't have to do as much coding. The reason we don't use Harlowe on You & CO<sub>2</sub> is that we think it's important that you learn some basic coding for other applications in your life!
If you continue to create stories and games with Twine, you'll find you want to do more advanced things as your knowledge and skills grow. Why not start with the format that can grow with you?