GrueWeaver Help

GrueWeaver 1.0 · Last updated: October 15, 2026

GrueWeaver makes text adventures: places to explore, people to talk to, things to pick up, and words the player types. You write a story; GrueWeaver publishes it as a game that plays in any web browser. Stuck? Write to support@widgetpress.com.

Getting started

GrueWeaver runs on a Mac with macOS 13 Ventura or later, or a PC with Windows 10 (version 1809 or later) or Windows 11.

1. Choose File > New Story…, give the story a name and pick where to keep it. GrueWeaver makes a folder of that name for it.
2. Fill in the Title and Author, then choose how to start:
   • Blank: one scene, ready to write. Name it in First scene.
   • Starter template: 3 scenes, a character and a state group. It is a small finished game, “The Rain Jar”, to play and pull apart.
   • Import a Twine story: see Importing from Twine.
3. Click Create. GrueWeaver opens the story at its Introduction.

There is no Save. GrueWeaver writes every change to disk a moment after you make it, and the toolbar shows Editing…, Saving…, Saved or Not saved after the story's name. Undo and Redo, in the Edit menu, cover every change to the story.

The window

• The toolbar, at the top: the sidebar button, Back and Forward, the story's name and whether it is saved, then Publish, Search and Play at the right.
• The sidebar, on the left: the Storyboard, Names, Media, and the lists of everything in your story. Drag its edge to make it wider or narrower.
• The page, in the middle: whatever you picked in the sidebar.
• The inspector, on the right: details of the exit, beat or thing you selected, and which file it is saved in.
• The status bar, at the bottom: the gear opens Game settings, and the check mark runs Check and shows how many problems it found.

Back and Forward step through the pages you have opened, as in a web browser.

The sidebar and the Story tree

At the top of the sidebar are Storyboard (the map of your story), Names (the name pools for extras) and Media (pictures and sound). Below them, type in Filter to narrow every list, and use the button beside it to expand or collapse them all.

• Story: your acts, their chapters, and each chapter's scenes, with the Introduction above Act 1. Use the + buttons for a new act, a new chapter in an act, or a new scene in a chapter.
• Characters, Items, Objects and Buildings: everything in your world. + makes a new one.
• States: your state groups (see Scene states).
• Dialogues: one for each character, and one for each kind of extra.
• Readers: who the story follows. A game starts with one of them, and always has at least one.

In the Story tree, double-click an act, chapter or scene (or select it and press Return, Enter on Windows, or F2) to rename it. Delete or Backspace deletes it, after asking.

Scenes

A scene is a place the player can be: a lane, a cottage, a hill top. Click a scene in the Story tree to open it. Its page shows its name, where it is on the map, Show on map and Rename…, then three tabs.

• Arrival: what the player reads on entering. Below it, the Revisit title (the heading on later visits), the scene's Exits, and two groups of settings. World holds its Chapter, its Terrain (land, sea, indoors and so on) and its State group. Advanced holds Jump to scene, for a scene the player passes straight through, and which state it Arrives in.
• Beats: the paragraphs and lines of dialogue that play here, before the arrival, on arrival, after who and what is here, or as the player leaves. A beat can be for any day and season or only some, can have several alternatives (one is picked at random each time), can play a sound, and can play every visit or a set number of times. Tick Ends the story on a beat to end the game there. Insert token puts in words the game fills in as it plays, such as a character's first name or a greeting for the time of day.
• Who & what is here: the characters, items, objects and buildings in the scene. Use + Add character… (and the other lists) to place one, and the × to take it away.

Renaming a scene keeps every exit that leads to it working. Delete at the foot of the page deletes the scene after asking. A game always has at least one scene.

Exits

An exit is a way out of a scene: north, up, inside, or anything you name.

• Add an exit from a scene's Exits with + Exit to…, or on the Storyboard (below). GrueWeaver adds the way back as well unless you tick One way.
• Click an exit to open it in the inspector. There you set where it Leads to, its Direction, the Action words the player can type to take it, its Name and Description, and Before this exit, words shown as the player leaves.
• Delete exit is at the foot of the inspector.

Under its exits, a scene lists the scenes that lead to it (Leads here).

The Storyboard

Click Storyboard at the top of the sidebar to see your story as a map. The map is a grid of sectors; each scene sits in its sector, and each exit is a line between two scenes. Scenes that aren't on the map yet wait in the tray on the left.

