Modder API

Modder API

Snitch lets any mod report its own performance. The API is a zero-overhead no-op when Snitch is not installed, so you can ship the integration unconditionally with no hard dependency. Full working example: ScheduleOne-SnitchExample.

Add the API

• Copy-in source (recommended): drop Snitch.cs (from the example repo) into your mod project. It compiles into your DLL - nothing extra to ship.
• Reference the DLL: reference Snitch.Api.dll.

Both bind to the running Snitch host by reflection, so they share no type with it and work regardless of load order (registrations are queued until the host is up).

Use it

using Snitch.Api;                  // StateSnapshot
using Prof = Snitch.Api.Snitch;    // alias avoids the Snitch namespace/type clash

// 1) Time a section (no heap alloc; no-op when Snitch is absent or not sampling)
using (Prof.Sample("MyMod.Pathfinding")) { /* expensive work */ }

// gate hot loops for the absolutely-free path:
if (Prof.Enabled) using (Prof.Sample("MyMod.Tick")) { /* ... */ }

// 2) A numeric gauge (polled a few Hz by the host)
Prof.RegisterCounter("MyMod.QueueLength", () => _queue.Count, "items");

// 3) An entity/state distribution (a bar panel in the HUD + web dashboard)
Prof.RegisterStateProvider("MyMod.Jobs", () =>
    new StateSnapshot { Title = "Jobs" }.Add("running", _running).Add("queued", _queued));

// 4) An ablation lever so 'snitch ablate mymod.fx' measures your subsystem's causal frame cost
Prof.RegisterAblationLever("mymod.fx", apply: () => DisableFx(), restore: () => EnableFx());

// 5) Mark a one-off spike
Prof.Mark("MyMod.LevelLoaded");

Rules

• Call from the Unity main thread. Counter/state delegates are invoked by the host on the main thread, so they may safely touch game objects.
• Prefix labels with MyMod. so they roll up per mod in the HUD and dashboard.
• Prof.Sample returns a readonly struct scope - no heap allocation, and Dispose is a no-op when Snitch isn't sampling.

Your sections, counters and states appear live in the in-game HUD and the Web Dashboard, right alongside the vanilla NPC/trash/quest data.