macOS: Embedded window support. by stuartcarnie · Pull Request #105884 · godotengine/godot

stuartcarnie · 2025-04-28T21:07:54Z

Embedded window support for macOS.

This feature is implemented using CARemoteLayer, which is similar to how we implemented it for OpenEmu. This works by creating a CALayer in the child process and passing the CAContextID back to the Godot Editor. The editor is then able to create an instance of CARemoteLayer and display the rendered output in real-time, as if it was hosted in the app. A major difference is that we serialise the events from the host app, the Godot Editor, and process them in the running game.

The following additional state / events are processed correctly:

Joystick add / remove events must be sent to the child process

Joystick.mp4

Joystick rumble timestamps (can't demonstrate that in a video)
DisplayDriver events
- cursor changes within embedded window

Cursor.Shape.mp4

IME events

IME.mp4

OpenGL Support, selection, panning, and more

OpenGL.and.more.mp4

Mouse Capture and ⌥+ESC shortcut, always available to the editor, to release capture

Mouse.Capture.mp4

Production edit: This closes Add support for game window embedding on macOS godot-proposals#11453.

bruvzg · 2025-04-29T08:14:29Z

DisplayDriver events
cursor changes within embedded window
others?

IME activation and position events (:window_set_ime_*) should be sent from embedded DS to the host and back (NOTIFICATION_OS_IME_UPDATE and preedit string) to properly work. Currenlty it is never actvated for the embedded process.

bruvzg · 2025-04-29T08:27:37Z

So far the only issues I have found, embedded view is not hiden when switching tabs from game tab (if floating window is diabled). And IME not workitng (expected since events are not passed).

Screen.Recording.2025-04-29.at.11.26.29.mov

stuartcarnie · 2025-04-29T19:37:08Z

So far the only issues I have found, embedded view is not hiden when switching tabs from game tab (if floating window is diabled). And IME not workitng (expected since events are not passed).

Screen.Recording.2025-04-29.at.11.26.29.mov

That's great – I must have recently broken the tab switching, as I did fix that previously 🙄 Thanks for catching that, I'll push a fix!

stuartcarnie · 2025-04-29T20:07:48Z

@bruvzg I've fixed the panel hiding issue

stuartcarnie

Added some comments

stuartcarnie · 2025-04-28T21:10:32Z

core/input/input_event_codec.cpp

Various codecs for serialising and deserialising input events

Note that debugger_marshalls.cpp have serialize_key_shortcut() method, which is something similar. The new codecs could replace that probably.

EDIT:
Also you are encoding things into binary data. You could just use var_to_bytes(), though it's probably less efficient (if that matters).

Also you are encoding things into binary data. You could just use var_to_bytes(), though it's probably less efficient (if that matters).

Efficiency was a concern here, as we're sending a rapid stream of events to the child process, such as mouse movement. I did look at encoding variants but favoured a more efficient approach to keep latency to a minimum.

Note that debugger_marshalls.cpp have serialize_key_shortcut() method, which is something similar. The new codecs could replace that probably.

@KoBeWi I will move the encode / decode functions to DebuggerMarshalls. Wasn't aware of those, but it is an obvious place to put them. Thanks

stuartcarnie · 2025-04-28T21:10:56Z

drivers/apple/joypad_apple.h

A small change to make polling a little more efficient.

stuartcarnie · 2025-04-28T21:11:56Z

editor/debugger/script_editor_debugger.cpp

I moved the started signal to when the PID is set, as it was causing a race condition with the embedded process, which raised the started before it had received its PID, so it wasn't able to communicate with the child process

stuartcarnie · 2025-04-28T21:12:43Z

editor/editor_node.cpp

+#ifdef MACOS_ENABLED
+extern "C" GameViewPluginBase *get_game_view_plugin();
+#else
+GameViewPluginBase *get_game_view_plugin() {
+	return memnew(GameViewPlugin);
+}
+#endif
+


If there are recommendations for a better way to switch out the GameViewPlugin for macOS, I'm all ears.

Maybe we can move this plugin to the DisplayServer entirely:

A plugin instance can be created and returned by the DisplayServer method. Windows and X11 overrides return base type. And macOS its special one.

I will take a look at that - would be a nice approach

stuartcarnie · 2025-04-29T20:18:49Z

core/input/input_event_codec.cpp

This can be used for future implementations that want to serialise events across processes.

stuartcarnie · 2025-04-29T20:32:19Z

platform/macos/godot_application_delegate.h

- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context;
- (void)accessibilityDisplayOptionsChange:(NSNotification *)notification;


Moved these into the mm so they are hidden from the public interface

stuartcarnie · 2025-04-29T20:33:13Z

platform/macos/godot_application_delegate.h

- (void)forceUnbundledWindowActivationHackStep1;
- (void)forceUnbundledWindowActivationHackStep2;
- (void)forceUnbundledWindowActivationHackStep3;


Moved these to the GodotApplication class, as I was exploring removing NSApplication loop completely from embedded child process, as it may not be needed.

stuartcarnie · 2025-04-29T20:33:49Z

platform/macos/godot_application_delegate.h

-	bool high_contrast;
-	bool reduce_motion;
-	bool reduce_transparency;
-	bool voice_over;


Moved these to the .mm file, as they don't need to be in the public interface.

stuartcarnie · 2025-04-29T20:35:38Z

platform/macos/godot_main_macos.mm

+		if (strcmp("--os-debug", argv[i]) == 0) {
+			i++;
+			wait_for_debugger = 5000; // wait 5 seconds by default
+			if (i < argc && strncmp(argv[i], "--", 2) != 0) {
+				wait_for_debugger = atoi(argv[i]);
+				i++;
+			}
+			continue;


For macOS, we can added a --os-debug <ms> run argument, so you can have it wait for a debugger and attach to debug the entire startup process when the Godot editor launches the child process, which was very handy for this work (and many other things I've done in the past)

Probably should be in ifdef DEBUG_ENABLED block.

stuartcarnie · 2025-04-29T20:36:21Z

platform/macos/os_macos.h

 	String _get_default_fontname(const String &p_font_name) const;

 	static _FORCE_INLINE_ String get_framework_executable(const String &p_path);
-	static void pre_wait_observer_cb(CFRunLoopObserverRef p_observer, CFRunLoopActivity p_activiy, void *p_context);


Moved this to a block.

bruvzg · 2025-04-30T05:23:08Z

editor/editor_node.cpp

+#ifdef MACOS_ENABLED
+extern "C" GameViewPluginBase *get_game_view_plugin();
+#else
+GameViewPluginBase *get_game_view_plugin() {
+	return memnew(GameViewPlugin);
+}
+#endif
+


Maybe we can move this plugin to the DisplayServer entirely:

A plugin instance can be created and returned by the DisplayServer method. Windows and X11 overrides return base type. And macOS its special one.

bruvzg · 2025-04-30T05:33:54Z

platform/macos/godot_main_macos.mm

+		if (strcmp("--os-debug", argv[i]) == 0) {
+			i++;
+			wait_for_debugger = 5000; // wait 5 seconds by default
+			if (i < argc && strncmp(argv[i], "--", 2) != 0) {
+				wait_for_debugger = atoi(argv[i]);
+				i++;
+			}
+			continue;


Probably should be in ifdef DEBUG_ENABLED block.

bruvzg · 2025-04-30T05:52:50Z

editor/plugins/game_view_plugin.cpp

+	r_arguments.push_back("--rendering-driver");
+	r_arguments.push_back("metal");


Not sure about this, maybe it's better to check renderer and disable embedding if it's GL for now. Silently switching a running project to a different renderer is not what most users will expect.

nubels · 2025-04-30T10:19:14Z

First of all, thanks a ton for implementing this feature and opening this pr.

I was very eager to test it and I think I've found some issues:

You can't resize the game window if you drag your mouse over it, you have to move the mouse around the window and then it works.
After clicking outside of the game window, it sometimes registers input that isn't there. In this clip, I stop pressing A around the 5s mark and my character still moves to the left. After pressing A again, it seems to stop. I'm using Input.get_vector

I hope this helps :)

stuartcarnie · 2025-05-01T07:31:57Z

@bruvzg OpenGL now works, so I've removed the explicit --rendering-device argument.

KoBeWi · 2025-05-05T21:02:27Z

You might've missed #105884 (comment)

stuartcarnie · 2025-05-05T22:51:21Z

You might've missed #105884 (comment)

Thanks!

stuartcarnie · 2025-05-05T23:37:01Z

@Calinou

I noticed the CLI arguments used by the embedded process are --display-driver embedded --embedded. Can --embedded imply --display-driver embedded so you don't need to use both?

💯 agree. I've made that change.

Repiteo · 2025-05-06T13:57:49Z

Shoot, this got included in the merge batch erroneously. It should be fine as-is, but I meant to hold off for some more maintainer approvals & wait for the followup fixes.

@stuartcarnie Those can go into an immediate followup PR, my apologies

akien-mga · 2025-05-06T14:19:41Z

Heh, thankfully it had time to be well-reviewed and polished in the past couple of days, so it was 99% ready to merge already.

Let's celebrate this huge achievement and long-awaited feature and not just the merge process mishap :P 🎉

Thanks for the amazing work @stuartcarnie 🥇

stuartcarnie · 2025-05-06T19:59:53Z

No stress, @Repiteo! I do have some follow up fixes that I'll prep today in a new PR!

Thanks @akien-mga and to all those that reviewed.

@Calinou my changes will include preventing embedding in single-window mode.

stuartcarnie · 2025-05-06T20:15:24Z

@Repiteo see #106134 with some initial follow up work to resolve some of @Calinou's issues.

stuartcarnie · 2025-05-06T20:21:42Z

Remaining items to investigate (no included in #106134):

Clicking the X button to close the floating game window has no effect.
Closing the editor using Ctrl + C in the terminal won't always stop the running project
In Compatibility, using window embedding will break V-Sync (FPS will be uncapped).
When using Metal in Truck Town (Forward+/Mobile), the sky takes the background color of the game window

macOS: Fix `template_debug` build after #105884

stuartcarnie requested review from a team as code owners April 28, 2025 21:07

stuartcarnie force-pushed the macos_embedded branch from 16778d8 to 3718ce1 Compare April 28, 2025 21:09

stuartcarnie requested a review from a team as a code owner April 28, 2025 21:09

akien-mga added enhancement platform:macos topic:editor topic:platforms labels Apr 28, 2025

akien-mga added this to the 4.x milestone Apr 28, 2025

bruvzg self-requested a review April 29, 2025 05:23

stuartcarnie force-pushed the macos_embedded branch 3 times, most recently from 2b57725 to 44ec980 Compare April 29, 2025 07:40

stuartcarnie force-pushed the macos_embedded branch from 44ec980 to e2527e4 Compare April 29, 2025 20:07

stuartcarnie force-pushed the macos_embedded branch from e2527e4 to 6d4ba50 Compare April 29, 2025 20:17

stuartcarnie commented Apr 29, 2025

View reviewed changes

stuartcarnie force-pushed the macos_embedded branch 2 times, most recently from b14b6df to affb92c Compare April 29, 2025 20:43

bruvzg approved these changes Apr 30, 2025

View reviewed changes

stuartcarnie force-pushed the macos_embedded branch 2 times, most recently from 4bf9a01 to 35cb8f7 Compare May 1, 2025 07:31

stuartcarnie force-pushed the macos_embedded branch 2 times, most recently from dd3bce0 to 604072c Compare May 1, 2025 07:41

Repiteo merged commit aa24e3b into godotengine:master May 6, 2025
20 checks passed

stuartcarnie deleted the macos_embedded branch May 6, 2025 19:59

stuartcarnie mentioned this pull request May 6, 2025

macOS: Additional improvements and fixes for embedded window support #106134

Merged

RobProductions mentioned this pull request May 6, 2025

Add support for embedding subwindows and dual screen GameViews #104079

Open

akien-mga added a commit to akien-mga/godot that referenced this pull request May 13, 2025

macOS: Fix template_debug build after godotengine#105884

3e2c064

akien-mga mentioned this pull request May 13, 2025

macOS: Fix template_debug build after #105884 #106348

Merged

akien-mga added a commit that referenced this pull request May 13, 2025

Merge pull request #106348 from akien-mga/macos-fix-template_debug-build

af62a09

macOS: Fix `template_debug` build after #105884

lalitshankarch pushed a commit to lalitshankarch/godot that referenced this pull request May 13, 2025

macOS: Fix template_debug build after godotengine#105884

74d67a7

PiCode9560 pushed a commit to PiCode9560/godot that referenced this pull request May 13, 2025

macOS: Fix template_debug build after godotengine#105884

fb9fa20

vbettaque pushed a commit to vbettaque/godot that referenced this pull request May 14, 2025

macOS: Fix template_debug build after godotengine#105884

be7d538

harrisyu pushed a commit to harrisyu/godot that referenced this pull request May 16, 2025

macOS: Fix template_debug build after godotengine#105884

d57f06e

bruvzg mentioned this pull request May 21, 2025

Fix GodotApplicationDelegate init. #106672

Merged

syntaxerror247 mentioned this pull request Jun 7, 2025

Fix Game runtime debugging in the Android Editor #107251

Merged

goatchurchprime pushed a commit to goatchurchprime/godot that referenced this pull request Jun 10, 2025

macOS: Fix template_debug build after godotengine#105884

1676888

dsmtE pushed a commit to dsmtE/godot that referenced this pull request Jun 17, 2025

macOS: Fix template_debug build after godotengine#105884

189b44e

AndreaMonzini mentioned this pull request Jun 19, 2025

Wayland: Implement game embedding #107435

Merged

spanzeri pushed a commit to spanzeri/godot that referenced this pull request Jun 25, 2025

macOS: Fix template_debug build after godotengine#105884

b012e1b

dawdle-deer pushed a commit to dawdle-deer/godot that referenced this pull request Jul 3, 2025

macOS: Fix template_debug build after godotengine#105884

fe02120

Haydoggo pushed a commit to Haydoggo/godot that referenced this pull request Jul 7, 2025

macOS: Fix template_debug build after godotengine#105884

d30352e

Alex2782 mentioned this pull request Jul 24, 2025

Intermittent editor freezes after upgrading to 4.4 #103780

Closed

adamscott mentioned this pull request Jul 24, 2025

[macOS] Embedded game window return wrong DisplayServer.screen_get_scale() #108949

Closed

Nordup mentioned this pull request Sep 18, 2025

Add external texture support (GLES3) #96982

Merged

		- (void)observeValueForKeyPath:(NSString )keyPath ofObject:(id)object change:(NSDictionary )change context:(void *)context;
		- (void)accessibilityDisplayOptionsChange:(NSNotification *)notification;

		r_arguments.push_back("--rendering-driver");
		r_arguments.push_back("metal");

Uh oh!

Conversation

stuartcarnie commented Apr 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bruvzg commented Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bruvzg commented Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stuartcarnie commented Apr 29, 2025

Uh oh!

stuartcarnie commented Apr 29, 2025

Uh oh!

stuartcarnie left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KoBeWi May 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nubels commented Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stuartcarnie commented May 1, 2025

Uh oh!

KoBeWi commented May 5, 2025

Uh oh!

stuartcarnie commented May 5, 2025

Uh oh!

stuartcarnie commented May 5, 2025

Uh oh!

Uh oh!

Repiteo commented May 6, 2025

Uh oh!

akien-mga commented May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stuartcarnie commented May 6, 2025

Uh oh!

stuartcarnie commented May 6, 2025

Uh oh!

stuartcarnie commented May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stuartcarnie commented Apr 28, 2025 •

edited

Loading

bruvzg commented Apr 29, 2025 •

edited

Loading

bruvzg commented Apr 29, 2025 •

edited

Loading

KoBeWi May 5, 2025 •

edited

Loading

nubels commented Apr 30, 2025 •

edited

Loading

akien-mga commented May 6, 2025 •

edited

Loading

stuartcarnie commented May 6, 2025 •

edited

Loading