Skip to content

Game.ProfilerMetricsDebugUI

Assembly:
Game

Namespace:
Game.Debug

Type:
class

Base:
System.Object, implements System.IDisposable

Summary:
A debug UI container that collects a set of Unity Profiler metrics (ProfilerRecorder instances) and exposes them as DebugUI widgets grouped by category. It starts ProfilerRecorders for a predefined set of memory-related metrics, formats their values for display (bytes, time, counts, frequency, percent) and provides a DebugTab ("Profiler Metrics") that returns the widgets to be shown in the in-game debug UI. The class manages lifecycle of the recorders and must be disposed to release resources.

Fields

  • private List<StatInfo> m_AvailableStats
    Holds the list of tracked metrics (StatInfo) containing the category, name and a ProfilerRecorder for each metric. Populated by CollectProfilerMetrics() in the constructor and cleared/disposed by DisposeProfilerMetrics() when disposing the object.

  • private struct StatInfo

  • public string categoryName
    Category display name used for grouping in the Debug UI (e.g., "Memory").
  • public ProfilerCategory category
    Unity.Profiling.ProfilerCategory for the metric.
  • public string name
    The exact marker name used to start the ProfilerRecorder.
  • public ProfilerRecorder profilerRecorder
    The ProfilerRecorder instance collecting the metric data.
  • public StatInfo(string categoryName, ProfilerCategory category, string name, int sampleCount = 0)
    Constructor: starts a ProfilerRecorder for the given category/name. If sampleCount > 0 it calls ProfilerRecorder.StartNew(category, name, sampleCount); otherwise StartNew(category, name).

Properties

  • This class does not expose any public properties.

Constructors

  • public ProfilerMetricsDebugUI()
    Initializes the ProfilerMetricsDebugUI and calls CollectProfilerMetrics() to start the set of ProfilerRecorders for the metrics defined in that method.

Methods

  • public void Dispose()
    Implements IDisposable. Calls DisposeProfilerMetrics() to Dispose each ProfilerRecorder and clears the internal list. Must be called when the debug UI is unloaded to avoid leaking ProfilerRecorder resources.

  • private unsafe static double GetRecorderFrameAverage(ProfilerRecorder recorder)
    Copies the recorder's samples to a stackallocated array and returns the arithmetic mean of the samples. Returns 0.0 if recorder.Capacity is 0. Uses unsafe code and stackalloc; the returned value is in the unit used by the recorder (e.g., nanoseconds for TimeNanoseconds), so callers often scale it to displayable units (the class multiplies by ~1e-6 to get ms).

  • private void CollectProfilerMetrics()
    Populates m_AvailableStats with a fixed set of memory-related metrics by constructing StatInfo entries. Each StatInfo will create/start its ProfilerRecorder when constructed. The method currently registers a list of "Memory" markers like "Total Used Memory", "GC Used Memory", "Gfx Used Memory", etc.

  • private void DisposeProfilerMetrics()
    Iterates m_AvailableStats, disposes each StatInfo.profilerRecorder, and then clears the list. Called from Dispose().

  • [DebugTab("Profiler Metrics", 0)] private List<DebugUI.Widget> BuildProfilerMetricsDebugUI()
    Builds and returns the list of DebugUI widgets to show in the profiler metrics debug tab. Groups metrics by categoryName into DebugUI.Foldout widgets, then for each StatInfo creates a DebugUI.Value with an appropriate getter based on the ProfilerRecorder.UnitType:

  • Bytes -> formats LastValue as human-readable bytes via FormatUtils.FormatBytes.
  • TimeNanoseconds -> uses GetRecorderFrameAverage(...) * 9.999999974752427E-07 to convert average nanoseconds to milliseconds and formats to two decimal places with "ms".
  • Count -> returns profilerRecorder.Count.
  • FrequencyHz -> returns LastValue with "Hz" suffix.
  • Percent -> returns LastValue with "%" suffix. Notes:
  • The conversion factor used is approximately 1e-6 (ns -> ms).
  • The widget getters access the ProfilerRecorder properties (LastValue, Count) directly and so the UI will reflect the latest recorder values.
  • The function uses a dictionary to group widgets by category and returns the full widget list.

Usage Example

// Typical usage within a mod or debug subsystem:
// Create an instance when the debug system initializes, and Dispose when unloading.

private ProfilerMetricsDebugUI m_profilerMetrics;

public void OnEnable()
{
    // Start collecting profiler metrics and register the debug tab
    m_profilerMetrics = new ProfilerMetricsDebugUI();
}

public void OnDisable()
{
    // Dispose to release ProfilerRecorder resources
    m_profilerMetrics?.Dispose();
    m_profilerMetrics = null;
}

Additional notes: - ProfilerRecorder instances should be disposed when no longer needed to prevent resource leaks; this class handles that via Dispose(). - The GetRecorderFrameAverage method uses unsafe code and stackalloc: make sure your project and runtime settings allow unsafe execution. - The set of tracked metrics is hardcoded in CollectProfilerMetrics(); to track additional markers you can extend that list with their category and marker name. - Because this class interacts with Unity.Profiling types, ensure it runs in contexts where the Unity Profiler API is available (typically in-editor or in debug builds where profiler APIs are enabled).