Variables

Variables are your world's game state. Numbers, text, flags, complex objects, anything that persists across turns. The AI reads them, updates them through directives, and your automation can react to changes.

In the editor, open the Variables section. Each variable has a name, type, default value, and AI instructions.

The horror world from the entries page uses 5 variables: health (number, 0-5), energy (number, 0-8), day count (number, 1-14), game phase (string, "Night" or "Day"), and armed status (boolean). That's enough to run a full 14-night survival game.

Each turn, the AI reads current values, writes directives like [health: -1] in its response, and the engine extracts them and updates the state. The player only sees the narrative.

Variable Types

Number

Tracks quantities: health, gold, affinity, day count, hunger.

[health: -15]          → subtract 15
[gold: +50]            → add 50
[day-count: set 3]     → set to exactly 3
[damage: *2]           → multiply by 2

You can set min/max bounds. The engine clamps automatically.

String

Tracks text state: location, mood, current quest, time of day.

[location: set "dark forest"]
[mood: set "suspicious"]
[time-period: set "night"]

Boolean

Tracks true/false flags: has a key, met the NPC, triggered an event.

[has-key: toggle]      → flip true ↔ false
[met-elder: set true]

JSON

Tracks complex structures: inventory arrays, NPC relationship objects, quest logs, map data.

[inventory: push {"name": "Iron Sword", "damage": 10}]
[inventory: delete 0]
[npcs.aria.affinity: +5]
[npcs.aria.mood: set "happy"]
[quest-log: merge {"main": "completed"}]

JSON variables support dot-path updates — you can modify nested fields without rewriting the whole object.

AI Instructions — The Most Important Part

AI instructions are plain English instructions that teach the AI when and how to change a variable. Without them, the AI won't reliably use your variables.

(The editor labels this field "Behavior Rules." We call them AI instructions here to avoid confusion with the automation system, which the editor calls "Behaviors.")

Bad AI instructions

Track the player's health.

The AI doesn't know what "track" means. When should it change? By how much? What does zero mean?

Good AI instructions

0 = death — describe a death scene and end the game. 1-20 = critical (bleeding, difficulty breathing). 20-50 = wounded (pain affects actions). 50-80 = bruised (minor discomfort). 80-100 = healthy.

Decrease on physical damage proportional to severity. A punch: -5 to -10. A sword slash: -15 to -25. A fall from height: -20 to -40. Increase slowly when resting (+5 per rest scene) or healing (+10 to +30). Never change by more than 30 in a single turn.

This is specific. The AI knows the scale, the thresholds, the triggers, and the limits.

Patterns That Work

Numeric ranges — define what each range means narratively:

0 = game over. 1-25 = desperate. 26-50 = struggling. 51-75 = capable. 76-100 = confident.

Triggers — when should this change:

Increases when the player helps villagers, gives gifts, or defends them. Decreases on theft, threats, or broken promises.

Limits — prevent wild swings:

Never change by more than 10 in one turn. Minimum 0, maximum 100.

Relationships between variables — how they interact:

When hunger reaches 0, start decreasing health by 5 each turn.

TIP

Two to four sentences is usually enough. If your AI instructions are longer than a short paragraph, simplify. The AI is smart — give it the concept and the boundaries, not a 500-word essay.

Tips

• Use kebab-case IDs: player-health, not playerHealth or Player Health
• JSON for anything complex: If you need more than one value (inventory items with properties, NPC data with multiple fields), use JSON
• Don't over-track: You don't need a variable for everything. If the AI can handle something narratively without tracking it, skip the variable
• Test your AI instructions: Play your world and check if the AI updates variables when you expect. If not, your instructions need to be more specific