Skip to content
Bit Quirky Behavior Trees and
State Machines

Search documentation

All topics and APIs

Close returns focus to Search.

What are you looking for?

Try a common topic or enter a complete API identifier.

Browse the reference instead

Esc closes · Tab reaches results · Enter opens the focused link

v0.11.0
Menu

Variables and types

Declare a graph variable, pick the exact type your game already uses, and decide what it starts as.

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.

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.

  • 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 string to float tuning 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.

The blackboard type picker with its search field and grouped type rows
Figure 1. The whole picker. The search counts every type it can offer; the shape and the element shape are chosen above the list; a source filter sits between them and the grouped results.
Native size type picker showing the List shape, the Single element shape, and the selected Vector2 type
Figure 2. Shape and element type are separate choices. Escape closes the picker without losing the name you typed.
The advance node’s Read-write parameters card and the EnemyPatrol blackboard showing route, profile, route_tag, next_stop, and pause_progress, with a 2 READ · 2 WRITE count
Figure 3. 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.
Six declared Guard2 variables above the Member bindings section, with Variables 6 and Member bindings 10 visible in the same Blackboard panel
Figure 4. Declared variables and surfaced bindings share one namespace. In this graph, Variables 6 includes the alarm and indexed waypoint values with the tier override; Member bindings 10 lists values connected to the guard’s game components.
The Behavior Tree Editor’s Blackboard following the running director: the SHARED group holds wave_difficulty at 1 with a shared WaveDifficulty chip, above the director’s private HOST AUTHORITATIVE rows.
Figure 5. Horde Survival’s wave_difficulty field: the SHARED group reads 1 with a shared WaveDifficulty chip, ahead of the director’s own HOST AUTHORITATIVE rows.
  1. Open a graph in Static and open the BLACKBOARD · WHOLE GRAPH panel in the right rail.

  2. Under Variables, choose New variable.

  3. Type the name first, in the C# identifier style the rest of the graph uses: patrol_speed, current_target, route_tag.

  4. Choose Choose a type… under the accepted name, or press Enter to move straight to type selection.

  5. Pick the shape: Single, List, Array, or Dictionary. A dictionary asks for its key type first and its value type second.

  6. 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.

  7. 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.

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.Entity is 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 ScriptableObject or 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 ScriptableObject implements it. Declare the exact interface as None, then populate it with a member result such as GetComponent<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.bqbehavior shows the pattern: four Transform declarations, every one authored none, 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

SymptomCheckFix
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 WaveDifficulty this page’s shared identity example reads.
Full-size image