This page documents how 0 A.D. might be ported to the ​Android platform.

Plan

1. Set up a generic Android NDK build environment.
2. Find and adapt replacement libraries for every dependency in the PC edition.
3. Port graphics and sound to OpenGL ES and OpenSL ES, respectively.
4. Come up with a suitable UI for mobile devices.
5. Implement the new UI on Android.
6. Build the package with Android NDK and SDK.
7. Publish the package on Android Market.
8. Rock.

Target devices

Samsung Galaxy Nexus

• 720×1280 px at 316 ppi
• !16:9 aspect-ratio
• 16M colors
• Multi-touch, capacitive touchscreen

Design

User Interface

Due to the vastly different controls and form factor, the whole user interface of the game needs to be rethought.

In the following, each control primitive is summarized as a bullet point.

We will use the following terminology for basic gestures:

A swipe is a single-point touch motion.

A pinch is a two-point touch motion.

Camera

Camera panning is performed by applying inverse swipe gestures on the screen:

• Swipe down - pan camera up.
• Swipe up - pan camera down.
• Swipe left - pan camera right.
• Swipe right - pan camera left.

The further from the center of the screen the swiping motion begins, the faster the panning will be.

Camera rotation is performed by applying a circular pinch gesture on the screen:

• Pinch clockwise - rotate camera counter-clockwise.
• Pinch counter-clockwise - rotate camera clockwise.

The closer to the center of the screen the pinching motion begins, the faster the rotation will be, such that when the circular gesture is complete, the camera has completed a full rotation.

Camera zoom is performed by applying a pinching gesture on the screen:

• Pinch in - zoom out.
• Pinch out - zoom in.

The camera may also be panned by touching near the edge of the screen:

• Touch near edge of screen - pan camera in the direction of the given edge.

The camera may also be panned by touching a position on the minimap:

• Touch position on minimap - pan camera to the corresponding position on the map.

Entity selection

If an entity is tapped once, the entity is immediately selected.

• Single-tap entity - immediately select entity.

If touch is applied to the game world for more than ~0,25s, a brief tactile feedback vibration is played, and the interface enters 'selective mode.'

• Touch game world for more than ~0,25s - enter 'selective mode' and play brief tactile feedback vibration.

While in selective mode, a bounding box is drawn with one corner where the touch point was when the mode began ('start position') and the opposite corner where the touch point currently is ('end position'').

While in selective mode, the camera pans slowly in the direction from the start position to the end position. The further the end position is from the start position, the faster the camera pans.

When touch is released in selective mode, all units within the drawn bounding box are selected.

Unit orders

If a position in the game world is double tapped, the selected unit is ordered to apply its context-dependent primary action to the position.

• Double-tap position in game world - apply selected unit's primary action to the position.

Libraries

Android-compatible replacements must be found for all ​the dependencies of the PC edition. This is what we have so far:

• GCC - The Android NDK provides its own ndk-build tool for compiling.
• Subversion - Assuming this is just for obtaining the source, this can be done on a PC workstation.
• SDL - Is already ​ported to Android.
• Boost - There is ​an unofficial port.
• zlib - libz is part of the native NDK.
• libpng - There's unofficial ports like ​this one.
• libxml2 - Google publishes ​a tree that is tuned to compile on Android.
• OpenGL - This must be ported to OpenGL ES.
• OpenAL - This should be ported to OpenSL ES.
• zip - Not sure which exact library this refers to?
• libogg - May be covered by Tremor (below).
• libvorbis - This can be ​done with Tremor.
• libcurl - May be ported ​like this.
• Gamin - Don't know about this one. It's used for monitoring file hotloading which doesn't seem as useful on an Android device.
• CMake - All build tools are provided by the NDK.

In addition to the external dependencies above, the following are bundled with the game:

• ​NVTT - We don't need any of its fancy features like CUDA support or image-loading tools, just the basic CPU-only compression library, so it should be buildable with no significant external dependencies (though its build system might need fixing).
• Spidermonkey - Presumably, Spidermonkey has been ported as part of ​Fennec. We can't use Android's native V8 engine since we rely on some complex API features, so porting would be a huge amount of work. SpiderMonkey isn't API-compatible or behaviour-compatible across versions, so it'd be best to use the same ​1.8.5 release as we use on PCs if possible; I think the standard releases are meant to work on ARM, so that should be okay.
• Enet - From a quick check, I see no dependencies outside of libc, so this should compile natively.
• FCollada - We use a customised/bugfixed version of FCollada, so a port of the standard version of FCollada probably wouldn't work. Our own version has no significant dependencies other than libxml2.

Implementation

The ​Android VM allows applications to call methods implemented in native code through ​JNI. This means we have to produce a native shared library which implements the core game functions as a set of methods that can be called from a ​shim running in the standard Android VM. The native library and the shim can then be packaged and distributed together.

Setting up your workstation

For everything short of actually running the application, we will use a PC workstation. This section will assume your workstation runs Ubuntu Linux, but the steps should be relatively easy to adapt to other platforms. Begin by setting up a working directory for the project:

$ mkdir ~/android

Next, ​install the Android SDK. Download the SDK package from ​this page to the working directory and then unpack it there, e.g.:

$ cd ~/android
$ tar -xvf android-sdk_r16-linux.tgz

Now complete the installation by running the android tool:

$ ~/android/android-sdk-linux/android

A window with installable packages should open. In addition to any packages checked by default, make sure 'Android SDK Platform-tools' is checked and click 'Install packages'.

You also need to install the Android NDK (r4 or later). Download the NDK package from ​this page to the working directory and then unpack there, e.g.:

$ cd ~/android
$ tar -xvf android-ndk-r7-linux-x86.tar.bz2

You also must install a Java Development Kit (JDK) if you haven't already, e.g. ​the standard JDK from Ubuntu Software Center:

$ sudo apt-get install default-jdk

Finally, make sure ​Ant and ​Subversion is installed:

$ sudo apt-get install ant subversion

Setting up an Android project

All data that is to be compiled and packaged into the Android application must be assembled in an Android project.

We'll use the template provided by SDL. Download the development snapshot for SDL 1.3 from ​this page to the working directory and then unpack it there, e.g.:

$ cd ~/android
$ tar -xvf SDL-1.3.tar.gz

Then move the project template to a fitting name under the working directory, e.g.:

$ mv SDL-1.3.0-6172/android-project/ ~/android/0ad

This is your project directory. Now move the SDL directory itself into the jni directory under the project directory, e.g.:

$ mv SDL-1.3.0-6172/ ~/android/0ad/jni/SDL

Then download the game source code into the jni/src directory under the project directory, e.g.:

$ svn co http://svn.wildfiregames.com/public/ps/trunk/ ~/android/0ad/jni/src

Open the file Android.mk in the jni/src directory under the project directory in a text editor, e.g.:

$ nano -w ~/android/0ad/jni/src/Android.mk

Add the full path of the jni/src/source directory to the LOCAL_C_INCLUDES declaration, e.g.:

LOCAL_C_INCLUDES := $(LOCAL_PATH)/$(SDL_PATH)/include \
        /home/youruser/android/0ad/jni/src/source

Add the source/main.cpp file to the LOCAL_SRC_FILES declaration:

# Add your application source files here...
LOCAL_SRC_FILES := $(SDL_PATH)/src/main/android/SDL_android_main.cpp \
        source/main.cpp

Then save the file and exit the text editor.

Installing replacement libraries

Building the application

The native library (i.e. the actual game) is built by running the ndk-build command in the project directory, e.g.:

$ cd ~/android/0ad/
$ ~/android/android-ndk-r7/ndk-build