Inheritance #

Performance #

is_instantiable, core, not_builtin_classes, singleton

Exposes performance-related data.

This class provides access to a number of different monitors related to performance, such as memory usage, draw calls, and FPS. These are the same as the values displayed in the Monitor tab in the editor's Debugger panel. By using the get_monitor method of this class, you can access this data from your code.

You can add custom monitors using the add_custom_monitor method. Custom monitors are available in Monitor tab in the editor's Debugger panel together with built-in monitors.

Note: Some of the built-in monitors are only available in debug mode and will always return 0 when used in a project exported in release mode.

Note: Some of the built-in monitors are not updated in real-time for performance reasons, so there may be a delay of up to 1 second between changes.

Note: Custom monitors do not support negative values. Negative values are clamped to 0.

Members #

Methods #

func _ready():
    var monitor_value = Callable(self, "get_monitor_value")

    # Adds monitor with name "MyName" to category "MyCategory".
    Performance.add_custom_monitor("MyCategory/MyMonitor", monitor_value)

    # Adds monitor with name "MyName" to category "Custom".
    # Note: "MyCategory/MyMonitor" and "MyMonitor" have same name but different IDs, so the code is valid.
    Performance.add_custom_monitor("MyMonitor", monitor_value)

    # Adds monitor with name "MyName" to category "Custom".
    # Note: "MyMonitor" and "Custom/MyMonitor" have same name and same category but different IDs, so the code is valid.
    Performance.add_custom_monitor("Custom/MyMonitor", monitor_value)

    # Adds monitor with name "MyCategoryOne/MyCategoryTwo/MyMonitor" to category "Custom".
    Performance.add_custom_monitor("MyCategoryOne/MyCategoryTwo/MyMonitor", monitor_value)

func get_monitor_value():
    return randi() % 25

public override void _Ready()
{
    var monitorValue = new Callable(this, MethodName.GetMonitorValue);

    // Adds monitor with name "MyName" to category "MyCategory".
    Performance.AddCustomMonitor("MyCategory/MyMonitor", monitorValue);
    // Adds monitor with name "MyName" to category "Custom".
    // Note: "MyCategory/MyMonitor" and "MyMonitor" have same name but different ids so the code is valid.
    Performance.AddCustomMonitor("MyMonitor", monitorValue);

    // Adds monitor with name "MyName" to category "Custom".
    // Note: "MyMonitor" and "Custom/MyMonitor" have same name and same category but different ids so the code is valid.
    Performance.AddCustomMonitor("Custom/MyMonitor", monitorValue);

    // Adds monitor with name "MyCategoryOne/MyCategoryTwo/MyMonitor" to category "Custom".
    Performance.AddCustomMonitor("MyCategoryOne/MyCategoryTwo/MyMonitor", monitorValue);
}

public int GetMonitorValue()
{
    return GD.Randi() % 25;
}

print(Performance.get_monitor(Performance.TIME_FPS)) # Prints the FPS to the console.

GD.Print(Performance.GetMonitor(Performance.Monitor.TimeFps)); // Prints the FPS to the console.

Annotations #

Constants #

const TIME_FPS = 0 enum Monitor#

The number of frames rendered in the last second. This metric is only updated once per second, even if queried more often. Higher is better.

const TIME_PROCESS = 1 enum Monitor#

Time it took to complete one frame, in seconds. Lower is better.

const TIME_PHYSICS_PROCESS = 2 enum Monitor#

Time it took to complete one physics frame, in seconds. Lower is better.

const TIME_NAVIGATION_PROCESS = 3 enum Monitor#

Time it took to complete one navigation step, in seconds. This includes navigation map updates as well as agent avoidance calculations. Lower is better.

const MEMORY_STATIC = 4 enum Monitor#

Static memory currently used, in bytes. Not available in release builds. Lower is better.

const MEMORY_STATIC_MAX = 5 enum Monitor#

Available static memory. Not available in release builds. Lower is better.

const MEMORY_MESSAGE_BUFFER_MAX = 6 enum Monitor#

Largest amount of memory the message queue buffer has used, in bytes. The message queue is used for deferred functions calls and notifications. Lower is better.

const OBJECT_COUNT = 7 enum Monitor#

Number of objects currently instantiated (including nodes). Lower is better.

const OBJECT_RESOURCE_COUNT = 8 enum Monitor#

Number of resources currently used. Lower is better.

const OBJECT_NODE_COUNT = 9 enum Monitor#

Number of nodes currently instantiated in the scene tree. This also includes the root node. Lower is better.

const OBJECT_ORPHAN_NODE_COUNT = 10 enum Monitor#

Number of orphan nodes, i.e. nodes which are not parented to a node of the scene tree. Lower is better.

const RENDER_TOTAL_OBJECTS_IN_FRAME = 11 enum Monitor#

The total number of objects in the last rendered frame. This metric doesn't include culled objects (either via hiding nodes, frustum culling or occlusion culling). Lower is better.

const RENDER_TOTAL_PRIMITIVES_IN_FRAME = 12 enum Monitor#

