Add "Game" editor for better runtime debugging

[YeldhamDev]

Implements several aspects of godotengine/godot-proposals#7213.

2024-09-20.19-19-42.mp4

Features Implemented

• Selection of 2D/3D nodes at runtime when the game is suspended (see below), this includes anything that has collisions or some sort of visual representation. When a node is selected, a selection box will appear around it and it will be opened in the inspector.
• Suspend mode. This is a middle ground between in-game pausing and the editor's break feature. When this mode is enabled, it allows node selection, and frame skipping.
• Next frame. This allows the game to run one frame at the time when the it's suspended.
  • Production edit: This closes Add a keyboard shortcut to pause and perform frame-by-frame stepping when running a project from the editor  godot-proposals#3105.
• 2D/3D camera override. The camera manipulation can come from within the game, or the 2D and 3D editors.

Things Missing

• Window embedding. This requires low-level OS-specific code, that's above my league.

Limitations

• For now, selection only works in the root window. This is not a hard limitation, and selection in subwindows could be implemented as well.
• No editor theming for the selection boxes and popup list, as well as no shortcut redefinition for camera controls, since we can't access those values at runtime. A possible workaround would be to pass those settings via the debugger.

Compatibility Break

• A minor one is unavoidable to add this new editor to the feature profile.

Sponsored By: 🐺 Lone Wolf Technology / 🍀 W4 Games.

[JoNax97]

This is excellent!

One small detail I think would be neat is to freeze the time parameter in shaders while the game is suspended, so that the effects don't continue animating and the 'next frame' button allows for shader debugging

[YeldhamDev]

@JoNax97 Done!

[RobProductions]

Finally, this is incredible work and I'm really excited to see this merged! Thank you so much! A few questions:

1. I can't tell from the video but does the click selection also work to highlight the tree item in the "remote" tab? I see it selects the remote note in the inspector which is great but it would also be cool to quickly navigate a complex hierarchy by selecting stuff, which would quickly unfold the parent items. I believe I've seen a plugin do this recently.
2. Would it possible to separate the "suspend" mode from the click selection so that users can click on things while the game is not paused? Like maybe with a separate toggle to activate a selection mode instead of being tied to suspend? I think this was something mentioned in the original proposal with the "selection mode", and being able to click on (and eventually edit I presume) nodes while the game is running could save a lot of time for realtime tech demos (like cloth physics demos as an example) that would otherwise have to implement their own selection tools. I'm also imagining a debug camera being the next step here and that might fit better in a selection mode rather than suspend mode because you could take a look at something more closely while its in motion/changing instead of having to unpause and repause and find that exact spot again.
3. Finally, and this may be a big ask, but is there potential for users to extend the functionality of these new runtime tools with custom code? For example, if there was never a PR for changing camera in pause mode, a user might want to code their own camera system that hooks into the new suspend code. But since I noticed that the can_process method now checks for suspend status, no user code can be run while the game is paused. This makes sense as a quick way to halt scripts but it would be neat to allow some way to customize how the tools work, though I'm not exactly sure how. On that note, it would also be great to get a signal for suspend and unsuspend to coincide with the notifications, that way at least user code can run when the mode starts and stops :)

I don't think all of that necessarily needs to go in this PR but just curious about the future of this feature. Regardless, I really appreciate what you have so far!

[YeldhamDev]

@RobProductions

1. Yes! And clicking an item in the remote tree also highlights the node in the game as well.
2. Internally we settled to make selection only available when suspended, as the inputs of clicking around would clash with in-game code.
3. This sort of stuff would need to have its own proposal opened for discussion, as this is beyond the scope of this PR.

[m4gr3d]

Great work!

I'm curious how this would behave for an XR project.. would it be possible to disable the Game tab for an XR project but keep the functionality shown in the video?
cc @BastiaanOlij

Also I'm curious if this would work with the Android editor. Have you tested this PR with the Android editor?

[Faless]

3. Finally, and this may be a big ask, but is there potential for users to extend the functionality of these new runtime tools with custom code? For example, if there was never a PR for changing camera in pause mode, a user might want to code their own camera system that hooks into the new suspend code. But since I noticed that the can_process method now checks for suspend status, no user code can be run while the game is paused.

