World State Flags

World state flags are the game's memory of what has happened: the bridge is down, the smith has been met, three keys are found. Doors, conversations and cutscenes ask this one list instead of keeping private notes. Names come from a fixed list, so a typing mistake is caught and never becomes a second, silent flag.

Also called: Story flags, Game flags, World variables, Quest flags.

A round-eared otter in a green coat pulls a brass lever as a drawbridge swings down, while on a clothesline above, one more paper lantern flares to life among the dark ones. — Quillmoth Crossing, an invented paper-craft adventure. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "World State Flags" to my game.

What it should do: One shared memory lets any part of the game react to what the player did, without the parts knowing about each other, so choices and progress can change the world in many places at once.

Use these starting values:
- historyLimit: 20 changes

Watch out for these common mistakes:
- A typing mistake becomes a second flag: Tell your AI: keep one list of all flag names, refuse any name that is not on it, and check every door and conversation against that list when the game loads.
- A condition with an empty list: Tell your AI: an empty list asks for nothing and always passes.
- A counter goes below zero or past its top: Tell your AI: give every counter a top, keep it between zero and the top, and only accept whole numbers.
- An old save has names the game no longer has: Tell your AI: when loading a save, drop every name the game no longer lists and cut each counter to its current top.
- Setting a flag twice looks like news: Tell your AI: report whether a flag really changed, and only react to real changes.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

One shared memory lets any part of the game react to what the player did, without the parts knowing about each other, so choices and progress can change the world in many places at once.

Good starting values

Value	Start with	What it changes
historyLimit	20 changes	How many recent changes are remembered. More helps when hunting a strange bug, but every saved game carries them.

What usually goes wrong

A typing mistake becomes a second flag

The story sets "bridge-dwon" and the door waits for "bridge-down". Nothing complains, the door never opens, and nobody sees why.

Fix: Tell your AI: keep one list of all flag names, refuse any name that is not on it, and check every door and conversation against that list when the game loads.

A condition with an empty list

A line of talk says "any of these flags" with no flags in the list. A careless check says no, and the line can never be said.

Fix: Tell your AI: an empty list asks for nothing and always passes.

A counter goes below zero or past its top

The player hands in four keys but only three were found, and the counter shows minus one. Or a bonus adds ten moths to a jar that holds ten, and a later check for exactly ten fails.

Fix: Tell your AI: give every counter a top, keep it between zero and the top, and only accept whole numbers.

An old save has names the game no longer has

An update renames or removes a flag. Old saves still carry it, and the world is a little wrong for the player who loads one.

Fix: Tell your AI: when loading a save, drop every name the game no longer lists and cut each counter to its current top.

Setting a flag twice looks like news

Every time the player walks past the smith, the "met the smith" flag is set again and the game shows a new-entry sign or plays the jingle again.

Fix: Tell your AI: report whether a flag really changed, and only react to real changes.

How to check it works

No flag is on. the story sets "bridge-down": that flag is on, every other flag is still off, and the action reports a change.
"bridge-down" is already on. the story sets it again: the action reports no change and the history still holds one entry.
"lamp-lit" is on. the story clears it: it is off, and clearing it again reports no change.
The game knows "bridge-down" but not "bridge-dwon". the story sets the misspelled name or adds to a misspelled counter: the action is refused as an unknown name, and nothing at all changes, not even the history.
A counter for keys has a top of 3. you add 5, then take away 10: it stops at 3, then at 0, and taking away from 0 reports no change.
A fresh world. you ask whether an empty condition holds, or one with only empty lists: it holds.
Only "bridge-down" is on. you check conditions that need all, any or none of some flags: "all" needs every flag, "any" needs at least one, and "none" fails as soon as one of its flags is on.
Two of three keys are found. a door needs three, then you find the third: the door check fails with two and passes with three, and a counter never touched counts as zero.
The history holds at most 3 changes. five changes happen: only the last three are kept, oldest first.
A condition names "bridge-dwon" and a counter "keys-fnd", neither of which exists. you check it against the world and against the list of names: the condition fails, and the check of names lists both mistakes.
A save holds a flag and a counter the game has since dropped, a repeated flag, and a counter above its current top. the save is loaded: the dropped names are gone, the repeat is gone, and the counter is cut to its top.
A counter for keys. you add 1.5, or something that is not a number: the action is refused as a bad amount and the counter stays put.

Works well with

Dialogue System: The conversation reads and writes the same list, so a promise made in one talk can change another talk hours later. Set a flag when the player picks an answer, then let later answers ask for it.
Key Items: A door can need both the key and a flag such as "storm-over", so story and items open it together. Ask the flags when the player uses a key item on a door.
Achievements: Many achievements are just a condition on the flag list, so they need no code of their own. Change flags first, then let achievements read the new world.

Common questions

what are story flags in a game

Named yes or no notes the game keeps about what has happened, such as the bridge being down. Any door, conversation or cutscene can look at them, so one deed can change the world in many places.

how do i stop typos in flag names

Keep one list of every allowed name and refuse any other name. Then check every door and conversation against that list when the game loads, so a mistyped name shows up before a player meets it.

what do i tell my ai to add story flags

Paste this: Add world state flags. Keep one list of allowed flag and counter names, refuse unknown names, keep counters between zero and a top value, report whether a change really happened, and drop unknown names when loading an old save.

should a flag be a number or a yes or no

Use a yes or no for things that either happened or did not. Use a counter, with a top value, when you need to count, such as keys found. A counter with a top is easier to check than a pile of separate flags.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

13 tests pass on the reference code.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it