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

Horde Survival’s enemies are entities, and the graph that decides for them ticks in Burst jobs of its own, scheduled beside your simulation’s systems: it reads and writes your component fields where they live.

Horde Survival’s enemies are entities. Their health, attack cooldown, and movement intent are IComponentData, and their systems run in jobs. A graph that wanted a MonoBehaviour in the middle would undo the reason that data is in components.

HordeEnemy.bqbehavior binds the components directly. ContactAttack.CooldownRemaining and ContactAttack.RadiusSq are field reads. AttackIntent.Ready is a two-way bool. MovementIntent.Mode and TargetPosition are writes the movement system consumes. DeadFade is watched through its enabled state, SurvivorTarget is read as a singleton, and the distance itself comes from Unity.Mathematics.math.distancesq, called as a static member.

  • The decision inputs are already component fields, and you want the graph reading them where they live.
  • One shared entity holds the answer for everybody, which is what a singleton target is for.
  • The math you need is a public static function, in your code or in Unity.Mathematics.
The Horde enemy graph attached Live to one running entity, with the entity binding rows in the rail
Figure 1. The graph ticks in a job and the editor still follows one entity: this World instance, this entity index and version, this graph instance.
  1. Set the graph’s Runtime path to Entity. The Target card’s Mode control changes to the entity modes.

  2. Choose the mode: Self for the entity this graph instance runs on, Handle for exactly one hop to another entity, Singleton for the one entity carrying a component, Static for a declaring type with no entity at all, or Asset for a declared event channel. The three cards below are HordeEnemy.bqbehavior’s own.

  3. Pick the member. A component offers its fields, its direct properties, and its enabled state; a static type offers its static methods and fields.

  4. Set the direction or the result as usual, and read Validation.

  5. Reimport the graph file so the consumer assembly regenerates its binding set, then let Unity compile.

  6. Register the graph with the generated binding set and its scheduler together, then run an entity carrying the components you bound.

The entity Target card with Mode Self and Component ContactAttack, with the help line This graph’s own entity; the component is read from it
Figure 2. Cooldown Ready reads ContactAttack.CooldownRemaining off the enemy itself. Self has one row, Component, because there is nothing to look up.
The entity Target card with Mode Singleton and Component SurvivorTarget, plus an In the world row tagged RESOLVED
Figure 3. Read Current Survivor reads the survivor entity through Singleton. The In the world row states the contract: exactly one entity carries this component, and zero or several is a failure on that evaluation, never a guess.
The entity Target card with Mode Static and Type math from Unity.Mathematics
Figure 4. Distance Squared calls math.distancesq through Static: the declaring type alone, on the same card the GameObject path shows.

Handle adds a Read from control with two choices: Blackboard, which reads a surfaced entity value, or Field on self, which reads an Entity field off one of this entity’s own components. Either way the entry names one entity and the Component row names what to read on it. One hop, never a chain.

Target Resolves to
Self The entity that owns this graph instance
Handle Exactly one Entity hop, from a surfaced entity variable or an entity-typed field on Self
Singleton The one entity carrying the chosen component, with exactly one required
Static The static declaring type, with no entity lookup
Asset The channel declared by GUID, baked to an unmanaged identity and registered once per graph in this World

A handle takes one hop and never chains from another handle. A destroyed handle, a missing component, the wrong singleton cardinality, or a missing buffer entry fails that one evaluation and performs no access, so a stale entity index is never read.

Container Available Refused
Component Field, direct property, enabled state, member condition on those Method and message, because a component has no call site
Buffer element Field on one addressed entry Property, method, message
Static type Method, message, field Property
Managed component Nothing Everything, for lack of entity storage
Declared asset Message raise and Event Condition listen through the event library’s integration Direct managed invocation or subscription inside the entity tick

An ordinary entity event condition observes an enableable component’s state or one retained event-buffer entry. It cannot subscribe to a C# event or UnityEvent inside a job. A declared Asset target uses the separate shared-generation transport described below.

A static method’s parameters pass by value or by ref. A ref parameter gets the same Read-write parameters row the GameObject path shows, with the same read-before, write-after rule, including on a void method bound as a member condition. An out, in, or params parameter is refused, and the refusal names that modifier.

A coroutine or awaitable result is refused too, with the reason stated plainly: waiting on a call needs a managed continuation this path does not have. When a member is unavailable the strip reads no entity call site and validation tags it, offering two ways out: pick another member, or run this graph on the GameObject path.

Choose an entry that already exists, By index with a non-negative constant, or By field with one exact identity field and the value to match. The accessor never adds, removes, resizes, or reorders the buffer, and an out-of-range index, no match, or several matches fails that evaluation without touching anything.

