diff --git a/tutorials/platform/android/img/play_console_app_bundle_explorer.webp b/tutorials/platform/android/img/play_console_app_bundle_explorer.webp new file mode 100644 index 00000000000..bb4fd566417 Binary files /dev/null and b/tutorials/platform/android/img/play_console_app_bundle_explorer.webp differ diff --git a/tutorials/platform/android/img/play_console_app_bundle_explorer2.webp b/tutorials/platform/android/img/play_console_app_bundle_explorer2.webp new file mode 100644 index 00000000000..899cdb07210 Binary files /dev/null and b/tutorials/platform/android/img/play_console_app_bundle_explorer2.webp differ diff --git a/tutorials/platform/android/img/play_console_create_new_release.webp b/tutorials/platform/android/img/play_console_create_new_release.webp new file mode 100644 index 00000000000..fb03b83b3a2 Binary files /dev/null and b/tutorials/platform/android/img/play_console_create_new_release.webp differ diff --git a/tutorials/platform/android/img/play_console_create_new_release2.webp b/tutorials/platform/android/img/play_console_create_new_release2.webp new file mode 100644 index 00000000000..122166d0c10 Binary files /dev/null and b/tutorials/platform/android/img/play_console_create_new_release2.webp differ diff --git a/tutorials/platform/android/img/play_console_latest_release_bundles.webp b/tutorials/platform/android/img/play_console_latest_release_bundles.webp new file mode 100644 index 00000000000..f3cf6f99cc2 Binary files /dev/null and b/tutorials/platform/android/img/play_console_latest_release_bundles.webp differ diff --git a/tutorials/platform/android/img/play_console_latest_release_bundles2.webp b/tutorials/platform/android/img/play_console_latest_release_bundles2.webp new file mode 100644 index 00000000000..cbb70a9862f Binary files /dev/null and b/tutorials/platform/android/img/play_console_latest_release_bundles2.webp differ diff --git a/tutorials/platform/android/img/play_console_upload_native_debug_symbols.webp b/tutorials/platform/android/img/play_console_upload_native_debug_symbols.webp new file mode 100644 index 00000000000..ff2004c7de5 Binary files /dev/null and b/tutorials/platform/android/img/play_console_upload_native_debug_symbols.webp differ diff --git a/tutorials/platform/android/index.rst b/tutorials/platform/android/index.rst index aa1ea66ce41..b7f7a19081c 100644 --- a/tutorials/platform/android/index.rst +++ b/tutorials/platform/android/index.rst @@ -11,3 +11,4 @@ Android android_plugin android_in_app_purchases javaclasswrapper_and_androidruntimeplugin + resolving_crashes_on_android diff --git a/tutorials/platform/android/resolving_crashes_on_android.rst b/tutorials/platform/android/resolving_crashes_on_android.rst new file mode 100644 index 00000000000..58695efd145 --- /dev/null +++ b/tutorials/platform/android/resolving_crashes_on_android.rst @@ -0,0 +1,107 @@ +.. _doc_resolving_crashes_on_android: + +Resolving crashes on Android +============================ + +When your game crashes on Android, you often see obfuscated stack traces in Play Console +or other crash reporting tools like Firebase Crashlytics. To make these stack traces human-readable (symbolicated), +you need native debug symbols that correspond to your game's exported build. + +Godot now provides downloadable native debug symbols for each official export template. + +Getting Native Debug symbols for official templates +--------------------------------------------------- + +Native debug symbol files are provided for every stable Godot release +and can be downloaded from the `GitHub release page `_. + +For example, to get the native debug symbols for version ``4.5.1.stable``: + +- Go to the `4.5.1.stable release page `_ +- Download the release artifact ``Godot_native_debug_symbols.4.5.1.stable.template_release.android.zip`` + +Getting Native Debug symbols for custom builds +---------------------------------------------- + +Your exported template and its native debug symbols must come from the **same build**, +so you can use the official symbols only if you are using the **official export templates**. +If you are building **custom export templates**, you need to generate matching symbol files yourself. + +To do so, add ``debug_symbols=yes separate_debug_symbols=yes`` to your scons build command. +This will generate a file named ``android-template-release-native-symbols.zip`` containing the native debug symbols for your custom build. + +For example, + +:: + + scons platform=android target=template_release debug_symbols=yes separate_debug_symbols=yes generate_android_binaries=yes + +If you are building for multiple architectures, you should include the ``separate_debug_symbols=yes`` only in the last build command, +similar to how ``generate_android_binaries=yes`` is used. + +:: + + scons platform=android arch=arm32 target=template_release debug_symbols=yes + scons platform=android arch=arm64 target=template_release debug_symbols=yes + scons platform=android arch=x86_32 target=template_release debug_symbols=yes + scons platform=android arch=x86_64 target=template_release debug_symbols=yes separate_debug_symbols=yes generate_android_binaries=yes + +Uploading Symbols to Google Play Console +---------------------------------------- + +Follow these steps to upload the native debug symbols: + +1. Open `Play Console `_. +2. Select any app. +3. In the left menu, navigate to ``Test and release > Latest releases and bundles``. + +.. image:: img/play_console_latest_release_bundles.webp + +4. Now choose the relevant bundle and open it. + +.. image:: img/play_console_latest_release_bundles2.webp + +5. Select the ``Downloads`` tab, and scroll down to the ``Assets`` section. + +.. image:: img/play_console_app_bundle_explorer.webp + +6. Next to ``Native debug symbols``, click the upload arrow icon. + +.. image:: img/play_console_app_bundle_explorer2.webp + +7. Select and upload the corresponding native debug symbols file for that build version. + +.. image:: img/play_console_upload_native_debug_symbols.webp + +Alternatively, you can upload the symbols when creating a new release: + +1. On the Create release page, locate your new release bundle. + +.. image:: img/play_console_create_new_release.webp + +2. Click the three-dot menu beside it. +3. Choose ``Upload native debug symbols (.zip)`` from the menu. + +.. image:: img/play_console_create_new_release2.webp + +4. Select and upload the corresponding native debug symbols file for that build version. + +Manually Symbolicating Crash Logs +--------------------------------- + +You can also symbolicate the crash logs manually using the `ndk-stack `_ tool included in the Android NDK. + +.. note:: + + If you already have the Android SDK installed, you can find the ``ndk-stack`` tool inside the ``ndk`` folder in your SDK location. + Otherwise, you can download the NDK directly from the `NDK downloads page `_. + +1. Extract the native debug symbols zip you downloaded earlier (or generated with your custom build). +2. Save your crash log to a text file (for example, ``crash.txt``). +3. Run ndk-stack with the path to the symbol directory that matches the crash's CPU architecture (for example, ``arm64-v8a``): + +:: + + ndk-stack -sym path/to/native_debug_symbols/arm64-v8a/ -dump crash.txt + +4. The output will display a symbolicated trace, showing file names and line numbers in Godot's source code (or your custom build).