Add support for embedding subwindows and dual screen GameViews

[RobProductions]

Closes godotengine/godot-proposals#11091

Thanks to guidance from @Hilderin this PR adds two new features to the Game tab and embedding tools that were introduced in Godot 4.4. The first change extends the embedding functionality to allow embedding of "subwindows" (as they're known in DisplayServer) when provided with a unique window name. The user can now select whether to embed the main window or a custom window that matches the name provided via a text box in the GameView:

Capture2025-03-12.13-46-20.mov

This allows developers of multi-window games to embed the game window that makes the most sense for their project rather than being stuck with the main window. This is accomplished through modifications to the display server so that a subwindow can be parented much the same as the main window. In order to send the parenting data to the built game, a new --swid (subwindow ID) command line parameter was created that matches the --wid implementation for the main window. Then, when the GameView modifies the instance parameters, it can optionally send the --swid with the user provided window name.

As suggested by @Hilderin , I took the next step in the proposal to better utilize subwindow embedding here by adding an option to split the Game tab into two GameViews for better visibility while debugging. This was largely done by splitting out functionality that used to be handled by the GameView into the GameViewPlugin and having the plugin manage two instances, but all together it works pretty cleanly! A button in the embed options popup lets you split the view and the layout is saved as project metadata, with the default setting being the regular single view that people are familiar with:

Capture2025-03-12.13-58-35.mov

Since this PR was already looking like a lot to review, one step I left for a future PR was getting the secondary view's game debugger working properly. This proved challenging to do immediately because we would either need to make the RuntimeSelect stuff not a singleton or we'd need to pass window data through every message sent via the debugger, but I'm certain that one of these solutions will be easier to work out when this initial PR is wrapped up. Besides that, the regular debugger controls for the main GameView are still fully functional:

Capture2025-03-12.14-02-01.mov

Note: This PR only implements subwindow embedding for the Windows display server. Sadly I don't have a Linux machine to test on but Hilderin said it was fine to leave it like this so that a follow up PR can tackle the Linux/Android support which I believe shouldn't be too tough to match from Windows.

Thank you to everyone who offered ideas about the future of embedding in #99010 and I hope this new functionality proves to be helpful for developers looking for more debugging options! Let me know if there's anything I've missed and I'll be happy to make adjustments :)

[RobProductions]

Rebased to handle the new mute audio button. Like the other debugger controls, it works the same as before on the main game view and is hidden on the secondary view for now to prevent confusion :)

[RobProductions]

Rebased to handle the feature profile changes. Thanks to the update, there are less #ifdef checks now in the new logic

[YeldhamDev]

On my end (Fedora 41 GNU/Linux), this breaks a few things:

• Clicking the "Game" tab doesn't focus the window when floating is enabled, instead it switches to it, in a blank state.
• Running with "Custom Window" makes so that no window is embedded at all.

[RobProductions]

• Clicking the "Game" tab doesn't focus the window when floating is enabled, instead it switches to it, in a blank state.

Thanks for trying it out, you're right that this became broken somehow. It was working correctly when I first created the PR but somewhere along rebasing it got messed up, so it should be an easy fix!

• Running with "Custom Window" makes so that no window is embedded at all.

You mean setting the dropdown to "Custom Window" and leaving the title blank? On Windows it results in the Main Window getting embedded:

Note that I haven't implemented subwindow embedding on Linux, but this "empty title" case should give the same result because currently Linux should always embed the main window (only the displayserver signatures were changed). If this is what's happening, I might need to look into this further and get some help testing on Linux.

However, if you put some string into the custom window title field then this might be the expected result on Linux until someone (probably @Hilderin ) matches the Windows implementation and verifies it in a future PR :)

[YeldhamDev]

I see. Then this leaves only the empty "Game" tab then.
However, until the implementation for GNU/Linux is made, it should ignore the behavior and just keep embedding the root window for now.

[RobProductions]

@YeldhamDev Understood. I've updated the code to fix the tab switching issue now, and introduced a new Display Server feature called FEATURE_SUBWINDOW_EMBEDDING to handle the difference on Linux and other platforms that haven't caught up yet. The easiest path was to just hide the window selector dropdown and enforce GameView to always embed the main view, hopefully that works as a stopgap for now. Note for whoever implements the Linux side of things: you'll need to first enable the feature in the X11 display server code in order to test subwindow embedding properly.

Feel free to give a try and let me know if this looks better!

[YeldhamDev]

You should probably hide the dual view option as well.

[deralmas]

