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

Before a binding can call anything it has to know which object holds the member. The Target card is where you say so once, and after that the runtime stops looking.

One Dungeon Heist guard talks to three different kinds of object. Its movement and sight services sit on the guard itself. Guards and GameMaster are single shared objects the whole level uses. The thing it is currently chasing is whatever its focus variable happens to hold this frame.

A single “find the component” rule cannot serve all three. A scene-wide search would find the wrong guard’s service, and a hard reference would stop the graph from being reusable. So the mode is an authoring choice, and each mode has exactly one resolution rule.

Mode is the first row of every Target card. Pick one and the rest of the card changes to ask for exactly what that mode needs.

Mode Reach for it when You fill in
Agent The component travels with the actor Resolve (Self, Children, or Parent), a Child path for Children, then Component
Reference One object serves everybody: a ScriptableObject holding shared game state or tuning, or a shared scene object Target type, then whoever fills the Object slot: the host in code, the graph, or a scene owner
Static The declaration has no instance Type
Variable The object changes while the game runs Variable, then Target type
Asset The graph itself chooses one project asset, including a shared event channel Target type, then the Asset field

Each mode in the samples:

  • Agent: Guard2.bqbehavior binds GuardBehaviorMovementService and GuardBehaviorActor on the guard itself.
  • Reference: CpuRace.bqbehavior binds the Pacing, Drivers, and GameMaster assets through slots its driver fills at runtime.
  • Static: Horde’s HordeEnemy.bqbehavior calls Unity.Mathematics.math.distancesq.
  • Variable: Guard2.bqbehavior reads Position off the focus target its liveFocus variable holds.

Every example on this page comes from a sample game or from DocumentationTargetModes.bqbehavior in the Platformer project, a five-node graph with one member node per mode, ready to open and click through.

The whole inspector rail for a Static method binding: the SELECTED NODE head, the Target card with Mode Static and Type Mathf, the Member card naming Abs, the Arguments card feeding f from the blackboard value velocity_x, and the Result card storing the return in speed
Figure 1. Every member node reads top to bottom in the order you author it. Target says which object; Member says which declaration; Arguments and Result say where the values come from and where they go. This one turns a signed velocity into a speed with Mathf.Abs.
  1. Select a member node and read the top card, Target.

  2. Choose Mode. On a GameObject graph the choices are Agent, Reference, Static, Variable, and Asset. On an entity graph the same row offers Self, Handle, Singleton, Static, and Asset; see entity bindings.

  3. Fill the rows that mode asks for. The sections below walk through the choices.

  4. Open Member > Change and pick the declaration. Until Target resolves to a type, there is nothing to list.

  5. Finish the cards below it. Arguments come from constants, blackboard values, or sibling bindings; a result can decide the node outcome, land in a variable, or both. Arguments and results has every option.

Agent: a component that travels with the actor

Section titled “Agent: a component that travels with the actor”

The default. The member lives on the GameObject the agent runs on, on that object’s parent, or on one named child. Nothing walks the scene.

The Target card with Mode set to Agent, Resolve set to Self, and the component GraphEnemyPatrol chosen, with the help line Resolves the component on the agent’s own GameObject
Figure 2. Platformer’s EnemyPatrol.bqbehavior, node advance. Self resolves GraphEnemyPatrol on the enemy that runs the graph.
  1. Set Mode to Agent and Resolve to Self.
  2. Under Component, pick the component type. The picker’s Project scope lists your own components first.
  3. Open Member > Change and choose the member.
The Target card with Mode Agent, Resolve Children, a Child row reading Sprite, and the component SpriteRenderer chosen, with the help line explaining that the path is exact and a missing path is a validation error
Figure 3. DocumentationTargetModes.bqbehavior, node which way it faces: SpriteRenderer.flipX read off the child named Sprite.
  1. Set Resolve to Children. A Child row appears.
  2. Type the path exactly as it reads under the agent in the Hierarchy: Sprite, or Body/Sprite for a grandchild.
  3. Pick the Component on that child, then the member.

