How to Turn Your Groovy Phaser Game into a Mobile App

Here’s a Phaser game I wrote called Annihilation

So you made your amazing Phaser game, and now you’re thinking to yourself, “Self, let’s port this to a mobile app and get rich beyond our wildest dreams!”

(* you know you did. everybody does)

In case you don’t know, Phaser is a javascript library to facilitate game development using HTML5’s nifty new “canvas” element.

From the creators of Phaser:

Phaser is a fast, free, and fun open source HTML5 game framework that offers WebGL and Canvas rendering across desktop and mobile web browsers. Games can be compiled to iOS, Android and native apps by using 3rd party tools. You can use JavaScript or TypeScript for development.

What we’re interested in for the purposes of this tutorial is that next-to-last line, practically a throwaway comment:

Games can be compiled to iOS, Android and native apps by using 3rd party tools.

That’s what we’re going to do today. This tutorial isn’t about making a game in Phaser. I’m not going to teach you one line of code. It’s predicated on the fact that you’ve already done that, and are now just wanting to turn your existing game into a mobile app.

Here’s a look at my sexy little Annihilation game. That’s the one I wanted to turn into a phone app. I call it a “Retro 80s-Style Arcade Space-Shooter Game.” I grew up on those. I like those.

(Easter egg: the space bar is a secret “boost”)

There’s a nice tutorial at GameDevAcademy outlining the Cordova steps involved (Thank You, Tobe Osakwe!), and expect to be referring back to it often, but the purpose of this article is to help get you to that point!

This article is by no means a replacement for that excellent guide. This is only to help you get to the point where that guide will be useful for you!

If you’ve ever installed/configured/trouble..shoot..ed framework packages, then you already know what I mean. The tedious tedium of writing a zillion lines of code to produce a game has been replaced by the tedious tedium of installing, configuring and troubleshooting the tools you now use to write those zillion lines of code for you.

I don’t know about you, but I much prefer writing the pew-pew-pew code than the calculus to output each pixel to the screen. So it’s worth it.

I saw a relevant xkcd the other day that was talking about how the company paid some guy for six months to install all the correct frameworks so that you could write your 14 lines of code in a familiar environment. I totally get it.

To that point, here’s what’s going to happen:

You are going to install and configure something like 16gig of software to transform your 400-line Phaser game into a mobile app!

Here’s the irony. If you just follow the link to my existing game on your phone, then turn your phone sideways, it’s already playable on mobile, all scaled down nicely and everything. But it’s not an app. It’s just a web page that you’re looking at sideways.

Here’s what you’re going to need:

>gitBash (get git, too, because Cordova uses it)
>NodeJS
>Cordova.

Easy peasy, right?

But Cordova needs you to install:
>Android SDK
Which needs you to install:
>Java

So I went like this: gitBash, git, NodeJS, Java, Android SDK, then Cordova.

Then comes the setup.

git and NodeJS installed pretty smoothly and work as expected. Java fit right in, and Android SDK also smoothly assimilated into the crowd.

Getting them all to function the way Cordova wanted was a little more complicated. That’s what the meat of this article is about.

By this point, you're halfway through the GameDevAcademy tutorial and wondering why your Cordova isn’t being as friendly as their Cordova. Meanwhile, you’re also following the steps to run your first app with Cordova.

The first thing I ran into with Cordova when I was following those steps was this:

Requirements check results for android:
Java JDK: installed 1.8.0
Android SDK: installed true
Android target: installed android-25,android-23
Gradle: not installed 
Could not find an installed version of Gradle either in Android Studio,
or on your system to install the gradle wrapper. Please include gradle 
in your path, or install Android Studio

I already had Android SDK installed so now I had to add Gradle. Gradle helps package your build when you’re ready to publish.

So here’s the steps to install Gradle:

Microsoft Windows users

Create a new directory C:\Gradle with File Explorer.

Open a second File Explorer window and go to the directory where the Gradle distribution was downloaded. Double-click the ZIP archive to expose the content. Drag the content folder gradle-6.0.1 to your newly created C:\Gradle folder.

Alternatively you can unpack the Gradle distribution ZIP into C:\Gradle using an archiver tool of your choice.

Step 3. Configure your system environment

Step 3’s the kicker: “Configure your system environment”

Sounds simple, right? Like when you’re trying to learn how to fix a carburetor and the book says “Step 1: remove carburetor from engine.”

Now you have to learn how to do that.

Here you go:

Download Gradle binary file.

Extract the zip file to ‘C:\Gradle’ or somewhere else

