-container for each view and handle their visibility with javascript and css.
Let’s say we have 3 different views:
- Loading (Show some loading spinner)
- Menu (could have game options, menu, character selection)
- In-game (Show your in-game controller)
For each view we create a \
container with a unique **id** and a **class** “*view*”. The id helps us later to identify the view.
:::BlockQuote
// Controller html
\* | Send this as soon as the game is loaded and to register the controller. |
| `key` | *\* | Applied to the AirConsole.MessageKey expression |
| `message` | *\* | Applied to the AirConsole.Message expression |
**For example**
:::BlockQuote
\
\
:::
### *Export your game*
Export the game as a usual HTML5 game. AirConsole will request a`/screen.html`, which is why you should rename the`index.html`into`screen.html`. And of course, don't forget to create a`controller.html`in the same directory, which includes the functionality for the controllers.
As soon as your game is ready make a zip file of the whole directory (screen.html and controller.html in the root) and [publish](https://developers2.airconsole.com/publishing-your-game) it on AirConsole.
### *Example Pong Game walktrough*
To show you how all of this works together we will go through our example (very basic) pong game.
[Play example](https://www.airconsole.com/simulator/#!play=com.demo.construct)
Download Game: [https://github.com/AirConsole/airconsole-construct2/tree/master/example\_project](https://github.com/AirConsole/airconsole-construct2/tree/master/example_project)
**Event sheet**
**Trigger the GameReady Event**
As mentioned before, you **ALWAYS **have to trigger a Game ready event when the game has loaded, so that the controllers can tell us they are there.
**Store and assign device\_ids**
Every controller owns a paddle-sprite. Which means if controller-2 presses the up-button, then we want the right paddle to move up. That means we have to know which device belongs to which sprite. We can achieve this by creating global vars for each device the game will support (In pong two global vars, because we will just have two players in our game).
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/nrs3utCqLzHW6f5Mgplar_image.png" size="50" width="310" height="269" position="center" showCaption="false"}
If the first controller connects "On device join", then we assign the joined AirConsole.device\_id to the global DeviceID1\_Move. The second devices which connects get assigned to DeviceID2\_Move.
:::BlockQuote
**Device\_ids are random
**The value of DeviceID1 does not have to be always "1". The device with another device\_id (2, 3, 6, ...) could join before the device\_id 1.
:::
**Device joins, set the device\_id**
With the condition`AirConsole.onDeviceJoin`we can listen for events when a new device joins. If device joins, then assign the global variable device\_id to the value of`AirConsole.DeviceIDJoin`.
The tricky part here is to have the order of devices which join in mind. This means the first player who joins should be assigned to DeviceID1. The second player should be the DeviceID2. Consequently we also have to check if the DeviceID1 already has a value. If yes, we check if the DeviceID2 var has none and if that is true we assign the device\_id.
**Move paddles**
To move our paddles we create another two global vars called`DeviceID1_Move`and`DeviceID2_Move`. Each of them can have one of the 3 values:
- -1 = Move up
- 0 = Stop
- 1 = Move down
**Send a message from a controller to the screen**
Our controller will only consist of two buttons: move up and move down. If we press one of this buttons we will send a message to the game (screen) and the corresponding paddle-sprite object should move - or if we release a button it should stop.
Our`controller.html`contains the following code:
```html
```
Now the game has to listen to a message which has the content "up", "down" or "stop".
In our event sheet, you can see two events of "On receive message data". They were added by the `AirConsole.onMessage` event like this:
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/3wpOSrlwpIa5WHC1U4MNd_image.png" size="80" width="586" height="240" position="center" showCaption="false"}
To sum it up:
**IF **message == "up" AND device\_id matches the value of DeviceID1 **THEN **we set the variable`DeviceID1_Move`to -1, which means our sprite moves down.
The same happens with message == 'stop' or message == 'down'.
### *External Tutorials*
- [HowTo: Construct2 and AirConsole](https://laurentchervet.wordpress.com/2016/11/30/howto-construct2-and-airconsole/)
- [Construct 2 and AirConsole](https://www.scirra.com/tutorials/9414/construct-2-and-airconsole)
- [Little expression guide](https://www.scirra.com/tutorials/9415/airconsole-little-expression-guide)
### *Troubleshooting*
**Game won't work because of Javascript errors**
If you get any javascript errors try to export your game without checking the "Minify script" checkbox.
[title] AirConsole Hero & Revenue
[path] Generate income with your game/
### *Monetization Basics*
AirConsole and its developers earn money through a paid service called [AirConsole Hero](https://www.airconsole.com/hero). Users can try a limited version of AirConsole for free, or pay for the full version.
In the free version, there are “breaks” where we ask the user to wait or show them the benefits of getting a subscription. There are no third party advertisements on AirConsole and therefore no ad revenue.
The exact features of the free and paid versions are subject to changes. We frequently and extensively A-B-test the exact offering in order to find the right balance between what our users like and what benefits the developers.
### *Revenue Share for Developers*
Every user’s subscription revenue is split among the games that the user played after the shares for App Stores and AirConsole Infrastructure have been deducted. See our exact legal terms [here](https://developers2.airconsole.com/revenue-page).
:::BlockQuote
**Fun Fact:** Statistically, every Hero User on AirConsole has a favorite game in which they spend about half their total playtime.
:::
This is an example of how gross revenue is distributed on AirConsole:
## *AirConsole Ad Break Implementation*
AirConsole does not show third party ads, but there are breaks in which we show advertisements for [AirConsole Hero](https://www.airconsole.com/hero).
When an AirConsole ad is shown, it will be displayed on all connected devices - the screen as well as on all controllers. AirConsole is taking care of everything concerning displaying the ads.
**Game developers must specifically demand to show an ad by calling an API method (see "API Methods" below).**
### *API Methods*
:::BlockQuote
You need the API version 1.4.0 or higher!
:::
**showAd()**
The`showAd()`method requests that AirConsole shows a multiscreen advertisment. This method can only be called by the AirConsole screen.
**onAdShow()**
Calling`showAd()`does not necessarily mean that an ad will be shown. However, if an ad is shown, the`onAdShow()`method is called. You can use this method to pause your game and mute all sounds.
**onAdComplete(ad\_was\_shown)**
This method will be called if an ad was closed (whether it was shown or not). Use the`ad_was_shown`param to find out if and ad was shown.
### *Javascript example*
:::BlockQuote
// Our airconsole instance
var airconsole = new AirConsole();
// The perfect moment has come to show an ad:
airconsole.showAd();
// Overwrite the onAdShow method
airconsole.onAdShow = function() \{
// Pause the game and mute all sounds
game.pause();
game.sound.mute();
};
// Overwrite the onAdComplete mthod
airconsole.onAdComplete = function(ad\_was\_shown) \{
// Unpause the game and play sounds again if ad was shown
if (ad\_was\_shown) \{
game.unpause();
game.sound.play('prodigy');
}
};
:::
## Any Questions?
Head over to the [Help Page](https://developers2.airconsole.com/faq-help) for answers to frequently asked questions about AirConsole Hero, ads and revenue shares.
[title] Persisting Player Data
[path] AirConsole Games Features/Improving your game engage/
## *What is the Persistent Storage API?*
[The Persistent Storage API](https://airconsole.github.io/airconsole-api/AirConsole-Persistent_Data.html) enables your game to store data on behalf of your players to continue anywhere, anytime.
You can think of [the Persistent Storage API](https://airconsole.github.io/airconsole-api/AirConsole-Persistent_Data.html) as AirConsoles version of a **save game system that stores the data for players** but with additional possibilities towards unique game designs that go well beyond traditional savegame capabilities.
## *Before you get started*
There are different ways to implement persistent data storage for your game depending on your game design.
This gives you unique possibilities to use persistent data as a gameplay feature in your game design.
### *1. Which players need to store and request part of the game state*
- You can store and request data for every player in the game and selectively decide what to apply when and where (see Working with data from multiple connected players below).
- You can store and request data for the player driving the session (see Persisting data only for the controlling player below).
:::BlockQuote
When working with the Persistent Storage API, keep in mind that the storage limit is **1MB per UID per game!**
:::
### *2. How do you want to use and persist the data in your game*
- Decide at what points you want to store the persistent data.
- Decide what happens when the owner of the persistent data leaves:
\- Will future updates to the persistent data be stored for the leaving owner of the current game state?
\- If not, will the players be able to continue but the general game state progress will no longer be persisteted, only player specific personal progress?
\- Or do you use the flexible capabilities to offer a unique approach?
- Remember the players uids for which persistent data was requested for the lifetime of the usage of this game state to persist it for the correct player again.
## *Working with data from multiple connected players*
AirConsoles Persistent Storage API nature as key - value based store gives you unique flexibility in deciding which controller contributes what information to the game worlds state
This allows you to request and store data for multiple players in the same game and enable an optimal experience by combining the data in ways providing the best game experience.
**Example**
- Level unlocks are taken from the device with the most advanced state and to this device this part of the state is persisted.
- **example key: **level\_progress
- But every player can have their own unlocks (characters, gadgets, skins, abilities, features, ...) which are stored based on their uid.
- **example key: **player\_progress
In this example, the game requests and stores the progress of the world state, global quests or content unlocks in **level\_progress** while storing personalized player progress information in **player\_progress**.
When the players connect the game would request **level\_progress **for all players and select the most advanced state. The game would also request **player\_progress**for all players and apply it to the corresponding player to unlock player specific aspects.
Such a hybrid achives the best results, if the corresponding game experiennce and game progression is optimized for AirConsole early in the game design and playtesting process, allowing you to create an experience your players want to come back to often and [increasing your income](https://developers2.airconsole.com/airconsole-hero-and-revenue).
### *Persisting data only for the controlling player*
If you are working with the controlling player (using `GetMasterControllerDeviceId()`) to load the game state, then you need to consider the different cases arising from this Id changing as players join or leave the game.
:::BlockQuote
`GetMasterControllerDeviceId()` can change during the runtime of the game due to connects / disconnects and you don't want to (re)load or store the data for the wrong player.
:::
**Examples**
- If a premium user connects to a game with non-premium users only, then the master device will change to the premium device.
- If the master device disconnects a different connected device will become master.
Simply storing the persistent data to the now current master device would duplicate the state of the original players data to the new player while **not updating the progress for the original player**! The game needs to remember the UID of the device for which the game state has been requested and used.
### *Important considerations when not providing a UID to storePersistentData / requestPersistentData*
:::BlockQuote
From AirConsole API 1.9.0 and Unity Plugin 2.5.0 onwards, the possibility to call StorePersistentData / RequestPersistentData without providing a UID will be removed.
:::
If you are not providing a UID to StorePersistentData / RequestPersistentData, then the data will be stored for the device that calls the function.
This is a convenience functionality when using it the Persistent Storage API on your controller. You must not rely on this convencience when using it on the screen!
The screen does not have a persistent uid (incognito mode, security features, plugins). Due to this, the screen commonly is unable to restore persistent data reliably (browser and car in particular)!
## *Persisting data in web games*
The web examples assume that you have already [set up your game similar to the pong example](https://developers2.airconsole.com/pong-example) and have an object like `var airconsole = new AirConsole();`.
### *Storing Persistent Data*
- Implement function \`handlePersistentDataStored\` that does something based on the UID, for example a visual confirmation.
- Register an event listener to `airconsole.onPersistentDataStored = handlePersistentDataStored;`
Alternatively you can also directly declare the function`airconsole.onPersistentDataStored = function(uid) { // do something based on the uid };`
- After onReady was invoked, call
:::BlockQuote
string uid = airconsole.getUID(airconsole.getDeviceId());
if(uid) \{
airconsole.storePersistentData("dataKey", \{ keyA: "data a", keyB: "data b" }, uid);
} else \{
console.error("master controller has no UID yet, was onReady really invoked?");
}
:::
### *Retrieving Persistent Data*
- Implement function \`handlePersistentDataLoaded\` that processes the loaded persistent data.
- Register an event listener to `airconsole.onPersistentDataLoaded = handlePersistentDataLoaded;`
Alternatively you can also directly declare the function`airconsole.onPersistentDataLoaded = function(data) { // do something now with the data };`
- After onReady was invoked, call something like
:::BlockQuote
var controllers = airconsole.getControllerDeviceIds();
var uids = controllers.map(it => airconsole.getUID(it)) || \[];
if(uids.length > 0) \{
airconsole.requestPersistentData(uids);
}
:::
## *Persisting data in Unity games*
Please see [ExampleBasicLogic.cs](https://github.com/AirConsole/airconsole-unity-plugin/blob/master/Assets/AirConsole/examples/basic/ExampleBasicLogic.cs) for an example implementation.
### *Storing Persistent Data*
- Implement an event handler \`HandlePersistentDataStored\` that processes the received persistent data.
- Register an event listener to `AirConsole.instance.onPersistentDataStored += HandlePersistentDataStored;`
- After onReady was invoked, call
:::BlockQuote
string uuid = AirConsole.instance.GetUID(AirConsole.instance.GetDeviceId());
if(!string.IsNullOrEmpty(uuid)) \{
JObject exampleData = new JObject();
exampleData.Add ("test", "data");
AirConsole.instance.StorePersistentData("example\_data", exampleData, uid);
} else \{
Debug.Error("MasterController has no UID yet, was onReady really invoked?");
}
:::
### *Retrieving Persistent Data*
- Implement an event handler \`HandlePersistentDataLoaded\` that processes the received persistent data.
- Register an event listener to `AirConsole.instance.onPersistentDataLoaded += HandlePersistentDataLoaded;`
- After onReady was invoked, call something like
:::BlockQuote
List\ uids = new List\(AirConsole.instance.GetControllerDeviceIds()
.Select(id => AirConsole.instance.GetUID(id))
.Where(id => !string.IsNullOrEmpty(id)));
if(uids.Count > 0) \{
AirConsole.instance.RequestPersistentData(uids);
}
:::
## *Persisting data does not work, I have the following problem:*
### *When reopening the game after storing the state, I can not get the stored state*
- The UIDs in the simulator are not stable. You will need to connect a real device to test this. See the guides [How to test your game](https://developers2.airconsole.com/testing-your-game) and [Learn how to connect Phones in Unity](https://developers2.airconsole.com/testing-with-your-phone) guides for more information.
- You can not store or retrieve a persistent state before the event [onReady](https://airconsole.github.io/airconsole-api/) was invoked.
In Unity this would throw the [AirConsole.NotReadyException.](https://github.com/AirConsole/airconsole-unity-plugin/blob/b1c86de4fb1797f81d654051e6d61cc8c310b786/Assets/AirConsole/scripts/AirConsole.cs#L939)
[title] AirConsole Unity Plugin
[path] Games in Unity/
The Unity-Plugin is a C# wrapper for the AirConsole Javascript API. With the plugin, Unity serves you the needed screen.html file inside the Editor and creates a screen.html file after an WebGL build export.
:::BlockQuote
**Note:** The plugin comes with an embedded webserver / websocket-server for the communication between the AirConsole backend and the Unity-Editor. You don't need to install any other webserver or services. The plugin was tested with Unity 5.1 and above for the Windows and OSX-Editor.
:::
### *Known issues and solutions*
Before you start installing the plugin, be aware that because we support such a wide range of Unity versions, some Unity versions have some known issues when importing the plugin or when building for a specific platform. Below you will find the list of known issues and their fixes:
| Affected versions | Description | Solution |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unity 2022+ | After trying to build for Android TV you may get this error:
`mainTemplate.gradle is using the old aaptOptions noCompress property definition does not include types defined in unityStreamingAssets constant.` | Edit **Assets/Plugins/Android/mainTemplate.gradle** and **launcherTemplate.gradle** to add/replace the **aaptOptions** section to the following:
:::BlockQuote aaptOptions \{ noCompress = \['.ress', '.resource', '.obb'] + unityStreamingAssets.tokenize(', ') ignoreAssetsPattern = "!.svn:!.git:!.ds\_store:!\*.scc:.\*:!CVS:!thumbs.db:!picasa.ini:!\*\~" }\*\*PACKAGING\_OPTIONS\*\* :::
Check [Unity support](https://developers2.airconsole.com/faq-help) for more details. | | Unity 2021+ | After importing the AirConsole plugin into Unity you may get this error:
`Multiple precompiled assemblies with the same name Newtonsoft.Json.dll included on the current platform. [...]` | Delete the following plugin file (It is now included in Unity directly and is not needed in newer Unity versions): `Assets/AirConsole/plugins/Newtonsoft.Json.dll` | | Unity 2018.3 | After importing the AirConsole plugin into Unity you may get:
`The type or namespace name 'ILGenerator' could not be found (are you missing a using directive or an assembly reference?) and The type or namespace name 'DynamicMethod' could not be found (are you missing a using directive or an assembly reference?)` | Set the **API Compatibility Level** to **.NET 4.x** in the Player Settings of your selected Platform.
Check [AirConsole FAQ](https://developers2.airconsole.com/faq-help) for more details. | ### *Download* **Download from Github** Download the newest AirConsole-Unity-Plugin on our [GitHub repository](http://github.com/AirConsole/airconsole-unity-plugin). You can find the newest ".unitypackage" file in the "Builds" folder. **Download from Assetstore** [Unity Store](https://assetstore.unity.com/packages/tools/game-toolkits/airconsole-42776) ### *Video Tutorial* Learn the basics of how to make an AirConsole game in Unity in just 4 minutes. ::embed[]{url="https://www.youtube.com/embed/omKvqRZbfY8"} ### *Installation* To import the plugin, click on `Assets > Import Package -> Custom Package` and choose the downloaded `*.unitypackage` file. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/DLJWExYYGEHZ5ObQU96KQ_image.png" size="80" width="456" height="246" position="center" showCaption="false"} Make sure that all assets are selected and click on "Import". ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/X8uCcFWbrtCI_jfMYyZ27_image.png" size="70" width="366" height="384" position="center" showCaption="false"} **Instantiate AirConsole object** To set up the communication inside a scene, you have to instantiate the AirConsole object. In the Hierarchy window, click on `Create > Create Other > AirConsole`. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/DoLR-NMNEqNINm-PjJUhD_image.png" size="60" width="350" height="270" position="center" showCaption="false"} The AirConsole object offers you the following options: | Option | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Browser Start Mode | As soon as you press the “Play” button in Unity, your default browser will open the AirConsole simulator in the chosen mode. | | Controller Html | Link your controller.html file to this inspector variable, otherwise you can’t start the AirConsole simulator and you will get an error message. (Note: if your controller needs additional files like images or fonts, put them in the folder “Assets/WebGLTemplates/AirConsole”) | | Auto Scale Canvas | This option is enabled by default and scales your final webgl canvas automatically to the window size. The aspect ratio will be kept during the scaling. | ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/78kUQccxPrshav9aLnUWq_image.png" size="60" width="321" height="283" position="center" showCaption="false"} :::BlockQuote **Note:** the AirConsole object survives a scene change by default, so you don’t have to worry about the connections and device states when changing a level inside Unity). ::: ### *Quick example* Here is a simple example where the controller sends "How are you?" to the screen and the screen replies with "Full of pixels!" Include the AirConsole Javascript API in your controller.html file: :::BlockQuote \ ::: **/controller.html** :::BlockQuote var air\_console = new AirConsole(); air\_console.message(AirConsole.SCREEN, "How are you?"); ::: **Unity** To be able to receive a message in Unity, create a new Unity MonoBehaviour class and include these namespaces: :::BlockQuote using NDream.AirConsole; using Newtonsoft.Json.Linq; ::: Add an event handler in the Start method of the MonoBehaviour class: :::BlockQuote void Start() \{ AirConsole.instance.onMessage += OnMessage; } void OnMessage(int from, JToken data) \{ AirConsole.instance.Message(from, "Full of pixels!"); } ::: :::BlockQuote **Note:** make sure to only send JSON supported data types between the controller.html file and Unity. The AirConsole-Unity-Plugin exchanges data via a modifed version of the popular JSON.NET library. The plugin delivers received data inside Unity as JToken objects. You can check the documentation of JSON.NET here: [http://www.newtonsoft.com/json/help/html/N\_Newtonsoft\_Json\_Linq.htm](http://www.newtonsoft.com/json/help/html/N_Newtonsoft_Json_Linq.htm) ::: ### *JToken parse example* When you send an object like this one on the controller.html side: :::BlockQuote // Javascript var message = \{ 'action': 'move', 'info': \{ 'amount': 5, 'torque': 234.8 } }; air\_console.message(AirConsole.SCREEN, message); ::: You can parse the object in Unity like this: :::BlockQuote // C# void OnMessage(int from, JToken data) \{ string action = (string) data\["action"]; int amount = (int) data\["info"]\["amount"]; float torque = (float) data\["info"]\["torque"]; } ::: :::BlockQuote Note: when you receive JToken data in Unity, you have to cast the object to get the right data type. ::: To send the same data from Unity you can use dynamic vars: :::BlockQuote // C# var message = new \{ action = "move", info = new \{ amount = 5, torque = 234.8f } }; AirConsole.instance.Message(device\_id, message); ::: ### *Test your game* To test your game, just hit the “Play” button inside the Unity-Editor. If you want to test the final WebGL-Build, choose the right AirConsole Template in the PlayerSettings first (For Unity versions 2020 and up choose the **AirConsole-2020** template, for previous Unity versions choose the **AirConsole** template): ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/0A4IF7aN04TvX6GBCPwQm_image.png" size="80" width="400" height="379" position="center" showCaption="false"} Now you can export your Unity project in the Build-Settings (choose “Build” instead of the “Build and run” button). As soon as your build is exported, the button “Open Exported Port” on the AirConsole object in your scene will appear. By pressing this button, the AirConsole simulator will start with your final build. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/rbRSVhPH6n-smRLYYvL54_image.png" size="50" width="250" height="178" position="center" showCaption="false"} :::BlockQuote **Note:** the "Open Exported Port" button is only available as long as you don’t change the last target location of your exported build. ::: :::BlockQuote **Note:** AirConsole uses the Unity WebGL Custom Progress Bar by Alexander Ocias for WebGL builds: https\://ocias.com/ ::: :::BlockQuote **IMPORTANT:** before you can build the WebGL port, you have to start the game at least once in the Editor to generate all important metafiles for the final build. ::: ### *Examples* - AirConsole/Examples/Basic/basic.scene: In this example all possible API functions are listed & used. - AirConsole/Examples/Pong/pong.scene: This example contains a simple pong game with a specific controller. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/uOouAd15U-Yv5oP61kD32_image.png" size="60" width="895" height="557" position="center" showCaption="false"} ### *Settings* You can open the settings window by clicking on the "Settings" button on the inspector of the AirConsole object or by navigating over the menu bar `AirConsole > Settings`. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/qXF2nNM3Genls_VRzoHra_image.png" size="60" width="417" height="147" position="center" showCaption="false"} In the "Settings" window, the ports for the internal web socket and web server can be changed, should the default ports already be occupied. :::BlockQuote **Note:** These ports are only needed for the AirConsole simulator inside the Unity Editor. The final WebGL port will not use any of these ports. ::: You can stop and restart the internal web server in case the AirConsole simulator isn't working properly. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/rEp6aJltjg85SAZsIlk6E_image.png" size="60" width="336" height="278" position="center" showCaption="false"} ### *AirConsole, Unity and AndroidTV* AirConsole also provides an AndroidTV app, so that user can play your games also on a smart-tv. Please read the ["AirConsole Unity on AndroidTv"](https://developers2.airconsole.com/unity-game-on-android-tv) documentation to adapt your game for AndroidTV. [title] Creating and publishing your game [path] AirConsole Games Features/ [title] Archive [path] / [title] Pong Example [path] Example games in web / unity/ In this example you will learn how to use the AirConsole API to communicate between a screen and controllers in a simple Pong-game. You can play the game here: [https://www.airconsole.com/#https://game.airconsole.com/com.airconsole.testpong.cdn.airconsole.com/2024-02-14-14-52-40/](https://www.airconsole.com/#https://game.airconsole.com/com.airconsole.testpong.cdn.airconsole.com/2024-02-14-14-52-40/) to get a better idea about what we are gonna talk about :)  You can check the game code here: [View code.](https://github.com/AirConsole/games-pong) To download the game, use the following link: [Download pong.zip](https://github.com/AirConsole/games-pong/archive/master.zip) ### *Basic message exchange between a screen and controllers:* AirConsole and its API makes it very easy for game developers to build games, which can be controlled by a smartphone - instead of e.g. a keyboard or a mouse. The whole communication can be pretty much summed up with two methods of the API:`onMessage()`and`message()`. All devices (screen and controllers) share the same API - thus there are (almost) no controller or screen specific methods for the communication. In the following we will explain you in detail how players can control their paddles in a simple, but fun game like Pong.  ### */screen.html* Start a local webserver of your choice and create a `/screen.html` in the root directory. :::BlockQuote You can check the code of the whole `screen.html` in [this repo](https://github.com/AirConsole/games-pong/blob/master/screen.html) ::: Include the AirConsole API file: | | \ | | - | --------------------------------------------------------------------------------------------------------- | Our game will run on a canvas element, have a score and a "wait message". As soon as the document is ready, we call the`init()`function. ```html
```
The`init()`function sets up our canvas, creates player objects and a ball object and most importantly calls the`setupConsole()`function.
In the`setupConsole()`we construct the`AirConsole`object and assign it to the`airconsole`variable.
```javascript
//* Sets up the communication to game pads.* /
function setupConsole() {
airconsole = new AirConsole();
airconsole.onConnect = function (device_id) {
checkTwoPlayers();
};
airconsole.onDisconnect = function (device_id) {
var player = airconsole.convertDeviceIdToPlayerNumber(device_id);
if (player != undefined) {
// Player that was in game left the game.
// Setting active players to length 0.
airconsole.setActivePlayers(0);
}
checkTwoPlayers();
};
airconsole.onMessage = function (device_id, data) {
var player = airconsole.convertDeviceIdToPlayerNumber(device_id);
if (player != undefined && data.move !== undefined) {
paddles[player].move.y = data.move;
}
};
}
```
After that, we overwrite the`onMessage()`,`onConnect()`and the`onDisconnect()`methods, so we can use them for our needs of the game.
`onMessage(device_id, data)`
The`onMessage(device_id, data)`method listens for all incoming messages. In the screen-context it means that it receives all data which the controllers send. In our pong-game, whenever a player presses the up or down button on its device, the screen receives a messages and that is handled in the`onMessage(device_id, data)`method. The`device_id`param is the id of the device which sent the message (E.g.*2*). The`data`param is an object and holds custom data, like`{ move: 50 }`.
`onConnect(device_id)`
The`onConnect()`method gets called when a device connects.
`onDisconnect(device_id)`
Whenever a device disconnects`onDisconnect()`gets called.
`setActivePlayers(max_players)`
The`setActivePlayers(max_players)`was introduced to avoid confusion with device ids. You can use it as a helper method which tells which devices should get a player number. It basically maps your controller devices to a zero-based player number.
**Set active players**
When a player connects and we have at least two controllers connected, we call`setActivePlayers(2)`method in the`checkTwoPlayers()`function to set the first two devices to active players and start the game.
```javascript
// Only update if the game didn't have active players.
if (active_players.length == 0) {
if (connected_controllers.length >= 2) {
// Enough controller devices connected to start the game.
// Setting the first 2 controllers to active players.
airconsole.setActivePlayers(2);
resetBall(50, 0);
score = [0, 0];
score_el.innerHTML = score.join(":");
document.getElementById("wait").innerHTML = "";
} else if (connected_controllers.length == 1) {
document.getElementById("wait").innerHTML = "Need 1 more player!";
resetBall(0, 0);
} else if (connected_controllers.length == 0) {
document.getElementById("wait").innerHTML = "Need 2 more players!";
resetBall(0, 0);
}
}
```
Otherwise we just display that more players are needed to play the game.
**Set no active players**
When an active player disconnects and there are not enough active players left we want again to display "*It's a 2 player game!*" on the controller and on the screen "*Need X more player!*". When the leaving player was active in the game, we set all active players to 0, before calling again the`checkTwoPlayers()`function.
`message(device_id, data)`
The message method sends a message to another device. In our pong game, whenever a player wins, we send a message to this device and let the device vibrate (if supported).
```javascript
/**
* Sends a message to the device that it should vibrate;
*/
function vibrate(player) {
airconsole.message(
airconsole.convertPlayerNumberToDeviceId(player),
{ vibrate: 1000 })
}
```
How that works is explained below in the controller.html.
Thats basically all AirConsole relevant code of the`screen.html`. The rest of the code is only the game itself, which we won't cover here.
### */controller.html*
Whenever someone requests an AirConsole game on a mobile device, the `/controller.html` will be delivered.
Now create a`/controller.html`and include the same AirConsole API file as we did in the`/screen.html`:
```html
```
As in the`/screen.html`, we also create an`AirConsole()`object and initialize it with the options`{"orientation": "portrait"}`.
```javascript
/**
* Sets up the communication to game pads.
*/
function setupConsole() {
airconsole = new AirConsole();
airconsole.onConnect = function (device_id) {
checkTwoPlayers();
};
airconsole.onDisconnect = function (device_id) {
var player = airconsole.convertDeviceIdToPlayerNumber(device_id);
if (player != undefined) {
// Player that was in game left the game.
// Setting active players to length 0.
airconsole.setActivePlayers(0);
}
checkTwoPlayers();
};
airconsole.onMessage = function (device_id, data) {
var player = airconsole.convertDeviceIdToPlayerNumber(device_id);
if (player != undefined && data.move !== undefined) {
paddles[player].move.y = data.move;
}
};
}
```
We again overwrite the`onMessage()`method and also make use of the`onActivePlayersChange()`method.
`onMessage(device_id, data)`
This time we listen for all messages, which were sent from the screen. As already mentioned, whenever a player wins, the device of the player should vibrate. The`onMessage(device_id, data)`method receives now a message from the screen (AirConsole.SCREEN) and with the data`{ vibrate: 1000 }`.
`onActivePlayersChange(player_number)`
Whenever the screen calls`setActivePlayers()`, the`onActivePlayersChange(player_number)`method will be called on the controllers, which are set to active. Use this method to tell your controller it is an active device in your game. In our Pong game we use the passed`player_number`to tell if the player is the left or the right paddle. The`player_number`starts at 0, so that the first player will receive *0 *and the second *1 *as the`player_number`param.
**Sending a move event from controller to the screen**
To tell the screen that a player wants to move his paddle up or down we use the`airconsole.message`method.
```javascript
/**
* Tells the screen to move the paddle of this player.
* @param amount
*/
function move(amount) {
airconsole.message(AirConsole.SCREEN, {move: amount})
}
```
On an`ontouchstart`event the move function will be called, which sends a message to the screen. On a`ontouchend`we again call the move function with a value of 0 and again send a message to the screen.
```html
```
That's it! That's all you need to let your screen and controllers communicate!
Learn more about [how to test your game](https://developers2.airconsole.com/testing-your-game) locally or on your webhost.
[title] Handling players connecting
[path] AirConsole Games Features/Connect to your game/
:::BlockQuote
Prerequisites: API 1.9.0 or Unity Plugin 2.5.0 or higher
:::
## *What is Player Silencing?*
Player Silencing allows you to control what happens when a new player joins the game while the game is in an active game round without additional game code.
It ensures that newly joined players are not known to the game until the game round is finished.
:::BlockQuote
Player Silencing is by default not enabled! If you update your game to use the new API it will not impact your game until you decide to enable it.
:::
### *Comparison*
**With player silencing disabled: **New players will be added to your game as soon as they connect to the game, invoking onConnect and requiring your game to manually handle and ignore messages as well as visualizing the correct state on the game controller.
**With player silencing enabled: **New players will be informed that they need to wait for the game round to finish on their controller.
Your screen and controller will only invoke onConnect after the game round is no longer active, which is controlled by your screen calling setActivePlayers(0).
## *How does Player Silencing work?*
Player Silencing works by keeping track of new devices connecting while the game is in an active game round.
The onConnect event of such devices will be delayed until the game round is no longer active.
Once the active game round is no longer active, all waiting onConnect events will be executed, **unless **the device has disconnected already.
## *Who is Player Silencing for?*
Player Silencing allows you to be sure that after a game round is started, newly joining players are requested to wait until the game round is finished. This does not require additional game code to prevent an impact to the game experience or the game rounds outcome.
## *When not to use Player Silencing?*
If your game is designed to allow players to join at any time, then player silencing is not for you.
## *How to guides*
### *How to: **Enable Player Silencing***
To enable and use player silencing, all you need to do is to configure AirConsole to use it on the screen.
- **Web Setup:** Include `silence_inactive_players: true` when calling the constructor:
:::BlockQuote
var airconsole = new AirConsole(\{ silence\_inactive\_players: true });
:::
- **Unity Setup: **Enable the checkbox`Silence Players`on the AirConsole component in the scene.
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-m8sn7HURyoTysiDTrnB7p-20250303-115802.jpg" size="60" width="443" height="364" position="center" showCaption="false"}
### *How to: **Use Player Silencing***
After enabling playing silence, you can control when new players can join using .
Once player silencing is enabled, during any phase of your game where you to anything but 0, new joining players will be silenced.
After is called, the game will be in a waiting state and new players will be added to the game.
Players that are already waiting to join will now be added and onConnect is called for them.
## *The example pong game explained*
We will use the [Pong Example Game](https://github.com/AirConsole/games-pong), to explain player silencing and how it applies :
1. We initialize AirConsole including the`silence_inactive_players: true`flag when creating the AirConsole object, signaling that new players to automatically wait during active gameplay.
2. The game is initially in the LOBBY state, waiting for players.
3. Once 2 devices are connected and the master device starts the game, the game switches to the GAME state.
- Entering the GAME state executes `setActivePlayers(2)`, starting the active Pong gameplay.
- If any additional device connects while in the GAME state, the new device will be silenced and the controller will inform the user with the following screen.
4. After the game ends, the screen enters the LOBBY state, which calls `setActivePlayers(0)` to mark no controller as active player.
- After setActivePlayers(0) all players that joined while the GAME was ongoing will now join the game, showing the currently active controller
We provide a full example implementation as a 2 player Pong game with dedicated game states.
### *Game States*
- **LOBBY**: New players automatically join the pre-game waiting state until the main controller decides its time to start.
In this state, setActivePlayers(0) was called.
- **GAME: **In this state, new players need to wait to join (they are **silenced**).
In this state, setActivePlayers(2) was called.
You can find this example Pong Game at [https://github.com/AirConsole/games-pong](https://github.com/AirConsole/games-pong)
[title] AirConsole JS API
[path] Reference/
[title] Explanation
[path] /
[title] Best Practices for Web Games on AirConsole
[path] /
This guide provides developers with essential **guidelines and standards** for building performant and reliable WebGL games for AirConsole. The document applies to **desktop, mobile, and automotive** devices. Games are expected to **scale automatically** across platforms — there are no separate versions.
***
## 🎯 Goals
- Ensure compliance with [AirConsole Checklist](docId\:IEdkpmfJl8JQS3UOIFhmg).
- Provide **performance and resource usage best practices**.
- Deliver games that are **robust, safe, and enjoyable** everywhere.
***
## ✅ Technical Requirements
### General Requirements
- **Compatibility:** Game must run correctly on **Chrome 61+** (baseline automotive embedded Chromium).
- **Loading Performance:** Main menu loads in ≤30s under 20mbit up/down with 100ms latency.
- **Frame Rate:** Game must achieve **≥30 FPS** consistently across all supported platforms.
- **Error Handling:** No uncaught exceptions in console during normal play.
:::hint{type="success"}
Always validate performance under throttled conditions, not just on your development machine.
:::
***
## 🚀 General Performance Best Practices
### Rendering — Lights, Shaders & Materials
Automotive graphics chip are heavily pixel throughput limited (up to 20x lower than current generation mobiles)
- **Prefer baked lighting** for static geometry; reserve **1–2 realtime dynamic lights** for hero objects only. Use **lightmaps** (directional if supported) or **spherical harmonics light probes** for dynamic objects.
- **Shadow strategy:** If shadows are required, use **single sun/dir light shadows** with **resolution ≤1024** and **cascade count ≤2**; disable soft shadows on low-end. Avoid per-pixel point/spot shadows.
- **Shader precision:** Default to `mediump` in fragment shaders; use `highp` **only** where artifacts are visible (normals/IBL). In vertex shaders, `highp` is generally fine.
- **Branching & loops:** Avoid dynamic branching and unbounded loops in fragment shaders; prefer **static **`#define`**-based variants** and precomputed LUTs (BRDF, fog, tone map curves).
- **Material variants:** Limit material permutations; prefer a **single uber-shader** with compile-time feature flags, or a **small set** of well-curated variants.
- **Specular/IBL:** Use **image-based lighting** with prefiltered environment maps (mip chain as roughness levels). Keep environment cubemap at **≤256 px face** (≤128 on low-end / automotive).
- **Normals & tangents:** Use **octahedral/BC5**-style normal encodings when possible; otherwise compress normals to two channels. Recompute tangents offline.
- **PBR pragmatism:** Avoid it unless it provides significant value. If used, use **metalness/roughness** workflow; clamp roughness to **\[0.04, 0.96]** to avoid fireflies.
- **Tone mapping & gamma:** Avoid HDR and tonemapping unless it provides significant value. If used work in **linear space** with sRGB textures; apply **ACES (approx)** or filmic tone mapping **once** at the end of the pipeline.
- **Transparency:** Sort back-to-front; minimize overdraw. Prefer **alpha test / dithered cutout** over expensive blended layers when possible.
- **Post-processing budget:** Keep to **≤1–2 passes**. Prefer **FXAA** over MSAA;
- Ensure mobile optimised shaders are used when running on cars
- **Instancing & batching:** Batch small meshes and **GPU-instance** repeated props to keep draw calls **\< 200**.
- **Overdraw control:** Keep fill rate low; avoid full-screen particles and parallax layers. Use **depth pre-pass only if profiling proves a net win**.
- **Texture sampling:** Prefer **trilinear with mipmaps**; add **anisotropy 2–4x** for ground textures. Avoid manual LOD biasing unless necessary.
- **Texture lookups:** For wide support try to have \<= 4 texture l
- **Skinned meshes:** Limit bones per draw (≤50); update skinning on GPU where available; pool and reuse skeletons.
- **GL Extensions**: The available GL extensions vary widely between platforms, in particular in cars -> Ensure you only use features that are provded by the GL extensions
- If that is technically not feasible -> Ensure that you support WebGL1
:::hint{type="success"}
Baked/global lighting + minimal dynamic lights yields the biggest visual/performance win for WebGL across all devices.
:::
### Assets — Formats, Sizes & Streaming
- **Texture formats:** Ship GPU-compressed textures: **ASTC** (best), **ETC2** (fallback AndroidTV) and **DXT** for desktop.
- Where available use ** Basis** or **KTX2** which are optimal for automotive and desktop.
- **Texture sizes:** Target **max 2048²** (automotive) / 4096² (desktop high). Generate full mip chains; avoid NPOT when possible to keep mips efficient.
- **Atlasing:** Use **sprite/texture atlases** to reduce binds; group by sampler/state.
- **Streaming:** Stream large assets (music, video) and **lazy-load** level content; gate heavy loads behind user interactions.
- **Audio:** Stream BGM; keep SFX short and pooled. Avoid decoding large audio during gameplay.
### Memory Management
- Cap texture memory per platform (\~256MB for low-end & automotive, higher for desktop).
- Implement **lazy asset loading**: load resources only when needed.
- Use **asset eviction strategies**: unload unused textures/models/audio.
- Monitor garbage collection behavior; avoid excessive object churn in critical loops.
:::hint{type="warning"}
Run memory profiling sessions at least once per major milestone — many issues only appear under long play sessions.
:::
### Particles & VFX
- Keep particle systems **GPU-cheap**: billboard quads, batched draws, avoid complex fragment work.
- Prefer **CPU-updated, GPU-drawn** pools
- Avoid allocating particle and VFX systems during gameplay
- Cull off-screen particle and VFX systems early.
- For smoke/fire, use [flipbook textures / texture sheets](https://vfxdoc.readthedocs.io/en/latest/textures/flipbooks/) at half/quarter-res
- Limit additive blending areas using tight sprite meshes where possible
### Input & Responsiveness
- Ensure **input latency \<100ms** under normal conditions.
- Support **AirConsole's input integration** only.
- Design for **scalable UI layouts** — support resizing and different aspect ratios.
- **If your game's input is time sensitive: **Use lag compensation approaches and timestamps for controller -> screen messages for the best game experience.
### Audio
- Use **compressed audio formats** (AAC low, OGG) for background music.
- Keep audio memory low by streaming long tracks.
- Ensure to implement onPause/onShowAd -> onResume/onAdComplete to pause and resume audio.
### Power & Battery
- Minimize unnecessary background work.
- Pause heavy animations or physics simulations when not visible.
- Use **frame skipping** or **dynamic resolution scaling** if hardware struggles.
***
## 🚗 Automotive-Specific Considerations
While games must scale automatically across all platforms, **automotive environments** require additional care:
- Avoid distracting animations or high-contrast flashing elements.
- Handle **OS memory pressure** → free unused textures/models.
- Implement **crash recovery**: auto-return to safe menu state.
- Test readability under glare and low-light conditions.
***
## 🧪 Testing & Certification
### Mandatory Test Scenarios
- Chrome DevTools Network Throttling (20mbit/100ms latency).
- FPS measurement with Chrome Performance tab.
- Memory profiling vs platform budgets.
- Long play session stability (≥1 hour).
- AirConsole simulator and real-device tests (incl. automotive hardware where possible).
### Recommended Tooling
- Chrome DevTools (Performance, Memory, Network tabs).
- WebGL Inspector / Spector.js for GPU analysis.
- For automotive, test using the [Xiaomi Pad 6 WLAN](https://www.gsmarena.com/xiaomi_pad_6-12237.php)
- **For web:** To test your game in a similar performance setup as many cars, use Chrome to load [https://airconsole.com](https://airconsole.com) as Desktop Site and connect the Chrome Dev tools with video stream active. This gives a somewhat similar experience and performance profile.
- **Android native games:** Work like normal but ensure to not add your game to Xiaomi's Game Space! This would enable optimisations that impact performance and behaviour considerably.
***
## ⚖️ Do’s and Don’ts
| Do ✅ | Don’t ❌ |
| ------------------------------------------------------ | ----------------------------------------- |
| Use compressed textures and atlases. | Ship raw PNGs or too many small textures. |
| Profile with Chrome DevTools and Spector.js. | Assume desktop performance = automotive. |
| Implement adaptive quality (LOD, texture scaling). | Hardcode high-quality settings. |
| Test input latency on real devices (incl. automotive). | Only test on desktop Chrome. |
| Stream large assets (audio/video). | Load everything eagerly at startup. |
***
## 📌 Summary
- Meet **technical requirements** across all platforms.
- Follow **general performance best practices**: rendering, networking, memory, input, audio, and power.
- Apply **automotive-specific safety considerations** when needed.
- Use robust **testing workflows and profiling tools** to ensure consistent quality.
By following this guide, developers can deliver games that are performant, efficient, and enjoyable across all environments on AirConsole.
[title] Example games in web / unity
[path] /
[title] FAQ / Help
[path] Reference/
## General
:::ExpandableHeading
### Where can I publish a game in the gamestore?
Visit [https://www.airconsole.com/developers](https://www.airconsole.com/developers) or visit the "[How to publish your game](https://developers2.airconsole.com/publishing-your-gamehttps://developers2.airconsole.com/publishing-your-game)" guide.
:::
:::ExpandableHeading
### Where can I get information about the monetization?
You can find information about the monetization in our "[AirConsole Hero & Revenue](https://developers2.airconsole.com/airconsole-hero-and-revenue)" guide.
:::
:::ExpandableHeading
### Which games can be built for AirConsole?
If your game runs in a browser then it also works with AirConsole. In fact you won't write a lot of code to adapt your game for AirConsole. However, there are of course limitations to consider like for example the latency or the amount of buttons your controller should have. Check our "[Best Practices for Web Games on AirConsole](docId\:Due8W48UINjBRxskf8iNf)" to see what other developers have built for AirConsole.
:::
:::ExpandableHeading
### Who is behind AirConsole?
Checkout these handsome people at [N-Dream AG](https://corp.airconsole.com/).
:::
## Technical
:::ExpandableHeading
### How can I test my game?
Please check out the "[Testing your game](https://developers2.airconsole.com/testing-your-game)" guide.
:::
:::ExpandableHeading
### Can I directly link to my game?
Yes, by either using https\://www\.airconsole.com/#http\://your-game-url/ or when your game is published in the game store by https\://www\.airconsole.com/#!play=GAME\_ID.
:::
:::ExpandableHeading
### Is there an easy way to simulate high latency?
Yes, if you load `www.airconsole.com/?server=[SERVER_ZONE]`or `www.airconsole.com/simulator/?server=[SERVER_ZONE]`all your communication will go through a datacenter in the specified server zone. WebRTC will also be disabled. To simulate high latency, choose a server zone that is far away. Currently available server zones are:`europe-west1-b`,`us-central1-a`,`asia-east1-a`.
To show the latency of your controllers, you can use the [Latency Debugger](https://developers.airconsole.com/#!/help#technical-latency:~\:text=can%20use%20the-,Latency%20Debugger,-.).
:::
:::ExpandableHeading
### What is the send-message limit?
Between two devices, there is a limit of 25 messages per second (e.g. from one controller to the screen).
Broadcasts and Custom device state changes (combined) are limitted to 25 events per second per device.
However, all messages will be queued, so that no message will be lost. We've created a [Rate Limiter](https://github.com/AirConsole/airconsole-controls/tree/master/rate-limiter) library to help you to rate-limit messages intelligently.
:::
:::ExpandableHeading
### I can't load my game in the simulator or on a test phone!
Make sure your`screen.html`and`controller.html`are accessible from all devices.
Let's assume you are running your local web server on http\://192.168.0.2:8080/
Try to access http\://192.168.0.2:8080/screen.html and http\://192.168.0.2:8080/controller.html using a normal web browser on the device that doesn't work. It should display the screen/controller html.
If you can't access http\://192.168.0.2:8080/controller.html from your phone, but from your computer, make sure you are in the same network and that your router does not have "Client Isolation" activated.
If you are testing with real smartphones, make sure you do not use http\://localhost/ or http\://127.0.0.1/, because localhost is not your computer on the phone but the phone itself!
If you are still unable to connect your phone, you can use the "ngrok" tool to forward your local url. See our [guide](https://developers2.airconsole.com/testing-with-your-phone) for how to do this in the Unity Engine.
:::
:::ExpandableHeading
### Is WebRTC supported?
Yes, we support WebRTC but only as much as WebRTC [is currently supported](http://iswebrtcreadyyet.com/) by browsers. WebRTC decreases the latency dramatically. Because not everyone supports it yet, always assume that your game also works on a higher latency. When WebRTC is supported you will see a message`WebRTC active for device_id {id}`in the browsers console.
:::
:::ExpandableHeading
### Can I self-host AirConsole?
No that is not possible. But you can directly link to your game like this: http\://www\.airconsole.com/#*http\://your-game-url/.*
:::
## Monetization, Ads & AirConsole Hero
:::ExpandableHeading
### How are games on AirConsole monetized?
Users can purchase our premium subscription, [AirConsole Hero](https://www.airconsole.com/hero). Please see the [monetization guide](https://developers2.airconsole.com/airconsole-hero-and-revenue) for details.
:::
:::ExpandableHeading
### Can I create special content for Hero users?
Yes, can lock some content in your game (like characters, or certain levels or game modes) so that they’re only available if at least one Hero user is playing.
Feel free to contact us if you need ideas on how to incorporate Hero content into your game. See our [guide on Premium content](https://developers2.airconsole.com/hero-exclusive-content) for more information.
:::
::::ExpandableHeading
### How do I show ads?When should I show ads?
By calling the`showAd`method in the AirConsole API.
:::BlockQuote
Make sure you mute the sound and execution of the game if`onAdShow`is called.
You can unmute sounds and game execution as soon as`onAdComplete`is called.
:::
::::
:::ExpandableHeading
### When should I show ads?
It is up to you to find the best moment in your game to show an ad. We recommend calling the function at a point where there is a sort of ‘pause’ in your game, but before it’s actually over. Because we will limit the frequency of when an Ad is actually shown on our side to every 5 minutes, you should try to display ads as often as possible.
:::
:::ExpandableHeading
### Do I get ad revenue from my game on AirConsole?
There is no ad revenue on AirConsole. Any "ad breaks" that are shown are just advertising our own AirConsole Hero subscription, or showing other AirConsole features or content. The platform does not get any income through third party advertisements, and neither do developers.
:::
:::ExpandableHeading
### How do I get paid?
We pay developers via Paypal or Bank Wires. You can request a payout on your Revenues page, which you can access via the [Developers Console](https://www.airconsole.com/developers).
:::
:::ExpandableHeading
### Can I decide which ad or kind of ad will be shown?
No. All ads that are shown on the platform are our own AirConsole Hero advertisements. The exact content and order of advertisements that players see is carefully balanced on AirConsole's side.
:::
:::ExpandableHeading
### Why don't you show third party advertisements?
We did at some point and our data clearly showed that our users were happier and more likely to get an AirConsole Hero subscription if no external ads were shown. The ad revenue gained by impressions was not worth it for us in comparison.
:::
::::ExpandableHeading
### Can I launch a free/ad-free/unmonetized game on AirConsole?
Normally, no. Since we have server costs from all the games that are live on the platform, we don't allow anyone to launch completely unmonetized games. For special solutions and exceptions to this (are you making a game for a good cause, for example?) get in touch [via email](https://publishers@n-dream.com).
## Unity
:::ExpandableHeading
### Where do I add images to my controller?
Any files your controller should have access to, such as images, JavaScript files, style sheets etc., should be placed either in`Assets/WebGLTemplates/AirConsole-2020`for Unity versions 2020 and up or in`Assets/WebGLTemplates/AirConsole`for Unity versions 2019 and down.
The controller that is linked in your AirConsole Game Object will be automatically copied to that folder when you start your game, and paths will be relative to it.
:::
:::ExpandableHeading
### Why do I get compilation errors after adding JavaScript files?
If your JS scripts throw compilation errors, it's because Unity is trying to compile them as UnityScript files. Make sure you place all JavaScript files in`Assets/WebGLTemplates/AirConsole`. If the compiler errors show up despite proper file location, try restarting the Unity Editor.
:::
:::ExpandableHeading
### Why do I get "Multiple precompiled assemblies with the same name Newtonsoft.Json.dll included on the current platform. \[...]" after importing the AirConsole plugin in Unity 2021+
Delete the following plugin file (It is now included in Unity directly and is not needed anymore in newer Unity versions):`Assets/AirConsole/plugins/Newtonsoft.Json.dll`
:::
:::ExpandableHeading
### Why do I get "mainTemplate.gradle is using the old aaptOptions noCompress property definition does not include types defined in unityStreamingAssets constant." when building for Android TV on Unity 2022+?
Unity 2022 made some updates to their gradle launcher which doesn't support and old option syntax anymore. The solution is to edit **Assets/Plugins/Android/mainTemplate.gradle **and **launcherTemplate.gradle **to add/replace the **aaptOptions **"noCompress" line with`noCompress = ['.ress', '.resource', '.obb'] + unityStreamingAssets.tokenize(', ')`
Check [Unity Support](https://support.unity.com/hc/en-us/articles/4408584577044-Why-do-I-get-errors-when-using-a-Gradle-file-with-an-old-aaptOptions-noCompress-property) for more details.
:::
::::
## Help and contact
Chat with the AirConsole team and other fellow developers on our [Discord](https://discord.com/invite/5BzND3v) channel.
If you have any ideas for how to make AirConsole better and more attractive for game developers, let us know your thoughts!
Fill out our [Developer Feature Request Form here](https://goo.gl/forms/0ezPM42bL082dBH93).
[title] Using the microphone to create unique games
[path] AirConsole Games Features/Improving your game engage/
This guide is for game developers using `airconsole-1.11.0.js` inside their game.
Use `airconsole.getUserMedia()` when a controller needs microphone access, for example for voice volume, singing, blowing, rhythm, or other audio-reactive gameplay.
## Quick Start
Add a button to your controller HTML:
```html
```
Then wait until AirConsole is ready and request microphone access from that button. In most games, requesting from an intentional player action is clearer than asking immediately on page load and various browsers require user interaction for permission requests to work:
```javascript
var micStream = null;
function setMicrophoneStatus(message) {
document.getElementById("microphone-status").textContent = message;
}
airconsole.onReady = function() {
document.getElementById("request-microphone").onclick = function() {
airconsole.getUserMedia({ audio: true })
.then(function(stream) {
micStream = stream;
setMicrophoneStatus("Microphone enabled");
// Use the stream, for example with the Web Audio API.
})
.catch(function(error) {
// Show a useful message or keep the game playable without microphone input.
setMicrophoneStatus("Microphone is not available");
console.error("Microphone access failed:", error);
});
};
};
```
Stop the microphone when you no longer need it:
```javascript
if (micStream) {
micStream.getTracks().forEach(function(track) {
track.stop();
});
micStream = null;
}
```
Stopping tracks matters. It releases the microphone for the browser or app and lets privacy indicators turn off when nothing else is using the microphone.
## Current limits
As of 2026-05-19, the AirConsole API 1.11.0 supports getUserMedia only on controllers and it only supports the audio constraint, not video
```javascript
// Rejects in AirConsole 1.11.0.
airconsole.getUserMedia({ video: true });
// Rejects in AirConsole 1.11.0 on the screen.
airconsole.getUserMedia({ audio: true });
```
## What You Can Request
In AirConsole 1.11.0, you can call
```javascript
airconsole.getUserMedia({ audio: true });
```
to request access to the users audio stream on the controller.
You can also request user media constraints for audio:
```javascript
airconsole.getUserMedia({
audio: {
echoCancellation: true,
noiseSuppression: true,
autoGainControl: true
}
});
```
## Where It Works
After `airconsole.onReady` has fired, call `getUserMedia()` from a controller, not from the screen. Calling before `onReady`, before the controller has a device id, rejects `getUserMedia()` with `NotReady`.
The screen can learn whether one of the controllers was granted or denied microphone access through callbacks:
```javascript
airconsole.onUserMediaAccessGranted = function(deviceId) {
console.log("Controller " + deviceId + " has microphone access");
};
airconsole.onUserMediaAccessDenied = function(deviceId) {
console.log("Controller " + deviceId + " was denied microphone access");
};
```
The controller that requested access should use the returned Promise to know its own result:
```javascript
airconsole.getUserMedia({ audio: true })
.then(function(stream) {
// This controller got access.
})
.catch(function(error) {
// This controller did not get access.
});
```
## Handling Errors
`getUserMedia()` returns a Promise. It rejects when AirConsole cannot start the request or when the browser/app cannot grant microphone access.
AirConsole-specific errors extend `AirConsoleUserMediaError`
```javascript
error.name === "AirConsole.UserMediaError"
```
Common AirConsole-specific messages:
- `NotSupportedOnScreen`: the screen called `getUserMedia()`.
- `NotReady`: AirConsole is not ready yet.
- `AlreadyPending`: another microphone request is already in progress on this controller.
- `InvalidConstraints`: the constraints are missing, false, or unsupported by AirConsole 1.11.0.
- `Timeout`: the AirConsole permission flow timed out.
- `PermissionDenied`: AirConsole/platform permission flow denied the request.
Browser-originated errors use the browser's own error names. Common ones are:
- `NotAllowedError`: the user, browser, page, iframe policy, or app settings denied microphone access.
- `NotFoundError`: no matching microphone was found.
- `NotReadableError`: the microphone exists, but the browser/OS could not open it.
- `OverconstrainedError`: your audio constraints could not be satisfied.
- `AbortError`: the browser could not use the device after starting the request.
A practical handler:
```javascript
function showMessage(message) {
document.getElementById("microphone-status").textContent = message;
}
function handleMicrophoneError(error) {
if (error instanceof AirConsoleUserMediaError) {
if (error.message === AirConsole.USER_MEDIA_ERROR_TYPE.notSupportedOnScreen) {
showMessage("Microphone input is only available on controllers.");
} else if (error.message === AirConsole.USER_MEDIA_ERROR_TYPE.alreadyPending) {
showMessage("Microphone permission is already being requested.");
} else if (error.message === AirConsole.USER_MEDIA_ERROR_TYPE.timeout) {
showMessage("Microphone permission timed out. Try again.");
} else {
showMessage("Microphone is not available right now.");
}
return;
}
if (error instanceof DOMException) {
if (error.name === "NotAllowedError") {
showMessage("Allow microphone access in your browser or app settings.");
} else if (error.name === "NotFoundError") {
showMessage("No microphone was found on this device.");
} else if (error.name === "OverconstrainedError") {
showMessage("This microphone does not support the requested audio settings.");
} else {
showMessage("Could not start the microphone.");
}
return;
}
showMessage("Could not start the microphone.");
}
```
## Recommended Game Flow
Ask for microphone access only when the player intentionally enables an audio feature. A button in the controller lobby is usually better than requesting immediately on page load as certain browsers will reject permission requests without user interaction. If you use the `request-microphone` button from the quick-start HTML above, the flow is:
```javascript
airconsole.onReady = function() {
document.getElementById("request-microphone").onclick = function() {
airconsole.getUserMedia({ audio: true })
.then(startMicrophoneGameplay)
.catch(handleMicrophoneError);
};
};
```
Keep the game playable when microphone access fails. For example, keep button controls available or let the player retry.
Do not call `getUserMedia()` repeatedly while one request is pending. AirConsole rejects concurrent requests with `AlreadyPending`.
:::hint{type="info"}
Do as much of the audio processing as possible on the controller. The message rate limit and the users network bandwidth can impact the users game experience otherwise.
:::
## Example: Send Audio Level To The Screen
This example measures microphone volume on the controller and sends a simple level value to the screen.
Controller HTML:
```html
```
Controller JavaScript:
```javascript
var micStream = null;
var audioContext = null;
var analyser = null;
var animationFrame = null;
var lastSendTime = 0;
var source = null;
airconsole.onReady = function() {
document.getElementById("request-microphone").onclick = startMicLevelInput;
document.getElementById("stop-microphone").onclick = stopMicLevelInput;
};
function setMicrophoneStatus(message) {
document.getElementById("microphone-status").textContent = message;
}
function startMicLevelInput() {
airconsole.getUserMedia({ audio: true })
.then(function(stream) {
var AudioContextClass = window.AudioContext || window.webkitAudioContext;
micStream = stream;
audioContext = new AudioContextClass();
source = audioContext.createMediaStreamSource(stream);
analyser = audioContext.createAnalyser();
analyser.fftSize = 256;
source.connect(analyser);
setMicrophoneStatus("Microphone enabled");
sendMicLevelLoop();
})
.catch(handleMicrophoneError);
}
function sendMicLevelLoop() {
var data = new Uint8Array(analyser.frequencyBinCount);
function tick() {
animationFrame = requestAnimationFrame(tick);
var now = Date.now();
// We want to send the information only 10 times per second of our 25 messages / second limit.
if (now - lastSendTime < 100) {
return;
}
lastSendTime = now;
analyser.getByteFrequencyData(data);
var sum = 0;
for (var i = 0; i < data.length; i++) {
sum += data[i] * data[i];
}
var level = Math.sqrt(sum / data.length) / 255;
airconsole.message(AirConsole.SCREEN, {
type: "audio-level",
level: level
});
}
tick();
}
function stopMicLevelInput() {
if (animationFrame) {
cancelAnimationFrame(animationFrame);
animationFrame = null;
}
if (micStream) {
micStream.getTracks().forEach(function(track) {
track.stop();
});
micStream = null;
}
if (source) {
source.disconnect();
source = null;
}
if (analyser) {
analyser.disconnect();
analyser = null;
}
if (audioContext) {
audioContext.close();
audioContext = null;
}
setMicrophoneStatus("Microphone stopped");
}
function handleMicrophoneError(error) {
setMicrophoneStatus("Microphone is not available");
console.error("Microphone access failed:", error);
}
```
Screen:
```javascript
airconsole.onMessage = function(deviceId, data) {
if (data && data.type === "audio-level") {
var level = data.level;
// Use level for gameplay or visualization.
}
};
```
The example sends at most 10 audio-level messages per second. Keep audio telemetry small and rate-limited; games should not stream raw microphone data through AirConsole messages.
For a complete game structure, start from the AirConsole Pong example repository:
- [https://github.com/AirConsole/games-pong](https://github.com/AirConsole/games-pong)
In this game you will find `controller.html` which implements the getUserMedia requesting.
Additionally you will find `screen.html` that subscribes to the [`airconsole.onUserMediaPermissionGranted`](https://airconsole.github.io/airconsole-api/beta/AirConsole-Microphone_Permission.html#onUserMediaAccessGranted) and [`airconsole.onUserMediaPermissionDenied`](https://airconsole.github.io/airconsole-api/beta/AirConsole-Microphone_Permission.html#onUserMediaAccessDenied) callbacks.
Use those as full-context examples for where controller setup, `onReady`, lobby UI, screen messages, and microphone cleanup live in an actual game.
## Browser And App Behavior To Expect
Browsers and mobile apps do not expose microphone permission exactly the same way.
On web controllers:
- the browser may show its own microphone prompt.
- the Promise can stay pending if the player ignores the prompt.
- AirConsole rejects with `Timeout` after its own timeout period.
- browser failures such as `NotAllowedError` or `NotFoundError` may be returned.
On native AirConsole controller apps:
- the app may show native permission UI.
- if permission was denied permanently, the player may need to open system settings. AirConsole will inform the user about that.
- older app versions may not support the feature. AirConsole will in this case inform the user about the need to update the application.
Build your game UI around outcomes, not platform assumptions:
- granted: start audio gameplay.
- denied: When the user denies microphone access, the platform will be handling explain how to allow microphone access or offer a retry.
## Checklist
- Call `getUserMedia()` only from controllers.
- Request microphone with `{ audio: true }` unless you have a reason for advanced audio constraints.
- Handle both `AirConsole.UserMediaError` and browser error names.
- Keep a non-microphone fallback.
- Stop all tracks when leaving the audio feature, lobby, or game.
- Rate-limit any audio-derived messages sent to the screen.
- Do not request video through AirConsole 1.11.0.
## References
- MDN `MediaDevices.getUserMedia()`: [https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia)
- MDN `MediaTrackConstraints`: [https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints)
- MDN `MediaStreamTrack.stop()`: [https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/stop](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/stop)
[title] Testing your game
[path] Getting started with AirConsole/
### *The Simulator*
The AirConsole simulator makes it easy for you to test your game. It provides a way to load your game into the AirConsole environment and shows you the screen and (on start) two controllers. With that you can easily play your game in one browser window without having to use another device, such as a smartphone.
[http://airconsole.com/simulator/#debug\:YOUR\_HOST\_OR\_URL](http://airconsole.com/simulator/#debug\:YOUR_HOST_OR_URL)
Open Simulator Demo: [https://www.airconsole.com/simulator/#debug\:https://game.airconsole.com/com.airconsole.testpong.cdn.airconsole.com/2024-02-14-14-52-40/](https://www.airconsole.com/simulator/#debug\:https://game.airconsole.com/com.airconsole.testpong.cdn.airconsole.com/2024-02-14-14-52-40/)
**How to access the simulator**
The website on which your game runs has to be accessible - either by an IP or an URL. To load your game simply replace *YOUR\_IP\_OR\_URL *with your games-location:
If you use a local ip, use:
:::BlockQuote
**http\://http.airconsole.com/simulator/#debug:***YOUR\_IP\_OR\_URL*
:::
If you use a https reachable game, use:
:::BlockQuote
**https\://www\.airconsole.com/simulator/#debug:***YOUR\_URL*
:::
For example the pong game's testing url is:
:::BlockQuote
**https\://www\.airconsole.com/simulator/#debug:**https\://game.airconsole.com/com.airconsole.testpong.cdn.airconsole.com/2024-02-14-14-52-40/
:::
Or if hosted on localhost:
:::BlockQuote
**http\://http.airconsole.com/simulator/#debug:**http\://192.168.0.1/
:::
:::BlockQuote
**NOTE:** AirConsole will try to access the /screen.html and a /controller.html, so make sure its accessible in the root url.
:::
**Join with your smartphone**
Of course you can additionally join with your smartphone. Just connect your phone like you would normally connect to a game: go to airconsole.com and enter the code which appears in the developer consoles top right.
:::BlockQuote
**NOTE:** If you are testing with real smartphones, make sure you do not use http\://localhost/ or http\://127.0.0.1/, because localhost is not your computer on the phone but the phone itself! Also make sure your devices are visible within the network to each other.
:::
### *Test https with ngrok*
Once your game is uploaded to the AirConsole store, it will be accessed via https. This means all your external resources you load in your game have to be loaded through https too.
To simulate https locally we recommend to use [ngrok](https://ngrok.com/) or [cloudflare tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel/).
1. Go to [ngrok-website ](https://ngrok.com/)download and install ngrok. :)
2. (Optional for unix-based systems: Add to path: `sudo mv ngrok /usr/local/bin`)
3. Execute ngrok in the terminal: `ngrok http 8000`
(Assuming 8000 is the port your local webserver is running at).
4. Ngrok will display some urls now -> copy the https url and try if it works in the simulator.
**Example**
Your game url on localhost is running at`192.10.20.42:8080`and the URL from ngrok (`ngrok http 8080`) is`https://cb501143.ngrok.io`. To test your game in the simulator with https open:
:::BlockQuote
https\://www\.airconsole.com/simulator/#*https\://cb501143.ngrok.io/*
:::
### *Troubleshooting: Using Airconsole on a standard University/Corporate network*
This issue can also be solved by using [ngrok](https://ngrok.com/) (see above). This way you can make your localhost public even if there is client isolation.
:::BlockQuote
**Note to Unity Developers:** You need the latest airconsole unity plugin from [github.com](https://github.com/AirConsole/airconsole-unity-plugin) released on 2016-02-01 and you should select "Normal" as the browser start mode.
:::
[title] Introduction
[path] /
We have created the following documents to clarify how AirConsole system works and to help with the game integration into our platform.
[title] Tutorials
[path] /
[title] Game Language Translations
[path] AirConsole Games Features/Improving your game engage/
Translating your games to multiple languages broadens your audience.
### *1. Basics*
- Every displayed text in your game is a string (Graphics can not be translated).
- Every string has an ID. Example: The text "Welcome to our game" could have the id "`welcome_message`".
- Every string has to be registered in AirConsole's translation console.
- You or AirConsole Translators can translate all your string in the translation console to any language
- You don't have to worry about language selection / loading language files.
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/1Cn-BBIA6JwwaiEfdGH0z_image.png" size="80" width="760" height="315" position="center" darkWidth="760" darkHeight="315" showCaption="false"}
### *2. AirConsole Translation console*
The translation console is the central repository for all your strings.
Any string that you want to have translated needs to be in there.
The translation console can be found in the developer console, inside one of your games under "Translations". You first need to register a game in the developer console before you can start adding translation string.
To add new translation strings, just follow the instructions in the translation console.
Once you have translation strings registered, you can select a language in the drop down and start to translate them. You can also add additional translators by email address to get some help with other languages. These translators can only suggest translations, but can not create or modify translation ids.
Anytime a translator or you changes a translation, you need to approve the suggestion before it goes to production. You can preview the changes with the "Preview" buttons.
:::BlockQuote
Local development always uses suggested translations and not live translations.
:::
[Go to Developers Console](http://www.airconsole.com/developers)
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/IXuANxwK3ya5rtbVzVLZd_image.png" size="98" width="932" height="739" position="center" darkWidth="932" darkHeight="739" showCaption="false"}
### *3. Using Translation Strings in your game*
To use translations, you need to call the AirConsole constructor with the option `translation: true`
:::BlockQuote
new AirConsole(\{"translation": true})
:::
Once you have registered a string in the translation console, you can start using it inside your code. Assuming you have registered a string `welcome_screen` that has the English value "Welcome to our game", you can retrieve it using:
:::BlockQuote
airconsole.getTranslation("welcome\_screen");
:::
If the users language is English, it will return "Welcome to our game".
For static html translations you can use the `data-translation` attribute. This will automatically fill in your static translation:
:::BlockQuote
\\
:::
This will result in:
:::BlockQuote
\Welcome to our game\
:::
Translation strings can use replacement parts. For example `welcome_user` could be have an English value of `Hi %username%`. To retrieve the translated string with the username filled in, you can call:
:::BlockQuote
airconsole.getTranslation("welcome\_user", \{"username": "Tom"});
:::
which would result in "Hi Tom".
Replacement parts can only be used in programatically and can not be used with the static html attribute `data-translation`.
You should never concatenate translation strings to build a sentence. Always use replacement parts instead. Different languages have different sentence structures.
:::BlockQuote
To preview a different language, add the "?language" parameter when loading AirConsole. e.g.: www\.airconsole.com/?language=de
:::
### ***4**. Advanced usage*
You can also use your own translation system. A quiz for example could load different questions depending on the current language. To get the current language, call:
:::BlockQuote
airconsole.getLanguage()
:::
This could also be abused to load different images depending on the users language and therefor you could use graphics containing texts.
:::BlockQuote
Note that the AirConsole Translation team will not be able to help you with your translations.
:::
### *5. Translations in Unity*
To enable translation functionality within your Unity project, do the following on your AirConsole Game Object:
- enable the `Translation` checkbox.
- enter your game id.
You can see the translation functionality in action in the 'translations' example scene that you can find in your plugin under `Assets/AirConsole/examples/translations`.
The example scene uses a few pre-defined translation strings set up for the game ID `com.airconsole.plugin.unity`. You can request these for testing purposes, but you cannot edit them or add more.
:::BlockQuote
To test translations within the Unity Editor, you need to create an entry for your game in our [Developer Console.](http://www.airconsole.com/developers) This is where you define your Game ID.
:::
Request an individual translation string by id:
:::BlockQuote
string welcomeScreenTranslated = AirConsole.instance.GetTranslation("welcome\_screen");
:::
Request a translation with replacement parts. The values have to be passed along as a`Dictionary ` :
:::BlockQuote
string welcomeUserTranslated = AirConsole.instance.GetTranslation("welcome\_user", new Dictionary \ \{ \{ "username", "Tom" } });
:::
You can translate multiple UI Text or Text Mesh elements (without replacement values). For it to work, the`text`property of the UI Text or Text Mesh needs to contain the translation ID string within double curly brackets:`{{welcome_screen}}`
:::BlockQuote
public Text\[] textsToTranslate;
void OnReady(string code) \{
AirConsole.instance.TranslateUIElements(textsToTranslate);
}
:::
:::BlockQuote
You cannot test different languages within the Unity Editor. Upload your Game to the [Developer Console](http://www.airconsole.com/developers) to enable and test different languages.
:::
### *6. Importing and exporting translations*
The importing/exporting translations functionality simplifies the process of working with changes on many string IDs, whether creating a new one or editing the existing ones.
:::BlockQuote
All translations are imported from or exported to the **.xlsx** file format.
:::
The import and export buttons can be found in the side menu.
**Importing Translations**
The import file must have the following structure:
- The first column represents translation IDs.
- Each other column represents one of the languages that you are importing.
- The header row for the translation IDs, which is the first column, must have the value **"string-id"**.
- The header row for each language column contains the value of the language code for the language being imported. You can find available languages and their corresponding codes below.
- For each row, the string ID name is in the first column, and each corresponding language column contains the value of the string ID in the imported language.
This is an example of the import file:
You can download a template here:
::File{src="https://archbee-doc-uploads.s3.amazonaws.com/2_r-qrqZUGzk_b42RwDvD-7DwchpupMy_7chRg-426Z-20241119-104144.xlsx" label="import_translations_template.xlsx"}
When translations are imported, the following rules apply:
- When importing translations with new string IDs, the new string IDs will be automatically registered with the default metadata:
- Devices: Available on both
- Description:
- Render limit: No
- If you import a new string ID, the string ID value in the English column is mandatory.
- All translation string ID's new values in importing languages will be displayed in the translation console as new changes in the corresponding language section and have to be manually approved. Only English values of the new string IDs will be automatically approved as the part of the process of the registration of the new string IDs.
- A string ID with an empty value in a language column does not delete the previous value from the database for that language. It just skips the importing of the value for the language.
- The system's flexibility allows you to import new string IDs and edit the language values of the existing ones in the same import file.
- If the import file contains irregularities, error messages will be displayed addressing the problems. Please correct all errors and try importing again.
**Exporting Translations**
- All available translations for the game will be exported.
- The export file structure mirrors the pattern defined in the import translations section.
- The values of production translation string IDs are sorted in the columns by language, with the language code in the header row.
- New translation string values that have not been approved are also sorted in the columns per language, with the language code suffixed with "-dev" in the header row.
**Translation languages**
The AirConsole platform is currently translated into the following languages: Chinese, English, French, German, Indonesian, Italian, Japanese, Korean, Portuguese, Portuguese(Brazil), Spanish, Thai, and Ukrainian, but you can provide your game in many more languages.
[title] Handling unstable connections
[path] AirConsole Games Features/Connect to your game/
Your game needs to handle unstable connections and high latency. In this guide you will learn about properly handling unstable connections (Such as in cars, unstable 4G/Wi-Fi networks)
### *Internet Connections can be unstable (E.g. in cars)*
The AirConsole API makes sure that no messages and updates from the Screen and the Controllers are lost. A message or update sent by a device is guaranteed to arrive at some point in the right order even if the internet connection was disrupted, but the latency can be high.
### *Loading file resources in your game*
:::BlockQuote
You are responsible to reload resources if they fail to load after `onReady()` is called.
:::
If a request fails before onReady is called in the API, we will reload the entire game. But once onReady was called, you have to reload resources that fail to load yourself. The best practice is to load all resources before onReady if you know that they are going to be used. Additional levels and big data files should still be loaded on demand at a later point, but you are responsible to handle load failures/retries.
### *Implementing onPause() / onResume() events*
**General**
:::BlockQuote
It is vital that you implement the `onPause()` / `onResume()` events.
:::
When a device such as a car's infotainment screen loses the internet connection (E.g. in a tunnel), the inputs from the Controllers will not arrive on time. When AirConsole detects a very high latency or temporary disconnect from the internet, the `onPause()` method will be called, and you should immediately pause the game and all audio. You don't need to inform the user about pausing the game since AirConsole will provide a pause overlay on the screen and all controllers.
:::BlockQuote
Make sure that pause still works if called twice!
:::
Sometimes, there may be a delay in displaying the pause overlay on Controllers. This happens when the connection between the Controllers and the screen is completely lost, but as soon as the connection is re-established, the pause overlay will appear.
:::BlockQuote
Please, do not create any informative screens about pausing the game. AirConsole will provide pause overlay on Screen and all Controllers.
:::
Once the internet connection conditions are back to normal, AirConsole will call `onResume()`, and you should resume the game and all sounds. AirConsole will show a countdown overlay for 3 seconds before `onResume` event is called.
:::BlockQuote
The`onPause()`method will only be called on the Screen! Controller input will still arrive on the Screen and should not change the game's state before`onResume()`is called.
:::
`onPause()` / `onResume()` methods were added in AirConsole API 1.8.0. You can test them in the [AirConsole Simulator](http://www.airconsole.com/simulator/) if you are using at least API version 1.8.0.
**Testing**
Please include these following cases in your tests:
- **Test Case 1 - Initially (Game loaded)**
The Screen is disconnected from the internet while the game is loading and the `onPause()` function is called. When the game loads, it calls the `onReady()` callback function. AirConsole will call the `onPause()` function right after it executes the `onReady()` function from the game that just loaded. Make sure that this is handled properly and that you pause any game logic, intro videos or other background music immediately.
**Steps:**
Load your game preview in the AirConsole Simulator, e.g.: https\://www\.airconsole.com/simulator/#https\://game.airconsole.com/com.your.game/2023-06-07-16-06-19/ with **Pause on start** selected.
**Expected:**
The game should be paused and not producing any sounds (E.g. background music, intro sound/music, video intro, etc.)
- **Test Case 2 - During gameplay**
Disconnecting the Screen from the internet while playing the game should pause the game and all sounds in the game.
**Steps:**
- Load your game preview in the AirConsole Simulator, e.g.: https\://www\.airconsole.com/simulator/#https\://game.airconsole.com/com.your.game/2023-06-07-16-06-19/
- Press the pause button any time during the gameplay (E.g. While loading a game level, while in the game menu, while playing, etc.)
**Expected:**
The game should be paused and not producing any sounds (E.g. background music, intro sound/music, video intro, etc.)
- **Test Case 3 - Repetitive calls to**`onPause()`
Calling the `onPause()` function multiple times will not cause any issues.
The game should remain paused and not exhibit different behavior even if `onPause()` is called repeatedly.
**Steps:**
Simulate calling the `onPause()` function multiple times (without calling `onResume()` in between).
**Expected:**
Invoking `onPause()` on an already paused game should keep the game in a paused state.
- **Test Case 4 - Repetitive calls to**`onResume()`
Calling the `onResume()` function multiple times will not cause any issues.
The game should remain active and not exhibit different behavior even if `onResume()` is called repeatedly.
**Steps:**
Simulate calling the `onResume()` function multiple times (without calling `onPause()` in between).
**Expected:**
Invoking `onResume()` on an already active game should keep the game active. It should not pause the game or behave differently even if called multiple times.
### *High Latency handling*
**General**
Input latency from Controllers can be significantly higher in cars. The API call `getServerTime()` provides a synchronized clock between the devices.
For example in a Quiz game, this timestamp can be sent from the Controller to the Screen. If Controllers have different latency, you can still determine the correct winner by looking at all timestamps received from the Controllers to compare the real user input times.
This can be applied to almost any game. You can determine the latency of a message by sending the `getServerTime()` timestamp from the Controller to the Screen and compare it with the `getServerTime()` on the Screen. Once you know how many milliseconds the message took, you can consider this in your input. (E.g. rewind the game by X milliseconds, add the input, fast-forward X milliseconds again).
**Testing**
The best way to simulate a high latency between the controller and the screen is to use a VPN. The Chrome Devtools Network option won't throttle the WebRTC connection, only the loading of the game assets.
[title] Create engaging games
[path] AirConsole Games Features/
[title] Hero Exclusive Content
[path] Generate income with your game/
With the “Premium” functions of the AirConsole API, it is possible to restrict certain content or features to AirConsole Hero subscribers, respectively sessions with at least one AirConsole Hero subscriber in them.
### *Why should I add Exclusive Content?*
[AirConsole Hero](https://www.airconsole.com/hero) is a premium subscription for the AirConsole platform, which is otherwise available for free. Premium subscriptions are the main monetizations strategy for AirConsole and its games.
The developer of every game profits from users that get an AirConsole Hero subscription while playing their game, so it is in their best interest to give the users some additional, game-specific incentive.
:::BlockQuote
See [our guide on Ads and AirConsole Hero](https://developers2.airconsole.com/airconsole-hero-and-revenue) for more details.
:::
### *How do I add Exclusive Content?*
There are several approaches to having Hero-Exclusive content in your game. In general, the content that is exclusive to paying users should offer more variety or more convenience, but not a mechanical advantage over fellow non-Hero players in the session.
- **Cosmetic Options**
Example: Exclusive Characters in [Silly World Series](https://www.airconsole.com/play/silly-world-series), only available to Hero subscribers themselves.
- **Additional Content**
Example: Exclusive Levels in [Castle Hustle](https://www.airconsole.com/play/castlehustle), available if at least one person in the session is a Hero subscriber.
- **Convenient Features**
Example: Team Color Selection in [Hotline](https://www.airconsole.com/play/party-games/hotline) or Character Selection in [The Neighborhood](https://www.airconsole.com/play/the-neighborhood), available if at least one person in the session is a Hero subscriber.
You can label Hero-exclusive content in your game with the AirConsole Hero Logo. Find our logo package [here.](https://drive.google.com/drive/folders/0BxEs-y1NpJ4zZ0VERG5NUm40X00?usp=sharing)
### *Implementation*
There are four calls in the AirConsole API that you can use to find out which and how many devices are premium as well as offer the players to get premium.
See the “Premium” section in the [AirConsole API](https://www.airconsole.com/api/airconsole-1.9.0.js) to view exactly what each of these is used for.
:::BlockQuote
While “AirConsole Hero” is the brand name of our premium subscription, the API itself only uses the generic term “premium”!
:::
### *A-B-Test for your own game!*
A-B-testing refers to trying two different versions at the same time with half of the audience and seeing which performs better.
It is impossible for us to compare conversion rates across games since these are influenced by a variety of factors. If you want to find the best way of offering premium-exclusive content in your game, we recommend you gather the relevant data yourself and see what works in your specific case.
:::BlockQuote
To make sure one player/group of players is always getting the same version, you can for example show version A or version B based on whether the screen’s UID is divisible by 2 or not. Gather this data using Google Analytics or Unity Analytics.
:::
[title] Quick Start
[path] Getting started with AirConsole/
For Unity games, please refer to our [Unity tutorial](https://developers2.airconsole.com/airconsole-unity-plugin).
### *General idea*
1. Create a new directory with two files screen.html and controller.html.
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-pYf4Y9aMZjhx0U9wJXcTL-20250303-115341.png" size="40" width="234" height="164" position="center" darkWidth="234" darkHeight="164" showCaption="false"}
2\. Include the [AirConsole JS API](https://aircn.sl/js-api) and use it to communicate between devices.
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-aEidQrS8JiA8OvV8dbnLf-20250303-115406.png" size="40" width="239" height="164" position="center" darkWidth="239" darkHeight="164" showCaption="false"}
3\. Host your files (local/remote) and call: **airconsole.com/#**http\://YOUR\_GAME\_URL/
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-Eu2hHO4ILHwwZuLmSQzLe-20250303-115426.png" size="30" width="116" height="164" position="center" darkWidth="116" darkHeight="164" showCaption="false"}
### *Step by step guide*
**Create files:**
Create a new directory for your game (E.g. game) and create two files in it:
**/game**
- screen.html
- controller.html
The screen.html is for the gameconsole's screen.
The controller.html are for the gameconsole's controllers (gamepads).
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-ApSCsHN9_ZLgLObHnPptK-20250303-115535.png" size="40" width="260" height="240" position="center" darkWidth="260" darkHeight="240" showCaption="false"}
:::hint{type="warning"}
Make sure both files can be accessed by: [http://your-local-webserver/screen.html](http://your-local-webserver/screen.html) (or /controller.html)
:::
If you don't want to create your own screen.html and controller.html right now and just play around, you can use our pong example [(pong.zip)](https://github.com/AirConsole/games-pong/archive/master.zip) from [the Classic Pong walkthrough](https://developers2.airconsole.com/pong-example).
**Include AirConsole Javascript API file:**
Include the AirConsole Javascript API in both files /screen.html and /controller.html
```html
```
**Send a message:**
Here is a simple example where the controller sends "*How are you?*" to the screen and the screen replies with "*Full of pixels!*"
/controller.html
```javascript
```
/screen.html
```javascript
```
**Test your game:**
You need to start a local webserver in your /game folder to serve the screen.html and controller.html
In this example we will host the two files on:
:::BlockQuote
http\://192.168.0.1:8080/screen.html
http\://192.168.0.1:8080/controller.html
:::
To run the game, go with the browser that should act as the screen to:
[https://www.airconsole.com/#http://192.168.0.1:8080/](http://www.airconsole.com/#http://192.168.0.1:8080/)
:::hint{type="danger"}
NOTE: there is NO screen.html at the end!
:::
there are problems with certain browsers like chrome not allowing access like this with http and https mixed. Alternatively you can use:
[http://http.airconsole.com/?http=1\&#http://192.168.0.1:8080/](http://http.airconsole.com/?http=1\&#http://192.168.0.1:8080/)
or use the simulator like desribed below
Game controllers (your smartphone) can join as usual over [www.airconsole.com](https://www.airconsole.com).
Enter the code you see on the screen.
When accessing the game with a separate device make sure the content (controller.html) is also accessible for that device under the url in the link ( in our example http\://192.168.0.1:8080/controller.html )
The devices should now exchange the messages.
**Simulator:**
If you append /simulator in the URL, then you will get a split view of the screen and two controllers:
[http://http.airconsole.com/simulator/#http://192.168.0.1:8080/](http://www.airconsole.com/simulator/#http://192.168.0.1:8080/)
This makes testing and developing a lot easier
:::hint{type="warning"}
If you run into issue with HTTPS (mixed content issues), refer to the [tunneling guide](https://developers2.airconsole.com/testing-with-your-phone#0a3QQ).
:::
**Device Ids - Important warning:**
Make sure you do not assume that the controllers have device\_ids 1, 2, 3 ... We strongly recommend you read the [device ids and states](https://developers2.airconsole.com/device-ids-and-state) guide!
**Next steps:**
Checkout the guide about our [pong example](https://developers2.airconsole.com/pong-example) or the [API](https://airconsole.github.io/airconsole-api/) to learn more about how to build games for AirConsole.
To getting started with uploading your game to AirConsole, you can log in here: [https://www.airconsole.com/developers](https://www.airconsole.com/developers)
[title] Game Viability Judging Criteria
[path] Creating and publishing your game/
When we receive a game for AirConsole, we have a variety of criteria that determine whether the game will be launched in the store, and whether it is good enough to be featured.
### *Basic Requirements*
What your game needs in order to be published in the AirConsole web store.
- There are no major bugs. The game has been tested thoroughly across Android and iOS controllers and various desktop browsers.
- Your game passes the [AirConsole checklist](https://developers2.airconsole.com/airconsole-checklist).
- You have read our [Best Practices guide ](https://developers2.airconsole.com/best-practices)and adapted your game accordingly.
- You have read our guide on [Smartphone Controllers ](https://developers2.airconsole.com/smartphones-as-controllers)and follow the basic do’s and don’ts.
- Your game doesn’t infringe on copyright and is free of content that is deceptive, misleading, false or threatening.
### *Advanced Requirements*
What your game needs in order to be featured at the top of the AirConsole store or win one of our game development contests.
- Your game has a consistent and appealing visual style
- Your game has fitting sound effects and music
- Your game has replay value and is interesting to play for longer than a few minutes
- Your game’s controls are completely intuitive and make sense for the platform
- Your game is easily understandable or has a good tutorial
:::BlockQuote
If you send us a version of your game, we will gladly provide feedback and point out what is missing for it to be launched.
:::
[title] Multi-screen multiplayer
[path] AirConsole Games Features/Main Screen & Controller/
:::BlockQuote
Prerequisites: API 1.9.0 or Unity Plugin 2.5.0 or higher
:::
## *Key concepts explained*
- An environment, as provided by AirConsole for the screen device, is a limited environment that the current screen is part of.
- A multi-screen multiplayer session is an online multiplayer session where AirConsole screens act as players in an online multiplayer game.
- The primary screen is the screen responsible for all decisions in an ongoing multi-screen multiplayer session.
- Secondary screens are additional screens in a multi-screen multiplayer session that have no responsibility and ability to make decisions.
- The primary controller is what you receive from the API using **getMasterControllerDeviceId()**.
- The primary multi-screen controller is the master controller of the primary screen.
- An environment defines a grouping of multiple screens that share one or more characteristics.
- An identifier in an environment enables the screen to identify the current (physical) environment they are in, like a specific car.
- A partner in an environment enables screens to identify other screens in a similar environment, for example the same brand of car.
## *Multi-screen multiplayer: What is it and how does it help us to make more engaging games?*
### *What is a multi-screen multiplayer game?*
A multi-screen multiplayer game in AirConsole is an online multiplayer game that uses additional information to
- enable matchmaking to allow screens in a single physical environment (a single car with multiple screens for example) to play together.
- enable matchmaking to allow screens on the same general environment (cars of a brand, web) to play together with a similar experience across multiple physical environments.
These new capabilities make it possible to create multiplayer games suitable for in-car entertainment that provide a comparable, fair experience to the different players.
### *How can my players play together on multiple screens in the same environment / car?*
To enable games to implement environment based multi-screen multiplayer gaming, AirConsole provides the **screen device** with information on the *environment* it is part of. This environment contains the so called *environment identifier* (**id**) that identifies the environment the screen is as uniquely as possible.
An example of such an environment can be a single car with one or more screens, which all share the same **id**.
To ensure reliability of multi-screen multiplayer game implementations created today, AirConsole always provides an *environment* with a valid **id** and **partner**.
For screens that are not part of a specific physical environment, an *environment* with a generic **id** and **partner** is provided. Players in this case would play against other screens purely online without being in physical proximity to each other.
### *How can the environment identifier be used to enable multiple screens in the same environment to play together?*
After the *environment* with its **id** is obtained on the web or in Unity, the game can use this information to identify waiting games from other screens in the same physical environment.
Example usages of the **id** would be:
- In a solution like [Photon Fusion](https://www.photonengine.com/fusion), the environment id can be used as the SessionName in the StartGameArgs to either start or join the same game session of this particular car.
- In a solution like [Photon Realtime](https://www.photonengine.com/realtime), the environment id can be used as the room name to either create or join the same room of this particular car.
This way, the game can ensure that only players in the same physical environment can play together, while those without a specific physical environment can play.
It is in this context simplest to think of a screen as a **group of players** that in the multiplayer context act like a single player. One of the screens, we call it *primary screen*, would be the *primary screen* that would be responsible to handle the configuration of the multi-screen multiplayer session. The *primary multi-screen controller* of this *primary screen* is in that sense the *primary controller* for the whole session, while the main controller of the *secondary screen* must not have any special rights.
### *How can the partner be used to improve multiplayer games?*
After the *environment* with its **partner** is obtained on the web or in Unity, the game can use this information as a grouping parameter to provide match making between devices of the same platform or car brand.
- In a solution like [Photon Fusion](https://www.photonengine.com/fusion), the **partner **can be used in SessionProperty in the [Matchmaking API through StartGameArgs](https://doc.photonengine.com/fusion/current/manual/connection-and-matchmaking/matchmaking) to either start or join games running on the same partner platform.
- In a solution like [Photon Realtime](https://www.photonengine.com/realtime), the **partner **can be used in [OpJoinRandomRoomParams](https://doc.photonengine.com/realtime/current/lobby-and-matchmaking/matchmaking-and-lobby#filtering-room-properties-in-join-random) to enable random match making to only take place against other screens on the same partner platform.
## *Best Practices*
Best practice for multiplayer on multiple screens in the same environment / same car:
1. Query the multiplayer platform to see if a room / session with the same *environment ***id **already exists.
2. When the query result is received:
1. If a corresponding room / session exists, the screen should offer the option to join the other screen
2. If no corresponding room / session exists, the screen should offer the option to start a multiplayer game in the car.
In this case the screen starting the multiplayer would need to wait for the second screen to join and confirm their readiness before the multiplayer round starts.
Best practice for using the environment identifier and partner in multiplayer games:
- Unless there is a strong reason against it, always use the *environment* **partner** as
- a grouping parameter in room / session creation
- as a filter in match making
Together these will ensure that players on the same platform or car brand with similar performance metrics play together.
- when multi-screen multiplayer in a single physical enviroment is supported
- use the *environment* **id **as room / session name
- use the *environment* **id **to query for pending games in the same physical environment and join them
Best practice for handling screens and master controllers
- Only a single controller must be considered the *primary multi-screen controller *of all screens after multiple screens are in the same session.
- Only the *primary screen *must be able to configure and control the multi-screen multiplayer session.
- When the *primary screen* leaves the multi-screen multiplayer session
- one of the *secondary screens *needs to be promoted to become the *primary screen.*
- only the new new *primary screen *must have the ability to end the multi-screen multiplayer session to continue on a single screen.
In consequence the *master controller *of the new *primary screen *also becomes the new *primary multi-screen controller.*
## *How to access the environment information*
### *On the web*
```javascript
var partner = undefined;
var environmentId = undefined;
if (airconsole.devices[AirConsole.SCREEN].hasOwnProperty("environment") {
var environment = airconsole.devices[AirConsole.SCREEN].environment;
environmentId = environment.id;
partner = environment.partner;
}
```
:::BlockQuote
var environmentId = undefined;
var partner = undefined;
var airconsole = new AirConsole(\{});
// somewhen later for example as you reach the multiplayer matchmaking part of your game
if (airconsole.devices\[AirConsole.SCREEN] && airconsole.devices\[AirConsole.SCREEN].hasOwnProperty("environment")) \{
var environment = airconsole.devices\[AirConsole.SCREEN].environment;
environmentId = environment.id;
partner = environment.partner;
}
:::
You also get this through the **onDeviceStateChange **event, checking for the sending device\_id === AirConsole.SCREEN and then accessing **device\_state.environment.id**. Be aware that the initial device state update might not yet contain the information, so always check if **device\_state.hasOwnProperty("environment")**.
:::BlockQuote
var airconsole = new AirConsole(\{});
airconsole.onDeviceStateChange = handleOnDeviceStateChanged;
function handleOnDeviceStateChanged(device\_id, device\_state) \{
if (device\_id === AirConsole.SCREEN && device\_state.hasOwnProperty("environment")) \{
const \{ environmentId, partner } = device\_state.environment;
// do something with the partner and environmentId or do something with device\_state.environment itself.
}
}
:::
### *In Unity*
:::BlockQuote
JToken deviceData = AirConsole.instance.devices\[AirConsole.SCREEN];
JToken environment = deviceData?\["environment"];
string partner = environment?\["partner"]?.ToString();
string environmentId = environment?\["id"]?.ToString();
:::
You can also get it from the onDeviceStateChange event
:::BlockQuote
AirConsole.instance.onDeviceStateChange += HandleOnDeviceStateChange;
void HandleOnDeviceStateChange(int device\_id, JToken device\_data) \{
JToken environment = device\_data?\["environment"];
string partner = environment?\["partner"]?.ToString();
string environmentId = environment?\["id"]?.ToString();
// do something with the partner and environmentId or do something with environment itself.
}
:::
[title] Generate income with your game
[path] /
[title] Untitled
[path] Reference/
[title] Testing with your Phone
[path] AirConsole Games Features/Connect to your game/
If you are on a public wi-fi such as at a university, library or game jam site, you may run into trouble connecting your phone, getting stuck on the loading screen instead. You can work around this by using tool like Cloudflare Tunnels or the paid version of ngrok, which lets you expose local servers to the public internet over secure tunnels.
**When is this guide relevant to you?**
This will help you if you can open and play your game with virtual controllers in Unity, but are not able to connect an actual phone.
Most likely, your phone will remain stuck on the Loading screen with the AirConsole logo and three dots visible.
This workaround can also be used if your phone and your computer cannot be connected to the same WiFi for any reason, for example because your computer is connected to a hotspot coming from your phone itself.
### *Using Local IP Override to test easily*
To configure the public HTTPS address using the *Local IP Override* of your AirConsole component, you need at least v2.14 of the AirConsole Unity Plugin
1. Setup and run cloudflared to match your needs following the Install and run cloudflared guide below.
2. Select your AirConsole game object and set your *Browser Start Mode *to **Normal or Debug.**
3. Copy your public https URL into the *Local IP Override *field.
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/kZoMSXe6Hg_E8jpLafVA0_image.png" size="70" width="438" height="331" position="center" showCaption="false"}
Start the play mode using *Edit > Play *or press *Ctrl/Cmd + P*.
### *Install and run cloudflared*
**If you only need access to your Unity playmode:**
- Follow the installation instructions for the [Cloudflared Quick Tunnel.](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)
- Start it using
`cloudflared tunnel --url http://localhost:7842`
(the webserver port configured in your AirConsole settings)
- When running the cloudflared quick tunnel, you will receive a randomized URL like the one shown below to copy into the **Local IP Override:**
:::BlockQuote
Every time you run *cloudflared tunnel --url http\://localhost:7842* the resulting URL will change and need to be copied into the **Local IP Override** again.
:::
**If you need access to multiple ports including Unity playmode for your testing**
- Follow the installation instructions at [Create CloudFlare Local Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel/)
- In the config.yaml, replace *url: http\://localhost:8000 *with *url: http\://localhost:7842*
- Insert the url you configured in config.yaml into the Local IP Override field. This will not change between executions of cloudflared.
[title] Device Ids and state
[path] Getting started with AirConsole/
It's important to know that in AirConsole controllers can join and leave at any time.
Some developers have wasted a lot of hours debugging, because they did not understand the following points.
### *Device IDs*
Every device in a AirConsole session has a device\_id.
The screen always has device\_id 0. You can use the `AirConsole.SCREEN` constant instead of 0.
All controllers also get a device\_id.
:::BlockQuote
Do not hardcode controller device_ids! You can NOT assume that the device_ids of controllers are consecutive or that they start at 1.
:::
Within an AirConsole session, devices keep the same device\_id when they disconnect and reconnect. Different controllers will never get the same device\_id in a session. Every device\_id remains reserved for the device that originally got it.
`airconsole.getControllerDeviceIDs();` returns all currently connected controllers that have loaded your game.
### *setActivePlayers to the rescue!*
(AirConsole API 1.3.0 and above)
Devices can join and leave at any point in time during an AirConsole Session.
When you're game is loaded, maybe only controller device\_ids `[3, 7, 12]` are still present and NOT `[1, 2, 3]`.
This is where `setActivePlayers()` comes into play. You don't have to use this helper function, but this mechanism is very convenient if you want to know which device is the first player, the second player, the third player ...
`airconsole.setActivePlayers()` takes all currently connected controllers and assigns them a player number. The assigned player numbers always start with 0 and are consecutive. You can hardcode player numbers, but not device\_ids. Once the screen has called `airconsole.setActivePlayers()`, you can get the device\_ids of players by calling:
- `airconsole.convertPlayerNumberToDeviceId(0)` for the first player
- `airconsole.convertPlayerNumberToDeviceId(1)` for the second player
- `airconsole.convertPlayerNumberToDeviceId(2)` for the third player
- ...
You can also convert device\_ids to player numbers by calling `airconsole.convertDeviceIdToPlayerNumber(device_id)`. You can get all device\_ids that are active players by calling `airconsole.getActivePlayerDeviceIds()`.
The screen can call this function every time a game round starts.
:::BlockQuote
In the beginning of a round in your game the screen can call `airconsole.setActivePlayers()`. Then you can easily send a message to the first player by calling `airconsole.message(airconsole.convertPlayerNumberToDeviceId(0), "Hello first player!")`
:::
### *Custom Device States*
Custom Device States are really powerful!
`airconsole.setCustomDeviceState(custom_data)` sets data for a device, readable by all other devices at any point in time. `airconsole.onCustomDeviceStateChange(device_id, custom_data)` will be called on all other devices, when data is set for a device - **even if a device joins at a later point** and was not connected when the data was set.
:::BlockQuote
A typical use case for custom device states is to control what "view" is displayed on the controller. Check out [https://github.com/AirConsole/airconsole-view-manager](https://github.com/AirConsole/airconsole-view-manager) if you want to do this.
:::
`airconsole.setCustomDeviceStateProperty(key, value)`sets a single property in the custom device state, instead of overwriting the whole object.
`airconsole.getCustomDeviceState(device_id)`gives you access to any devices custom device state at any point in time.
With Custom Device States you do not have to send messages to devices that connect after the games has already started with information about "state" of the game.
**A Custom Device State example**
If a player chooses to be the color blue, he sets his custom device state with `airconsole.setCustomDeviceStateProperty("my_color", "blue")`.
All present devices will get notified with `airconsole.onCustomDeviceStateChange(device_id, {"my_color": "blue", [...]})`.
If a new device joins later it will also get notified with `airconsole.onCustomDeviceStateChange(device_id, {"my_color": "blue", [...]})`right after `onReady`gets called.
[title] Best practices
[path] Creating and publishing your game/
Try the [AirConsole Checklist](https://developers2.airconsole.com/airconsole-checklist) before submitting your game!
### *General*
1. Try to test your game on as many as different phones and screens as possible.
2. Make sure all resources (external JS, CSS files etc.) can be loaded over https.
3. Games shouldn't request a separate login.
4. Having problems during development? Check the [airconsole tag on StackOverflow ](http://stackoverflow.com/questions/tagged/airconsole)- somebody might have had the same issue before.
### *Controller - Technical*
- Use `
Loading ...\
\
\Controller ...\
:::
The css *.view* class helps us to define a general style for all containers. In the beginning, every container is invisible:
:::BlockQuote
// CSS style
.view \{
display\:none;
}
:::
Now, when we open the controller.html we would see nothing, because every container is set to *display\:none*.
To handle views and show/hide them we will write some Javascript. The main procedure to show one view is:
- Hide all containers (By class .view)
- Show the container by id
:::BlockQuote
\
```
The controller will send a message back to the screen and trigger`AirConsole.onDeviceJoin`events in Construct2, which you will also have to add. :)
### *Controller messages*
To send a message from a controller to the screen you have to stick to certain keys in the JSON data you send, so that the Construct2 plugin knows which condition you want to trigger.
| Key | Type | Description |
| ---------------------------------------- | ------------ | ----------------------------------------------------------------------- |
| `handshake` | *\`mainTemplate.gradle is using the old aaptOptions noCompress property definition does not include types defined in unityStreamingAssets constant.` | Edit **Assets/Plugins/Android/mainTemplate.gradle** and **launcherTemplate.gradle** to add/replace the **aaptOptions** section to the following:
:::BlockQuote aaptOptions \{ noCompress = \['.ress', '.resource', '.obb'] + unityStreamingAssets.tokenize(', ') ignoreAssetsPattern = "!.svn:!.git:!.ds\_store:!\*.scc:.\*:!CVS:!thumbs.db:!picasa.ini:!\*\~" }\*\*PACKAGING\_OPTIONS\*\* :::
Check [Unity support](https://developers2.airconsole.com/faq-help) for more details. | | Unity 2021+ | After importing the AirConsole plugin into Unity you may get this error:
`Multiple precompiled assemblies with the same name Newtonsoft.Json.dll included on the current platform. [...]` | Delete the following plugin file (It is now included in Unity directly and is not needed in newer Unity versions): `Assets/AirConsole/plugins/Newtonsoft.Json.dll` | | Unity 2018.3 | After importing the AirConsole plugin into Unity you may get:
`The type or namespace name 'ILGenerator' could not be found (are you missing a using directive or an assembly reference?) and The type or namespace name 'DynamicMethod' could not be found (are you missing a using directive or an assembly reference?)` | Set the **API Compatibility Level** to **.NET 4.x** in the Player Settings of your selected Platform.
Check [AirConsole FAQ](https://developers2.airconsole.com/faq-help) for more details. | ### *Download* **Download from Github** Download the newest AirConsole-Unity-Plugin on our [GitHub repository](http://github.com/AirConsole/airconsole-unity-plugin). You can find the newest ".unitypackage" file in the "Builds" folder. **Download from Assetstore** [Unity Store](https://assetstore.unity.com/packages/tools/game-toolkits/airconsole-42776) ### *Video Tutorial* Learn the basics of how to make an AirConsole game in Unity in just 4 minutes. ::embed[]{url="https://www.youtube.com/embed/omKvqRZbfY8"} ### *Installation* To import the plugin, click on `Assets > Import Package -> Custom Package` and choose the downloaded `*.unitypackage` file. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/DLJWExYYGEHZ5ObQU96KQ_image.png" size="80" width="456" height="246" position="center" showCaption="false"} Make sure that all assets are selected and click on "Import". ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/X8uCcFWbrtCI_jfMYyZ27_image.png" size="70" width="366" height="384" position="center" showCaption="false"} **Instantiate AirConsole object** To set up the communication inside a scene, you have to instantiate the AirConsole object. In the Hierarchy window, click on `Create > Create Other > AirConsole`. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/DoLR-NMNEqNINm-PjJUhD_image.png" size="60" width="350" height="270" position="center" showCaption="false"} The AirConsole object offers you the following options: | Option | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Browser Start Mode | As soon as you press the “Play” button in Unity, your default browser will open the AirConsole simulator in the chosen mode. | | Controller Html | Link your controller.html file to this inspector variable, otherwise you can’t start the AirConsole simulator and you will get an error message. (Note: if your controller needs additional files like images or fonts, put them in the folder “Assets/WebGLTemplates/AirConsole”) | | Auto Scale Canvas | This option is enabled by default and scales your final webgl canvas automatically to the window size. The aspect ratio will be kept during the scaling. | ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/78kUQccxPrshav9aLnUWq_image.png" size="60" width="321" height="283" position="center" showCaption="false"} :::BlockQuote **Note:** the AirConsole object survives a scene change by default, so you don’t have to worry about the connections and device states when changing a level inside Unity). ::: ### *Quick example* Here is a simple example where the controller sends "How are you?" to the screen and the screen replies with "Full of pixels!" Include the AirConsole Javascript API in your controller.html file: :::BlockQuote \ ::: **/controller.html** :::BlockQuote var air\_console = new AirConsole(); air\_console.message(AirConsole.SCREEN, "How are you?"); ::: **Unity** To be able to receive a message in Unity, create a new Unity MonoBehaviour class and include these namespaces: :::BlockQuote using NDream.AirConsole; using Newtonsoft.Json.Linq; ::: Add an event handler in the Start method of the MonoBehaviour class: :::BlockQuote void Start() \{ AirConsole.instance.onMessage += OnMessage; } void OnMessage(int from, JToken data) \{ AirConsole.instance.Message(from, "Full of pixels!"); } ::: :::BlockQuote **Note:** make sure to only send JSON supported data types between the controller.html file and Unity. The AirConsole-Unity-Plugin exchanges data via a modifed version of the popular JSON.NET library. The plugin delivers received data inside Unity as JToken objects. You can check the documentation of JSON.NET here: [http://www.newtonsoft.com/json/help/html/N\_Newtonsoft\_Json\_Linq.htm](http://www.newtonsoft.com/json/help/html/N_Newtonsoft_Json_Linq.htm) ::: ### *JToken parse example* When you send an object like this one on the controller.html side: :::BlockQuote // Javascript var message = \{ 'action': 'move', 'info': \{ 'amount': 5, 'torque': 234.8 } }; air\_console.message(AirConsole.SCREEN, message); ::: You can parse the object in Unity like this: :::BlockQuote // C# void OnMessage(int from, JToken data) \{ string action = (string) data\["action"]; int amount = (int) data\["info"]\["amount"]; float torque = (float) data\["info"]\["torque"]; } ::: :::BlockQuote Note: when you receive JToken data in Unity, you have to cast the object to get the right data type. ::: To send the same data from Unity you can use dynamic vars: :::BlockQuote // C# var message = new \{ action = "move", info = new \{ amount = 5, torque = 234.8f } }; AirConsole.instance.Message(device\_id, message); ::: ### *Test your game* To test your game, just hit the “Play” button inside the Unity-Editor. If you want to test the final WebGL-Build, choose the right AirConsole Template in the PlayerSettings first (For Unity versions 2020 and up choose the **AirConsole-2020** template, for previous Unity versions choose the **AirConsole** template): ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/0A4IF7aN04TvX6GBCPwQm_image.png" size="80" width="400" height="379" position="center" showCaption="false"} Now you can export your Unity project in the Build-Settings (choose “Build” instead of the “Build and run” button). As soon as your build is exported, the button “Open Exported Port” on the AirConsole object in your scene will appear. By pressing this button, the AirConsole simulator will start with your final build. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/rbRSVhPH6n-smRLYYvL54_image.png" size="50" width="250" height="178" position="center" showCaption="false"} :::BlockQuote **Note:** the "Open Exported Port" button is only available as long as you don’t change the last target location of your exported build. ::: :::BlockQuote **Note:** AirConsole uses the Unity WebGL Custom Progress Bar by Alexander Ocias for WebGL builds: https\://ocias.com/ ::: :::BlockQuote **IMPORTANT:** before you can build the WebGL port, you have to start the game at least once in the Editor to generate all important metafiles for the final build. ::: ### *Examples* - AirConsole/Examples/Basic/basic.scene: In this example all possible API functions are listed & used. - AirConsole/Examples/Pong/pong.scene: This example contains a simple pong game with a specific controller. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/uOouAd15U-Yv5oP61kD32_image.png" size="60" width="895" height="557" position="center" showCaption="false"} ### *Settings* You can open the settings window by clicking on the "Settings" button on the inspector of the AirConsole object or by navigating over the menu bar `AirConsole > Settings`. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/qXF2nNM3Genls_VRzoHra_image.png" size="60" width="417" height="147" position="center" showCaption="false"} In the "Settings" window, the ports for the internal web socket and web server can be changed, should the default ports already be occupied. :::BlockQuote **Note:** These ports are only needed for the AirConsole simulator inside the Unity Editor. The final WebGL port will not use any of these ports. ::: You can stop and restart the internal web server in case the AirConsole simulator isn't working properly. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/eODGJqzvP6Walum1Gn5N9/rEp6aJltjg85SAZsIlk6E_image.png" size="60" width="336" height="278" position="center" showCaption="false"} ### *AirConsole, Unity and AndroidTV* AirConsole also provides an AndroidTV app, so that user can play your games also on a smart-tv. Please read the ["AirConsole Unity on AndroidTv"](https://developers2.airconsole.com/unity-game-on-android-tv) documentation to adapt your game for AndroidTV. [title] Creating and publishing your game [path] AirConsole Games Features/ [title] Archive [path] / [title] Pong Example [path] Example games in web / unity/ In this example you will learn how to use the AirConsole API to communicate between a screen and controllers in a simple Pong-game. You can play the game here: [https://www.airconsole.com/#https://game.airconsole.com/com.airconsole.testpong.cdn.airconsole.com/2024-02-14-14-52-40/](https://www.airconsole.com/#https://game.airconsole.com/com.airconsole.testpong.cdn.airconsole.com/2024-02-14-14-52-40/) to get a better idea about what we are gonna talk about :)  You can check the game code here: [View code.](https://github.com/AirConsole/games-pong) To download the game, use the following link: [Download pong.zip](https://github.com/AirConsole/games-pong/archive/master.zip) ### *Basic message exchange between a screen and controllers:* AirConsole and its API makes it very easy for game developers to build games, which can be controlled by a smartphone - instead of e.g. a keyboard or a mouse. The whole communication can be pretty much summed up with two methods of the API:`onMessage()`and`message()`. All devices (screen and controllers) share the same API - thus there are (almost) no controller or screen specific methods for the communication. In the following we will explain you in detail how players can control their paddles in a simple, but fun game like Pong.  ### */screen.html* Start a local webserver of your choice and create a `/screen.html` in the root directory. :::BlockQuote You can check the code of the whole `screen.html` in [this repo](https://github.com/AirConsole/games-pong/blob/master/screen.html) ::: Include the AirConsole API file: | | \ | | - | --------------------------------------------------------------------------------------------------------- | Our game will run on a canvas element, have a score and a "wait message". As soon as the document is ready, we call the`init()`function. ```html
0:0
` tags with a background-image style as buttons instead of `` or `![]()
` tags.
- Use `touchstart`and `touchend`for event handlers instead of `click`or `mousedown`.
:::BlockQuote
var button = document.getElementById('button\_1');
button.addEventListener('touchstart', touchdownHandler);
button.addEventListener('touchend', touchendHandler);
:::
Or try the [airconsole-controls](https://github.com/AirConsole/airconsole-controls) library, which already takes care of this.
- Preload your images in the beginning
:::BlockQuote
// For example in javascript:
var images = \['button\_1.png', 'button\_2.png', 'character\_1.png'];
for (var i=0; i \< images.length; i++) \{
var img = new Image();
img.src = 'assets/images' + images\[i];
}
:::
### *Controller - Design*
- Always indicate which ingame-character the player is controlling.
:::BlockQuote
E.g. If the player is controlling the blue character in the game, then make the controller interface blue.
:::
- Avoid having unnecessary buttons
:::BlockQuote
E.g. you can just go left and right, so you don’t need a 4-directional-dpad
:::
- Show different states on the phone instead of always showing the ingame controller.
:::BlockQuote
If a player dies in the game and the game is still running, then show a “You are dead” view on the players controller.
:::
- Make sure the user-flow works. From Menu -> Game -> Game End -> Menu
### *Screen / Game*
- Explain your game to your players.
:::BlockQuote
E.g. with an intro-screen or a tutorial. Make sure that it's not too easy to skip the instruction screen by accident.
:::
- Check what happens if a player joins or leaves during a running game.
- If your game needs more than 1 Player, display it in the start screen.
- If your game has a max player amount, display a “max player reached” if too many players connected.
- Do not use device ids as player numbers. Device ids may not be consecutive, there may be devices that were connected but have left. [Read more](https://developers2.airconsole.com/device-ids-and-state)
- Instead of showing "Player 1", try to show the real player name (`(airconsole.getNickname()`).
- Be aware that players may have a high latency.
### *Unity*
- Export your game early and often! Some issues may not appear in the editor and cause unpleasant surprises if you export it for the first time right before launch time.
- Images and JavaScripts need to be in `WebGLTemplates/AirConsole`so your screen and controller can access them in the exported build.
- Use the Profiler to pinpoint performance issues and optimize them.
- Read up on the limitations of WebGL early enough so you don’t spend time on features that can’t be used in the exported version.
- Having memory issues? Can you reduce the number of GameObjects in your game, for example? If not, consider increasing the memory size in Build Settings -> Publishing Settings.
- Avoid Exceptions at all costs, because they will cause crashes in the WebGL export. If you’re getting an exception and don’t know why, make a debug build with Build Settings -> Publishing Settings -> Enable Exceptions set to “Full” and then look at the Console in your browser to see a precise error message.
[title] Smartphones as Controllers
[path] AirConsole Games Features/Main Screen & Controller/
The smartphone controllers are simultaneously one of the biggest challenges in developing games for AirConsole and also the aspect with the most potential for true innovation.
When developing an AirConsole game, the smartphone controls should be an integral part of early gameplay prototyping, since some mechanics that work with a gamepad will often feel subpar when controlled with a smartphone.
While we are proud of the over 100 games the AirConsole store currently offers, we believe that we have barely scratched the surface of what is possible in regards to innovative, intuitive and fun smartphone controlled local multiplayer games.
### *Main Takeaways*
- Use different controller views / layouts for different situations
- Label buttons / interactive areas with their actual function
- Make all buttons / interactive areas as big as possible
- Make use of personalized controllers for individual players
- Do not use d-pads and virtual joysticks
- Play existing AirConsole games to see which control schemes feel good and which don’t\*
:::BlockQuote
\*Feel free to ask the AirConsole team or our [developer community on Discord](https://discordapp.com/invite/5BzND3v) for recommendations for a specific type of game or control scheme you are interested in.
:::
### *Smartphones are not gamepads*
When designing a smartphone controller layout, the first and most important thing to realize and remember is that a smartphone screen is not a regular gamepad / xbox controller and should not be treated as such.
This provides some challenges, but also has its advantages:
**Pro: Individual Layouts**
The controller screen can be adjusted to meet any ingame situation and mechanic it needs to: whether you need it to only display a single big button or you want to let the player play an entire minigame on it.
Instead of having buttons (or other interactive areas) labelled with “A”, “B” or “X”, you can label all touch areas directly with their function and don’t need to include captions for them on the main screen.
**Pro: Personalized Information**
Every individual player can have their own controller view. This can be used for something as simple as displaying the player color, but you can also convey secret information (cards, items, secret objectives) or design asymmetrical input schemes where different players have different roles and input options.
**Pro: Input Variety**
Virtual buttons are not the only way to register input from a smartphone. Besides button taps, your game input can also use swiping and the phone's gyroscope, or even its camera, speakers or microphone. Everything that works in a mobile browser is possible on AirConsole.
**Con: No Tactile Feedback**
The most significant disadvantage smartphone controllers have over regular gamepads is the lack of tactile feedback: A player’s finger may slip over the screen while they are not looking down, and the player might not realize that their finger is no longer on the button or interactive area, which leads to frustration.
To combat this, interactive areas / buttons on AirConsole controllers should be made as big as possible, reducing the chance of players tapping empty space and growing frustrated.
### *Views*
**What are views?**
What we call views are different controller layouts for different ingame situations.
In the pictures below, you can see the “Ingame” and “Pause” views for [Dust Squad - Tanks For Nothing](https://www.airconsole.com/play/dust-squad).
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-_g5ryvfDApdrbIknl0c-X-20250304-085105.png" size="70" width="562" height="357" position="center" darkWidth="562" darkHeight="357" showCaption="false"}
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-22ZjglfQCph63Jnwh00DP-20250304-085124.png" size="70" width="565" height="359" position="center" darkWidth="565" darkHeight="359" showCaption="false"}
Views can be updated for more specific and/or frequently changing situations too. Three examples from Dust Squad where the view shows that
1. the player’s weapon is currently on cooldown
2. the player is close to Hero Exclusive content and can buy a subscription here
3. the player has died and is waiting for respawn
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-rzaz7j0419wImrlEj1dPm-20250304-090027.png" size="70" width="1133" height="721" position="center" darkWidth="1133" darkHeight="721" showCaption="false"}
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-mqWdmmYuezbsgDjVzjk9d-20250304-090050.png" size="70" width="565" height="359" position="center" darkWidth="565" darkHeight="359" showCaption="false"}
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-JJ-Yw3b5qdNZKN-jeaggf-20250304-090108.png" size="70" width="564" height="358" position="center" darkWidth="564" darkHeight="358" showCaption="false"}
**How do I change views?**
We leave the exact implementation to you, but we recommend using Custom Device States and not messages to change your views.
We also recommend using the [AirConsole View Manager](https://github.com/AirConsole/airconsole-view-manager). With it you can add the ‘view’ class to div containers and easily show one of them and hide all others.
**Using Screen Estate**
Input fields (buttons, swipe areas etc.) should always be as big as possible, so that they are hard to miss. Reduce the number of different input fields by only showing the ones that are currently needed and updating the controller view whenever necessary.
*Bad:*
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-R502aMAjutnAlz5ERJHwk-20250304-085902.jpg" size="70" width="800" height="450" position="center" darkWidth="800" darkHeight="450" showCaption="false"}
*Good:*
::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/L3gEEzW6h4GKdEukxKEmf-7crbyinKbSX8ghp2bEGAm-20250304-085929.jpg" size="70" width="800" height="450" position="center" darkWidth="800" darkHeight="450" showCaption="false"}
### *Visuals*
The controller’s visual design should fit the ingame graphics and big screen UI, adding up to an aesthetically pleasing whole picture.
When it comes to developing a UI art style with smartphone controllers in mind, it is helpful to use elements that can be stretched instead of relying on exact angles or aspect ratios. This can make the implementation for different phone screen resolutions with HTML/css easier.
### *Joysticks & D-Pads*
Virtual joysticks and movement D-Pads ***do not work*** for AirConsole. We have several games that use them, but free character movement with analogue sticks or directional buttons will ***always*** feel subpar on a smartphone controller in comparison to a gamepad.
This means that you cannot rely on including “character movement” in your game design without giving serious thought to how exactly it will work with a smartphone.
How character movement should work instead depends heavily on the game and there is no universal answer for how to solve this issue. This limitation should be considered in your game design from the very beginning.
### *Haptic Feedback*
Give you players more control over their actions by letting them feel what they are doing with haptic feedbacks.
Be it direct feedback of the controls just on the controller side or vibrations triggered by ingame events happening on the screen.
The controller app of AirConsole for iOS and Android gives you more control over vibrations on the controller devices. With the [vibrate](https://airconsole.github.io/airconsole-api/AirConsole-Controller_Inputs.html#vibrate) function of the AirConsole API you can play several vibration primitives and chain them together to form a more complex pattern.
Use the Composition vibration interface to play vibration primitives by passing the VibrationOptions to the vibrate function:
:::BlockQuote
airconsole.vibrate(\{
type: AirConsole.VIBRATE.TYPE.COMPOSITION,
value: \[
\{
primitive: AirConsole.VIBRATE.PRIMITIVE.THUD,
scale: 0.8,
}
]
})
:::
The above code is playing a vibration pattern that emulates a thud with a strength of `0.8`.
You can find all the available primitives in our API documentation.
To be able to create more complex pattern you can chain two or more primitives together to create a new pattern that can be executed with one call.
:::BlockQuote
airconsole.vibrate(\{
type: AirConsole.VIBRATE.TYPE.COMPOSITION,
value: \[
\{
primitive: AirConsole.VIBRATE.PRIMITIVE.QUICK\_FALL,
scale: 0.8,
},
\{
primitive: AirConsole.VIBRATE.PRIMITIVE.TICK,
scale: 0.9,
delay: 10,
},
]
})
:::
The example above plays a quick fall vibration followed by a short tick vibration effect with a delay of 10ms after the quick fall has completed.
Please note that executing vibrations also drains the battery. Also make sure that you don't over do it an numb you players hands.
[title] How we achieve low latency
[path] AirConsole Games Features/Connect to your game/
[title] Phaser 2 Game Example
[path] Archive/