android-activity

Unlike older Android glue crates, android-activity is designed to avoid global static state. This provides several architectural benefits:

1. Encapsulated State: Instead of using global getters to access application state, the entry point provides an explicit app: AndroidApp argument. This argument encapsulates the state connected to a single Activity.
2. Lifecycle Resilience: Because it avoids global statics, applications can gracefully handle repeated create -> run -> destroy cycles of the Activity.
3. Multi-Activity Support: The design theoretically allows for running multiple Activity instances simultaneously, as state is not tied to a global singleton.
4. Thread Synchronization: The crate encapsulates the Inter-Process Communication (IPC) and synchronization required between the native thread and the JVM thread, reducing the risk of race conditions during state changes (like state saving).

Choosing between NativeActivity and GameActivity depends on your application's requirements for input and complexity:

NativeActivity

• Best for: Simple apps, quick prototyping, or applications that require zero Java/Kotlin code.
• Pros: Shipped with the Android OS; allows building purely in Rust without any Java/Kotlin.
• Cons: Limited input method support (no built-in onscreen keyboard support; only physical key events).
• Setup: Enable the native-activity feature in Cargo.toml.

GameActivity

• Best for: Modern games, apps requiring text input (IME), and apps using AndroidX features.
• Pros: Built-in support for input methods (via GameTextInput), AppCompatActivity features, and better compatibility across Android versions.
• Cons: Requires adding a Gradle dependency and compiling some Java/Kotlin code.
• Setup:
  1. Add androidx.games:games-activity:4.4.0 to your Gradle dependencies.
  2. Enable the game-activity feature in Cargo.toml.
  3. Warning: Do NOT enable Android Prefab support in Gradle or CMake, as android-activity provides its own native glue layer.

The agdk-mainloop example is a minimal test application based on GameActivity. It demonstrates how to run a mainloop using android_activity::poll_events(), trace received events without rendering, and save/restore minimal application state.

To run this example on an Android device or emulator, follow these steps:

1. Set up environment variables: Ensure your NDK and SDK paths are exported.
2. Prepare the Rust toolchain: Add the Android target and install cargo-ndk.
3. Build the native library: Use cargo ndk to build for the arm64-v8a target and output the resulting JNI libraries to the Android project directory.
4. Build and install the Android app: Use Gradle to build the APK and install it.
5. Launch the activity: Use adb to start the MainActivity.

# 1. Set environment variables
export ANDROID_NDK_HOME="path/to/ndk"
export ANDROID_HOME="path/to/sdk"

# 2. Prepare toolchain
rustup target add aarch64-linux-android
cargo install cargo-ndk

# 3. Build native library
cargo ndk -t arm64-v8a -o app/src/main/jniLibs/ build

# 4. Build and install app
./gradlew build
./gradlew installDebug

# 5. Launch the app
adb shell am start -n com.github.rust_mobile.agdkmainloop/.MainActivity

When updating android-activity to a new version of the Android Game Development Kit (AGDK), follow this checklist to rebase integration patches and regenerate bindings:

1. Prepare the integration branch: Clone the android-games-sdk repository, add the Google remote, and rebase your integration branch onto the latest Google release branch using the appropriate <base> commit ID.
2. Set Environment Variable: Set ANDROID_GAMES_SDK to point to your external games-sdk branch to allow building android-activity against it during the update process.
3. Regenerate Bindings: Run ./generate-bindings.sh to recreate the GameActivity FFI bindings.
4. Update Build Configuration: Modify build.rs to include any new header files or source files introduced by the new AGDK version.
5. Update Backend: Adjust the src/game-activity backend implementation if required by the new SDK version.
6. Import Source: Once the external branch is ready, run ./import-games-sdk.sh to copy the new AGDK code into the android-activity repository.
7. Document the Update: Reference the specific branch name and commit hash from the android-games-sdk repository in your android-activity commit and update CHANGELOG.md.