The path is a lookup, never a descendant search: the first object matching that exact path is bound, and a path that finds nothing is reported as a missing host, named after the agent, with nothing else tried. When a scene object owns the graph, the rail checks against that object while you author: the Child row turns invalid as soon as the path finds nothing, and the Component row reads not on the selected agent when the component is absent there.

The Target card with Mode Agent and Resolve Parent, the component Rigidbody2D chosen, and the help line Resolves the component on the agent’s parent GameObject
Figure 4. Node sideways velocity: Rigidbody2D.linearVelocityX read from the parent, the usual shape when the brain sits on a child of the physics body.
  1. Set Resolve to Parent.
  2. Pick the Component that lives on transform.parent, then the member.

Racing Line does the same for the car: the CPU driver’s agent is a child of the vehicle and reaches the Rigidbody above it through Parent.

How Agent decides. On the host it resolved, the component whose runtime type equals your chosen type wins. When nothing matches exactly, a single assignable component is accepted. A missing host, no matching component, or two equally good candidates each report themselves (host missing, not present, ambiguous). None of them falls back to another object.

Reference: one shared object, named by a slot

Section titled “Reference: one shared object, named by a slot”

A Reference target is a named slot: the slot key, the expected type, and whatever object fills it. The graph carries the slot; three different parties can fill it.

The Target card in Reference mode with Target Type Players and the Object row showing the assigned Players asset
Figure 5. DocumentationMemberNodes.bqbehavior, node check fall: the Players asset assigned in Object, so the graph carries the reference itself.
The Target card in Reference mode with Target Type GameMaster and the Object row reading assign a GameMaster in amber
Figure 6. Node is the goal open: the same card with the slot left empty. This is the expected state for a slot your code fills at runtime, and Bindings valid still reports the graph sound.
  1. Set Mode to Reference.
  2. Under Target type, pick the class. The Project scope groups your types under Components, Interfaces & abstract bases, GameLogic assets, and Project ScriptableObjects.
  3. Open Member > Change and bind any instance member on the class: a method, a property or field, a condition.
  4. Decide who fills the slot:
    • The host, at runtime. Leave Object empty. The component that composes the agent builds a BehaviorMemberReference per slot key and assigns the array to BehaviorAgent.MemberReferences before initializing the agent. The graph asset carries no reference at all, so the same graph binds to whichever instance the host chooses. Racing Line’s CpuBehaviorGraphDriver.Configure fills pacing, drivers, driving, and gameMaster this way; Dungeon Heist’s GuardBehaviorActor fills five slots, including its own patrol-speed clone and patrol route.
    • The graph, at design time. Drop a project asset into Object. The reference is stored with the graph itself, in the .bqbehavior importer’s slot, so every agent that runs the graph gets the same asset.
    • A scene owner, at design time. Drop a scene object into Object. It is stored on that agent, the same BehaviorAgent.MemberReferences a host fills in code. When several scene agents run one graph, an Owner row appears above Object so you can see whose reference you are editing.

A slot filled on both the graph and the agent is refused when the agent initializes. Assigning a scene object to a slot the graph held clears the graph’s stored asset, and a scene object can never be stored on the graph.

An agent’s references are fixed once it is running. During Play Mode, in Live and in Static, the Owner row names the running agent and Object shows its current reference read-only; assign it after Play Mode stops.

The Target Type picker with the Project scope chip active, listing the Platformer project’s own components followed by its interfaces and abstract bases and then its GameLogic assets, with GameMaster highlighted as the current selection
Figure 7. The Project scope of the type picker. The sample games’ shared authorities, such as GameMaster, Players, and Collectibles, sit under GameLogic assets.

A ScriptableObject is the usual Reference target: a shared authority that owns game state, tuning data, a config. For an asset your game already initializes and holds, such as the sample games’ Pacing or Guards, leave Object empty and let the host pass its instance, so the graph binds to the one instance the rest of the game uses. Drop the asset into Object when the graph itself should own the reference.

