Add a keyboard shortcut to pause and perform frame-by-frame stepping when running a project from the editor

[Calinou]

Describe the project you are working on

The Godot editor 🙂

Describe the problem or limitation you are having in your project

Troubleshooting bugs in your character/AI controller scripts or physics bugs can be difficult due to the real-time nature of the simulation. When a hitch is only visible for 1/60th of a second or sometimes even less, it's hard to see what can go wrong in real-time.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Add a keyboard shortcut to perform frame-by-frame stepping when running a project from the editor.

You may have seen a feature like this in console emulators. It's pretty similar in principle.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

• Bind a default key to a built-in action that would be something like ui_advance_frame_by_frame. See the implementation of By default, bind Alt + Enter to switch between fullscreen and windowed mode #1983 for an example of this.
• When the project is not paused and the ui_advance_frame_by_frame action is pressed, pause the project.
• When the project is paused and the action is pressed, unpause the project, wait for 1 physics frame to pass then pause the project again.
• The project can be unpaused by using the Resume shortcut in the editor (symbolized as a highlighted pause icon).
  • Speaking of which, we should probably make the F7 pause toggle work while the project window is focused too, as is done with F8 already.

I'm not sure which key this should be bound by default; ideas are welcome. (Note that this shortcut will be ignored in exported projects.)

Also, we may want to add a project setting to configure the kind of frame-by-frame advance used:

• Physics (default): Waits for 1 physics frame to be simulated (1/60 of a second by default). Best used for debugging physics.
• Idle: Waits for 1 frame to be rendered. Best used for debugging visual effects, but not suited to physics unless your rendering frame rate matches your physics FPS exactly.

Alternatively, we could allow holding a modifier such as Shift to choose between the kind of frame-by-frame advance to perform.

If this enhancement will not be used often, can it be worked around with a few lines of script?

This can be implemented using an add-on. However, I expect this feature to be used relatively often in complex games where physics interactions can get dodgy when you're developing large character controllers and whatnot.

Is there a reason why this should be core and not an add-on in the asset library?

See above.

[MaaaxiKing]

This should also be a button in the debugger.

[manuq]

It was easy to prototype this in an autoload:

extends Node


func _ready():
	process_mode = Node.PROCESS_MODE_ALWAYS


func _input(event):
	if Input.is_action_pressed("pause-resume"):
		get_tree().paused = not get_tree().paused


func _process(delta):
	if Input.is_action_just_pressed("next-frame"):
		if get_tree().paused:
			get_tree().paused = false
		await get_tree().process_frame
		get_tree().paused = true

[Calinou]

Reopening, as while godotengine/godot#97257 does provide frame stepping options, it lacks a keyboard shortcut for it (especially one that works while the project window is focused).

We should also investigate process vs physics frame stepping as only one of them is exposed right now (I believe it's physics but I'm not 100% sure).