---
order: 4
title: States
---

# States

Most objects behave differently depending on what they're doing — a character that's *idle*, *running*, *in a menu*, or *paused* wants different logic active in each case. **States** let one node hold all of that logic at once and switch which part is live, instead of building a separate graph for every mode.

## What a state is

Each node has up to **30 state layers**, numbered 1–30. Every brick belongs to one or more layers, and a node can be "in" any combination of them at runtime. Think of states as transparent sheets stacked over the node: you author logic on whichever sheet a mode belongs to, and the runtime only acts on the sheets that are currently active.

This keeps a complex object readable — the *menu* logic and the *gameplay* logic live on different layers and never tangle together.

## Driving states at runtime

Two bricks do the work:

- The **[State Executor](../reference/generated/executors/state_executor.md)** adds or removes states — this is how you *change mode*.
- The **[State Gate](../reference/generated/gates/state_gate.md)** only passes pulses when the node is in a given state — this is how logic *reacts to mode*.

```
UI Click(PauseButton)        -> AND -> State(add=paused)
State Gate(paused) + Keyboard(Esc) -> AND -> State(remove=paused)
State Gate(playing) + Keyboard(WASD) -> AND -> Motion2D(move)
```

Movement only runs while in `playing`; the pause toggle flips the mode. No branch checks a flag — the State Gate does the routing.

## Authoring in the editor

The state panel sits at the top of the brick editor, one button per state, and gives each layer three signals:

- **Visibility** — click a state to show or hide its bricks in the graph. New bricks you add land in the visible layer, so you build one mode at a time without clutter.
- **Initial state** — one state is marked as where the node *starts* on load (right-click to set; only one can hold it, like a radio button).
- **Content** — a marker shows which states actually contain bricks, so empty layers are obvious.

```{tip}
Your brick layout is yours. The editor never auto-rearranges bricks when you switch states or reload — saved positions are respected exactly, so you can spatially group related logic and trust it stays put.
```

## States vs variables

A **state** is the right tool for *mutually exclusive modes* — you're either in the menu or you're not. A **[variable](variables.md)** is better for *quantities and flags that combine freely* — health, score, "has key". If you find yourself gating lots of branches on the same boolean variable, that's usually a sign it wants to be a state instead.

## Where to go next

- [Variables](variables.md) — the other half of a node's runtime state
- [Listeners, Gates, Executors](listeners-gates-executors.md) — where the State Gate fits in the pipeline
- The [State Gate](../reference/generated/gates/state_gate.md) and [State Executor](../reference/generated/executors/state_executor.md) reference pages