With the HTML5 export, you have a huge variety of ways that you can publish your game, like publishing it on your own website or going through a third party portal. One of the most popular methods to get your game out there for people to play is to use the Facebook Instant Games API.
In this article we explain how to get a game uploaded and running using this API, but before continuing please make sure that you are a Registered Facebook developer with access to the Instant Games Developer Platform. You can find more information from Facebook here.
Get The JS File Path
Take note of this as we'll need this path for the next step.
Get The Facebook Instant Games Extension
Assuming you have a HTML5 game or demo all ready for playing, you then want to add the Facebook Instant Game Extension to the project. This extension has the functions required to communicate with the Facebook Instant Games API and you won't be able to upload a working instant game without it. You can get just the extension file from the following link:
To add this to your project, simply open the project and then drag the downloaded extension from the file explorer onto the IDE. This will show the following prompt:
Click the Yes button, and then in the following window choose Add All then Import:
The extension will now be added to the resource tree of your game, ready for use.
Create A Custom HTML File
For the extension to communicate with Facebook, we need to set a Custom index.html file as the game launcher. This file will need to include the following line to include the Facebook Instant API:
You can find an example HTML file that calls this script here:
We'll need to edit this file in a moment, to actually point to our game in order for it be played. For now though, you'll want to just add it to your project as an Included File.
Your resource tree should now look something like this:
If you right-click on the file you've just added in the resource tree, then select "Open in Explorer", you will be taken to where this file has been saved in the project, and you can now open it in any text editor to edit. You want to change the line at the bottom that says:
To use the path to your game JS file that you noted previously like this:
Save this file and go back to GameMaker Studio 2 now.
We now need to tell GameMaker Studio 2 to use this custom index file instead of the default HTML, so you need to open the HTML5 Game Options and go to the General section. Here you need click the Included file as index.html dropdown and select the custom index html file that you just added. Once that's done, you then need to tell GameMaker that you want to use the Loading Bar extension, so click the Loading bar extension dropdown and select FBIntantGames_LoadingBar:
Create Config JSON
Facebook also requires that your game be bundled with a JSON file containing at least a minimum of configuration details. Below is the absolute minimum information that this file is required to contain before you can upload a game, but this will need to be edited to suit the game you are making (see the Facebook Developer page Bundle Configuration Reference):
"example": "Edgar played their move"
Once you have created this JSON file, save it somewhere safe for now as we won't be including it within GameMaker, but rather we'll be adding it to a ZIP file later. Make sure to name the file:
Graphics Game Options
While you are in the HTML5 Game Options, you should take this opportunity to set the Graphics options. For Facebook Instant Games, WebGL is fully supported but if the game is only available in WebGL then it must be set properly in the settings of the application on the dashboard of the FB application.
Facebook also recommend that the initial loading of an Instant Game is less than 1MB in size, so if your game does not use the built-in particle sprites, you should also disable Use built-in particles. This will help reduce the initial load weight.
Initialising Instant Games In Your Project
With all that done, it's time to add some code to initialise the Instant Games API. The following code is the minimum required by Facebook to get your game uploaded and running, and should be added to the Create Event of the first object to be created in the first room of your game (so some controller or init object):
The first of these functions initialises the API and then the next is to tell the Instant Games API that the game has loaded and is ready to start - you would normally wish to use 100 here to indicate that the game has loaded 100%. If you have further elements that you wish to load or add (like creating sprites from surfaces, or adding audio, etc...), then you can set this to a value less than 100 and increment it as required.
The third line is to tell the API that your game has started, and it requires you to provide two script names as strings, so for example:
These scripts will be called asynchronously whenever the Instant Games API generates a relevant callback:
- The first script will be called when the API returns that it is ready and the game can start to be played so you can go ahead and permit player interaction, start music, etc...
- The second script will be called whenever the API detects a "pause", enabling you to pause any music and pause any action in your game.
Note that the scripts all start with "gmcallback_". All callback scripts must be named with this suffix! In this way, the compiler will know not to obfuscate them and permit the extension to call them when required.
IMPORTANT! You cannot use the GML keywords "other" and "self" as they have no context when checked as part of a callback from the Instant Games functions. Using these keywords in any callback will cause an error, so they must not be used.
Packaging Your Instant Game
Your game now meets the minimum requirements to be permitted onto the Instant Games platform, and so it's time to package it ready for uploading. To start with you simply need to click the Run button in GameMaker Studio 2 (make sure you have the Target Manager set to HTML5) to run the game in your browser:
With the game running, browse to the to the folder from where the game is being run. You can find the full path to this folder from the Micro Web Server:
In this folder, select the html5game folder and the index.html file and add them to a Zip file:
To the ZIP, we will also need to add the JSON file that we made earlier: fbapp-config.json. It should be in the top level of the ZIP, beside the index.html file.
This ZIP file will be what we upload to Facebook as our Instant Game.
Setting Up The Game On Facebook
Now you have your game file packaged, it's time to set up your Facebook Developer page with the App details. For that you need to go to your Developer Apps dashboard (here) and select "Add a New App". Enter the title of your game, along with a contact email, before clicking "Create App ID":
From the App Dashboard, you need to go to the Instant Games section, and click the button labelled "Setup" then fill in the required information:
Once you've saved the changes you will need to click on Web Hosting in the products list on the left tab and click the "Upload Version" button:
Now, browse to where you saved the Zip we created previously and select it and click "Upload":
After uploading the status of that build will be set to Processing on the app dashboard. Within a minute or two this should change to Standby. If it doesn't (and it may not first time, as the upload and processing may fail due to external reasons) just upload the same ZIP file again.
Once the status is Standby, hover over the status and a "star" icon labelled "Push to Production" becomes visible. Click this now, but note that this doesn’t publish it publicly - at this stage only developers whose Facebook accounts have been added to the game will be able to play the game.
Your uploaded game status should now change to "Production". You now need to go back to Products > Instant Games > Details, and scroll down to the bottom of the page to find the button labelled Share Game, as well as a link:
Clicking the Share Game button will create a generated post for the game to be posted on your own timeline with the visibility set to "Only me":
When you go to your own Facebook profile, you should now see the post you just generated, and clicking on it should launch your game. This should work exactly the same on both mobile devices or desktop/browser Facebook. If you get any errors then check the console output in your browser's Developer Tools and you should be able to see what errors are occurring.
Note that you can also copy the link at the bottom and share that.
With that, you have successfully created and uploaded a Facebook Instant Game ready project. As we mentioned at the start of the article, this outlines the absolute minimum requirements to get a game onto Facebook in this way, however there are other more complex things which the Instant Game API can do. For more information, please see the following article: