Memory Profiling

The editor includes a Game Memory overlay that shows what the engine has loaded for the project being edited — the same asset state a built game would consume. The overlay does not measure the editor's own caches, ImGui atlas, or theme textures; the workshop is not the product.

For runtime profiling inside a shipped game (periodic sampling, file sinks, ring-buffer recording with no editor or ImGui dependency), see story 12.7's MemoryProfiler API.

Capturing a snapshot

Open the launcher (Ctrl+Space) and run Snapshot Memory Profile to capture a snapshot from anywhere in the editor. Open Show Diagnostics Overlay to see live numbers in a tile and to save snapshots to disk.

Saved snapshots are written as JSON to %LOCALAPPDATA%/PopcorningGuineaPig/Diagnostics/snapshot-{timestamp}.json. The schema mirrors the MemorySnapshot record and is stable enough to compare across runs.

Interpreting the categories

A snapshot reports bytes for each MemoryCategory. The overlay groups them into two sections:

Game asset state — the game's footprint

  • Textures — engine asset registry's estimate of texture pixel data, derived from each texture's pixel format and dimensions. Compressed formats (DXT, ETC, ASTC) round up to block boundaries.
  • Models — engine model assets. Counts are tracked exactly; per-byte estimation is conservative.
  • Sounds — registered audio sources.
  • Fonts — registered fonts.
  • Shaders — registered shaders. GPU memory of compiled shaders is opaque to the engine; this category is reported as 0.
  • Other — catch-all.

The overlay's "% of Asset Total" column is computed against this group only, so each row reflects its share of the game's asset footprint specifically.

Host process — editor + engine combined

  • ManagedHeap — CLR heap of the host process. When sampled from inside the editor this includes the editor's allocations.
  • ProcessWorkingSet — physical RAM the OS reports as in use.
  • ProcessPrivate — committed memory not shared with other processes.

The overlay UI labels these as "Host process (editor + engine — not the game's footprint)" so they are never mistaken for the game's memory budget. To get clean process counters for a shipped game, use story 12.7's MemoryProfiler from inside the game's own process.

Where baselines live

Documented baselines for the four scenarios required by the architecture sit at memory-bank/performance/memory-baselines.md in the repository root. When you optimize memory, capture a fresh snapshot in the same scenario and append a comparison entry there — never replace the historical numbers.

Cost of the instrumentation itself

The cheap path (IDiagnosticsService.Tick()) is throttled to a 500ms cadence and reads only GC.GetTotalMemory(false) plus the cached process counters — it never walks the asset registry. The heavy path (IDiagnosticsService.CaptureSnapshot()) is target-bounded under 50ms; the service logs a warning if a single capture exceeds the budget. The story-level acceptance criterion sets the per-frame instrumentation budget at less than 1% of a 60fps frame (≈0.166ms).