From 4a745aa0b8035abf69a2272ec544dc16b0b15de8 Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Sun, 12 Sep 2021 23:04:26 +0200
Subject: Improve documentation for
 `Engine.get_process_frames/get_physics_frames()`

---
 doc/classes/Engine.xml | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/doc/classes/Engine.xml b/doc/classes/Engine.xml
index 8b399f64c9..36590093bd 100644
--- a/doc/classes/Engine.xml
+++ b/doc/classes/Engine.xml
@@ -37,7 +37,7 @@
 		<method name="get_frames_drawn">
 			<return type="int" />
 			<description>
-				Returns the total number of frames drawn. If the render loop is disabled with [code]--disable-render-loop[/code] via command line, this returns [code]0[/code]. See also [method get_process_frames].
+				Returns the total number of frames drawn. On headless platforms, or if the render loop is disabled with [code]--disable-render-loop[/code] via command line, [method get_frames_drawn] always returns [code]0[/code]. See [method get_process_frames].
 			</description>
 		</method>
 		<method name="get_frames_per_second" qualifiers="const">
@@ -67,7 +67,13 @@
 		<method name="get_physics_frames" qualifiers="const">
 			<return type="int" />
 			<description>
-				Returns the total number of frames passed since engine initialization which is advanced on each [b]physics frame[/b].
+				Returns the total number of frames passed since engine initialization which is advanced on each [b]physics frame[/b]. See also [method get_process_frames].
+				[method get_physics_frames] can be used to run expensive logic less often without relying on a [Timer]:
+				[codeblock]
+				func _physics_process(_delta):
+				    if Engine.get_physics_frames() % 2 == 0:
+				        pass  # Run expensive logic only once every 2 physics frames here.
+				[/codeblock]
 			</description>
 		</method>
 		<method name="get_physics_interpolation_fraction" qualifiers="const">
@@ -79,7 +85,13 @@
 		<method name="get_process_frames" qualifiers="const">
 			<return type="int" />
 			<description>
-				Returns the total number of frames passed since engine initialization which is advanced on each [b]process frame[/b], regardless of whether the render loop is enabled. See also [method get_frames_drawn].
+				Returns the total number of frames passed since engine initialization which is advanced on each [b]process frame[/b], regardless of whether the render loop is enabled. See also [method get_frames_drawn] and [method get_physics_frames].
+				[method get_process_frames] can be used to run expensive logic less often without relying on a [Timer]:
+				[codeblock]
+				func _process(_delta):
+				    if Engine.get_process_frames() % 2 == 0:
+				        pass  # Run expensive logic only once every 2 process (render) frames here.
+				[/codeblock]
 			</description>
 		</method>
 		<method name="get_singleton" qualifiers="const">
-- 
cgit v1.2.3