@RobProductions I haven't checked the code yet, but like this PR is doing, you can have your own code evaluated outside of process (even during debug breaks), by registering a capture in EngineDebugger and implementing a EditorDebuggerPlugin to communicate with it.

[Chaosus]

Nice work, I would like to see more controls for the interacted objects (in Unity you can move, rotate, scale in this mode?), maybe some new buttons needs to be introduced for this.

[KoBeWi]

• Sometimes the suspend button is stuck disabled:

fbq8107lZ3.mp4

This happens after running the project a couple of times and requires restarting editor to fix.

EDIT:
Seems to happen when you F8 to close the game. Looking at the implementation, maybe session counter is broken.

EDIT2:
Yep, F8 closes the session twice and makes the counter go negative permanently.

• The selection popup appears at wrong position. Seems to be relative to "Game" position.

godot.windows.editor.dev.x86_64_BOfYg60Jin.mp4

• It would be useful to have in-game shortcut for next frame. Clicking a button isn't always convenient.

[someThrowAway1900]

I can't seem to get this to work properly. Is there a setting that I need to set somewhere?

When I launch the game it is not always on top, and with the same position/size as per the viewport. Clicking the editor brings the editor window to the front and hides the game window. This is on windows 10.

[ettiSurreal]

I can't seem to get this to work properly. Is there a setting that I need to set somewhere?

When I launch the game it is not always on top, and with the same position/size as per the viewport. Clicking the editor brings the editor window to the front and hides the game window. This is on windows 10.

Go in the project settings, turn on Advanced Settings, look for Display > Window and turn on the appropriately named Always on Top.
Though if embedding doesn't make it in before 4.4 stable the game editor should override that setting because without that on the tab is unusably clunky.

[arkology]

Though if embedding doesn't make it in before 4.4 stable the game editor should override that setting because without that on the tab is unusably clunky.

But then #70792 will become extremely annoying.

[allenwp]

Congrats on this 🎉 I'm very impressed and grateful for your work, @YeldhamDev!

[ryevdokimov]

@jcostello The ideal would be to make the current gizmo code from the editor work at runtime as well, but that would be a heavy task as it's written specifically to work within the editor itself.

Might be a stupid idea but having worked on an "alternative" pathway for this kind of functionality in godotengine/godot-proposals#9142, it sounds like a possible inevitable progression is just the play button runs another (slightly modified) instance of the Godot editor that can run the scenes in process like in the proposal.

This would result in a kind of hybrid with godotengine/godot-proposals#7213, with embedding coming free, and if you crash the "nested" editor it's no big deal. The beauty of the editor itself is that it's very lightweight, and going this route kind of helps dogfooding the editor just like the Godot's own UI.

Just food for thought.

Edit: Also, I think the idea of having the editor run on the game engine, but the debug runtime runs on the editor is pretty funny. See: https://docs.godotengine.org/en/stable/getting_started/introduction/godot_design_philosophy.html#the-godot-editor-is-a-godot-game

[allenwp]

@Jesusemora It will be optional. And embedded or not, you will not need to worry about crashing, as in either mode the game still runs in a separate process.

I'm not sure what your thoughts on this are, but I've shared an idea that will likely be related to this here: #99010 (comment)

[allenwp]

Now that this new Game workspace has been merged, I've updated my existing proposal relating to focusing/centering on selected remote nodes: godotengine/godot-proposals#8130

Because 3D camera movements are made much easier by focusing (especially zooming and orbiting), I believe this proposal is even more important now that the Game workspace has been implemented.

[geowarin]

It would be really handy if the game toolbar actions had configurable shortcuts (suspend in particular).

[JohnnyKeolot]

Game mode doesn't work for me on Windows 10, the game doesn't show up. Am I doing something wrong?

[Chaosus]

Game mode doesn't work for me on Windows 10, the game doesn't show up. Am I doing something wrong?

You need to press a play button (F5) to run a game. It's a bit counter-intuitive.

[JohnnyKeolot]

