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:
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.
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.
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:
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:
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:
On Linux or OS X, you won’t need a device driver. If you can’t access your device, you may need to read:
However, modern versions of Linux and OS X should just work.
Itself. The latest version of PGS4A can be downloaded from:
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.
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.
The next step is to set up the Android SDK and the rest of your development environment. This step will:
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.
To continue, we’ll need a game to package. The section on Writing a Game explains how a simple game works. For now, you can make a game by:
Creating the mygame directory underneath the PGS4A directory.
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.
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.
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
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.