Device Ids and state

4 min

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 \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 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 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