From 2d027280b619a5db6be3c1a23906b27b91137f23 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Mon, 21 Nov 2022 19:37:56 +0100 Subject: [PATCH] Add a page on custom performance monitors --- about/list_of_features.rst | 3 +- .../debug/custom_performance_monitors.rst | 118 ++++++++++++++++++ tutorials/scripting/debug/debugger_panel.rst | 6 + ...om_performance_monitors_graph_example.webp | Bin 0 -> 6120 bytes tutorials/scripting/debug/index.rst | 1 + 5 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 tutorials/scripting/debug/custom_performance_monitors.rst create mode 100644 tutorials/scripting/debug/img/custom_performance_monitors_graph_example.webp diff --git a/about/list_of_features.rst b/about/list_of_features.rst index ae907396766..063fb44fea1 100644 --- a/about/list_of_features.rst +++ b/about/list_of_features.rst @@ -51,7 +51,8 @@ Editor - No support for debugging in threads yet. - Visual profiler with CPU and GPU time indications for each step of the rendering pipeline. -- Performance monitoring tools. +- Performance monitoring tools, including + :ref:`custom performance monitors `. - Live script reloading. - Live scene editing. diff --git a/tutorials/scripting/debug/custom_performance_monitors.rst b/tutorials/scripting/debug/custom_performance_monitors.rst new file mode 100644 index 00000000000..467126e400d --- /dev/null +++ b/tutorials/scripting/debug/custom_performance_monitors.rst @@ -0,0 +1,118 @@ +.. _doc_custom_performance_monitors: + +Custom performance monitors +=========================== + +Introduction +------------ + +As explained in the :ref:`doc_debugger_panel` documentation, Godot features a +**Debugger > Monitor** bottom panel that allows tracking various values with +graphs showing their evolution over time. The data for those graphs is sourced +from the engine's :ref:`class_Performance` singleton. + +Since Godot 4.0, you can declare custom values to be displayed in this Monitor +tab. Example use cases for custom performance monitors include: + +- Displaying performance metrics that are specific to your project. For + instance, in a voxel game, you could create a performance monitor to track the + number of chunks that are loaded every second. +- Displaying in-game metrics that are not strictly related to performance, but + are still useful to graph for debugging purposes. For instance, you could + track the number of enemies present in the game to make sure your spawning + mechanic works as intended. + +Creating a custom performance monitor +------------------------------------- + +In this example, we'll create a custom performance monitor to track how many +enemies are present in the currently running project. + +The main scene features a :ref:`class_Timer` node with the following script attached: + +:: + + extends Timer + + + func _ready(): + # The slash delimiter is used to determine the category of the monitor. + # If there is no slash in the monitor name, a generic "Custom" category + # will be used instead. + Performance.add_custom_monitor("game/enemies", get_enemy_count) + timeout.connect(_on_timeout) + # Spawn 20 enemies per second. + wait_time = 0.05 + start() + + + func _on_timeout(): + var enemy = preload("res://enemy.tscn").instantiate() + get_parent().add_child(enemy) + + + # This function is called every time the performance monitor is queried + # (this occurs once per second in the editor, more if called manually). + # The function must return a number greater than or equal to 0 (int or float). + func get_enemy_count(): + return get_tree().get_nodes_in_group("enemies").size() + + +The second parameter of +ref:`Performance.add_custom_monitor` +is a :ref:`class_Callable`. + +``enemy.tscn`` is a scene with a Node2D root node and Timer child node. The +Node2D has the following script attached: + +:: + + extends Node2D + + + func _ready(): + add_to_group("enemies") + $Timer.timeout.connect(_on_timer_timeout) + # Despawn enemies 2.5 seconds after they spawn. + $Timer.wait_time = 2.5 + $Timer.start() + + + func _on_timer_timeout(): + queue_free() + +In this example, since we spawn 20 enemies per second, and each enemy despawns +2.5 seconds after they spawn, we expect the number of enemies present in the +scene to stabilize to 50. We can make sure about this by looking at the graph. + +To visualize the graph created from this custom performance monitor, run the +project, switch to the editor while the project is running and open **Debugger > +Monitors** at the bottom of the editor window. Scroll down to the newly +available **Game** section and check **Enemies**. You should see a graph +appearing as follows: + +.. :figure: img/custom_performance_monitors_graph_example.webp + :align: center + :alt: Example editor graph from a custom performance monitor + + Example editor graph from a custom performance monitor + +.. note:: + + The performance monitor handling code doesn't have to live in the same + script as the nodes themselves. You may choose to move the performance + monitor registration and getter function to an :ref:`autoload + ` instead. + +Querying a performance monitor in a project +------------------------------------------- + +If you wish to display the value of the performance monitor in the running +project's window (rather than the editor), use +``Performance.get_custom_monitor("category/name")`` to fetch the value of the +custom monitor. You can display the value using a :ref:`class_Label`, +:ref:`class_RichTextLabel`, :ref:`doc_custom_drawing_in_2d`, :ref:`doc_3d_text`, +etc. + +This method can be used in exported projects as well (debug and release mode), +which allows you to create visualizations outside the editor. diff --git a/tutorials/scripting/debug/debugger_panel.rst b/tutorials/scripting/debug/debugger_panel.rst index 4b30715da45..08e5fb97525 100644 --- a/tutorials/scripting/debug/debugger_panel.rst +++ b/tutorials/scripting/debug/debugger_panel.rst @@ -68,6 +68,12 @@ FPS, memory usage, how many nodes are in a scene and more. All monitors keep track of stats automatically, so even if one monitor isn't open while the game is running, you can open it later and see how the values changed. +.. seealso:: + + In addition to the default performance monitors, you can also create + :ref:`custom performance monitors ` + to track arbitrary values in your project. + Video RAM +++++++++ diff --git a/tutorials/scripting/debug/img/custom_performance_monitors_graph_example.webp b/tutorials/scripting/debug/img/custom_performance_monitors_graph_example.webp new file mode 100644 index 0000000000000000000000000000000000000000..75743aa2a34d2bfabbe9d9f6083bb67696564f87 GIT binary patch literal 6120 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 literal 0 HcmV?d00001 diff --git a/tutorials/scripting/debug/index.rst b/tutorials/scripting/debug/index.rst index 514fe197226..a6bba65fd65 100644 --- a/tutorials/scripting/debug/index.rst +++ b/tutorials/scripting/debug/index.rst @@ -8,3 +8,4 @@ Debug overview_of_debugging_tools debugger_panel the_profiler + custom_performance_monitors