• + Scene adds a scene. + Column and + Row make the map bigger.
• Drag a scene into another sector to move it there.
• Draw an exit by dragging from a scene's right edge onto another scene. Choose its direction and click Add exit.
• Open a scene by double-clicking it. Click an exit's line to open the exit in the inspector.
• Right-click a scene for Open, the state group commands and Delete. Shift-click chooses several scenes, to make a state group of them all at once.
• Layer shows only the scenes of one kind of terrain, such as Indoors or Sea. States picks a state group to preview (see Scene states).

Zoom with the controls in the corner, or drag in the small overview at the lower right to move about a big map.

The Introduction

Every new story begins with an Introduction: the words the player reads before the story starts. It sits above Act 1 in the Story tree. Change its Title, choose where The story begins at, and write its paragraphs. The player types “play story” to leave it, so keep a paragraph that says so; if none does, GrueWeaver offers Add the line. Restore default text puts back GrueWeaver's own words.

The Introduction doesn't count towards the free version's three scenes.

Characters and dialogue

Click + beside Characters to make one. Pick an Archetype (Innocent, Everyman, Lover, Explorer, Rebel, Creator, Ruler, Caregiver, Magician, Hero, Sage or Jester), which gives the character a sensible start, then choose:

• A character: a named person you write. Give a Name (how they are known before introductions, such as “Old Keeper”) and a First name.
• An extra: one of a kind, named automatically, such as guards, gulls or villagers. Give the Kind; each extra gets a name from that kind's pool in Names.

A character's page has Details and Responses (what happens when the player does something with them). You can change the archetype in the page's header; GrueWeaver asks before it replaces anything you changed. In the inspector, + Place in scene… puts the character in a scene. Placed in several scenes, a character is one person who starts in the first and moves to each of the others when the player first arrives there.

Dialogue

Click Open dialogue in a character's inspector, or pick them under Dialogues.

• Questions the player can ask: a word or short phrase. The player adds “?”: the question “lamp” answers “lamp?” and also “what about the lamp?”.
• Answer: each line has Narration and Spoken words. + next line adds another, played in order.
• Then: + reply adds what the player can say next and which answer it leads to, so a conversation can branch. Or tick Ends the conversation. Shows an item has the character show something they carry.

Extras of one kind share their lines; a named character's own lines win over their kind's.

Items, objects and buildings

• Items are things the player can carry: a tool, a weapon, a light, something to wear or read, a key, money or a ticket. Each kind is a template to start from.
• Objects stay where they are: scenery, or a container. A Boat, Aircraft, Land vehicle, Submarine or Spaceship is an object with room inside for the player. In 1.0 the player can drive a land vehicle one scene at a time; the others stay where they are placed, and the player can board them, look around and get out.
• Buildings have an inside the player can go into. Use + Add room… in the inspector to add more rooms.

Place a thing from its inspector with + Place in scene…, or from a scene's Who & what is here. Placing a building or a vehicle adds its inside scene, which counts as a scene. A thing that isn't placed isn't in the game.

A thing's name is fixed once it is made, because its file is named after it; its Display name can change at any time. Its Responses tab sets what happens when the player takes it, uses or wears it, or drops it.

Scene states

A scene can change as the story goes on: a storm rolls in, the lights go out. Each change is a state. Every scene starts in Start, and each state can have its own arrival, beats and who appears.

• A state for one scene: on the scene's page, click + New state… beside its states.
• A state group is a set of scenes that change together, such as every scene in a valley. Make one with + beside States in the sidebar, from a scene's State group, or by right-clicking scenes on the Storyboard.
• What changes it: on an item's Responses tab, under taking, using or dropping it, click + Add a change… and choose what the group becomes. Tick and replays the arrival now to show the player the change at once.
• Exits arrive in the group's current state unless you say otherwise in the exit's Arrives in.

A state group's page lists its states and its scenes, and which scenes still need an arrival for each state. On the Storyboard, pick the group under States to see its scenes together, then pick one of its states to preview it: a red dot marks a scene with no arrival written for that state.

In the starter template, taking the Rain Jar changes the Valley from Start to Clear Skies.

Pictures and sound

Open Media at the top of the sidebar. Drop files on it, or click Import….

• Pictures: PNG, JPG, WebP or SVG, up to 8 MB. GrueWeaver makes every file the game needs from one picture: the picture itself, a thumbnail, and for characters, objects, buildings and readers a map icon in each faction colour. You can replace any of them. Your original is kept in the story folder. Choose a folder in New pictures go in to say what a picture is for; it shows the recommended size.
• Covers and the game icon: the game has three covers (mobile portrait, desktop and tablet portrait, and desktop and tablet landscape) and a game icon. Until you add your own, the game uses GrueWeaver's placeholders.
• Sound: MP3, M4A or OGG, up to 8 MB, used as it is. Convert WAV or AIFF files to MP3 first. A sound over two minutes long is taken as music. Choose a sound for a beat in the beat's inspector.
• GrueWeaver's library: five music tracks, sound effects, and placeholder pictures for characters, items, objects, buildings and readers. A game uses none of them unless you add them. Each carries its credit, which the game's Credits screen shows.

