BodyController API
The NUI Service tracks the human bodies inhabiting the room that can interact with Xbox One. The BodyController API integrates into the User Manager to provide the system and apps with awareness of these bodies and their associations with users and other forms of input.
Overview
The BodyController API supports the following types of scenario:
- Two users are taking turns bowling. The app is able to differentiate the players as they come and go from the field of view.
- A guest walks into the living room and picks up a gamepad to enjoy an arcade racing game in progress. He can instantly begin steering with the gamepad and leaning his body for tighter turns, even before he’s signed in.
- A user chooses to play as his friend to help him earn achievements. Even though he’s signed in as his friend, the system can remember him as he leaves and returns to the field of view, correctly rewarding his friend with progress in the game.
The BodyController API provides dedicated functionality for managing human bodies and their associations to users on the system. Rather than having to query for all IControllers and filter out the ones of type “…Nui.Body”, the BodyController class provides means of directly accessing the list of bodies being tracked. Additionally, it provides dedicated events for when bodies are added and removed from the system. Finally, it provides a biometric user identifier, an efficient way to maintain continuity of experiences when users leave and re-enter the field of view.
BodyController::User provides information about which profile a body is acting on behalf of. In many cases, this will be the same user represented by the BiometricUserId property. However, there are common, legitimate reasons why the User object does not always represent the user’s true identity, for example:
- The user may choose to play as another to help them in a game
- The user may choose to switch profiles to view another user’s profile-specific content (eg. Facebook)
- The user may just not want to be signed in but still want to participate in turn-taking / jump-in-jump-out experiences that require biometric identity
For gameplay situations where the game requires a consistent physical identity of the player, the BiometricUserId property should be used. For scenarios where the game simply needs to determine which profile the body controller is bound to, the BodyController.User property should be used.
Flow of Control
When a human body begins to be tracked by Kinect, it is represented as a BodyController. Its Id property corresponds to the Body.TrackingId property in the KinectSensor API. Its User property is null. Its BiometricUserId property is 0.
The system automatically starts trying to biometrically recognize the body. Once recognized, its BiometricUserId property gets set to a unique identifier of the recognized user on the console. The BiometricUserId property corresponds to the User.Id property of the identified user.
If that user then engages through gesture (holding their hand toward the sensor), voice (saying “Xbox”), or gamepad (picking up a gamepad), then they will be biometrically signed in, causing a User object to be added. Their BodyController’s User property will then be set to that User object. Once signed in, if that body stops and then starts being tracked again, when it’s subsequently recognized, its BiometricUserId will be set again, and its User property will be set to the recognized signed in user.
BodyController Properties
BodyController Class (defined in the Windows.Xbox.Input namespace) is a type of IController and contains the standard set of public properties:
- BodyController.BodyControllers Property (static): An IVectorView<IBodyController> that represents the list of all tracked bodies
- BodyController.Id Property: A uint64 that corresponds to the TrackingId of the body being tracked by the NUI Service.
- BodyController.Type Property: A string that represents the type of IController, “Windows.Xbox.Input.BodyController” for BodyController
- BodyController.User Property: The User that this BodyController is signed into the system as. This property is initially paired to a guest User object that is unique to the console and can be used to associate bodies and gamepads before the user is signed in as a local console user. The pairing will change as the body is signed in (or out) as local console users on the system.
- AssociatedControllerIds: A list of associated controller Ids. An associated controller is a controller that the user might have picked up, be wearing, or has somehow associated the device with themselves. This property will always represent the physical body-controller pairing. BodyControllers remain associated with a given controller until NUI detects that the controller has been positively handed off to another BodyController.
There is no set maximum of associated devices for one body controller, but the Xbox One does limit the total number of connected devices to eight. Typical associated devices are gamepads and steering wheels.
Additionally, BodyController contains an additional public property unique to this type:
- BodyController.BiometricUserId Property A uint32 that corresponds to the Id of the local console User that the BodyController has been identified as. This property is set as soon as the body has been biometric identified, regardless of the body’s sign-in state. Thus, it is useful for maintaining continuity of tracking as the user leaves and re-enters the field of view.
Note The BiometricUserId corresponds to a console-wide unique identifier for the User; it cannot provide or be associated to an Xbox Service-wide identifier for the User unless the user is signed in.
BodyController Events
BodyController contains the following public events:
- BodyController.BodyControllerAdded Event (static): A body has begun to be tracked by NUI Service. This event provides a BodyControllerAddedEventArgs object which contains the BodyController representing the added body.
- BodyController.BodyControllerRemoved Event (static): A body ceased to be tracked by NUI Service. This event provides a BodyControllerRemovedEventArgs object which contains the BodyController representing the removed body.
- BodyController.BiometricUserChanged Event: The body has been biometrically identified as a local console user. This event provides a BiometricUserChangedEventArgs object which contains the BiometricUserId representing the biometrically identified user.
- BodyController.BodyControllerRemoved Event: The user has removed an associated controller.
- BodyController.ReadingChanged Event: The body lean of the user has changed.
BodyController Methods
BodyController contains the following public method:
- BodyController.GetCurrentReading Method: gets the current body lean of the user.