Device Ids and state

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.

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.

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.

(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:

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.

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.

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 onReadygets called.