Performance

Inherits: Object

Exposes performance-related data.

Description

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: A few of these monitors are only available in debug mode and will always return 0 when used in a release build.

Note: Many of these monitors are not updated in real-time, so there may be a short delay between changes.

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

Methods

void

add_custom_monitor ( StringName id, Callable callable, Array arguments=[] )

Variant

get_custom_monitor ( StringName id )

Array

get_custom_monitor_names ( )

float

get_monitor ( Monitor monitor ) const

int

get_monitor_modification_time ( )

bool

has_custom_monitor ( StringName id )

void

remove_custom_monitor ( StringName id )

Enumerations

enum Monitor:

  • TIME_FPS = 0 --- Number of frames per second.

  • TIME_PROCESS = 1 --- Time it took to complete one frame, in seconds.

  • TIME_PHYSICS_PROCESS = 2 --- Time it took to complete one physics frame, in seconds.

  • MEMORY_STATIC = 3 --- Static memory currently used, in bytes. Not available in release builds.

  • MEMORY_STATIC_MAX = 4 --- Available static memory. Not available in release builds.

  • MEMORY_MESSAGE_BUFFER_MAX = 5 --- Largest amount of memory the message queue buffer has used, in bytes. The message queue is used for deferred functions calls and notifications.

  • OBJECT_COUNT = 6 --- Number of objects currently instantiated (including nodes).

  • OBJECT_RESOURCE_COUNT = 7 --- Number of resources currently used.

  • OBJECT_NODE_COUNT = 8 --- Number of nodes currently instantiated in the scene tree. This also includes the root node.

  • OBJECT_ORPHAN_NODE_COUNT = 9 --- Number of orphan nodes, i.e. nodes which are not parented to a node of the scene tree.

  • RENDER_TOTAL_OBJECTS_IN_FRAME = 10

  • RENDER_TOTAL_PRIMITIVES_IN_FRAME = 11

  • RENDER_TOTAL_DRAW_CALLS_IN_FRAME = 12

  • RENDER_VIDEO_MEM_USED = 13 --- The amount of video memory used, i.e. texture and vertex memory combined.

  • RENDER_TEXTURE_MEM_USED = 14 --- The amount of texture memory used.

  • RENDER_BUFFER_MEM_USED = 15

  • PHYSICS_2D_ACTIVE_OBJECTS = 16 --- Number of active RigidDynamicBody2D nodes in the game.

  • PHYSICS_2D_COLLISION_PAIRS = 17 --- Number of collision pairs in the 2D physics engine.

  • PHYSICS_2D_ISLAND_COUNT = 18 --- Number of islands in the 2D physics engine.

  • PHYSICS_3D_ACTIVE_OBJECTS = 19 --- Number of active RigidDynamicBody3D and VehicleBody3D nodes in the game.

  • PHYSICS_3D_COLLISION_PAIRS = 20 --- Number of collision pairs in the 3D physics engine.

  • PHYSICS_3D_ISLAND_COUNT = 21 --- Number of islands in the 3D physics engine.

  • AUDIO_OUTPUT_LATENCY = 22 --- Output latency of the AudioServer.

  • MONITOR_MAX = 23 --- Represents the size of the Monitor enum.

Method Descriptions

Adds a custom monitor with name same as id. You can specify the category of monitor using '/' in id. If there are more than one '/' then default category is used. Default category is "Custom".

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

The debugger calls the callable to get the value of custom monitor. The callable must return a number.

Callables are called with arguments supplied in argument array.

Note: It throws an error if given id is already present.


Returns the value of custom monitor with given id. The callable is called to get the value of custom monitor.

Note: It throws an error if the given id is absent.


  • Array get_custom_monitor_names ( )

Returns the names of active custom monitors in an array.


Returns the value of one of the available monitors. You should provide one of the Monitor constants as the argument, like this:

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

  • int get_monitor_modification_time ( )

Returns the last tick in which custom monitor was added/removed.


Returns true if custom monitor with the given id is present otherwise returns false.


Removes the custom monitor with given id.

Note: It throws an error if the given id is already absent.