Appearance
Authoring Guide
A conceptual introduction to building games with Ana: how the systems fit together, rather than what each macro does in isolation. For exact syntax, see the Macro Reference; for a working game in 15 minutes, start with the Quick Start.
The three building blocks
Everything you write in a passage is one of three things, distinguished by its punctuation:
| Construct | Looks like | What it is |
|---|---|---|
$variable / _temp | $player.gold, _roll | State you read and write. $ persists and is saved; _ is scratch for one passage. |
@directive | @zone(options), @on(dayAdvance), @hook(bar_extras) | A structural instruction to the engine: where content goes, when a passage fires, where mods inject. Directives are part of the passage structure, not values you compute with. |
(macro:) | (if:), (add:), (goto:), (link:) | An action or value. Statement macros do something; expression macros return a value; block macros take a [...] body. |
This is why zones are written @zone(text) and not (zone: "text"): choosing a zone is a directive about structure, while printing or branching is a macro. Keep the three straight and the syntax stops feeling arbitrary.
Macro naming convention: Multi-word macro names use hyphens:
(time-advance:),(modal-open:),(item-define:). Dots are reserved for variable paths only:$world.timeOfDay,$npc.bartender.location. Never put a dot in a macro name.
Quoting convention: String ids you invent are quoted: item ids, container ids, NPC ids, quest ids, status ids, theme ids, as in
(add: $inv, "beer")and(quest-start: "find_thief"). Engine keywords and booleans are bare:stackable,unique,weapon,cycle,enabled,true,off, as in(item-define: "torch", stackable, ...). Keyword arguments must stay bare, since some macros recognize them by being unquoted symbols, so quoting one changes its meaning. Passage names are written quoted in these docs ((goto: "BarScene")) because a passage name may contain spaces, though a bare single-word name also works. The engine evaluates a bare symbol and a quoted string to the same value, so outside of keyword arguments this is a readability convention rather than a hard rule.
Chapters
Foundations
- Files & Passages: project layout and the kinds of passages you write.
- State & Variables: declaring variables and the namespace/story-flag model.
- Zones & Layout: routing content to screen regions and defining those regions.
- Navigation: the three render tiers (goto, update, action) and when to use each.
Structure & Reactivity
- Hooks & Events: injecting/wrapping passages, event handlers, and tag-driven events.
- Time & Scheduling: game time and reactivity, scheduled events, calendars and clocks.
Game Systems
- RPG Systems: dice and skill checks, quests, NPC state and economy, and status effects.
Presentation & Text
- Theming & Modals: visual customization with themes, and modal overlay screens.
- Prose & Text: prose styling, interpolation/sanitization rules, and text transitions.
- Math, Loops & Expressions: arithmetic, comparisons, loop control, and expression logic.
Operations
- Boot, Saves & Mods: the boot/load sequence, the save model, and how mods extend a game.
- Debugging & Mistakes: the dev debugger, and what the engine does when you make a mistake.