Files & Passages

How an Ana project is laid out and the kinds of passages you write.

File Structure

Ana passage files use the .ana extension. Files can go anywhere under the passages/ directory; the engine finds them recursively. Organize them however makes sense for your project:

passages/
  _init.ana              ← GameInit (required)
  locations/
    bar.ana
    mainstreet.ana
  characters/
    bartender.ana
    sheriff.ana
  systems/
    quest_tracker.ana

A file can contain any number of passages. Each passage starts with :: PassageName:

:: BarScene [location]

(img: bar_evening.jpg)
You push open the heavy door.

@zone(options)
(link: "Approach the bar")[(update: Bar_BartenderGreet)]

:: Bar_BartenderGreet

@zone(text)
The bartender watches you without expression.

Comments

Two comment forms can appear anywhere, inside passages or at the top of a file before the first :::

// A line comment runs to the end of the line.

/* A block comment can span
   multiple lines — handy for commenting
   out a whole stretch of passage content. */
(set: $x to 1)
/* (set: $x to 2) */   // this line is commented out
(set: $y to 3)

Both forms are line-level (like most of Ana's syntax): a comment starts a line or sits at the end of one. A /* ... */ placed in the middle of a prose line is not treated as a comment, so write block comments on their own line(s). To strike through prose visually, use ~~text~~, not a comment.

Passage Types

Ana doesn't have named passage "types," but passages fall into clear patterns based on how they're reached and what they do.

Location passages

Full scenes. Usually tagged [location:id]. Called with (goto:). Rebuild the entire UI.

The [location:id] tag sets $world.location to the id automatically on every visit, with no manual (set:) needed. (A bare [location] tag falls back to setting $world.location to the passage name.) Use $world.location anywhere you need "where is the player right now," e.g. to filter an NPC sidebar with (filter: $npc.location is $world.location).

:: MainStreet [location:main_street]

(img: mainstreet_day.jpg)

The main street stretches out before you.

@zone(options)
(link: "Head to the bar")[(goto: BarScene)]

Update passages

Continuation content within a scene. Called with (update:). Replace the text and options zones only.

:: Bar_BartenderGreet

@zone(text)
The bartender drifts over, unhurried.

@zone(options)
(link: "Order a drink")[(action: Bar_OrderBeer)]

Action passages

Side-effects only. Called with (action:). There's no navigation: it executes and updates only the zones it writes to.

:: Bar_OrderBeer

(add: $inv, "beer", 1)
(pay: 5)
(notify: "You ordered a beer. -5 gold.")

@zone(text)
He slides a glass down the bar without spilling a drop.

System passages

Special runtime roles, marked with @system(...):

:: GameInit @system(init)        ← runs once, new game only
:: GameInitSave @system(init_save)  ← runs after every load