f38d330ba1
* fix: node code bugs from docstring audit (#115) - runtime crashes, phantom/duplicate sockets, registry typo aliases, property default mismatches * fix: address PR #122 review - register template scene types on intent_state, StageExit node_state_pop, annotations, shared graph-test helpers, migration round-trip test * docs: correct the circular-import chain named in apply_to_scene's deferral comment * fix: SetScenePhase defaults to the shipped roleplay scene type instead of an empty string that errors on run
14 KiB
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 for scope semantics. The ...Path variants address nested values with dotted paths, and the counter nodes increment numeric state in place.
14 nodes.
| Node | Registry path |
|---|---|
| Counter State (Conditional) | state/ConditionalCounterState |
| Set State (Conditional) | state/ConditionalSetState |
| Unset State (Conditional) | state/ConditionalUnsetState |
| State Counter | state/CounterState |
| State Counter (Path) | state/CounterStatePath |
| Game State | state/Gamestate |
| Get State | state/GetState |
| Get State (Path) | state/GetStatePath |
| Has State | state/HasState |
| Has State (Path) | state/HasStatePath |
| Set State | state/SetState |
| Set State (Path) | state/SetStatePath |
| Unset State | state/UnsetState |
| 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. |