Adventure Workshop

The User Manual

Play, create, and edit text adventures. No installs, no accounts, no mercy for grues.

Covers the release with 360° panorama rooms · August 2026


About this manual

Adventure Workshop is two programs wearing one coat. The Player runs a text adventure. The Builder makes one. They share a file — a single .json document that holds every room, item, puzzle and picture in your world — and that file is the only thing you ever need to move, back up, or hand to someone else.

This manual is arranged in three parts. Part I is for anyone who sits down to play. Part II is the builder, control by control. Part III is getting your adventure out into the world. The appendices are the parts you will actually keep coming back to: the command list, the effect list, and the table of what every warning means.

You do not have to read it in order. If you have ten minutes and want a finished, playable adventure at the end of them, start at Chapter 8.

Conventions

Style Meaning
LOOK Something the player types into the game. Case doesn’t matter; small capitals are just tradition.
Export A button or control in the builder.
Room A tab in the builder’s side panel.
adventures/index.json A file or folder.

The plates. The fifteen figures are SVG files in docs/figures/, drawn as printed plates: warm paper stock, ink line art, and true screen colours taken from the app’s own stylesheet wherever a figure depicts the program. They scale without loss, print cleanly, and can be edited in any vector tool. Nothing in the text depends on them — but it is a better book with them.

FIG. 0.1 THE FOYER A hollow voice says, ‘Nice try.’ > XYZZY FOYER HALL OFFICE DEN CELLAR ★ 🔒 TWO HALVES OF THE SAME PROGRAM

Figure 0.1 — Frontispiece. The two halves of the program, side by side: the terminal that plays a world, and the pencilled grid that plans one.


Part I — Playing

1. Starting a game

There are four doors into a game, and they all end up in the same place.

From the menu. Open the site’s front page. Adventures published on that site are listed under Play; click one and it loads. The list comes from a small catalogue file, so it always reflects whatever the site owner has uploaded.

From a file. Click Open an adventure file… and choose a .json adventure from your computer — or drag the file onto the box. This works even with no internet connection and no web server, which is why it is the classroom’s favourite door.

From a link. A URL ending in ?adv=the-caverns loads that adventure directly. This is the link you send people.

From a single file. If someone hands you an adventure as an .html file, double-click it. The entire game — engine, story, pictures — is baked into that one file. Nothing to install, nothing to unpack, no internet required.

FIG. 1.1 1 · FROM THE MENU click an adventure on the front page 2 · FROM A FILE open or drag a .json — works offline 3 · FROM A LINK a URL ending ?adv=the-caverns 4 · FROM ONE .html FILE the whole game, baked in THE CAVERNS A cold seam of rock opens ahead. Water moves somewhere below. > north > ONE PLAYER, FOUR DOORS

Figure 1.1 — The four doors. Menu, file, link, or a single .html file — all four arrive at the same player.

On a Game Boy Color. There is also a door that leaves the browser behind. An author can export an adventure as a .gbc cartridge image (Chapter 20); it plays in any Game Boy Color emulator or, flashed to a cartridge, on the real handheld. The game is the same one — same parser, same puzzles, same text, pictures redrawn in Game Boy tiles — but you steer it with buttons rather than a keyboard: the D-pad walks, START opens a menu of verbs, and the menu types the command for you. Appendix D has the buttons.

If the adventure has structural problems, the game says so in dim text at the top — lines beginning [adventure warning]. Those are messages for the author, not for you. The game will still run; something in it may simply be missing.

2. The screen

The player is a terminal. Text scrolls upward; you type at the bottom.

The transcript is everything that has happened. Room names appear in the brightest weight, your own commands are echoed back with the prompt character, and quieter system messages — saves, hints, the parser shrugging — appear dim and italic. Occasionally something will glow in the accent colour: that is the author highlighting a moment, and usually means you have found something.

The prompt line sits at the bottom with a blinking prompt character. Press ↑ and ↓ to walk back through commands you have already typed, which is the difference between a pleasant evening and a lot of retyping.

The visuals pane, in illustrated adventures, is pinned above the transcript and stays in view while the text scrolls beneath it. A room may show a flat picture, a draggable 360° panorama, or nothing at all — the author chooses per room, and all three can appear in the same adventure. Pictures can change as you solve things. A safe that was closed a moment ago may now be open.

FIG. 2.1 360° / PICTURE / NOTHING THE FOYER You are standing in the front hall. A coir doormat reads GO AWAY. A door leads north. > look under the mat You lift the doormat. A brass KEY is stuck underneath. You pocket it. (Saved as “quicksave”.) > take the key 1 the visuals pane — pinned, so it stays while the text scrolls 2 room title 3 description 6 prompt character, blinking 4 your command, echoed back 5 a system line — dim italics 7 input line — use ↑ and ↓ for history ILLUSTRATED MODE, GREEN THEME

Figure 2.1 — The player screen, labelled. Illustrated mode in the green theme: ① the pinned visuals pane, ② room title, ③ description, ④ your echoed command, ⑤ a system line, ⑥ the blinking prompt character, ⑦ the input line.

3. Speaking to the parser

Type what you want to do, in plain words. The parser is friendly but literal.

> look
> examine the brass key
> take lantern
> open the safe with the key
> look under the doormat

It ignores the small words — the, a, an, to, my, some, of, at — so EXAMINE THE BRASS KEY and EXAMINE BRASS KEY are the same command. Case never matters.

Naming things. Objects answer to several names, and the parser picks the most specific one that fits. If a room holds both a map and a plat map, typing EXAMINE PLAT MAP gets you the plat map — an exact match beats a partial one, and a longer name beats a shorter one. When you are being ambiguous, be more specific.

Two objects at once. Some puzzles want a tool and a target. Both of these word orders work, and they mean the same thing:

