How to Make A Simple HTML5 Game With Enchant.js

This is a post by Tutorial Team member Guts Rodsavas, an iOS development trainer at Software Park Thailand and game developer at Coffee Dog Games. Are you curious about developing cross-platform mobile games that work in a web browser? Well, as you probably know, Apple doesn’t allow Flash to run on iOS devices, and Adobe […] By .

Leave a rating/review
Save for later

This is a post by Tutorial Team member Guts Rodsavas, an iOS development trainer at Software Park Thailand and game developer at Coffee Dog Games.

Learn how to make a simple browser-based mobile game with HTML5!

Learn how to make a simple browser-based mobile game with HTML5!

Are you curious about developing cross-platform mobile games that work in a web browser?

Well, as you probably know, Apple doesn’t allow Flash to run on iOS devices, and Adobe has pulled the plug on Flash for mobile. This makes HTML5 your only solution – but actually a pretty good one!

The thing is, while there are many HTML5 game libraries available, only a few of them support mobile browsers. In this tutorial, you’ll try out one HTML5 game library that works great on the iPhone, Android, and the desktop – enchant.js!

You’ll make a game called called Penguin Dive, where players will take control of a penguin that’s swimming in the ocean, and dodge incoming ice boulders. The longer the penguin stays safely in the ocean, the higher the score. Once an ice boulder hits the penguin, it’s game over!

This tutorial assumes you are a complete beginner to enchant.js, but you must have some basic knowledge of JavaScript and HTML. Knowing how to set up your own local server also helps for testing purposes, but isn’t required.

If you’re ready, then let’s get this party started!

Introducing enchant.js

enchant.js logoenchant.js is a fairly new HTML5+JavaScript game framework. The version as of writing is 0.51, which is DOM-based. The future version will move to HTML5 Canvas-based.

In case you’re wondering, DOM stands for Document Object Model. In this type of JavaScript coding, the code accesses the elements on a page via a structured hierarchy. Usually, the elements on the page are represented like a tree, where each HTML element is a branch or a leaf, and has a name or ID by which it can be accessed directly (or by way of a parent or grandparent).

The Canvas-based approach will rely on the new HTML5 <canvas> tag, which allows the code to define a canvas (or drawing area) and then draw directly on that surface, much as you would use CoreGraphics drawing functions in Objective-C.

Each approach has its pros and cons, but this tutorial won’t delve into those, since enchant.js will take care of the details internally. But it’s good to know the pros and cons of using enchant.js itself!

Pros of Using enchant.js:

  • It has a 2D scene graph system with a simple Flash-like API.
  • It’s cross-platform. Your game will work on iOS, Android, and desktop browsers.
  • It’s lightweight.
  • There are many plugins available to help you make specific types of games, such as a visual novel or an RPG.
  • It’s free and open-source!

Cons of Using enchant.js:

  • It lacks device orientation-related features.
  • It doesn’t yet support multi-touch.
  • Due to the framework’s Japanese origin, there is a lack of resources in English. (But this tutorial is helping to change that!)

Its cross-platform support is what makes enchant.js stand out from other HTML5 game frameworks. While it lacks some features, the current version is functional enough to make a complete working game.

Setting Up the Environment

Here is what you’ll need in order to write a game with enchant.js:

  1. enchant.js: Download the framework from their github page. You can either clone the git repository, or use the ZIP icon at the top of the page to download a ZIP archive of the current source.
  2. Game assets: Download these assets for the tutorial, and unzip them on your hard drive.
  3. Text Editor: Since developing using enchant.js means working with JavaScript, decide what IDE/text editor to use. My favorite is Sublime Text 2. You can also use something like, which allows you to develop in your browser. :]
  4. Web Server: This is optional. However, it’s better to test your HTML5 game on a web server rather than from your hard disk, since viewing a web page on your hard disk directly might disable some features. It also lets you test your game from your mobile device! There are many ways to set up a web server, but one of the easiest is to go with XAMMP.

Apart from the above, you need a web browser with a JavaScript console so that you can view the JavaScript output as you code.

Note: Note that although you are making a HTML5 game that will work on mobile browsers, usually you’ll want to test the game on a normal browser while you’re developing the game. This allows for faster test/run cycles, and lets you easily see the Javascript output.

In this tutorial, you will be using a normal web browser until later on in the tutorial, where I’ll show you how to get it working nicely on a mobile browser.

Your choices for a development browser are:

  1. Google Chrome: You can enable the console by clicking on the Wrench Icon, then Tools, and selecting the JavaScript console.
  2. Safari: You have to enable the Developer menu first. Go to Safari\Preferences and check Show Develop menu in menu bar in the Advanced Tab. You can then open the console through Develop\Show Error Console.
  3. Firefox: You can either install the Firebug extension, or enable the console via Extras\Error Console or Tools\Web Developer\Error Console (depending on your version). Note Firebug has some extra cool features beyond the normal console.
  4. Opera: Enable through Menu\Page\Developer Tools\Opera Dragonfly.
  5. Internet Explorer: Don’t use this! :D Unless you really have no other choice – then grit your teeth and press F12 to get to the developer tools.

Preparing Your Project Structure

enchant.js doesn’t enforce any directory structure for projects. You can structure the project folders any way you like. So in this tutorial, you’re going to structure things in a way that makes sense to me. Hopefully, it will make sense to you, too. ;]

Go to the directory that you want to be your workspace and create a new folder named penguindive.

Next, create subfolders within your penguindive folder so that the folder structure is as shown:


The res and js folders will be where you store your JavaScript files and your game assets, respectively. The lib folder will be where you store third-party JavaScript files/libraries.

The next step is to put all the game assets you downloaded earlier inside the res folder. Simply extract the ZIP file and copy the files. Once you do that, you should have the following files in the res folder:


You will not be using all of these files in this tutorial. However, feel free to use them to extend the game on your own, as a challenge. There are some suggestions for how to do this at the end of the tutorial. :]

Next, extract the enchant.js archive you downloaded from GitHub. Copy the enchant.js file and put it in your js\lib folder.

Hilighting enchant.js inside the archive downloaded from github.

Note: You’ll notice that there are two versions of enchant.js in the archive – enchant.js and enchant.min.js. The second file is the minified version, where extra spaces and carriage returns have been removed to make the smallest downloadable version possible for the code.

Since that version also replaces variable names and methods with short (usually incomprehensible) alternatives, it doesn’t lead to very human-readable code. So it’s best to use the standard version of the code during development and debugging (enchant.js) and to use the minified version in production (enchant.min.js).

You’re now ready to start the actual coding!