# State Nodes

Read and write named variables in the graph state. Every variable lives in a **scope**: `local` (this module run), `parent`, `shared` (all modules in the graph), `scene loop` (reset each loop iteration) or `game` (persisted with the scene save). See [States](../../core-concepts/states.md) for scope semantics. The `...Path` variants address nested values with dotted paths, and the counter nodes increment numeric state in place.

<!-- glossary:generated - everything below this line is generated by `python -m talemate.game.engine.nodes.tools glossary --write` - do not edit -->


_14 nodes._

| Node | Registry path |
| --- | --- |
| [Counter State (Conditional)](#counter-state-conditional) | `state/ConditionalCounterState` |
| [Set State (Conditional)](#set-state-conditional) | `state/ConditionalSetState` |
| [Unset State (Conditional)](#unset-state-conditional) | `state/ConditionalUnsetState` |
| [State Counter](#state-counter) | `state/CounterState` |
| [State Counter (Path)](#state-counter-path) | `state/CounterStatePath` |
| [Game State](#game-state) | `state/Gamestate` |
| [Get State](#get-state) | `state/GetState` |
| [Get State (Path)](#get-state-path) | `state/GetStatePath` |
| [Has State](#has-state) | `state/HasState` |
| [Has State (Path)](#has-state-path) | `state/HasStatePath` |
| [Set State](#set-state) | `state/SetState` |
| [Set State (Path)](#set-state-path) | `state/SetStatePath` |
| [Unset State](#unset-state) | `state/UnsetState` |
| [Unset State (Path)](#unset-state-path) | `state/UnsetStatePath` |

## Counter State (Conditional)

`state/ConditionalCounterState`

Counter node that increments a numeric value in the state and returns the new value.

Provides a required `state` input causing the node to only run when a state is provided

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `name` | `str` | (optional) |
| `reset` | `bool` | (optional) |
| `reset_cap` | `number` | (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `name` | `str` |  |
| `value` | `any` |  |
| `scope` | `str` |  |
| `reset_cap` | `number` |  |
| `reset` | `bool` |  |
| `new_cycle` | `bool` |  |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |
| `increment` | `number` | `1` | The amount to increment the value by. Min: 1. |
| `reset` | `bool` | `False` | If true, the value will be reset to 0 |
| `reset_cap` | `number` | `0` | If set (> 0), the counter resets to 0 once the value reaches this cap |

## Set State (Conditional)

`state/ConditionalSetState`

Set a variable in the graph state

Provides a required `state` input causing the node to only run when a state is provided

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `name` | `str` | (optional) |
| `value` | `any` |  |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `name` | `str` |  |
| `value` | `any` |  |
| `scope` | `str` |  |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |

## Unset State (Conditional)

`state/ConditionalUnsetState`

Unset a variable in the graph state

Provides a required `state` input causing the node to only run when a state is provided

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `name` | `str` | (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `name` | `str` |  |
| `value` | `any` |  |
| `scope` | `str` |  |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |

## State Counter

`state/CounterState`

Counter node that increments a numeric value in the state and returns the new value.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | required state input (conditional execution) |
| `name` | `str` | (optional) The key to the value to increment |
| `reset` | `bool` | (optional) If true, the value will be reset to 0 |
| `reset_cap` | `number` | (optional) If set, the counter resets to 0 once it reaches this value |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | the state that was passed in |
| `name` | `str` | The key that was used |
| `value` | `any` | The new value |
| `scope` | `str` | The scope that was used |
| `reset_cap` | `number` | The reset cap that was used |
| `reset` | `bool` | Whether the counter was reset |
| `new_cycle` | `bool` | True if the counter was at 0 before this run |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |
| `increment` | `number` | `1` | The amount to increment the value by. Min: 1. |
| `reset` | `bool` | `False` | If true, the value will be reset to 0 |
| `reset_cap` | `number` | `0` | If set (> 0), the counter resets to 0 once the value reaches this cap |

## State Counter (Path)

`state/CounterStatePath`

Counter node that increments a numeric value in the state using a path (e.g., 'a/b/c').

Creates intermediate dictionaries as needed (mkdir -p semantics).
Mutating operation - conditional by default with required state input.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | required state input (conditional execution) |
| `name` | `str` | (optional) The path key to the value to increment (e.g., 'a/b/c') |
| `reset` | `bool` | (optional) If true, the value will be reset to 0 |
| `reset_cap` | `number` | (optional) If set, the value will be reset to 0 when it reaches this value |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | the state that was passed in |
| `name` | `str` | The key that was used |
| `value` | `any` | The new value |
| `scope` | `str` | The scope that was used |
| `reset_cap` | `number` | The reset cap value |
| `reset` | `bool` | Whether reset occurred |
| `new_cycle` | `bool` | Whether this is a new cycle (value was 0) |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |
| `increment` | `number` | `1` | The amount to increment the value by. Min: 1. |
| `reset` | `bool` | `False` | If true, the value will be reset to 0 |
| `reset_cap` | `number` | `0` | If set (> 0), the counter resets to 0 once the value reaches this cap |

## Game State

`state/Gamestate`

Get the game state variables of the active scene.

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `variables` | `dict` | Dict of the scene's game state variables |

## Get State

`state/GetState`

Get a variable from the graph state

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `name` | `str` | (optional) the name to get |
| `default` | `any` | value to return if the variable is not set (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `name` | `str` | the name that was retrieved |
| `value` | `any` | the value that was retrieved |
| `scope` | `str` | the scope that was retrieved |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |

## Get State (Path)

`state/GetStatePath`

Get a variable from the graph state using a path (e.g., 'a/b/c').

Does not create missing containers - returns default if path doesn't exist.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `name` | `str` | (optional) the path name to get (e.g., 'a/b/c') |
| `default` | `any` | (optional) default value if path doesn't exist |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `name` | `str` | the name that was retrieved |
| `value` | `any` | the value that was retrieved |
| `scope` | `str` | the scope that was retrieved |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |

## Has State

`state/HasState`

Check if a variable exists in the graph state

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `name` | `str` | (optional) the name to check |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `name` | `str` | the name that was checked |
| `value` | `any` |  |
| `scope` | `str` | the scope that was checked |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |

## Has State (Path)

`state/HasStatePath`

Check if a variable exists in the graph state using a path (e.g., 'a/b/c').

Does not create missing containers - returns False if path doesn't exist.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `name` | `str` | (optional) the path name to check (e.g., 'a/b/c') |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `name` | `str` | the name that was checked |
| `value` | `any` |  |
| `scope` | `str` | the scope that was checked |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |

## Set State

`state/SetState`

Set a variable in the graph state

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `name` | `str` | (optional) the name to set |
| `value` | `any` | the value to set |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `name` | `str` | the name that was set |
| `value` | `any` | the value that was set |
| `scope` | `str` | the scope that was set |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |

## Set State (Path)

`state/SetStatePath`

Set a variable in the graph state using a path (e.g., 'a/b/c').

Creates intermediate dictionaries as needed (mkdir -p semantics).
Mutating operation - conditional by default with required state input.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | required state input (conditional execution) |
| `name` | `str` | (optional) the path name to set (e.g., 'a/b/c') |
| `value` | `any` | the value to set |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | the state that was passed in |
| `name` | `str` | the name that was set |
| `value` | `any` | the value that was set |
| `scope` | `str` | the scope that was set |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |

## Unset State

`state/UnsetState`

Unset a variable in the graph state

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `name` | `str` | (optional) the name to unset |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `name` | `str` | the name that was unset |
| `value` | `any` | the value that was unset |
| `scope` | `str` | the scope that was unset |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |

## Unset State (Path)

`state/UnsetStatePath`

Unset a variable in the graph state using a path (e.g., 'a/b/c').

Does not create missing containers - returns None if path doesn't exist.
Mutating operation - conditional by default with required state input.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | required state input (conditional execution) |
| `name` | `str` | (optional) the path name to unset (e.g., 'a/b/c') |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | the state that was passed in |
| `name` | `str` | the name that was unset |
| `value` | `any` | the value that was unset |
| `scope` | `str` | the scope that was unset |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `local`, `parent`, `shared`, `scene loop`, `game`. |