Update the Android documentation for Godot 4.2 #7884

m4gr3d · 2023-09-06T05:46:20Z

Draft for updates to the Android documentation for Godot 4.2:

Updates the Android plugins documentation based on the refactor done for Godot 4.2 in Godot Android plugin re-architecture godot#80740, Refactor Godot Android architecture godot#76821, Re-architect how Android plugins are packaged and handled at export time godot#78958 and Relax restriction on loading v1 Android plugins on Godot 4.2+ godot#81368
- Supersedes Update android_plugin.rst about compatible Android Studio version #7416
- Addresses Re-architect how Android plugins are packaged and handled at export time godot#78958 (comment) and Re-architect how Android plugins are packaged and handled at export time godot#78958 (comment) and Godot Android plugin re-architecture godot#80740 (comment)
Adds a page to describes the Godot Android library and provide instructions for how to use it
- Fixes Documentation for exporting game as embeddable iOS/Android views #4018
Fix misc issues, updates terminologies as needed

Remaining TODOs (to be addressed in follow-up PRs):

Incorporate the NDK location or rather the instructions to compile godot-cpp via scons for Android when the NDK is not at the root directory. See Update the Android documentation for Godot 4.2 #7884 (comment)
Update the OpenXR documentation to provide information on how to build an Android plugin with OpenXR GDExtension capabilities

Docs maintainers note: ping Yuri once merged

tutorials/platform/android/android_library.rst

dsnopek

This is looking great to me! Just a couple notes from skimming the diff

tutorials/platform/android/android_in_app_purchases.rst

tutorials/platform/android/android_plugin.rst

paddy-exe · 2023-09-07T14:53:50Z

Reminder from RocketChat to incorporate the NDK location or rather the instructions to compile godot-cpp via scons for Android when the NDK is not at the root directory. In this case the ANDROID_NDK_ROOT path has to be set. Mine was at C:\Users\Patrick\AppData\Local\Android\Sdk\ndk\23.2.8568313

tokengamedev · 2023-09-12T07:01:08Z

I peeked into the documentation in the commit code. I am not sure I can read the documentation without this getting merged, but I tried. I have few comments, correct me if I am wrong somewhere,

Building and Packaging the Plugin

We are dropping the local godot library aar file dependency in favor of maven dependency. I think it is better compared to V1, but can you confirm? Also, can you provide a beta version somewhere when engine beta version is released, as 4.2.0 stable is not available yet.

On a side note, version 4.1.1 version is missing in the maven repo

When we package the plugin, the output will be a plugin directory as follows (non-gdextension)

+ MyPLugin
|
+--.bin/  # output location for the AAR binaries
|   |
|   +--MyPlugin.1.1.2.release.aar  # the release version of the aar file (naming standards is up to the creator)
|   |
|   +--MyPlugin.1.1.2.debug.aar  # the debug version of the aar file (naming standards is up to the creator)
|
+--.export/  # scripts directory
|   |
|   +--editor_export_plugin.gd  # EditorExportPlugin tool script
|   |
|   +--editor_plugin.gd # EditorPlugin tool script
|
+--plugin.cfg  # plugin INI file

Too much work for the plugin to be created, compared to just generating a gdap file, but I hope there are merits to it.

Can you provide simple examples or usage for all methods inside editor_export_plugin (like _get_android_dependencies_maven_repos and others)

Using the plugin

It seems like the plugin has to be enabled two times to be usable, one in project settings and one in export preset. Is that so?
When the plugin is imported, which name will be used to fetch the plugin Singleton in code
Name in the plugin.cfg or
_get_name() function of the editor_export_plugin.gd

Thanks for the hard work of refactoring the plugin for android, I haven't started testing yet, let me know if there is any way I can get hold of godot library aar file so that I can start testing with simple plugins.

👍 😎

Rindbee · 2023-09-15T00:04:15Z

I think it is necessary to modify cmdline-tools;latest (It is now cmdline-tools;11.0 and does not support JDK11) to cmdline-tools;10.0 for JDK11. See #7902 (comment).

tokengamedev · 2023-09-24T14:37:52Z

Is this going to be updated sometime soon?
Anyway I am busy next couple of weeks working for the critical part of my next game.

BTW, I saw aar files in the Godot builds, I hope I can use them for dependency. Let me know.

tutorials/platform/android/android_plugin.rst

m4gr3d · 2023-09-25T15:37:10Z

Is this going to be updated sometime soon? Anyway I am busy next couple of weeks working for the critical part of my next game.

@tokengamedev yes, I'm working on incorporating the received feedback; expect an update this week.

BTW, I saw aar files in the Godot builds, I hope I can use them for dependency. Let me know.

The AAR files are generated for each build and also pushed to mavencentral so feel free to use whichever is easier for your workflow:

