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 onto the Facebook Instant Games platform, allowing players to play it directly through Facebook and Messenger.

Note: this guide assumes melonJS 18.x or higher. For older versions, refer to the Upgrade Guide.

The whole process relies on 3 simple steps:

1. Create a new App through your Meta Developer account and configure it as an "Instant Game"
2. Integrate the Instant Games SDK with your game
3. Upload your game to Facebook infrastructure

1. Setting up a new Instant Game

At this stage, it is assumed that you already have a Meta developer account. If not, sign up at: Meta Developer account

Once logged in, create a new app, select the "Games" type, and configure it as an Instant Game product. Follow the on-screen instructions to complete the setup.

IMPORTANT: Make sure you choose "Yes" for "use Instant Games", and select the appropriate orientation for your game.

2. Instant Games SDK Integration

The following is based on the getting started page of the Instant Games documentation.

Note: the Instant Game platform expects a root index.html file and a fbapp-config.json configuration file at the root of your game bundle.

Importing the SDK

Add the Instant Games SDK to your index.html before your game scripts:

<div id="screen"></div>

<!-- FB Instant Games SDK -->
<script src="https://connect.facebook.net/en_US/fbinstant.6.3.js"></script>

<!-- Your game bundle -->
<script type="module" src="index.js"></script>

Initializing

Initialize the SDK before starting your game. The FBInstant.initializeAsync() function must be called before any other SDK functions:

import { Application, event, state } from 'melonjs';
import { PlayScreen } from './screens/play.js';

// wait for the FB SDK to be ready
FBInstant.initializeAsync().then(() => {
    // retrieve player info if needed
    const playerName = FBInstant.player.getName();
    const playerPhoto = FBInstant.player.getPhoto();

    // create the application
    const app = new Application(800, 600, {
        parent: "screen",
        scale: "auto",
    });

    // notify Facebook of loading progress
    event.on(event.LOADER_PROGRESS, (progress) => {
        FBInstant.setLoadingProgress(Math.round(progress * 100));
    });

    // set up game screens
    state.set(state.PLAY, new PlayScreen());

    // tell the SDK loading is done and start the game
    FBInstant.startGameAsync().then(() => {
        state.change(state.PLAY, true);
    });
});

Note: it can be useful to force a resize event after startGameAsync() resolves, as Messenger sometimes doesn't return the correct canvas size initially:

FBInstant.startGameAsync().then(() => {
    app.resize();
    state.change(state.PLAY, true);
});

3. Game Upload and Testing

Instant Games content is hosted on Facebook infrastructure — you don't need your own hosting.

1. Package all game files into a single .zip file (make sure index.html is at the root, not in a sub-folder)
2. In the App Dashboard, go to the "Instant Games" > "Web Hosting" tab
3. Click "+ Upload Version" and upload the .zip file
4. Once the build status changes to "Standby", click the "★" button to push it to production

The game should then appear in the Games tab of Messenger under "In Development".

More information about testing, publishing, and sharing your Instant Games: Test, Publish and Share