Android Application Development

Unigine SDK is not a full development environment and you need to install the required software before starting up:

1. Install the Android SDK (the latest version can be downloaded from the official site for free).
2. Install the Android NDK (the latest version can be downloaded from the official site for free).
3. For Windows and Linux development platforms, install JDK (Java Development Kit); it can be downloaded for free.
4. For Windows, install Apache Ant (it can be downloaded for free).
5. Add the following environment variables:
   • NDKROOT that specifies the path to the Android NDK. For example, on Linux type the following:
     Shell commands

     username@pc-name$ export NDKROOT=/home/username/development/android-ndk-5c
     

   • Path to arm-eabi-g++ compiler. For example, on Linux type the following:
     Shell commands

     username@pc-name$ export PATH=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin
     

6. In addition, you may also need to set up your system to detect Android device via USB. See the official guide for more information.
7. Install SCons 2.0 (can be downloaded for free).
8. Install Python 2.7 (can be downloaded for free).

Unigine SDK for Android requires a source SDK version to be already installed since it contains only Android-specific files without the engine itself. You need to unpack the Unigine archive and add all files (preserving folder structure) to the source SDK.
After that, you will have all files required to build Unigine engine for Android platform. Additionally, there are included sample applications that can be used as a template to create your own application package file.

Using SCons you can build Unigine engine for Android. By following these steps you will also build a default .apk file with generic interface that can be later used to develop your own application.

1. Open your console.
2. Go to the <UnigineSDK>/source/app/Android/jni directory.
3. Type scons and specify android platform. By default, the ARM-based debug build for Android devices will be created. (See the details on other available SCons compilations options).
   Shell commands

   username@pc-name$ cd ~/UnigineSDK/source/app/Android/jni/
   username@pc-name$ scons platform=android
   

   By compilation, the following two libraries will be created and placed into <UnigineSDK>/source/app/Android/libs/armeabi folder (in addition to libopenal.so already present there):
   • libUnigineActivity.so
   • libUnigine.so
4. The next step is to update a project (see more details). It generates all files and folders required to be present in an Android project.
   Type the following in the console:
   Shell commands

   username@pc-name$ cd ~/UnigineSDK/source/app/Android
   username@pc-name$ android update project --name Main --target 3 --path ./
   

   For Linux and Mac development platforms, you can simply run update.sh:
   Shell commands

   username@pc-name$ update.sh
   

5. To build a default project for Android in the debug mode (it will only have basic interface and black viewport), use Ant (see more details):
   Shell commands

   username@pc-name$ ant debug
   

   By that, Main-debug.apk will be created and saved into <UnigineSDK>/source/app/Android/bin directory.
6. Connect the Android device to your development machine.
7. After that, you can copy the created application package file from your development computer and install it on the device using adb tool (see more details):
   Shell commands

   username@pc-name$ adb install ~/UnigineSDK/source/app/Android/bin/Main-debug.apk
   

Building the development version of your Android application is really fast and simple once you've build and installed .apk file that launches the engine.

1. Open <UnigineSDK>/source/app/Android/unigine.cfg. Specify your project world to be loaded or a system script that will load it.
   Source code (XML)

   <item name="console_command" type="string">world_load my_world</item>
   <!--or-->
   <item name="system_script" type="string">my_project/unigine.cpp</item>
   

   It is strongly recommended to use all other rendering optimization flags as well (see more details on these optimizations).
2. Go to the <UnigineSDK>/data/ folder.
3. Copy the following into the root of SD card:
   • core data (core directory)
   • your project folder
   • modified source/app/Android/unigine.cfg
   Unigine engine will use these resources as if it were stored in data folder.
   Shell commands

   adb -d push core /sdcard/
   adb -d push ../source/app/Android/unigine.cfg /sdcard/
   adb -d push my_project /sdcard/data/
   

   Notice

   Before copying, you can pack resources into core.ung and my_project.ung. For that purpose, use Archiver tool or see details on assets.sh script.
   For example, type the following to pack your project data and exclude version control system directories, if any:

   Shell commands

   ung -d my_project -x .svn
   

4. And that is it. Choose the installed Main-debug.apk on the device and run it.

You can also check scripts described below (assets.sh, build.sh) if you want to speed up some steps.

Building the release version of Android application package takes some additional steps. You can use sample applications (found in ~/<UnigineSDK>/builds/ folder) as a template to create the final build of your project.

