Integrating Unity into Android applications
This page describes how to integrate the Unity Runtime Library into Android applications using the Unity as a Library feature.
You can use this feature to include Unity-powered features, such as 3D/2D Real-Time Rendering The process of drawing graphics to the screen (or to a render texture). By default, the main camera in Unity renders its view to the screen. More info
See in Glossary , AR Augmented Reality (AR) uses computer graphics or video composited on top of a live video feed to augment the view and create interaction with real and virtual objects.
See in Glossary Experience, 3D model interaction, or 2D mini-games, into your application. The Unity Runtime Library exposes controls to manage when and how to load, activate, and unload content within the application.
Important: If you upgrade your project to Unity 2019.4 or above, the introduction of Unity as a Library might require you to adapt native and managed plug-ins A set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
See in Glossary to work properly for Android. Plug-ins that make changes to Gradle An Android build system that automates several build processes. This automation means that many common build errors are less likely to occur. More info
See in Glossary manifests need to use the the Gradle changes outlined in Using Unity as a library in native iOS/Android apps.
How it works
You don’t need to do anything different when you build your Gradle project from Unity.
Every Android Gradle project that Unity generates has the following structure:
- A library part in the unityLibrary module that you can integrate into any other Gradle project. This contains the Unity runtime and Player data.
- A thin launcher part in the launcher module that contains the application name and its icons. This is a simple Android application that launches Unity. You can replace this module with your own application.
To integrate Unity into another Android Gradle project, you must include the unityLibrary module of the generated Android Gradle project in your Android Unity Project through the settings.gradle file.
This repository contains example Projects and plug-ins that demonstrate how to integrate Unity into an Android app, along with further documentation.
To control a Player, relay an Intent to launch Unity activity and extend it if needed. For more information, see Android developer documentation on Intents and Intent Filters. You can also use the UnityPlayer Java API.
IUnityPlayerLifecycleEvents
IUnityPlayerLifecycleEvents provides a way to interact with two important lifecycle events of the Unity Player:
- Unload — The application calls IUnityPlayerLifecycleEvents.onUnityPlayerUnloaded when Application.Unload or UnityPlayer.unload() unloads the Unity Player. This puts the Unity Player in a paused state where it unloads all Scenes A Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary , but keeps everything else loaded in the memory. - Quit — The application calls IUnityPlayerLifecycleEvents.onUnityPlayerQuitted when the Unity Player quits. The process that was running Unity ends after this call.
You can pass an instance of IUnityPlayerLifecycleEvents to the UnityPlayer constructor, or to override methods in subclasses of UnityPlayer and UnityPlayerActivity .
Limitations
Unity doesn’t control the runtime lifecycle, so Unity as a Library might not work for all possible use cases. Known limitations include:
- Unity as a Library only supports full-screen rendering, and doesn’t support rendering on part of the screen.
- You can’t load or integrate more than one instance of the Unity runtime.
- You might need to adapt third-party plug-ins (both native and managed) to work with the Unity runtime.
- Unity as a Library for Android added in 2019.3. NewIn20193
Источник
Building apps for Android
There are two locations to configure settings that affect how your app is built:
- Player settings — Allows you to configure runtime settings for the app. For more information on Player settings, see Player settings for the Android platform.
- Build settings — Allows you to configure build system parameters and build the app.
The output package includes an APK, and an APK expansion file (OBB) if the Split Application Binary option is selected in the Player settings. For more information on OBB files, see OBB Support.
To optimize for download and installation size, enable the Split APKs by target architecture option in the Player settings. The Split APKs by target architecture option produces one set of APKs and OBBs for each device architecture selected in the Target Architecture list in the Player settings. You can upload this set of APKs (and OBBs, if enabled) to the Google Play, or other, store instead of a FAT APK in which all of the selected architectures are included into a single APK. For more information on this feature, see Multiple APK support on the Android Developer website.
Configuring Build Settings
To configure and build apps for Android, access the Build Settings window (File > Build Settings). In Platform, select Android.
To set Android as your default build platform, click the Switch Platform button.
After you specify your build settings, click the Build button to create your build. To build the app, click Build And Run to create and run your build on the platform you have specified.
| Setting | Функция: |
|---|---|
| Texture Compression | The Unity Android build system supports the following texture compression format options: Don’t override, DXT (Tegra), PVRTC (PowerVR), ETC (default), ETC2 (GLES 3.0), and ASTC. For advice on using these formats, see the Texture Compression section below. |
| ETC2 fallback | 32-bit, 16-bit, and 32-bit, half resolution. |
| Build System | |
| Internal (deprecated) — Generate the output package (APK) using the internal Unity build process, based on Android SDK utilities. Selecting Internal hides the Export Project checkbox. | |
| Gradle — Generate the output package (APK) using the Gradle build system. Supports direct Build and Run and exporting the Project to a directory. This is the default Build System for Unity. | |
| Export Project | Export the Project as a Gradle project that you can import into Android Studio. |
| Build AppBundle (Google Play) | Build an Android App Bundle for distribution on Google Play. Selecting this option also lets you configure the Warn about App Bundle Size option in the Player settings. |
| Run Device | A drop-down list of attached devices on which you can test your build. If you connect a new device or you don’t see an attached device in the list, click the Refresh button to reload the list. |
| Development Build | A development build includes debug symbols and enables the Profiler. Selecting Development Build allows you to select the Autoconnect Profiler, Script Debugging, and Scripts Only Build options. |
| Autoconnect Profiler | Allows the Profiler to automatically connect to the build. Selectable when the Development Build option is selected. For more information on the Profiler, see Profiler Overview. |
| Script Debugging | Allow script debuggers to attach to the Player remotely. Enabled when the Development Build option is selected. |
| Scripts Only Build | Check this option to build just the scripts in the current Project. Enabled when the Development Build option is selected. |
| Compression Method | Compress the data in your Project at build time. Choose between the following methods: |
| Default — The default compression is ZIP, which gives slightly better compression results than LZ4 and LZ4HC, but data is slower to decompress. | |
| LZ4 — A fast compression format that is useful for development builds. Using LZ4 compression can significantly improve loading time of games/apps built with Unity. For more information, see BuildOptions.CompressWithLz4. | |
| LZ4HC — A high compression variant of LZ4 that is slower to build but produces better results for release builds. Using LZ4HC compression can significantly improve loading time of games/apps built with Unity. For more information, see BuildOptions.CompressWithLz4HC. | |
| SDKs for App Stores | Select which third party app stores to integrate with. To include an integration, click Add next to an App Store name. The Unity Package Manager automatically downloads and includes the relevant integration package. |
Texture compression
Unity uses the Ericsson Texture Compression (ETC) format for textures that don’t have individual texture format overrides. When building an APK to target specific hardware, use the Texture Compression option to override this default behavior. Texture Compression is a global setting for the Project. If a texture has a specific override on it, that texture is not affected by the Texture Compression setting. For additional information, see Textures.
For additional information on textures and texture compression, see the Mobile and WebGL specific formats and Notes on Android sections on the Texture compression formats for platform-specific overrides page.
Note: Texture Compression is a global setting. Individual textures override the global setting.
ETC2 fallback
For Android devices that don’t support ETC2 (which don’t support GL ES3), you can override the default ETC2 texture decompression by choosing from 32-bit, 16-bit, or 32-bit with half the resolution formats.
This option allows you to choose between the uncompressed image quality and the amount of memory the uncompressed texture occupies. 32-bit RGBA texture is the highest quality format, and takes twice the required disk space as the 16-bit format, but a texture in 16-bit might lose some valuable color information. 32-bit half-resolution reduces the memory requirement further, but the texture is likely to become blurry.
Build system
Unity supports two Android build systems: Gradle and Internal.
The steps involved with building for Android are:
Preparing and building the Unity Assets.
Processing the plug-ins.
Splitting the resources into the parts that go to the APK and the OBB, if Split Application Binary is selected.
Building the Android resources using the AAPT utility (internal build only.)
Generating the Android manifest.
Merging the library manifests into the Android manifest (internal build only.)
Compiling the Java code into the Dalvik Executable format (DEX) (internal build only.)
Building the IL2CPP library, if IL2CPP Scripting Backend is selected.
Building and optimizing the APK and OBB packages.
Gradle build system
The Gradle build system uses Gradle to build an APK or export a Project in Gradle format, which can then be imported to Android Studio. When you select this build system, Unity goes through the same steps as the Internal build system excluding resource compilation with AAPT, merging manifests, and running DEX. Unity then generates the build.gradle file (along with the other required configuration files) and invokes the Gradle executable, passing it the task name and the working directory. Finally, the APK is built by Gradle.
Internal build system
The Internal build system creates an APK using the Android SDK utilities to build and optimize the APK and OBB packages. For more information about OBB files, see OBB Support.
Exporting the Project
If you need more control over the build pipeline, or to make changes that Unity does not normally allow (for example, fine tuning the manifest files that are automatically generated by Unity), you can export your Project and import it into Android Studio. Exporting a Project is only available when you have selected Gradle as your Build System.
To export the Project:
- From the Build System drop-down menu, select Gradle.
- Check the Export Project checkbox. When Export Project is checked, the Build button is relabeled Export and the Build And Run button is disabled.
- Click the Export button and select a destination folder for the project.
When the export finishes, open Android Studio and import your project. For more information on importing projects to Android Studio, see the Migrate to Android Studio section of the Android Developer documentation.
Build or Build and Run
The Build Settings window offers two options: Build and Build and Run. Using either option saves the output packages (APK and OBB, if enabled) to the path that you select. You can publish these packages to the Google Play Store, or install them on your device manually with the help of Android Debug Bridge (ADB). For further information about installing apps manually, see the Run your app section of the Android Developer documentation. For information on ADB commands, see the Android Debug Bridge section of the Android Developer documentation.
Selecting Build and Run saves the output packages to the file path you specify, while also installing your app on the Android device connected to your computer.
If the Split Application Binary option is enabled, the OBB file is pushed to the correct location on your device. If Development Build is checked, Unity also sets up a Profiler tunnel and enables CheckJNI. After that, the app is launched. The Split Application Binary setting is located in the Publishing Settings section of the Player settings.
Tip: Specify the output path for the packages and then use the Ctrl+B (Windows) or Cmd+B (macOS) keyboard shortcut to Build and Run using the saved output path.
2018–11–19 Page amended
Updated functionality in 5.5
Updated the Build Settings Configuration options
Источник