Select a file in Media to see where it is used, replace it, or delete it.

Game settings

Click the gear in the status bar. General holds the game's Title, Author, Version (shown in your game's About box) and Ending (the words printed just before THE END). Reader shows a preview of the game as players will see it, and Plain text…, which turns off music, sound effects, pictures, the stats icon, the map and the economy for a game of words alone.

GrueWeaver's own Settings… is a separate window: on the Mac in the GrueWeaver menu, and on Windows in the File menu. It holds your GrueWeaver Unlimited purchase and, under About, the version and the runtime licence.

Search

Click the magnifying glass in the toolbar, or press ⌘K (Ctrl+K on Windows), and type at least two letters. GrueWeaver searches the text of every scene, its beats included. Click a match to open it, or press Return for the first. Esc closes Search.

Check

GrueWeaver checks your story as you write. Click the check mark in the status bar, or press ⇧⌘K (Ctrl+Shift+K on Windows), for a full check: it builds the whole game and lists what it finds.

• Errors stop the game working, and must be fixed before you publish.
• Warnings and style notes are advice. They never stop you publishing.

Click Go to beside a problem to open the place it is in. Some problems offer a fix of their own, in one click, and Undo takes it back.

Play

Click Play in the toolbar to play your game right in GrueWeaver. It starts from the scene you have open; Start at picks another. You can also choose the Day and Season it starts in, if your story has more than one, and preview it on a Phone or a Desktop. Restart starts again with your latest changes. While the game plays, Play in the toolbar becomes Stop: click it to go back to writing.

Importing from Twine

Choose File > New Story…, then Import a Twine story, and Choose File…. GrueWeaver reads a story published from Twine 2 (Build > Publish to File, an .html file) or a Twee 3 file (.twee).

• Each passage becomes a scene, and each link an exit. The start passage becomes the first scene.
• Macros, variables, images and HTML aren't brought across; each one is listed. Text inside a condition is kept, every branch of it, so read those scenes through.
• Before anything is made, a report lists every change. Save report keeps a copy. Open story makes the story; Back returns to New Story.

A big Twine story imports in full in the free version, and you can edit and play all of it. Publishing it needs GrueWeaver Unlimited if it has more than three scenes.

Publishing

GrueWeaver publishes your game as a small website: a folder of files that runs in any modern browser.

1. Fix anything Check marks as an error. Publish waits until there are none; warnings don't stop it.
2. Choose File > Publish Game…, or click Publish in the toolbar.
3. Choose what to make:
   • Web folder: a folder, named after your game, to upload to any web host.
   • itch.io package: the same files in one .zip, ready to upload to itch.io. GrueWeaver counts the files against itch.io's limit of 1,000; above 1,000 the option is off, so publish a web folder and host it elsewhere.
4. The first time you publish, GrueWeaver shows the licence your game carries (see Your game and the licence). Read it and choose I agree, publish.
5. Choose where to save. GrueWeaver says where the game is when it's done.

Upload the folder as it is. Don't rename the 1 folder inside it or move files about: the game finds its files by these paths. Your story's own working files are never included.

Why double-clicking index.html doesn't work

