Skip to content

Dev: Android notes

Jump to bottom
Chris McFarland edited this page Jul 16, 2022 · 5 revisions

Here be some notes to help tackle Unity game development for Android.

At the time of this writing (October 2019), I'm using Windows 10, Unity 2019.2, and a Samsung Galaxy S9+ with Android 9 Pie.

Install Unity with Android Build Support

  1. Install a version of Unity via Unity Hub.

  2. During setup, select Android Build Support and its child options for Android SDK & NDK Tools and OpenJDK:

Android Build Support options

Enable Developer Mode on your Android device

  1. Go to Settings > About > Software Information.
  2. Locate Build Number and tap it 7 times. This will enable a new Developer Options category on the Settings page.
  3. Go to Settings > Developer Options, and ensure it is toggled on.

Enable USB for file transfer

With Developer Mode enabled:

  1. Plug your Android device into your main computer via USB cable.
  2. On your Android device, swipe down to show its notification panel.
  3. Tap the USB notification, and select Use USB for Transferring Files.

If successful, your Android device's storage drive should be accessible by opening Windows' File Explorer and selecting This PC.

Can't see your Android device? Try installing drivers

If needed, run Windows Update to hopefully find drivers automatically.

Otherwise, try installing drivers from your Android device's manufacturer, such as:

Run ADB (Android Debug Bridge)

For your Android device to communicate with Unity, ADB needs to recognise your Android device.

adb.exe is part of the Android SDK, which should have been downloaded during the Unity installation.

Locate the directory where adb.exe resides. For example:

C:\Apps\Unity Editors\2019.2.1f1\Editor\Data\PlaybackEngines\AndroidPlayer\SDK\platform-tools\adb.exe

To run ADB on Windows:

  1. Open Windows' Start menu, then search for cmd or Command Prompt to open a Command Prompt.
  2. Change the Command Prompt's directory to ADB's directory using the cd command:
cd "C:\Apps\Unity Editors\2019.2.1f1\Editor\Data\PlaybackEngines\AndroidPlayer\SDK\platform-tools\"
  1. You can then run ADB as a process by typing:
adb start-server
  1. To see if your Android device is detected by ADB, type:
adb devices -l
  1. If you need to end the ADB process, type:
adb kill-server

Testing before compiling: enter Unity Remote 5

Unity offers an Android app called Unity Remote 5, allowing touchscreen-testing without compiling an APK.

Unity Remote 5 can save time if you just need to test touch input, but setting up the app can be a frustrating process.

General steps are:

  1. On your Android device:
    • Ensure Developer Mode is enabled.
    • Ensure USB for File Transfer is selected.
    • Install Unity Remote 5.
  2. On Windows:
    • Ensure ADB is running and that it lists your Android device with the adb devices -l command.
    • Close Unity.
  3. On your Android device:
    • Launch Unity Remote 5.
  4. On Windows:
    • Open Unity.
    • Go Edit > Project Settings > Editor > Device, and ensure Any Android Device is selected from the drop-down menu.
    • Click the Play button.

If successful, your Unity Editor's Game tab will be mirrored onto your Android device, allowing you to tap the screen and have your touches mimicked in the Editor.

Troubleshooting Unity Remote 5

If Unity Remote 5 doesn't mirror your Editor's screen, troubleshooting suggestions include:

  • Clear Unity Remote 5's data and cache:

    • On your Android device's home screen, long-tap on Unity Remote 5, then go App Info > Storage, then tap Clear Data and Clear Cache, or
    • On older versions of Android, go Home Screen > Settings > Storage > Apps > Unity Remote 5, then tap Clear Data and Clear Cache.

  • Add ADB's directory to Windows' PATH:

    • Copy the name of the directory your adb.exe file resides in.
    • Open Windows' Environment Variables by going File Explorer > This PC > right-click a blank space > Properties > Advanced System Settings > Advanced tab > Environment Variables button.
    • Under both User Variables and System Variables, there will be variables named Path.
    • For each Path, select Path, click the Edit button, click the New button, then paste the directory you copied earlier.
    • Click the OK buttons until each window is closed.
    • Restart your computer.

  • Try different USB modes:

    • Various developers have claimed success by selecting different USB modes, such as PTP (pictures) or Tethering.

  • Try different USB cables and ports:

    • Various developers have claimed success by using a different USB cable or different USB port.

  • Ensure Unity's Android tool paths are correct:

    • On Windows, go Unity Editor > Edit > Preferences > External Tools.
    • Ensure the various tick boxes for JDK, Android SDK, and Android NDK are selected.
    • If desired, you can untick them and attempt to locate the directories yourself, but the defaults should be correct if you installed Unity via Unity Hub with Android Build Support selected.

  • Change device to "None" and then back to "Any":

    • If Unity Remote 5 was working previously, go:
      • Unity Editor > Edit > Project Settings > Editor > Device.
      • Change the drop-down to None, then change it to Any Android Device again. This sometimes restores functionality without having to restart anything.

Compiling an APK

When you're ready to compile your APK for Android, a simple way to build is to go:

  • Unity Editor > File > Build Settings > Android.

There are also many settings under Edit > Project Settings > Player.

For more control, a scripted build pipeline can be handy, such as creating a static method with the MenuItem attribute, allowing you to execute the build process via a custom menu item from Unity's toolbar.

Here is a rough example of how builds are scripted for Tallowmere 2:

[MenuItem("Tallowmere 2/Build Game Client/Android", false, 1)]
public static void BuildGame_Android () {
    var buildTarget = BuildTarget.Android;
    string outputFolder = "C:\\UnityBuilds\\Tallowmere2\\Android\\";
    string binaryShortname = "Tallowmere2.apk";
    var buildOptions = BuildOptions.ShowBuiltPlayer;
    BuildGame(buildTarget, outputFolder, binaryShortname, buildOptions);
}

public static void BuildGame (BuildTarget buildTarget, string outputFolder, string binaryShortname, BuildOptions buildOptions) {
    var buildPlayerOptions = new BuildPlayerOptions();
    buildPlayerOptions.scenes = new [] {
        "Assets/Tallowmere2/Scenes/TitleScene.unity",
        "Assets/Tallowmere2/Scenes/MainScene.unity",
        "Assets/Tallowmere2/Scenes/MusicDatabase.unity",
    };
    buildPlayerOptions.locationPathName = outputFolder + binaryShortname;
    buildPlayerOptions.target = buildTarget;
    buildPlayerOptions.options = buildOptions;

    UnityEditor.Build.Reporting.BuildReport buildReport = BuildPipeline.BuildPlayer(buildPlayerOptions);

    if (buildReport.summary.totalErrors == 0) {
        Debug.Log("Game built successfully @ " + buildPlayerOptions.locationPathName);
    }
    else {
        Debug.LogError("Game build failed.");
    }
}

Further reading:

To compress or not compress

Be wary of building with compression – APK file sizes are sometimes larger when compression is used.

Deploying to your Android device

With the APK built, copying the APK file and pasting into a directory on the Android device's storage drive via File Explorer is fast enough.

You can then install your game using your Android system's file manager app.

There are probably ways to automate deployment and installation via scripting, but I have not pursued this yet.

Read logs via Android Logcat

Once your game's installed on your Android device, it can be handy to view its logs from the Unity Editor.

The Android Logcat Unity package lets you inspect your Android device's log in real-time.

Install the package by going:

  1. Unity Editor > Window > Package Manager, which will open a Packages tab.
  2. Within the Packages tab, select the top-left dropdown menu and choose All packages.
  3. In the search field, search for Android Logcat, select it and click the Install button. Packages tab with Android Logcat
  4. Once installed, open the Android Logcat tab by going Unity Editor > Window > Analysis > Android Logcat.
  5. On the Android Logcat tab, you can filter to only show info from specific apps, tags, or log types (priorities). Use the drop-down menus, or right-click column headers for filtering options. Unity Android Logcat example

I recommend filtering to only show your app, and only use the Unity tag.

Building an Android App Bundle (AAB) for Google Play

As Tallowmere 2's regular Android APK build size exceeds Google Play's 150 MB threshold, we need to build the game as an AAB.

As we are using Easy Mobile Pro for Google Play cloud saves, achievements, and leaderboards, some fun things need to be included in the Unity project:

  • Google Play Asset Delivery

    • Easy Mobile Pro comes with an External Dependency Manager for Unity (namespace: com.google.external-dependency-manager), which appears to add many Google packages available within Unity's Package Manager.

Gotchas

Either Easy Mobile Pro or the External Dependency Manager adds a com.google.android.play.core-1.8.0.aar file within the Unity project's Assets/Plugins/Android directory.

However, the Google Play Asset Delivery package also includes its own playcore.aar file.

As such, when trying to build an Android App Bundle, the compiler fails because various com.google.android.play.core modules/classes are duplicated because these two core .aar files are trying to both be included in the final build.

Solution: In Unity's Project tab, inspect Assets/Plugins/Android/com.google.android.play.core-1.8.0 and deselect the Android checkbox in the Inspector tab.

Utilising Unity's AssetBundles

Part of this whole APK/AAB file-size workaround is to ensure the main installable APK file Google Play distributes is less than 150 MB, and then extra files can be loaded post-install (even though they will be delivered at runtime during the initial download from Google Play Store).

As of Tallowmere 2 v0.1.7, the game is built with three Unity scenes:

  1. LoadingScene.unity (< 1 MB)
  2. MusicDatabase.unity (~47 MB)
  3. MainScene.unity (~58 MB)

For Windows, macOS, Linux, and iOS builds, we can get away with compressing the scenes into one large file, but this doesn't work for the Android Google Play file-size threshold.

To build the AAB file satisfactorily:

  • We use the Google Play Asset Delivery package to tell Unity to build the game with LoadingScene.unity as the only scene, and
  • We tag the MusicDatabase.unity and MainScene.unity scene files as individual AssetBundles (Unity's Asset Bundle Browser package comes in handy here).

Then, at runtime when the game is launched, a script within the LoadingScene uses Google.Play.AssetDelivery.PlayAssetDelivery methods to load the two scene AssetBundles from disk.

Fixing Gradle issues

Sometimes, Gradle has errors.

To fix this without mucking around with any installations or editing any files:

  1. Unity > Edit > Preferences > External Tools
  2. Click and click again on each JDK, Android SDK, Android NDK, and Gradle checkbox. The act of toggling each checkbox resets something within Unity's settings.

Afterwards, Gradle should function properly. Check by going Unity > Assets > External Dependency Manager > Android Resolver > Force Resolve.

unity_android_gradle_fix

Detecting Android TV

Gist: Platform_AndroidTV.cs

Clone this wiki locally