> use the quarter on the cabinet
> unlock the door with the brass key

Read it as do this to that. The word after on, onto, in or into is the target; the word after with or using is the tool.

When it doesn’t understand, the parser says so — in the author’s own words, if they wrote some. It is not a hint that you are close. It means those words did not parse.

HELP lists the verbs the author expects you to need. The full built-in verb list is in Appendix A, and it is longer than HELP lets on.

4. Getting around

Rooms connect in six directions: north, south, east, west, up, down.

> north          > n          > go north          > climb up

Single letters work: N S E W U D. So do UPSTAIRS and DOWNSTAIRS, and the verbs GO, WALK, HEAD, RUN, TRAVEL, ENTER and CLIMB in front of a direction.

Doors can be locked. A locked exit tells you so in the author’s words. If you are carrying the right key, it usually opens the moment you try — you do not have to unlock it as a separate step. Some locks are not opened by keys at all, but by solving something.

The engine does not list the exits for you. They are described in the room description, the way they were in 1983. Read the prose; it is load-bearing. The same goes for the objects in the room — with one exception. Anything that arrives in a room after the game starts, because you dropped it or the story put it there, is listed separately as Also here: … so it can’t be lost.

5. Things

> take the lantern            > inventory     (or just I)
> drop the lantern            > examine the lantern
> search the desk             > look under the rug
> read the letter             > open the box

Not everything can be picked up, and the game will tell you when something resists. SEARCH X and LOOK UNDER / BEHIND / INSIDE X are the phrases that turn up hidden things most often; authors hang secrets on them.

Some objects are doors to the wider web — a computer, a photo album, a business card. Opening, using or reading one opens a page in a new browser tab. The game tells you before it does this.

6. 360° rooms

Some rooms are photographs you can stand inside.

Drag the panorama to look around. Scroll to zoom in and out. Everything else in the game works exactly as it did — the panorama is a view, not a separate mode, and you can still type at the prompt.

Two kinds of marker appear on the picture:

Dots come and go with the world. Take the token off the table and its dot disappears, because the token is in your pocket now.

If your browser cannot do 3D graphics, the panorama quietly becomes a flat picture and the game carries on. Nothing is lost but the dragging.

FIG. 6.1 glowing pool north THE SUNKEN GALLERY Something bright moves under the water. > examine pool > a DOT examines or opens — and vanishes with its item a DIAMOND travels — locks and all honoured drag to look scroll to zoom EVERY HOTSPOT JUST TYPES A COMMAND YOU COULD HAVE TYPED

Figure 6.1 — Inside a panorama. A dot examines; a diamond travels. Both simply type a command you could have typed yourself.

7. Saving, loading, and the look of the thing

Your progress autosaves every turn into a slot called continue. Close the tab mid-puzzle and the next time you start that adventure it will offer to pick you up where you left off — type LOAD CONTINUE.

Beyond that:

Command What it does
SAVE Saves to a slot called quicksave.
SAVE tower Saves to a slot you name.
LOAD / LOAD tower Restores quicksave, or the slot you name.
SAVES Lists every save you have for this adventure.
CODE Prints a long copyable save code — your whole game as text.
RESTORE <code> Restores from a pasted code, on any device.
RESTART Begins again from the first room.

Saves live in this browser, on this computer. The save code is the escape hatch: copy it, mail it to yourself, paste it into the same adventure on another machine and you are exactly where you were. It is also the only save that survives clearing your browser data. Codes are tied to one adventure — pasting The Caverns’ code into The Lantern politely declines.

On a cartridge. The Game Boy version saves to the cartridge’s battery instead: the same continue autosave every turn (the title screen offers CONTINUE), plus three numbered slots under SAVE/LOAD in the START menu, or by typing SAVE 1 on the on-screen keyboard. There are no save codes there; the cartridge is its own escape hatch. Saves are tagged with the adventure’s id, so flashing a different adventure onto the same cartridge starts clean.

Themes. Type THEME followed by green, amber, mono or paper. Green and amber are phosphor CRTs with scanlines and a faint flicker; mono is a clean dark terminal; paper is ink on white, for reading in daylight or printing a transcript. The author picks the default; you can always override it.

FIG. 7.1 THE FOYER A coir doormat reads GO AWAY. > look under mat A brass KEY is stuck underneath. > GREEN phosphor · scanlines the default THE FOYER A coir doormat reads GO AWAY. > look under mat A brass KEY is stuck underneath. > AMBER phosphor · scanlines THE FOYER A coir doormat reads GO AWAY. > look under mat A brass KEY is stuck underneath. > MONO clean · no CRT effect THE FOYER A coir doormat reads GO AWAY. > look under mat A brass KEY is stuck underneath. > PAPER ink on white · daylight TYPE THEME GREEN | AMBER | MONO | PAPER AT ANY PROMPT

Figure 7.1 — The four themes. The same three lines, four ways. Green and amber carry the scanlines; mono and paper are clean.


Part II — Building

8. Ten minutes to an adventure

The fastest useful path through the builder. Open build.html.

  1. Name it. Go to the Adv. tab. Set the title, your name, and a one-line blurb. This is what people see on the menu.
  2. Make rooms. On the map, click any empty square. A room appears and the cursor lands in its name field. Type the name, then write the description in the box below — and mention the doors and objects in that prose, because the engine will not list them.
  3. Connect them. Click the gap between two neighbouring rooms. One click makes a two-way passage. Keep clicking to cycle through one-way each direction, then back to nothing.
  4. Add a thing. On the Items tab, type a name and press + Add. Give it a description, tick Takeable, then go back to a room and add it under Items starting here.
  5. Make a puzzle. On the Rules tab, press + New rule. In verbs type search; aim it at your item; add a say something effect. That is a puzzle.
  6. Play it. Press ▶ Playtest in the top bar. It opens in a new tab with debug commands available.
  7. Keep it. Press Export. Your work also autosaves in this browser continuously, but files are forever and browsers are not.

