Variables and types
Declare a graph variable, pick the exact type your game already uses, and decide what it starts as.
On this page
A variable is a name, a type, a shape, and a starting value. Pick the type your game already uses and the graph stops being a translation layer.
The problem
Section titled “The problem”EnemyPatrol.bqbehavior declares the shapes instead. route is a List of Vector2. profile is the project struct PatrolProfile, authored inline with PauseSeconds, FaceDirection, and MoveSpeed. route_tag is a string holding curious. The enemy component receives the types it declared, with no unpacking step.
The same graph also owns the enemy’s progress: which stop comes next and how far into its pause it has gotten. next_stop is the project struct PatrolStop, holding WaypointIndex, Phase, and CompletedCycles; pause_progress is a float. These are not settings authored once and forgotten: the advance node reads both before every step and writes back the ones that changed, on this exact running instance. Enemies.EvaluatePatrol still decides where an enemy goes and how long it pauses; the graph is where two enemies sharing this same authored route keep their own place in it, instead of an offscreen record neither of them can see.
When to reach for each shape
Section titled “When to reach for each shape”- Single for one value: a speed, a mode enum, a last known position.
- List or Array when the graph owns several: patrol points, candidate cover spots. A list adds and removes rows; an array has an authored length.
- Dictionary for named lookups, such as
stringtofloattuning values. Keys are unique and authored order is kept.
Shapes nest on the GameObject path, so List<List<int>> and Dictionary<string, List<Vector3>> are both authorable. On the entity path they are not; see entity variables.
See it
Section titled “See it”


EnemyPatrol.bqbehavior’s advance node. Its two ref parameters, nextStop and pauseProgress, read from and write back to the blackboard rows of the same name; the band above Variables counts exactly how many of the five declared values this one node reads and writes.