dev builds: https://s01.oss.sonatype.org/content/repositories/snapshots/org/godotengine/godot/
stable builds: https://repo1.maven.org/maven2/org/godotengine/godot/

mhilbrunner · 2023-10-06T12:13:37Z

@m4gr3d With Godot 4.2 beta imminent, what is the status of this? :)

m4gr3d · 2023-10-06T14:21:08Z

@m4gr3d With Godot 4.2 beta imminent, what is the status of this? :)

@mhilbrunner, working on that today!

I was blocked working on the sample apps to go alongside the documentation; I completed those yesterday (see godotengine/godot#82893 and m4gr3d/Godot-Android-Samples@94a6480) so I should be now unblocked.

mhilbrunner · 2023-10-08T23:52:58Z

Great to hear :) No pressure or anything, just wanted to check. Feel free to ping me once ready to review/merge!

m4gr3d · 2023-10-09T02:22:38Z

@tokengamedev I've addressed your questions / feedback below.

I peeked into the documentation in the commit code. I am not sure I can read the documentation without this getting merged, but I tried. I have few comments, correct me if I am wrong somewhere,

You can take a look as my branch as github should generate and make the documentation readable: https://github.com/m4gr3d/godot-docs/blob/update_android_plugin_tutorial/tutorials/platform/android/android_plugin.rst

Building and Packaging the Plugin

We are dropping the local godot library aar file dependency in favor of maven dependency. I think it is better compared to V1, but can you confirm? Also, can you provide a beta version somewhere when engine beta version is released, as 4.2.0 stable is not available yet.

That's correct, maven dependency is the preferred and recommended approach, but the local godot library aar will continue to be provided for the time being for those that prefer that approach.

Until 4.2 is stable, you can use the snapshot versions available at https://s01.oss.sonatype.org/content/repositories/snapshots/org/godotengine/godot/4.2.0.dev-SNAPSHOT/. Those versions are updated for each dev / beta release.

To use the snapshot versions, you'll need to include the maven url for the snapshot repo. See here for reference.

On a side note, version 4.1.1 version is missing in the maven repo

This has been fixed, and it should now be available.

When we package the plugin, the output will be a plugin directory as follows (non-gdextension)

+ MyPLugin
|
+--.bin/  # output location for the AAR binaries
|   |
|   +--MyPlugin.1.1.2.release.aar  # the release version of the aar file (naming standards is up to the creator)
|   |
|   +--MyPlugin.1.1.2.debug.aar  # the debug version of the aar file (naming standards is up to the creator)
|
+--.export/  # scripts directory
|   |
|   +--editor_export_plugin.gd  # EditorExportPlugin tool script
|   |
|   +--editor_plugin.gd # EditorPlugin tool script
|
+--plugin.cfg  # plugin INI file

Too much work for the plugin to be created, compared to just generating a gdap file, but I hope there are merits to it.

This has been reduced to the following:

    export_scripts_template/
    |
    +--export_plugin.gd         # export plugin tool script
    |
    +--plugin.cfg               # plugin INI file

So using your example, that would correspond to:

    MyPlugin/
    |
    +--MyPlugin.1.1.2.release.aar  # the release version of the aar file (naming standards is up to the creator)
    |
    +--MyPlugin.1.1.2.debug.aar  # the debug version of the aar file (naming standards is up to the creator)
    |
    +--export_plugin.gd         # export plugin tool script
    |
    +--plugin.cfg               # plugin INI file

So compared to the previous (.gdap) approach, only one additional script file is added.

but I hope there are merits to it.

The merits are most evident for plugins that provide customization options. The previous (.gdap) approach had no such capabilities. With the new approach, v2 Android plugins can now:

Include options in the Android export presets using _get_export_options, along with warnings to ensure the selected options match the plugin's preconditions
Customize the AndroidManifest file for the generated binary in a manner that's preserved on editor upgrade using _get_android_manifest_activity_element_contents, _get_android_manifest_application_element_contents and _get_android_manifest_element_contents
Customize the export flow using the rest of the APIs provided by the EditorExportPlugin

The Godot OpenXR Loaders plugin makes heavy use of the new capabilities to provide options, capabilities and plugin binaries for multiple OpenXR vendors. Take a look at its implementation for reference.

Can you provide simple examples or usage for all methods inside editor_export_plugin (like _get_android_dependencies_maven_repos and others)

The Godot OpenXR Loaders plugin is a good reference for usage of the methods:

Using the plugin

It seems like the plugin has to be enabled two times to be usable, one in project settings and one in export preset. Is that so?

No, only the first time in the project settings is required. Once the plugin is enabled in the project settings, it's then up to the plugin developer whether additional checks are required or not.
For example, the Godot OpenXR Loaders plugin supports multiple OpenXR vendors, so I include additional options in the export preset to let the user select which vendors should be enabled. The plugin also includes warnings to prevent users from enabling more than 1 vendor for a single export preset.