Everything after this chapter is detail.

FIG. 8.1 STEP 1 Name it title, author, blurb STEP 2 NEW Make rooms click an empty square STEP 3 Connect them click the gap between STEP 4 Add a thing Items tab, + Add STEP 5 WHEN IF THEN Make a puzzle Rules tab, + New rule STEP 6 THE FOYER A doormat reads GO AWAY. > Play it ▶ Playtest STEP 7 .json Keep it Export — files are forever TEN MINUTES, START TO FINISHED Drafts autosave as you go. Everything after this is detail.

Figure 8.1 — The seven steps. Name it, make rooms, connect them, add a thing, make a puzzle, play it, keep it.

9. The builder at a glance

The builder is one screen with three regions.

The top bar holds everything that acts on the whole adventure: the draft selector, New, Import, Export, ▶ Playtest, the floor controls, and a small status area at the right that tells you when your work was saved.

The map fills the left. It is 18 squares across and 12 down — one floor at a time.

The side panel on the right has five tabs:

Tab Holds
Room The selected room: name, text, pictures, items, exits, entry effects.
Items Every object in the adventure.
Rules Every puzzle.
Extras Easter eggs and the game’s stock phrases.
Adv. Title and settings, sharing, checks, and deleting the draft.

FIG. 9.1 AW BUILDER The Caverns ▾ New Import Export ▶ Playtest ▼ level 0 [0* 1] ▲ saved Cave Mouth ★ ◆ Gallery ▼ ◆ Ledge Pool 🔒 Room Items Rules Extras Adv. NAME The Sunken Gallery DESCRIPTION Something bright moves under the water. EXITS NORTH Ledge · z0 ⇆ 🔒 DOWN Pool · z0 THE TOP BAR acts on the whole adventure THE MAP 18 squares by 12, one floor at a time THE SIDE PANEL five tabs: Room, Items, Rules, Extras, Adv. ★ start room ◆ panorama ▼ exit down 🔒 locked door

Figure 9.1 — The builder, labelled. The top bar acts on the whole adventure; the map is the world’s shape; the side panel edits whatever is selected.

Your work saves itself. Every change is written to this browser’s storage about half a second after you stop typing; the status area flickers … and then saved. Closing the tab saves immediately. There is no save button and you do not need one.

If the status area ever says SAVE FAILED, the browser’s storage is full — usually from embedded pictures. Export at once, then see Chapter 21.

10. Drafts: keeping more than one world

The builder can hold as many adventures as your browser has room for. The dropdown at the top left lists them; choosing one saves the current draft and opens that one.

Control Does
New Starts a blank adventure with one room, and opens the Adv. tab so you can name it.
Import Loads a .json from your computer as a draft. If a draft with the same id already exists, it asks before overwriting.
Export Downloads the current adventure as <id>.json, and runs the checks on the way past — if anything looks wrong, the status area says how many warnings to go and read.
Delete this draft (Adv. tab) Removes it from this browser only. Files you have exported are untouched.

A draft is identified by its adventure id, not its title. Change the id and the draft moves with you; the old copy is cleaned up. But player saves are keyed to the id too, so changing it after publishing orphans everyone’s progress. Pick an id early, then leave it alone.

A word about browser storage. Drafts live in one browser profile on one machine. They survive closing the tab, restarting, and rebooting — but not clearing site data, not private-browsing windows, and they do not follow you to another computer. Export regularly. The .json file is the real adventure; the draft is a convenience.

11. The map

The map is the shape of your world, and it is the fastest surface in the builder.

Make a room. Click any empty square.

Select a room. Click it. Its details fill the side panel.

Move a room. Drag it to another square. Dropping onto an occupied square does nothing, harmlessly. Position is for your benefit only — players never see this map — so rearrange freely.

Connect two rooms. Click the gap between neighbours. Each click advances through the cycle:

nothing  →  two-way  →  one-way (A to B)  →  one-way (B to A)  →  nothing

A plain line is two-way; an arrow is one-way. A padlock on the line means at least one side is locked. If the click refuses and the status area complains, one of those two rooms already has an exit in that direction pointing somewhere else — fix it in the Room tab’s exit list.

Up, down, and long distances are not clickable on the map, because the map is flat. Set those in the Room tab, where you can connect any room to any other room on any floor.

Floors. The ▲ and ▼ buttons in the top bar change which floor you are looking at. The label between them shows the floor you are on and, in brackets, every floor that has rooms — with a * on the current one. A new room is created on whichever floor you are viewing.

The badges in the corner of each room tile:

Badge Means
★ The start room.
▲ / ▼ Has an exit up / down.
◉ Has a 360° panorama.
▣ Has a static picture.

FIG. 11.1 A B nothing A B two-way A B one-way A → B A B one-way B → A A B nothing click click click click A B 🔒 a padlock on the line means one side is locked — set it in the Room tab and separately: CLICK THE GAP BETWEEN TWO NEIGHBOURS

Figure 11.1 — The exit cycle. Each click on the gap advances one state. A padlock on the line means one side is locked.

12. The Room tab

Everything about one place.

Id and rename. The grey line at the top shows the room’s internal id. Players never see it. rename id changes it and repairs every reference — exits pointing here, rules mentioning it, the start room setting — so renaming is safe.

Name is the room’s title in the transcript. Description is the prose beneath it; blank lines make paragraphs.

Write the exits and the objects into the description. The engine does not list them. This is a design decision, not an omission — a room described as “A cramped office. The only door is behind you, north.” reads like a story; a room followed by Exits: north reads like a spreadsheet.

