profiler.module
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, andpctof the frame. - An explicit
present / idlenode — the frame time no schedule covers (the frame-limiter / vsync wait, GPU present, event loop) — so nothing vanishes. - Per-component
update(dt)attribution grafted underlua_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.