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.
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.
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.
Twine shows the story as a network of boxes joined by arrows. Players never see the map; they see the published page.
images folder inside it.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.
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.
nora or sam. This name starts every one of their picture files.kitchen and garden.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.
The file name, without its ending, is the tag. Follow these patterns exactly.
| What it is | File name | Tag you will type |
|---|---|---|
| A background | bg-kitchen.jpg | bg-kitchen |
| A still character picture | nora-happy.png | nora-happy |
| An animated mood, frame 1 | nora-talk-1.png | nora-talk-1 |
| An animated mood, frame 2 | nora-talk-2.png | nora-talk-2 |
| A second character | sam-idle.gif | sam-idle |
bg-. They can be .jpg, .jpeg, .png, .gif or .webp.name-mood.png. They can be .png, .gif, .jpg, .jpeg or .webp, and you can mix formats between frames. Use PNG (or GIF) when you want a see-through background; a JPG always has a solid rectangle behind the character.-1 and -2, means “this is a frame of an animation”. Tags that share the same name before the number play together as a loop.nora-happy.png and nora-happy.jpg exist, the first format in the script’s list (PNG) wins.| File name | What it shows |
|---|---|
nora-idle-1.png | Neutral, eyes open |
nora-idle-2.png | Same, eyes closed (the blink) |
nora-talk-1.png | Mouth closed or small |
nora-talk-2.png | Mouth open |
nora-happy.png | Pleased expression |
nora-sad.png | Disappointed expression |
bg-kitchen.jpg | The kitchen picture |
bg-garden.jpg | The garden picture |
Six character frames is plenty. Younger groups can make just nora-idle, nora-talk-1, nora-talk-2 and one reaction.
images folder with the names from the naming rules.bg- pattern.Nora-Talk-1.png and nora-talk-1.png are different files. A tag has to match the file name exactly.
The last column is the tags you will add in Step 8. Keep the plan on paper beside you.
| Passage name | What happens | Tags (Step 8) |
|---|---|---|
Start | We meet the character. | bg-kitchen nora-idle-1 nora-idle-2 blink |
Ask | The character talks and asks for help. | bg-kitchen nora-talk-1 nora-talk-2 |
AnswerYes | The player helps. | bg-garden nora-happy |
AnswerNo | The player refuses. | bg-garden nora-sad |
Ending | The result, with a link to start over. | bg-garden nora-idle-1 nora-idle-2 blink |
Start, and confirm.
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.
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.
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.
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; }
}
tw-story, tw-passage, tw-link and tw-sidebar are Harlowe’s own page elements, used here in place of ordinary div and a tags. The page becomes the picture area, and the passage becomes a semi-transparent white text panel so words stay readable over a busy painting.tw-sidebar { display: none; } hides the back and forward arrows, so make sure no passage is a dead end unless it is a deliberate ending. Ours ends with “Start again”.
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();
})();
bg- becomes the page background, found in the images folder. Each other tag becomes a character picture. It tries .png, .gif, .webp, .jpg and .jpeg in that order, so students do not need to say which format a file is.nora-talk-1, nora-talk-2) are shown one after another as a loop. With no animation tags, a picture simply stays still. An animated GIF plays its own animation, and can also be used as a single tag.
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.
Now the students work only in the passage editor. Every passage gets one background tag and the picture tags of each character who appears.
bg-kitchen, and confirm with Add or Enter.nora-idle-1.Nora is standing by the kitchen door, turning her pockets inside out. [[Ask]]
“Have you seen my keys?” Nora asks. “I had them a minute ago.” [[Help->AnswerYes]] [[Walk away->AnswerNo]]
“You found them!” Nora says. “Thank you.” [[Ending]]
“Oh,” Nora says. “Maybe next time.” [[Ending]]
The evening goes quiet. Nora goes back to the library. [[Start again->Start]]
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.
| Tag | What it does |
|---|---|
bg- then a name | Background. Only one per passage; if there are two, the last is used. |
name-mood | A 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. |
fast | Plays frames quickly, about 0.15 seconds each. |
slow | Plays frames slowly, about 0.6 seconds each. |
blink | Holds 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.
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.
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.
blink, the wait is uneven: a long wait on frame 1, a short flash of the others. That is why a blink looks like a blink and not like talking.| Tags on the passage | Reads as |
|---|---|
two talk frames plus fast | Fast chatter or panic |
| two talk frames, no speed tag | Ordinary talking |
two talk frames plus slow | Slow talking, a gentle sway |
two idle frames plus blink | Blinking, breathing |
| three or four numbered frames | A short stop-motion walk or wave |
Ask, remove the tag nora-talk-2. With one frame, the mouth stops moving. Add it back.fast and play it again. Then try slow.nora-talk-3.png, with the mouth half open. Add the tag nora-talk-3 and see how three frames feel.nora-surprised, and use it in a passage.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.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.index.html and save it in the project folder, next to the images folder.index.html. The story should play with pictures.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.| Problem | Likely cause and fix |
|---|---|
| No background or character appears | The 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 character | The 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 nothing | The 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 facilitator | The Story JavaScript is missing, or it pasted with curly quotes. Paste it again from this page. |
| Picture is missing online but works on your computer | File 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 screen | The 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 picture | Each 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 talking | The frames have different sizes or crops. Re-export every frame with the same canvas. |
| White box around the character | The frame was saved as JPG, or the background was not removed. Use a transparent PNG (or GIF) if you want no box. |
| Two characters overlap | They 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 reverse | Check 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 outline | The link text does not match a passage name. |
| Story is lost | Browser data was cleared. Restore from the archive file, and archive more often. |