Choose a different mode when the asset is not the point:

  • The members you want are static on the class: use Static. An asset instance is always Reference.
  • The asset should differ per agent, or change while the game runs: declare a blackboard variable of the class, let the host or another node write the asset into it, and target that Variable.

Addressables. A slot the graph or an owner fills is an ordinary serialized Unity object reference on the imported graph asset or on the agent’s prefab, and Addressables treats it like any other asset dependency. The usual rule applies: the reference resolves to the shared instance when the holder is itself in Addressables space, in a group that depends on the asset’s group; a holder outside Addressables space, such as a scene in the build list, gets its own copy of the asset and binds to a second instance that never sees the state the rest of the game writes. A project that loads its graphs through AssetReferenceT<BehaviorSourceAsset> and its agents from Addressable prefabs can therefore store those shared assets on the graph directly. A graph that lives in a build-list scene should leave the slot to the host, which hands over the instance it already loaded.

The Target card with Mode Static and the Type row showing Mathf from UnityEngine, tagged STRUCT 67 members
Figure 8. Node velocity into speed: Type is the declaring type, and that is the whole card.
  1. Set Mode to Static.
  2. Under Type, pick the declaring type. Any type with static members qualifies: Mathf, Unity.Mathematics.math, or a static helper class of your own.
  3. Open Member > Change. Instance members stay listed with the reason instance member: choose an instance target, so you can see the declaration you were thinking of and why it needs a different mode.
  4. Feed the arguments from the blackboard and store the result, as the See it rail above does with velocity_x in and speed out.

One CLR declaration with no instance, and therefore one value for the whole game. Static state is shared state: use an instance target when you want per-agent answers. Horde’s HordeEnemy.bqbehavior uses Static for math.distancesq, which is pure arithmetic and reads identically on both runtime paths.

Variable: whatever object the blackboard holds right now

Section titled “Variable: whatever object the blackboard holds right now”
The Target card with Mode Variable, the Variable row reading nearest_coin : Coin with a check mark, Target Type Coin, the sentence Coin can provide Coin, and the SAVED IN THE GRAPH receipt showing the saved member-target line
Figure 9. Node nearest coin taken: Coin.IsCollected read off whichever Coin the nearest_coin variable carries this evaluation.
  1. Declare a blackboard variable of the object’s type, if you have not already. The Blackboard panel’s New variable takes a name and then a type; the variable picker’s Choose type and declare target… does the same from inside the Target card.
  2. Set Mode to Variable. The variable picker opens at once, headed by the values that can provide an object.
  3. Choose the variable. Target type fills from its declared type and the member picker opens straight after, listing that type’s members.
  4. Choose the member.
  5. Make sure something writes the variable before this node runs: the host through the blackboard, or another member node. Guard2.bqbehavior surfaces GuardBehaviorActor.LiveFocus into liveFocus with one property read, then reads Position through it with a Variable target.
The blackboard variable picker headed Choose blackboard variable and Can provide Coin, listing nearest_coin under Variables declared by this graph, with Show entries that cannot hold it unchecked
Figure 10. The variable picker. Untick Show entries that cannot hold it and only the values that can carry the target type remain.

How Variable decides. The variable is read before each evaluation that needs it, so a new object takes effect on the next evaluation. A compatible value is used directly; a GameObject, Transform, or Component carrier resolves the component on its own GameObject only. An empty, destroyed, wrong-type, or component-less value fails that one evaluation without substituting anything. Changing the object while the old one owns a coroutine or an event subscription releases that work from the old object first: the old activation finishes as a failure, and a later activation can start against the replacement.

Set the graph’s Runtime path to Entity and the same Mode row offers Self, Handle, Singleton, Static, and Asset. Self is the entity the graph instance runs on, Handle is exactly one hop to another entity, Singleton is the one entity in the world carrying a component, and Static is the same declaring-type mode as above. Asset chooses the same project channel on either runtime path. Entity bindings shows the entity-specific cards.

