Android

Ren'Py support devices running the Android operating system, such as smartphones and tablets. While these devices do not support 100% of Ren'Py's functionality, with minimal modification code can be packaged and ported to these devices.

RAPT - the Ren'Py Android Packaging Tool - is a program, downloaded separately from Ren'Py, that creates an Android package for testing or release purposes.

User Instructions

When a Ren'Py game has been launched on Android, the following keybindings work:

Home
Returns to the Android home screen, suspending the Ren'Py game. As part of the suspend process, Ren'Py will automatically save the game. If necessary, the save will be automatically loaded when the user returns to the game.
Menu
Brings up the in-game menu, and returns to the game.
Back
Rolls back.
Volume Up, Volume Down
Controls Android's media volume.

Platform Differences

There are many important differences between the touch-based Android platform and the mouse-based platforms that Ren'Py supports. Changes due to the Android software and hardware are:

  • The touchscreen is treated as if it was a mouse. However, it will only produce mouse events when the user is actively touching the screen. When the user is not touching the screen, the virtual pointer will move to the upper-left corner of the screen.
  • ImageDissolve(), AlphaDissolve(), and AlphaBlend() are not supported.
  • Functions that render to a texture can only render an opaque texture. This means that the Dissolve() and Pixellate() transitions will only produce opaque output.
  • The focus_mask property is not supported. It will be treated as if all pixels in the mask are opaque.
  • Movie playback is not supported.
  • Launching the web browser is not supported.
  • Some python modules (including network communication) modules are not supported.
  • Ren'Py cannot change the device volume. However, the android volume buttons work normally.

In addition, there are a few changes that may be necessary due to human factors:

  • Since Android smartphones can be smaller than a computer monitor, it may be necessary to increase text size.
  • Since touch input is less accurate than mouse input, touch-based buttons need to be larger than mouse-based ones.

To help you adapt to these differences, Ren'Py for Android automatically selects a screen variant of touch. It also selects screen variants of phone or tablet based on the device's screen size. See Screen Variants for more information.

Building Android Applications

RAPT 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 RAPT, 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 RAPT 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 RAPT tools are command-line based. This documentation assumes that you are proficient with the basics of command-line operation.

Step 1: Installing RAPT and its Dependencies

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

Java Development Kit. The Java Development Kit (JDK) contains several tools that are used by RAPT, 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 RAPT. It can be downloaded from:

RAPT 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 RAPT can be downloaded from:

Once RAPT 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 RAPT 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 RAPT 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

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

Step 3: Configure Your Game

Before building a package, you must give RAPT 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.