Official [Android] Introducing GameActivity for Android in 2023.1

Hello from the Android Platform team with some exciting news!


Starting from Unity 2023.1 you can now choose a new application entry for Android - GameActivity. Under the hood, this is powered by the GameActivity Jetpack library, with all the benefits that this brings.


Why switch to GameActivity?

We believe that this feature will improve your Android development and app runtime experience in three ways:

1. You will have better threading support for lifecycle, input, and touchscreen keyboard events
2. You can update the GameActivity package outside of Engine updates
3. You can tweak the new Unity<>Android Bridge with your own customisations

Better threading support
A major benefit to GameActivity is that many of the main application elements are now being handled by Android’s androidx.games:games-activity package, this includes:

• Lifecycle events
• Touchscreen keyboard
• Input events

Google has published a use case where a reduction in ANRs was observed when using GameActivity. Since androidx.games:games-activity handles everything in the separate thread, we hope that you will also see similar benefits in your Unity applications.

Updatability
The AndroidX GameActivity Package is being maintained by Google and can be updated without updating the Unity version, it is simple enough to tweak the androidx.games:games-activity package version in unityLibrary/build.gradle file. So any bug fixes and improvements can be received without waiting for a Unity Engine update.

GameActivity-to-Unity bridge
As part of the Game Activity work we’ve introduced gameactivity-to-unity bridge layer.

If you switch to GameActivity you will also be able to tweak or change the bridge code (between Unity and androidx.games:games-activity package). This will give you even more flexibility over the events like pause/resume, which was previously impossible with Activity based applications. Read more about the bridge here.


Future of Game Activity

Our ambition is that GameActivity application entry point will become the main selection for the Android based applications created with Unity in the future. In 2023.1 the default application entry point remains Activity, and you have to turn GameActivity on explicitly. IIn Unity 2023.2, GameActivity will be turned on by default for new projects. When upgrading older projects to Unity 2023.2 the application entry setting will be preserved.

I’m sold - how can I try it out?

You can find the documentation for GameActivity here. The application entry setting can be found in Player Settings (Android):




Depending on what value you choose - the Gradle project will contain the following entry points:

• UnityPlayerActivity.java - if Activity is chosen.
• UnityPlayerGameActivity.java - if GameActivity is chosen.

As seen in the screenshot, you can both select Activity and GameActivity at the same time, this useful for testing purposes, since you don’t need to rebuild the application to run the application with Activity or GameActivity.

Note: If there are two activities selected, you’ll see two applications icons on your android device.


If you want to debug your application in AndroidStudio:

• Export a Gradle project with Activity and GameActivity selected
• Open the project in Android Studio
• Under Run/Debug Configurations->General->Launch Activity->Launch Options pick Specified Activity
• This way you can quickly switch between two application entry points and compare the behaviour of your application

Note: When building a non development application, Unity will warn you if there are more than one application entry point selected, since it’s not suitable for uploading to the store. Selecting two application entry points is only suitable for development purposes.

To switch your application to only use GameActivity application entry point, simply go to PlayerSettings (Android), locate Application Entry Point setting, deselect Activity and select GameActivity.


A note about plugins & dependencies

Plugin Creators

We expect that most plugins should work the same for both application entry points - Activity and GameActivity. Known exceptions:

• Your plugin explicitly references UnityPlayerActivity.

If the app using your plugin targets only GameActivity, UnityPlayerActivity won’t exist. We advice not to use UnityPlayerActivity or UnityPlayerGameActivity classes directly in your plugin. It’s better to detect the current Activity with UnityPlayer.currentActivity .​

• You use the Looper API directly or indirectly

If you target GameActivity, the main game looper runs on the native thread (created via pthread API) thus there’s no java Looper associated with that thread, calling that API will cause a null reference exception. You can use getMainLooper instead. Note: This looper runs on main/UI thread, if you have a long operation, it’s not recommended to use this looper, otherwise you’ll get ANR.

You can also create Java thread manually and create a looper on this thread instead, but you’ll need to handle synchronisation between game looper thread and your manually created Java thread​

Dependencies

When targeting GameActivity, Unity adds the following dependencies into unityLibrary\build.gradle:

• androidx.appcompat:appcompat
• androidx.games:games-activity
• androidx.core:core
• androidx.constraintlayout:constraintlayout

If you use auto-resolution tools like Google’s EDM4U, you need to create the following templates to avoid conflicts during the gradle.build:

• Main Gradle Template
• Gradle Properties Template
• Gradle Settings Template

We need your feedback!

We can’t wait to see how you use GameActivity and the bridge layer in your projects, and if you observe lifecycle/ANR improvements. Your feedback is very important to us - please let us know if you encounter any issues or if you have suggestions to share.

—-

Known Issues

• You cannot enter characters with physical keyboard while touchscreen keyboard is up, should be fixed in androidx.games:games-activity 2.0.0 version
  
  
• Sometimes application crashes in GameActivityMotionEvent_getHistoricalAxisValue when introducing a lot of motion events, should be fixed in androidx.games:games-activity 2.0.0 version

 

It seems you've found a bug, you can workaround it, by exporting gradle project instead and building from Android Studio.

You need to tweak UnityPlayerGameActivity.java a bit.

The faulty code is:

Code (CSharp):

1.         mUnityPlayer = new UnityPlayerForGameActivity(this, frameLayout, mSurfaceView, this);
2.         String cmdLine = updateUnityCommandLineArguments(getIntent().getStringExtra("unity"));
3.         getIntent().putExtra("unity", cmdLine);

it should have been:

Code (CSharp):

1.         String cmdLine = updateUnityCommandLineArguments(getIntent().getStringExtra("unity"));
2.         getIntent().putExtra("unity", cmdLine);
3.         mUnityPlayer = new UnityPlayerForGameActivity(this, frameLayout, mSurfaceView, this);

Thanks for highlighting this, we'll fix it on our end

 

Yes, the entry point for GameActivity is UnityPlayerGameActivity. Also, note, for UnityPlayerGameActivity there are additional entries in the manifest file