Flags, variables and events: which to use

A flag is a state: the door is open. An event is a moment: the bell just rang. quest'n'click has no separate "variable": a flag holds a value (a boolean, a number or a string), so a counter or a choice is a flag too. This page says what each one is, what the engine keeps of it, and how to choose.

What each one is

A flag is a named value in the save (GameState.flags), set by commands and read by conditions:

A flag stays until something changes it; a save keeps it, a load restores it. Flags are named however you like; the validator warns about one read and never set, or set and never read. A minigame that says how it ended writes the reserved flag minigame.<id> (4.1.16). A text can show a flag's value through a text switch, {form?gull=e|*=} (translations).

An event is a name fired by { emit: 'bell_rang' }. Right there, in order, it moves on every script paused on { waitEvent: 'bell_rang' }, then runs the listeners of the current room, then the game's (scripts and events):

// market.ts, in a rule:  { gain: 'key' }, { emit: 'key_found' }
// game.ts:
events: [
  { id: 'grandpa.goes-home', on: 'key_found', once: true, do: [{ moveActor: ['grandpa', 'house'] }, { toast: 'Grandpa went home.' }] },
],

if and once work as on a rule. An event is not remembered: once its listeners have run, nothing of it is left, except what they changed (and a once listener's mark that it fired). A listener of a room the player is not in does not hear it.

Other parts of the state answer "has it happened?" without a flag: a prop's state ({ prop: ['lamp', 'on'] }), the inventory ({ has }), a room visited ({ visited }), where a moving character is ({ actorIn }), a topic heard ({ seen }), the count of a once, nth, cycle or random block.

How to choose

The last row is the usual pattern: an event is not remembered, so to react the next time the player enters a room, set a flag in the listener and test it in onEnter.

events: [{ id: 'bell.heard', on: 'bell_rang', do: [{ set: 'bell_rang_once' }] }],
// hall.ts
onEnter: [{ if: 'bell_rang_once', then: [{ say: ['butler', 'You rang?'] }] }],

Alternatives set aside

• Typed variables beside flags. A second store would be one more thing to save, migrate, show in the DEV panel and explain; a flag that holds a value covers counters and choices.
• Remembered events (a log of moments that conditions could query). Conditions would then depend on history, and the solver's states would grow with it. A flag set by a listener says exactly what is worth remembering.
• Code in listeners. Listeners are data, like rules, so the validator, the solver and the save understand them (principles).

Trade-offs

• Every flag the solver can see is part of the state it explores: a flag nobody needs to read makes proofs slower. npm run lint and validate point at flags never read.
• { flag, lt } is true for an absent flag: test gte first, or set the flag at the start (start.flags in game.ts), when absent must mean "zero tries".
• Renaming a flag breaks old saves unless a migration renames it too (migrations: [{ from, renameFlag }], state and saves).

Decisions and ADRs

• ADR 0002, content is data: listeners and flags are data the tools read.
• ADR 0003, the solver runs the real engine: every flag is part of the state it explores.
• References: commands, logic, conditions, scripts and events, the generated DSL reference.