godotengine
Add support for exporting to Google Play Instant via Google Play Instant Export Option
This PR implements godot-proposals#12432: Add support for exporting to Google Play Instant.
It introduces a new export preset option for Android builds: gradle_build/google_play_instant
When enabled, this option modifies the asset bundling behavior to use the APK-style asset structure for both APK and AAB exports. This is required for compatibility with Google Play Instant, which mandates that all assets be delivered in the base module and does not allow install-time modules (the default behavior for AABs from godot android export).
- Production edit: This closes https://github.com/godotengine/godot-proposals/issues/12432.
This begs the question of whether we should perform any kind of size enforcement/warning when exporting a project as Google Play Instant. This can be implemented by checking for the exported APK size after it's done exporting and making sure it's smaller than 15 MB (or MiB – we should double-check this carefully).
Checking the size of an AAB accurately is going to be more difficult though. I'm not sure if it's possible, unless you only enable a single architecture (and even then, it might be inaccurate).
However, Google may change this size limit over time, which would lead to Godot's check being outdated.
My suggestion would be as follows:
- Prevent exporting with the default export templates, as they're too large and will probably always be unless Google increases the size limit by a lot. Therefore, exporting with Google Play Instant enabled should only be possible when a custom export template is specified in the Android export preset.
- Implement a size check as a warning, after the APK is done exporting. Use
WARN_PRINT_ED()for this purpose. - Point the documentation of the export option to the Optimizing for size documentation, stating that this is a hard requirement to fit within the size limit.
- Add an editor setting to configure the size limit to a different value (in megabytes, as a float). This is in case Google changes it in the future. Not every Godot user always updates to the latest engine version before exporting a project, so there needs to be a way for users to adapt the warning accordingly.
Prevent exporting with the default export templates, as they're too large and will probably always be unless Google increases the size limit by a lot. Therefore, exporting with Google Play Instant enabled should only be possible when a custom export template is specified in the Android export preset.
Implement a size check as a warning, after the APK is done exporting. Use
WARN_PRINT_ED()for this purpose.Point the documentation of the export option to the Optimizing for size documentation, stating that this is a hard requirement to fit within the size limit.
Add an editor setting to configure the size limit to a different value (in megabytes, as a float). This is in case Google changes it in the future. Not every Godot user always updates to the latest engine version before exporting a project, so there needs to be a way for users to adapt the warning accordingly.
Wouldn't it be more user-friendly to leave the enforcement of the size limit to the developer, while still providing strong guidance and warnings? Instead of preventing export entirely without a custom template, we could allow the export to proceed and issue a clear warning if the size exceeds the current Google Play Instant limit.
This approach has a few advantages:
- Flexibility: Developers experimenting or testing may want to proceed regardless of size, especially during early stages.
- Future-proofing: Since Google's size limit may change, hard constraints risk becoming outdated. A warning allows for flexibility without requiring frequent engine updates.
- Consistency with other export warnings: We already warn for common misconfigurations without blocking export; this would align with that pattern.
I fully support implementing a post-export size check using WARN_PRINT_ED() and linking to the "Optimizing for size" documentation. An editable size limit via editor settings is a great idea too, as it enables developers to adapt to evolving requirements.
By making this a warning instead of a hard block, we trust developers while still highlighting the constraints of the platform.
I'm a bit divided on this. I’d really like to see this option available, but I’m also concerned since the support is only partial.
I don’t have direct experience with Play Instant, but after going through the requirements checklist https://developer.android.com/topic/google-play-instant/instant-play-games-checklist, it’s clear that some requirements can't be fully met by Godot Editor. For example:
Automatic sign-in using Google Play Games Services is required.
However, integrating Google Play Games Services directly into the engine core isn’t feasible, so users would have to implement that themselves or use a plugin.
This PR introduces core changes, but full compliance still depends on additional work outside the editor. My concern is that users might expect the editor to take care of all Instant Play requirements, which could lead to confusion.
I'm a bit divided on this. I’d really like to see this option available, but I’m also concerned since the support is only partial.
I don’t have direct experience with Play Instant, but after going through the requirements checklist https://developer.android.com/topic/google-play-instant/instant-play-games-checklist, it’s clear that some requirements can't be fully met by Godot Editor. For example:
Automatic sign-in using Google Play Games Services is required.
However, integrating Google Play Games Services directly into the engine core isn’t feasible, so users would have to implement that themselves or use a plugin.
This PR introduces core changes, but full compliance still depends on additional work outside the editor. My concern is that users might expect the editor to take care of all Instant Play requirements, which could lead to confusion.
I'm a bit divided on this. I’d really like to see this option available, but I’m also concerned since the support is only partial.
I don’t have direct experience with Play Instant, but after going through the requirements checklist https://developer.android.com/topic/google-play-instant/instant-play-games-checklist, it’s clear that some requirements can't be fully met by Godot Editor. For example:
Automatic sign-in using Google Play Games Services is required.
However, integrating Google Play Games Services directly into the engine core isn’t feasible, so users would have to implement that themselves or use a plugin.
This PR introduces core changes, but full compliance still depends on additional work outside the editor. My concern is that users might expect the editor to take care of all Instant Play requirements, which could lead to confusion.
I understand your concerns, but it's important to note that while Google Play Games Services is currently listed as a requirement, this is a policy from Google, and such policies can change at any time. This pull request is a barebone implementation of Play Instant, providing the basic structure without enforcing strict compliance with all Google Play policies.
Moreover, even though Google mentions Google Play Games Services as a requirement, apps without it are still fully supported for Play Instant. So, making this implementation dependent on the ever-evolving Google Play policies would be counterproductive. Users who need specific features, like automatic sign-in, can always extend this with plugins or custom code.
Moreover, even though Google mentions Google Play Games Services as a requirement, apps without it are still fully supported for Play Instant.
Interesting.
I'm not against adding this option -- Instant Play support does require core changes, so this is a necessary step.
We just need to clearly communicate that this is partial support -- some requirements still need to be handled manually.
We should provide explicit guidance on how to meet some of these requirements like 15mb limit, and make it clear that users must consult the Instant Play requirements checklist and verify compliance by uploading their game to the Play Console.
We should provide explicit guidance on how to meet some of these requirements like 15mb limit, and make it clear that users must consult the Instant Play requirements checklist and verify compliance by uploading their game to the Play Console.
I agree. having a dedicated section in the documentation would be very helpful. We can add a new page under Platform-specific → Android, titled Google Play Instant, which outlines the required steps, considerations, and any platform-specific constraints.
There will be some overlap with the existing Build with optimization section, especially around APK size limits and stripping unused features, but I think it's worth keeping this separate for clarity and discoverability, given how specific the Instant Play requirements are.
Thanks for the discussion and feedback!
I've implemented the following based on the suggestions:
✅ Warning when exporting without a custom export template has been added, since the default templates are too large to meet Instant Play constraints.
✅ The documentation link has been updated to point to the optimization guide as suggested.
⚠️ Size check for the exported APK has been partially addressed. While a strict enforcement (<15 MiB) is tricky due to architecture-specific variations and AAB complexity, a general warning has been added to prompt users to optimize their exports when Google Play Instant is enabled.
📘 Suggestion: Dedicated Documentation Page I strongly recommend adding a dedicated documentation page for Google Play Instant support. Enabling it requires manual adjustments to the Android project structure, which go beyond toggling the export option alone.
This includes both AndroidManifest.xml and build.gradle customization:
🔧 Required Project Changes
✅ AndroidManifest.xml Modifications
Inside the
xmlns:dist="http://schemas.android.com/apk/distribution"
android:targetSandboxVersion="2"
Inside the
<dist:module dist:instant="true" />
✅ build.gradle Modifications the following changes are required for a valid Instant App build: Add the following dependency:
implementation "com.google.android.gms:play-services-instantapps:17.0.0"
remove the assetPacks:installTime depencency
assetPacks = [":assetPacks:installTime"] -> assetPacks = []
this manual change can be converted to injection. Androidmanifest.xml can be injected but i couldnot find a way to inject build.gradle.
Thanks for the discussion and feedback!
I've implemented the following based on the suggestions:
✅ Warning when exporting without a custom export template has been added, since the default templates are too large to meet Instant Play constraints.
✅ The documentation link has been updated to point to the optimization guide as suggested.
⚠️ Size check for the exported APK has been partially addressed. While a strict enforcement (<15 MiB) is tricky due to architecture-specific variations and AAB complexity, a general warning has been added to prompt users to optimize their exports when Google Play Instant is enabled.
📘 Suggestion: Dedicated Documentation Page I strongly recommend adding a dedicated documentation page for Google Play Instant support. Enabling it requires manual adjustments to the Android project structure, which go beyond toggling the export option alone.
This includes both AndroidManifest.xml and build.gradle customization:
🔧 Required Project Changes ✅ AndroidManifest.xml Modifications Inside the
tag: xmlns:dist="http://schemas.android.com/apk/distribution" android:targetSandboxVersion="2"Inside the
tag: <dist:module dist:instant="true" />✅ build.gradle Modifications the following changes are required for a valid Instant App build: Add the following dependency:
implementation "com.google.android.gms:play-services-instantapps:17.0.0"remove the assetPacks:installTime depencency
assetPacks = [":assetPacks:installTime"] -> assetPacks = []this manual change can be converted to injection. Androidmanifest.xml can be injected but i couldnot find a way to inject build.gradle.
@kojurohan42 All the changes you described can be, and should be done at export time:
- The manifest file for gradle builds is manually generated, and thus can be edited at will based on the instant flag
- Logic within
build.gradlecan be gated based on gradle parameters passed by the Godot editor.
✅ Warning when exporting without a custom export template has been added, since the default templates are too large to meet Instant Play constraints.
⚠️ Size check for the exported APK has been partially addressed. While a strict enforcement (<15 MiB) is tricky due to architecture-specific variations and AAB complexity, a general warning has been added to prompt users to optimize their exports when Google Play Instant is enabled.
I didn't find these changes 😕? Although, I don't think we need to add warnings for these.
Thanks so much for taking the time to review the code and for the detailed feedback — I really appreciate it!
I've attached a custom.py script I used to help reduce the app size to under 15MB. Hopefully it’s helpful as you move forward with testing. Let me know if there's anything else I can assist with. Though the customization is not limited to them. custom.txt
@syntaxerror247 Just following up on your last comment — were you able to find time to test this with the demo project as you mentioned? No worries if not, just checking in to see if there are any updates.
@syntaxerror247 Just following up on your last comment — were you able to find time to test this with the demo project as you mentioned? No worries if not, just checking in to see if there are any updates.
No, I haven't tested it yet. some other work has piled up, but I'll try to test it as soon as possible
No, I haven't tested it yet. some other work has piled up, but I'll try to test it as soon as possible
No worries at all—thanks for the update! Let me know if you run into anything when you get the chance to test it.
I've attached a custom.py script I used to help reduce the app size to under 15MB. Hopefully it’s helpful as you move forward with testing. Let me know if there's anything else I can assist with. Though the customization is not limited to them. custom.txt
I tested a build with this config (with the only difference that I set lto=none, because LLVM LTO actually makes the binaries bigger by inlining very aggressively, unlike GCC LTO).
In the current master branch I get a 41 MiB apk just for arm64.
I tried to export the 2D platformer demo with it and I get a 44 MiB APK.
I haven't tried with this PR specifically, and I think the recent removal of APK compression in https://github.com/godotengine/godot/pull/106288 may have made things worse for small exports.
Could you share more details on how you get an APK under 15 MiB?
I haven't tried with this PR specifically, and I think the recent removal of APK compression in #106288 may have made things worse for small exports.
Fredy said 2 weeks ago in Android Chat:
I'm thinking about reverting https://github.com/godotengine/godot/pull/106359 and instead just adding a warning to the compress_native_libraries option to mention that it may be incompatible with 16kb page devices;
https://chat.godotengine.org/channel/android?msg=PZ4TEu8bNaZQGACRo
I tested a build with this config (with the only difference that I set
lto=none, because LLVM LTO actually makes the binaries bigger by inlining very aggressively, unlike GCC LTO).
I'll test it more thoroughly (create a 2D demo on the Play Store internal test or public beta).
We probably don't need compression; the Google Play Store also performs optimizations. Android Studio shows the download size; if the APK isn't compressed, the download size will be significantly smaller.
screenshot
We need to perform AAB export (Gradle Build). This doesn't seem to be working properly with the latest master branch.
Or I still need to configure something correctly. (I'll try to investigate further.)
error: failed linking references. mipmap/icon_background not found.
screenshot / details
git log
commit 466acc5953304ef9ba7843105d484366b436ad2e (HEAD -> test_google_play_instant)
Merge: 03bd8ba9c2 12ad9ed4e0
Author: Alexander Hartmann <****>
Date: Thu Jun 12 13:03:07 2025 +0200
Merge branch 'pr/106447' into test_google_play_instant
commit 03bd8ba9c23d31f8f658f97093fd3f2e4a0f9031 (upstream/master, upstream/HEAD, origin/master, origin/HEAD, master)
Merge: 494cdc37a0 e87cccefca
Author: Rémi Verschelde <*****>
Date: Thu Jun 12 11:57:01 2025 +0200
Merge pull request #107439 from bruvzg/lb_config
Add `line_breaking_strictness` project setting.
FAILURE: Build completed with 2 failures.
1: Task failed with an exception.
-----------
* What went wrong:
Execution failed for task ':processMonoDebugResources'.
> A failure occurred while executing com.android.build.gradle.internal.res.LinkApplicationAndroidResourcesTask$TaskAction
> Android resource linking failed
com.godot.game-mergeMonoDebugResources-18:/values/values.xml:148: error: resource mipmap/icon_background (aka com.example.test1:mipmap/icon_background) not found.
com.godot.game-mergeMonoDebugResources-18:/values/values.xml:148: error: resource mipmap/icon_background (aka com.example.test1:mipmap/icon_background) not found.
error: failed linking references.
2: Task failed with an exception.
-----------
* What went wrong:
Execution failed for task ':processStandardDebugResources'.
> A failure occurred while executing com.android.build.gradle.internal.res.LinkApplicationAndroidResourcesTask$TaskAction
> Android resource linking failed
com.godot.game-mergeStandardDebugResources-18:/values/values.xml:148: error: resource mipmap/icon_background (aka com.example.test1:mipmap/icon_background) not found.
com.godot.game-mergeStandardDebugResources-18:/values/values.xml:148: error: resource mipmap/icon_background (aka com.example.test1:mipmap/icon_background) not found.
error: failed linking references.
I've attached a custom.py script I used to help reduce the app size to under 15MB. Hopefully it’s helpful as you move forward with testing. Let me know if there's anything else I can assist with. Though the customization is not limited to them. custom.txt
I tested a build with this config (with the only difference that I set
lto=none, because LLVM LTO actually makes the binaries bigger by inlining very aggressively, unlike GCC LTO).In the current
masterbranch I get a 41 MiB apk just for arm64.I tried to export the 2D platformer demo with it and I get a 44 MiB APK.
I haven't tried with this PR specifically, and I think the recent removal of APK compression in #106288 may have made things worse for small exports.
Could you share more details on how you get an APK under 15 MiB?
Yes, the APK size on disk is around 40 MiB, which is expected due to uncompressed assets and the overall build size. But for Google Play Instant, the key metric is the download size, which needs to stay under 15 MiB.
I’ve tested this with the latest master branch using minimal assets, and the download size of the AAB/APK does fall within the required limit for Instant Apps. I’ve also tried merging this into my own branch, and the results were consistent there as well.
You can view the download size using brotli or just directly in Android Studio as in the images shown.
I tested a build with this config (with the only difference that I set
lto=none, because LLVM LTO actually makes the binaries bigger by inlining very aggressively, unlike GCC LTO).I'll test it more thoroughly (create a 2D demo on the Play Store internal test or public beta).
We probably don't need compression; the Google Play Store also performs optimizations. Android Studio shows the download size; if the APK isn't compressed, the download size will be significantly smaller.
screenshot
We need to perform AAB export (Gradle Build). This doesn't seem to be working properly with the latest master branch.
Or I still need to configure something correctly. (I'll try to investigate further.)
error: failed linking references. mipmap/icon_background not found.screenshot / details
git log commit 466acc5953304ef9ba7843105d484366b436ad2e (HEAD -> test_google_play_instant) Merge: 03bd8ba9c2 12ad9ed4e0 Author: Alexander Hartmann <****> Date: Thu Jun 12 13:03:07 2025 +0200 Merge branch 'pr/106447' into test_google_play_instant commit 03bd8ba9c23d31f8f658f97093fd3f2e4a0f9031 (upstream/master, upstream/HEAD, origin/master, origin/HEAD, master) Merge: 494cdc37a0 e87cccefca Author: Rémi Verschelde <*****> Date: Thu Jun 12 11:57:01 2025 +0200 Merge pull request #107439 from bruvzg/lb_config Add `line_breaking_strictness` project setting.FAILURE: Build completed with 2 failures. 1: Task failed with an exception. ----------- * What went wrong: Execution failed for task ':processMonoDebugResources'. > A failure occurred while executing com.android.build.gradle.internal.res.LinkApplicationAndroidResourcesTask$TaskAction > Android resource linking failed com.godot.game-mergeMonoDebugResources-18:/values/values.xml:148: error: resource mipmap/icon_background (aka com.example.test1:mipmap/icon_background) not found. com.godot.game-mergeMonoDebugResources-18:/values/values.xml:148: error: resource mipmap/icon_background (aka com.example.test1:mipmap/icon_background) not found. error: failed linking references. 2: Task failed with an exception. ----------- * What went wrong: Execution failed for task ':processStandardDebugResources'. > A failure occurred while executing com.android.build.gradle.internal.res.LinkApplicationAndroidResourcesTask$TaskAction > Android resource linking failed com.godot.game-mergeStandardDebugResources-18:/values/values.xml:148: error: resource mipmap/icon_background (aka com.example.test1:mipmap/icon_background) not found. com.godot.game-mergeStandardDebugResources-18:/values/values.xml:148: error: resource mipmap/icon_background (aka com.example.test1:mipmap/icon_background) not found. error: failed linking references.
After testing again, in the latest master branch i didn't seem to have any issues like you mentioned it. Have you checked if there are images like icon_background inside the mipmap folder. I don't know about this in detail but it apparently has been added in the latest build and my android custom build template had the mentioned images.
Can you try it once again and let me know how it goes?
Thank you! 🙌 Really appreciate the quick review, test and merge — I’ll continue testing and help address any issues that come up during beta. Also, thanks a lot for the warm welcome! Excited to have my first contribution merged into Godot 🎉
Well here's some comedic timing from Google... https://www.theverge.com/news/686573/google-android-instant-apps-shutdown
Instant Apps will shutdown in December 2025, so we should probably revert this PR as we won't be able to support this workflow (IIUC the next update of Android Studio will already remove support for it).
🙁