Visuals. Each room can have a 360° panorama, a flat picture, or neither. If both are set the panorama wins. Note that none of it appears in the game unless the adventure’s display mode is illustrated — the heading tells you when it isn’t, and the setting is on the Adv. tab.

Items starting here. Objects the player will find in this room at the start of the game. Add one from the dropdown; the list notes if it is being moved from another room, because an object can only start in one place. The ✕ removes it from the room without deleting the object itself.

Exits. All six directions, always shown. Choose a destination room from the dropdown — any room, any floor, adjacent or not. Two buttons appear once an exit exists:

Field Effect
Opens with An item that unlocks the door automatically when the player is carrying it. Leave it empty for a door only a rule can open.
Locked message What the player is told when they try. Defaults to “It’s locked.”
Unlock message What they are told when the key works.

When the player enters. Two optional lists of effects: first visit only and every visit. These use the same effect editor as rules — see Chapter 14 — and are the natural home for atmosphere on arrival, a flag set the first time someone finds a place, or a trap that fires the moment they walk in.

★ Set as start room makes this the first room of the game. Delete room removes it and cleans up any exits pointing at it.

FIG. 12.1 Room Items Rules Extras Adv. id: sunken-gallery rename id NAME The Sunken Gallery DESCRIPTION A shelf of wet rock. Something bright moves under the water. The way out is north; a crack drops away below. Mention exits and items — the engine won’t. VISUALS PANO FILE PATH adventures/panos/gallery.jpg Edit hotspots (2)… remove pano ITEMS STARTING HERE brass token carved bowl ✕ ✕ EXITS NORTH The Ledge · z0 ⇆ 🔒 OPENS WITH (AUTO-UNLOCKS WHEN CARRIED) brass token LOCKED MESSAGE The slab will not shift. UNLOCK MESSAGE ⇆ APPEARS ONLY WHEN THE WAY BACK IS MISSING click it to add the matching return exit THE PADLOCK opens these three fields PANORAMAS ARE PATH-REFERENCED never embedded — upload the file too renaming the id is safe: every reference is repaired for you EVERYTHING ABOUT ONE PLACE

Figure 12.1 — The Room tab. Note the ⇄ button: it appears only when the way back is missing, so its presence is itself a hint.

13. The Items tab

Items are everything the player can look at, pick up, or use — including things that never move, like a painting or a fireplace. If a player might type its name, it is an item.

Type a name, press + Add (or Enter). The list shows every object with, at the right, where it currently lives:

Selecting an item opens its editor:

Field Notes
Name What the player sees in the inventory and in messages.
Aliases Comma-separated words the parser will accept. Include the plain noun and any nickname: key, brass key, little key. More specific wins — see Chapter 3.
Description The EXAMINE text. Also what SEARCH prints if no rule intercepts.
Takeable Whether it can be picked up. Off by default, deliberately: most scenery is not portable.
Hidden until a rule reveals it Starts invisible. Something must reveal or give it, or the player will never meet it.
Open this URL… Makes the object a door to a web page. OPEN, USE or READ opens it in a new tab. The link label is the friendly name shown as it opens.

Place in (room) puts the item into whichever room is currently selected on the map — the fast way to distribute objects. Delete item removes it from the library and from every room; rules that mention it are left alone, on purpose, so you can see what broke and decide.

FIG. 13.1 one item, five fields NAME brass key shown in the inventory ALIASES key, brass key, little key everything a player might call it — the most specific one wins DESCRIPTION A small brass key, slightly gummy. the EXAMINE text TAKEABLE ☑ yes off by default — most scenery isn’t portable HIDDEN ☑ until a rule reveals it something must reveal or give it, or it is unreachable If a player might type its name, it is an item — including the things that never move: a painting, a fireplace, a doormat that reads GO AWAY. ANATOMY OF AN ITEM

Figure 13.1 — Anatomy of an item. One object, five fields. The aliases line is everything a player might call it.

14. The Rules tab — puzzles

A rule is one sentence with four parts:

WHEN the player types one of these verbs at this thing, IF the world is in this state, THEN these things happen — OTHERWISE these other things happen.

That is the whole puzzle system. There is no scripting language, and there does not need to be.

WHEN — the trigger

Field Meaning
Verbs Comma-separated. Phrases work: search, look under, lift.
Aimed at The item the player’s noun must resolve to. Or nothing (bare verb) — the rule fires only when the verb is typed alone, like PRAY. Or anything at all — fires with or without an object.
Using An optional second object, for USE X ON TARGET and UNLOCK TARGET WITH X.
Fires at most once Tick for one-shot events: a cutscene, a trap, a discovery.

The item you aim at must be present or carried for the rule to fire — a rule about the safe stays quiet in every room but the one with the safe in it.

IF — the conditions

Add as many as you like; all must be true. Each row has a not button that inverts it.

Condition True when
player has item It is in the inventory.
flag is set That flag has been set.
player is in room They are there right now.
player has visited They have been there at some point.
item is revealed It is no longer hidden.
item is gone It has been destroyed or removed.

Flags are the world’s memory: invented names you set and check, like met-the-dog or power-on. Type a new one and it joins the autocomplete list everywhere else in the builder. Nothing needs declaring.

With no conditions at all, the rule always fires when the trigger matches.

THEN — the effects

Effects run top to bottom. Each row can be reordered with ↑ ↓ or removed with ✕. The full list is in Appendix B; the ones you will use daily are say something, give an item, reveal a hidden item, set a flag, unlock an exit, and end the game — player wins.

Say something has three styles: normal, highlight (the accent colour — for discoveries and good news) and quiet (dim italics — for asides and stage directions).

