====== Using the Android Demo as a template for your own projects ======

If you have worked through [[en:tutorials:android:setup_android|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 under Android. There are pitfalls along the way and I'll do my best to guide you through. You don't have to know Java or Android to make use of this guide.


===== Copy demo as a template =====

Depending how you structure your own project, (especially if you use the [[en:tutorials:projects:creating_your_own_project|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.bat
            build.gradle
            build.sh
            gradle.properties
            gradlew
            gradlew.bat
            settings.gradle
        windows
        mac
    data
    include
    lib
    src


===== The Application ID =====

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 the files coming up.

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

===== Naming Folders and APK file =====

If you don't know what an APK is, it is like an installer package for Android, similar to a setup.exe for Windows.

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'

to:

   include ':rocket-boy'

This is also known as the project name.

Also:

  rootProject.name = "Orx Demo"

to:

  rootProject.name = "Rocket Boy"


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




===== Edit AndroidManifest.xml (the App Manifest) =====

Edit the meta data in the ''build/android/rocket-boy/src/main/AndroidManifest.xml'' file:

from:

  <meta-data android:name="android.app.lib_name" android:value="orxDemo" />

to:

 <meta-data android:name="android.app.lib_name" android:value="RocketBoyGame" />


<WRAP center round box 90%>
An activity is a screen, or drawable area. An Android application can have multiple activities, one stacked on another, and each removed using the back button on a device.

An activity can also show or hide a title, Android nav bar, or onscreen keyboard.

Read more about Activities and Manifests at: https://developer.android.com/reference/android/app/Activity and https://developer.android.com/guide/topics/manifest/manifest-intro
</WRAP>


===== Edit the build.gradle File =====

Edit the following at ''build/android/rocket-boy/build.gradle''.

  namespace 'org.orx.demo'

to:

  namespace 'net.rabbitgames.rocketboy'


And:

  applicationId "org.orx.demo"
    
to:

  applicationId "net.rabbitgames.rocketboy"

Change all manifestPlaceholders from:

  manifestPlaceholders = [ gameArguments: 'orxDemo' ]
  manifestPlaceholders = [ gameArguments: 'orxDemoDebug' ]
  manifestPlaceholders = [ gameArguments: 'orxDemoProfile' ]

to become:

  manifestPlaceholders = [ gameArguments: 'RocketBoyGame' ]
  manifestPlaceholders = [ gameArguments: 'RocketBoyGameDebug' ]
  manifestPlaceholders = [ gameArguments: 'RocketBoyGameProfile' ]


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



===== Resource Strings =====

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>



===== The Module Name =====

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    := RocketBoyGame

Next file to change is: ''build/android/rocket-boy/src/main/jni/Application.mk''

  APP_MODULES = RocketBoyGame


===== Your Source Files =====

All your source files, *.cpp and *.h can be copied into the ''build/android/rocket-boy/src/main/jni'' folder. However if your prefer, you can source them from your existing project with a relative path.

To ensure your C/C++ files are compiled, each source file (but not header files) will need to be listed in the ''build/android/rocket-boy/src/main/jni/Android.mk''. If you copied your source files to the ''assets'' folder, you can just specify the files like this:

   LOCAL_SRC_FILES := file01.cpp file02.cpp file03.cpp file04.cpp file05.cpp
   
Or to access them relatively:

  LOCAL_SRC_FILES := ../../../../../../src/file01.cpp ../../../../../../src/file02.cpp

Note that if you followed the same file structure in this tutorial, the six parent levels to get to your source files would be correct.

You can delete the unused ''orxDemo.cpp'' on disk.

The files 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.". 

Listing on one line makes the problem go away.


===== The initial .ini config file =====

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

Because of the ''manifestPlaceholders'' configured earlier, Orx will try to load ''RocketBoyGameDebug.ini'' when in debug mode, or ''RocketBoyGame.ini'' for release mode. (Debug or release APKs are covered later).

From these initial ini files, you can load your other project application files. But please note that your Android application will not be able reach back into a parent path for assets. These all need to live in your ''build/android/rocket-boy/src/main/assets'' folder. Therefore it will be useful for you to consider creating a publishing script to regularly copy all your Orx assets from the project into this ''assets'' folder.

?? 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''. ??

To learn more about bootstrapping different //ini// files at:  [[en:tutorials:console:changing_default_config_file|changing the default ini file here]].





===== Image and Sound files =====

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

Consider a publishing script to periodically copy them from your project ''data'' folder to Android ''assets'' folder.




===== Building the Debug, Profile and Release APKs =====

Open a terminal and go to: 

  build/android

And type:

  build.bat (for Windows or)
  build.sh (Linux / Mac)

Locate your APK files in: ''build\android\rocket-boy\build\outputs\apk\debug''

You are done!


===== Testing =====

There are three ways to test your application:

  - Using Android Studio 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.
  - Using the "Debug or Profile APK" in Android Studio, select ''Run > Run 'RocketBoyGame' '' to send to the Android Emulator. This also has good logging.
  - Take the APK and manually copy it to your device.


===== Release Builds =====

<WRAP center round box 90%>
Please note that this section is not complete or tested. New content will replace this very soon.
</WRAP>


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



===== Misc Troubleshooting Tips =====

  * 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.
  * You need to ensure that paths are correct to your images and sounds. Your config between Android and other platforms will be different. You can use the [Resource] config option to configure multiple paths to reach ini files and assets.
  * 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.