--- title: Device Ids and state slug: device-ids-and-state docTags: createdAt: 2024-06-27T10:50:26.701Z --- 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.