Flags & game state#

A flag is your game's memory. Did the player already unlock the gate? Have they talked to the janitor? How many coins are in their pocket? Every "the game remembers that…" is a flag — a named switch (or a stored value) that your rules set, clear and check. This guide explains the one thing about flags that trips people up at first: where a flag lives.

One shared memory#

Flags aren't scoped to a room, a character or a scene. There is one flag store for the whole game, and every part of your project reads and writes the same one — a hotspot reaction in the kitchen, a puzzle rule in the attic, a line of dialogue, a cutscene step. Set a flag anywhere and it's visible everywhere.

There's no "declare a flag" step, either. A flag comes into being the first time anything sets it, and a name you've never set simply reads as off — false for a switch, 0 for a counter, empty for a stored value. Checking a flag before anything touches it is safe; it just answers "no".

Setting, clearing and checking#

The everyday flag is an on/off switch:

• SETFLAG:gate_unlocked turns it on (remembers something happened).
• CLEARFLAG:gate_unlocked turns it off (forgets it).
• TOGGLEFLAG:gate_unlocked flips it to the opposite.
• In a rule's conditions, the flag check asks "is this switch on?" — that's how one part of the game reacts to what another part remembered.

More than on/off: values & counters#

A flag can also hold a value — a dialled number, a password, a running count — not just a yes/no. SETVAL stores one, APPENDVAL builds one up a piece at a time (each keypad button adds its digit, and an optional cap keeps a four-digit lock at four digits), ADDVAL adds to a counter (use a negative to count down), and you branch on the result with the value equals and compare conditions. That's how you build a combination lock, a coin purse, or a "you've tried this three times" beat. The Effect tokens reference covers the full family.

Name them like folders#

Because the name is the identity, a little naming discipline is the whole organizational system. There are no folders under the hood — but you can fake them by prefixing:

kitchen.window_open
kitchen.tap_running
sewer.valve_turned
act2.met_the_mayor

The engine still sees each of these as one plain name; the dots are purely for you. Group by room, by chapter, by puzzle — whatever keeps related flags together and stops two unrelated switches from accidentally sharing a name. Pick a convention early and your flag list stays readable at flag #200 the same as it did at flag #5.

How long a flag lives#

• Across rooms: flags never reset when the player walks between rooms. That's the point — it's how the attic remembers what happened in the basement.
• Across save/load: the whole flag store is written into the save and restored on load, so a playthrough's memory survives quitting and coming back.
• Across chapters: starting a new chapter is a deliberate clean slate — its entry resets the flag store to empty (only the reserved party bookkeeping carries over). So flags are the memory of the current chapter and playthrough; they don't leak into the next chapter. If you need something to persist past a chapter break, that's a structure-level decision, not a flag.

Flags are durable because they were chosen to be. A handful of runtime overlays deliberately are not: which clip a hotspot was swapped onto with STARTANIM, and the position, spin, scale and opacity a hotspot picked up from MOVEHOTSPOT / SETHOTSPOTMOTION. Those are wiped when the player leaves the room and are never written to a save, so the room file always stays the truth about how a prop starts — a pulse or an endless spin included: the loop itself is transient. If a prop needs to stay moved, grown or pulsing, the durable half is a flag: set one, and re-fire the token from the room's entry rules when the flag is present. (SETHOTSPOTFX is the exception that proves the rule — a glow that encodes puzzle state, so it is saved. HIDEPLAYER is durable for the same reason: a player hidden for a puzzle has to still be hidden after a reload, or the save quietly puts a character back into a scene you took them out of. Starting a new game always brings them back.)

Two things the engine remembers for you. You never need a flag for either: whether a room's lamp is lit (TOGGLELIGHT), and what music each character is playing. The lamp is remembered per room; the music is remembered per character — switch it off while playing one character and it stays off for them across rooms, cutscenes and saves, while another character's theme still starts when you switch to them.

What it remembers is not just on/off but which track. STOPMUSIC means silence; any MUSIC: becomes that character's music from then on, so a portable music player with five songs keeps playing the one the player picked instead of snapping back to the character's default theme at the next door — crossfade and loop points included. That is also why you never have to tell the engine how your on/off button is wired: it reads the tokens, not your flags.

A room that authors its own music is unaffected, and still wins: what the player silenced is that character's radio, not the room.

Same name, same flag — everywhere. One store, addressed by name, is what makes cross-room logic effortless: set gate_unlocked at the gate, check it from any room. The flip side is that two unrelated switches with the same name are secretly the same switch. Namespaced names (kitchen.tap_running) are the cure — and the only one you need.

Where to go next#

• Reactions & puzzle rules — where flags get set and checked, and how the engine decides which rule wins.
• Timers & watchers — flags and timers are the two things a watcher listens to; this is the delayed-reaction pattern built on both.
• Effect tokens — the reference for SETFLAG, TOGGLEFLAG, SETVAL, ADDVAL, RANDVAL and the rest of the state-changing verbs.