Official 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

 

We're in talks with Google trying to resolve this, but basically when not using templates, EDM4U is downloading packages as .aar files and puts them in Assets\Plugins\Android, those end up in the generated gradle project and in some cases they conflict with dependencies added for GameActivity:

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

 

Sadly its impossible with earlier Unity versions, since we had to refactor some code in core engine, additonally we exposed some hooks. So without those things, its not possible to connect GameActivity to Unity runtime

 

Regarding Unity IAP, you would need to submit a feedback/bug for them, since there's a dedicated team working on this package.

Starting Unity 2023.1, we'll provide API for managing gradle files - https://docs.unity3d.com/2023.1/Documentation/Manual/android-modify-gradle-project-files-agp.html, it might already provide the functionality you want, if not, we would love to get your feedback on this.

 

Can you provide examples where you would use specifically UnityPlayerActivity in the plugins? Usually I think it's enough to use UnityPlayer.currentActivity which would return Activity instance in both cases (UnityPlayerActivity and UnityPlayerGameActivity)

 

Check UnityPlayerGameActivity.onCreateSurfaceView, there's a variable mSurfaceView, also UnityPlayer class has getView function, which also returns surface view instance.

As for overriding surface view with your own, check https://android.googlesource.com/pl...m/google/androidgamesdk/GameActivity.java#251, I think you can override createSurfaceView and provide your own surface view, but it has to derive from InputEnabledSurfaceView. I haven't tried this myself, so not sure how fluent the process is

 

Yes, I am actually not sure what would happen if you would submit an app with two activities enabled, would store deny such submission, since that would produce to application icons with the same name and icon, which obviously would be confusing.

 

I don't think this is an issue in Unity, since Unity has code which handles key down/up events happening in the same frame. Though I see that this is incorrectly handled by input system package, but that would be a bug in input system package, so I think in this case Google is correct in saying, that they shouldn't introduce any artificial delays, it's up to game engine to handle this gracefully.

In any case, thank you for highlighting this.

 

Thanks for reporting, it looks like a bug we missed. We'll try to fix it asap.

 

If you're asking if the fix will be in 2023.1.4f1, then no, the fix needs to first land into our main branch, and only then it will be backported to Unity versions like 2023.1.

Currently the fix is being reviewed by our QA.

 

Just to clarify, your UI elements are with different layout when you launch with GameActivity?

 

Please create a separate thread in https://forum.unity.com/forums/android.30/, since you're problem is not GameActivity specific, and please attach some screenshots from Android device, since I am not exactly sure what you're talking about. Thank you.

 

The fix is still being verified, you can track it here - https://issuetracker.unity3d.com/product/unity/issues/guid/UUM-42522 (should be up in few minutes)

 

Ideally, you shouldn't need to do any custom implementation yourself if you switch to GameActivity, but there might be edge cases, we don't know about

I don't think that's related to GameActivity, the logic which chooses how many worker threads to use is controlled by Unity's native engine part, which is independent from Application Entry Point option. Try asking XR forum section for more details regarding worker threads on XR.

 

I would say users benefit more from GameActivity than Unity due code being more transparent, the reason being - the whole lifecycle code area is managed now by GameActivity package which is provided by platform owner - Google.
Also, the most important reason, in case of a bug, you no longer need to wait for Unity to provide the fix, you can either get the fix directly from Google, or apply a local patch, which is especially important in late development cycle.

 

In some cases - for ex., input handling - yes, because input events will now come via game activity package.

 

GameActivity uses Google's https://developer.android.com/games/agdk/add-support-for-text-input to show TouchScreenKeyboard, GameTextInput implementation doesn't show native input field above touch screen keyboard. There should be also a message in logcat informing that.

 

@rmiha good catch - I can confirm we are aware of this issue and waiting for a fix from Google's AGDK. We will rollout after this. Please let us know if you encounter anything else.

 

I think it might be fixed in game activity package 3.0, when it's out - https://mvnrepository.com/artifact/androidx.games/games-activity

 

Can you give more information? What error are you getting, if you're building to GameActivity, yes - the above dependencies are needed.

 

In ANR case, there should be multiple threads reported