BitQuirky.Behavior.Diagnostics
Public behavior trees and state machines: instrumentation (optional) symbols in BitQuirky.Behavior.Diagnostics.
Source snapshot 29003d8b1658.
On this page
Assembly: BitQuirky.Behavior.Instrumentation
BehaviorTraceHighDetailRecorder
Section titled “BehaviorTraceHighDetailRecorder”Category: Low-level runtime
class BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRecorderSource declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:366-411
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.
- Stamp
realtimeSinceStartupAsDoublefor 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
Section titled “Members”Record(BehaviorTraceHighDetailRegistry registry, int followerId, BehaviorTraceHighDetailKind kind, int nodeIndex, int payloadId)
Section titled “Record(BehaviorTraceHighDetailRegistry registry, int followerId, BehaviorTraceHighDetailKind kind, int nodeIndex, int payloadId)”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/Instrumentation/BehaviorTraceHighDetail.cs:399-408
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)
Section titled “Record(BehaviorTraceHighDetailRegistry registry, int followerId, BehaviorTraceHighDetailKind kind, int nodeIndex, int payloadId, double timestampSeconds)”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/Instrumentation/BehaviorTraceHighDetail.cs:376-393
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
Section titled “BehaviorTraceHighDetailRegistry”Category: Low-level runtime
class BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRegistrySource declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:186-344
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
Section titled “Members”ActiveFollowerIds
Section titled “ActiveFollowerIds”public System.Collections.Generic.IReadOnlyCollection<int> ActiveFollowerIds { get; }Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:223-224
Snapshot of the follower ids that currently have an active ring.
RingCapacity
Section titled “RingCapacity”public int RingCapacity { get; }Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:218
Gets the entry capacity every ring this registry activates is built with.
BehaviorTraceHighDetailRegistry(int ringCapacity)
Section titled “BehaviorTraceHighDetailRegistry(int ringCapacity)”public BehaviorTraceHighDetailRegistry(int ringCapacity = 64)Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:210-215
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)
Section titled “Activate(int followerId)”public BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRing Activate(int followerId)Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:235-247
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)
Section titled “Append(int followerId, in BehaviorTraceHighDetailEntry entry)”public bool Append(int followerId, in BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailEntry entry)Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:304-313
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)
Section titled “Deactivate(int followerId)”public void Deactivate(int followerId)Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:254-268
Decrement the activation refcount. When it hits zero the ring is disposed and removed; furtherAppendcalls for this id silently no-op.
Dispose()
Section titled “Dispose()”public void Dispose()Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:324-329
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)
Section titled “IsActive(int followerId)”public bool IsActive(int followerId)Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:273-276
True when at least one debugger has bound tofollowerId.
TryGetRing(int followerId, out BehaviorTraceHighDetailRing ring)
Section titled “TryGetRing(int followerId, out BehaviorTraceHighDetailRing ring)”public bool TryGetRing(int followerId, out BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRing ring)Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:282-291
Get the ring forfollowerId; returns false
when high-detail is inactive for that id.
BehaviorTraceHighDetailRing
Section titled “BehaviorTraceHighDetailRing”Category: Low-level runtime
class BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailRingSource declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:31-158
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_EDITORorUNITY_INCLUDE_INSTRUMENTATIONper / R-11.
Members
Section titled “Members”Capacity
Section titled “Capacity”public int Capacity { get; }Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:69
Gets how many entries the ring holds before an append overwrites the oldest one. Fixed when the ring is constructed.
public int Count { get; }Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:71
Gets how many entries are recorded right now; it rises to Capacity and then stays there as each append overwrites the oldest row.
Version
Section titled “Version”public int Version { get; }Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:78
Monotonic mutation counter. Increments on every successful Append and on Clear. The debugger caches this and only repaints when it advances.
DefaultCapacity
Section titled “DefaultCapacity”public const int DefaultCapacity = 64Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:39
Default ring capacity perdata-model.md §Behavior Trace (high-detail tier): 64 entries per follower.
BehaviorTraceHighDetailRing(int capacity)
Section titled “BehaviorTraceHighDetailRing(int capacity)”public BehaviorTraceHighDetailRing(int capacity = 64)Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:59-66
Build a ring with the given capacity.capacity
must be positive; values <= 0 fall through to
DefaultCapacity.
Append(in BehaviorTraceHighDetailEntry entry)
Section titled “Append(in BehaviorTraceHighDetailEntry entry)”public void Append(in BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailEntry entry)Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:88-94
Append an entry, overwriting the oldest record when the ring is full. O(1), no allocation.
Clear()
Section titled “Clear()”public void Clear()Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:100-109
Drop every recorded entry and reset the cursor. Bumps Version.
CopyChronological(BehaviorTraceHighDetailEntry[] destination)
Section titled “CopyChronological(BehaviorTraceHighDetailEntry[] destination)”public int CopyChronological(BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailEntry[] destination)Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:120-138
Copy the ring’s contents intodestinationin
chronological order (oldest first). Returns the number of entries
written, capped atmin(Count, destination.Length).
Get(int index)
Section titled “Get(int index)”public BitQuirky.Behavior.Diagnostics.BehaviorTraceHighDetailEntry Get(int index)Source declaration: Packages/io.bitquirky.behavior/Runtime/Instrumentation/BehaviorTraceHighDetail.cs:144-155
Read the entry at chronological positionindex
(0 == oldest). Throws when out of range.
Source fingerprint: sha256:29003d8b1658b98a79bebcd93e3b4030caf8511268b96817ab764d63df8d6c3b