A graph sometimes needs a component it never declared: the Rigidbody on the actor, the Renderer on a child. Rather than wrap GetComponent in your own method, pick the acquisition row and then the component you want. That authors one closed GetComponent<T>() method binding with Agent mode, Self resolve, the agent’s own Transform as the carrier, a reference test against null, and a stored result surfaced under the acquired component’s lower-camel name.

Editing the target afterwards re-closes the same acquisition against the new carrier instead of clearing your member choice. Any Component subtype can carry one, because it resolves the acquired component on its own GameObject; an interface cannot. The Static segment stays visible on an acquisition’s card but is never offered, because a component is read off an instance.

To ask for an implemented interface rather than a concrete component type, bind the ordinary native GameObject.GetComponent<T>() or Component.GetComponent<T>() method and choose that interface in Generic types. The carrier remains a GameObject or Component instance; the query’s type argument can be an interface. No component wrapper or invented T : Component constraint is needed.

Presentation destinations: text, animation, and audio

Section titled “Presentation destinations: text, animation, and audio”

A Target card wires a member node inside the graph. A separate Core-owned family of components wires a shared value to what the player sees and hears, entirely outside the graph: no member node, no Target card, no Horde-specific script. Add NumericLabelBinding, NumericAnimatorBinding, or NumericAudioSourceBinding to the GameObject that carries the destination, assign the same shared FloatVariable asset as Source, and the destination tracks it for the rest of its lifetime.

Component Destination Author
NumericLabelBinding A UI Toolkit Label’s text Document, Label Name, and a composite Format string
NumericAnimatorBinding An Animator numeric (Float or Int) parameter Target, Parameter Name, and a Multiplier/Offset mapping
NumericAudioSourceBinding An AudioSource’s pitch and volume Target, with independent pitch and volume multiplier/offset mappings

Horde Survival’s HUD, warning chip, and warning tone each carry one of these components, all pointed at the same WaveDifficulty asset the director reads. Raising the shared value updates every destination on its own next change, with no synchronization code connecting them to each other. The chip’s Animator-driven pulse speeds up and its AudioSource pip rises in pitch and volume as the value climbs; a still frame can only show the label text and the chip artwork, not the motion or the sound.

The Horde HUD seven seconds into a run, its red difficulty label reading 3, with the wave warning chip at the top.
Figure 11. The HUD’s difficulty Label reads 3, with the wave warning chip at the top.

Each binding resolves and subscribes on OnEnable/Start, unsubscribes on OnDisable, and refreshes on every effective change to the source, including an Inspector edit and a configured reset, with no per-frame poll.

When it goes wrong

SymptomCheckFix
Validation reports an ambiguous target.Two components on the host satisfy the chosen type.Choose the exact concrete type, or move one of them off that object.
The binding works on one actor and faults on another.The second actor is missing the component, or its child path differs.Add the component, or bind through Reference if the object is genuinely shared.
The Object row reads "assign a …" in amber.The Reference slot is empty in the graph and on every owner.Expected when the host fills the slot in code. Otherwise drop the asset or scene object into Object.
Every agent reads the same number.The mode is Static.Static is one declaration for the whole game. Use Agent, Reference, or Variable for per-agent values.
A Variable target fails on the first tick.The variable is None until something writes it.Write the object first, with a member read or a write, then bind against it.
A child path stopped resolving after a scene edit.The child was renamed or reparented.Update the Child path, or move the component onto the agent and use Self.
The member list is empty.Target is unresolved, so there is no type to list members from.Finish the Target card first.

Declared asset: one channel chosen in the graph’s source

Section titled “Declared asset: one channel chosen in the graph’s source”

A Reference slot is useful when the host supplies an object. It is unnecessary ceremony when the graph itself always calls one particular channel asset. Behavior Trees and State Machines can instead declare that asset directly in the member target’s text, so a missing assignment fails at bake time rather than on the first tick.

