profiler
Functions for getting profiling data in runtime. More detailed profiling and debugging information available in the manuals.
Functions
profiler.dump_frame(): voidprofiler.enable(enabled: boolean): voidprofiler.enable_ui(enabled: boolean): voidprofiler.get_cpu_usage(): numberprofiler.get_memory_usage(): numberprofiler.log_text(text: string): voidprofiler.recorded_frame_count(): numberprofiler.scope_begin(name: string): voidprofiler.scope_end(): voidprofiler.set_ui_mode(mode:profiler.Mode): voidprofiler.set_ui_view_mode(mode:profiler.ViewMode): voidprofiler.set_ui_vsync_wait_visible(visible: boolean): voidprofiler.view_recorded_frame(frame_index: { distance: number } | { frame: number }): void
profiler.dump_frame(): void
logs the current frame to the console
profiler.dump_frame();profiler.dump_frame()profiler.enable(enabled: boolean): void
The profiler is a real-time tool that shows the numbers of milliseconds spent in each scope per frame as well as counters. The profiler is very useful for tracking down performance and resource problems.
// Show the profiler UI
profiler.enable(true);-- Show the profiler UI
profiler.enable(true)Parameters
enabled:boolean— true to enable, false to disable
profiler.enable_ui(enabled: boolean): void
Creates and shows or hides and destroys the on-sceen profiler ui The profiler is a real-time tool that shows the numbers of milliseconds spent in each scope per frame as well as counters. The profiler is very useful for tracking down performance and resource problems.
// Show the profiler UI
profiler.enable_ui(true);-- Show the profiler UI
profiler.enable_ui(true)Parameters
enabled:boolean— true to enable, false to disable
profiler.get_cpu_usage(): number
Get the percent of CPU usage by the application, as reported by the OS.
This function is not available on HTML5.
For some platforms ( Android, Linux and Windows), this information is only available
by default in the debug version of the engine. It can be enabled in release version as well
by checking track_cpu under profiler in the game.project file.
(This means that the engine will sample the CPU usage in intervalls during execution even in release mode.)
Returns
percent:number— of CPU used by the application
profiler.get_memory_usage(): number
Get the detailed amount of memory used by the application in bytes, as reported by the platform. The values are gathered from internal OS functions which correspond to the following;
OS Value
iOS MacOS Android Linux Resident memory
Windows Working set
HTML5
Allocated bytes reported by mallinfo().uordblks
// Get memory usage before and after loading a collection:
print(profiler.get_memory_usage());
msg.post("#collectionproxy", "load");
// ...
print(profiler.get_memory_usage()); // will report a higher number than the initial callprint(profiler.get_memory_usage())
msg.post("#collectionproxy", "load")
...
print(profiler.get_memory_usage()) -- will report a higher number than the initial callReturns
bytes:number— used by the application
profiler.log_text(text: string): void
Send a text to the connected profiler
const name = "my_event";
profiler.log_text(`Event: ${name}`);profiler.log_text("Event: " .. name)Parameters
text:string— the string to send to the connected profiler
profiler.recorded_frame_count(): number
Get the number of recorded frames in the on-screen profiler ui recording buffer
// Show the last recorded frame
const recorded_frame_count = profiler.recorded_frame_count();
profiler.view_recorded_frame({ frame: recorded_frame_count });-- Show the last recorded frame
local recorded_frame_count = profiler.recorded_frame_count()
profiler.view_recorded_frame(recorded_frame_count)Returns
frame_count:number— the number of recorded frames, zero if on-screen profiler is disabled
profiler.scope_begin(name: string): void
Starts a profile scope.
function test_function() {
// the work being measured
}
// Go back one frame
profiler.scope_begin("test_function");
test_function();
profiler.scope_end();-- Go back one frame
profiler.scope_begin("test_function")
test_function()
profiler.scope_end()Parameters
name:string— The name of the scope
profiler.scope_end(): void
End the current profile scope.
profiler.set_ui_mode(mode: profiler.Mode): void
Set the on-screen profile mode - run, pause, record or show peak frame
function start_recording() {
profiler.set_ui_mode(profiler.MODE_RECORD);
}
function stop_recording() {
profiler.set_ui_mode(profiler.MODE_PAUSE);
}function start_recording()
profiler.set_ui_mode(profiler.MODE_RECORD)
end
function stop_recording()
profiler.set_ui_mode(profiler.MODE_PAUSE)
endParameters
mode:profiler.Mode— the mode to set the ui profiler in To stop recording, switch to a different mode such asMODE_PAUSEorMODE_RUN. You can also use theview_recorded_framefunction to display a recorded frame. Doing so stops the recording as well. Every time you switch to recording mode the recording buffer is cleared.
profiler.set_ui_view_mode(mode: profiler.ViewMode): void
Set the on-screen profile view mode - minimized or expanded
// Minimize the profiler view
profiler.set_ui_view_mode(profiler.VIEW_MODE_MINIMIZED);-- Minimize the profiler view
profiler.set_ui_view_mode(profiler.VIEW_MODE_MINIMIZED)Parameters
mode:profiler.ViewMode— the view mode to set the ui profiler in
profiler.set_ui_vsync_wait_visible(visible: boolean): void
Shows or hides the time the engine waits for vsync in the on-screen profiler Each frame the engine waits for vsync and depending on your vsync settings and how much time your game logic takes this time can dwarf the time in the game logic making it hard to see details in the on-screen profiler graph and lists. Also, by hiding this the FPS times in the header show the time spent each time excuding the time spent waiting for vsync. This shows you how long time your game is spending actively working each frame. This setting also effects the display of recorded frames but does not affect the actual recorded frames so it is possible to toggle this on and off when viewing recorded frames. By default the vsync wait times is displayed in the profiler.
// Exclude frame wait time from the profiler ui
profiler.set_ui_vsync_wait_visible(false);-- Exclude frame wait time form the profiler ui
profiler.set_ui_vsync_wait_visible(false)Parameters
visible:boolean— true to include it in the display, false to hide it.
profiler.view_recorded_frame(frame_index: { distance: number } | { frame: number }): void
Pauses and displays a frame from the recording buffer in the on-screen profiler ui The frame to show can either be an absolute frame or a relative frame to the current frame.
// Go back one frame
profiler.view_recorded_frame({ distance: -1 });-- Go back one frame
profiler.view_recorded_frame({distance = -1})Parameters
frame_index:{ distance: number } | { frame: number }— a table where you specify one of the following parameters:distanceThe offset from the currently displayed frame (this is truncated between zero and the number of recorded frames)frameThe frame index in the recording buffer (1 is first recorded frame)
frameis 1-based; passed to Defold unchanged.
Constants
profiler.MODE_PAUSE: number & { readonly __brand: "profiler.MODE_PAUSE" }
pause on the currently displayed frame
profiler.MODE_RECORD: number & { readonly __brand: "profiler.MODE_RECORD" }
record incoming frames to the recording buffer
profiler.MODE_RUN: number & { readonly __brand: "profiler.MODE_RUN" }
continuously show the latest frame
profiler.MODE_SHOW_PEAK_FRAME: number & { readonly __brand: "profiler.MODE_SHOW_PEAK_FRAME" }
pause on the displayed frame, replacing it when a slower frame arrives
profiler.VIEW_MODE_FULL: number & { readonly __brand: "profiler.VIEW_MODE_FULL" }
show all profiler details
profiler.VIEW_MODE_MINIMIZED: number & { readonly __brand: "profiler.VIEW_MODE_MINIMIZED" }
show only the header with FPS counters and profiler mode