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
coinsormet_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. A set event offers a picker of your declared variables, and its value editor matches the type - number fields even accept simple math, so love + 1 adds one to the current value. 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.