OTHERWISE — the fallback

This is where the rule system earns its keep, and the behaviour is worth understanding exactly:

That second behaviour is how you build ladders. Three rules on the same verb, in order:

1. OPEN SAFE   if flag "safe-open" is set     →  "It's already open."
2. OPEN SAFE   if player has the brass key    →  "The key turns…"  set flag  reveal contents
3. OPEN SAFE   (no conditions)                →  "Locked. There's a keyhole."

The first matching rule wins. Rule 3 has no conditions, so it catches everything the first two didn’t. Give none of them an OTHERWISE and the chain just works.

Order matters, and it is yours to set. Rules are checked top to bottom, and they get first crack at every command before the built-in verbs — which means you can override TAKE, OPEN, or anything else, for one specific object, without affecting the rest of the game. Reorder with the ↑ ↓ buttons in the rule list.

FIG. 14.1 RULE id: find-key WHEN the player types search, look under at the doormat verbs, comma-separated — phrases work the target item IF all of these hold NOT player has item: brass key add as many as you like; any row can be inverted with NOT (leave empty and it always fires) THEN these happen, in order 1. say “You lift the doormat. A brass KEY is stuck underneath.” 2. give the player the brass key OTHERWISE say “Just floor under there now.” optional — leave it off and a failed IF lets the next rule try instead ONE PUZZLE IS ONE SENTENCE

Figure 14.1 — The rule sentence. One puzzle is one sentence, filled in: the doormat, the brass key, and what to say the second time.

FIG. 14.2 > open the safe RULE 1 OPEN SAFE — if flag “safe-open” is set → “It’s already open.” not set — falls through no RULE 2 OPEN SAFE — if player has the brass key → “The key turns…” → set flag “safe-open” → reveal the contents ✓ CAUGHT nothing below gets a turn RULE 3 OPEN SAFE — no conditions → “Locked. There’s a keyhole.” the catch-all, if nothing above fires THE BUILT-IN VERBS take, drop, examine, open, go… the floor everything lands on checked top down THREE RULES ON ONE VERB, IN ORDER Give none of them an OTHERWISE and the chain just works.

Figure 14.2 — The ladder. The command falls until a rule’s conditions hold. The built-in verbs are the floor everything lands on.

15. The Extras tab

Easter eggs are exact phrases the game answers before it considers anything else — no verb parsing, no rules, just the phrase and the reply. XYZZY is traditional. So are PLUGH, HELLO, and your own name. Type the phrase, press + Add, write the response.

Standard responses are the game’s stock phrases, one per line — the engine picks a line at random each time, so several lines means variety:

Pool Used when
unknown The parser didn’t understand at all.
noExit There’s no exit that way.
cantTake Something can’t be picked up.
cantOpen Something doesn’t open.

Leave a pool blank to use the built-in defaults, which are perfectly good. Fill one in when your world has a voice of its own — the difference between “You can’t go that way.” and “The corridor ends. The wallpaper judges you.” is most of a game’s personality.

HELP text is what HELP prints. Write it as a nudge toward the verbs your particular adventure cares about.

16. The Adv. tab

The adventure as a whole.

Setting Notes
adventure id The published filename and the key for player saves. Changing it after publishing orphans everyone’s progress. Choose once.
Title, Author, Blurb Shown on the menu and at the start of the game.
Start room Where the player begins.
Display mode text — transcript only. illustrated — the visuals pane appears above the transcript, showing each room’s panorama or picture, or nothing for rooms that have neither.
Default theme green, amber, mono or paper. Players can override with THEME.
Prompt character The character at the input line. Defaults to >.

Contents counts your rooms, items, rules and eggs — a quiet progress bar.

Share is Chapter 19. Checks is Chapter 20. Danger deletes this draft from this browser, and only from this browser.

17. 360° rooms and hotspots

A panorama turns a room into a place you can stand in and look around.

Preparing the image

You need a 2:1 equirectangular panorama — twice as wide as it is tall. Any 360° camera produces these; so do phone panorama apps, and so do several AI image generators if you ask for equirectangular output.

Unlike static pictures, panoramas are never embedded in the adventure file. They are far too big. They stay as separate image files, and the adventure stores a path to them.

The builder can prepare one for you. Under Big pano? Convert to a web-ready JPEG, choose your image. The builder resizes it to at most 4096 pixels wide, compresses it to JPEG, downloads the result named after the room, and fills in the path field pointing at adventures/panos/. The status area reports the new size. Your remaining job is to upload that file to that folder on your site — see Chapter 19.

Any relative path works, so an existing folder of panoramas is fine; type the path in directly.

Placing hotspots

Click Edit hotspots to open the editor. You get the panorama, a crosshair fixed in the centre, and a list.

The workflow is: drag the view until the crosshair sits on the thing, then place.

Control Does
+ Place hotspot at crosshair Drops a new hotspot where you’re looking.
+ travel hotspot… Drops a hotspot that walks the player in the direction you choose.
Aim here Moves an existing hotspot to the crosshair. Use it to nudge.
Show Turns the view to face a hotspot, so you can find one you’ve lost.
✕ Deletes it.

Each hotspot has three settings:

Because a hotspot just types a command, every hotspot puzzle is an ordinary rule, and everything clickable is also typeable. There is no separate hotspot logic to learn, and no player is ever locked out for preferring the keyboard.

Travel hotspots are hotspots whose command is a bare direction. They render as diamonds instead of dots and walk the player through that exit, honouring locks and locked messages. Put one on a door.

The numbers at the right of each row are the hotspot’s bearing — yaw and pitch in degrees. You never have to type them, but they are there if you want to place something precisely.

