Export game as embeddable iOS view to easily use non-Godot code (Android already supported)

[bfelbo]

Describe the project you are working on:
Multiplayer game for iOS and Android

Describe the problem or limitation you are having in your project:
Due to the social nature of our game, we need to:

• Use many mobile features like microphone permissions (Streamline permission requesting / handling on mobile #1272), in-app purchases (Add "restore purchases completed/failed" notifications to iOS IAP #242), VoIP push notifications, ForegroundService, CallKit. Godot doesn't support these, but there's lots of battle-tested iOS/Android libraries for these features and it would be great to rely on those libraries.
• Build lots of UI to support multiplayer features (e.g. friends, guilds, chat), which would be easier to do using e.g. the React Native framework, which is focused exclusively on building UI.

Describe the feature / enhancement and how it helps to overcome the problem or limitation:
Godot added support for embedding your game inside an Android app and it would be amazing if Godot added support for iOS as well.

A few benefits:

• Developers wanting more flexibility or needing specific mobile features could use the approach. In this way, Godot doesn't have to build support for many mobile features, e.g. Streamline permission requesting / handling on mobile #1272, Option to disable the Boot Splash on specific platforms #1175, Add "restore purchases completed/failed" notifications to iOS IAP #242, Add a method to check if vibration is supported on Android #1427, Make iOS GameCenter authentication controllable by developer #1184.
• Many multiplayer games need a lot of UI such as e.g. friends, guilds, chat. It would be easy to write this UI in a cross-platform UI framework such as React Native or Flutter, which has lots of libraries for e.g. chat.
• It would be easy to add Godot games inside existing apps, which is becoming a increasingly popular trend (see e.g. Snapchat games).

Describe how your proposal will work, with code, pseudocode, mockups, and/or diagrams:
Similar to godotengine/godot#39855 for Android, it would be possible to export your game as an embeddable iOS view.

A developer would create their own Android/iOS app from scratch and use the Godot embeddable view. Inside the app, the Godot view could be displayed for the actual gameplay. For instance, consider the popular mobile games Brawl Stars, Fortnite, and PUBG. The developers could code up all the UI, app permissions, ad tracking, etc. in any language and then use Godot once the user clicks "Play" and enters the actual gameplay.

One way to think of the current default Godot app exports is that they're a embeddable view + a wrapper. The view has all the core functionality and the wrapper handles things like setting the right permissions in the AndroidManifest.xml. If this was separated, it would be easy for anyone to export a complete app or to just use the embeddable view depending on their use case.

If this enhancement will not be used often, can it be worked around with a few lines of script?:
Not that I know of.

Is there a reason why this should be core and not an add-on in the asset library?:
Porting/exporting is best handled in core and this proposal would alleviate the need for many other core proposals (see linked issues above).

EDIT:
Updated to split out documentation and focus on iOS support based on @m4gr3d's suggestion.

[Calinou]

This will be supported for Android in 4.0 since godotengine/godot#39855 was merged.

[bfelbo]

Amazing! Then this proposal can be focused on adding support for iOS and documentation on how to use it 😊

[m4gr3d]

@bfelbo Quick clarifications:

• Being able to use Godot as a library is already supported starting with Godot 3.2.0 (though using the latest stable version, 3.2.2, is recommended as it addresses several issues). There is not a lot of documentation since it's an advanced feature but you can take a look at the project structure when Godot installs an Android build template in the res://android/build directory.
• The PR you linked to above (PR Enable the ability to use Godot as a subview within an Android app godot#39855) builds on that capability to enable embedding Godot as an Android fragment. The feature has been merged but it's still in development (mostly testing and bug squash if any) and is targeted for Godot 3.2.4.

So if you just need the ability to embed Godot as a library on Android with Godot taking over the full screen when invoked, you should be good to go with the current stable version.
If you need the ability to embed/restrict Godot to a specific view, then that feature will be available in Godot 3.2.4. I'd still recommend starting the process of integrating the Godot library in your target application to get familiar with the process.

And since this is an open source project, any feedback, learnings, documentations or examples you'd like to share or contribute back would be much appreciated :)

[m4gr3d]

@bfelbo Would you mind splitting this proposal in two. The iOS portion remains, so there should be a proposal focusing on the iOS side of the equation.
For the Android side, based on the current proposal, only the documentation portion is missing, so the updated proposal should reflect that.

[bfelbo]

@bfelbo Would you mind splitting this proposal in two.

Definitely! I've separated out the documentation into https://github.com/godotengine/godot-proposals/issues/1518.

If you need the ability to embed/restrict Godot to a specific view, then that feature will be available in Godot 3.2.4.

Thanks for the detailed explanation. It's really cool that it's already possible to do this on Android!

And since this is an open source project, any feedback, learnings, documentations or examples you'd like to share or contribute back would be much appreciated :)

Yes, we'd love to contribute in any way we can :)

[naithar]

• Use many mobile features like microphone permissions (Streamline permission requesting / handling on mobile #1272), in-app purchases (Add "restore purchases completed/failed" notifications to iOS IAP #242), VoIP push notifications, ForegroundService, CallKit. Godot doesn't support these, but there's lots of battle-tested iOS/Android libraries for these features and it would be great to rely on those libraries.

This should be possible with new iOS plugin system once or if it gets merged. Plugin Proposal, 4.0 PR, 3.2 PR.
In PR for 4.0 I've also gave some kind of example for using native UI. I guess integrating it with React Native should be possible too.
I also plan to make AppDelegate class more extendable as well as enabling ARC usage. This should give a more easier access to PushKit and RemoteNotifications as well as simplify iOS specific implementation.

---

As for making Godot embeddable.
It should probably not be an embeddable UIView, but UIViewController, which should give some control over app lifecycle.
Switching to NSNotification instead of AppDelegate method would be needed, but some things might be missing there, I'm not entirely sure.
Also Godot uses it's own main method, so moving it into iOS template is required, otherwise iOS application will get a duplicated symbols error.
This should be pretty much all the work needed on platform side. But with current 3.2 state I would probably wait for some refactoring done first.

[bfelbo]

Thanks for the detailed explanation @naithar! Makes sense that it might require some refactoring first before working on making Godot embeddable.

[bfelbo]

I just saw that 3.2.4 will include Android embedding support 🎉 Would be awesome to also have it on iOS in the near future so this can be used by all the devs building cross-platform mobile apps.

@naithar, what kind of refactoring do you think should be done before working on this? Anything I can help with?

[naithar]

@bfelbo most of the work that are needed was already merged (godotengine/godot#42459, godotengine/godot#42582 and some other PRs), only PRs with fixes are left, like godotengine/godot#42648. Maybe Motion manager should also be moved in separate class, like joypad, but I'm not sure.

I'm also waiting for godotengine/godot#41230 to be merged. It'll allow to build plugins for iOS without rebuilding the whole engine.

After that I think it'll be safe to implement embedding Godot game into another iOS application.