Porting an HTML/PixiJS game to Android

Read this post on Medium

I recently wanted to port some of my PixiJS games to standalone Android apps and couldn’t find any guide on how to do so. The process itself isn’t complicated, but requires some Android knowledge that not every HTML game dev is going to have. So this is my attempt to document how I port my game, in the hopes that it helps others.

This assumes you have your game as a standalone build (built using something like webpack) and doesn’t rely on any external dependencies or links.

Step 1: Setting up Android Studio

I’m not going to talk about this part in depth, because this step is already well documented. However, you will need to have Android Studio installed and ready to build Android apps.

Download Android Studio here: https://developer.android.com/studio

Step 2: Creating a new project

We’ll start by creating a new project in Android Studio and selecting the Empty Activity template

Give it a name, and select “Java” as the language:

You should be able to run your app on a device or emulator now and see a basic “Hello world” screen.

Step 3: Adding a Webview

We’ll need to add a Webview to display the HTML game. In Android Studio, open the app/res/layout/activity_main.xml file and you should see a graphical editor in which you can edit the activity.

Delete the existing TextView

And drag in a WebView

And make sure to give it an id. I called mine “webView”.

Next, we’ll edit MainActivity.java and load some HTML into our WebView to test it works:

Step 4: Loading in the HTML game

After building my game with Webpack, I have my game files as a neat directory featuring an index.html, the script containing my Javascript and PixiJS dependencies, and an assets directory containing images and sounds used in the game.

Create an ‘assets’ directory on the same level as the ‘res’ directory in your Android project (ie, ‘app/src/main/assets’) and copy in your game files.

Next, we’ll add some code to load this game from our WebView.

You should be able to run the app and see the game appear on the screen now.

If your game is portrait and fits the screen already, and you’re fine with having the system controls showing all the time, you’re pretty much done! However this is not often going to be the case. Many games are fullscreen and landscape, so let’s configure our app a bit more.

Step 5: Adjusting scale, fullscreen and screen orientation

Fullscreen

I made the app fullscreen following the instructions here: https://developer.android.com/training/system-ui/immersive

It’s as simple as copying the code from the documentation into the MainActivity class.

Screen Orientation

For this one, we’ll need to edit the AndroidManifest.xml file located under ‘manifests’. We need to add android:screenOrientation=“landscape” inside the tag. It should look something like:

Scale

This one was a little trickier. After enabling fullscreen and changing the screen orientation to landscape, I noticed the dimensions of my game didn’t quite fit the screen of my device:

Oops

My game’s view is 800x600 which doesn’t match the aspect ratio of my device even slightly.

To fix this, I wrote a small helper function that will calculate the scale the WebView should be set to, given a desired width and height (this should be the size of your game’s view).

This should be used in the code like so:

// For a 800px by 600px web game
webView.setInitialScale(getScale(800, 600));

And voilà:

The letterboxing is a bit ugly, which is really on me for not picking a more mobile-friendly aspect ratio, or allowing the game to be easily resized. But it is now fully visible within the webview and 100% playable.

Phew! We’re done! All up this process took me about a half hour, so it’s really not too tricky to get an HTML game into it’s own app. I haven’t yet tested performance on anything particularly intensive, but the game plays as well in the app as it does in my Android’s browser.

If you’ve made it this far, I really hope this helped you. If you run into any issues, please let me know!