# Example rebase workflow
git clone git@github.com:rust-mobile/android-games-sdk.git
cd android-games-sdk
git remote add google https://android.googlesource.com/platform/frameworks/opt/gamesdk
git fetch google
git checkout -b android-activity-5.0.0 origin/android-activity-4.0.0
git rebase --onto google/android-games-sdk-game-activity-release <base>
# (where <base> is the upstream commit ID below our stack of integration patches)

If you are using a standard Android build workflow, you can build and install the na-mainloop example using Gradle. This requires setting up your NDK and SDK environment variables and using cargo-ndk to compile the Rust components into JNI libraries before running the Gradle tasks.

Prerequisites:

• ANDROID_NDK_HOME and ANDROID_HOME must be set.
• The aarch64-linux-android target must be added via rustup.
• cargo-ndk must be installed.

Steps:

1. Compile the Rust code into the app/src/main/jniLibs/ directory using cargo ndk.
2. Build the Android project using ./gradlew build.
3. Install the debug APK using ./gradlew installDebug.
4. Launch the NativeActivity via adb shell.

export ANDROID_NDK_HOME="path/to/ndk"
export ANDROID_HOME="path/to/sdk"

rustup target add aarch64-linux-android
cargo install cargo-ndk

cargo ndk -t arm64-v8a -o app/src/main/jniLibs/  build
./gradlew build
./gradlew installDebug

# To run:
adb shell am start -n com.github.realfit_mobile.namainloop/android.app.NativeActivity

To use android-activity, configure your Cargo.toml to output a cdylib and enable either the native-activity or game-activity feature. You must implement the android_main function, which runs on a dedicated thread and handles the application's event loop.

Important Lifecycle Note: android_main is tied to the Activity lifecycle, not the application lifecycle. If the Activity is destroyed and recreated, android_main may be called multiple times. Use std::sync::OnceLock to ensure global state (like logging) is only initialized once.

[dependencies]
log = "0.4"
android_logger = "0.13"
android-activity = { version = "0.6", features = [ "native-activity" ] }

[lib]
crate-type = ["cdylib"]

use std::sync::OnceLock;
use android_activity::{AndroidApp, InputStatus, MainEvent, PollEvent};

#[unsafe(no_mangle)]
fn android_main(app: AndroidApp) {
    static APP_ONCE: OnceLock<()> = OnceLock::new();
    APP_ONCE.get_or_init(|| {
        android_logger::init_once(android_logger::Config::default().with_min_level(log::Level::Info));
    });

    loop {
        app.poll_events(Some(std::time::Duration::from_millis(500)), |event| {
            match event {
                PollEvent::Wake => { log::info!("Early wake up"); },
                PollEvent::Timeout => { log::info!("Hello, World!"); },
                PollEvent::Main(main_event) => {
                    match main_event {
                        MainEvent::Destroy => { return; }
                        _ => {}
                    }
                },
                _ => {}
            }

            app.input_events(|event| {
                log::info!("Input Event: {event:?}");
                InputStatus::Unhandled
            });
        });
    }
}

Input events (Key, Motion, Text, and Text Actions) are processed using an iterator pattern. The InputIteratorInner::next method allows you to dispatch events to a callback function.

When iterating, the system handles:

1. Buffered Events: Key events and Motion events currently in the input buffer.
2. Text Input State: Changes to the IME (Input Method Editor) text state.
3. Editor Actions: Pending text actions (e.g., 'Enter' or 'Done' from a keyboard).

The iterator ensures that input state changes are processed before checking for editor actions so that actions apply to the most recent state.

/* 
Conceptual usage of the input event loop:

while input_iterator.next(|event| {
    match event {
        InputEvent::KeyEvent(key) => { /* handle key */ }
        InputEvent::MotionEvent(motion) => { /* handle motion */ }
        InputEvent::TextEvent(text) => { /* handle text */ }
        InputEvent::TextAction(action) => { /* handle action */ }
    }
    InputStatus::Consumed // or other status
}) {
    // loop continues
}
*/