Documentation – ShiVa Engine

Documentation


Publishing: Android

Standalone Engine for Android Mobiles (Phones, Tablets, Microconsoles)


Table of Contents

Engine Compatibility

This engine port runs on Android 2.3 and later devices. Version 4+ is recommended.

Limitations

Camera and Microphone support is patchy. Do not rely on it, or write your own plugin.

Many mobile phones are still locked to Android version 2.3, you might want to compile against that API for maximum compatibility. If you are developing for modern tablets or consoles like the nVidia Android TV, try to compile against the Android version that is running on the device itself.

Hardware Requirements

In this section, you will learn what hardware you will need to build and test your game.

Building

Any computer capable of running ShiVa. Make sure you run your game before exporting it in order to let ShiVa generate all required shaders.

Testing

You can create both x86 and ARM builds of your Android games. That means testing on your ShiVa x86 machine is possible, but pointless if you are targeting the mobile market, since the overwhelming majority of tablets and phones is running on an ARM processor. You should definitely test your APK on a real Android device like a phone or tablet, not a simulator, and not as an x86 build.

To test your game on a device, you need to have it usb-connected to your development PC in development mode, accepting packages from unknown sources:

Android usb debugging

Android unknown sources

To transfer your game to your device, either check the box "install on connected device" when exporting, or run the adb install command. adb is an application that ships as part of the Android SDK. Note: Some devices (especially Samsung) require a special USB driver to be recognized properly. These drivers are usually available on the manufacturer website, on an installer CD that came with the tablet/phone, or are selectable in the Android SDK package installation (see below).

/path/to/adb install /path/to/your/package-debug.apk

Software Requirements

In this section, you will learn which tools and programs are needed besides ShiVa in order to port your game to the desired platform.

Legacy and Modern toolchain

Starting with ShiVa 2.0 beta 4, we are adopting the Google recommendation of abandoning ADT/Eclipse in favour of Android Studio (AS). That means the manual SDK/NDK/ANT and optional ADT/Eclipse toolchain is no longer required to build packages - in most cases. AS is available for Windows, Mac and Linux.

Using AS means you will use ShiVa's AS Project Exporter and do all your building and testing from AS. In other words, you will lose the ability to build APKs from within ShiVa. This might not be a bad thing for you, especially if you are an experienced Android developer and have need of special settings only AS can give you. If you are a newcomer to the platform however, learning AS in addition to ShiVa might be a major obstacle.

We offer both ways to create Android packages: "legacy" with SDK/NDK/ANT(/JAVA/CYGWIN) and "modern" with AS 2.2 and up. Since google is ramping down Eclipse support and raw SDK/NDK downloads, we recommend the AS workflow for all new ShiVa-Android projects.

If you wish to adopt AS as your main build platform, please read the AS workflow guide at the end of this doc page.

Windows - Legacy

Windows is the hardest platform to build Android packages on with the Legacy toolchain. If at all possible, try to build on Mac or Linux instead if you must use the old toolchain.

Cygwin

The major hurdle of building Android on Windows is that Android comes from the same Unix family tree as Linux and OS X, which means many essential tools and concepts are not available on Windows by default. To develop on Windows, you need to bring a minimalistic Unix environment to your Windows machine, which is Cygwin. Get the latest version from cygwin.com. Run the installer. When you are asked to select your packages, expand the Devel category and select the binary make package - or better yet, select the whole Devel category:

cygwin devel

Do not forget to add the Cygwin path to ShiVa in Settings -> Paths after you are done.

Java

Java lets you develop and deploy Java applications for Java-centric platforms like Android. Get the latest JDK (version 7+) from oracle.com/technetwork/java/javase/downloads. After you have installed it, you need to configure the JAVA_HOME environment variable to the Java jdk path:

java devel

Android SDK and NDK

Both these packages can now be installed through Android Studio, see below. It is important that you tell ShiVa the location of these folders after the installation. Open the ShiVa menu and go to Settings -> Paths:

Android paths shiva

Ant

