In this tutorial we are going to create the “new hello world” in gaming, a Flappy Bird style game. We’ll be using Phaser, which is a popular HTML5 game framework, and the game we are going to build will feature the main character from my Super Jetroid game along with a few obstacles from my free Space Exploration Art Pack. In the first part of this three part series we are going to cover the following:
Before we dig into the code, you can check out the live demo of the game here.
The next three sections will walk you through three different configuration options: CodePen.io, NodeJS + Grunt and Apache local server.
Simply pick the one you feel the most comfortable with, and once you have your environment configured you can move ahead to setting up Phaser itself. It’s important to note that each of these development options have advantages and disadvantages. Which option you choose depends on your technical comfort level and your past experience building HTML5 content.
Sometimes the hardest part of making an HTML5 game is setting up the development environment. To help make this as easy as possible, you can actually use an online code editor such as CodePen.io in order to run all of the code we’ll cover in this Introduction to Phaser tutorial. The advantage here is that you don’t have install anything on your computer. The disadvantage is that you will not be able to really publish and share your game; you’ll still end up having to host it online somewhere else. This means, you’ll need to rewrite the code to be standalone which I will not cover in this tutorial. Here are instructions for setting that up.
Step 1. You will need to create a new account on CodePen.io.
Step 2. Create a new project.
Step 3. Add the following to the HTML Window
<div id=“game”></div>
This will give us an empty div where we can put our game.
Step 4. Now we’ll need to add the following into the CSS Window
body { background: #333; margin: 0; padding: 0; } #game { margin: 0 auto; max-height: 568px; max-width: 320px; }
This will represent our default CSS for the body of the page and the game div itself.
Step 5. We need to configure an external JS file for the project. We’ll be using a version of Phaser I have hosted on my server. Click on the gear icon to the left of the JS window and paste the following url in the “External JS File” field:
http://games.jessefreeman.com/wp-content/public/workshop/phaser/phaser.min.js
You should have something that looks like this:
Step 6. At this point we are done with the basic configuration, so make sure to minimize the HTML and CSS windows so you have a larger place to work on your code.
One thing to note when using CodePen is that you’ll need to load all of the artwork and sounds from an online server. We’ll cover this later in the tutorial but just keep in mind that you will need to preface the url path to all of the assets we load as part of this tutorial with the following url (which is coming from my personal website):
http://games.jessefreeman.com/wp-content/public/workshop/phaser/
As an aside, you may have issues loading your own artwork into a CodePen project if you are not a pro member and using their hosting solution. To get around this, I have a .htaccess file in the root of my server’s public folder with the following:
<IfModule mod_headers.c> Header set Access-Control-Allow-Origin "*" </IfModule>
This allows you to bypass the cross-domain issues you normally get when loading images from severs on a different domain.
At this point we are ready to move on so you can skip the next two sections on setting up the project locally with NodeJS and Grunt or Apache.
I am a big fan of having an automated build process when I develop HTML5 games. For all of my projects I use NodeJS and Grunt. This automated build process will compile the game’s code into a single JS file for you any time you make a code change and hit save. The workflow also sets up a temporary server to run your game locally and even opens your browser to the correct URL making the entire setup and development process dead simple once it’s fully configured.
To help you get started I have created a Phaser Template Project which you will need to download in addition to NodeJS, Grunt and the project’s dependent modules. The following steps will walk you through this process from scratch. If you already have node and grunt installed, simply skip ahead to step 2.
Step 1. You will need a copy of NodeJS, which works on Mac, PC and Linux. Simply go to http://nodejs.org and get the correct installer for your computer. Once it’s installed you want to open up the command line and type in the following:
> npm
You should see something like the following:
This means that NPM (Node Package Manager) is installed and you can continue on with the rest of the setup process.
Step 2. Next we’ll need to install Grunt on the command line. If you have never used Grunt before, you can learn more about it at http://gruntjs.com. For now, enter the following in the command line:
> npm install -g grunt-cli
Step 3. At this point you have everything you need to support the automated workflow. Next you’ll want to download my Phaser Project Template from https://github.com/gamecook/phaser-project-template and unzip it on your computer where you do your development.
Step 4. Let’s go ahead and rename the Phaser Template Project to phaser-demo.
Step 5. Now we need to install the project’s module dependencies that will allow us to run the Grunt build script. Open up the command line and navigate to the project folder. Once inside, type the following command.
> npm install
You’ll see the following in the terminal window:
If you get an error for any reason, simply re-run the command again.
Step 6. Run the following command to start the grunt task:
> grunt
Once the command is executed your browser should automatically open showing you the default project page and display the current Phaser build version.
Phaser is a very active project, so your build number may be slightly higher then what is displayed above. As of this writing, the current version of Phaser is v2.0.3. As long as you have the Grunt task running, your project will automatically recompile every time you make a change to any JavaScript file inside the src directory. Once the project is recompiled, simply refresh your browser to see the changes. Also, make sure you disable your browser's cache.
This template project has everything you need to build your own Phaser game. You’ll find the game’s source file in the src/game folder called main.js.
Phaser’s source code is inside of the lib folder. You can update Phaser on your own at any point by simply replacing the phaser.min.js file in that folder. Just be careful because newer versions of Phaser may break your game’s code.
Since this project is pre-configured to display the Phaser version number, you will want to open up the main.js file and delete all the code inside of it so that it’s blank before you get started building your new game. Now you can skip ahead to the Setting up Phaser section of the tutorial.
Phaser is just like any other HTML/JS project you have ever worked with. If CodePen and NodeJS/Grunt are not your thing, simply run the game from Apache or any web server you are familiar with. Let’s look at how to setup the Phaser Project Template from the NodeJS configuration setup inside of Apache.
Step 1. Make sure you have Apache installed. I suggest using one of the following depending on your OS:
Step 2. Once Apache is installed and running, you will need to download my Phaser Project Template (https://github.com/gamecook/phaser-project-template) and put it in your Apache’s web root.
Step 3. Now you will want to move main.js and phaser.min.js from src folder into deploy/js folder. Since we are not automatically compiling these two files, we’ll just manually set them up like any regular script tag reference in an HTML file.
Step 4. Open up the index.html file inside of the deploy folder and fix the paths. You will need to load both js files like so:
<script src="js/phaser.min.js"></script> <script src="js/main.js"></script>
Step 5. At this point you are ready to load the project up in the browser. Navigate to your Apache’s localhost and go into the deploy folder. You should see the following:
Note that your url may be different depending on what port your Apache is configured to use. You may also see a different Phaser version number than what is displayed above. As of this writing, Phaser 2.0.3 is the latest build.
Step 6. Now that everything is working, open up the main.js file that should now be located in your deploy/js directory and delete everything inside of it. Then you’ll be ready to start the tutorial in the next section.
The hard part of configuring our environment is now behind us and it’s time to build our first Phaser game.
Step 1. At this point you should have an empty main.js file if you are using the Phaser Project Template or an empty JS window in CodePen.
Step 2. Type out the following object, which we will assign to a state variable:
var state = { preload: function(){ }, create: function(){ }, update: function(){ } }
Phaser uses a notion of “states” to represent each screen of your game. Think of the state as a place to keep all of the logic that belongs in that scene. Phaser will take a state and wire it up to the main game engine to run your code. When creating states, we’ll take advantage of a few functions such as preload(), create() (which is run first when a state is created and done preloading), and update() (which is run before the draw call). While Phaser has other state functions available, we’ll only be focusing on these three main ones for this tutorial.
Step 3. Now it’s time for us to create an instance of the actual Phaser game. Add the following code below where we created our state object:
var game = new Phaser.Game( 320, 568, Phaser.AUTO, 'game', state )
This will represent our Phaser game. Here you can see we are creating an instance of Phaser.Game as well as supplying the width and height. We are going to set the render mode of Phaser to Phaser.AUTO. This will detect what rendering options your browser supports and either run the game with WebGL support or call back to software based 2d Canvas. Finally we define the name of the div where our game should be created as well as pass in a reference of the initial state object.
Step 4. Now you are ready to refresh browser. You should see that we simply have a black box representing where our game will eventually go.
At this point you should now have a stable work environment for building Phaser games as well as the initial game code setup to build upon in the next parts of this tutorial. Coming up next, well talk about preloading, displaying images and building out some basic game mode logic for starting, playing and ending our game.
- Jesse Freeman (@jessefreeman)