Play, create, and edit text adventures. No installs, no accounts, no mercy for grues.
Covers the release with 360° panorama rooms · August 2026
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.
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.
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.
Figure 1.1 — The four doors. Menu, file, link, or a single
.htmlfile — 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.
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.
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.
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.
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.
> 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.
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.
Figure 6.1 — Inside a panorama. A dot examines; a diamond travels. Both simply type a command you could have typed yourself.
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.
Figure 7.1 — The four themes. The same three lines, four ways. Green and amber carry the scanlines; mono and paper are clean.
The fastest useful path through the builder. Open build.html.
search;
aim it at your item; add a say something effect. That
is a puzzle.Everything after this chapter is detail.
Figure 8.1 — The seven steps. Name it, make rooms, connect them, add a thing, make a puzzle, play it, keep it.
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. |
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.
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
.jsonfile is the real adventure; the draft is a convenience.
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. |
Figure 11.1 — The exit cycle. Each click on the gap advances one state. A padlock on the line means one side is locked.
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: northreads 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.
adventures/panos/cave.jpg.
Panoramas are referenced, never embedded; see Chapter 17.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.
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.
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.
Figure 13.1 — Anatomy of an item. One object, five fields. The aliases line is everything a player might call it.
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.
| 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.
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.
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).
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.
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.
Figure 14.2 — The ladder. The command falls until a rule’s conditions hold. The built-in verbs are the floor everything lands on.
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.
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.
A panorama turns a room into a place you can stand in and look around.
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.
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:
open door,
search pool, xyzzy.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.
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.
▶ 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.
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.
All of them live under Share on the Adv. tab.
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.
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.
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.pyfrom your own computer.
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.
Figure 20.1 — Three ways out. The
.jsonto keep, the.htmlto hand over, and the two-file kit that puts it on your site.
publish.pyFor 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.pyThat 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.
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.
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>.
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.
| 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).
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 |
| 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. |
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.
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.
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.
docs/FORMAT.md — the adventure file format, for
hand-editing the .json.SPEC.md — the design and why it is shaped this
way.README.md — running the app and what each file
does.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.