In this article by Emanuele Feronato, author of the book Learning Cocos2d-JS Game Development, we will see why we need to make cross-platform games and how to do it using Cocos2d-JS.

This is a very important question. I asked it to myself a lot of times when HTML5 mobile gaming started to become popular. I was just thinking it was a waste of time to simply care about the different screen resolutions and aspect ratios, so my first HTML5 game was made to perfectly fit my iPad 2 tablet.

When I finally showed it to sponsors, most of them said something like “Hey, I like the game, but unfortunately it does not look that good on my iPhone”. “Don’t worry”, I said, “you’ll get the game optimized for iPad and iPhone”. Unfortunately, it did not look that good on the Galaxy Note. Neither did it on the Samsung S4.

You can imagine the rest of this story. I found myself almost rewriting the game with a series of if.. then.. else loops, trying to make it look good on any device.

This is why you should make a cross-platform game: To code once and rule them all. Focus on game development and let a framework do the dirty work for you.

What Cocos2d-JS is and how it works

Cocos2d-JS is a free open source 2D game framework. It can help you to develop cross-platform browser games and native applications. This framework allows you to write games in JavaScript. So, if you have already developed JavaScript applications, you don’t have to learn a new language from scratch. Throughout this book, you will learn how to create almost any kind of cross-platform game using a familiar and intuitive language.

Requirements to run Cocos2d-JS

Before you start, let’s see what software you need to install on your computer in order to start developing with Cocos2d-JS:

