Merge pull request #78012 from Calinou/cli-add-max-fps-argument

Add a `--max-fps` command-line argument to set a FPS limit

6 files changed, 25 insertions, 2 deletions

diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml
index 4407176fd2..fcdcdc697e 100644
--- a/doc/classes/ProjectSettings.xml
+++ b/doc/classes/ProjectSettings.xml
@@ -348,6 +348,7 @@
 			If [member display/window/vsync/vsync_mode] is [code]Enabled[/code], on monitors with variable refresh rate enabled (G-Sync/FreeSync), using a FPS limit a few frames lower than the monitor's refresh rate will [url=https://blurbusters.com/howto-low-lag-vsync-on/]reduce input lag while avoiding tearing[/url].
 			If [member display/window/vsync/vsync_mode] is [code]Disabled[/code], limiting the FPS to a high value that can be consistently reached on the system can reduce input lag compared to an uncapped framerate. Since this works by ensuring the GPU load is lower than 100%, this latency reduction is only effective in GPU-bottlenecked scenarios, not CPU-bottlenecked scenarios.
 			See also [member physics/common/physics_ticks_per_second].
+			This setting can be overridden using the [code]--max-fps <fps;>[/code] command line argument (including with a value of [code]0[/code] for unlimited framerate).
 			[b]Note:[/b] This property is only read when the project starts. To change the rendering FPS cap at runtime, set [member Engine.max_fps] instead.
 		</member>
 		<member name="audio/buses/channel_disable_threshold_db" type="float" setter="" getter="" default="-60.0">
diff --git a/main/main.cpp b/main/main.cpp
index e6dd576b8a..60f04df3d5 100644
--- a/main/main.cpp
+++ b/main/main.cpp
@@ -210,6 +210,7 @@ static bool debug_paths = false;
 static bool debug_navigation = false;
 static bool debug_avoidance = false;
 #endif
+static int max_fps = -1;
 static int frame_delay = 0;
 static bool disable_render_loop = false;
 static int fixed_fps = -1;
