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

BitQuirky.Behavior.Diagnostics

Public behavior trees and state machines: runtime symbols in BitQuirky.Behavior.Diagnostics.

Source snapshot 29003d8b1658.

Assembly: BitQuirky.Behavior.Runtime

Category: Low-level runtime

C#
class BitQuirky.Behavior.Diagnostics.BehaviorDebugTickControl

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:38-278

Instance-owned per-follower debug pause / step state plus an explicit node-enter notification fan-out. Lives on the runtime that ticks behavior followers (Layer 3 FollowerBehaviorRuntimein this project) and is referenced fromBehaviorTickContextso the Layer 2 tick loop can honour pause without taking a Layer 3 dependency.

Responsibilities:

  • Track a per-follower paused flag and single-step credit.
  • Decide, given a follower id and a tick, whether the tick path should skip the follower (paused, no credit), tick it once (paused, one credit), or run normally, and report from that same decision whether the run spends the credit.
  • Fan-out node-enter events emitted from the high-detail / debug trace path so subscribers (the breakpoint service) can react.
  • Host-authoritative rule : only the host-owned runtime honours pause / step. Client views see paused state through their own read binding but do not mutate authoritative ticking.

Does NOT:

  • Maintain a static instance. The runtime that ticks the follower owns oneBehaviorDebugTickControlobject and publishes it throughBehaviorTickContext.
  • Talk to the editor directly. The editor uses an explicit IBehaviorGraphDebugControl adapter that forwards to this object.
  • Allocate per-tick in the steady state. The dictionary lookups are O(1) and we never enumerate the dictionary on the hot path.

C#
public void ClearFollower(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:170-183

Forget a follower’s pause/step state (called when the follower is despawned, or when the editor explicitly releases the binding).

C#
public void ConsumeStepCredit(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:155-163

Consume one step credit if any. Should be called by the tick path immediately after ticking a paused follower so the next frame returns to paused.

C#
public bool IsPaused(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:65-68

True when the follower is currently paused.

NotifyNodeEntered(int followerId, int nodeIndex)

Section titled “NotifyNodeEntered(int followerId, int nodeIndex)”
C#
public void NotifyNodeEntered(int followerId, int nodeIndex)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:224-233

Called by the high-detail / debug trace path when a node enter event is recorded. Safe to call when no subscribers exist (cheap O(1) dictionary miss).

C#
public void Pause(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:71-86

Pause this follower’s tick path.

C#
public void Resume(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:89-95

Resume this follower; clears any leftover step credit.

C#
public bool ShouldTickThisFrame(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:123-126

Returns true if the tick path should run the follower this frame. Paused followers without a step credit return false; paused followers with one credit return true (and the caller must consume the credit viaConsumeStepCredit after running). Unknown followers always tick normally.

ShouldTickThisFrame(int followerId, out bool consumesStepCredit)

Section titled “ShouldTickThisFrame(int followerId, out bool consumesStepCredit)”
C#
public bool ShouldTickThisFrame(int followerId, out bool consumesStepCredit)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:138-148

Resolves one follower’s whole tick decision from a single lookup: whether the tick path should run the follower this frame, and whether running it spends the follower’s one step credit. A normal tick path asks once per frame and calls ConsumeStepCreditafter the evaluation only when consumesStepCreditis true, so a stepped frame performs exactly one ordinary evaluation and the two readings can never disagree about which frame spent the credit.

C#
public void Step(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:103-114

Grant one step credit. Tick paths call ShouldTickThisFrame; if true, they consume the credit viaConsumeStepCreditso the next tick is paused again.

SubscribeNodeEntered(int followerId, Action<int> onNodeEntered)

Section titled “SubscribeNodeEntered(int followerId, Action<int> onNodeEntered)”
C#
public System.IDisposable SubscribeNodeEntered(int followerId, System.Action<int> onNodeEntered)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:196-217

Subscribe a callback to node-enter notifications for the specified follower. Disposing the returned object removes the callback. Implementations of IBehaviorGraphDebugControl forward their subscribe calls here.

Category: Low-level runtime

C#
class BitQuirky.Behavior.Diagnostics.BehaviorMemberFaultTrace

Source declaration: Packages/io.bitquirky.behavior/Runtime/Member/BehaviorMemberFault.cs:131-179

Managed companion trace for exceptional member failures whose actionable text cannot live in the Burst-safeBehaviorTracevalue. The owning GameObject agent exposes this bounded trace beside its always-on runtime trace.

Responsibilities:

  • Retain a bounded, allocation-free-after-construction sequence of structured member faults.
  • Let diagnostic consumers read and clear faults without reaching into the member runtime.

Does NOT:

  • Emit logs, grow after construction, or add managed references to the always-on trace.

C#
public int Count { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Member/BehaviorMemberFault.cs:144

Gets the number of retained faults.

C#
public int OverflowCount { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Member/BehaviorMemberFault.cs:147

Gets the number of faults dropped after the trace filled.

C#
public BehaviorMemberFaultTrace(int capacity)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Member/BehaviorMemberFault.cs:138-141

Creates one bounded managed fault trace.

C#
public BitQuirky.Behavior.Member.BehaviorMemberFault At(int index)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Member/BehaviorMemberFault.cs:150-157

Reads one retained fault by chronological index.

C#
public void Clear()

Source declaration: Packages/io.bitquirky.behavior/Runtime/Member/BehaviorMemberFault.cs:160-168

Clears retained faults after a diagnostic consumer has read them.

Category: Low-level runtime

C#
enum BitQuirky.Behavior.Diagnostics.BehaviorNodeExecutionStatus

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorNodeExecutionStatus.cs:23-44

Underlying type: byte

Compact latest-execution state retained for each baked behavior node.

Responsibilities:

  • Represent resting, running, successful, unsuccessful, canceled, deferred, and skipped execution in one byte.
  • Keep the zero value equivalent to a freshly allocated status vector.

Read-only Live presentation renames three of these values without changing them: a group atResting reads Waiting, Successreads Succeeded on a row and Complete on a lifecycle group, andFailurereads Failed. An individual resting row shows no result at all, so Live never invents one.

Does NOT:

  • Replace detailed result codes or retain a transition history.
  • Carry a distinct Waiting member. Waiting is howRestingpresents, so a freshly allocated status vector already means “has not started”.

C#
Canceled = 4

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorNodeExecutionStatus.cs:37

Running work stopped exactly once at a cancellation boundary.

C#
Deferred = 5

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorNodeExecutionStatus.cs:40

Lifecycle work chosen for a later update and not yet evaluated.

C#
Failure = 3

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorNodeExecutionStatus.cs:34

Live reads Failed.

C#
Resting = 0

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorNodeExecutionStatus.cs:26

Never started, or cleared for a new activation. Live reads Waiting.

C#
Running = 1

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorNodeExecutionStatus.cs:28

Work is in flight this activation. Live reads Running.

C#
Skipped = 6

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorNodeExecutionStatus.cs:43

An ordered lifecycle row the sole Exit evaluation never reached.

C#
Success = 2

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorNodeExecutionStatus.cs:31

Live reads Succeeded on a row and Complete on a lifecycle group.

Category: Low-level runtime

C#
struct BitQuirky.Behavior.Diagnostics.BehaviorUtilityBranchScore

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorUtilityBranchScore.cs:22-50

One Utility Selector branch’s latest computed score, whether it is the branch currently running this tick, and the selector’s retained commitment. Entities-independent so the shared tick core (which never references Unity.Entities) can read and write it directly; the entity buffer elementBehaviorRuntimeUtilityBranchScoreshares this exact field layout so a batched tick can reinterpret itsDynamicBufferas this type with no copy.

Responsibilities:

  • Store one row per bakedBakedUtilityBranch, recomputed every tick the owning Utility Selector is active, indexed exactly like the baked branch table.

Does NOT:

  • Decide selection: the runtime scan (UtilitySelector) reads this array, it does not own it.

C#
public bool HasEvaluated

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorUtilityBranchScore.cs:49

Whether the owning selector has ever evaluated for this agent. False forever for an agent whose tree never reaches this selector (a shared graph’s profile-gated branch), distinguishing a genuinely never-evaluated row from one real evaluation already scored at exactly zero.

C#
public bool IsActive

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorUtilityBranchScore.cs:33

Whether this branch’s child is the one the selector is resuming this exact tick (the finish_first/interrupt reactive-comparison gate’s own per-tick fact). Cleared the instant that child finishes, even within the same tick a brand-new branch is chosen; useIsCommittedfor a retained “which tactic is active” reading.

C#
public bool IsCommitted

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorUtilityBranchScore.cs:41

Whether this is the branch the selector last committed to. Set the instant a branch is chosen and held across ticks, including across the same tick’s instant child completion; cleared only when the selector next evaluates and selects a different branch, evaluates and selects none, or the runtime resets.

C#
public float Score

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorUtilityBranchScore.cs:25

The branch’s current score, recomputed every tick the owning selector is active.

Source fingerprint: sha256:29003d8b1658b98a79bebcd93e3b4030caf8511268b96817ab764d63df8d6c3b

Full-size image