From ce2a7f32537ecf6c275194d2bb962d417d2781c2 Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Tue, 12 Dec 2023 13:10:16 +0100
Subject: [PATCH] Document `AudioServer.playback_speed_scale` in
 `Engine.time_scale`

This also documents `physics_ticks_per_second` not being automatically
adjusted, which can be important when speeding up simulation.
---
 doc/classes/AudioServer.xml | 2 +-
 doc/classes/Engine.xml      | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/classes/AudioServer.xml b/doc/classes/AudioServer.xml
index 21ad817c6c9a..5b3fcd67d484 100644
--- a/doc/classes/AudioServer.xml
+++ b/doc/classes/AudioServer.xml
@@ -311,7 +311,7 @@
 			Name of the current device for audio output (see [method get_output_device_list]). On systems with multiple audio outputs (such as analog, USB and HDMI audio), this can be used to select the audio output device. The value [code]"Default"[/code] will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to [code]"Default"[/code].
 		</member>
 		<member name="playback_speed_scale" type="float" setter="set_playback_speed_scale" getter="get_playback_speed_scale" default="1.0">
-			Scales the rate at which audio is played (i.e. setting it to [code]0.5[/code] will make the audio be played at half its speed).
+			Scales the rate at which audio is played (i.e. setting it to [code]0.5[/code] will make the audio be played at half its speed). See also [member Engine.time_scale] to affect the general simulation speed, which is independent from [member AudioServer.playback_speed_scale].
 		</member>
 	</members>
 	<signals>
diff --git a/doc/classes/Engine.xml b/doc/classes/Engine.xml
index 207cd0bccc73..0a544077e43e 100644
--- a/doc/classes/Engine.xml
+++ b/doc/classes/Engine.xml
@@ -307,6 +307,8 @@
 		</member>
 		<member name="time_scale" type="float" setter="set_time_scale" getter="get_time_scale" default="1.0">
 			Controls how fast or slow the in-game clock ticks versus the real life one. It defaults to 1.0. A value of 2.0 means the game moves twice as fast as real life, whilst a value of 0.5 means the game moves at half the regular speed. This also affects [Timer] and [SceneTreeTimer] (see [method SceneTree.create_timer] for how to control this).
+			[b]Note:[/b] This does not affect audio playback speed. Use [member AudioServer.playback_speed_scale] to adjust audio playback speed independently of [member Engine.time_scale].
+			[b]Note:[/b] This does not automatically adjust [member physics_ticks_per_second], which means that with time scales above 1.0, physics simulation may become less precise (as each physics tick will stretch over a larger period of engine time). If you're using [member Engine.time_scale] to speed up simulation by a large factor, consider increasing [member physics_ticks_per_second] as well to improve physics reliability.
 		</member>
 	</members>
 </class>