Entity debugging
Watch one enemy out of a horde decide, in the same window, with the honest limits the entity host imposes.
On this page
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.
The problem
Section titled “The problem”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.
See it
Section titled “See it”
Attach to one entity
Section titled “Attach to one entity”-
Press Play and let the run reach the point you care about.
-
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.
-
Read the toolbar. It shows the entity identity, a Read-only badge, and BOUND while the entity is alive.

What the entity view offers
Section titled “What the entity view offers”- 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.bqbehaviorcarries 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.
Structured tracing on tactic change
Section titled “Structured tracing on tactic change”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.
What it deliberately does not offer
Section titled “What it deliberately does not offer”| 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
| Symptom | Check | Fix |
|---|---|---|
| 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. |
- Entity agents: the host that schedules this graph.
- Entity variables: what the rail is showing you.
- Faults: reading a failure that is not an ordinary refusal.
- Weigh it up: the Utility Selector node that produces the scores in the rail above.
- Horde Survival: brutes choose a tactic: the Brute’s three tactics staged and compared side by side.
- Performance: the measured cost of running that extra scored branch at scale.