Class files: all the images, backgrounds and sample files we use in this class are in the shared folder — open the shared Google Drive folder »
Handmade Techniques · Interactive Fiction · Twine (Harlowe) · Frame Animation

Making a Game in Twine (v2)

A follow-along class: photograph a few frames of characters you made by hand, place them in front of a handmade location, and make them blink and talk inside a Twine story. Pictures are added by tagging passages with the picture’s file name, so nobody types HTML or edits code.

This is the Twine module of Handmade Techniques for Digital Art. It has the same remit as Living Characters, but uses only Twine: handmade characters, a few photographed frames, a story that speaks through them. Students work with text, links, image files and tags.

Tag = file name. The facilitator pastes two pieces of setup into Twine once: a stylesheet for the page’s look and a small Story JavaScript that loads pictures. After that, a passage tagged bg-kitchen shows images/bg-kitchen.jpg behind it, and a passage tagged nora-happy shows images/nora-happy.png (or .gif or .jpg, whichever file you saved). Students never edit the stylesheet or the script again. Test the whole class once on your own machine before teaching it.
How this page is organised. Steps 1–3 happen at the table with paper and a camera. Steps 4–9 are in Twine. Steps 10–11 are testing and publishing. A troubleshooting table is at the end.

The Idea in One Minute

Twine lets you put a short label, called a tag, on any passage. In this class a tag is simply the name of a picture file, without the .png, .gif or .jpg. When the player reaches a passage, the setup looks at its tags, finds the matching pictures in the images folder, and shows them. A tag starting with bg- is a background. Any other tag is a character picture.

Harlowe puts each passage’s tags on the page it builds, which is what lets the setup read them. This is documented Harlowe behaviour, shown in the Twine Cookbook.

Why Harlowe, Not SugarCube

What Twine Is

Twine shows the story as a network of boxes joined by arrows. Players never see the map; they see the published page.

Materials

Class Flow

1. Make the characters and decide what they want.

2. Make the locations, one wide picture each.

3. Photograph and prepare the frames (transparent PNGs work best), named by the tag naming rules.

4. Start a Twine story and set the format to Harlowe.

5. Build the passages and links.

6. Write the text.

7. Facilitator pastes the setup (stylesheet and Story JavaScript), once.

8. Tag each passage with picture names.

9. Animate by tagging several numbered frames.

10. Test.

11. Publish, host and exchange.

Step 1: Make the Characters

Work in any handmade medium: drawing, collage, cardboard cut-out, felt, clay. Make each character chest-up and facing the camera, so it reads clearly when it sits at the side of a screen. One character is enough; groups can make two so they can meet in a scene.

Step 2: Make the Locations

Step 3: Photograph and Prepare the Frames

3a. What a frame is

A frame is one still image of the character. Animation is what happens when the browser shows several frames in a row, quickly, in the same spot. Two frames that differ only in the mouth look like talking. Two frames that differ only in the eyes look like blinking. The frames must line up exactly, or the character will jump instead of move.

3b. The naming rules (this is how the tags work)

The file name, without its ending, is the tag. Follow these patterns exactly.

What it isFile nameTag you will type
A backgroundbg-kitchen.jpgbg-kitchen
A still character picturenora-happy.pngnora-happy
An animated mood, frame 1nora-talk-1.pngnora-talk-1
An animated mood, frame 2nora-talk-2.pngnora-talk-2
A second charactersam-idle.gifsam-idle

3c. Frames to make for the sample story

File nameWhat it shows
nora-idle-1.pngNeutral, eyes open
nora-idle-2.pngSame, eyes closed (the blink)
nora-talk-1.pngMouth closed or small
nora-talk-2.pngMouth open
nora-happy.pngPleased expression
nora-sad.pngDisappointed expression
bg-kitchen.jpgThe kitchen picture
bg-garden.jpgThe garden picture

Six character frames is plenty. Younger groups can make just nora-idle, nora-talk-1, nora-talk-2 and one reaction.

3d. Photograph so frames line up

  1. Tape the backdrop paper down so it cannot move.
  2. Fix the phone in one spot (stacked books or a tripod) and mark its position with tape. Do not hand-hold it.
  3. Light the character evenly, from the side of a window or with a lamp, so there are no hard shadows on the paper.
  4. If your camera lets you, lock focus and exposure by pressing and holding on the screen.
  5. Photograph frame 1. Change only the one small part that should change, then photograph frame 2 without touching the camera or moving the figure. For drawings, redraw on a new sheet taped in the same place, or use tracing paper over the first drawing.
  6. Repeat for every frame and check that the character is in the same place in each photo.