Game mode doesn't work for me on Windows 10, the game doesn't show up. Am I doing something wrong?

You need to press a play button (F5) to run a game. It's a bit counter-intuitive.

If I press play (F5), the window opens as usual. The window is not embedded in the editor

[Chaosus]

If I press play (F5), the window opens as usual. The window is not embedded in the editor

Yes, this is the current limitation. You can only interact with a non-embedded game window, at least until #99010 got merged.

[JohnnyKeolot]

If I press play (F5), the window opens as usual. The window is not embedded in the editor

Yes, this is the current limitation. You can only interact with a non-embedded game window, at least until #99010 got merged.

Thank you!

[Comdfsfsfas]

@YeldhamDev
If you want to embed the running window into the engine, you can refer to this plug-in:https://fabimakesgames.itch.io/embedgame

[Arnklit]

@Comdfsfsfas there is already a PR for embedding it. #99010

[Comdfsfsfas]

But I have always wanted to know, why not embed the runtime window into the 3D window, but open a new Game window. In fact, you can display the debugging tool on the 3D viewport during runtime (I think this is better)

[allenwp]

But I have always wanted to know, why not embed the runtime window into the 3D window, but open a new Game window. In fact, you can display the debugging tool on the 3D viewport during runtime (I think this is better)

If you're meaning you'd like to have both the playable game and the embedded game workspace viewable and interactive at the same time, this proposal is a good place for discussion: godotengine/godot-proposals#11091

[vlcoo]

I've tried my best on looking for a mention of this both in this PR and the related proposal, and I didn't find any discussion that answered my doubt, so:

I feel like the new "Suspend" button in the Game tab is pretty redundant (at least in the still dev version I tested) and clashes nastily with the existing Pause feature at the very top right. I couldn't see any difference in functionality, and some odd counterintuitive cases appeared like having the game Paused but not Suspended, or having it both Paused and Suspended. I still don't quite understand that. Is it going to be developed further, and I'm a bit too early perhaps?

[KoBeWi]

You can't use picking when the app is stopped with the debugger's pause, because it's completely frozen.
The new Game pausing is implemented as forced pause at SceneTree level. It stops all processing, but you can still interact with the app.

[allenwp]

I feel like the new "Suspend" button in the Game tab is pretty redundant (at least in the still dev version I tested) and clashes nastily with the existing Pause feature at the very top right.

I think there might be a usability issue with using the same icon for both pause and suspend, given they do different things.

One idea that comes to mind is something about a stopped/paused clock that gives the idea that we are pausing time in the game when it is suspended, rather than pausing all rendering and interactivity. Maybe a clock with a pause icon over top of it. Not sure if this idea can be turned into a good looking icon. Also not sure if it makes sense to anyone else.

Maybe someone else has an idea of what a unique suspend icon could be…

[Zireael07]

I think there might be a usability issue with using the same icon for both pause and suspend, given they do different things.

Agreed.

[peerlessblue]

I feel like the new "Suspend" button in the Game tab is pretty redundant (at least in the still dev version I tested) and clashes nastily with the existing Pause feature at the very top right.

I think there might be a usability issue with using the same icon for both pause and suspend, given they do different things.

One idea that comes to mind is something about a stopped/paused clock that gives the idea that we are pausing time in the game when it is suspended, rather than pausing all rendering and interactivity. Maybe a clock with a pause icon over top of it. Not sure if this idea can be turned into a good looking icon. Also not sure if it makes sense to anyone else.

Maybe someone else has an idea of what a unique suspend icon could be…

Maybe a snowflake? If I understand the difference in functionality correctly….

[vlcoo]

You can't use picking when the app is stopped with the debugger's pause

Ok thanks, I understand the justification now. A part of me still wishes that it was possible to pick nodes when Paused (so a Suspend isn't needed), but I'm getting way ahead of myself - maybe a different time.

Maybe a snowflake?

That being said, I really like the idea of giving the button a different icon, and a snowflake representing "freeze (the game)" feels clear enough to me. Just wanted to add that I believe a tooltip on the button describing the use of the feature would avoid confusions even more.