Index · Object → Performance

Performance

Exposes performance-related data.

Class 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: 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.

Methods

func add_custom_monitor(id: StringName, callable: Callable, arguments: Array = [], type: Performance.MonitorType = 0) -> void

Adds a custom monitor with the name id. You can specify the category of the monitor using slash delimiters in id (for example: "Game/NumberOfNPCs"). If there is more than one slash delimiter, then the default category is used. The default category is "Custom". Prints an error if given id is already present.

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 zero or positive integer or floating-point number.

Callables are called with arguments supplied in argument array.

func get_custom_monitor(id: StringName) -> Variant

Returns the value of custom monitor with given id. The callable is called to get the value of custom monitor. See also has_custom_monitor(). Prints an error if the given id is absent.

func get_custom_monitor_names() -> StringName[]

Returns the names of active custom monitors in an Array.

func get_custom_monitor_types() -> PackedInt32Array

Returns the MonitorType values of active custom monitors in an Array.

func get_monitor(monitor: Performance.Monitor) -> float

Returns the value of one of the available built-in 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.

See get_custom_monitor() to query custom performance monitors' values.

func get_monitor_modification_time() -> int

Returns the last tick in which custom monitor was added/removed (in microseconds since the engine started). This is set to Time.get_ticks_usec() when the monitor is updated.

func has_custom_monitor(id: StringName) -> bool

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

func remove_custom_monitor(id: StringName) -> void

Removes the custom monitor with given id. Prints an error if the given id is already absent.

Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Object (2)

Enums & Constants

enum Monitor
TIME_FPS = 0

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.

TIME_PROCESS = 1

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

TIME_PHYSICS_PROCESS = 2

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

TIME_NAVIGATION_PROCESS = 3

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

MEMORY_STATIC = 4

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

MEMORY_STATIC_MAX = 5

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

MEMORY_MESSAGE_BUFFER_MAX = 6

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.

OBJECT_COUNT = 7

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

OBJECT_RESOURCE_COUNT = 8

Number of resources currently used. Lower is better.

OBJECT_NODE_COUNT = 9

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

OBJECT_ORPHAN_NODE_COUNT = 10

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

Note: This is only available in debug mode and will always return 0 when used in a project exported in release mode.

RENDER_TOTAL_OBJECTS_IN_FRAME = 11

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.

RENDER_TOTAL_PRIMITIVES_IN_FRAME = 12

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.

RENDER_TOTAL_DRAW_CALLS_IN_FRAME = 13

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.

RENDER_VIDEO_MEM_USED = 14

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.

RENDER_TEXTURE_MEM_USED = 15

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

RENDER_BUFFER_MEM_USED = 16

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

PHYSICS_2D_ACTIVE_OBJECTS = 17

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

PHYSICS_2D_COLLISION_PAIRS = 18

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

PHYSICS_2D_ISLAND_COUNT = 19

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

PHYSICS_3D_ACTIVE_OBJECTS = 20

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

PHYSICS_3D_COLLISION_PAIRS = 21

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

PHYSICS_3D_ISLAND_COUNT = 22

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

AUDIO_OUTPUT_LATENCY = 23

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

NAVIGATION_ACTIVE_MAPS = 24

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

NAVIGATION_REGION_COUNT = 25

Number of active navigation regions in NavigationServer2D and NavigationServer3D.

NAVIGATION_AGENT_COUNT = 26

Number of active navigation agents processing avoidance in NavigationServer2D and NavigationServer3D.

NAVIGATION_LINK_COUNT = 27

Number of active navigation links in NavigationServer2D and NavigationServer3D.

NAVIGATION_POLYGON_COUNT = 28

Number of navigation mesh polygons in NavigationServer2D and NavigationServer3D.

NAVIGATION_EDGE_COUNT = 29

Number of navigation mesh polygon edges in NavigationServer2D and NavigationServer3D.

NAVIGATION_EDGE_MERGE_COUNT = 30

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

NAVIGATION_EDGE_CONNECTION_COUNT = 31

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

NAVIGATION_EDGE_FREE_COUNT = 32

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

NAVIGATION_OBSTACLE_COUNT = 33

Number of active navigation obstacles in the NavigationServer2D and NavigationServer3D.

PIPELINE_COMPILATIONS_CANVAS = 34

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

PIPELINE_COMPILATIONS_MESH = 35

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.

PIPELINE_COMPILATIONS_SURFACE = 36

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 a scene the first time a user runs the game and the pipeline is required.

PIPELINE_COMPILATIONS_DRAW = 37

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.

PIPELINE_COMPILATIONS_SPECIALIZATION = 38

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.

NAVIGATION_2D_ACTIVE_MAPS = 39

Number of active navigation maps in the NavigationServer2D. This also includes the empty default navigation maps created by World2D instances.

NAVIGATION_2D_REGION_COUNT = 40

Number of active navigation regions in the NavigationServer2D.

NAVIGATION_2D_AGENT_COUNT = 41

Number of active navigation agents processing avoidance in the NavigationServer2D.

NAVIGATION_2D_LINK_COUNT = 42

Number of active navigation links in the NavigationServer2D.

NAVIGATION_2D_POLYGON_COUNT = 43

Number of navigation mesh polygons in the NavigationServer2D.

NAVIGATION_2D_EDGE_COUNT = 44

Number of navigation mesh polygon edges in the NavigationServer2D.

NAVIGATION_2D_EDGE_MERGE_COUNT = 45

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

NAVIGATION_2D_EDGE_CONNECTION_COUNT = 46

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

NAVIGATION_2D_EDGE_FREE_COUNT = 47

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

NAVIGATION_2D_OBSTACLE_COUNT = 48

Number of active navigation obstacles in the NavigationServer2D.

NAVIGATION_3D_ACTIVE_MAPS = 49

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

NAVIGATION_3D_REGION_COUNT = 50

Number of active navigation regions in the NavigationServer3D.

NAVIGATION_3D_AGENT_COUNT = 51

Number of active navigation agents processing avoidance in the NavigationServer3D.

NAVIGATION_3D_LINK_COUNT = 52

Number of active navigation links in the NavigationServer3D.

NAVIGATION_3D_POLYGON_COUNT = 53

Number of navigation mesh polygons in the NavigationServer3D.

NAVIGATION_3D_EDGE_COUNT = 54

Number of navigation mesh polygon edges in the NavigationServer3D.

NAVIGATION_3D_EDGE_MERGE_COUNT = 55

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

NAVIGATION_3D_EDGE_CONNECTION_COUNT = 56

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

NAVIGATION_3D_EDGE_FREE_COUNT = 57

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.

NAVIGATION_3D_OBSTACLE_COUNT = 58

Number of active navigation obstacles in the NavigationServer3D.

MONITOR_MAX = 59

Represents the size of the Monitor enum.

enum MonitorType
MONITOR_TYPE_QUANTITY = 0

Monitor output is formatted as an integer value.

MONITOR_TYPE_MEMORY = 1

Monitor output is formatted as computer memory. Submitted values should represent a number of bytes.

MONITOR_TYPE_TIME = 2

Monitor output is formatted as time in milliseconds. Submitted values should represent a time in seconds (not milliseconds).

MONITOR_TYPE_PERCENTAGE = 3

Monitor output is formatted as a percentage. Submitted values should represent a fractional value rather than the percentage directly, e.g. 0.5 for 50.00%.