FIG. 17.1 AW BUILDER HOTSPOTS — THE SUNKEN GALLERY Done + + Place hotspot at crosshair + travel hotspot… ▾ #1 brass token ▾ Aim here Show ✕ brass token examine token 44°/-12° #2 — no item — ▾ Aim here Show ✕ label on hover north -170°/8° Drag the view until the crosshair sits on the thing, then Place. 1. DRAG until the crosshair sits on the thing 2. PLACE a hotspot lands where you looked 3. COMMAND a bare direction makes a TRAVEL hotspot — drawn as a diamond bind an item and the hotspot comes and goes with it DRAG, AIM, PLACE

Figure 17.1 — The hotspot editor. Drag, aim, place. Hotspot #1 is bound to an item; #2 is a travel hotspot, its command a bare direction.

Changing the view mid-game. The change a room’s 360° panorama effect swaps the image on puzzle state, exactly like swapping a picture — a cave dark before you light the lantern, and lit afterwards. Its twin, change a room’s picture, does the same for flat images.

18. Playtesting

▶ Playtest stages the current draft and opens it in a new tab. Your work is saved first, so nothing is at risk.

The playtest tab prints its debug commands at the top:

Command Does
/flags Prints the current room, every set flag, your inventory, and the turn count.
/tp <roomId> Teleports to a room — anywhere, ignoring exits and locks. With no valid id, lists the room ids.
/give <itemId> Puts an item straight into your inventory.
/reveal <itemId> Reveals a hidden item in the current room.

These exist only in playtest. Published adventures have no debug commands, so there is nothing to strip before you share.

Playtest saves are stored separately from real player saves, so testing a draft never disturbs the progress of someone playing the published version — including your own.

The builder stays open in its own tab throughout. Change something, press ▶ Playtest again, and a fresh tab opens with the change in it.

A useful habit. Play your adventure once without touching the debug commands, from the first room, as though you had never seen it. It is the only reliable way to notice that the brass key is mentioned nowhere in the prose.

19. Checks

The Adv. tab’s Run checks button reads the whole adventure and reports what looks wrong. Export runs the same checks quietly and tells you the count if anything turns up.

Checks are warnings, not blockers. A half-built world is the normal state of a world, and the builder will never refuse to save or export.

What it looks for:

Appendix E explains each message and what to do about it.


Part III — Sharing

20. Three ways to share (and a cartridge)

All of them live under Share on the Adv. tab.

Download .json

The adventure file itself. This is your backup, your archive, the thing you mail to a collaborator, and the thing you re-import later. Do this often. It is the only copy that does not depend on one browser on one computer continuing to behave.

Download single-file .html

The whole game — engine, story, embedded pictures — assembled into one .html file. Double-click it and it plays. No web server, no internet, no install. This is the format to hand in, to email, to put on a USB stick.

Two caveats. It needs the builder to be running from a web address rather than opened straight from disk, because it reads the app’s own files to assemble itself; if it can’t, it says so. And panoramas, being separate files, don’t travel inside it — a single-file export of a 360° adventure will show its flat pictures and text, but the panoramas will only load if the file sits where those paths still resolve.

Download publish kit

Two files: your adventure, and an updated menu catalogue with your adventure merged into it. Upload both into the adventures/ folder of the app on your site — replacing index.json — and the adventure appears on the menu.

This works from any browser, on any machine, with nothing installed. It is the add-a-room-in-a-spare-moment pipeline, and the reason the builder can be used from a borrowed laptop.

Why isn’t there a Publish button? Because NeoCities’ upload API refuses requests made from web pages — it sends no CORS headers, so the browser blocks the call before it leaves. This was tested and confirmed, not assumed. The publish kit is the closest a browser can legally get. For one-command publishing, use publish.py from your own computer.

Download Game Boy Color ROM

The adventure as a .gbc cartridge image: the whole game, pictures included, for a Game Boy Color emulator or a flash cart. The player walks with the D-pad, opens a command menu with START (LOOK, EXAMINE, TAKE, DROP, OPEN/USE, SEARCH, UP, DOWN, INVENTORY, then your own rule verbs), picks the object from a list, and has an on-screen keyboard under TYPE… for easter eggs and anything else. Saves go to the cartridge battery: a continue autosave every turn and three slots; the title screen offers CONTINUE. Everything the parser does on the web it does on the cartridge, with the same text; openLink prints the address and shows it as a QR code to point a phone at (fill in the site address field so links like /projects/ become full addresses), and save codes don’t exist there.

To export one: run the builder from a web address if the adventure has pictures (opened from disk, the browser will not release a picture file’s pixels), check the site address field, and click Download Game Boy Color ROM. The file <adventure id>.gbc downloads and the status line reports its size, rooms and pictures. Open it in a Game Boy Color emulator (SameBoy, BGB, mGBA, Emulicious) or flash it to a cartridge; the buttons are in Appendix D.

Pictures are converted to 8 x 8 tiles with six four-colour palettes each, a panorama to four views (SELECT turns). A text adventure makes a 64 KB ROM; a photographic picture costs about 3.6 KB, a panorama about 14 KB, and the status line warns past 1 MB. Serve the builder over http for pictures - opened from disk, the browser refuses to hand over the pixels of a panorama file. The engine and the data format are documented in the gb_adventure folder beside the app.

FIG. 20.1 BUILDER Share, on the Adv. tab DOWNLOAD .json the adventure file itself backup · archive · re-import later do this often .html DOWNLOAD SINGLE-FILE .html the whole game in one file disk · email · USB stick nothing to install .json index DOWNLOAD PUBLISH KIT two files — your adventure plus an updated menu catalogue upload both to adventures/ on your site your site /adventures/ No Publish button: NeoCities’ API refuses calls made from web pages. Use the kit, or publish.py from your own computer. THREE WAYS OUT