When the plugin is imported, which name will be used to fetch the plugin Singleton in code
Name in the plugin.cfg or
_get_name() function of the editor_export_plugin.gd

The name used is the one returned by GodotPlugin#getPluginName().
I'd recommend the value in plugin.cfg and _get_name() function to also match that value (the provided github template do so), but it's not required.

Thanks for the hard work of refactoring the plugin for android, I haven't started testing yet, let me know if there is any way I can get hold of godot library aar file so that I can start testing with simple plugins.

👍 😎

Feel free to take a look at https://github.com/m4gr3d/Godot-Android-Samples/tree/master, a collection of samples I develop for reference.

m4gr3d · 2023-10-09T15:30:36Z

Great to hear :) No pressure or anything, just wanted to check. Feel free to ping me once ready to review/merge!

@mhilbrunner Ready for review!

mhilbrunner · 2023-10-10T13:06:59Z

_tools/redirects/redirects.csv

@@ -130,7 +130,7 @@ source,destination
 /getting_started/workflow/best_practices/scene_organization.html,/tutorials/best_practices/scene_organization.html
 /getting_started/workflow/best_practices/scenes_versus_scripts.html,/tutorials/best_practices/scenes_versus_scripts.html
 /getting_started/workflow/best_practices/what_are_godot_classes.html,/tutorials/best_practices/what_are_godot_classes.html
-/getting_started/workflow/export/android_custom_build.html,/tutorials/export/android_custom_build.html
+/getting_started/workflow/export/android_custom_build.html,/tutorials/export/android_gradle_build.html


This means redirects would break for 4.0 and 4.1. I think adding a new second redirect with this instead should work fine, hopefully. Not 100% sure, it's been some time since messing with the redirects.

Alternatively (and potentially simpler) we could rename the page in 4.0 and 4.1 too and then have this redirect everywhere in 4.x, if it applies to all versions?

Or leave it as is, even if not 100% great. The redirects are pretty brittle, unfortunately. We can still change the doc title, just not the URL/file name.

Alternatively (and potentially simpler) we could rename the page in 4.0 and 4.1 too and then have this redirect everywhere in 4.x, if it applies to all versions?

This change would apply to all 4.x versions so I can provide another PR for this change against the 4.1 and 4.0 branch for backport.

@mhilbrunner I've backported the changes in #8217

tutorials/platform/android/android_library.rst

mhilbrunner

The PNGs need to be converted to WebP for newly added/changed images (see image creation guidelines).

Besides that and the other small things I noted above, I spotted nothing. Great work :)

m4gr3d · 2023-10-10T16:33:17Z

@mhilbrunner I've addressed your feedback!

mhilbrunner · 2023-10-10T17:09:23Z

Merged 🎉 Great work!

tokengamedev · 2023-10-16T07:20:17Z

@m4gr3d thanks for the update, sorry could not reply earlier as been busy with the game code 🤓. I will try to check out this week.
Appreciate your great work ❤️

m4gr3d added the enhancement label Sep 6, 2023

m4gr3d added this to the 4.2 milestone Sep 6, 2023

m4gr3d force-pushed the update_android_plugin_tutorial branch 8 times, most recently from 2f1595c to c224e21 Compare September 6, 2023 10:38

This was referenced Sep 6, 2023

Godot Android plugin re-architecture godotengine/godot#80740

Merged

Re-architect how Android plugins are packaged and handled at export time godotengine/godot#78958

Merged

Anutrix reviewed Sep 6, 2023

View reviewed changes

tutorials/platform/android/android_library.rst Outdated Show resolved Hide resolved

m4gr3d force-pushed the update_android_plugin_tutorial branch from c224e21 to c451d57 Compare September 6, 2023 18:33

m4gr3d mentioned this pull request Sep 6, 2023

Android build doesn't work TokisanGames/Terrain3D#197

Closed

dsnopek reviewed Sep 7, 2023

View reviewed changes

m4gr3d force-pushed the update_android_plugin_tutorial branch from c451d57 to 5888d98 Compare September 7, 2023 14:40

AThousandShips reviewed Sep 7, 2023

View reviewed changes

m4gr3d force-pushed the update_android_plugin_tutorial branch from 5888d98 to 17b5c59 Compare September 7, 2023 14:53

AThousandShips reviewed Sep 24, 2023

View reviewed changes

tutorials/platform/android/android_plugin.rst Outdated Show resolved Hide resolved

m4gr3d force-pushed the update_android_plugin_tutorial branch 3 times, most recently from 3a5d55a to 9779fa1 Compare October 6, 2023 20:05