wave_difficulty field: the SHARED group reads 1 with a shared WaveDifficulty chip, ahead of the director’s own HOST AUTHORITATIVE rows.-
Open a graph in Static and open the BLACKBOARD · WHOLE GRAPH panel in the right rail.
-
Under Variables, choose New variable.
-
Type the name first, in the C# identifier style the rest of the graph uses:
patrol_speed,current_target,route_tag. -
Choose Choose a type… under the accepted name, or press Enter to move straight to type selection.
-
Pick the shape: Single, List, Array, or Dictionary. A dictionary asks for its key type first and its value type second.
-
Pick the exact type. Search accepts a short name or a qualified one, and two types with the same short name stay two separate identities because the graph records namespace and assembly.
-
Edit the starting value. Numbers,
bool,char, and enums use their ordinary controls; flags enums accept several members including the empty set; a project struct expands into its serialized fields; a project class is None until you create an inline instance.
How it decides
Section titled “How it decides”Names
- A name is unique across every other name the graph holds, which includes surfaced binding values and external service names.
- Renaming a declaration rewrites the references to that exact declaration in the same edit.
- Removing one leaves every old reference visible and unresolved, so the repair stays yours to make.
Types
- A built-in scalar is saved by its C# keyword. Everything else keeps its exact type and assembly identity.
- A project class needs
[Serializable], and a project struct needs either[Serializable]or a carried unmanaged layout. Types that miss that stay listed under Not available with the reason. - Delegates, pointers, by-reference types, open generic definitions such as
List<>, and editor-only types have no saved form.Unity.Entities.Entityis listed but unpickable, because an entity handle has no meaning until a World hands one out. - Collection types are declared through the Shape control instead of appearing as type rows.
Starting values
| Declared type | Starts as |
|---|---|
Number, bool, char |
Its zero value |
| Enum | The zero-valued member, or underlying zero when no member names it |
System.Guid |
00000000-0000-0000-0000-000000000000 |
| Unity value struct | Every component at zero |
| Project struct | Every serialized field at its own default |
string, project class, asset, interface, component slot |
None |
| List, array, dictionary | An empty collection or None, as authored |
Edit System.Guid in a single text field. Valid input is saved in the hyphenated xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx form. Invalid text stays a draft and does not replace the committed identifier. A member result can write a nonzero identifier; reset restores the authored starting value.
None and empty are different states. none means there is no instance. [] means a collection exists with zero elements. [none] means a collection exists holding one null element. That distinction survives save, reopen, bake, reset, and the per-instance clone at initialization.
Customer-owned values
Serializable customer classes and structs keep nonzero Guid fields, including nested fields and inherited private fields marked [SerializeField] or [SerializeReference]. Their dictionaries and sets keep their contents; queues keep their order too. Those values survive save/reopen and per-agent cloning, and reset restores the authored contents. No wrapper type or custom serialization callback is required.
Runtime-assigned managed references retain their concrete types, nulls, shared references and cycles. Shared nested collections remain shared within one cloned value graph, while mutable customer data stays isolated between agents. Reset restores the authored values rather than mutating another agent’s copy.
Object references
- A project asset is stored by stable asset identity, so a
ScriptableObjector prefab reference reopens correctly. - A component slot is authored as None and filled at runtime by the running GameObject graph, through a member read or write. Dropping a scene object into a saved graph value is refused instead of quietly storing a reference that cannot survive.
- An interface implemented by a component works the same way, even when no
ScriptableObjectimplements it. Declare the exact interface as None, then populate it with a member result such asGetComponent<IGuardActor>(). Interface lists keep those same component references; each graph instance owns its list, and reset restores the authored values without destroying the referenced components. EnemyPatrolParams.bqbehaviorshows the pattern: fourTransformdeclarations, every one authorednone, all populated by the running instance.
Shared identity
A declared value’s shape says what it holds; identity says who owns it. Most declared values live inside one graph instance and start fresh with every new one. A game can inject an explicit shared numeric source instead, so the same value is read by every subscribed consumer and by the asset’s own Inspector, never invented as a private per-instance copy. Horde Survival’s wave_difficulty field is a host input field, not a declared variable; only BehaviorSharedNumericInputBinder (GameObject) or BehaviorSharedNumericEntityInputBinder (entity) injecting WaveDifficulty makes it shared. Live editing reads the running SHARED group that identity earns.
Reset
A shared asset’s own Has Reset Value toggle and Reset Value field, in its Reset box, decide what a new run restores. Turn Has Reset Value on and set Reset Value, and the game’s reset event calls the asset’s GameReset(), which restores that reset value on the asset itself, so the graph and every binding read it on their next tick. Leave Has Reset Value off and a new run leaves the value exactly where it was last set. WaveDifficulty ships with Has Reset Value on and Reset Value 1, so Horde Survival’s new-run action always returns it to 1.
Dictionary keys use the declared key type’s equality. Strings compare ordinally and case-sensitively with no trimming, numbers by exact value, enums by underlying value, flags as a set. Empty text is a legal key and None is never one. A duplicate is refused without touching the existing entry, and when the editor cannot compute a free starter key the new entry holds <unset> until you supply one.
Per-instance progress and node access
A variable is data; whether a node may touch it is a separate, per-node choice. A member node that reads a declared value needs that value in its own declared read set, and one that writes it needs write; a ref parameter that does both needs both, and a node without the matching access is refused before the graph can bake rather than silently allowed because the value exists. EnemyPatrol.bqbehavior’s advance node declares read=route,profile,route_tag,next_stop,pause_progress write=next_stop,pause_progress, matching the two parameters AdvancePatrol receives by ref and hands back changed. Two enemies running this exact graph each keep their own next_stop and pause_progress: advancing one never reads or writes the other’s blackboard. See Search and validation for that refusal, its exact wording, and its one-click repair.
When it goes wrong
Section titled “When it goes wrong”When it goes wrong
| Symptom | Check | Fix |
|---|---|---|
| Your struct is listed under Not available. | Read the reason on the row. | Add [Serializable], or declare a type whose stored shape the path can carry. |
| A List<Vector2> will not bind to a member that takes Vector2[]. | Collection types need exact identity in both places. | Declare the shape the member actually takes, or add an overload that takes the list. |
| The component slot you authored is still None in Play Mode. | Nothing has written it yet. | Let a member read or a member write put the concrete component into the slot, then read it from there. |
| A dictionary refuses Add entry. | Look for an <unset> key, or a key space that has run out, such as a bool with both values used. | Complete the pending key, or remove an entry before adding another. |
| Two variables with the same short type name behave differently. | Open each row and read the qualified type. | They are two identities. Pick the one your member declares. |
- Entity variables: the narrower set the unmanaged path carries.
- Live editing: watch these values while the game runs.
- Conversion: which variable types reach which member types, exactly.
- Platformer: the patrol whose route, profile, and route_tag this page reads.
- Horde Survival: the shared
WaveDifficultythis page’s shared identity example reads.