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

Condition and event

Check a member value or one event observation, or explicitly wait for your game to raise an event.

A member condition asks your code a question now. An event condition can check whether an event fired for this observation, or explicitly wait for the next firing.

The Platformer beacon has a wind up. The graph has to know two things about it: whether the beacon is ready to start, and when the wind up has finished. The first is a value it can read. The second only your component knows, and only when it happens.

Give the graph its own timer for the second one and you have two clocks that will eventually disagree about when a wind up ended. BeaconWarmUp.bqbehavior reads IsReady for the gate and waits for the WarmUpFinished event for the finish, so the beacon stays the only thing that knows how long a wind up takes.

  • member condition when a value already answers the question: Players.Initialized is true, stamina is above zero, the guard has a destination.
  • event condition, Reads as: Check, when an event is a yes-or-no gate: quiet means failed, and one observed firing means succeeded.
  • event condition, Reads as: Wait, when the graph must stay on a node until the next wind up, door movement, or animation event finishes.

A member condition can also poll. Map its false outcome to running and it re-reads the member on the next evaluation, which is a wait-until without a subscription.

A member condition checking player readiness
Figure 1. A member condition turns one value into a branch decision.
The comparison card of a member condition
Figure 2. The Comparison card: an operator, a compared value, and the two outcomes.
An event condition waiting for the slam wind up
Figure 3. The pictured event condition uses Wait and holds Running until the event arrives.
The event condition rail showing Target, Member, and Subscription
Figure 4. The pictured Subscription card shows the preserved Wait contract: it subscribes while active and responds once. Newly chosen events default to Check; choose Reads as: Wait for this use case.
The member condition rail: Target, Member, and the Comparison card the rail scrolls into
Figure 5. A member condition from the top: the object, the member, and the comparison that turns its value into a decision.
The whole event condition rail: Target, Member, Subscription
Figure 6. The GameObject event rail ends at Subscription. Reads as chooses Check or Wait; the note states the chosen contract.
The event condition holds Running for the whole 1.5 second warm up, then WarmUpFinished arrives once and the cursor moves straight on to the next node.
The event condition holds Running for the whole 1.5 second warm up, then WarmUpFinished arrives once and the cursor moves straight on to the next node.

BeaconWarmUpLive.bqbehavior is the same five member nodes with one awaited action after them, so the cursor parks somewhere readable. Watch wait for the warm up hold its blue RUNNING pill for the whole one and a half second wind up, then the event arrives once and the cursor moves on to the message. The event card’s own SUCCESS lasts a single frame, because the message runs on that same tick, and only the active card carries a pill.

  1. Add member condition or event condition from the picker, under CONDITIONS.

  2. Finish Target and pick the member.

  3. For a member condition, open Comparison. Choose the Operator, then Constant or Blackboard for the compared value, then When true and When false.

  4. For an event condition, choose Reads as: Check or Wait on Subscription (GameObject) or Observation (entity). Check observes while the graph is enabled and returns a decision immediately. Wait subscribes only while active and responds once.

  5. When you choose Wait and the game cannot promise the event will ever fire, wrap the node in Time Limit.

Result

Success
The member comparison mapped to succeeded, an event Check received a firing, or an explicit Wait completed with succeeded.
Failure
The member comparison mapped to failed, an event Check was quiet, or an explicit Wait completed with failed.
Running
A member comparison maps to running, or an explicit event Wait has not fired. An event Check never runs.

