Interactive fiction is a cuisine. Tweego is a kitchen built for it — small, sharp, and command-line. What follows is a clickable primer on how the kitchen works, what dishes it can produce, and which ingredients each one wants.
If you have read your way through hypertext fiction for years and now want to make some, you are in the best possible position. The reading taught you the flavours; the toolkit only adds the seams. This primer will not exhaustively teach you to code — it will give you a felt sense of what a Tweego project tastes like to assemble, and a map of which kinds of stories want which kinds of pantries.
Three motions repeat through every Tweego session, in the same order, forever. You mise — gather your passages and lay them out in plain text files. You marry them with bracketed links so the reader can move between them. You fire — run the tweego command, and your folder of source files compiles into a single self-contained HTML artifact you can open, taste, and adjust.
:: PassageName on a line of its own, then your prose. Lay them out in .tw files however you like — one per file, or many.[[take the key]] jumps to a passage of that name. The graph builds itself as you type — every link knits two passages together.tweego -o story.html src/ — turns your source folder into a finished HTML file. No build pipeline. No deploy. Open it. Taste it. Adjust.That is the entire authoring surface. Everything else — variables, conditionals, save systems, the whistle of an achievement chime — is bolted onto this loop, never replacing it. A Tweego project is, at root, a sheaf of plain-text recipe cards that compile into a single dish.
Below is a working hypertext story rendered in plain HTML — six passages, two links per turn, and one small piece of state. It is a single bite, fully cooked. Click through it. The right-hand panel is the kitchen line: it shows what's being tracked as you move.
Two things to taste. First, the door cares whether you took the key — that is the variable in the right-hand panel, set in one passage and read in another. It is the same primitive that powers every save file in every CRPG you have ever played; here it weighs almost nothing. Second, the graph of passages looks like a graph because it is one. That visual map is also what your editor's directory tree and your .tw files describe, in text — drag passages around in your head; type brackets to draw arrows.
Tweego is the kitchen — the compiler, the file structure, the rhythm. The story format is the pantry: the macros, the in-passage syntax, the runtime that turns your source into a playable page. Three are dominant, each with a personality. Click between them; the same passage from The Lighthouse, in each pantry's idiom.
A reasonable rule of thumb: if you're cooking prose-forward, mood-driven work, start in Harlowe. If you suspect you'll want inventories, save slots, or stat sheets, jump straight to SugarCube. Try Chapbook if the syntax of the other two feels noisy on the tongue. Switching pantries later means rewriting your macro-level logic — the prose, the structure, and the link graph all transfer cleanly, but conditionals and variables will need new clothes.
Most published hypertext fiction falls into one of a handful of culinary shapes. Each shape implies a different mise — a different bill of mechanical materials. Click a dish on the left; the recipe card on the right shows what it takes to build, how much it yields, and which pantry makes it easiest.
These shapes are not exclusive — most real dishes are blends. A mystery often has stat-driven negotiation; a time loop is usually also a branching tale, just folded over itself. But identifying the dominant shape early gives you a target for your first prototype: cook the narrowest version of your dish that's still recognisable, then build outward. The petit four version of your novel is almost always your sharpest test of the idea.
A handful of things every first-time Tweego author runs into. Each is solved more easily once it has a name.
It is shockingly easy to write a beautiful scene, link to it, and forget to give the player a way out. Run tweego --test with verbose output — orphans are usually the loudest thing in the kitchen.
Three meaningful choices per scene across ten scenes is fifty-nine thousand possible meals. Most great branching dishes use a small number of permanent forks and many transient ones that re-converge into a shared corridor.
If a value is changing in the background and the player can't see or feel its presence, it might as well not exist. Either show the consequence in the prose, or cut the bookkeeping. No silent seasoning.
Tweego is fast — compiles take milliseconds. There is no excuse for going more than a few passages without firing the build and clicking through. The errors you catch at the stove are the errors you don't serve to a guest.
Three passages. A single variable. One conditional. Whatever your game is, the version of it that fits in three passages exists, and is the only honest first draft. Cook that. Then cook the next thing it asks for.