If you have worked through Compiling orx and the Android demo and all compiled and deployed fine, then you are right to continue with this tutorial.

That means your own application should be able to work. There are pitfalls along the way and I'll do my best to guide you through.

Depending how you structure your own project, (especially if you use the init script to create your projects) it is likely that you have a folder layout something like this:

  bin
  build
      windows
          codelite
      mac
          xcode
  data
  include
  lib
  src

Perhaps you are targeting more than one operating system and IDE. You'll want to add the Android demo project to the build folder where it can be customised to work with your project. So copy the whole orx/code/demo/android folder to your build folder so it becomes:

  bin
  build
      android <------- here
          app/
          gradle/
          build.gradle
          gradlew
          settings.gradle
          etc...
      windows
      mac
  data
  include
  lib
  src

The Application ID notation is used to make Android applications (and their ownership) unique from all other applications that are available.

This notation is peppered through many files in the demo project and we'll need to change all of them to make the project your own. The notation used in the demo is:

 org.orxproject.orxtest.OrxDemo

• The org.orxproject.orxtest portion is called the Package Name and also the Application ID.
• The OrxDemo portion is the Class Name.
• The entire sequence which is org.orxproject.orxtest.OrxDemo is the Activity.

To make this demo easier to follow, let's come up with a fantasy application name and company.

Imagine you owned the domain name: rabbitgames.net And your game was Rocket Boy. Then a good identifier might be:

 net.rabbitgames.rocketboy.RocketBoyGame

So therefore:

• net.rabbitgames.rocketboy would be your Package Name and Application ID.
• RocketBoyGame would be the Class Name.
• net.rabbitgames.rocketboy.RocketBoyGame would be the Activity.

These names do not represent anything visual in your game itself, title, or icon, etc. Those are defined elsewhere.

We will apply this notation though a few files coming up.

Read more about this at: https://developer.android.com/studio/build/application-id

The string you choose will become the name of the APK, for example: app-debug.apk and app-debug-unaligned.apk

Similar to the naming we discussed earlier, let's call the app: rocket-boy.

Edit the build/android/settings.gradle file and change from:

 include ':app', ':orx-lib'

to:

 include ':rocket-boy', ':orx-lib'

Now you need to rename the folder build/android/app folder to match so it becomes: build/android/rocket-boy.

When it comes time to import the project later into Android Studio, this will be the project name.

The Activity is currently called OrxDemo. You can see it stored under the folder structure:

 build/android/rocket-boy/src/main/java/org/orxproject/orxtest/OrxDemo.java

Change these folder names to:

 build/android/rocket-boy/src/main/java/net/rabbitgames/rocketboy/RocketBoyGame.java

