How to deploy your melonJS game on Facebook Instant Games in 3 minutes

Introduction

This guide will take you through the basic steps required to deploy your existing melonJS game(s) onto the Facebook Instant Games platform, and thus allowing to play it directly through Facebook and Messenger.

Note: to ensure the highest compatibility when integrating melonJS with the Facebook API and deploying games on the “Instant-Game” platform, minimum requirements for melonJS is version 5.1.0

The whole process relies on 3 simple steps that will only take a few minutes to complete:

1. Create a new App through your Facebook Developer account and configure it as an “Instant-game” product
2. Integrate the Facebook Instant Games API with your game
3. Upload your game on Facebook infrastructure

Once step 3 is done, you are ready to play your game through Messenger!

1. Setting up a new Instant-Game

At this stage, it is assumed that you already have a Facebook developer account, if not, you can simply go to the following URL and sign up for a new account: Facebook Developer account

Once logged in your developer account, let’s first Create a new app ID, name it, and click on the [Create App ID] button:

Once done, click on settings in the dashboard on the left, and on the right panel choose the “game” category:

Then choose a Sub-Category fitting with the style of your game (Puzzle here), and finally do not forget to click on [Save Changes]

Then back on the dashboard (on the left), click on +add Product, and choose “Instant-Game” from the available choices on the right:

Finally, the last step is to fill the form that will appear when clicking on “Set Up”:

IMPORTANT NOTE: Make sure you choose “Yes” for “use Instant Games”, and also make sure to choose the appropriate Orientation for your game.

Once done, scroll down to the bottom of the page and click on save changes, if all done properly you should then see the following message appearing.

We are not done yet though, as before uploading our game, we then need to integrate the Facebook API into our melonJS game. 

2. Instant-Game Facebook API Integration

The following instructions is based on the getting-started page of the Instant Games online documentation (where you can find further information and also links to the SDK documentation)

Note : when loading an Instant Game, it will search for a main root file index.html, so you need to make sure to use the same naming, but as well for the configuration file fbapp-config.json; an example of the latter can be found in the tic-tac-toe example available in the Quickstart section here, and should therefore be placed in the root level of your game beside the index.html file.

Importing

Now that our app is setup, we can start modifying our existing melonJS game. First step being to import the Instant Games SDK.

Simply modify your root index.html, and add the following script in the melonJS index.html file, for example before the melonJS script, as shown below.

  <!-- Canvas placeholder -->
  <div id="screen"></div>

  <!-- ES5-Shim -->
  <script type="text/javascript" src="lib/es5-shim.min.js"></script>

  <!-- FB instant Gaming -->
  <script src="https://connect.facebook.net/en_US/fbinstant.6.1.js"></script>

  <!-- melonJS Library -->
  <script type="text/javascript" src="lib/melonjs.js"></script>

  <!-- Game Scripts -->

Initializing

First thing to do is Initializing the SDK library, through the FBInstant.initializeAsync() function. This should be called before any other SDK functions. In the example below we call the function and then retrieve the player information

FBInstant.initializeAsync()
  .then(function() {
    playerInfo.name = FBInstant.player.getName();
    playerInfo.photo = FBInstant.player.getPhoto();
    playerInfo.id = FBInstant.player.getID();
    playerInfo.locale = FBInstant.getLocale();
  });

Back In our melonJS example, this should be inserted, still in index.html file, but this time in the bootstrap me.device.onReady function, and in our case we call game.onload() once the promised is solved, as shown below :

  <!-- Bootstrap -->
  <script type="text/javascript">
      me.device.onReady(function onReady() {
          FBInstant.initializeAsync()
            .then(function() {
              game.onload();
          });
      });
  </script>

Next and final step is to make sure we inform the SDK of the loading progress, and once all assets are loaded, tells the SDK to end loading view and start the game.

Informing the SDK about the loading process is done through the FBInstant.setLoadingProgress(progress) function.

As melonJS already has a built-in mechanism for such a progess event, it is as simple as connecting both together by simply adding the following code before calling the melonJS preload() function :

// notify the facebook API of the loading progress
me.event.subscribe(me.event.LOADER_PROGRESS, function (progress) {
    FBInstant.setLoadingProgress(Math.round(progress * 100));
});

Finally to tells the SDK to end the loading view and start a game, all we need is to insert a call for the startGameAsync() function, from within the onload callback, and right before changing (for example) to your title screen :

// tells the SDK to end loading view and start the game
FBInstant.startGameAsync().then(function() {
    // trigger a window resize event to adapt to the given CANVAS
    // since messenger does not give us the correct fullsize CANVAS size
    // unless the startGameAsync promise is
    me.event.publish(me.event.WINDOW_ONRESIZE);
    // The player is now guaranteed to have already tapped "play".
    me.state.change(me.state.PLAY);
});

Note : two things to be noted (1) it's sometime useful to force a resize event by adding a call to me.event.publish(me.event.WINDOW_ONRESIZE) within the promise, as messenger sometimes "fails" as returning the correct full canvas size. (2) a better place where to call the startGameAsync() function is probably after the state were changed, as sometimes, the melonJS loading screen (normally hidden by the Facebook loading screen) might still briefly be visible.

And we are done, now the only remaining task is to upload your game and play it in messenger!  

3. Game upload and Testing

Instant Games content is hosted on Facebook infrastructure, so you don't need to host the game content on your own or use third-party services. Once the game is ready for testing, package all game files into a single .zip file. Please note that the index.html file should be in the root of this archive and not in any sub-folders.

To upload the .zip file, click the Canvas Hosting tab in the App Dashboard. From there select "Instant Game" from the dropdown menu and click +Upload Version which will allow you to upload the .zip file to Facebook's hosting service.

After that, the build will process the file, which should only take a few seconds. When the state changes to "Standby", click the "★" button to push the build to production.

Once uploaded and in production, the game should appear in the Games Tab of Messenger under the “In Development section”.

More information about testing, publishing, and sharing your Instant Games are available [here] (https://developers.facebook.com/docs/games/instant-games/test-publish-share).