Figure 20.1 — Three ways out. The .json to keep, the .html to hand over, and the two-file kit that puts it on your site.

21. Publishing with publish.py

For uploading from your own computer in one command. Python 3, no libraries to install.

Get an API key from your NeoCities settings, under Manage Site Settings → API.

python publish.py

That uploads the adventure files. To upload the whole app — the first time, or after updating the program itself:

python publish.py --all
Flag Does
--all Upload the app files (.html, css/, js/) as well as adventures.
--dry-run List exactly what would be sent, and send nothing.
--remote-dir "" Publish at the site root instead of /games/adventure.
--key <key> Supply the API key inline.

The key is taken from the NEOCITIES_API_KEY environment variable, then --key, then an interactive prompt — so you never have to put it in a file.

Image files are not uploaded by this script. It sends adventures/*.json and, with --all, the app’s own code. Panoramas and any pictures you reference by path must go up through the NeoCities dashboard. Embedded pictures are inside the .json and travel with it.

Start with --dry-run the first time. It prints the exact list of local files and their destinations on the site, which is the moment to notice that --remote-dir isn’t what you thought.

22. Housekeeping

Back up by exporting. Browser storage is convenient and not durable. A folder of dated .json files costs nothing and has saved every project that ever kept one.

Watch the file size. Embedded pictures are stored inside the adventure and count against the browser’s storage limit for the whole builder. If the status area ever reports a failed save, export immediately, then reduce the pictures — smaller images, fewer of them, or move to path-referenced files uploaded alongside the adventure.

Ids are permanent in practice. The adventure id keys every player’s saves. Room and item ids can be renamed safely at any time — the builder repairs every reference — but the adventure id is a promise to your players.

Updating a published adventure means uploading one small .json file. The engine never changes when your content does. That is the entire point of the format.


Appendices

Appendix A — Player command reference

Case never matters. Filler words — the, a, an, to, my, some, of, at — are ignored everywhere.

Movement

Type Also accepts
NORTH SOUTH EAST WEST N S E W
UP DOWN U D, UPSTAIRS, DOWNSTAIRS
GO NORTH MOVE, WALK, HEAD, RUN, TRAVEL, ENTER, CLIMB

Looking

Type Does
LOOK / L Describes the room again.
EXAMINE X / X X / INSPECT X Describes one thing.
LOOK AT X Same as examine.
SEARCH X / CHECK X Searches it — the usual home of hidden things.
LOOK UNDER X / LOOK BEHIND X / LOOK INSIDE X Same family as search.
READ X / STUDY X Reads it, or opens its link if it has one.

Handling things

Type Also accepts
TAKE X GET, GRAB, POCKET, STEAL, PICK UP
DROP X LEAVE, DISCARD
INVENTORY I, INV
OPEN X / USE X PLAY, UNLOCK, UNROLL, LAUNCH, START, PRESS, CLICK, PULL, TURN, BOOT, INSERT, PUT
USE X ON Y / UNLOCK Y WITH X Also ONTO, IN, INTO, USING

Everything else

Type Does
WAIT / Z Time passes.
HELP / COMMANDS / HINT The author’s help text.
SAVE [name] Saves. Default slot: quicksave.
LOAD [name] / RESTORE [name] Restores a slot.
SAVES Lists your saves for this adventure.
CODE Prints a portable save code.
RESTORE <code> Restores from a pasted code.
RESTART Starts over.
THEME green\|amber\|mono\|paper Changes the look.

Save, load, theme and the rest are handled before anything else, so an adventure can never accidentally break them.

In playtest only: /flags, /tp <roomId>, /give <itemId>, /reveal <itemId>.

Appendix B — Effect reference

Available in rule THEN and OTHERWISE branches, and in a room’s entry effects.

Effect What happens
say something Prints text. Styles: normal, highlight, quiet.
give an item to the player Straight into the inventory, revealing it if hidden.
take an item from the player Gone for good.
reveal a hidden item Makes it visible. If it was nowhere, it appears in the current room — or in a room you name.
destroy an item Gone for good.
set a flag / clear a flag The world’s memory.
unlock an exit / lock an exit A direction, in the current room or one you name.
create a new exit Opens a brand-new passage where there was none — the secret-door effect.
teleport the player Moves them to another room, running that room’s entry effects.
change a room’s picture Swaps the static image on puzzle state. Updates instantly if the player is there. Can also be set to no picture.
change a room’s 360° panorama The same, for panorama rooms.
open a web page Opens a URL in a new tab, announcing it first.
end the game — player wins Prints your victory text and ends the story.
end the game — player loses Prints your ending text and ends the story.

Effects run in the order listed. Once the game ends, later effects in the same list are skipped.

Appendix C — Condition reference

Condition True when
player has item It is in the inventory right now.
flag is set That flag has been set and not cleared.
player is in room They are in it at this moment.
player has visited They have been in it at least once.
item is revealed It is no longer hidden — whether or not they have it.
item is gone It has been destroyed or taken away.

All conditions in a rule must be true. Any row can be inverted with not.

Adventure files may also contain any and all groupings written by hand; the builder preserves them untouched and shows them as (complex condition).

Appendix D — Controls at a glance

Map

Action Result
Click empty square Create a room
Click room Select it
Drag room Move it
Click gap between neighbours Cycle the connection
▲ / ▼ in top bar Change floor

Panorama viewer (player and hotspot editor)

Action Result
Drag Look around
Scroll wheel Zoom in and out
Click a dot Types that command into the game
Click a diamond Travel through that exit

Player input

Key Result
Enter Run the command
↑ / ↓ Previous / next command in your history

Game Boy Color cartridge

Button Result
D-pad Walk north, south, east, west
START The command menu: built-in verbs, the adventure’s own verbs, TYPE…, SAVE/LOAD, THEME, HELP
A EXAMINE — straight to the list of things here and carried
B INVENTORY
SELECT Turn a 360° room by 90 degrees
A on -- more -- Next page of a long description
In a list A picks, B goes back
On the keyboard D-pad and A spell, B deletes, START runs the line

Appendix E — What the checks mean

Message What to do
“X” can’t be reached Nothing leads there. Add an exit, a teleport effect, or a create-a-new-exit rule — or delete the room.
has a ⟨dir⟩ exit to a missing room The destination was deleted. Repoint or remove the exit in the Room tab.
locked with no key, and no rule ever unlocks it The door can never open. Give the exit a key item, or write a rule with an unlock-an-exit effect.
needs a key item that doesn’t exist The key was deleted or renamed. Pick a key again.
starts with a missing item The item was deleted. Remove it from the room’s item list.
A rule mentions an item / a room that doesn’t exist Something was deleted after the rule was written. Open the rule and repoint it.
is never placed in a room, given, or revealed The player can’t encounter it. Put it in a room, or have a rule give or reveal it.
is hidden but no rule ever reveals or gives it Same problem, one step later. Add a reveal or give effect.
The flag “x” is checked but nothing ever sets it Usually a typo in one of the two places. Use the autocomplete.
A hotspot points at a missing item Rebind or delete the hotspot.
A hotspot has no item and no command Clicking it does nothing. Give it one or the other.
has hotspots but no panorama The panorama path was cleared. Restore it, or delete the hotspots.
No winning ending yet Add an end the game — player wins effect somewhere. Harmless for a sandbox.

Appendix F — Troubleshooting

The menu says it couldn’t read the adventure list. Normal when the page is opened straight from disk — browsers block that kind of file reading. Use Open an adventure file instead, or run a small web server: python -m http.server 8321, then visit http://localhost:8321/.

The single-file HTML export fails. It reads the app’s own files to assemble itself, which needs the builder served over http:// rather than opened from disk. Same fix as above.

My panorama doesn’t appear. Four things to check, in order: the adventure’s display mode is illustrated; the path in the room panel matches where the file actually sits on the site; the image is 2:1 equirectangular; and the file has actually been uploaded — publish.py does not upload images.

The panorama shows as a flat picture. The browser can’t do WebGL, or the page was opened from disk, which blocks image textures. The game deliberately falls back rather than failing.

A rule doesn’t fire. Work down this list: is the target item present in the room or carried? Does the verb match what you typed, including any phrase? Is an earlier rule on the same verb catching it first — remember rules run top down? Do the conditions actually hold — check with /flags in playtest? Does an earlier rule have an OTHERWISE branch, which stops anything later from getting a turn?

A puzzle can be skipped by typing the room’s name. GO <room name> moves the player to any room whose name contains what they typed, without consulting exits or locks. Worth knowing if a locked door is guarding something important: either give the room a name players won’t type, or intercept it with a rule — rules are checked before that behaviour.

Nothing saves and the status area says SAVE FAILED. The browser’s storage is full, almost always from embedded pictures. Export at once so nothing is lost, then reduce the images.

A player’s saves vanished after an update. The adventure id changed. Saves are keyed to it. Change it back, or tell them to use RESTORE with a code.

The transcript doesn’t list the exits or the items. By design — put them in the room description. See Chapter 12.

The Game Boy export says the engine is missing. js/gbc-engine.js is not beside the app. It is generated by gb_adventure/build.ps1; copy it in, or rebuild.

The Game Boy export has no pictures, or fails on a panorama. The builder was opened from disk. Browsers will not release a picture file’s pixels to a page opened that way; serve the app over http:// as in the first entry.

The QR code on the cartridge reads /projects/ instead of a web address. The site address field was empty when the ROM was exported. Fill it in (the site the adventure lives on) and export again; it is remembered afterwards.

The ROM is too big for the cartridge. Photographs and panoramas are the cost — about 3.6 KB a picture, 14 KB a panorama. Drop the pictures that matter least, or redraw them in a few flat colours, which packs far smaller and looks better on the screen.

Appendix G — Where everything is stored

All in this browser, for this site, on this computer:

What Where
Builder drafts aw:draft:<adventure-id>
Which draft to reopen aw:lastDraft
The staged playtest copy aw:playtest
Player saves aw:save:<adventure-id>:<slot>
Playtest saves aw:save:draft:<adventure-id>:<slot>

Clearing your browser’s site data removes all of it. Exported .json files and save codes do not live here and are unaffected.

Appendix H — Glossary

Adventure — one .json file containing an entire game.

Alias — one of the words the parser accepts for an item.

Draft — a work-in-progress adventure held in this browser.

Effect — something that happens: text, an item, a flag, an ending.

Egg — an exact phrase with a canned reply, answered before anything else.

Flag — a named yes/no memory of something that has happened.

Hotspot — a clickable marker on a panorama that types a command.

Id — the internal name of a room, item, or adventure. Players never see it.

Illustrated mode — the display setting that turns on the visuals pane.

Panorama — a 2:1 equirectangular image you can look around inside.

Publish kit — the two files that put an adventure on your site.

Rule — one puzzle: when / if / then / otherwise.

Save code — an entire saved game as copyable text.

Travel hotspot — a hotspot that walks the player through an exit.


Further reading

FIG. H.1 CAVE MOUTH ★ GALLERY DRY LEDGE THE POOL SUNKEN STAIR ALCOVE THE VAULT 🔒 one-way token here — opens the slab lantern must be lit N S E W UP DOWN six directions, and no more A FINISHED WORLD

Figure H.1 — Back cover. The map from the frontispiece, finished — and a compass rose with only six points, which is all this parser has ever needed.