Monday, 26 June 2017

Manually copying Unity's APK and OBB files to an Android device for testing

When developing an Android game that is meant to be published through the PlayStore, there's a limitation regarding the maximum file size of the APK. It currently can't exceed 100 MB.

The thing is that games usually go beyond that limit. To deal with that, Google offers the so called APK Expansion Files. Every application can include up to 2 of them, with a maximum size of 2 GB each.

If your game goes beyond 100 MB, you can easily instruct Unity to split the game in two by checking the "Split Application Binary" in Edit->Project Settings->Player->Android->Publishing Settings.

Image result for unity split application binary

That will generate two files instead of one:
  • APK: the usual APK file with all the binaries, scripts etc, and the first scene included in the build settings (the scene with build index 0). You need to take care that the first scene is small enough so this APK doesn't go beyond 100 MB. In general, this scene is usually just a loading icon, or a game logo that is displayed while loading. 
  • OBB: A second Expansion File with the OBB, holding everything else. 
Some time ago, it was necessary to use a Unity plugin to deal with OBB loading, but this is no longer necessary. So, first of all, DO NOT USE that plugin. In fact, it hasn't been updated for years, and won't work in current versions of Unity. 

Current versions of Google PlayStore natively support the distribution of OBB files, so you won't need to do anything special besides providing the OBBs along with the APK when you upload your game.

Note: usually, the first time you upload your game to Google Play, it won't ask you for OBB expansion files (I guess that's a bug in the system). If that's your case, simply generate a second version of your game, and re-upload your APK. Then it will ask for Expansion Files properly. 

How to install the game locally, in a test device? 

In normal circumstances, you  just create one big APK, copy it manually to the SD-Card of your phone, and install the game by tapping on the APK file. If you do that now, the game will install fine but it won't be able to find the Expansion OBB files, so the first scene will load fine, but it will probably get stuck there. 

In order to let the game find the OBB files, you need to:

1.- Rename the OBB so it follows the convention:

Unity creates valid OBB files, but their names don't follow the convention Android expects. Your OBB file should have a name like the following: 

main.[VERSION_NUMBER].[PACKAGE_NAME].obb

Where [VERSION_NUMBER] is the highest digit of the version number you can find in the Player Settings:


And [PACKAGE_NAME] is the package name specified in the same screen, right above the version number:


So, in the example depicted in the images, the name of the OBB file would be:

main.1.com.iayucar.TestGame1.obb

2.- Copy the renamed OBB file to an specific location

The game will expect to find that OBB file in a location like:

[INSTALL_LOCATION]\Android\obb\[PACKAGE_NAME]

Where [PACKAGE_NAME] is the same value described above, and INSTALL_LOCATION refers to whether the game is installed in the internal memory or the external SD-Card (this depends on your own settings). 

As our game is configured to be installed in an external SD-Card preferably, the folder where we need to paste the OBB file is:

\\SDCard\Android\obb\com.iayucar.TestGame1\

And that's it. Now you can launch the game, and it will properly find the additional contents included in the OBB Expansion File. 

No comments: