BitQuirky.Behavior.Diagnostics

Assembly: BitQuirky.Behavior.Runtime

BehaviorDebugTickControl

Category: Low-level runtime

C#

class BitQuirky.Behavior.Diagnostics.BehaviorDebugTickControl

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:55-295

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.

Members

ClearFollower(int followerId)

C#

public void ClearFollower(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:187-200

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

ConsumeStepCredit(int followerId)

C#

public void ConsumeStepCredit(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:172-180

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.

IsPaused(int followerId)

C#

public bool IsPaused(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:82-85

True when the follower is currently paused.

NotifyNodeEntered(int followerId, int nodeIndex)

C#

public void NotifyNodeEntered(int followerId, int nodeIndex)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:241-250

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).

Pause(int followerId)

C#

public void Pause(int followerId)

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

Pause this follower’s tick path.

Resume(int followerId)

C#

public void Resume(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:106-112

Resume this follower; clears any leftover step credit.

ShouldTickThisFrame(int followerId)

C#

public bool ShouldTickThisFrame(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:140-143

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)

C#

public bool ShouldTickThisFrame(int followerId, out bool consumesStepCredit)

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

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.

Step(int followerId)

C#

public void Step(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:120-131

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)

C#

public System.IDisposable SubscribeNodeEntered(int followerId, System.Action<int> onNodeEntered)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorDebugTickControl.cs:213-234

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.

BehaviorMemberFaultTrace

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.

Members

Count

C#

public int Count { get; }

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

Gets the number of retained faults.

OverflowCount

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.

BehaviorMemberFaultTrace(int capacity)

C#

public BehaviorMemberFaultTrace(int capacity)

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

Creates one bounded managed fault trace.

At(int index)

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.

Clear()

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.

BehaviorNodeExecutionStatus

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”.

Members

Canceled

C#

Canceled = 4

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

Running work stopped exactly once at a cancellation boundary.

Deferred

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.

Failure

C#

Failure = 3

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

Live reads Failed.

Resting

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.

Running

C#

Running = 1

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

Work is in flight this activation. Live reads Running.

Skipped

C#

Skipped = 6

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

An ordered lifecycle row the sole Exit evaluation never reached.

Success

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.

BehaviorTrace

Category: Low-level runtime

C#

struct BitQuirky.Behavior.Diagnostics.BehaviorTrace

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:96-464

Always-on Behavior Trace for a single follower. Bounded, Burst-friendly per-follower struct carrying eleven core 32-bit fields per data-model.md §Behavior Trace (always-on tier): active-node-id, current-state-id, last-transition-id, last-transition-cause-id, last-result-code, pending-path-request-id, pending-animation-request-id, authority-context-id, selected-probability-child-index, last-evaluated-transition-predicate-id, and last-evaluated-transition-right-field-id.

Responsibilities:

• Carry the bounded POD trace fields the diagnostic surface (follower.status, follower.behavior-report, follower.behavior-graph) projects out of the running graph.
• Provide a Burst-callable projection from BehaviorRuntimeInstance+ a BehaviorTraceServiceBindingsbinding so callers can produce a trace snapshot from native data without touching the full runtime-instance layout.
• Stay native: the struct itself contains no managed references and is sized so it can be returned by value across Burst boundaries.

Does NOT:

• Allocate per-follower buffers - the trace is a snapshot; the storage lives onBehaviorRuntimeInstance.
• Lift to managed eagerly. R-11 mandates “lifted to managed only on demand”: the projection is run by the consumer when it actually needs to format a string or update a debugger view.
• Carry the high-detail ring buffer - that lives in BehaviorTraceHighDetailRingand is opt-in by id.

Members

Authority

C#

public BitQuirky.Behavior.Baked.BakedAuthorityContext Authority { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:205-209

AuthorityContextIdas the strongly-typed enum.

Empty

C#

public static BitQuirky.Behavior.Diagnostics.BehaviorTrace Empty { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:215-241

All-zero / all-NoValue trace. Returned when no runtime instance is bound (e.g. follower has not spawned).

FinalResult

C#

public BitQuirky.Behavior.Execution.BehaviorMachineResult FinalResult { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:196-200

MachineResult as the strongly typed final result.

ResultCode

C#

public BitQuirky.Behavior.Execution.BehaviorResultCode ResultCode { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:189-193

LastResultCodeas the strongly-typed enum.

this[int fieldIndex]

C#

public int this[int fieldIndex] { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:248-282

Read the trace’sFieldCountints by index. Used by marshalling code that wants to copy the trace into a fixed-size buffer without committing to the field layout.

ActiveMachineIndex

C#

public int ActiveMachineIndex

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:172

Current composed machine row; zero names the authoring host.

ActiveNodeIndex

C#

public int ActiveNodeIndex

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:117

Active baked-node index when the snapshot was taken, or NoValue when the follower has no node scheduled (just spawned, or just transitioned without an entry tick).

ActiveStateMachineCandidateIndex

C#

public int ActiveStateMachineCandidateIndex

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:170

Active candidate node, or NoValue while parked/outside.

ActiveStateMachineReferenceIndex

C#

public int ActiveStateMachineReferenceIndex

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:168

Active Referenced State Machine node, or NoValue.

AuthorityContextId

C#

public int AuthorityContextId

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:131

Authority the follower’s instance was attached under, as an int; Authority returns the typed value and Unknown means unattached.

CurrentStateIndex

C#

public int CurrentStateIndex

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:119

Baked-node index of the active top-level statechart state, or NoValue when none is active.

FieldCount

C#

public const int FieldCount = 24

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:104

Number of int-sized fields on the trace. Used to dimension fixed-size buffers in marshalling code.

HostedCompletedCycleCount

C#

public int HostedCompletedCycleCount

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:152

Terminal hosted cycles completed since the active state was entered.

HostedLifetime

C#

public int HostedLifetime

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:149

Baked lifetime of the active state-hosted behavior tree.

HostedResultCode

C#

public int HostedResultCode

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:161

Terminal result of the latest hosted cycle.

HostedResultEventId

C#

public int HostedResultEventId

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:158

Pending or last emitted hosted result-event id, or 0 when the latest terminal hosted outcome had no configured event.

HostedResultTick

C#

public int HostedResultTick

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:180

Input tick that produced the held hosted result, or NoValue.

LastEvaluatedTransitionPredicateId

C#

public int LastEvaluatedTransitionPredicateId

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:135

Stable hash of the graph field the most recently evaluated transition predicate read as its left operand, or NoValue when no predicate group has been evaluated. LastEvaluatedTransitionRightFieldId names the other operand.

LastEvaluatedTransitionRightFieldId

C#

public int LastEvaluatedTransitionRightFieldId

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:146

Stable hash of the graph value the last evaluated transition predicate compared against, orNoValuewhen that predicate used its baked constant or no predicate has been evaluated. Pair it with LastEvaluatedTransitionPredicateIdto distinguish those cases and name both operands of a deciding comparison. Resolve it with ResolveTransitionCauseSourceId, which reads the same authored field-name table.

LastResultCode

C#

public int LastResultCode

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:125

Result of the follower’s most recent step as an int, None before its first tick; ResultCode returns the typed value.

LastTransitionCauseId

C#

public int LastTransitionCauseId

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:123

What satisfied that transition: the stable hash of the deciding graph field for a condition-group edge, otherwise the baked node index of the edge’s condition node. Turn the field form back into a name with ResolveTransitionCauseSourceId.

LastTransitionId

C#

public int LastTransitionId

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:121

Interned string index of the most recently fired transition’s authored id, or NoValue before any transition fires.

MachineFinished

C#

public int MachineFinished

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:166

One when the machine has stopped, including a no-result empty Return.

MachineResult

C#

public int MachineResult

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:164

Explicit final state-machine result, or None while execution remains active.

NestedMachinePhase

C#

public int NestedMachinePhase

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:174

Current nested machine lifecycle phase.

NestedMachineResult

C#

public int NestedMachineResult

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:176

Last nested machine result.

NoValue

C#

public const int NoValue = -1

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:110

PendingAnimationRequestId

C#

public int PendingAnimationRequestId

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:129

Pending command id of the request outstanding on the bound animation service, or NoValue when nothing is outstanding and when no animation service is bound.

PendingPathRequestId

C#

public int PendingPathRequestId

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:127

Pending command id of the request outstanding on the bound path service, or NoValue when nothing is outstanding and when no path service is bound.

SelectedProbabilityChildIndex

C#

public int SelectedProbabilityChildIndex

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:133

Baked node index the active Probability Selector last drew, NoValue before a draw or after reset, or -2 when the selector drew its optional Direct failure outcome and ended the pass without ticking a child.

SuspensionDepth

C#

public int SuspensionDepth

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:178

Current Push suspension depth.

Equals(in BehaviorTrace other)

C#

public bool Equals(in BitQuirky.Behavior.Diagnostics.BehaviorTrace other)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:388-414

Compares every trace field, so two snapshots differ only when something a debugger would draw has changed. Cheaper than repainting on every tick.

Equals(object obj)

C#

public override bool Equals(object obj)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:420

Boxing equality; forwards toEqualswhen objis a trace and returns false for anything else.

FromInstance(in BehaviorRuntimeInstance instance)

C#

public static BitQuirky.Behavior.Diagnostics.BehaviorTrace FromInstance(in BitQuirky.Behavior.Execution.BehaviorRuntimeInstance instance)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:350-351

Convenience overload that runs the projection with no pending- service bindings - all pending fields report NoValue. Used by tests + quick-look diagnostics.

FromInstance(in BehaviorRuntimeInstance instance, BehaviorTraceServiceBindings bindings)

C#

public static BitQuirky.Behavior.Diagnostics.BehaviorTrace FromInstance(in BitQuirky.Behavior.Execution.BehaviorRuntimeInstance instance, BitQuirky.Behavior.Diagnostics.BehaviorTraceServiceBindings bindings)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:293-343

Project a runtime instance + service bindings into the always-on trace shape. Pure: no mutation, no allocation. Burst-callable because every operation is a field read or a switch on a byte.

GetHashCode()

C#

public override int GetHashCode()

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:426-456

Hash over allFieldCounttrace fields, consistent with Equals.

ResolveTransitionCauseSourceId(BakedBehaviorArtifact artifact, int stableCauseId)

C#

public static string ResolveTransitionCauseSourceId(BitQuirky.Behavior.Baked.BakedBehaviorArtifact artifact, int stableCauseId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:356-378

Resolves a stable transition-cause field ID to its authored source field ID.

op_Equality(in BehaviorTrace a, in BehaviorTrace b)

C#

public static bool operator ==(in BitQuirky.Behavior.Diagnostics.BehaviorTrace a, in BitQuirky.Behavior.Diagnostics.BehaviorTrace b)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:459

Field-by-field equality, identical to Equals.

op_Inequality(in BehaviorTrace a, in BehaviorTrace b)

C#

public static bool operator !=(in BitQuirky.Behavior.Diagnostics.BehaviorTrace a, in BitQuirky.Behavior.Diagnostics.BehaviorTrace b)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:461

True when any trace field differs between the two snapshots.

BehaviorTraceHighDetailEntry

Category: Low-level runtime

C#

struct BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailEntry

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:89-127

One row in the high-detail ring buffer. Per data-model.md §Behavior Trace (high-detail tier)each entry is a(timestamp, node-id, kind, payload-id)tuple.

The struct stays POD so the ring is layout-stable across editor / dev player builds and so the entry can be appended without managed allocation when the recording path is hot.

Members

Kind

C#

public BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailKind Kind

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:107

What this row records; it also selects how PayloadId is interpreted.

NodeIndex

C#

public int NodeIndex

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:104

Baked-node index this entry refers to, or -1 when the entry is not node-scoped (e.g.AuthorityHandoff at instance scope).

PayloadId

C#

public int PayloadId

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:126

Kind-specific payload id. Conventions:

• NodeEntered / NodeExited: parent-node-index (or -1).
• TickStarted / TickCompleted: BehaviorResultCode as int.
• TransitionFired: transition id (interned index).
• ExternalCommandIssued / Completed / Refused: pending-id.
• AuthorityHandoff: new-authority value cast to int.
• BlackboardWrite / Read: field-name interned index.
• ResultRecorded: BehaviorResultCode as int.
• SubgraphPushed / Popped: subgraph reference index.

Reserved0

C#

public byte Reserved0

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:109

Explicit padding that keeps the row layout stable across editor and dev-player builds; it carries no meaning.

Reserved1

C#

public ushort Reserved1

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:111

Explicit padding that keeps the row layout stable across editor and dev-player builds; it carries no meaning.

TimestampSeconds

C#

public double TimestampSeconds

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:97

Wall-clock timestamp in seconds since some epoch the recorder chose at activation time (typically Unity’s Time.realtimeSinceStartupAsDouble). Monotonic within a single activation - safe to subtract for deltas.

BehaviorTraceHighDetailKind

Category: Low-level runtime

C#

enum BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailKind

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:32-78

Underlying type: byte

What a high-detail trace entry describes. Numeric values are stable so the editor debugger and any future trace dump format can decode archived traces consistently.

Members

AuthorityHandoff

C#

AuthorityHandoff = 9

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:62

Authority over the instance moved between roles.

BlackboardRead

C#

BlackboardRead = 11

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:68

A blackboard slot was read.

BlackboardWrite

C#

BlackboardWrite = 10

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:65

A blackboard slot was written.

ExternalCommandCompleted

C#

ExternalCommandCompleted = 7

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:56

A posted external-service command came back with a completion record.

ExternalCommandIssued

C#

ExternalCommandIssued = 6

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:53

An external-service command was posted to the command queue.

ExternalCommandRefused

C#

ExternalCommandRefused = 8

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:59

An external-service command was rejected instead of accepted.

NodeEntered

C#

NodeEntered = 1

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:38

Execution entered the entry’s node.

NodeExited

C#

NodeExited = 2

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

Execution left the entry’s node.

ResultRecorded

C#

ResultRecorded = 12

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:71

A node’s terminal result was recorded on the instance.

SubgraphPopped

C#

SubgraphPopped = 14

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:77

A subgraph activation was popped off the instance’s stack.

SubgraphPushed

C#

SubgraphPushed = 13

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:74

A subgraph activation was pushed onto the instance’s stack.

TickCompleted

C#

TickCompleted = 4

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:47

A tick of the instance ended.

TickStarted

C#

TickStarted = 3

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:44

A tick of the instance began.

TransitionFired

C#

TransitionFired = 5

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:50

A transition latched and moved the statechart to its target state.

Unknown

C#

Unknown = 0

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:35

The entry was never filled in; a decoder should skip it.

BehaviorTraceHighDetailRecorder

Category: Low-level runtime

C#

class BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRecorder

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:492-537

Editor / dev-build façade for recording high-detail trace events.

Responsibilities:

• Provide a single entry point the Layer 3 tick-system bridge and external-service-adapter bridge call to record events.
• StamprealtimeSinceStartupAsDouble for the convenience overload so callers do not have to pass a clock through.

Does NOT:

• Hold a singleton registry. Layer 3 constructs the registry instance on its central GameLogic and hands it to consumers explicitly (no-singletons rule).
• Decide what to record - that is the bridge layer’s responsibility.
• Live in shipping builds. The whole class is stripped per / R-11 along with its siblingBehaviorTraceHighDetailRing andBehaviorTraceHighDetailRegistry; callers gate their bridge code identically.

Members

Record(BehaviorTraceHighDetailRegistry registry, int followerId, BehaviorTraceHighDetailKind kind, int nodeIndex, int payloadId)

C#

public static void Record(BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRegistry registry, int followerId, BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailKind kind, int nodeIndex, int payloadId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:525-534

Convenience overload that stamps the current Unity realtime clock as the entry timestamp.

Record(BehaviorTraceHighDetailRegistry registry, int followerId, BehaviorTraceHighDetailKind kind, int nodeIndex, int payloadId, double timestampSeconds)

C#

public static void Record(BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRegistry registry, int followerId, BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailKind kind, int nodeIndex, int payloadId, double timestampSeconds)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:502-519

Append an entry toregistryfor followerId. The registry no-ops when high-detail is not active for the id, so this is safe to call from the bridge for every event.

BehaviorTraceHighDetailRegistry

Category: Low-level runtime

C#

class BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRegistry

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:312-470

Implements: IDisposable

Editor / dev-build registry of per-follower BehaviorTraceHighDetailRinginstances and the activation reference count (so two debuggers binding the same id keep the ring alive across deactivation).

Responsibilities:

• Map follower id to its ring buffer + activation refcount.
• ExposeActivate / Deactivateso the debugger window manages lifecycle, plus TryGetRingfor read access.
• Provide a static null-safeAppendthat consumers (the tick-system bridge, the external-service-adapter bridge) can call unconditionally; when high-detail is inactive for that id, the call is an O(1) lookup miss with no allocation.
• Be instantiable per Layer 3 runtime (no global singleton). Layer 3 constructs a registry on its central GameLogic and hands a reference to the editor debugger when the user opens it.

Does NOT:

• Persist across editor reloads; the registry lives for the life of its owning runtime.
• Activate by default; high-detail is opt-in by id (FR-024c).
• Live in shipping builds: gated on UNITY_EDITOR / UNITY_INCLUDE_INSTRUMENTATION per / R-11.

Members

ActiveFollowerIds

C#

public System.Collections.Generic.IReadOnlyCollection<int> ActiveFollowerIds { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:349-350

Snapshot of the follower ids that currently have an active ring.

RingCapacity

C#

public int RingCapacity { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:344

Gets the entry capacity every ring this registry activates is built with.

BehaviorTraceHighDetailRegistry(int ringCapacity)

C#

public BehaviorTraceHighDetailRegistry(int ringCapacity = 64)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:336-341

Creates an empty registry. Every ring it later activates is built with ringCapacityentries; a value of zero or less falls back to DefaultCapacity.

Activate(int followerId)

C#

public BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRing Activate(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:361-373

MarkfollowerIdas actively recording. Returns the ring the caller may pass to readers. Idempotent: a second activation increments the refcount and returns the same ring.

Append(int followerId, in BehaviorTraceHighDetailEntry entry)

C#

public bool Append(int followerId, in BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailEntry entry)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:430-439

Append an entry forfollowerIdwhen its ring is active. Silently no-ops otherwise. Thread-safety: the registry is single-threaded, matching the bridge layer that owns it - the Burst tick job records its outcome on the runtime instance and the managed bridge appends to the ring on the same thread.

Deactivate(int followerId)

C#

public void Deactivate(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:380-394

Decrement the activation refcount. When it hits zero the ring is disposed and removed; furtherAppendcalls for this id silently no-op.

Dispose()

C#

public void Dispose()

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:450-455

Releases every activated ring and its recorded entries. After this the registry reports nothing active,Append and TryGetRingfail silently, andActivate throws ObjectDisposedException.

IsActive(int followerId)

C#

public bool IsActive(int followerId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:399-402

True when at least one debugger has bound tofollowerId.

TryGetRing(int followerId, out BehaviorTraceHighDetailRing ring)

C#

public bool TryGetRing(int followerId, out BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRing ring)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:408-417

Get the ring forfollowerId; returns false when high-detail is inactive for that id.

BehaviorTraceHighDetailRing

Category: Low-level runtime

C#

class BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRing

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:157-284

Per-follower fixed-capacity ring buffer of high-detail trace entries.

Responsibilities:

• Hold up toCapacityrecent BehaviorTraceHighDetailEntryrecords and overwrite the oldest on append (FIFO with wrap).
• Provide an O(1) append and an O(Count) snapshot copy in chronological order so the editor debugger can paint the trail without allocating per-frame.
• Expose its mutation cursor (Version) so the debugger can short-circuit when the ring has not changed since the last refresh.

Does NOT:

• Run inside a Burst job: the ring is appended from the managed side (the tick system / adapter layer) when high-detail is active. The tick job itself stays Burst-pure - it produces its result and the bridge layer records it.
• Allocate per-append. The backing array is sized once at construction time.
• Live in shipping builds: the entire type is gated on UNITY_EDITOR or UNITY_INCLUDE_INSTRUMENTATIONper / R-11.

Members

Capacity

C#

public int Capacity { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:195

Gets how many entries the ring holds before an append overwrites the oldest one. Fixed when the ring is constructed.

Count

C#

public int Count { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:197

Gets how many entries are recorded right now; it rises to Capacity and then stays there as each append overwrites the oldest row.

Version

C#

public int Version { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:204

Monotonic mutation counter. Increments on every successful Append and on Clear. The debugger caches this and only repaints when it advances.

DefaultCapacity

C#

public const int DefaultCapacity = 64

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:165

Default ring capacity perdata-model.md §Behavior Trace (high-detail tier): 64 entries per follower.

BehaviorTraceHighDetailRing(int capacity)

C#

public BehaviorTraceHighDetailRing(int capacity = 64)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:185-192

Build a ring with the given capacity.capacity must be positive; values <= 0 fall through to DefaultCapacity.

Append(in BehaviorTraceHighDetailEntry entry)

C#

public void Append(in BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailEntry entry)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:214-220

Append an entry, overwriting the oldest record when the ring is full. O(1), no allocation.

Clear()

C#

public void Clear()

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:226-235

Drop every recorded entry and reset the cursor. Bumps Version.

CopyChronological(BehaviorTraceHighDetailEntry[] destination)

C#

public int CopyChronological(BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailEntry[] destination)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:246-264

Copy the ring’s contents intodestinationin chronological order (oldest first). Returns the number of entries written, capped atmin(Count, destination.Length).

Get(int index)

C#

public BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailEntry Get(int index)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTraceHighDetail.cs:270-281

Read the entry at chronological positionindex (0 == oldest). Throws when out of range.

BehaviorTraceServiceBindings

Category: Low-level runtime

C#

struct BitQuirky.Behavior.Diagnostics.BehaviorTraceServiceBindings

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:38-61

Well-known service ids the always-on trace projects out of the runtime instance’s pending-external slots into named fields.

Service ids are interned indices into the baked artifact’s ServiceNames table; FollowerBehaviorRuntimein Layer 3 resolves them at boot and hands the result here. -1 means the adapter is not bound for this graph (the trace then reports -1 for the corresponding pending field).

Members

None

C#

public static BitQuirky.Behavior.Diagnostics.BehaviorTraceServiceBindings None { get; }

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:49-50

Sentinel used when no adapter has been resolved yet. Both fields are -1 so the projection emits -1 for each pending slot.

AnimationServiceId

C#

public int AnimationServiceId

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

Interned service id of the resolved animation adapter, or -1 when none is bound; the trace projects the pending slot waiting on it into PendingAnimationRequestId.

PathServiceId

C#

public int PathServiceId

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

Interned service id of the resolved path adapter, or -1 when none is bound; the trace projects the pending slot waiting on it into PendingPathRequestId.

BehaviorTraceServiceBindings(int pathServiceId, int animationServiceId)

C#

public BehaviorTraceServiceBindings(int pathServiceId, int animationServiceId)

Source declaration: Packages/io.bitquirky.behavior/Runtime/Diagnostics/BehaviorTrace.cs:56-60

Binds the two adapters the trace projects by service id. Pass -1 for an adapter this graph does not use; its pending field then reportsNoValue.

Source fingerprint: sha256:ad0983d00d773d882bc61865e18d8c5559e009d181e5891575cd7f262515b23e