Member condition

  • Any of the seven outcomes is selectable for either branch: succeeded, failed, running, interrupted, blocked, timeout, authority. A mapping whose every possible outcome is running is refused, because it can never finish.
  • Value types compare with <, ≤, =, ≠, ≥, >. Reference types use is and is not, and accept the empty reference as the compared value.
  • A struct compares with its own == operator when it declares one, and otherwise through the default equality comparer for that type.
  • A method-backed condition invokes once per evaluation, including when it has outputs, and maps the value it got back without calling a second time.
  • A void method with ref parameters is a legal member condition. The Tested value row names the ref parameter to compare, and the condition reads it, calls once, writes it back, then compares the value after the call. A void method with no ref parameter returns nothing to test, and the picker rules it out. Racing Line’s surge check works this way; arguments and results shows its card.
  • A method whose last parameter is params is a legal member condition with either form, Individual values or one Collection, and it still invokes once per evaluation. Platformer’s EnemyPatrolParams.bqbehavior asks RouteContainsWaypointsInOrder(params Transform[] waypoints) both ways, in individual waypoints match route and waypoint array matches route. Variable arguments walks that card.
  • An invocation or target failure is a fault, deliberately distinct from a comparison that came out false.
  • A member condition takes part in reactive interruption when the Selector above it is set to Lower priority. That Selector owns the opt-in. See interrupt.

Event condition: Check

  • Newly chosen events use Check. It returns failed while quiet, succeeded for one selected observation receiving a firing, then failed on the next quiet observation. Several firings before one observation still form one true decision, not a queued count.
  • It subscribes to C# events or supported UnityEvents while its graph is enabled, even when another branch is running. An ordinary Selector can take its fallback when the check is false; the check does not itself interrupt that running fallback.
  • Reset, disable, disposal, hosted-graph release, and receiver replacement remove the old subscription. A callback captured before reset or retarget cannot satisfy the new generation.
  • A subscription accessor that throws faults the graph with the member recorded. It is not a quiet false decision or a silently retried subscription.
  • On the entity path, an enabled-state edge or newly observed retained event-buffer entry supplies the same one-observation decision. A retained source rearms after the opposite state or entry absence is observed.

Event condition: Wait

  • Existing source without a mode stays Wait. Choosing Check does not discard the saved Wait completion choice, and switching back restores it.
  • A Wait subscription belongs to one activation. Starting subscribes; completion, interruption, timeout, reset, target loss, or leaving the state removes it. Concurrent waits on the same source keep independent subscriptions.
  • Each activation carries a generation stamp. Old captured callbacks cannot complete a later activation.
  • Firings are drained before the core tick, so waiting work completes on an update rather than midway through a walk.
  • On the entity path, When it fires chooses the completion and Until then is locked to running. Entity bindings covers enabled-state and event-buffer sources.
  • An event nobody raises is an indefinite wait. Use Time Limit to bound it.

Reuse a check in a state-machine transition

Section titled “Reuse a check in a state-machine transition”

Use the same member method, property, field, or event binding directly in a Transition’s ordered All or Any condition group. No Blackboard mirror or wrapper component is required. All stops at the first false check; Any stops at the first true check. Skipped conditions do not call gameplay methods or evaluate their argument projections.

A Transition’s member checks have fixed succeeded/failed outcomes, and its event checks use Check, not Wait. Gameplay members are sampled once when their group needs them during a host update; the normal transition handoff then takes effect on the next host call. A zero-delta update is still a new host observation.

When it goes wrong

SymptomCheckFix
The event never completes the node.Log the event once in your component to confirm the game raises it.Raise it, or bound the wait with Time Limit so the branch can move on.
The event fires but the node stays Running.Confirm the firing belongs to the current activation, not one from before a reset or an interrupt.Nothing to repair. A stale firing is ignored on purpose; the new activation gets the next one.
The condition is true in the Inspector and false in the graph.Read the compared value and the operator; a Blackboard operand may be stale or unset.Compare against the value you meant, and confirm the variable is written before this node runs.
The branch loops forever.An outcome maps to running, which polls.Map it to failed, or let the branch above it decide when to stop.
Your event is missing from the picker.Open the events group and confirm the event is public.Make it public, or expose a public wrapper event the graph can see.
You need the event payload.An event condition observes the occurrence, and arguments stay with your event.Store the payload in your component and read it with a property binding.
Full-size image