1. Build the release version of Unigine engine libraries with SCons (see above):
   Shell commands

   username@pc-name$ cd ~/UnigineSDK/source/app/Android/jni/
   username@pc-name$ scons platform=android debug=0
   

2. Copy a sample application (for example, <UnigineSDK>/builds/Android_Crypt) with scripts and folders inside. To create your own Android application, you need to modify this template.
   For a start, rename the copied folder, for example, to <UnigineSDK>/builds/MyApp.
3. Take a look at a sample Java launcher UnigineCrypt.java stored <UnigineSDK>/builds/builds/MyApp/src/com/unigine/. For release build, the engine does not need look up data directory on SD card (which it does by default). You need to specify any arbitrary nonexistent data folder in order for the engine to search for all resources in MyApp/assets folder in .apk file.
   Source code

   final String[] argv = new String[] {
   	"-data_path", "nonexistent_data_folder",
   	...
   };
   

4. Further customize the Java launcher UnigineMain.java to change the start-up interface or modify Activity implementation in any other way.
5. Update the project to create a proper Android project file structure under this directory. For that, run android update in the console. Make sure that you reference Unigine engine libraries; otherwise, the project will not be built (see more details).
   Shell commands

   username@pc-name$ cd ~/UnigineSDK/builds/MyApp
   username@pc-name$ android update project --name MyApp --target 3 --path ./ --library ../../source/app/Android
   

6. If necessary, replace application icon stored in <UnigineSDK>/builds/MyApp/res/drawable/ folder.
7. Update AndroidManifest.xml (see more details):
   Source code (XML)

   <!--A full Java-language-style package name for the application
   with Internet domain ownership (in reverse)-->
   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
   	package="com.my_company.my_app">
   	...
   	<!--A human-readable name for the application.-->
   	<application android:label="MyApp"
   					<!---An application icon.-->
   					android:icon="@drawable/my_app"
   					android:debuggable="true">
   		<!--The name of the class that implements the activity.-->
   		<activity android:name="UnigineMain"
   					<!--A user-readable label for the activity..-->
   					 android:label="Main" ...>
   		...
   	</application>
   	...	
   </manifest>
   

8. Customize assets.sh script: modify the path (relative to the script directory) to the project resources (see item 2.2). Other paths can be left unchanged.
   Shell commands

   #!/bin/sh
   
   # Step 1. Pack Unigine core data (shaders, default textures, etc.) into core.ung archive:
   # 1.1. Path to core_adb.sh script that will be executed
   # 1.2. Path to the Unigine core data
   # 1.3. Target folder inside your project directory to store packed core resources
   ../core_adb.sh ../../data/core assets/data
   
   # Step 2. Compress and pack your project data into assets/data folder (this step will be
   # skipped if -c flag is specified as an argument):
   # 2.1. Path to data_adb.sh script that will be executed
   # 2.2. Path to the project resources
   # 2.3. Target folder inside your project directory to store packed project resources
   if [ "$1" != "-c" ]; then
   ../data_adb.sh ../../data/my_project assets/data
   fi
   

9. Run assets.sh script:
   Shell commands

   username@pc-name$ cd ~/UnigineSDK/builds/MyApp/
   username@pc-name$ assets.sh
   

   This script performs the following:
   1. Copies Unigine core data (only such data which is necessary for mobile version) into the specified folder and packs it into core.ung archive.
   2. Copies and compresses all project resources:
      • Compresses XML files (world file, as well as materials, properties, nodes and UI files) into binary format that is more compact and is parsed faster.
      • Images stored in uncompressed folder are compressed and normal maps (with _n postfix) are downsized.
      • Stores all resources into MyApp/assets/data folder where they can be accessed when application is run on the Android device.
   If any, svn directories (used by the version control system) are automatically excluded by this script.
10. Customize build.sh. Use ant debug to create unsigned .apk file that it can be later signed with your key to be distributed.
    Shell commands

    #!/bin/sh
    
    ant release
    
    if [ "$1" = "-i" ]; then
    	adb -d install -r ./bin/MyApp-unsigned.apk
    fi
    

11. Connect the Android device to your development machine.
12. Create application package file and install it to the device by running build.sh with the -i flag:
    Shell commands

    username@pc-name$ build.sh -i
    

The release version of your Android project is ready. It is also copied to the target device where you can immediately launch it.