Building Android Applications
=============================

|PGS4A| contains tools that help you take a packaging-centric approach
to Android game development. In this approach, you will use a PC to
build an Android package and upload it to your device. You can then
run the game like any Android application. When it works correctly,
you can upload the package you make to the Android Market or other app
stores.

Building your first package takes four steps:

1. Download and install |PGS4A|, Python 2.7, the Java Development Kit,
   and Android USB Drivers.

2. Use the ``android.py installsdk`` command to install the Android SDK and
   set up your development environment.

3. Use the ``android.py configure`` command to configure
   Android-specific settings in your game.

4. Use the ``android.py build`` command to build a package, and to
   install the package on your device.

Once you've finished these four steps, you'll have a runnable Android
package. You'll then repeat steps 3 (rarely) and 4 (often) until you
your game works.


Host Platform Support
---------------------

We've tested |PGS4A| on Linux and Windows computers. While it should
work on Mac OS X, we haven't tested it there, so there may be problems
encountered. The examples we give will be for Linux and Windows.

The |PGS4A| tools are command-line based. This documentation assumes
that you are proficient with the basics of command-line operation.


Step 1: Installing |PGS4A| and its Dependencies
-----------------------------------------------

There are four things you may need to manually download and install
before you can run |PGS4A|:


**Java Development Kit.**
The Java Development Kit (JDK) contains several tools that are used by
|PGS4A|, including the tools used to generate keys and sign
packages. It can be downloaded from:

    http://www.oracle.com/technetwork/java/javase/downloads/index.html

Please note that the developer-focused JDK is different from the
user-focused JRE, and you'll need the JDK to create Android packages.


**Python 2.7.**
Python 2.7 is required to run the android.py script that's
included with |PGS4A|. It can be downloaded from:

    http://python.org/download/releases/2.7.2/

|PGS4A| is not compatible with Python 3 at this time.


**Android Device Drivers.**
On Windows, you will likely need to install a device driver to access
your device. Links to android device drivers can be found at:

    http://developer.android.com/sdk/oem-usb.html

On Linux or OS X, you won't need a device driver. If you can't access
your device, you may need to read:

    http://developer.android.com/guide/developing/device.html#setting-up

However, modern versions of Linux and OS X should just work.


**Itself.**
The latest version of |PGS4A| can be downloaded from:

    |PGS4A_URL|

Once |PGS4A| has been downloaded, you should extract it using an
archive program. The directory contained in that archive is what we
will refer to as the |PGS4A| directory.


Aside: Running android.py
-------------------------

In this documentation, we'll ask you to run the ``android.py``
command. The technique we use to run this varies based on the system
you're on.

In all cases, you should run ``android.py`` from within the |PGS4A|
directory. (That is, the directory containing ``android.py`` itself.)

On Windows, if the .py extension is registered to Python 2.7, you can
just run::

    android.py test

Otherwise, you'll have to give the full path to Python 2.7::

    C:\python27\python.exe android.py test

On Linux, you may need to prefix the command with the current
directory::

   ./android.py test

For the rest of this documentation, we'll just use ``android.py``, and
leave it up to you to figure out how to convert that to the
appropriate command on your system.


Step 2: Set up the Android SDK and Development Environment
----------------------------------------------------------

The next step is to set up the Android SDK and the rest of your
development environment. This step will:

* Check that the JDK is installed properly.
* Install Apache Ant.
* Install the Android SDK.
* Use the Android SDK to install the appropriate development
  packages.
* Create a signing key that will be used to sign packages that are
  placed on the market.

This step requires Internet access.

To perform this step, run::

   android.py installsdk

|PGS4A| will report on what it's doing. It will also prompt you with
warnings about licenses, and ask if you want it to generate a key.

.. warning::

   The key generated by |PGS4A| is created with a standard
   passphrase. You should really use keytool to generate your own
   signing keys.

   At the very least, you should keep the android.keyring file in
   a safe place. You should also back it up, because without the
   key, you won't be able to upload the generated applications.


.. ifconfig:: not is_renpy

  Aside: A Simple Game
  --------------------

  To continue, we'll need a game to package. The section on
  :ref:`writing` explains how a simple game works. For now,
  you can make a game by:

  1. Creating the ``mygame`` directory underneath the |PGS4A|
     directory.

  2. In the ``mygame`` directory, create a file main.py. Place the
     following code into main.py::
  
      import pygame
  
      # Import the android module. If we can't import it, set it to None - this
      # lets us test it, and check to see if we want android-specific behavior.
      try:
          import android
      except ImportError:
          android = None
  
      # Event constant.
      TIMEREVENT = pygame.USEREVENT
  
      # The FPS the game runs at.
      FPS = 30
  
      # Color constants.
      RED = (255, 0, 0, 255)
      GREEN = (0, 255, 0, 255)
  
      def main():
          pygame.init()
  
          # Set the screen size.
          screen = pygame.display.set_mode((480, 800))
  
          # Map the back button to the escape key.
          if android:
              android.init()
              android.map_key(android.KEYCODE_BACK, pygame.K_ESCAPE)
  
          # Use a timer to control FPS.
          pygame.time.set_timer(TIMEREVENT, 1000 / FPS)
  
          # The color of the screen.
          color = RED
  
          while True:
  
              ev = pygame.event.wait()
  
              # Android-specific: 
              if android:
                  if android.check_pause():
                      android.wait_for_resume()
  
              # Draw the screen based on the timer.
              if ev.type == TIMEREVENT:
                  screen.fill(color)
                  pygame.display.flip()
  
              # When the touchscreen is pressed, change the color to green. 
              elif ev.type == pygame.MOUSEBUTTONDOWN:
                  color = GREEN
  
              # When it's released, change the color to RED.
              elif ev.type == pygame.MOUSEBUTTONUP:
                  color = RED
  
              # When the user hits back, ESCAPE is sent. Handle it and end
              # the game.
              elif ev.type == pygame.KEYDOWN and ev.key == pygame.K_ESCAPE:
                  break
  
      # This isn't run on Android.
      if __name__ == "__main__":
          main()
  
  In the examples below, ``mygame`` is short for the path to the game
  you're working on, relative to the current directory. When you make
  your own game, you should change ``mygame`` to something else.

Step 3: Configure Your Game
---------------------------

Before building a package, you must give |PGS4A| some information
about your game. You can do this with the following command::

    android.py configure mygame

This will ask you a series of questions about your game, and store
that information in a file in the game directory.

The only difficult question should be the one about layout. For your
first game, you want to put it on the internal storage.

If you need to change the information - for example, if you release a
new version of your game - you can re-run the configure command. Your
previous choices will be remembered.


Step 4: Build and Install the Package
-------------------------------------

Finally, you can build and install the package. This is done with a
command like::

    android.py build mygame release install

This command will build a releasable version of your game, and then
install it on the connected device. Please look at the output of this
command to make sure it succeeds.

Once the game successfully installs, you can touch its icon in your
device's launcher to start it running.

The build command passes the options after the game name to the ant
tool, which is responsible for creating the Android package. Other
commands are also possible - for a list, run::

    android.py build mygame help


Viewing Debug Output
--------------------

To view debug output from your application, run the logcat command::

    android.py logcat 

This command runs the ``adb logcat`` command in a mode that selects
only Python output.