Use a declared asset when every agent running the graph chooses the same real ScriptableObject, such as an unparameterized alarm channel. The identical target record works on GameObject and entity graphs; only the graph’s %% runtime-path: entity header changes which baked storage it uses. Use Reference when a host supplies the object, and Variable when the object changes during play.

Select a Message (member_message) raise step or an Event Condition (member_event) listen step in the Behavior Tree Editor. Asset is the fifth segment in either runtime path’s Mode row. The Target card shows Target type and an Asset field using the same project-asset picker as a declared object value. At the default rail width, Mode shows words without glyphs so every choice fits. Widen the rail to see the mode glyphs, including Asset’s document glyph.

Plain text
%% member-target node="raise_alarm" binding="alarm" mode="asset" asset="asset(0123456789abcdef0123456789abcdef, \"AlarmRaised\")" assembly="MyGame" type="MyGame.AlarmChannel"
%% member-identity node="raise_alarm" binding="alarm" kind="method" name="Raise" static="false" access="invoke" return-assembly="mscorlib" return-type="System.Void"

The name beside the GUID makes the source readable. Resolution uses the GUID without searching the scene. The field reads the resolved asset’s current name even when that saved display name is older. Assigning through the field writes the chosen asset’s GUID and current name into the graph’s own text, rather than a host-supplied slot or importer setting.

  1. Select the raise or listen step and choose Mode > Asset.
  2. Choose the channel’s Target type. This constrains the Asset field to that declared type.
  3. Drop or pick the project channel in Asset. The field reads its own name, such as AlarmRaised. Scene objects and assets of another type are refused without replacing the saved assignment.
  4. Choose the ordinary public member under Member > Change: a raise method on a Message step, or the channel’s notification on an Event Condition step.
  5. Clear Asset. The field reads None, the existing generic unassigned prompt, and the step reports a missing channel. Choose another asset of the same declared type: its own name replaces None, and the missing-channel diagnostic clears when the channel resolves.
  6. Save and reopen the graph. The selected asset remains in the step’s canonical asset key. Undo and redo restore the assignment along with the displayed state.

Changing an entity Event Condition from an enabled-component or retained-buffer observation to Asset removes the old native observation and buffer selection. Choose the channel type, then assign its asset and select the notification to complete the binding. Undoing the target-mode change restores the original observation, including its buffer selection; redoing the edits restores the channel.

Choose an EventCondition (member_event) step, Mode > Asset, the channel type and the channel asset. Under Member > Change, choose the channel’s public notification, such as EventRaised. The GameObject rail shows the subscription contract; it has no result control. To change the outcome in the graph’s source, edit the existing member-event record for that node and binding, for example:

Plain text
%% member-event node="listen_alarm" binding="alarm" outcome="failed"

Use the node and binding IDs from your own listen step. outcome="succeeded" reports success when the event fires; outcome="failed" reports failure. Both runtime paths honor this authored record.

On a GameObject agent, the step subscribes to that exact asset’s notification only while active. With no notification it stays running. Raising another channel does not complete it; raising the chosen channel completes it with the authored outcome. A raise before the step becomes active is not replayed to that subscription. After completion, a new activation waits for a new notification.

The listen step uses the same mode="asset" asset="asset(guid, \"name\")" target record as a raise step. Moving that text to an entity graph does not change the chosen channel or the authored result. The entity runtime observes through the event library’s integration and the package’s World-scoped generation seam, never through a managed subscription inside a Burst tick. Its registration frame is excluded; a later raise is visible on the listening graph’s next scheduled tick in a later frame. For Core events, the optional Core Entities integration owns that connection; the Behavior Trees and State Machines package does not depend on Core.

A cleared or deleted listen channel fails the bake with the same node/binding coordinates and missing-channel diagnostic as a raise step. This capability reports a notification; it does not add a one-frame has-received predicate or make Dungeon Heist guards switch into lockdown in response to the alarm.