Edit the RocketBoyGame.java file and change the class name to match:

 public class RocketBoyGame extends OrxActivity {
      

Also while in this file, change the first line to match the path:

 package net.rabbitgames.rocketboy;

Edit build/android/src/main/AndroidManifest.xml file:

 <activity android:name="net.rabbitgames.rocketboy.RocketBoyGame"

Also in this file is the Package Name to change:

For example, the first line in the AndroidManifest.xml file you'll find:

 package="org.orxproject.orxtest"

Change this to:

 package="net.rabbitgames.rocketboy"

This file is located at build/android/rocket-boy/build.gradle.

  applicationId "org.orxproject.orxtest"
  

Change to:

 applicationId "net.rabbitgames.rocketboy"

To read more about the importance of your application id: https://developer.android.com/studio/build/application-id and http://developer.android.com/guide/topics/manifest/manifest-element.html#package

This is how to set the title text for your application icon when loaded on your device.

The App name is located at: build/android/rocket-boy/src/main/res/values/strings.xml

  <string name="app_name">OrxDemo</string>

Change to:

  <string name="app_name">Rocket Boy</string>

Your application must also be given a module name. You set this name in three places, the module name must match:

build/android/rocket-boy/src/main/jni/Android.mk

  LOCAL_MODULE    := rocketBoyModule

build/android/rocket-boy/src/main/jni/Application.mk

  APP_MODULES = rocketBoyModule
  

build/android/rocket-boy/src/main/java/net/rabbitgames/rocketboy/RocketBoyGame.java

  System.loadLibrary("rocketBoyModule");

Orx will load its startup ini file from the build/android/rocket-boy/src/main/assets folder.

Currently, Orx will load orxd.ini when in debug mode, or orx.ini for release mode. (Debug or release APKs are covered later).

Not sure which mode you are compiling for? Have a look in the build/android/rocket-boy/src/main/jni/Android.mk file. The “LOCAL_STATIC_LIBRARIES := orxd” line tells it is orxd (debug). In this case, load orxd.ini.

It is possible to bootstrap a different ini file, for example: rocket-boy.ini. However this has not been tested as part of this guide. Read about changing the default ini file here.

To be explained. Sorry, I don't have the expertise to advise on this as yet.

All your source files, *.cpp and *.h should be copied into the build/android/rocket-boy/src/main/jni folder.

Then to ensure the NDK can compile your source into a library, each source file (but not header files) will need to be listed in the build/android/rocket-boy/src/main/jni/Android.mk file:

 LOCAL_SRC_FILES := file01.cpp file02.cpp file03.cpp file04.cpp file05.cpp

They need to be laid out on the same line due to CR/LF issues in the file, causing errors like

 "*** commands commence before first target. Stop.". 

See the following regarding the issue and tips on :

generally how to resolve.

However, listing on one line makes the problem go away.

All your PNGs and OGGs and whatever else need to be copied into the build/android/rocket-boy/src/main/assets folder.

Hidden.

 ndk-build

Load Android Studio.

Select the Open an existing Android Studio project option and choose your project's android folder, located at build\android.

Gradle will attempt to build immediately.

It might fail with an error:

 Android NDK: WARNING: Ignoring unknown import directory: /build/android/rocket-boy/src/main/jni/../../../../../../
 

In this case, go to edit \build\android\rocket-boy\src\main\jni\Android.mk or expand External Build Files in Android Studio and edit it from there. You need to work out the relative path from Android.mk to the orx project's lib/static folder. In my case it was:

 $(call import-add-path,$(LOCAL_PATH)/../../../../../../../../orx/code/)

But yours will vary.

Once changed, re-sync and build with: File > Sync Project with Gradle Files

After this, the wrapping code for your project is complete.

Select the Build > Build APK(s) menu.

Locate your apk file in: build\android\rocket-boy\build\outputs\apk\debug

You are done!

There are three ways to test your application:

1. Connecting a phone via USB in Developer Mode. Select Run > Run 'RocketBoyGame' to send to the phone. You can track application progress and logs via Android Studio's output pane.
2. Select Run > Run 'RocketBoyGame' to send to the Android Emulator.
3. Take the APK and manually copy it to your device.

You can switch between building a debug APK and a release one. Debug is set by default. In order to switch to the Release build type:

  1. Click View / Tool Windows / Build Variants
  2. You will see your module name.
  3. In the next column is the build variant. Click on "debug".
  4. A dropdown will appear where you can choose "release"

Then “Rebuild Project”.

Before you can generate a release APK, you will need to sign it. You don't need to do this for debug APKs. You can do this by:

  1. Right clicking on the "rocket-boy" project.
  2. Click "Open Module Settings"
  3. Click the "Signing" tab.
  4. Click the + sign.

Continue on, by visiting the following link: http://developer.android.com/tools/publishing/app-signing.html and scroll down to the section titled “Signing Your App in Android Studio”.

• General compile issues or failing APK on a phone. First thing to track down is mismatches in the naming of the project folders, and application ids, classname, etc. Go back and check each one for typos or mismatches.
• APK too small? And the lib folder is missing in your project? Did you forget to ndk-build your project before going to Android Studio? To check, rename your rocket-boy.apk to rocket-boy.apk.zip. Open the zip and confirm you have a lib folder there.
• You need to ensure that paths are correct to your images and sounds, between android and other platforms. You can use the [Resource] config option to configure multiple paths. Tutorial coming soon on pathing.
• If you are sick of manually copying your image and sound assets, and concatenating ini files, some scripts will be published here soon that you can use in your own projects.