
An Instant Game is a game that can be played directly in the Facebook Messenger application, and from Babylon.js version 3.1 you can use your favorite framework to create a game that can be deployed on this platform.

This documentation explains how to transform an existing Babylon.js game into an Instant Game.

## Useful links

- [Instant Games documentation](https://developers.facebook.com/docs/games/instant-games)

- [Instant Games SDK documentation](https://developers.facebook.com/docs/games/instant-games/sdk/fbinstant6.2)

## The process

1. Create an Instant Game app : [Facebook Dashboard](https://developers.facebook.com/docs/games/instant-games/)

2. Include the Facebook SDK URL in your game HTML page:

```html
<script src="https://connect.facebook.net/en_US/fbinstant.6.2.js"></script>
```

3. Then you have to initialize the instant game with the `FBInstant.initializeAsync` method. In the game example, I created a file called `main.ts` that creates the game once the framework is initialized:

```javascript
FBInstant.initializeAsync()
  .then(() => {
    // Many properties will be null until the initialization completes.
    // This is a good place to fetch them:
    let locale = FBInstant.getLocale(); // 'en_US' 'fr_FR'...
    let platform = FBInstant.getPlatform(); // 'IOS', 'ANDROID' or 'WEB'
    let sdkVersion = FBInstant.getSDKVersion(); // '3.0'
    let playerID = FBInstant.player.getID();

    console.log(locale, platform, sdkVersion, playerID);

    // The game is created here
    new Game("gameCanvas");
  })
  .catch((e) => {
    console.log(e);
  });
```

Then you can load your assets and start your game.

4. Update the Facebook loading screen: by using an Asset Manager, you can use the exposed `onProgress` property to update the loading screen.

```javascript
loader.onProgress = (remaining: number, totalCount: number) => {
  FBInstant.setLoadingProgress(100 - remaining / totalCount);
};
```

5. Remove the loading screen and start the game: once your scene is ready, use `FBInstant.startGameAsync` to start your instant game.

```javascript
this.scene.executeWhenReady(() => {
  FBInstant.startGameAsync().then(() => {
    // Game initialization
    this._initGame();

    // Run render loop
    this.engine.runRenderLoop(() => {
      this.scene.render();
    });
  });
});
```

6. Once your game is ready, you can upload it through the Facebook Instant Games Dashboard and run it. Setup is complete.

## Example

An example game can be found here: [SIMON3D](https://github.com/Temechon/simon3d)

This game is far from finished, but it shows how to configure a very simple Babylon.js demo game and make it run as an Instant Game.



## A brief example showing how to use Babylon.js in an Ionic 2 application

For anyone interested, it is possible to integrate Babylon.js into an Ionic/Cordova app in just a few easy steps. The following is simply a narrative of how I did it. Since it has been a trial-and-error process, there is probably a better way to do it. When in doubt, I went for simplicity rather than optimization.

## What you need

First, you need node/npm installed. For more on that look [here](https://nodejs.org/en/).

Second, and quite obviously, a working Ionic environment. How to do this is very well documented by the Ionic people so, if you haven't done it before have a look [there](https://ionicframework.com/docs/intro/tutorial/).

## The process

1. Start a new Ionic project, I used the blank template, which provides a basic scaffolding, and removed all unnecessary stuff.

2. Then, install Babylon.js within the project:

```bash
npm install babylonjs@2.5.0 --save
```

> A couple things to remember:
>
> - Be careful not to write babylon (different package, yes it happened to me!).
> - Specify version, otherwise npm will install the preview branch and things will fall apart at runtime!

3. Go to the last line of babylon.d.ts (in node_modules/babylonjs/dist) and type:

```typescript
export = BABYLON;
```

> These last two steps will create the proper entry in the node_modules folder and will let you do:
>
> ```typescript
> import BABYLON from "babylonjs";
> ```
>
> wherever you need to.

4. Depending on what you intend to do in your app, other dependencies might be needed (e.g. cannon.js or hand.js).
   You could install them the same way as Babylon.js, but I just downloaded the JavaScript files, saved them in the `www` folder, and referenced them using script tags in `index.html`. However, this has a downside: the `www` folder is generated after transpiling, so you will need to add those JavaScript files **manually**.

5. After this, I generated an Angular [Provider](https://docs.angularjs.org/guide/providers). This is a singleton class that wraps our Babylon.js engine:

```bash
ionic g providerBabylon.js
```

> Besides holding our Engine instance, being in a provider allows for different pages to access the same Engine, e.g. you define different scenes in different pages and use the same Engine provider for all.

6. Another provider (`ConfigProvider`) is created to handle all necessary configuration variables. In this case, it just contains the dice colors and texture for both dice.

   > Actually, when you look at it, a Provider is a regular TypeScript class, nothing really special apart from the **@Injectable** decorator, which tells Angular that this is a special class to be injected during the bootstrap process and made available to the hierarchy of components that make up an app.

7. The very basic configuration interface is an Ionic page showing the available options. Note the header, a basic Ionic component that handles the back button automatically.  
   All the values are stored in the Config service, which makes them available to any page that declares a dependency on the Config provider.

8. The Home page will contain the Babylon.js canvas. An Ionic page is basically an Angular component with some sugar added, mainly in the form of a few helpful life cycle hooks.  
   The whole scene is created here, note that we are using the two providers that were previously generated.  
   The ViewChild decorator is needed in order to access the canvas element. Think of it as Angular's equivalent of the good old `document.getElementById` method.

## A few notes on the code

The app itself is a very basic, no-frills dice roller, but there are a few things worth mentioning:

- We are using Ionic components to provide a basic user interface, with a header and a couple FAB buttons to access the configuration screen and roll the dice. See the methods handling the button events.
- The Home page code makes use of `ionViewDidLoad` and `ionViewWillEnter`, both are Ionic hooks to the page life cycle. The first fires only once, when the view loads, so it is ideal to initialize variables and generate the scene proper.  
  The second fires every time the view is going to become active, it checks for possible changes in the configuration and modifies the vertex data to point to the correct coordinates if necessary.
- Ionic, by default, caches the views, so anything included in the `ionViewDidLoad` hook will run only once. As a result, the methods `createScene()` and `animate()` are called only once. Caching can be disabled; in that case, this method will fire every time the view is loaded, and the scene will be generated anew.

## Conclusion

Integrating Babylon.js into an Ionic application was easier than it seemed at first, once you get to know a couple of things about how Ionic/Angular 2 works. In fact, doing the same in an Ionic 1 app was easy too, but overall everything looks cleaner and more streamlined in the latest version.  
However, despite the improvements introduced to Angular, the overhead of having both Ionic and Babylon.js together might make performance a bit sluggish. Maybe it's not the best way to implement a pure 3D action-packed game.  
On the other hand, with Ionic you get things like a very simple way of handling the user interface, navigation, and storage out of the box. Not to mention that, through Cordova, it's easy to build apps for any mobile platform, so it might be the way to go for less demanding apps.

Finally, this is how the app looks running on an actual Android 6.0 device:

![](/img/how_to/ionic-angular/screenshot1.webp)
![](/img/how_to/ionic-angular/screenshot2.webp)
![](/img/how_to/ionic-angular/screenshot3.webp)



heyVR.io is a publishing platform for WebXR games, giving you access to a global audience of hundreds of thousands of players across multiple devices.

It offers a wide range of ready-to-use gameplay features to enhance your players' experience and enable you to start earning from your game through in-game content sales and advertisements.

## Useful Links
- [heyVR.io](https://heyvr.io)
- [heyVR Developer Area](https://developer.heyvr.io)
- [heyVR Documentation](https://docs.heyvr.io)

## Publishing Flow
heyVR.io is free to use, both for players and game developers.
Developers can create an account on the [Developer Area](https://developer.heyvr.io) and publish their games free of charge.
To read more about how the process works, please refer to the documentation on [Publishing Flow](https://docs.heyvr.io/en/developer-area/publish-a-game).

## SDK Implementation
While implementing the heyVR SDK in your games is completely optional, it's highly recommended that you take advantage of the SDK to further enhance your game and make use of features such as save games, leaderboards, inventory, etc. to provide a better user experience.

heyVR offers two different ways to integrate the SDK into your Babylon.js game. Depending on your development environment, you can proceed with either of them.

### 1) Built-in SDK
Every game submitted on heyVR has the option to enable the built-in SDK. This injects the SDK into the game at runtime. 

#### 1.1) Installation
The built-in SDK does not require any installation. 
To enable the built-in SDK, all you need to do is choose an SDK version for your build before uploading it. 
You can read more about this on the [documentation website](https://docs.heyvr.io/en/developer-area/publish-a-game#game-files).

> If you're using TypeScript, you can install the type definition package for the built-in SDK. Simply run:
> `npm i @heyvr/sdk-types -D` in your project's root directory.

#### 1.2) Basic Usage
Since the SDK loads asynchronously, it's important to make sure it's been loaded before making calls.
To do so, you can listen to the event that's dispatched by the SDK on load:

```javascript
const doStuff= () => 'Executed on SDK load'

window.heyVR ?
  doStuff() :
  window.addEventListener( 'heyVR.SDKLoaded', doStuff );
```

Once the SDK is loaded, all the methods are available via the `window.heyVR` object.
Here's a simple example of checking a user's authentication status:

```javascript
window.heyVR.user.isLoggedIn()
    .then( () => console.log( 'User is authenticated!' ) )
    .catch( () => console.warn( 'User is not logged in.' ) );
```

The SDK offers extensive methods and functionality, including a sandbox version that allows your game to use the SDK features locally. 
To read about how to use these features, please consult the [SDK documentation](https://docs.heyvr.io/game-development/sdk/gameplay).

### 2) NPM Package
You might be using NPM to manage your game's dependencies.
In that case, you can take advantage of the NPM package that heyVR provides. 

#### 2.1) Installation
You can install the package by running the following command in your project:

```bash
npm i @heyvr/sdk-gameplay
```
The package already includes the type definitions, in case you're using TypeScript.

#### 2.2) Basic Usage
The package's API is extremely similar to the built-in SDK. 
You can start by importing the pieces that you need. 
Let's replicate the previous example.

```javascript
import {User} from "@heyvr/sdk-gameplay/dist";

User.isLoggedIn()
    .then( () => console.log( 'User is authenticated!' ) )
    .catch( () => console.warn( 'User is not logged in.' ) );
```

The package also includes a sandbox version. 
For detailed instructions on how to use the package, check out the documentation on [NPM Package](https://docs.heyvr.io/en/game-development/sdk/gameplay/npm-package).


Babylon.js and Facebook Instant Games

Useful links

The process

Example