Skip to content
Version 2.32.0
↓ Get the launcher

HitchProbe class

Render-frame hitch attribution. When a rendered frame exceeds ThresholdMs, one [Hitch] line names what Stellar did inside that frame — the framework tick, each plugin’s Update, font-atlas rebuild refreshes, window mounts/destroys, config saves, combat-hook time — plus the managed and IL2CPP GC collections that ran. A hitch with near-zero Stellar time and no GC is the game’s own (render / shader compile / asset load), which is exactly the question a frametime-spike report needs answered first. Gated on the one diagnostics flag (StellarDiagnostics) or a HITCH line in stellar_perf.flags; when off every call returns on a cached field read.

Main-thread buckets use a plain dictionary (all callers are on the Unity main thread); the combat-hook total is fed from hook threads and accumulates with Interlocked.

Static mutable state is the sanctioned diagnostic exception, as for PerfProbe.

public static class HitchProbe
name description
static IsEnabled { get; } true when hitch attribution is armed (diagnostics on, or HITCH flag).
const HookKindCombat Attribution kind: game-network combat stub handlers (summed in combatHooks).
const HookKindCombatSubscriber Attribution kind: ICombatEvents.CombatEventOccurred subscribers (main-thread fan-out, inside the svc:combat segment).
const HookKindWire Attribution kind: wire tap / notify stub handlers (summed in wireHooks).
const ThresholdMs A rendered frame slower than this (ms) is reported.
static AddHook(…) Charge one hook invocation (any thread). kind: 0 = combat, 1 = wire/notify.
static Begin() Start timestamp for a timed section, or 0 when disabled.
static BeginSeg(…) Open a named segment (main thread); pairs with EndSeg. Fed by BeginSeg so the existing tick segments break a hitch down with no extra call sites.
static Count(…) Add n to a per-frame counter, reported as name=#N on a hitch line. Main thread only; stable (non-allocated) names.
static DescribeHandler(…) A stable, readable owner name for a handler delegate: its declaring type (closure / lambda classes folded into the type that wrote them), prefixed by the assembly when that differs and isn’t a framework assembly — e.g. RaidManager.MechanicTracker, PandaCombatStubProbe. Registration time only (reflection).
static End(…) Close a section opened with Begin and charge it to bucket. Main thread only. Use stable (non-allocated) bucket strings.
static EndHookSlot(…) Charge one handler invocation started at startTicks (Begin) to slot. Any thread.
static EndSeg(…) Close a segment opened with BeginSeg.
static HookSlotFor(…) The slot for handler name of kind, or null when hitch attribution is off (then keep the bare handler). Call at registration time, never per call.
static Lap(…) End then return a fresh start stamp — for back-to-back phases.
static OnRenderFrame(…) Called once per rendered frame (main thread) with that frame’s duration. Emits a line through log when the frame was a hitch, then resets the per-frame accumulators.
class HookSlot A pre-allocated per-handler accumulator. Opaque to callers — obtain via HookSlotFor.