3e. Make transparent PNGs

  1. Open the first photo in your background remover and remove the paper. Check the edges.
  2. Crop to the character. Crop tight along the bottom edge, so the lowest part of the character (the base of the figure, the bottom of the chest cut-off, the feet) touches the bottom of the canvas. Any empty space below it will make the character float above the bottom of the screen. A little space at the top and sides is fine.
  3. Use exactly the same crop box for every frame of every mood. If your tool allows it, set one canvas size, for example 800 × 1000 pixels, and apply it to all frames. Identical size is what makes the frames line up, and what keeps a character the same size from mood to mood.
  4. Export as PNG if you want a see-through background. PNG keeps the transparent area. A JPG brings back a solid box, which is fine if you want a framed, cut-paper or photo-booth look.
  5. Save the files in the images folder with the names from the naming rules.
  6. Save the locations in the same folder as JPGs with the bg- pattern.
File naming rules. Lowercase only. No spaces. File names are case-sensitive once the story is online, so Nora-Talk-1.png and nora-talk-1.png are different files. A tag has to match the file name exactly.
File size. Keep each character frame around 800 pixels tall, and each background under about 500 KB if you can. Large files load slowly on a phone.
Any shape of picture is safe. The page fits every character picture inside the same fixed slot at the bottom of the screen, so a wide GIF, a tall PNG and a square JPG are all kept fully on screen. The picture is scaled to fit the slot without stretching and sits on the bottom edge. For characters that look the same size from picture to picture, keep one canvas size for all of a character’s frames.

Step 4: Start a Twine Story and Set the Format

  1. Go to twinery.org and choose Use Twine in your browser, or open the desktop app. You land in the Library, which lists your stories.
  2. Click + New and type a short title, such as the character’s name. Click Create. The story map opens with one passage called “Untitled Passage”.
  3. Check the format. At the top of the story map, open the Story tab and choose Details. The dialog has a Story Format menu. Set it to the latest Harlowe 3 version, then close the dialog.
Why check? Changing Twine’s default format only affects stories created afterwards, and a story you import keeps whatever format is saved in its file. If someone on the course has used SugarCube before, their new story may not be Harlowe. Setting the format in each story’s Details avoids this.
Browser Twine saves inside the browser. Clearing browser data, using a private window, or switching computers loses the story. Use the library’s archive option regularly (see Step 11) and keep the archive file in your project folder. Menu names vary a little between Twine versions; if a menu is not where this page says, look for the same word in the top bar.

Step 5: Build the Passages and Links

5a. Plan the five passages

The last column is the tags you will add in Step 8. Keep the plan on paper beside you.

Passage nameWhat happensTags (Step 8)
StartWe meet the character.bg-kitchen nora-idle-1 nora-idle-2 blink
AskThe character talks and asks for help.bg-kitchen nora-talk-1 nora-talk-2
AnswerYesThe player helps.bg-garden nora-happy
AnswerNoThe player refuses.bg-garden nora-sad
EndingThe result, with a link to start over.bg-garden nora-idle-1 nora-idle-2 blink

5b. Rename the first passage

  1. Double-click the box “Untitled Passage” to open the passage editor.
  2. Click Rename in the editor toolbar, type Start, and confirm.
  3. The little green rocket on a passage marks the start passage, the one the player sees first. If it is not on Start, click the rocket button (“Start Story Here”) in the editor toolbar.

5c. Create the other passages by writing links

You do not have to make boxes by hand. When you type a link to a passage that does not exist, Twine creates that passage for you a moment after you stop typing. In Start, type:

[[Ask]]

A new passage called Ask appears next to Start with an arrow joining them. Now double-click Ask and type:

[[Help->AnswerYes]]
[[Walk away->AnswerNo]]

The form is [[text the player sees->passage name]]. The player sees Help, and clicking it goes to the passage named AnswerYes. Passage names are case-sensitive and must match exactly, including capital letters and spaces. Twine creates AnswerYes and AnswerNo for you. In each of those, write [[Ending]] to create the last passage.

Drag the boxes on the map so they read left to right: Start, Ask, then AnswerYes and AnswerNo above and below each other, then Ending. If the arrow points to a box with a broken outline, the link name has a typo.

Step 6: Write the Text

In each passage, write the character’s words and a line or two of description. Short is better: two to four sentences per passage. The text appears in a light panel over the picture, so there is nothing else to type. Example for Start:

Nora is standing by the kitchen door, turning her pockets inside out.