The legacy toolchain uses ANT instead of Gradle for its build system. ANT can be downloaded for free from ant.apache.org. It is important that you tell ShiVa the location of the ANT folder after unpacking the archive in Settings -> Paths.

macOS - Legacy

Android SDK, NDK

Both these packages can now be installed through Android Studio, see below. It is important that you tell ShiVa the location of these folders after the installation. Open the ShiVa menu and go to Settings -> Paths.

Java

Your OS X probably already comes with a version of Java. The Android Studio installer will look it up and request the installation of a newer version if required.

Ant

The legacy toolchain uses ANT instead of Gradle for its build system. Oldr versions (pre 10.9) had ANT preinstalled, newer versions do not. ANT can be downloaded for free from ant.apache.org, or as retrofit package from our own shiva3dstore.com. It is important that you tell ShiVa the location of the ANT folder after unpacking the archive in Settings -> Paths.

Linux - Legacy

Android SDK, NDK

Both these packages can now be installed through Android Studio, see below. It is important that you tell ShiVa the location of these folders after the installation. Open the ShiVa menu and go to Settings -> Paths.

Java

Android Studio 2.x comes with its own JRE folder, which makes any additional java installation unnecessary.

Ant

The legacy toolchain uses ANT instead of Gradle for its build system. ANT can be installed from your distribution's packet manager. It is important that you tell ShiVa the location of the ANT folder after the installation in Settings -> Paths.

Make sure you pick the correct folder. This command will tell you the location of the shortcut:

# which ant
A path will be returned to you, e.g. /usr/bin/ant. Resolve the path to get its true location:

# ls -l /usr/bin/ant
The resolved path is the true install location, e.g. /usr/share/ant

Licensing Requirements

In this section, you will learn which developer programs and services you must join in order to being able to publish games on the platform.

Standalone Self-Publishing

This publishing method is an option on this platform, though not one you want to opt for. While it is possible to distribute your APKs over e.g. you own website, it will require your customers to know how to transfer and install AKPKs on their tablet/phones after having disabled the "trusted sources" security filter. Publish your applications through the official platform store(s) instead.

Official Store

There are many stores for Android games, from big ones like Google Play and Amazon to highly specialized stores like the OUYA. All these stores come with their own set of rules, license fees and restrictions, so we cannot provide you with a general rulebook on how to get your games onto these platforms.

Export Settings

In this section, you will learn about the different options ShiVa presents you with while exporting.

Note: All file names in the following settings must contain only alphanumeric characters. Dot, colon, dash, whitespace, umlaut, etc. are not allowed.

Input

Target Profile: Platform-dependent settings for texture compression, audio and video formats.
Game File: Your main .gam from the current project.
Generate C++: Convert Lua to C++ if you intend on doing a Project build.
ShiVa resources: Instead of generating game packs, you can also generate gameless resource files using this checkbox.
Pack File: Instead of using a .gam, you can use a prebuilt STK too.
C++ Files: Optional path to additional C++ files for your Pack File STK.

Output

Type: Application (.apk), Project (Eclipse legacy), Project (Android Studio), STK archive
Folder: Where your exported files will be stored.
Open Folder: Show exported files after export.
Install on Device: If you have an Android device connected to your PC via USB that can be reached through adb, ShiVa can install it for you automatically.
Launch on Device: Launch game on device after successful installation.

Additional Files

Add (+), Remove (-) or Clear (X) files referenced in your game though playAdditional, playExternal, getPackDirectory() and similar functions. Commonly XML, video or STK files.

Icons, Splash Images

Load all required images for your application. Sizes and formats are given through the placeholders and tooltips.

Bundle Information

Title: The name of your game.
Description: A short description of your game.
Signing Identity: Auto-filled values pulled from your Provisioning Profile.
Bundle Identifier: Usually a reverse domain name, like com.yourcompanyname.yourgamename
Bundle Version: Release number, visible to customers. Usually in the form of Version.Release.Bugfix
Bundle Code: Internal version number, not visible to customers. Higher integers indicate more recent versions.

Build Options