I've updated the code to fix the tab switching issue now, and introduced a new Display Server feature called FEATURE_SUBWINDOW_EMBEDDING to handle the difference on Linux and other platforms that haven't caught up yet.

That's really nice, I support this! I'm working on window embedding on Wayland and being able to not immediately implement subwindow embedding without breaking the editor would be very nice.

[RobProductions]

Apologies for the delay, I've rebased the branch now and also updated the code to disable the dual screen options if FEATURE_SUBWINDOW_EMBEDDING is false. So now there should basically be no change on platforms other than Windows until we update the display server. @YeldhamDev feel free to check it out and let me know if this looks good :)

[YeldhamDev]

The issues I pointed out were fixed. Still, it's better if someone on a platform where this feature is implemented would give a proper review.

[jaydensipe]

Hey, love the idea of this PR and have been messing around with it, and it works well. A couple of things I wanted to open for discussion.

1. The idea of having a horizontal layout to the windows. I went ahead and implemented this in my branch (jaydensipe@51a6331) if you wanted to use the code and include it in this commit or just use it as a reference (or as a separate PR).

Screen.Recording.2025-05-01.214221.mp4

2. I think I saw you mention this somewhere but I can't remember, but having another option to Main Window and Custom Window being Debug Window that will automatically create a Window and add a Camera to the main scene. I think having it automatically do it for the user will make this feature easier for people to use.
3. This one is probably beyond just a suggestion, but in addition to the Debug Window, I wonder if we could have a Scene View option, which would show the Scene viewport, like Unity. No idea if this is actually technically possible at this point, but something to wonder about. Something like this (mockup):

I may play around with 2 and 3, but just wanted to post here just incase.

[RobProductions]

The idea of having a horizontal layout to the windows. I went ahead and implemented this in my branch (jaydensipe@51a6331) if you wanted to use the code and include it in this commit or just use it as a reference (or as a separate PR).

Wow, this is awesome, thank you so much! I think is really useful and had considered it a while ago but tried to keep the scope down for my initial attempt haha. Would be nice to have it in for this PR! If you'd like, I can paste in your changes to this commit and add you as a co-author? That seems the easiest path for me, or if you have another idea/want your own PR that works too.

I think I saw you mention this somewhere but I can't remember, but having another option to Main Window and Custom Window being Debug Window that will automatically create a Window and add a Camera to the main scene. I think having it automatically do it for the user will make this feature easier for people to use.

Yup it was discussed in the proposal here: godotengine/godot-proposals#11091 The work needed for that is definitely something a future PR should handle, but I've got ideas on how to tackle it after this. In short, we could send a debugger signal to create a Window Node with a custom name and reuse the embedded subwindow functionality to set the intended window name to that window. Next step after that would be activating the debugger for the top view so that either can be used for debugging, but that definitely requires a new PR. We'd either need to make the game debugger code instantiable (so there can be 2 copies of it) or send the window name along with each signal so that the debugger can act depending on which view the user interacted with; either option should work from what I can tell.

This one is probably beyond just a suggestion, but in addition to the Debug Window, I wonder if we could have a Scene View option, which would show the Scene viewport, like Unity. No idea if this is actually technically possible at this point, but something to wonder about. Something like this (mockup):

I could see that being useful, though users have to make sure they don't confuse the Scene View with the debug view - I'm thinking eventually (hopefully) we will have a lot of the same tools for runtime editing like the transform gizmos, so it will be important to distinguish them for beginners who may expect the Scene View to also work in runtime like in Unity. Side note: if it was up to me, I'd prefer an approach different than window embedding in the first place to get the editor tools at runtime, but considering this is what we've got, I'll work with it lol.

Anyways, I think the long term solution to this would be something like godotengine/godot-proposals#7233 where any viewport can be moved to any position, including the game tab views and 3D plugin so that users can make any layout they want. This is a lot of work but honestly it would probably be better to look into this than to try and figure out all the combinations of side-by-side windows that users might want. That's just my personal take though and if it's too far away, we can work with these alternatives for now

[jaydensipe]

If you'd like, I can paste in your changes to this commit and add you as a co-author?

Sure, that would be awesome!

Yup it was discussed in the proposal here: godotengine/godot-proposals#11091 The work needed for that is definitely something a future PR should handle, but I've got ideas on how to tackle it after this. In short, we could send a debugger signal to create a Window Node with a custom name and reuse the embedded subwindow functionality to set the intended window name to that window. Next step after that would be activating the debugger for the top view so that either can be used for debugging, but that definitely requires a new PR. We'd either need to make the game debugger code instantiable (so there can be 2 copies of it) or send the window name along with each signal so that the debugger can act depending on which view the user interacted with; either option should work from what I can tell.