@@ -468,7 +469,8 @@ void Main::print_help(const char *p_binary) {
 	OS::get_singleton()->print("  --debug-avoidance                 Show navigation avoidance debug visuals when running the scene.\n");
 	OS::get_singleton()->print("  --debug-stringnames               Print all StringName allocations to stdout when the engine quits.\n");
 #endif
-	OS::get_singleton()->print("  --frame-delay <ms>                Simulate high CPU load (delay each frame by <ms> milliseconds).\n");
+	OS::get_singleton()->print("  --max-fps <fps>                   Set a maximum number of frames per second rendered (can be used to limit power usage). A value of 0 results in unlimited framerate.\n");
+	OS::get_singleton()->print("  --frame-delay <ms>                Simulate high CPU load (delay each frame by <ms> milliseconds). Do not use as a FPS limiter; use --max-fps instead.\n");
 	OS::get_singleton()->print("  --time-scale <scale>              Force time scale (higher values are faster, 1.0 is normal speed).\n");
 	OS::get_singleton()->print("  --disable-vsync                   Forces disabling of vertical synchronization, even if enabled in the project settings. Does not override driver-level V-Sync enforcement.\n");
 	OS::get_singleton()->print("  --disable-render-loop             Disable render loop so rendering only occurs when called explicitly from script.\n");
@@ -1350,6 +1352,16 @@ Error Main::setup(const char *execpath, int argc, char *argv[], bool p_second_ph
 				goto error;
 			}
 
+		} else if (I->get() == "--max-fps") { // set maximum rendered FPS
+
+			if (I->next()) {
+				max_fps = I->next()->get().to_int();
+				N = I->next()->next();
+			} else {
+				OS::get_singleton()->print("Missing maximum FPS argument, aborting.\n");
+				goto error;
+			}
+
 		} else if (I->get() == "--frame-delay") { // force frame delay
 
 			if (I->next()) {
@@ -1987,6 +1999,10 @@ Error Main::setup(const char *execpath, int argc, char *argv[], bool p_second_ph
 	OS::get_singleton()->set_environment("MVK_CONFIG_LOG_LEVEL", OS::get_singleton()->_verbose_stdout ? "3" : "1"); // 1 = Errors only, 3 = Info
 #endif
 
+	if (max_fps >= 0) {
+		Engine::get_singleton()->set_max_fps(max_fps);
+	}
+
 	if (frame_delay == 0) {
 		frame_delay = GLOBAL_DEF(PropertyInfo(Variant::INT, "application/run/frame_delay_msec", PROPERTY_HINT_RANGE, "0,100,1,or_greater"), 0);
 	}
diff --git a/misc/dist/linux/godot.6 b/misc/dist/linux/godot.6
index 2481869d8a..a00a69299c 100644
--- a/misc/dist/linux/godot.6
+++ b/misc/dist/linux/godot.6
@@ -105,8 +105,11 @@ Show collisions shapes when running the scene.
 \fB\-\-debug\-navigation\fR
 Show navigation polygons when running the scene.
 .TP
+\fB\-\-max\-fps\fR <fps>
+Set a maximum number of frames per second rendered (can be used to limit power usage). A value of 0 results in unlimited framerate.
+.TP
 \fB\-\-frame\-delay\fR <ms>
-Simulate high CPU load (delay each frame by <ms> milliseconds).
+Simulate high CPU load (delay each frame by <ms> milliseconds). Do not use as a FPS limiter; use --max-fps instead.
 .TP
 \fB\-\-time\-scale\fR <scale>
 Force time scale (higher values are faster, 1.0 is normal speed).
diff --git a/misc/dist/shell/_godot.zsh-completion b/misc/dist/shell/_godot.zsh-completion
index 89fe840166..3b12fdbc22 100644
--- a/misc/dist/shell/_godot.zsh-completion
+++ b/misc/dist/shell/_godot.zsh-completion
@@ -69,6 +69,7 @@ _arguments \
   '--debug-collisions[show collision shapes when running the scene]' \
   '--debug-navigation[show navigation polygons when running the scene]' \
   '--debug-stringnames[print all StringName allocations to stdout when the engine quits]' \
+  '--frame-delay[set a maximum number of frames per second rendered (can be used to limit power usage), a value of 0 results in unlimited framerate]:maximum frames per seocnd' \
   '--frame-delay[simulate high CPU load (delay each frame by the given number of milliseconds)]:number of milliseconds' \
   '--time-scale[force time scale (higher values are faster, 1.0 is normal speed)]:time scale' \
   '--disable-vsync[disable vertical synchronization even if enabled in the project settings]' \
diff --git a/misc/dist/shell/godot.bash-completion b/misc/dist/shell/godot.bash-completion
index a7ce11e524..ba4edc4f25 100644
--- a/misc/dist/shell/godot.bash-completion
+++ b/misc/dist/shell/godot.bash-completion
@@ -72,6 +72,7 @@ _complete_godot_options() {
 --debug-collisions
 --debug-navigation
 --debug-stringnames
+--max-fps
 --frame-delay
 --time-scale
 --disable-vsync
diff --git a/misc/dist/shell/godot.fish b/misc/dist/shell/godot.fish
index ed58d8dcf6..bb4ff0b558 100644
--- a/misc/dist/shell/godot.fish
+++ b/misc/dist/shell/godot.fish
@@ -89,6 +89,7 @@ complete -c godot -l remote-debug -d "Enable remote debugging"
 complete -c godot -l debug-collisions -d "Show collision shapes when running the scene"
 complete -c godot -l debug-navigation -d "Show navigation polygons when running the scene"
 complete -c godot -l debug-stringnames -d "Print all StringName allocations to stdout when the engine quits"
+complete -c godot -l max-fps -d "Set a maximum number of frames per second rendered (can be used to limit power usage), a value of 0 results in unlimited framerate" -x
 complete -c godot -l frame-delay -d "Simulate high CPU load (delay each frame by the given number of milliseconds)" -x
 complete -c godot -l time-scale -d "Force time scale (higher values are faster, 1.0 is normal speed)" -x
 complete -c godot -l disable-render-loop -d "Disable render loop so rendering only occurs when called explicitly from script"