Variables And GameState

GameState is the project's shared bag of named values: score, lives, a quest line, an inventory list, a remembered object. Declare it once. Object Flow, Scene Flow, UI, components, and OpalScript all read and write the same fields.

Per-object variables live on one instance. They have no lifetime of their own — the instance is already scene-lived.

Same fields, different pickers. Flow writes GameState with Add Counter / Set Value (and the list or object nodes), and reads it with Get Value or a Flow = expression (=GameState.score). HUD labels use the UI Inspector Data bindings card (Source → GameState). A template like Score {value} belongs on the UI, not on a Flow node.

When To Use Which

Store	Use for	Example
GameState	Values the whole game needs	score, lives, hasKey, best
Object variables	State that belongs to one instance	a chest's opened, a door's locked
Component fields	Values a component already models	Health hp, Inventory counts

Prefer Health's hp over a loose enemyHp number. Prefer GameState for a score that the HUD, a win rule, and the next scene all need.

Open The Panel

1. Click Variables in the bottom shelf (next to Saved).
2. The dock shows Project variables.
3. Choose + Add variable, then set Name, Type, Lifetime, and Default.

While Play is running, Live value shows the current number, text, list, or object; declarations are read-only. Uses opens references in project and scene scripts, Flow, and UI. Failed or incomplete checks are shown explicitly.

Changing a variable's name preserves its stable script alias (shown below the name) and saved-value identity. A supported rename updates name-based references in one undoable change. Calculated names, unsupported scripts, or name-based references in closed scenes prevent an unsafe rename and explain why. Change a script alias separately with Script Studio's Rename symbol.

Help & reset → Reset this project's saved values… asks before clearing this project's local Saved values. The next play starts from defaults; declarations remain. The Flow action Clear Saved Variables does the same from a graph.

Object variables are declared on the selected object: Arrange → Inspector → Variables. Same types, no lifetime column.

Types

The type control uses these labels:

Type	Holds	Default example
Number	A number	0, 3, 100
True / False	A boolean	false
Text	A string	Player, Find the key
List	An ordered list of scalars	sword, 3, true
Object	A scene object (by id)	Unset until Set Variable To Object

A list mixes numbers, text, and true/false. It never stores a live Thing. An object variable stores an id, resolves to the live object when read, and is unset when that object is destroyed or the scene changes — it does not keep an object alive.

Lifetimes

Only GameState fields have a lifetime. Object variables do not.

Lifetime	Behaviour
Session (default)	Resets to its default when play starts. Kept across Go To Scene.
Saved	Remembered between plays — the game's save data. Restored when play starts, written on every change.
Scene	Back to its default every time a scene starts, including play start and Go To Scene.

Typical split:

Field	Lifetime	Why
score	Session	One run, many scenes
best	Saved	High score that should survive Stop and a later visit
keys	Scene	Pickups that should not leak into the next level

A session field that should have been saved looks like a bug: Play, set best to 12, Stop, Play again, and it is back to 0. Check the lifetime column before rewriting the graph.

Flow

The State group in the node picker is the write path.

Catalog label	Use
Add Counter / Set Counter	Number GameState
Set Flag	True / False GameState
Set Value / Get Value	Typed read/write (pick Game variable)
Add To List / Remove From List / Remove List Item / Clear List	List GameState
Set Variable To Object	Object GameState
Clear Saved Variables	Wipe saved data from a graph

Conditions:

Catalog label	Use
Variable at least	Number threshold
List Contains	First matching item (3 matches "3")
List Length At Least	How many items
Variable Holds An Object	The object field is set
Variable Is Object	It is this object

Get Value / Set Value sources that matter for GameState:

Source	Returns
Game variable	The whole declared field
List length	How many items
List item	Item by number — item 1 is the first
Random list item	One item
Object variable	A field on a scene object

Coin / On Tap
  -> Add Counter  score  +1
  -> Destroy

On Scene Start
  -> Variable at least  score  10
       ├─ true  -> Go To Scene  Win
       └─ false -> (keep playing)

Renaming a GameState field in the panel can rewrite those keys across scenes. Changing only a node's key by hand leaves the old name behind.

UI Bindings

Want a score on screen? Select a Text element and use Data bindings:

1. Source → GameState
2. Value → the field (score)
3. Format → Integer (rounded)
4. Template → Score {value}

{value} is the number. Wrap it in whatever words you like. The picker remembers the variable's id, so renaming the display name later does not break the HUD.

Older Expression bindings (self.score / GameState.score) still run if you already have them. Lists in those expressions are 0-based (GameState.items.length, GameState.items[0]). Flow list nodes are 1-based — do not mix those indexes.

A slider with a Variable field writes that GameState number, then the binding refreshes. See UI and HUD.

Lists

Declare a List. The default is a comma-separated literal (sword, 3, true).

Action	Result
Add To List	Append an item
Remove From List	Remove the first matching item
Remove List Item	Remove by 1-based index
Clear List	Empty the list

Use a list for inventory names, a queue of wave ids, or a bag of flags. Use a component (Inventory, Health) when the engine already models that data.

Object References

Declare an Object. It starts unset.

1. Set Variable To Object — Self, Target, or a specific object.
2. Any Object picker in a rule also offers Variable: name, so an action can target "whatever target currently is".
3. When that object is destroyed or you leave the scene, the variable is unset. Variable Holds An Object is the guard.

Never store a Thing yourself. The id is the only currency across Play, Stop, and scene changes.

Object Variables

On a selected object, the Inspector Variables card declares instance fields. Read and write them with Get Value / Set Value using Object variable, or with Add Object Counter / Set Object Flag.

Those names autocomplete in that object's Object Flow. They do not appear in the project Variables panel.

Scripts

In OpalScript, type Game. to discover the declared project symbols. Number → float, Boolean → bool, Text → string, Object → Entity. See Your first component, Scripts, and the typed gameplay guide.

Related Docs

• Visual scripting
• UI and HUD
• Projects and scenes
• Build your first game
• Testing and debugging
• Troubleshooting