I could see that being useful, though users have to make sure they don't confuse the Scene View with the debug view - I'm thinking eventually (hopefully) we will have a lot of the same tools for runtime editing like the transform gizmos, so it will be important to distinguish them for beginners who may expect the Scene View to also work in runtime like in Unity. Side note: if it was up to me, I'd prefer an approach different than window embedding in the first place to get the editor tools at runtime, but considering this is what we've got, I'll work with it lol.

Anyways, I think the long term solution to this would be something like godotengine/godot-proposals#7233 where any viewport can be moved to any position, including the game tab views and 3D plugin so that users can make any layout they want. This is a lot of work but honestly it would probably be better to look into this than to try and figure out all the combinations of side-by-side windows that users might want. That's just my personal take though and if it's too far away, we can work with these alternatives for now

Alright, sweet. Sounds like we share the same hope that we get those debugging gizmos, etc. This PR definitely takes us one step closer. Being able to have the more modular editor would be sick, but I bet you this horizontal/vertical two window setup is what almost all users will end up using anyways (of course that could be completely false lol).

[RobProductions]

I've now added in the horizontal split feature from @jaydensipe and it works great! Thanks again for contributing 😄

Capture2025-05-02.14-59-07.mov

One tiny caveat is the limited space on the top bar which locks the minimum size of the right view while in the horizontal mode, and I can only imagine that this will get worse as we add more debugging buttons. This seems to be a general problem with the Godot editor viewports (I've noticed it in other editor windows too) and I'm not exactly sure what the solution is, but that's a future concern we can reevaluate later.

[jaydensipe]

One tiny caveat is the limited space on the top bar which locks the minimum size of the right view while in the horizontal mode, and I can only imagine that this will get worse as we add more debugging buttons. This seems to be a general problem with the Godot editor viewports (I've noticed it in other editor windows too) and I'm not exactly sure what the solution is, but that's a future concern we can reevaluate later.

Good point. I wanna say later we could maybe chop off the "multi selection" tool, since it's already a shortcut on the "selection" tool, but not sure.

[RobProductions]

@AThousandShips thanks for the review! I've updated the branch with all of your requested changes and rebased it, so feel free to let me know if this is good and if there's anything else I should adjust

[RobProductions]

It took some trial and error with the CI but I've rebased the branch to account for the MacOS embedding that was added in #105884 . Like the other platforms, since the mac display server does not set the FEATURE_SUBWINDOW_EMBEDDING yet, the window selector & dual screen option won't show up there. Hopefully this gets another review and can be merged soon since it's a becoming a larger effort to keep it free of merge conflicts 😅

[stuartcarnie]

I'll have to do some additional work for multiple windows on macOS, but it is very doable. In fact, it would be easy enough to have a picker so you could switch windows

[RobProductions]

Rebased again!

[Robert-K]

Does this PR also enable embedding two run instances of a game within the Godot Editor?
If not, I'd like to kindly request that.

Here's my usecase:

I'm building a mobile game with multiplayer (using the fantastic EOSG plugin) and frequently have to debug/test with two run instances.
The first instance/session gets embedded in the Godot Editor window, but the second one remains a floating window:

Doing anything in the editor will move it to the front, hiding the floating window. This results in obscene amounts Alt+Tabbing.

It would be amazing if the game view provided options for displaying multiple run instances/sessions, with the horizontal/vertical splits from this PR. To be really feature complete, this would probably need to be able to handle more than two sessions as well...

I wouldn't mind iterating on the PR, if that's welcome.

[RobProductions]

@Robert-K If both instances are run from the editor, it may in fact be possible if you use the Custom Window setting and provide a unique window name for each instance. All that's really happening is Godot attaching a special flag to the build telling it that if a window spawns with the given name, it should become parented, and then the GameView searches for it and takes control. Theoretically, any Godot window can work, but it's been a while and I may be misremembering some technical oversight like if the code grabbing the window requires a specific process ID... which will definitely be a problem for that.

If it doesn't work automatically then it should probably be addressed in a follow up PR as its not covered in the original proposal. This one is already a lot of changes and it's been hard to keep it up to date haha. On that note, I'll get around to rebasing it soon and hope to get more code reviews now that we're in 4.6 territory :)

[RobProductions]

@AThousandShips Thanks! I've implemented all of your suggestions and rebased the branch. Let me know if there's anything else I should look into