examples: Use single up-to-date android example

Objective

- Only use a single modern and better documented android example
- Fix #10945
- Fix #17122

Problems with current examples

- We are currently using deprecated functions like for example [setSystemUiVisibility(int)](https://developer.android.com/reference/android/view/View#setSystemUiVisibility(int)).
- Most Android dependencies are very out of date.
- Kotlin is the [preffered language](https://developer.android.com/kotlin/first) for Android and we should migrate the examples to it.
- Most of the code in the examples is not inherently clear and there are very few comments especially in the build scripts.
- We should only have a single Android example using `games-activity` and `cargo-ndk`. It is confusing and unnecessary to do it any other way in my opinion.
- The crash from #10945 is fixed by migrating to `games-activity` 4. Before this PR, we were using `games-activity` 2. #17122 is apparently also fixed because of this.

Solution

- Replace all android examples with `./examples/mobile/android`
- Update dependencies in `libs.versions.toml`
- Add `gradle-daemon-jvm.properties` generated with `./gradlew updateDaemonJvm`
- Update gradle wrapper
- Migrate everything to kotlin/kotlin build scripts
- Use supported functions instead of deprecated ones
- Move `/assets/ic_launcher.png` to `/examples/mobile/android/app/src/main/res/mipmap/ic_launcher.png` because that is where it is [meant to be stored](https://developer.android.com/guide/topics/resources/providing-resources).
- Use `--link-libcxx-shared` flag for `cargo-ndk` in `examples/README.md`
- Use `targetSdk = 36` and `compileSdk = 36` and explain in `examples/README.md`

Author: leomeinel

.github/workflows/validation-jobs.yml

@@ -99,10 +99,11 @@ jobs:
         run: cargo install --force cargo-ndk
 
       - name: Build .so file
-        run: cargo ndk -t arm64-v8a -P 26 -o android_example/app/src/main/jniLibs build --package bevy_mobile_example
+        # FIXME: Remove --release flag after an issue that makes it necessary for building the example has been resolved.
+        run: cargo ndk build --link-libcxx-shared -t aarch64-linux-android -p bevy_mobile_example --release -o ./examples/mobile/android/app/src/main/jniLibs
 
       - name: Build app for Android
-        run: cd examples/mobile/android_example && chmod +x gradlew && ./gradlew build
+        run: cd ./examples/mobile/android && chmod +x ./gradlew && ./gradlew build
 
   run-examples-on-wasm:
     if: ${{ github.event_name == 'merge_group' }}

docs-template/EXAMPLE_README.md.tpl

@@ -45,9 +45,8 @@ git checkout v0.4.0
   - [Android](#android)
     - [Setup](#setup)
     - [Build & Run](#build--run)
-    - [About `libc++_shared.so`](#about-libc_sharedso)
+    - [Debugging](#debugging)
     - [Old phones](#old-phones)
-    - [About `cargo-apk`](#about-cargo-apk)
   - [iOS](#ios)
     - [Setup](#setup-1)
     - [Build & Run](#build--run-1)
@@ -104,16 +103,20 @@ Alternatively, you can install Android Studio.
 
 #### Build & Run
 
+<!-- FIXME: Remove --release flag after an issue that makes it necessary for building the example has been resolved.-->
+
+**⚠️ Note:** The `--release` flag is currently necessary for the example. You might be able to omit it when building your own crate.
+
 To build an Android app, you first need to build shared object files for the target architecture with `cargo-ndk`:
 
 ```sh
-cargo ndk -t <target_name> -P 26 -o <project_name>/app/src/main/jniLibs build
+cargo ndk build --link-libcxx-shared -t <target_name> --release -o <project_path>/android/app/src/main/jniLibs
 ```
 
 For example, to compile to a 64-bit ARM platform:
 
 ```sh
-cargo ndk -t arm64-v8a -P 26 -o android_example/app/src/main/jniLibs build
+cargo ndk build --link-libcxx-shared -t aarch64-linux-android --release -o ./android/app/src/main/jniLibs
 ```
 
 Setting the output path ensures the shared object files can be found in target-specific directories under `jniLibs` where the JNI can find them.
@@ -123,21 +126,14 @@ See the `cargo-ndk` [README](https://crates.io/crates/cargo-ndk) for other optio
 After this you can build it with `gradlew`:
 
 ```sh
+cd ./android
 ./gradlew build
 ```
 
 Or build it with Android Studio.
 
 Then you can test it in your Android project.
 
-##### About `libc++_shared.so`
-
-Bevy may require `libc++_shared.so` to run on Android, as it is needed by the `oboe` crate, but typically `cargo-ndk` does not copy this file automatically.
-
-To include it, you can manually obtain it from NDK source or use a `build.rs` script for automation, as described in the `cargo-ndk` [README](https://github.com/bbqsrc/cargo-ndk?tab=readme-ov-file#linking-against-and-copying-libc_sharedso-into-the-relevant-places-in-the-output-directory).
-
-Alternatively, you can modify project files to include it when building an APK. To understand the specific steps taken in this project, please refer to the comments within the project files for detailed instructions(`app/CMakeList.txt`, `app/build.gradle`, `app/src/main/cpp/dummy.cpp`).
-
 #### Debugging
 
 You can view the logs with the following command:
@@ -156,28 +152,18 @@ adb uninstall org.bevyengine.example
 
 #### Old phones
 
-In its examples, Bevy targets the minimum Android API that Play Store  <!-- markdown-link-check-disable -->
-[requires](https://developer.android.com/distribute/best-practices/develop/target-sdk) to upload and update apps. <!-- markdown-link-check-enable -->
-Users of older phones may want to use an older API when testing. By default, Bevy uses [`GameActivity`](https://developer.android.com/games/agdk/game-activity), which only works for Android API level 31 and higher, so if you want to use older API, you need to switch to `NativeActivity`.
+**⚠️ Note:** If you are using `bevy_audio` the minimum supported Android API version is 26 (Android 8/Oreo).
+
+In its example, Bevy uses Android API 36 as `targetSdk` to be able to benefit from security and performance improvements. For backwards compatibility, the example specifies Android API 31 as `minSdk`. This approach is recommended in the [Android Developers documentation](https://developer.android.com/google/play/requirements/target-sdk#why-target).
 
-Keep in mind that if you are using `bevy_audio` the minimum supported Android API version is 26 (Android 8/Oreo).
+Users of older phones may want to use an older API when testing. By default, Bevy uses [`GameActivity`](https://developer.android.com/games/agdk/game-activity), which only works for Android API 31 and higher, so if you want to use an older API, you need to switch to [`NativeActivity`](https://developer.android.com/reference/android/app/NativeActivity).
 
-To use `NativeActivity`, you need to edit it in `cargo.toml` manually like this:
+To use `NativeActivity`, you need to write a custom `MainActivity.kt` using `NativeActivity` instead of `GameActivity` and add the `android-native-activity` feature to Bevy in your `Cargo.toml` like this:
 
 ```toml
-bevy = { version = "0.19", default-features = false, features = ["android-native-activity", ...] }
+bevy = { version = "0.19", default-features = false, features = ["android-native-activity", <...>] }
 ```
 
-Then build it as the [Build & Run](#build--run) section stated above.
-
-##### About `cargo-apk`
-
-You can also build an APK with `cargo-apk`, a simpler and deprecated tool which doesn't support `GameActivity`. If you want to use this, there is a [folder](./mobile/android_basic) inside the mobile example with instructions.
-
-Example | File | Description
---- | --- | ---
-`android` | [`mobile/src/lib.rs`](./mobile/src/lib.rs) | A 3d Scene with a button and playing sound
-
 ### iOS
 
 #### Setup

examples/README.md

@@ -77,9 +77,8 @@ git checkout v0.4.0
   - [Android](#android)
     - [Setup](#setup)
     - [Build & Run](#build--run)
-    - [About `libc++_shared.so`](#about-libc_sharedso)
+    - [Debugging](#debugging)
     - [Old phones](#old-phones)
-    - [About `cargo-apk`](#about-cargo-apk)
   - [iOS](#ios)
     - [Setup](#setup-1)
     - [Build & Run](#build--run-1)
@@ -702,16 +701,20 @@ Alternatively, you can install Android Studio.
 
 #### Build & Run
 
+<!-- FIXME: Remove --release flag after an issue that makes it necessary for building the example has been resolved.-->
+
+**⚠️ Note:** The `--release` flag is currently necessary for the example. You might be able to omit it when building your own crate.
+
 To build an Android app, you first need to build shared object files for the target architecture with `cargo-ndk`:
 
 ```sh
-cargo ndk -t <target_name> -P 26 -o <project_name>/app/src/main/jniLibs build
+cargo ndk build --link-libcxx-shared -t <target_name> --release -o <project_path>/android/app/src/main/jniLibs
 ```
 
 For example, to compile to a 64-bit ARM platform:
 
 ```sh
-cargo ndk -t arm64-v8a -P 26 -o android_example/app/src/main/jniLibs build
+cargo ndk build --link-libcxx-shared -t aarch64-linux-android --release -o ./android/app/src/main/jniLibs
 ```
 
 Setting the output path ensures the shared object files can be found in target-specific directories under `jniLibs` where the JNI can find them.
@@ -721,21 +724,14 @@ See the `cargo-ndk` [README](https://crates.io/crates/cargo-ndk) for other optio
 After this you can build it with `gradlew`:
 
 ```sh
+cd ./android
 ./gradlew build
 ```
 
 Or build it with Android Studio.
 
 Then you can test it in your Android project.
 
-##### About `libc++_shared.so`
-
-Bevy may require `libc++_shared.so` to run on Android, as it is needed by the `oboe` crate, but typically `cargo-ndk` does not copy this file automatically.
-
-To include it, you can manually obtain it from NDK source or use a `build.rs` script for automation, as described in the `cargo-ndk` [README](https://github.com/bbqsrc/cargo-ndk?tab=readme-ov-file#linking-against-and-copying-libc_sharedso-into-the-relevant-places-in-the-output-directory).
-
-Alternatively, you can modify project files to include it when building an APK. To understand the specific steps taken in this project, please refer to the comments within the project files for detailed instructions(`app/CMakeList.txt`, `app/build.gradle`, `app/src/main/cpp/dummy.cpp`).
-
 #### Debugging
 
 You can view the logs with the following command:
@@ -754,28 +750,18 @@ adb uninstall org.bevyengine.example
 
 #### Old phones
 
-In its examples, Bevy targets the minimum Android API that Play Store  <!-- markdown-link-check-disable -->
-[requires](https://developer.android.com/distribute/best-practices/develop/target-sdk) to upload and update apps. <!-- markdown-link-check-enable -->
-Users of older phones may want to use an older API when testing. By default, Bevy uses [`GameActivity`](https://developer.android.com/games/agdk/game-activity), which only works for Android API level 31 and higher, so if you want to use older API, you need to switch to `NativeActivity`.
+**⚠️ Note:** If you are using `bevy_audio` the minimum supported Android API version is 26 (Android 8/Oreo).
+
+In its example, Bevy uses Android API 36 as `targetSdk` to be able to benefit from security and performance improvements. For backwards compatibility, the example specifies Android API 31 as `minSdk`. This approach is recommended in the [Android Developers documentation](https://developer.android.com/google/play/requirements/target-sdk#why-target).
 
-Keep in mind that if you are using `bevy_audio` the minimum supported Android API version is 26 (Android 8/Oreo).
+Users of older phones may want to use an older API when testing. By default, Bevy uses [`GameActivity`](https://developer.android.com/games/agdk/game-activity), which only works for Android API 31 and higher, so if you want to use an older API, you need to switch to [`NativeActivity`](https://developer.android.com/reference/android/app/NativeActivity).
 
-To use `NativeActivity`, you need to edit it in `cargo.toml` manually like this:
+To use `NativeActivity`, you need to write a custom `MainActivity.kt` using `NativeActivity` instead of `GameActivity` and add the `android-native-activity` feature to Bevy in your `Cargo.toml` like this:
 
 ```toml
-bevy = { version = "0.19", default-features = false, features = ["android-native-activity", ...] }
+bevy = { version = "0.19", default-features = false, features = ["android-native-activity", <...>] }
 ```
 
-Then build it as the [Build & Run](#build--run) section stated above.
-
-##### About `cargo-apk`
-
-You can also build an APK with `cargo-apk`, a simpler and deprecated tool which doesn't support `GameActivity`. If you want to use this, there is a [folder](./mobile/android_basic) inside the mobile example with instructions.
-
-Example | File | Description
---- | --- | ---
-`android` | [`mobile/src/lib.rs`](./mobile/src/lib.rs) | A 3d Scene with a button and playing sound
-
 ### iOS
 
 #### Setup

examples/mobile/android/.gitattributes

@@ -0,0 +1,12 @@
+#
+# https://help.github.com/articles/dealing-with-line-endings/
+#
+# Linux start script should use lf
+/gradlew        text eol=lf
+
+# These are Windows script files and should use crlf
+*.bat           text eol=crlf
+
+# Binary files should be left untouched
+*.jar           binary
+

…ndroid_example_native/app/CMakeLists.txt …amples/mobile/android/app/CMakeLists.txtexamples/mobile/android_example_native/app/CMakeLists.txt renamed to examples/mobile/android/app/CMakeLists.txt examples/mobile/android_example_native/app/CMakeLists.txt renamed to examples/mobile/android/app/CMakeLists.txt

@@ -1,5 +1,5 @@
-# This is part of a hack to convince gradle to insert libc++_shared.so
-cmake_minimum_required(VERSION 3.4.1)
-project(cppshared_dummy)
-set (SRC_DIR ./src/main/cpp)
-add_library (dummy SHARED ${SRC_DIR}/dummy.cpp)
+# This is part of a hack to convince gradle to insert libc++_shared.so
+cmake_minimum_required(VERSION 3.4.1)
+project(cppshared_dummy)
+set(SRC_DIR ./src/main/cpp)
+add_library(dummy SHARED ${SRC_DIR}/dummy.cpp)

examples/mobile/android/app/build.gradle.kts

@@ -0,0 +1,84 @@
+plugins {
+    alias(libs.plugins.android.application)
+}
+
+kotlin {
+    compilerOptions {
+        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_3
+        jvmToolchain(8)
+    }
+}
+
+android {
+    namespace = "org.bevyengine.example"
+    compileSdk = 36
+
+    // https://developer.android.com/reference/tools/gradle-api/9.1/com/android/build/api/dsl/DefaultConfig
+    defaultConfig {
+        applicationId = "org.bevyengine.example"
+        minSdk = 31
+        targetSdk = 36
+        // NOTE: Increase by 1 on each release
+        versionCode = 1
+        // NOTE: Update with full semantic version on each release
+        versionName = "0.0.0"
+        // https://developer.android.com/reference/tools/gradle-api/9.1/com/android/build/api/variant/ExternalNativeBuild
+        // NOTE: We need this, otherwise libc++_shared.so will not be inserted
+        @Suppress("UnstableApiUsage")
+        externalNativeBuild {
+            cmake {
+                arguments("-DANDROID_STL=c++_shared")
+            }
+        }
+        // https://developer.android.com/reference/tools/gradle-api/9.1/com/android/build/api/dsl/Ndk
+        ndk {
+            abiFilters.addAll(listOf("arm64-v8a", "armeabi-v7a", "x86_64"))
+        }
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+    // https://developer.android.com/reference/tools/gradle-api/9.1/com/android/build/api/dsl/ExternalNativeBuild
+    externalNativeBuild {
+        cmake {
+            path = file("CMakeLists.txt")
+        }
+    }
+    // https://developer.android.com/reference/tools/gradle-api/9.1/com/android/build/api/dsl/BuildType
+    buildTypes {
+        getByName("release") {
+            // https://developer.android.com/topic/performance/app-optimization/enable-app-optimization
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
+        }
+    }
+    // https://developer.android.com/reference/tools/gradle-api/9.1/com/android/build/api/dsl/CompileOptions
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_1_8
+        targetCompatibility = JavaVersion.VERSION_1_8
+    }
+    // https://developer.android.com/reference/tools/gradle-api/9.1/com/android/build/api/dsl/BuildFeatures
+    buildFeatures {
+        prefab = true
+    }
+    packaging {
+        // https://developer.android.com/reference/tools/gradle-api/9.1/com/android/build/api/dsl/JniLibsPackaging
+        jniLibs.excludes.add("lib/*/libdummy.so")
+        jniLibs.pickFirsts.add("lib/*/libc++_shared.so")
+    }
+    // https://developer.android.com/reference/tools/gradle-api/9.1/com/android/build/api/dsl/AndroidSourceSet
+    sourceSets {
+        getByName("main") {
+            assets {
+                directories += "../../../../assets"
+            }
+        }
+    }
+}
+
+dependencies {
+    implementation(libs.appcompat)
+    implementation(libs.core)
+    implementation(libs.material)
+    implementation(libs.games.activity)
+    implementation(libs.core.ktx)
+}

examples/mobile/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  xmlns:tools="http://schemas.android.com/tools">
+
+  <application android:icon="@mipmap/ic_launcher" android:label="Bevy Example" android:roundIcon="@mipmap/ic_launcher" android:theme="@style/Theme.AppCompat.NoActionBar" tools:targetApi="36">
+    <activity android:name=".MainActivity" android:exported="true" android:configChanges="layoutDirection|locale|orientation|keyboardHidden|screenSize|smallestScreenSize|density|keyboard|navigation|screenLayout|uiMode" android:theme="@style/Theme.AppCompat.NoActionBar">
+      <meta-data android:name="android.app.lib_name" android:value="bevy_mobile_example" />
+      <intent-filter>
+        <action android:name="android.intent.action.MAIN" />
+        <category android:name="android.intent.category.LAUNCHER" />
+      </intent-filter>
+    </activity>
+  </application>
+
+</manifest>

…droid_example/app/src/main/cpp/dummy.cpp …obile/android/app/src/main/cpp/dummy.cppexamples/mobile/android_example/app/src/main/cpp/dummy.cpp renamed to examples/mobile/android/app/src/main/cpp/dummy.cpp examples/mobile/android_example/app/src/main/cpp/dummy.cpp renamed to examples/mobile/android/app/src/main/cpp/dummy.cpp

@@ -1,2 +1,2 @@
-// Intentionally blank -- this is a dummy code!
-// This is part of a hack to convince gradle to insert libc++_shared.so
+// Intentionally blank -- this is a dummy code!
+// This is part of a hack to convince gradle to insert libc++_shared.so

examples/mobile/android/app/src/main/kotlin/org/bevyengine/example/MainActivity.kt

@@ -0,0 +1,49 @@
+package org.bevyengine.example
+
+import androidx.core.view.WindowCompat
+import androidx.core.view.WindowInsetsCompat
+import androidx.core.view.WindowInsetsControllerCompat
+import com.google.androidgamesdk.GameActivity
+
+/**
+ * Load rust library and handle android specifics to integrate with it.
+ *
+ *
+ * The library is loaded at class initialization and provided by jniLibs.
+ */
+class MainActivity : GameActivity() {
+    /**
+     * Hide system UI if the app window is focused.
+     *
+     *
+     * Called when the current Window of the activity gains or loses focus.
+     */
+    override fun onWindowFocusChanged(hasFocus: Boolean) {
+        // Call parent class implementation of onWindowFocusChanged to make sure that we are updating correctly.
+        super.onWindowFocusChanged(hasFocus)
+
+        if (hasFocus) {
+            hideSystemUi()
+        }
+    }
+
+    /**
+     * Hide system UI.
+     */
+    private fun hideSystemUi() {
+        val windowInsetsController =
+            WindowCompat.getInsetsController(window, window.decorView)
+
+        // Show bars if swiping
+        windowInsetsController.systemBarsBehavior = WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
+        // Hide both the status bar and the navigation bar.
+        windowInsetsController.hide(WindowInsetsCompat.Type.systemBars())
+    }
+
+    companion object {
+        // Load rust library
+        init {
+            System.loadLibrary("bevy_mobile_example")
+        }
+    }
+}