open Edit Environment variable dialog from start menu > Search

Click ‘New’ under system variables and add as below

Variable Name GRADLE_HOME Variable Value C:\Gradle\gradle-4.0.1

Then choose PATH variable from system variable list

append the gradle path to variable value like this C:\Gradle\gradle-4.0.1\bin

then type “command prompt” into Windows search, then go to command terminal and type gradle -v

if the setup is correct you will see the gradle installation details

Mine says this:

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — —
Gradle 6.0.1
— — — — — — — — — — — — — — — — — — — — — — — — — — — — — —

Build time: 2019–11–18 20:25:01 UTC
Revision: fad121066a68c4701acd362daf4287a7c309a0f5

Kotlin: 1.3.50
Groovy: 2.5.8
Ant: Apache Ant(TM) version 1.10.7 compiled on September 1 2019
JVM: 1.8.0_231 (Oracle Corporation 25.231-b11)
OS: Windows 10 10.0 amd64

So you go back to Cordova and try again. This time you run into this madness:

c:\Users\work\biziHiveMobile\platforms\android\cordova\node_modules\q\q.js:126
                throw e;
                      ^
ERROR : No emulator images (avds) found.
1. Download desired System Image by running: c:\Users\work\AppData\Local\Android\android-sdk\tools\android.BAT sdk
2. Create an AVD by running: c:\Users\work\AppData\Local\Android\android-sdk\tools\android.BAT avd
HINT: For a faster emulator, use an Intel System Image and install the HAXM device driver

Error: c:\Users\work\biziHiveMobile\platforms\android\cordova\run.bat:  Command failed with exit code 1 
at ChildProcess.whenDone (c:\Users\work\AppData\Roaming \npm\node_modules\cor
dova\node_modules\cordova-lib\src\cordova\superspawn.js:131:23)
at ChildProcess.emit (events.js:110:17)
at maybeClose (child_process.js:1015:16)
at Process.ChildProcess._handle.onexit (child_process.js:1087:5)

That’s telling you that you don’t have a phone type selected to emulate. So I went back to Android SDK and added one with these “simple” steps:

To create a new AVD:

1. Open the AVD Manager by clicking Tools > AVD Manager. (mine was empty and yours will be, too)

You can get there like this. Run Android Studio, and from the main menu there’s a “Configure” option at the bottom right (Right next to where it says “Get Help” in the picture below).

That will take you to AVD Manager:

2. Click Create Virtual Device, at the bottom left of the AVD Manager dialog.

3. The Select Hardware page appears.

Notice that only some hardware profiles are indicated to include Play Store. This indicates that these profiles are fully CTS compliant and may use system images that include the Play Store app.

Find one you want to develop for and select it.

Then it tells you to select System Image. This will be what version of Android or above you want to emulate. You want to make sure your API level matches the API level of your Cordova install:

It’ll ask you for some default settings. My Annihilation game is wider than it is high, so I chose “Startup Orientation -> Landscape,” but pick what you need.

So there’s another roadblock passed! On to the next one!

Next time you run Cordova, you will probably encounter about a hundred of these:

Emulator:glTexImage2D: got err pre :( 0x506 internal 0x1908 format 0x1908 type 0x1401

To fix this, you go back to Android SDK and start your AVD manager again.

This time you click the play icon under the “Actions” column and it brings up an emulator for your phone like this:

When you click the ellipses (…) at the bottom of the toolbar, that menu on the right comes up. Go to settings, then Advanced, and set OpenGL ES Render to “SwiftShader” and OpenGL ES API Level to “Render Maximum”.

Of course you’ll have to restart. Since it doesn’t specify, I just rebooted my whole machine, because by this time my fan was pretty well going crazy.

Then the next time I tried to run my Cordova app, I ran into this mess:

Panic! At the Source Code

Now we’re getting into “PANIC” level errors! It turns out this one was pretty easy to resolve. When originally set up my AVD, I chose what phone to emulate in the Android Development Kit, and I only chose the x86 version.

To resolve this error, I had to go back and choose the x86_64 system image to the one I had already selected.

I ended up having to go back and delete the first AVD I had setup, because Cordova still wanted to use that one. Once I deleted it, the new one worked just fine.

Keep in mind, you may have to be getting out of Android Studio and Cordova several times in the course of this process. I even rebooted my computer a few times.

But after all that, the next time you run your sample app from the Cordova tutorial you should finally be seeing this:

Hooray!

Now’s the time you can finally begin to edit your own code into the framework.

There’s still another consideration, though. During subsequent runs of your Cordova app you may run in to a couple of errors; 1) it may say your encryption failed and you have to reset your phone or b) The phone emulator may just disappear before loading your app.