• Firstly, you need a text editor. The official IDE for Cocos2d-JS coding is Cocos Code IDE, which you can download for free at http://www.cocos2d-x.org/products/codeide. It features auto completion, code hinting, and some more interesting characteristics to speed up your coding. If you are used to your favorite code editor, that’s fine. There are plenty of them, but I personally use PSPad (you can find this at http://www.pspad.com/) on my Windows machine and TextWrangler (you can find this at http://www.barebones.com/products/textwrangler/) on the Mac. They are both free and easy to use, so you can download and have them installed in a matter of minutes.
• To test your Cocos2d-JS projects, you will need to install a web server on your computer to override security limits when running your project locally. I am using WAMP (http://www.wampserver.com/) on my Windows machine, and MAMP (http://www.mamp.info/) on the Mac.

Again, both are free to use as you won’t need the PRO version, which is also available for Mac computers. Explaining all the theory behind this is beyond the scope of this book, but you can find all the required information as well as the installation documentation on the official sites.

• If you prefer, you can test your projects directly online by uploading them on an FTP space you own and call them directly from the web. In this case, you don’t need to have a web server installed on your computer, but I highly recommend using WAMP or MAMP instead.
• I personally use Google Chrome as the default browser to test my projects. As these projects are meant to be cross-platform games, it should run in the same way on every browser, so feel free to use the browser you prefer.

The latest information about Cocos2d-JS can be found on the official page http://www.cocos2d-x.org/wiki/Cocos2d-JS, while the latest version can be downloaded at http://www.cocos2d-x.org/download.

Cocos2d-JS is updated quite frequently, but at the time of writing, the latest stable release is v3.1. Although new releases always bring some changes, all examples included in this book should work fine with any release marked as 3.x as there aren’t huge changes in the roadmap.

You will notice the download file is a ZIP file that is greater than 250 MB. Don’t worry. Most of the content of the package is made by docs, graphic assets, and examples, while the only required folder, at the moment, is the one called cocos2d-html5.

The structure of your Cocos2d-JS project

Every HTML5 game is basically a web page with some magic in it; this is what you are going to create with Cocos2d-JS: a web page with some magic in it.

To perform this magic, a certain file structure needs to be created, so let’s take a look at a screenshot of a folder with a Cocos2d-JS project in it:

This is what you are going to build; to tell you the truth, this is a picture of the actual project folder I built for the example to be explained in this article, which is placed in the WAMP localhost folder on my computer. It couldn’t be any more real.

So, let’s take a look at the files to be created:

• cocos2d-html5: This is the folder you will find in the zip archive.
• index.html: This is the web page that will contain the game.
• main.js:This is a file required by Cocos2d-JS with the Cocos2d-JS function calls to make the game start. You will create this within the next few minutes.
• project.json: This is a JavaScript Object Notation (JSON) with some basic configurations. This is what you need to make your game run. Well, almost, because the actual game will be placed in the src folder. Let’s see a few other things first.

Hello Cross-World

The time has come, the boring theory has ended, and we can now start coding our first project. Let’s begin!

1. Firstly, create a page called index.html in the root of the game folder and write this HTML code:

   <!DOCTYPE html>
   <head>
      <title>
        My Awesome game
      </title>
      <script src="cocos2d-html5/CCBoot.js" type="text/javascript">
   </script>
      <script src="main.js" type="text/javascript">
   </script>
   </head>
   <body style="padding:0;margin:0;background-color:#000000;">
   </body>
   </html>

   There’s nothing interesting in it as it is just plain HTML. Let’s take a closer look at these lines to see what is going on:

   <script src=" cocos2d-html5/CCBoot.js "></script>

   Here, I am including the Cocos2d-JS boot file to make the framework start:

   <script src="main.js"></script>

   From the preceding line, this is where we call the script with the actual game we are going to build. Next, we have the following code:

   <canvas id="gameCanvas"></canvas>

   This is the canvas we will use to display the game. Notice here that the canvas does not have a width and height, as they will be defined by the game itself.

2. Next is the creation of main.js: the only file we will call from our main index.html page. This is more of a configuration file rather than the game itself, so you won’t code anything that is game-related at the moment. However, the file you are going to build will be the blueprint you will be using in all your Cocos2d-JS games.

   The content of main.js is as follows:

   cc.game.onStart = function(){
      cc.view.setDesignResolutionSize(320, 480, cc.ResolutionPolicy.SHOW_ALL);
      cc.director.runScene(new gameScene());
   };
   cc.game.run();

   Don’t worry about the code at the moment; it looks a lot more complicated than it really is. At the moment, the only line we have to worry about is the one that defines the resolution policy.

   One of the most challenging tasks in cross-platform development is to provide a good gaming experience, no matter what browser or what device the game is running on. However, the problem here is that each device has its own resolution, screen size, and ratio.

   Cocos2d-JS allows us to handle different resolutions in a similar way web designers do when building responsive design. At the moment, we just want to adapt the game canvas to fit the browser window while targeting the most popular resolution, which is 320×480 (portrait mode). That’s what this line does:

   cc.view.setDesignResolutionSize(320, 480, cc.ResolutionPolicy.SHOW_ALL);

   Using these settings, you should be pretty sure that your game will run on every device, although you will be working in a low resolution.

   Also, have a look at this line:

   cc.director.runScene(new gameScene());

   Basically, a Cocos2d-JS game is made by a scene where the game itself runs. There can be more scenes in the same game. Imagine a scene with the title screen, a scene with the game over screen, and a scene with the game itself. At the moment, you only have one scene called gameScene. Remember this name because you are going to use it later.

3. Following this, the next required blueprint file you are going to build is project.json, which has some interesting settings. Let’s take a look at the file first:

   {
   "debugMode" : 0,
   "showFPS" : false,
   "frameRate" : 60,
   "id" : "gameCanvas",
   "renderMode" : 0,
   "engineDir":"cocos2d-html5/",
    
   "modules" : ["cocos2d"],
    
   "jsList" : [
      "src/gamescript.js"
   ]
   }

   What do these lines mean? Let’s see them one by one:

   • debugMode: This is the object key that determines the level of debug warnings. It has a range from 0 to 6. Leave it at 0 at the moment since the project is very simple and we won’t make any errors.
   • showFPS: This object can be true or false; it shows or hides the FPS meter on the screen.
   • frameRate: This object sets the frame rate of your game. Set it to 60 to have a smooth game.
   • id: This is the DOM element that is required to run the game. Do you remember you gave your canvas the gameCanvas id? Here you are.
   • engineDir: This is the folder where Cocos2d-JS is installed.
   • modules: This object engines the modules to load. At the moment, we only need the basic Cocos2d library.
   • jsList: This is an array with the files used in the game. This means we are going to create our game in src/gamescript.js.
4. Finally, we arrive at the game script itself. This is the one that will contain the actual game, gamescript.js, which at the moment is just a plain declaration of the game scene:

   var gameScene = cc.Scene.extend({
   onEnter:function () {
      this._super();
      console.log("my awesome game starts here");
   }
   });

   Here, you want to save everything and call index.html page from your localhost (refer to your WAMP or MAMP docs) in your browser. If you now open the developer console, you should see:

   my awesome game starts here

Congratulations! This means you have successfully managed to create a Cocos2d-JS template file to build your future games.

Summary

In this article we learned the importance of cross-platform games and how to make them using Cocos2d-JS.