If you open index.html straight from your disk (an address starting file://), you see a blank page or an error. That is the browser, not your game: browsers don't run a game like this from files on your disk, for your safety, and saved progress needs a real web address too. So put your game on a web host, or try it on your own computer with a one-line local server. Open a terminal in the published folder (the one holding index.html) and run:

• Mac: python3 -m http.server 8000
• Windows, with Python installed: py -m http.server 8000

Then open http://localhost:8000 in your browser. Stop the server with Ctrl+C.

On itch.io

1. Publish an itch.io package.
2. On itch.io, choose Upload new project and set Kind of project to HTML.
3. Under Uploads, upload the .zip and tick This file will be played in the browser.
4. Save it as a draft first and play it there. When it works, make it public.

To update it, publish a new package and replace the old file. A player part-way through is told the game has been updated, and chooses to continue or start again.

On any other web host

Any host that serves plain files works: upload the folder, keeping its structure, for example as yoursite.com/mygame/. Players' saved progress belongs to the address the game was played at, so keep your game at the same address when you update it.

What is in the folder

Free version and Unlimited

GrueWeaver is free to download, and the free version does everything except publish a game bigger than three scenes. Every scene counts, building and vehicle interiors included; the Introduction doesn't. A bigger game is refused, not cut down, with a message such as:

This story has 12 scenes. The free version publishes games of up to 3 scenes.

Nothing in your story is lost: keep writing, and publish when you're ready. When placing a building or vehicle would take a free game past three scenes, GrueWeaver tells you first.

GrueWeaver Unlimited publishes games of any size. It is $29.99, once: one in-app purchase, no subscription, no account. Buy it from Upgrade to Unlimited… (on the Mac, in the GrueWeaver menu; on Windows, in the Help menu), from Settings…, or from the Publish sheet.

New computer, or reinstalled? Sign in to the store with the same account, then choose Restore Purchases: on the Mac it is in the GrueWeaver menu, and on Windows in the Help menu. GrueWeaver also checks with the store each time it starts, so it often finds the purchase by itself.

Your game and the licence

Every published game carries the GrueWeaver Runtime, our game engine, under a short licence: LICENSE-RUNTIME.txt in your game's folder. The licence itself is what counts; this is a summary.

• Your content is yours. Your words, characters, maps, pictures, sound and story files belong to you. We claim none of it. Make sure you have the rights to everything you put in, including anything you import from Twine.
• Share it, sell it, host it anywhere. Give your game away or sell it, on itch.io, your own site or any web host. You may also wrap it in an app of your own.
• No royalties, no revenue share, no credit required. That holds for games from the free version and from GrueWeaver Unlimited alike.
• The engine goes with your game, unchanged. You may not take the engine out to use on its own, change it, or use it to build another game-making tool. Keep the licence file and the copyright notices.
• Styling is yours. Your game's stylesheet, and any CSS you add, are yours to change.
• A game keeps the engine it was published with. Publish again from a newer GrueWeaver and the game gets that engine, under the licence that comes with it.

If your game uses music from GrueWeaver's library, its credit is part of your game and shows on the game's Credits screen. Most of the tracks' licences require that credit, so leave it in. You can read the licence any time in GrueWeaver's Settings…, under About.

Where your stories live

A story is an ordinary folder, wherever you saved it, named after the story. Inside are:

• <Name>.gwstory: double-click it to open the story;
• json/: the story itself, in plain text files;
• img/, audio/ and styles/: your pictures, sounds and stylesheet;
• .grueweaver/, a hidden folder: GrueWeaver's own files, such as your original pictures.

Open a story with File > Open Story… or Open Recent. On Windows you can also choose the folder itself with File > Open Story Folder…. On the Mac, the first time you open a story by double-clicking it, macOS asks once for permission to use its folder: choose the folder it shows and click Allow. GrueWeaver remembers it.

Backing up. Copy the folder, keep it in a backup or sync folder, or put it under git, like any other folder. To make one file of it, for a backup or to send, choose File > Export Story Archive…; it saves the whole story as a .zip. To use it again, extract the whole zip into a new folder, then double-click the .gwstory file inside.

Edits made outside GrueWeaver

The story's files are plain text, so you can change them in another editor, or let a sync service or a git pull change them. GrueWeaver never writes over a change made outside it. If you have no unsaved changes to that file, it simply takes the new version and says so. If you do, it asks: Keep my changes or Use the version on disk. Whichever you choose, it saves the other version as a copy in the story's .grueweaver/conflicts folder for 30 days.

Privacy

Your stories stay on your computer until you publish them. GrueWeaver has no account and no analytics, and sends nothing about you or your stories to us, except a feedback report if you choose to send one (Help > Provide Feedback…; nothing from your stories is included). Purchases go through the Mac App Store or the Microsoft Store. A game you publish saves its players' progress in their own browser. Our privacy policy covers GrueWeaver.

Keyboard shortcuts

Back and Forward don't work while you're typing in a field. On the Storyboard, Shift-click chooses several scenes, and a double-click opens one.

Getting help

To report a problem or suggest something from inside the app, choose Help > Provide Feedback…. Leave the email blank to send it anonymously; with “Include diagnostic info” ticked, it tells us your version and system for you.

Or write to support@widgetpress.com. A person reads every message, usually within two working days. Tell us what you did, what you expected and what happened instead, and which version you have (Mac: GrueWeaver > About GrueWeaver; Windows: File > Settings… > About). If you can, attach the story, zipped with File > Export Story Archive…. We use what you send only to answer you. The Support page answers common questions, including purchases and refunds.

↑ Back to the top