In both of those instances I just went back to Android Studio, and selected the AVD manager. Remember this guy?:

Under the actions column, the down-arrow is a menu of phone actions you can perform. One of them is “Wipe Data.” I ended up having to do that periodically when developing apps using Cordova. You may have to “Cold Boot” also.

Back to the mayhem:

Remember when you created your “hello” project in the GameDevAcademy Tutorial? Cordova established a file structure for you like this:

hooks\
platform\
plugins\
www\
css\
img\
js\
index.html
config.xml

That index.html page is the one you can start to edit to start making your own application dreams come true.

There’s nothing special you need to do to be able to edit the HTML file. Just browse to it with Windows File Explorer and edit it in your favorite editor. I use VS Code, but you can just as easily use Eclipse or Notepad++ or even Notepad if you’re some kind of maniac.

Here’s what my first edit of the index.html file looked like:

<!DOCTYPE html>
<html>
<head>
<! —
Customize this policy to fit your own app’s needs. For more guidance, see:
https://github.com/apache/cordova-plugin-whitelist/blob/master/README.md#content-security-policy
Some notes:

* gap: is required only on iOS (when using UIWebView) and is needed for JS->native communication
* https://ssl.gstatic.com is required only on Android and is needed for TalkBack to function properly
* Disables use of inline scripts in order to mitigate risk of XSS vulnerabilities. To change this:
* Enable inline JS: add ‘unsafe-inline’ to default-src

→

<meta http-equiv=”Content-Security-Policy” content=”default-src ‘self’ data: gap: https://ssl.gstatic.com ‘unsafe-eval’; style-src ‘self’ ‘unsafe-inline’; media-src *; img-src ‘self’ data: content:;”>
<meta name=”format-detection” content=”telephone=no”>
<meta name=”msapplication-tap-highlight” content=”no”>
<meta name=”viewport” content=”initial-scale=1, width=device-width, viewport-fit=cover”>

<link rel=”stylesheet” type=”text/css” href=”css/index.css”>

<title>Hello World</title>
</head>

<body>
<div class=”app”>
<h1>CrazyHappyFunTime!</h1>
<div id=”deviceready” class=”blink”>
<p class=”event listening”>Connecting to Device</p>
<p class=”event received”>Hi mom</p>
</div>
</div>

<script type=”text/javascript” src=”cordova.js”></script>
<script type=”text/javascript” src=”js/index.js”></script>

</body>
</html>

As you can see, all I did was change the text of the <h1>element to be the name of my website, and I changed the text below the icon to be “HiMom” (my personal version of “hello world”). The rest of that stuff is already put there for you by the Cordova framework. It’s paying off already.

Now we’re just getting started! It’s time to bring your Phaser code into this framework.

I tried slapping it all right into the middle of the HTML code, wrapped in a DIV. After a few tries and realizing that nothing was happening, I actually read those comments up there and realized that inline javascript was disabled for security purposes.

So then I put all my javascript into a separate file and Eureka Springs, it works!

This is also the point when you discover that you suck as a programmer because you hard-coded absolute positioning for virtually every game element you used in your game, and now all those need to be changed to relative positioning.

How do I know that? Because that’s the reason you’re not looking at a screenshot of my sweet sweet Annihilation Mobile App right now.

The only thing I used relative positioning for was my Player sprite like:

player(x,y) = game.width/2, game.height/2;

and everything else was posted at absolute positions like this:

enemy(x,y) = 0,150;

What’s that mean? My layout is all messed up. There’s enemies that pop up behind the player, the extra-lives counter displays off the side of the screen, and the bottom of the playing field isn’t even visible on mobile!

But that’s for me to fix. This tutorial is only to elucidate this concept:

The frustration and tedium involved in getting all these frameworks, packages and environments to work together is actually part of the process, not some random anomaly that only you are experiencing.

That you should never give up, become frustrated or irritated (I found out a long time ago that that doesn’t help) and understand that all these little fires you had to put out to get to this point are no more indicative of your skill as a creator than some random syntax error you have to track down and resolve.

The end result is what counts. Hopefully by now you’ve gotten everything set up so that you can begin developing mobile apps with your nifty new Cordova framework, and that when you run into the gajillion or so new glitches you’ll encounter in the future, that you’ll share your solutions as well.