How do variables work in Forge?

Q: How do variables work in Forge?

Declare a variable once in the Variables tab of the Forge dock - a name plus a type (number, text, or yes/no) - and every `set` and `when` event lets you pick it from a list instead of typing it. Each row also shows the variable's live value at the current moment of the story, so you can test values without playing from the start.

Short answer: Declare a variable once in the Variables tab of the Forge dock - give it a name and a type (number, text, or yes/no) plus a starting value - and from then on every set and when event lets you pick it from a list instead of typing it. Each row also shows the variable's live value at the moment the Stage is currently showing, editable on the spot for testing. Renaming a variable rewrites every place it's used across the whole project, and variables you used in scenes without declaring them show up in a "Detected in scenes" list with a one-click Save.

Declaring a variable

Open the Variables tab in the Forge dock and click New variable. A variable is three things:

Name - how you'll refer to it everywhere (like coins or met_emma).
Type - number, text, or yes/no. The type is fixed once the variable is created, and every editor respects it: a yes/no variable edits as a toggle, a number as a number field, text as plain text. You can't accidentally put words into a number.
Default value - the value the variable starts with when a reader begins the story.

The list is yours to organize: search it, filter by type, drag rows to reorder, and duplicate a variable to make a similar one.

Using variables in set and when events

Once declared, you never type a variable name again. Choosing Set variable from the insert palette asks which variable first and writes nothing until you pick one (with no variables yet, it offers to create one); the new event starts out harmless - a number goes up by one, a yes/no turns on, text starts empty - instead of resetting the value. A set event is one line that reads like a sentence - variable, verb, value - and a choice option's When picked changes use the same line. The value matches the type: a yes/no is a switch, text is a quoted box, and a number offers set to (a value, or simple math like love + 1, shown as a formula), add or subtract (written as love + 1 / love - 2 in a set, and as love += 1 / love -= 2 on an option). Anything that isn't a number stays red and is not saved until you fix it. Change a variable on an option asks which variable first and adds nothing if you back out. A when event (and conditional choice options) offers the same picker plus a comparison builder, so a condition like coins >= 50 is assembled from controls, not typed from memory.

If you're mid-edit and realize you need a variable that doesn't exist yet, the picker's "New variable" option takes you straight to the Variables tab in create mode.

Live values at the playhead

The prominent value on each row is not the default - it's the variable's current value at the moment the Stage is showing. Scrub to a later step and the values update to what the story has set by then.

You can edit a live value directly to test a branch ("what does this scene look like when affection is 10?"). A row whose live value differs from its default is tinted and grows a revert control, and a Reset button in the toolbar snaps every overridden variable back to its default at once. Live edits are for testing only - they never change your story or your defaults.

Renaming, reordering, and deleting

Renaming is safe: when you rename a variable, Forge rewrites every use across the entire project - conditions, set values, choice options, and text that displays the variable. Nothing is left pointing at the old name.

Deleting removes the declaration, but it can't orphan your story: if scenes still use the variable, it simply reappears in the detected list below.

Detected in scenes

You don't have to declare a variable before using it. If a scene sets a variable that was never declared, it still works - and the Variables tab lists it under Detected in scenes with a one-click Save that promotes it to a declared variable. This is common right after a Ren'Py import, where the story arrives already full of variables.

Showing a value in story text

Story text can display a variable's value inline: write the variable's name in square brackets, and the reader sees the current value. For example:

say "Merchant": "That'll be [coins] gold, friend."

This works in dialogue, narration, choice labels, and custom speaker names.