[[Ask]]

Pictures do not carry a text description here, so say in the story text what the player is looking at (“Nora is standing by the kitchen door”). That also helps anyone using a screen reader.

Step 7: Facilitator Pastes the Setup, Once

This is the only technical step, and the facilitator can do it for the whole room, or put it in a starter story that students copy. It has two parts. Neither part has any picture names in it, so students never need to open them again.

7a. The stylesheet: how the page looks

Open the Story tab and choose Stylesheet. Paste this and close the dialog. It saves automatically. This part styles the text panel and the background. The characters’ size and position are set by the Story JavaScript in 7b.

/* THE PAGE AND THE TEXT PANEL */
tw-story {
  background-color: #333;
  background-size: cover;
  background-position: center;
  background-repeat: no-repeat;
  color: #222;
  font-family: Georgia, serif;
  font-size: 18px;
  line-height: 1.5;
}
tw-passage {
  position: relative;
  z-index: 2;
  background: rgba(255, 255, 255, 0.85);
  max-width: 28rem;
  margin: 1rem;
  padding: 1rem;
}
tw-sidebar { display: none; }
tw-link { color: #0000aa; font-weight: bold; }
tw-link:hover { color: #aa0000; }

@media (max-width: 600px) {
  tw-passage { max-width: none; margin-bottom: 32vh; }
}

7b. The Story JavaScript: how pictures are found

Open the Story tab and choose JavaScript. Paste this and close the dialog. Do not edit it. The FOLDER line near the top, images/, is the only line you would ever change.

(function () {
  var FOLDER = 'images/';
  var BG_EXT = ['jpg', 'jpeg', 'png', 'gif', 'webp'];
  var CHAR_EXT = ['png', 'gif', 'webp', 'jpg', 'jpeg'];
  var SKIP = ['header', 'footer', 'startup', 'fast', 'slow', 'blink'];
  var cache = {};
  var reduce = window.matchMedia && matchMedia('(prefers-reduced-motion: reduce)').matches;

  /* Every character sits in a fixed slot on the bottom edge.
     Each picture is scaled to fit the slot (never stretched, never cut off). */
  var css = document.createElement('style');
  css.textContent =
    '.tw-cast{position:fixed;left:0;right:0;bottom:0;box-sizing:border-box;padding:0 3vw;height:55vh;height:55dvh;display:flex;flex-direction:row-reverse;justify-content:flex-start;align-items:flex-end;gap:2vw;overflow:hidden;pointer-events:none;z-index:5}' +
    '.tw-actor{position:relative;flex:0 1 min(38vw,44vh);min-width:0;height:100%}' +
    '.tw-frame{position:absolute;left:0;bottom:0;width:100%;height:100%;display:block;object-fit:contain;object-position:center bottom}' +
    '@media (max-width:600px){.tw-cast{height:28vh;height:28dvh;padding:0 2vw;justify-content:center}.tw-actor{flex-basis:min(46vw,22vh)}}';
  document.head.appendChild(css);

  function clearCast() {
    var old = document.querySelectorAll('.tw-cast');
    for (var i = 0; i < old.length; i++) { old[i].parentNode.removeChild(old[i]); }
  }

  function probe(name, exts, done) {
    var key = name + '|' + exts.join();
    if (key in cache) { return done(cache[key]); }
    var i = 0;
    (function next() {
      if (i >= exts.length) { cache[key] = null; console.warn('Twine tags: no image found for tag "' + name + '" in ' + FOLDER); return done(null); }
      var url = FOLDER + name + '.' + exts[i++];
      var img = new Image();
      img.onload = function () { cache[key] = url; done(url); };
      img.onerror = next;
      img.src = url;
    })();
  }

  function animate(imgs, speed, blink, root) {
    var i = 0;
    function wait(k) { return blink ? (k === 0 ? 3600 : 150) : speed; }
    function step() {
      if (!root.isConnected) { return; }
      i = (i + 1) % imgs.length;
      imgs.forEach(function (im, j) { im.style.opacity = j === i ? '1' : '0'; });
      setTimeout(step, wait(i));
    }
    setTimeout(step, wait(0));
  }

  function build(passage) {
    if (passage._built) { return; }
    passage._built = true;
    clearCast();
    var story = document.querySelector('tw-story');
    var tags = (passage.getAttribute('tags') || '').split(/\s+/).filter(Boolean);
    var bg = null, speed = 300, blink = false, groups = {}, order = [];
    tags.forEach(function (t) {
      if (t === 'fast') { speed = 150; }
      else if (t === 'slow') { speed = 600; }
      else if (t === 'blink') { blink = true; }
      else if (SKIP.indexOf(t) > -1) { return; }
      else if (/^bg-/.test(t)) { bg = t; }
      else {
        var m = /^(.*)-(\d+)$/.exec(t);
        var key = m ? m[1] : t;
        if (!groups[key]) { groups[key] = []; order.push(key); }
        groups[key].push({ tag: t, n: m ? +m[2] : 0 });
      }
    });

    if (bg) {
      probe(bg, BG_EXT, function (u) { if (passage.isConnected) { story.style.backgroundImage = u ? 'url("' + u + '")' : ''; } });
    } else { story.style.backgroundImage = ''; }

    if (!order.length) { return; }
    var cast = document.createElement('div');
    cast.className = 'tw-cast';
    document.body.appendChild(cast);
    order.forEach(function (key) {
      var frames = groups[key].sort(function (a, b) { return a.n - b.n; });
      var actor = document.createElement('div');
      actor.className = 'tw-actor';
      cast.appendChild(actor);
      var imgs = frames.map(function (f, i) {
        var img = document.createElement('img');
        img.className = 'tw-frame';
        img.alt = '';
        img.style.opacity = i === 0 ? '1' : '0';
        actor.appendChild(img);
        probe(f.tag, CHAR_EXT, function (u) { if (u) { img.src = u; } else { img.style.display = 'none'; } });
        return img;
      });
      if (imgs.length > 1 && !reduce) { animate(imgs, speed, blink, cast); }
    });
  }

  function scan() {
    var ps = document.querySelectorAll('tw-passage');
    for (var i = 0; i < ps.length; i++) { build(ps[i]); }
  }
  new MutationObserver(scan).observe(document.documentElement, { childList: true, subtree: true });
  scan();
})();

7c. What the script does, in plain words

Pasting note. The script needs straight quote marks, not curly ones. Paste it straight from this page rather than retyping, and do not pass it through a word processor. If a student’s pictures do not appear but the facilitator’s do, check that the script pasted whole.

Image paths such as images/bg-kitchen.jpg are relative to the published HTML file. They only work once the story is saved beside the images folder (Step 11). If the pictures are already online, change FOLDER at the top of the script to the full web address of that folder, ending in a slash.

Step 8: Tag Each Passage

Now the students work only in the passage editor. Every passage gets one background tag and the picture tags of each character who appears.

8a. How to add a tag

  1. Double-click a passage to open its editor.
  2. Click + Tag in the editor toolbar.
  3. Type the tag name exactly as the file is named, without the ending, for example bg-kitchen, and confirm with Add or Enter.
  4. Click + Tag again for each further picture, for example nora-idle-1.
  5. The tags show as small labels under the passage name. To remove one, click it and choose Remove.

8b. The five passages, tagged

Passage name: Start
Tags: bg-kitchen nora-idle-1 nora-idle-2 blink
Nora is standing by the kitchen door, turning her pockets inside out.

[[Ask]]
Passage name: Ask
Tags: bg-kitchen nora-talk-1 nora-talk-2
“Have you seen my keys?” Nora asks. “I had them a minute ago.”

[[Help->AnswerYes]]
[[Walk away->AnswerNo]]
Passage name: AnswerYes
Tags: bg-garden nora-happy
“You found them!” Nora says. “Thank you.”

[[Ending]]
Passage name: AnswerNo
Tags: bg-garden nora-sad
“Oh,” Nora says. “Maybe next time.”

[[Ending]]
Passage name: Ending
Tags: bg-garden nora-idle-1 nora-idle-2 blink
The evening goes quiet. Nora goes back to the library.

[[Start again->Start]]

8c. Two characters in one scene

Add the second character’s tags as well. A passage with bg-kitchen, nora-talk-1, nora-talk-2 and sam-idle shows Nora talking and Sam standing beside her. The first character named in the tags stands on the right; the next one stands to its left. Characters are told apart by the name before the mood, so nora- and sam- never mix.

8d. All the tag rules

TagWhat it does
bg- then a nameBackground. Only one per passage; if there are two, the last is used.
name-moodA still character picture (PNG, GIF, JPG, JPEG or WebP).
name-mood-1, name-mood-2 …Frames of an animation. Use two, three or more. They play in number order.
fastPlays frames quickly, about 0.15 seconds each.
slowPlays frames slowly, about 0.6 seconds each.
blinkHolds frame 1 for about 3.6 seconds, then shows the other frames very briefly. Use it for idle blinking.

With none of fast, slow or blink, frames change about every 0.3 seconds, which suits talking.

Careful with tags. Tags are case-sensitive and have no spaces. A tag must match a file name exactly. Do not use header, footer or startup as tags, which Harlowe treats specially. The tags fast, slow and blink are reserved for speed, so do not name a character or a picture with those exact words. A passage with no bg- tag shows the dark default background, and a passage with no character tags shows no character.

Step 9: Animate With Numbered Frames

9a. The rule

To animate, tag a passage with two or more frames of the same mood, numbered: nora-talk-1 and nora-talk-2. To stop the animation, use a still picture in the next passage: nora-happy. When the player clicks a link, the old passage disappears and its loop stops by itself.

9b. How the flipping works

9c. Timing guide

Tags on the passageReads as
two talk frames plus fastFast chatter or panic
two talk frames, no speed tagOrdinary talking
two talk frames plus slowSlow talking, a gentle sway
two idle frames plus blinkBlinking, breathing
three or four numbered framesA short stop-motion walk or wave

9d. Try it

  1. On Ask, remove the tag nora-talk-2. With one frame, the mouth stops moving. Add it back.
  2. Add the tag fast and play it again. Then try slow.
  3. Make a third frame, nora-talk-3.png, with the mouth half open. Add the tag nora-talk-3 and see how three frames feel.
  4. Make a new mood of your own, such as nora-surprised, and use it in a passage.

9e. Rules to remember

Step 10: Test

  1. In Twine, click Play (or Test) to check the text, links and tags.
  2. Pictures may not appear in this preview, because the story is not yet beside your images folder. That is normal. To check the pictures, publish the story (Step 11), put the HTML file next to the images folder, and open it in the browser.
  3. Click through every path: Start, Ask, then both answers, then Ending, then Start again.
  4. Check each passage against this list: right location, right frame, text readable, no dead end, character fully on screen.
  5. If a picture is missing, open the browser’s console (usually F12, then Console). The script prints a line such as no image found for tag “nora-sad”, which tells you the tag and the file name do not match. Lines about files not found (404) for other formats are normal: the script tries each format in turn.
  6. Try the page on a phone or a narrow browser window to check the small-screen layout.

Step 11: Publish, Host and Exchange

  1. Publish to file. In the story map, open the Build tab and choose Publish to File. The browser downloads one HTML file.
  2. Rename and place it. Rename it index.html and save it in the project folder, next to the images folder.
  3. Open it. Double-click index.html. The story should play with pictures.
  4. Back it up. Back in the Twine library, use the Archive option to save every story as one file, and keep it in the project folder.
  5. Put it online. Upload the whole folder (the HTML file and images) to any web host. A free static host such as GitHub Pages or Netlify Drop works, and so does the site you build in Cheap and Dirty Websites.
  6. Exchange. Swap stories with another group, play them, and say one thing you noticed about how their character moved.

Troubleshooting

ProblemLikely cause and fix
No background or character appearsThe test preview does not find the images, or the file is not beside the images folder. Publish and open the HTML next to images (Step 11).
Background shows but not the characterThe passage has no character tag, or the tag does not match a file name. Check capitals, hyphens and the number at the end.
A tag does nothingThe tag must be exactly the file name without its ending. The console message from Step 10 names the tag it could not find.
Nothing works at all, even for the facilitatorThe Story JavaScript is missing, or it pasted with curly quotes. Paste it again from this page.
Picture is missing online but works on your computerFile names are case-sensitive on a web host. Check the capitals and the ending (.png vs .PNG). The script looks for lowercase endings only.
Character floats above the bottom of the screenThe picture has empty space under the character. Re-crop every frame so the lowest part of the figure touches the bottom edge of the canvas (Step 3e).
Characters look different sizes from picture to pictureEach picture is scaled to fit the same slot, so a loosely cropped picture shows a smaller figure. Use one canvas size and crop for all of a character’s frames.
Character jumps while talkingThe frames have different sizes or crops. Re-export every frame with the same canvas.
White box around the characterThe frame was saved as JPG, or the background was not removed. Use a transparent PNG (or GIF) if you want no box.
Two characters overlapThey have the same name before the mood, so they are treated as one character. Give each character a different name in the file names.
Talking looks like blinking, or the reverseCheck whether blink is on the passage. Remove it for talking and add it only for idle frames.
Link arrow points to a box with a broken outlineThe link text does not match a passage name.
Story is lostBrowser data was cleared. Restore from the archive file, and archive more often.