the_profiler.rst 7.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167
  1. .. _doc_the_profiler:
  2. The Profiler
  3. ============
  4. You run your game from Godot and play around. It's fun, it's becoming feature
  5. complete, and you feel it's getting close to release.
  6. But then, you open the skill tree, and it grinds to a halt as something snags in
  7. your code. Watching the skill tree scroll by like it's a slide show is
  8. unacceptable. What went wrong? Is it positioning the skill tree elements, the
  9. UI, or rendering?
  10. You could try to optimize everything and run the game repeatedly, but you can be
  11. smarter about this and narrow down the possibilities. Enter Godot's profiler.
  12. An overview of the profiler
  13. +++++++++++++++++++++++++++
  14. You can open the profiler by opening the **Debugger** panel and clicking on the
  15. **Profiler** tab.
  16. .. image:: img/profiler.png
  17. Godot's profiler does not automatically run because profiling is
  18. performance-intensive. It has to continually measure everything happening in the
  19. game and report back to the debugger, so it's off by default.
  20. To begin profiling, click on the **Start** button in the top-left. Run your game
  21. and data will start appearing. You can also start profiling at any time before
  22. or during gameplay, depending on if you want.
  23. .. note::
  24. The profiler does not currently support C# scripts. C# scripts can be profiled
  25. using JetBrains Rider and JetBrains dotTrace with the Godot support plugin.
  26. You can clear the data by clicking the **Clear** button anytime. Use the
  27. **Measure** drop-down menu to change the type of data you measure. The
  28. measurements panel and the graph will update accordingly.
  29. The measured data
  30. +++++++++++++++++
  31. The profiler's interface is split into two. There is a list of functions on the
  32. left and the performance graph on the right.
  33. The main measurements are frame time, physics frame, idle time, and physics time.
  34. - The **frame time** is the time it takes Godot to execute all the logic for an
  35. entire image, from physics to rendering.
  36. - **Physics frame** is the time Godot has allocated between physics updates. In
  37. an ideal scenario, the frame time is whatever you chose: 16.66 milliseconds by
  38. default, which corresponds to 60FPS. It's a frame of reference you can use for
  39. everything else around it.
  40. - **Idle time** is the time Godot took to update logic other than physics, such
  41. as code that lives in `_process` or timers and cameras set to update on
  42. **Idle**.
  43. - **Physics time** is the time Godot took to update physics tasks, like
  44. `_physics_process` and built-in nodes set to **Physics** update.
  45. .. note:: **Frame Time** includes rendering time. Say you find a mysterious
  46. spike of lag in your game, but your physics and scripts are
  47. all running fast. The delay could be due to the appearance of
  48. particles or visual effects!
  49. By default, Godot ticks on Frame Time and Physics Time. This gives you an
  50. overview of how long each frame takes relative to the allocated desired physics
  51. FPS. You can toggle functions on and off by clicking the checkboxes on the left.
  52. Other facilities make appearances as you go down the list, like Physics 2D,
  53. Physics, and Audio, before reaching Script functions, where your code appears.
  54. If you click on the graph, you change which frame's information appears on the
  55. left. In the top right, there is also a frame counter where you can manually
  56. adjust the frame you are looking at more granularly.
  57. Scope of measurement and measurement windows
  58. ++++++++++++++++++++++++++++++++++++++++++++
  59. You can change what measurement you are looking at using the **Measure**
  60. drop-down menu. By default, it starts with Frame Time and lists the time it
  61. takes to go through the frame in milliseconds. The average time is the average
  62. time any given function took when called more than once. For example, a function
  63. that took 0.05 milliseconds to run five times should give you an average of 0.01
  64. milliseconds.
  65. If accurate milliseconds count is not important, and you want to see proportions
  66. of time relative to the rest of the frame, use percentage measurements. Frame %
  67. is relative to Frame Time, and Physics % is relative to Physics Time.
  68. The last option is the scope of the time. **Inclusive** measures the time a
  69. function took **with** any nested function calls. For example:
  70. .. image:: img/split_curve.png
  71. `get_neighbors`, `find_nearest_neighbor` and `move_subject` all took a lot of
  72. time. You could be fooled into thinking that this is because all three of them
  73. are slow.
  74. But when changed to **Self**, Godot measures the time spent in the function body
  75. without considering function calls it made itself.
  76. .. image:: img/self_curve.png
  77. You can see that `get_neighbors` and `move_subject` have lost a lot of their
  78. importance. In effect, that means that `get_neighbors` and `move_subject` have
  79. spent more time waiting for some other function call to finish than not, and
  80. `find_nearest_neighbor` is **actually** slow.
  81. Debugging slow code with the profiler
  82. +++++++++++++++++++++++++++++++++++++
  83. Finding slow code with the profiler boils down to running your game and watching
  84. the performance graph as it draws. When an unacceptable spike occurs in the
  85. frame time, you can click on the graph to pause your game and narrow the _Frame
  86. #_ to the spike's start. You may need to jump back and forth between frames and
  87. functions to find the root cause.
  88. Under the Script functions, turn on the checkboxes for some functions to find
  89. which take time. These are the functions you need to review and optimize.
  90. Measuring manually in microseconds
  91. ++++++++++++++++++++++++++++++++++
  92. If your function is complex, it could be challenging to figure out which part
  93. needs optimization. Is it your math or the way you access other pieces of data
  94. to do the math with? Is it the `for` loop? The `if` statements?
  95. You can narrow down the measurement by manually counting ticks as the code runs
  96. with some temporary functions. The two functions are part of the `Time` class
  97. object. They are `get_ticks_msec` and `get_ticks_usec`. The first measures in
  98. milliseconds (1,000 per second), and the second measures in microseconds
  99. (1,000,000 per second).
  100. Either one returns the amount of time since the game engine started in their respective
  101. time frame.
  102. If you wrap a piece of code with a start and end count of microseconds, the
  103. difference between the two is the amount of time it took to run that piece of
  104. code.
  105. .. tabs::
  106. .. code-tab:: gdscript GDScript
  107. # Measuring the time it takes for worker_function() to run
  108. var start = Time.get_ticks_usec()
  109. worker_function()
  110. var end = Time.get_ticks_usec()
  111. var worker_time = (end-start)/1000000.0
  112. # Measuring the time spent running a calculation over each element of an array
  113. start = Time.get_ticks_usec()
  114. for calc in calculations:
  115. result = pow(2, calc.power) * calc.product
  116. end = Time.get_ticks_usec()
  117. var loop_time = (end-start)/1000000.0
  118. print("Worker time: %s\nLoop time: %s" % [worker_time, loop_time])
  119. As you become a more experienced programmer, this technique becomes less
  120. necessary. You begin to learn what parts of a running program are slow. Knowing
  121. that loops and branches can be slow comes from experience, and you gain
  122. experience by measuring and doing research.
  123. But between the profiler and the ticks functions, you should have enough to get
  124. started finding which parts of your code need optimization.