The total number of vertices or indices rendered in the last rendered frame. This metric doesn't include primitives from culled objects (either via hiding nodes, frustum culling or occlusion culling). Due to the depth prepass and shadow passes, the number of primitives is always higher than the actual number of vertices in the scene (typically double or triple the original vertex count). Lower is better.

const RENDER_TOTAL_DRAW_CALLS_IN_FRAME = 13 enum Monitor#

The total number of draw calls performed in the last rendered frame. This metric doesn't include culled objects (either via hiding nodes, frustum culling or occlusion culling), since they do not result in draw calls. Lower is better.

const RENDER_VIDEO_MEM_USED = 14 enum Monitor#

The amount of video memory used (texture and vertex memory combined, in bytes). Since this metric also includes miscellaneous allocations, this value is always greater than the sum of RENDER_TEXTURE_MEM_USED and RENDER_BUFFER_MEM_USED. Lower is better.

const RENDER_TEXTURE_MEM_USED = 15 enum Monitor#

The amount of texture memory used (in bytes). Lower is better.

const RENDER_BUFFER_MEM_USED = 16 enum Monitor#

The amount of render buffer memory used (in bytes). Lower is better.

const PHYSICS_2D_ACTIVE_OBJECTS = 17 enum Monitor#

Number of active RigidBody2D nodes in the game. Lower is better.

const PHYSICS_2D_COLLISION_PAIRS = 18 enum Monitor#

Number of collision pairs in the 2D physics engine. Lower is better.

const PHYSICS_2D_ISLAND_COUNT = 19 enum Monitor#

Number of islands in the 2D physics engine. Lower is better.

const PHYSICS_3D_ACTIVE_OBJECTS = 20 enum Monitor#

Number of active RigidBody3D and VehicleBody3D nodes in the game. Lower is better.

const PHYSICS_3D_COLLISION_PAIRS = 21 enum Monitor#

Number of collision pairs in the 3D physics engine. Lower is better.

const PHYSICS_3D_ISLAND_COUNT = 22 enum Monitor#

Number of islands in the 3D physics engine. Lower is better.

const AUDIO_OUTPUT_LATENCY = 23 enum Monitor#

Output latency of the AudioServer. Equivalent to calling AudioServer.get_output_latency, it is not recommended to call this every frame.

const NAVIGATION_ACTIVE_MAPS = 24 enum Monitor#

Number of active navigation maps in the NavigationServer3D. This also includes the two empty default navigation maps created by World2D and World3D.

const NAVIGATION_REGION_COUNT = 25 enum Monitor#

Number of active navigation regions in the NavigationServer3D.

const NAVIGATION_AGENT_COUNT = 26 enum Monitor#

Number of active navigation agents processing avoidance in the NavigationServer3D.

const NAVIGATION_LINK_COUNT = 27 enum Monitor#

Number of active navigation links in the NavigationServer3D.

const NAVIGATION_POLYGON_COUNT = 28 enum Monitor#

Number of navigation mesh polygons in the NavigationServer3D.

const NAVIGATION_EDGE_COUNT = 29 enum Monitor#

Number of navigation mesh polygon edges in the NavigationServer3D.

const NAVIGATION_EDGE_MERGE_COUNT = 30 enum Monitor#

Number of navigation mesh polygon edges that were merged due to edge key overlap in the NavigationServer3D.

const NAVIGATION_EDGE_CONNECTION_COUNT = 31 enum Monitor#

Number of polygon edges that are considered connected by edge proximity NavigationServer3D.

const NAVIGATION_EDGE_FREE_COUNT = 32 enum Monitor#

Number of navigation mesh polygon edges that could not be merged in the NavigationServer3D. The edges still may be connected by edge proximity or with links.

const NAVIGATION_OBSTACLE_COUNT = 33 enum Monitor#

Number of active navigation obstacles in the NavigationServer3D.

const PIPELINE_COMPILATIONS_CANVAS = 34 enum Monitor#

Number of pipeline compilations that were triggered by the 2D canvas renderer.

const PIPELINE_COMPILATIONS_MESH = 35 enum Monitor#

Number of pipeline compilations that were triggered by loading meshes. These compilations will show up as longer loading times the first time a user runs the game and the pipeline is required.

const PIPELINE_COMPILATIONS_SURFACE = 36 enum Monitor#

Number of pipeline compilations that were triggered by building the surface cache before rendering the scene. These compilations will show up as a stutter when loading an scene the first time a user runs the game and the pipeline is required.

const PIPELINE_COMPILATIONS_DRAW = 37 enum Monitor#

Number of pipeline compilations that were triggered while drawing the scene. These compilations will show up as stutters during gameplay the first time a user runs the game and the pipeline is required.

const PIPELINE_COMPILATIONS_SPECIALIZATION = 38 enum Monitor#

Number of pipeline compilations that were triggered to optimize the current scene. These compilations are done in the background and should not cause any stutters whatsoever.

const MONITOR_MAX = 39 enum Monitor#

Represents the size of the Monitor enum.

Constructors #

Enums #

Monitor#

Operators #

Signals #

Theme Items #

Tutorials #