Plasmacore:Android Projects

From Plasmaworks

Jump to: navigation, search

Contents

Android-Specific Framework

General

  • The value ANDROID will be defined when you're compiling code for Android ("if (defined(ANDROID))" etc.).
  • System.os will return the string "android" when you're running on an Android.

android.slag

[include "android.slag"] to access the following methods:

  • Android.is_tablet().Logical
Returns "true" if code is running on a tablet-sized device.
  • Android.memory_class().Int32
Returns the number of megabytes that the OS allows per program. This will be "16" for first generation devices, "24" many second-gen devices, and "32" or higher for most modern devices.


Poor Drawing Performance on First Generation Models

Texture Bit Depth

Early Android devices have poor drawing performance. This can be improved to playable levels through using 16 instead of 32-bit textures. One way to decide at runtime is to check Android.memory_class() (see above) and use 16-bit textures if the result is "16". Write the following command before you start loading images: 

 Texture.default_pixel_format = PixelFormat.rgb16

Another strategy is to set any orthogonal, opaque background images to "tile mode" ("img.render_flags |= Render.tile_mode"). These will draw much faster on Android. Note: as of 3.5.0, these only draw correctly when the image Handle is at the default top-left. This will be fixed in the next release.

SDK Setup

Download the latest Plasmacore Framework and set it up for your Windows or Mac machine as normal. Then:

Windows

  • In your Plasmacore project folder type "gogo install android" to install the Android module.
  • Download the latest SDK and NDK from http://developer.android.com. Unzip them to your user folder (/Users/yourlogin) to avoid issues with write permissions. Add the "android-sdk-windows" directory to your system path (e.g. "c:\Users\yourlogin\android-sdk-windows\tools").
  • Download and install the Java JDK (for Standard Edition, "Java SE") from http://java.sun.com. Add the JDK's "bin" directory to your system path (e.g. "c:\Program Files (x86)\java\jdk1.6.0_20\bin"). This is necessary to run ANT.
  • Download and install the ANT build system from http://ant.apache.org. Place the uncompressed ANT directory (e.g. "apache-ant-1.8.0") in your "\Users\yourlogin" directory and add its "bin" directory to your system path (e.g. "\Users\yourlogin\apache-ant-1.8.0\bin").
  • Install Cygwin from http://cygwin.com. Use standard and recommended settings. On the "Select Packages" step, click the "View" button on the right side to switch to "Full" view and choose "make" and "ant" to install (click on the word "Skip" to toggle to install).
  • cd to "/cygdrive/c/yourlogin/android-sdk-windows" and type "./SDK\ Setup.exe &" to start the Android GUI manager with component installer. Install extra SDK components and set up and Android virtual machine with SD Card support.
  • Open the local.properties file within your project folder. Add a line containing: "ANDROID_NDK: path/to/NDK" (e.g. "ANDROID_NDK: C:\Users\yourlogin\android-ndk").
  • cd to "/cygdrive/c/yourlogin/android-ndk-r5b" and type "build/host-setup.sh" to configure the NDK.

Caveats

  • Placing android-ndk, your project directory, or any of the other build tools in a path that contains spaces will cause problems when working with cygwin.

The following error was generated during "gogo android-vm" (Compiling and Running). It was fixed by moving the project source out of 'Documents and Settings'. 

 Android NDK: There is no Android.mk under /cygdrive/C/Documents and Settings/For
 rest/Documents/SRC/gamedev/plasmacore-3.0.10-beta/inchworm/platforms/android/jni
 
 Android NDK: If this is intentional  please define APP_BUILD_SCRIPT to point
 Android NDK: to a valid NDK build script.
 build/core/add-application.mk:100: *** Android NDK: Aborting...    .  Stop.
  • Installing apps to your Android device may only work when the cable is plugged into a particular USB port (possibly the first one ever used for that purpose).
  • You must install Android SDK 1.6 when installing SDK components (even if you intend to compile for later versions).

The following error was generated during "gogo android-vm" for Android version 2.0.1. It was fixed by installing version 1.6 from the Android GUI manager. 

 [exec] BUILD FAILED
 [exec] C:\devel\gamedev\plasmacore-3.0.10-beta\inchworm\platforms\android\build.xml:65: Unable 
 to resolve target 'android-4'

Mac

  • In your Plasmacore project folder type "./gogo install android" to install the Android module.
  • Create or modify "~/.profile" to include the following two lines: 
 export PATH="/Applications/android-sdk-mac_x86/tools:$PATH"
  • Open a Terminal prompt (Applications->Utilities->Terminal) and type "android &" to start the Android manager GUI. Install extra SDK components and set up an Android virtual machine with SD Card support.
  • cd to "/Applications/android-ndk-r3" (or more recent version) and type "build/host-setup.sh" to configure the NDK.

Compiling and Running

Go to Settings->Applications on your Android phone and ensure that "Unknown sources (Allow...)" is checked.

Windows

  • Open a Cygwin command prompt and cd to your Plasmacore project folder.
  • Type "gogo android-vm" to compile and install the virtual machine build on your active simulator or plugged-in phone. This is faster to compile than the cross-compiled build and will throw an exception on a null reference error instead of crashing.
  • Type "gogo android-xc" to cross-compile to Java/C++ and install on your active simulator or plugged-in phone. This runs faster than the VM build but will crash on a null reference error.

Mac

  • Open a Terminal prompt and cd to your Plasmacore project folder.
  • Type "./gogo android-vm" to compile and install the virtual machine build on your active simulator or plugged-in phone. This is faster to compile than the cross-compiled build and will throw an exception on a null reference error instead of crashing.
  • Type "./gogo android-xc" to cross-compile to Java/C++ and install on your active simulator or plugged-in phone. This runs faster than the VM build but will crash on a null reference error.


Debug Certificate

  • To have the Android build system generate a debug certificate (it'll gripe if it needs one), cd to "platforms/android" and type "ant debug".

Release (Distribution) Build

There is currently no helper functionality in Plasmacore for creating a signed release build. Perform a regular android-xcoor android-vm build to set everything up, cd into "platforms/android", and then follow the official Android developer instructions to prepare your release. For example, typing "ant install" at that location would compile and install a debug version.

Retrieved from "http://www.plasmaworks.com/wiki/index.php/Plasmacore:Android_Projects"