swiftlys2/docs/api/releases/features/ai/

Profiler

SwiftlyS2's profiler service measures execution time in plugin code and records custom duration metrics.

Access it through Core.Profiler (APIISwiftlyCore.Profiler, type APIIContextedProfilerService).

Measuring Code Blocks

Pair APIIContextedProfilerService.StartRecording/APIIContextedProfilerService.StopRecording around the code, wrapped in try/finally so an exception doesn't leave a recording open.

Both take the recording name as a string, so pass the same name to StopRecording that you passed to StartRecording:

Core.Profiler.StartRecording("Database.PlayerStats.Load");
try
{
    LoadPlayerStats();
}
finally
{
    Core.Profiler.StopRecording("Database.PlayerStats.Load");
}

Neither method returns anything - StartRecording gives you no scope, handle or token, so the name is the only thing tying a start call to its stop call.

Recording Precomputed Durations

Use APIIContextedProfilerService.RecordTime for a duration you already measured - the second parameter is a double:

var stopwatch = System.Diagnostics.Stopwatch.StartNew();
 
BuildLargeMenu();
 
stopwatch.Stop();
double durationUs = stopwatch.ElapsedTicks * (1_000_000.0 / System.Diagnostics.Stopwatch.Frequency);
Core.Profiler.RecordTime("Menu.Build", durationUs);

The interface doesn't state a unit for duration, and the example above records microseconds. Pick one unit and use it consistently so profiler entries stay comparable across the codebase.

Profiling Sub-Operations

Nest start/stop pairs to profile major flow steps separately and find hot spots faster. Give each nested recording its own name, since there is no scope object that would separate two recordings sharing one:

Core.Profiler.StartRecording("PlayerData.Process");
try
{
    Core.Profiler.StartRecording("PlayerData.Load");
    try { LoadPlayerData(player.SteamID); } finally { Core.Profiler.StopRecording("PlayerData.Load"); }
 
    Core.Profiler.StartRecording("PlayerData.Apply");
    try { ApplyPlayerData(player); } finally { Core.Profiler.StopRecording("PlayerData.Apply"); }
}
finally { Core.Profiler.StopRecording("PlayerData.Process"); }

Naming Strategy

Use clear, hierarchical names so related entries group together:

category.operation.detail

Examples: Database.Players.Load, Database.Players.Save, Menu.Main.Build, Menu.Main.Open, Commands.Teleport.Execute, Events.PlayerSpawn.Process.

Avoid generic names like Operation or Process - they make hot spots hard to trace back to real code.

Reading Results

The service only writes. APIIContextedProfilerService has no member that returns a recording, a duration, a snapshot of the collected metrics or any current state - all three members return void - so a plugin can't read back what it recorded through this API. Recording names are therefore write-only keys: keep them in a consistent naming scheme and consume the results outside the plugin API.

Members

APIIContextedProfilerService members, in the SwiftlyS2.Shared.Profiler namespace:

MemberSignatureDescription
APIIContextedProfilerService.StartRecordingvoid StartRecording(string name)Starts a recording under name
APIIContextedProfilerService.StopRecordingvoid StopRecording(string name)Stops the recording started under name
APIIContextedProfilerService.RecordTimevoid RecordTime(string name, double duration)Records duration for name without a start/stop pair

services.AddSwiftly(Core) registers Core.Profiler as a singleton, so IContextedProfilerService can be constructor-injected - see Dependency Injection.

Reference

See APIISwiftlyCore for the full service list, and Swiftly Core for the other core services.