Assign an asset on an entity graph’s raise step, clear it, then assign a replacement. Repeat on a listen step. Both label sets use the identical field and author the identical mode="asset" record. Editing only the saved display name leaves the resolved field name and selected object unchanged; choose a different channel in Asset to change its GUID.

The graph’s runtime path selects the baked mode while the target spelling stays identical:

Runtime path Baked identity Storage
GameObject DeclaredAssetReference Exact resolved object in a generated managed companion slot
Entity DeclaredAssetIdentity AssetStableId, all four GUID words in a blittable Unity.Mathematics.uint4; one artifact-level resolved-reference table for graph registration

The bake resolves each distinct declared target once through the same asset resolver and checks the object against the target’s declared type. It preserves every bit of the selected GUID; neither the saved display label nor the object’s actual name participates in routing. Two assets with the same name remain independent channels on both runtimes. An entity target carries only the GUID and its artifact reference-table index; it requests no per-agent managed slot. Declared targets add no blackboard variable or selectable public companion member on either backend.

The stable baked cache has no Entities or runtime-backend dependency. The backend wraps those four words in Unity.Entities.Hash128 for registration and native event transport, without parsing text or allocating during a tick. Authoring validation lives in the owning backend.

On this entity mode only, the declaring type need not be an IComponentData or buffer element. The DeclaredAssetIdentity availability class admits the managed channel’s raise method and listen event for baking without treating the channel as component storage. Other entity targets retain their existing storage and member-kind restrictions. This is a source and bake contract, not permission to invoke a managed method or subscribe to a C# event inside a Burst tick.

The generated entity binding set does not compile a channel into a component array or a direct managed member accessor. Its baked identity is separate from ordinary native member access, so mixed graphs keep their native accessor ids aligned. An entity Asset listen step offers its event result without the enabled-component and event-buffer Observation choices. Those choices configure ordinary ECS occurrence sources.

  • No asset key is a source parse error. asset="none" is an explicitly unassigned channel and fails the bake.
  • Deleting an assigned channel automatically reimports every graph that declares it. The graph’s source stays unchanged, but its executable cache is invalidated and its diagnostic identifies the missing channel by GUID.
  • A resolved object of the wrong type fails with the resolved and expected type names. Correct the asset or its declared type rather than adding a runtime fallback.
  • The Behavior Tree Editor runs the same check while the graph is open: the step’s node shows the broken-binding warning with the same message, and the binding verdict counts it instead of reading Bindings valid. Saving stays blocked until the channel resolves.
  • Both runtime paths report the same missing, unresolved, and wrong-type channel failure. Assigning a backend-specific baked mode to the other runtime path still reports member-target-backend-mismatch; the authored asset token itself is portable.

For Dungeon Heist’s Assets/_Project/Behavior/Guard2.bqbehavior, clearing the chase_alarm step produces this exact diagnostic:

Plain text
Member binding 'chaseAlarm' node 'chase_alarm' declared channel is missing or invalid: the declared channel does not exist on this target; assign a channel asset.

Assigning a duplicate channel and deleting that duplicate produced:

Plain text
Member binding 'chaseAlarm' node 'chase_alarm' declared channel is missing or invalid: asset guid '93a96b435fc7c8e4290286413cae3105' did not resolve.

The GUID in the second message is the deleted asset’s identity and varies with the asset. Both errors belong to the imported Guard2.bqbehavior asset; the message names the binding and step, and the diagnostic points at the target’s source line. Choose a resolvable channel in Asset and rebake: the error clears and the graph receives a fresh executable cache. The guard integration tests exercise both failures and replacement-channel recovery through the real bake pipeline. Their live import case also restores the original AlarmRaised assignment byte for byte after proving automatic reimport.

Use Message for a fire-and-forget call, Reference when the graph’s host must choose the target instead, or entity bindings for the entity execution and member-availability contract.

Full-size image