Log inGet started
Package

cost.tool

Newest version

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

README.md

profiler.cost

What each frame cost the engine itself, beside its wall time, over a window of frames. Wall time reads the machine as much as the world: on a host running other engines and builds, or a player's laptop running a browser and a video call, a frame waits for a core another process holds and for a GPU other clients keep busy, and that wait lands in every wall-clock figure (frame, record, retro, the perf line). This view separates the two:

  • engine cpu: the engine thread's CPU time per frame, from the thread's own clock (thread_clock). In a browser, where a worker has no CPU clock, the worker's own time stands in (worker): the frame less what the host stated it spent waiting for the frame to fall due and running other work, which are reported apart as the host row. That time still holds any wait for a core the browser's thread had while the frame ran, which a browser does not state, so on a loaded machine it moves with the load.
  • waiting for core: the time per frame the engine thread was ready to run and waited for a core, with its share of the wall time (Linux and Android, from the scheduler's account of the thread).
  • gpu (own): the engine's own GPU time per frame: the GPU driver's account of the engine's process on the busiest of the GPU's engines where the driver states one (drm_fdinfo), otherwise the engine's timed passes (timestamp_queries), which other clients' work on a busy GPU lengthens.
  • host-bound fps: the frame rate the world would hold with the machine to itself, 1000 over the larger of the CPU and GPU time per frame, next to the frame rate it ran at.
  • the kinds of core the thread ran on (a hybrid CPU's performance and efficiency cores), the build profile, the Luau code generation state and the drawn size.

Frames that drew a capture a caller's tool call asked for are left out and counted. A caller's queued work (an execute, or the shell command reading this view) is taken out of the wall and CPU time of the frames it ran in, so zero profiler cost run from the shell measures the world's frames while it runs; a frame that spent half its wall time or more on that work is left out and counted. A figure the platform does not give is stated as unavailable with the platform's reason, never as zero.

Takes seconds (measure the next that many seconds, default 5) or last (read the last that many seconds the engine already holds, at once). profiler.frameCost returns the same report as a table, and the report record stops with carries it for the recording's frames.

Reading a frame cost on a shared machine

Two windows of one scene on a busy machine can run at very different frame rates while the engine's own figures stay where they were. Read engine cpu and gpu (own) to judge the world, and waiting for core to see how much of the wall time the machine took. A world is slow when the engine's own time per frame is high; the machine is busy when the wait for a core is a large share of the wall time while the engine's own time holds.