Result

Success
The access or the static call completed and its mapped outcome was succeeded.
Failure
The mapped outcome was failed, or a live target failure ended that evaluation.
Running
An authored outcome maps to running, or an explicit event Wait has not observed its occurrence. Event Check never runs.
  • Carried values are exact: bool, the signed and unsigned integrals, char, float, double, enums with those underlyings, float2, float3, float4, plus the entity handle and request identifier storage. Every one fits in sixteen bytes.
  • Conversions are the ordinary accepted set narrowed to those kinds, with reference assignability dropped. Registered converters apply to surfaced field/property/indexed reads as well as explicit stored results, and to an indexed setter’s value. Index arguments themselves keep their exact declared types; converting the value does not convert the index.
  • Generated access is a struct the job can carry: typed component and buffer handles, typed lookups, and a table of access rows recording read-only or read-write intent per component. Nothing about it is a managed reference.
  • Native member calls run inside the tick, on the job thread, through a constrained generic call, and complete in that evaluation. Results are copied into the surfaced blackboard slot as bytes, and ref values commit before the result is chosen. A declared-asset raise queues a request instead; it does not invoke a managed channel inside the tick.
  • Reads that feed the blackboard sample before the core tick and writes push after it, as extra stages of the same Burst carrier.
  • Native event Reads as: Check reports succeeded for one observation receiving a newly observed occurrence, failed while quiet, then failed on the next quiet observation. Wait reports running until that occurrence, consumes it once, and reports the authored result. Both rearm after a tick sees the opposite state or the buffer entry gone. Newly chosen events use Check; existing source without a mode keeps Wait. A declared-asset listen reads shared generations without that per-agent latch.

When it goes wrong

SymptomCheckFix
Your component method is missing from the picker.Read the refusal: a component has no entity call site for a method.Move the logic into a public static function and bind that, or keep the data in fields the graph reads.
An event you rely on cannot be bound.An entity job cannot subscribe directly to a managed C# event.For an integrated channel, choose a declared Asset target. For native ECS data, observe an enableable component or a retained event buffer entry.
The graph refuses to register at runtime.A binding set without its scheduler, or the reverse, is rejected.Supply the generated pair together, from the generated factory.
Validation reports the singleton cardinality.Zero or several entities carry that component.Make it genuinely single, or bind through Self or a Handle.
A buffer read fails on some entities.The addressed entry has to exist already.Have your producer retain the entry with a stable identity field, then address it by field.
The build fails on a stale generated binding set.The compiled fingerprint differs from the expected one.Reimport the graph file and let the consumer assembly recompile. A player build never generates it for the first time.

Your event channel is a Unity asset, but an entity job cannot call that managed asset or subscribe a delegate to it. Putting a MonoBehaviour on every listener would add the managed work the entity path avoids.

Use a declared Asset target when an event library supplies an integration with the package’s World-scoped event transport. The package owns requests and observations; the event library owns calling its real channel. A Core event uses the same declared asset on both runtime paths through that shared integration.

The Asset field names the actual chosen channel on both paths. A Message raise and an Event Condition listen share this authored target:

Plain text
%% member-target node="alarm" binding="alarm_channel" mode="asset" asset="asset(<channel-guid>, \"AlarmRaised\")" assembly="<event-assembly>" type="<event-type>"

The GUID identifies your channel; the saved name keeps the text readable. Use your actual channel and its assembly/type rather than the illustrative values above.

  1. Choose Asset in the step’s Mode row, then choose the event channel in Asset. The Event Condition uses that channel’s event notification; the Message uses its unparameterized raise member.
  2. Keep the target record unchanged when switching the graph between GameObject and Entity. Reimport and supply the regenerated entity binding set and scheduler together as usual.
  3. Use your event library’s integration in the same World. Registration supplies its resolved channel automatically; no separate event catalog or per-agent subscription is needed.

A raising tick adds one pending id per distinct declared channel, even when many agents raise it. A listen step returns its authored result when its shared generation is ahead of its own registration’s boundary, and Running otherwise. No entity stores or writes a private generation, pending bit, previous-match bit or disarm bit for this source.

For a Core channel, all listening agents in one registration report the raise once on their next scheduled tick. A raise before their tick in frame N and a raise after that tick both stay invisible in frame N. Their first scheduled tick in frame N+1 or later reports the authored result; later ticks return Running without another raise. A less frequently scheduled registration still gets its own observation, even after another registration has consumed the same generation.

Schedule one listening registration less often than another. Its next tick still sees a newer generation: another runtime or registration cannot advance its boundary. Multiple raises before that tick coalesce into one observed difference.

  • Each World owns its requests, external touches, generations, armed boundaries and waiting registrations. Distinct runtime owners in that World have distinct registration identities.
  • A new listener starts unarmed and records its registration frame. A fold in that same frame leaves it unarmed. At the first later frame’s fold, external touches are incorporated before its boundary is initialized to the current generation. Raises before or after registration in the registration frame are therefore excluded, regardless of fold ordering.
  • Each completed TickGraph or TickAll registration advances only its own armed boundaries. Skipping its tick leaves its catch-up state untouched.
  • The comparison is signed serial-number arithmetic over uint: a wrapped generation just ahead of its boundary is newer. Keep the distance below half the serial range.
  • Queuing is not delivery. An event-library drain can invoke the real channel later in the same frame at the earliest; listening agents observe the generation on their own next scheduled tick, never in the raising tick. The package transport alone never calls a Core event.

Bit Quirky Core supplies the optional BitQuirky.Core.Entities assembly. It compiles only when the hosting project already carries both com.unity.entities (6.5.0 or later) and io.bitquirky.behavior. A project missing either dependency has no integration assembly in its build. Behavior Trees and State Machines itself never references Core.

Choose a Core GameEvent asset and its parameterless Raise() for a Message, or GameEventBase.EventRaised for an Event Condition. Typed Core channels can be observed through that untyped base notification too; the bridge does not invent a payload or a parameterless raise for GenericEvent<T>.

Moving between bindings leaves every authored listen-step record byte-identical; only the graph’s runtime-path header changes. The GameObject path uses its generated provider’s real event subscription, while the entity path uses the Core bridge. Both wait with Running before the notification. Their eligible tick reports the same authored Succeeded or Failed result; the following tick returns Running without another notification. Entity requests reach the managed channel through the later drain.

Graph registration supplies the bake-resolved channel to a World-owned registry. The Core integration checks it synchronously and subscribes once when its first raising or listening registration arrives. The subscription remains until the final registration for that channel leaves, so a raise-only channel still records whether delivery actually happened. Entries registered before the integration system exists are replayed during its creation. World disposal releases every remaining subscription. No game startup catalog, global event lookup or per-agent MonoBehaviour is required.

The registry supplies the complete baked asset GUID alongside that resolved channel. Core captures that identity in its notification callback rather than computing another id. Two distinct assets named AlarmRaised in different folders can register simultaneously: raising either notifies only its own entity and GameObject listening graphs. Display names do not identify channels, and renaming a channel does not change its route.

The drain runs in LateSimulationSystemGroup, after ordinary simulation tick systems. It invokes GameEvent.Raise() once per distinct requested channel, even when many entities request it. Only actual EventRaised notifications advance a generation: a disabled channel delivers nothing and produces no graph observation. Inspector-wired chains such as A raising B (and B raising C) are recorded too. All notifications for one channel in the drain coalesce into one generation increment, including a channel both requested directly and reached through a chain. Bookkeeping never raises the channel again. A notification after that drain is folded at the next initialization pass, before listening ticks. The drain never arms a listener or advances a registration’s catch-up boundary.

The entity tick adds no managed allocation. Acceptance measurements include both raising and listening ticks: with one agent and with 256 agents per graph, the raising frame adds zero managed bytes beyond a separately measured direct GameEvent.Raise() baseline. The observation frame and a separate idle frame each add zero. The real bridge also coalesces 128 raising agents into one Core notification, shared by 96 listeners across two separately scheduled registrations. One integration subscription serves the channel regardless of agent count. Declared channels need no per-agent occurrence-state component. These measurements establish the allocation and managed-work guarantees; delivering an event still consumes CPU time.

Channel resolution and subscription finish during registration, before measured raising frames. The Core-aware acceptance tests run in Core’s test assembly with real GameEvent assets and the actual bridge; the package’s own conformance tests remain event-library independent. Dungeon Heist has no entity-bound agents. This capability is proven only by package and Core EditMode tests.

A missing or deleted channel fails the bake for both a Message raise and an Event Condition listen. The failed load retains the graph’s source key; its error identifies the step and binding on a positive source line and says the declared channel is missing or invalid. An unresolved identity also names its GUID. Distinct GUIDs register independently even when the assets have identical names. An event-library integration can reject an incompatible channel synchronously at registration. Rechoose the intended channel and reimport rather than adding a runtime lookup.

Read Asset targets for the shared authoring field and Entity runtime for registration and scheduling.

Full-size image