Log inGet started
Package

profiler.module

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

profiler

The profiler model — the single source of truth that turns the engine's flat profiling surface (getProfilingDataTable, getLuauVmDataTable, profiler.stopCapture) into the honest, self-accounting hierarchy every profiler tool and the System Tools Profiler tab reads from.

Location: src/lua/lib/modules/profiler.module

Required as require("modules.profiler").

What it composes

  • A nested tree where every node carries total_ms, self_ms (own time excluding children), calls, and pct of the frame.
  • An explicit present / idle node — the frame time no schedule covers (the frame-limiter / vsync wait, GPU present, event loop) — so nothing vanishes.
  • Per-component update(dt) attribution grafted under lua_update.vm_call, so a heavy script names the entity + component an author can open and fix.
  • Per-component coroutine-resume attribution under task_scheduler, so a busy scheduler names the component whose tasks it resumed.
  • Windowed aggregation over a capture: avg / p50 / p90 / p99 / max frame time, the worst single frame, and spike counting.

Reading a capture

readCapture(label?, opts?) reads a stored capture (a stopped recording, a retro snapshot, drained watchdog hits) in the shape profiler.stopCapture() decodes to, its frames built from the engine's records (profiler.captureFrames) with no JSON round trip. { frames = false } reads it without its frames, a few kilobytes however long it is, and { first, count } reads that page of frames alone. eachCaptureFrame(capture, fn) walks a capture read without its frames a page of CAPTURE_PAGE_FRAMES (64) frames at a time, and aggregateCapture takes such a capture and walks it that way, so the profiler tools hold one page of frames however long the capture they report on is.

The model + format functions are pure — the tools and the UI produce identical numbers from identical inputs. See the profiler toolbox for the tools that read this model.