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

Entity debugging

Watch one enemy out of a horde decide, in the same window, with the honest limits the entity host imposes.

Select one entity out of hundreds and its graph opens, drawn in the same status colors as a GameObject agent. Member cards stay observe-only; the graph’s own explicit shared value edits in place here through its SHARED card, and so does every graph-held row in the rail’s Live values section.

Horde Survival’s enemies are entities, and one of them is not chasing. There is no GameObject to click, no component to inspect, and no console line that says which branch that particular enemy took. Pausing the whole simulation to find out changes the thing you are trying to observe.

HordeEnemy.bqbehavior runs on every matching entity. Live attaches to exactly one of them, from Unity’s own entity selection, while the other enemies keep running at full speed.

A selected Pursuit Repeat reports its Until success progress in read-only Live while the enemy closes on the keeper.
A selected Pursuit Repeat reports its Until success progress in read-only Live while the enemy closes on the keeper.
  1. Press Play and let the run reach the point you care about.

  2. In Unity’s Hierarchy, under the live World, select the entity row. Entity selection belongs to Unity: clicking a rendered object in the Scene view does not select a pure entity, and the package creates no proxy GameObjects.

  3. Read the toolbar. It shows the entity identity, a Read-only badge, and BOUND while the entity is alive.

The Live rail for one Horde Survival entity, with its entity binding rows above the read-only blackboard readings
Figure 1. The rail for one enemy while the rest of the horde runs. It names the World, the entity index and version, and the graph instance, and the panel under it holds that entity’s own readings.
  • The full canvas with the same status words, including the amber unresolved-target reading, which the entity path publishes exactly like the GameObject path.
  • The rail’s runtime status, pending requests, selected node details, and the read-only blackboard snapshot for that entity.
  • A stable identity: World sequence plus entity index and version. An index reused with a new version is a different entity and needs selecting again.
  • The deepest evaluated node gets the running glow. Every other node that reported a result keeps its own status pill.
  • A toolbar that states the boundary: a Read-only lock chip beside Bindings valid, with the entity id and the tick rate.
  • A Utility scores rail section for any entity whose Utility Selector has evaluated at least once: every evaluated branch’s current score in authored order, labeled with its own authored name, and the branch the selector last chose, marked chosen (or running while that branch is still executing). Horde Survival’s HordeEnemy.bqbehavior carries one such selector on its Brute enemies (see brutes choose a tactic), so attaching to a live Brute shows its current Rush, Flank, and Retreat scores, and its chosen tactic, change as its real health, proximity, and nearby ally count change. A live non-Brute runs the same shared graph but never reaches that selector, so its section stays absent rather than showing three scores it never computed.

The live rail above shows only the one entity you selected, and only while it stays selected. A Utility Selector’s committed branch is also traceable independently of that rail, and independently of whether any debugger window is open. On the exact tick a Utility Selector’s committed branch changes, both the GameObject and entity hosts retain one BehaviorUtilityTraceEntry on that agent’s BehaviorRuntimeInstance.LastUtilityTrace field, carrying the previous branch’s source order (or none, before any selection), the new branch’s source order, every branch’s current score in source order from that same tick, and the tick’s frame number. Nothing is written on a tick where the committed branch stays the same, so no per-tick log is ever produced. Read it directly from the live runtime instance: a GameObject agent exposes it as agent.GetRuntime().RuntimeInstance.LastUtilityTrace; a pure entity exposes the same field through EntityManager.GetComponentData<BehaviorRuntimeInstance>(entity).LastUtilityTrace. The package never names the branches; Horde Survival maps source order 0/1/2 to Rush, Flank, and Retreat for its own presentation. For a horde-scale view instead of one agent, enemy.tactics reports each tactic’s live running count and score range across every Brute (docs/commands.md).

GetRuntime() is in BitQuirky.Behavior.GameObject. Native implementation consumers add BitQuirky.Behavior.Runtime.Backend to their assembly references; the serialized BehaviorAgent component remains in BitQuirky.Behavior.Runtime.

Capability GameObject host Entity host
Per-agent pause and step Yes, that follower alone No. The controls mirror Unity’s global Play mode
Breakpoints Yes, stored per graph and node id No. The menu item exists and nothing can pause
Editing a live value A two-way member card’s Current row, plus the rail’s Live values rows No member card, but the graph’s own SHARED card and every Live values row edit in place on both hosts
Watched values Empty in this release Empty in this release

The reason is structural: the entity document is opened without per-entity execution authority, so its pause and step controls retune to Unity’s globals, reading Pause / resume Unity Play mode: Space. and Advance one Unity frame: . In a simulation with hundreds of agents that is the honest boundary. One entity’s schedule belongs to your systems, and the editor does not reach into the job to hold a single entity still.

A destroyed entity keeps its identity and its authored graph in the window, clears the facts that would otherwise look current, and displays Selected entity no longer exists. The focus control in the rail says the same thing: Focus → (entity destroyed).

Debug an entity graph without per-agent control

Section titled “Debug an entity graph without per-agent control”
  • Pause Unity globally and step frames. The whole World advances a frame at a time, and your one entity advances with it.
  • Read the amber target readings. They are published for entity targets too, with entity-specific reasons like a destroyed handle, a missing component, or a singleton count that moved.
  • Narrow the problem with a smaller query: a benchmark or test scene with a handful of entities makes a single decision readable.
  • Move a decision that genuinely needs breakpoints onto a GameObject agent for the length of the investigation. Graph semantics are identical on both hosts, so the same shape behaves the same way.

When it goes wrong

SymptomCheckFix
Selecting the enemy in the Scene view opens nothing.Confirm you selected the entity row in the Hierarchy under the live World.Select the entity itself. Rendered objects are not entity selection.
The window stays on Static.Confirm Play Mode is running and the entity attached to a registered graph.Check the query in the system that registered the graph.
Space pauses the whole game.That is the entity behavior: the controls mirror Unity globals.Use frame stepping, or reproduce on a GameObject agent for per-agent control.
A Current row will not edit.The entity binding exposes no live member editing, except the graph’s own SHARED card.Change the authored default in Static, or write the component from your own system.
A breakpoint on this card does nothing.Entity documents have no per-agent execution control.Nothing to repair here; use global pause and step.
The view says the entity no longer exists.The entity was destroyed, or its index was reused with a new version.Select a live entity again. The old identity is deliberately not reused.
Full-size image