UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins
Content Creation
Materials
Unigine Material Library
Tutorials

Android Application Development

With Unigine you can create applications for a wide range of Android devices. Unigine allows to run projects on Android in the easy manner, without having to convert project codebase or needing to be concerned with underlying Java runtime.

Target Android versions are 2.2 and 2.3..

Notice
Android 2.2 cannot open resources stored in /assets folder within .apk if they are lager than 1Mb. As a workaround, SD card can be used to store resources.
Android version 2.3 does not have such limitations and can handle content of any size.

Step 1. Installation of SDK

1.1. Prepare Development Environment

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).

1.2. Install Unigine SDK

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.

Step 2. (Optional) Rebuilding Unigine Engine

Unigine Engine is written in C++ while Android has Java runtime environment. To bridge C++ and Java, the following files are used:

  • UnigineMain.java is an entry point for the application: it initializes UnigineActivity.java and creates basic interface necessary to launch the application (for example, buttons to choose screen resolution or quality of shaders). If you want to change the start-up interface, you will need to customize this file.
  • UnigineActivity.java allows to run C++ Unigine engine within a Java virtual machine in Android. It initializes the engine, sets the video mode together with the rendering API, updates the main loop and receives touch and key input events. It also initializes libUnigineActivity.so and libopenal.so (OpenAL library for sound support).
  • libUnigineActivity.so is a small wrapper for Unigine engine. Its source code is stored under source/app/Android/jni/ directory. This wrapper is necessary to launch libUnigine.so and when the engine is run for the second time, to properly initialize all objects and variables. libUnigineActivity.so forwards user input activity to libUnigine.so and allows it to request access to files from assets directory.
  • libUnigine.so is the library that contains the engine itself.

Build Unigine Engine and Default .apk

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
    

3.1. Building Your Application

Depending on compiled libraries, Android application can be of the following types:

  • Development (debug) version
  • Production (release) version

There are two things designed for fast and convenient development on Android device:

  • The Unigine-based application searches for resources in the root of SD card. Thus, test iterations are really fast as you only need to copy data there without rebuilding application package file.
  • Unigine uses Telnet protocol to connect to the device (available only for the development version of the Unigine application). The default TCP port is 8888. You can remotely control the application running on a target device by passing console commands, for example, via PuTTY or any other Telnet client. To close the session, use logout command.
    For example, you can use adb to set up port forwarding on a your local machine to the device port (see details) and then connect to the local host on specified port:
    Shell commands
    adb forward tcp:8888 tcp:8888
    telnet localhost 8888
    

To create your own project for Android you can use template applications provided in SDK. There you can find a number of scripts that after being customized will allow to build Android application in just several clicks.
See also guidelines how to set up and optimize your project for a mobile device. Create and set up your project for rendering on mobile devices on your development machine (see details):

3.1. Build App Development Version

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.

3.2. Build App Production Version

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.

Last update: 2017-07-03