Build Type: Debug (with logging, cannot be sold on the Play Store) or Release.
Architecture: v5 (legacy devices), v7 (ARM Cortex +, standard) or x86 (simulator only).
System API: Minimum iOS version you want to support. Minimum is 2.3, we recommend 4+. Available options depend on the platforms installed through the Andoid SDK tool.
Graphics API: OpenGL ES 2.0 (all effects, for modern devices) or OpenGL ES 1.1 (compatibility mode with very few graphical effects for old devices).
Color Buffer: 16bit (performance) or 32bit (enables transparency-based post processing effects like motion blur).
Depth Buffer: 24bit lead to more accurate depth rendering (less flickering) over 16bit at the cost of performance.
Orientation: Portrait or Landscape, determines which way your apps start.
STL: Option for C++ builds. By default, the headers and libraries for the minimal C++ runtime system library (/system/lib/libstdc++.so) are used. Other options are STLPort static/shared or GNU static/shared.
Launch Mode: Single Task, Top, or Instance. Leave at SingleTask if you are unsure. Please consult the Android documentation for more details.

Permissions

Select which functionality your app requires. Be careful about what you choose, do not simply select everything: Being inaccurate here may result in app rejection.

Android Studio

Android Studio can be used to modify Android Projects that come out of ShiVa. Version 1.5 or higher is required, version 2.2 and up is recommended.

System Requirements

- 2 GB RAM minimum, 4 GB RAM recommended
- 800 MB hard disk space for the editor...
- and at least 4 GB for Android SDK/NDK, emulator system images, and caches

Installing Android Studio

The latest version of Android Studio can be downloaded for free from developer.android.com/sdk. Choose the right version for your operating system.

Inside the AS Installer are a number of components, like the Gradle build system, a complete release of the JRE (so no additional Java installation is needed), and various other Android- and Java-related tools. In general, AS comes with everything you need, which gets rid of separate ANT, CYGWIN etc. installations.

During the installation, you will be asked to choose which components you would like to install. In general, we do not recommend testing in the Emulator/Virtual Machine, so you can safely skip it. Skipping the SDK installation at this point is also possible, since you will be modifying your SDK list later anyway.

Installing the SDK

The SDKs provide access to different versions of Android. By default, the latest version of the SDK is installed when you install Android Studio. Since you want to remain backwards compatible and target older devices as well, we highly recommend installing older SDKs like the ones for Android 2.3 and 4.x too.

AS sdk other

Installing the NDK

The NDK is also required for ShiVa. It allows C++ applications to run natively on Android. Since ShiVa is a C++ engine at heart, this ensures the best possible performance. You can install the NDK from the Preferences dialogue, SDK Tools:

AS ndk

ShiVa Projects in AS

After you have installed AS, the NDK and the SDKs you want to support, you need to add the xDK locations to ShiVa. Open the ShiVa menu and go to Settings -> Paths. Note that the NDK folder is located inside the SDK folder:

S:\androidSDK
S:\androidSDK\ndk-bundle
Now you can export your game as AS project. You will have to do all your builds and testing in AS. You will not be able to build an APK directly within ShiVa with just an AS installation.

In order to build an APK from within ShiVa, you will have to follow the Legacy toolchain and install ANT, Java, Cygwin etc. manually, depending on your platform.

JDK and openJDK

Android is a Java platform at heart. Running some form of Java Development Environment, or Java Development Kit (JDK) on top of the Java Runtime (JRE) is necessary for successful ShiVa to Android game exports. You can download the latest JDK from the Oracle website.

Starting with version 2.x, Android Studio has begun shipping with its own distribution of JDK. Some users have reported that they needed to install the Oracle JDK nevertheless, yet others have reported successful exports with just the built-in JDK. To be on the safe side, we do recommend installing the Oracle JDK on every machine you wish to export ShiVa Android games from.

On Linux, you have a choice between installing Oracle Java, or pulling the latest openJDK from your distro repository. While openJDK may be the preferred choice for open-source lovers, our users have reported mixed results in terms of compatibility as well as performance. Android Studio itself will give a warning when it detects openJDK. We only develop our build pipeline for Oracle Java. Use openJDK at your own discretion.