m4gr3d force-pushed the update_android_plugin_tutorial branch from 9779fa1 to d5a8803 Compare October 8, 2023 20:38

m4gr3d mentioned this pull request Oct 9, 2023

Update the plugin's directory structure GodotVR/godot_openxr_vendors#51

Merged

m4gr3d force-pushed the update_android_plugin_tutorial branch from d5a8803 to d14ccc8 Compare October 9, 2023 01:42

m4gr3d mentioned this pull request Oct 9, 2023

[C#] Plugin fails to load using suggested default plugin script folder godotengine/godot#81431

Closed

m4gr3d marked this pull request as ready for review October 9, 2023 15:29

m4gr3d requested a review from mhilbrunner October 9, 2023 18:02

mhilbrunner reviewed Oct 10, 2023

View reviewed changes

tutorials/platform/android/android_library.rst Outdated Show resolved Hide resolved

mhilbrunner requested changes Oct 10, 2023

View reviewed changes

m4gr3d force-pushed the update_android_plugin_tutorial branch from d14ccc8 to b3958d0 Compare October 10, 2023 16:22

Update the Android documentation for Godot 4.2

66ee5cb

m4gr3d force-pushed the update_android_plugin_tutorial branch from b3958d0 to 66ee5cb Compare October 10, 2023 16:32

mhilbrunner approved these changes Oct 10, 2023

View reviewed changes

mhilbrunner merged commit e269ed9 into godotengine:master Oct 10, 2023
1 check passed

m4gr3d mentioned this pull request Oct 10, 2023

Clean up the Android documentation for Godot 4.1 #8217

Merged

m4gr3d deleted the update_android_plugin_tutorial branch October 10, 2023 17:30

skyace65 mentioned this pull request Oct 10, 2023

Update android_plugin.rst about compatible Android Studio version #7416

Closed

mhilbrunner mentioned this pull request Oct 15, 2023

Docs: Update link to Android Gradle Build #8244

Merged

mhilbrunner mentioned this pull request Oct 16, 2023

Docs: Fix link to Android Gradle build tutorial godotengine/godot#83433

Merged

skyace65 mentioned this pull request Feb 3, 2024

Documentation on android custom builds is outdated. #7437

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update the Android documentation for Godot 4.2 #7884

Update the Android documentation for Godot 4.2 #7884

m4gr3d commented Sep 6, 2023 •

edited

Loading

dsnopek left a comment

paddy-exe commented Sep 7, 2023

tokengamedev commented Sep 12, 2023

Rindbee commented Sep 15, 2023 •

edited

Loading

tokengamedev commented Sep 24, 2023

m4gr3d commented Sep 25, 2023 •

edited

Loading

mhilbrunner commented Oct 6, 2023

m4gr3d commented Oct 6, 2023

mhilbrunner commented Oct 8, 2023

m4gr3d commented Oct 9, 2023

m4gr3d commented Oct 9, 2023

mhilbrunner Oct 10, 2023 •

edited

Loading

m4gr3d Oct 10, 2023 •

edited

Loading

m4gr3d Oct 10, 2023

mhilbrunner left a comment

m4gr3d commented Oct 10, 2023

mhilbrunner commented Oct 10, 2023

tokengamedev commented Oct 16, 2023

Update the Android documentation for Godot 4.2 #7884

Update the Android documentation for Godot 4.2 #7884

Conversation

m4gr3d commented Sep 6, 2023 • edited Loading

Remaining TODOs (to be addressed in follow-up PRs):

dsnopek left a comment

Choose a reason for hiding this comment

paddy-exe commented Sep 7, 2023

tokengamedev commented Sep 12, 2023

Rindbee commented Sep 15, 2023 • edited Loading

tokengamedev commented Sep 24, 2023

m4gr3d commented Sep 25, 2023 • edited Loading

mhilbrunner commented Oct 6, 2023

m4gr3d commented Oct 6, 2023

mhilbrunner commented Oct 8, 2023

m4gr3d commented Oct 9, 2023

m4gr3d commented Oct 9, 2023

mhilbrunner Oct 10, 2023 • edited Loading

Choose a reason for hiding this comment

m4gr3d Oct 10, 2023 • edited Loading

Choose a reason for hiding this comment

m4gr3d Oct 10, 2023

Choose a reason for hiding this comment

mhilbrunner left a comment

Choose a reason for hiding this comment

m4gr3d commented Oct 10, 2023

mhilbrunner commented Oct 10, 2023

tokengamedev commented Oct 16, 2023

m4gr3d commented Sep 6, 2023 •

edited

Loading

Rindbee commented Sep 15, 2023 •

edited

Loading

m4gr3d commented Sep 25, 2023 •

edited

Loading

mhilbrunner Oct 10, 2023 •

edited

Loading

m4gr3d Oct 10, 2023 •

edited

Loading