Struct InputUser

Represents a specific user/player interacting with one or more devices and input actions.

Namespace: UnityEngine.InputSystem.Users
Syntax
public struct InputUser : IEquatable<InputUser>
Remarks

Principally, an InputUser represents a human interacting with the application. Moreover, at any point each InputUser represents a human actor distinct from all other InputUsers in the system.

Each user has one or more paired devices. In general, these devices are unique to each user. However, it is permitted to use PerformPairingWithDevice(InputDevice, InputUser, InputUserPairingOptions) to pair the same device to multiple users. This can be useful in setups such as split-keyboard (e.g. one user using left side of keyboard and the other the right one) use or hotseat-style gameplay (e.g. two players taking turns on the same game controller).

Note that the InputUser API, like InputAction) is a play mode-only feature. When exiting play mode, all users are automatically removed and all devices automatically unpaired.

Fields

InvalidId

Declaration
public const uint InvalidId = 0U
Field Value
Type Description
UInt32

Properties

actions

Actions associated with the user.

Declaration
public readonly IInputActionCollection actions { get; }
Property Value
Type Description
IInputActionCollection
Remarks

Associating actions with a user will synchronize the actions with the devices paired to the user. Also, it makes it possible to use support for control scheme activation (ActivateControlScheme(InputControlScheme) and related APIs like controlScheme and controlSchemeMatch).

Note that is generally does not make sense for users to share actions. Instead, each user should receive a set of actions private to the user.

See Also

all

List of all current users.

Declaration
public static readonly ReadOnlyArray<InputUser> all { get; }
Property Value
Type Description
ReadOnlyArray<InputUser>
Remarks

Use PerformPairingWithDevice(InputDevice, InputUser, InputUserPairingOptions) to add new users and UnpairDevicesAndRemoveUser() to remove users.

Note that this array does not necessarily correspond to the list of users present at the platform level (e.g. Xbox and PS4). There can be users present at the platform level that are not present in this array (e.g. because they are not joined to the game) and users can even be present more than once (e.g. if playing on the user account but as two different players in the game). Also, there can be users in the array that are not present at the platform level.

See Also

controlScheme

The control scheme currently employed by the user.

Declaration
public readonly InputControlScheme? controlScheme { get; }
Property Value
Type Description
Nullable<InputControlScheme>
Remarks

This is null by default.

Any time the value of this property changes (whether by ActivateControlScheme(String) or by automatic switching), a notification is sent on onChange with ControlSchemeChanged.

Be aware that using control schemes with InputUsers requires actions to be set, i.e. input actions to be associated with the user (AssociateActionsWithUser(IInputActionCollection)).

See Also

controlSchemeMatch

The result of matching the device requirements given by controlScheme against the devices paired to the user (pairedDevices).

Declaration
public readonly InputControlScheme.MatchResult controlSchemeMatch { get; }
Property Value
Type Description
InputControlScheme.MatchResult
Remarks

When devices are paired to or unpaired from a user, as well as when a new control scheme is activated on a user, this property is updated automatically.

See Also

hasMissingRequiredDevices

Whether the user is missing devices required by the controlScheme activated on the user.

Declaration
public readonly bool hasMissingRequiredDevices { get; }
Property Value
Type Description
Boolean
Remarks

This will only take required devices into account. Device requirements marked optional (isOptional) will not be considered missing devices if they cannot be satisfied based on the devices paired to the user.

See Also

id

The unique numeric ID of the user.

Declaration
public readonly uint id { get; }
Property Value
Type Description
UInt32
Remarks

The ID of a user is internally assigned and cannot be changed over its lifetime. No two users, even if not concurrently active, will receive the same ID.

The ID stays valid and unique even if the user is removed and no longer valid.

index

The sequence number of the user.

Declaration
public readonly int index { get; }
Property Value
Type Description
Int32
Remarks

It can be useful to establish a sorting of players locally such that it is known who is the first player, who is the second, and so on. This property gives the positioning of the user within all.

Note that the index of a user may change as users are added and removed.

See Also

listenForUnpairedDeviceActivity

Whether to listen for user activity on currently unpaired devices and invoke onUnpairedDeviceUsed if such activity is detected.

Declaration
public static int listenForUnpairedDeviceActivity { get; set; }
Property Value
Type Description
Int32
Remarks

This is off by default.

Note that enabling this has a non-zero cost. Whenever the state changes of a device that is not currently paired to a user, the system has to spend time figuring out whether there was a meaningful change or whether it's just noise on the device.

This is an integer rather than a bool to allow multiple systems to concurrently use to listen for unpaired device activity without treading on each other when enabling/disabling the code path.

See Also

lostDevices

Devices that were removed while they were still paired to the user.

Declaration
public readonly ReadOnlyArray<InputDevice> lostDevices { get; }
Property Value
Type Description
ReadOnlyArray<InputDevice>
Remarks

This list is cleared once the user has either regained lost devices or has regained other devices such that the controlScheme is satisfied.

See Also

pairedDevices

Devices assigned/paired/linked to the user.

Declaration
public readonly ReadOnlyArray<InputDevice> pairedDevices { get; }
Property Value
Type Description
ReadOnlyArray<InputDevice>
Remarks

It is generally valid for a device to be assigned to multiple users. For example, two users could both use the local keyboard in a split-keyboard or hot seat setup. However, a platform may restrict this and mandate that a device never belong to more than one user. This is the case on Xbox and PS4, for example.

To associate devices with users, use PerformPairingWithDevice(InputDevice, InputUser, InputUserPairingOptions). To remove devices, use UnpairDevice(InputDevice) or UnpairDevicesAndRemoveUser().

The array will be empty for a user who is currently not paired to any devices.

If actions is set (AssociateActionsWithUser(IInputActionCollection)), then devices will be kept synchronized with the devices paired to the user.

See Also

platformUserAccountHandle

Declaration
public readonly InputUserAccountHandle? platformUserAccountHandle { get; }
Property Value
Type Description
Nullable<InputUserAccountHandle>

platformUserAccountId

Declaration
public readonly string platformUserAccountId { get; }
Property Value
Type Description
String

platformUserAccountName

Declaration
public readonly string platformUserAccountName { get; }
Property Value
Type Description
String

valid

Whether this is a currently active user record in all.

Declaration
public readonly bool valid { get; }
Property Value
Type Description
Boolean
Remarks

Users that are removed (UnpairDevicesAndRemoveUser()) will become invalid.

See Also

Methods

ActivateControlScheme(String)

Declaration
public InputUser.ControlSchemeChangeSyntax ActivateControlScheme(string schemeName)
Parameters
Type Name Description
String schemeName
Returns
Type Description
InputUser.ControlSchemeChangeSyntax

ActivateControlScheme(InputControlScheme)

Declaration
public InputUser.ControlSchemeChangeSyntax ActivateControlScheme(InputControlScheme scheme)
Parameters
Type Name Description
InputControlScheme scheme
Returns
Type Description
InputUser.ControlSchemeChangeSyntax

AssociateActionsWithUser(IInputActionCollection)

Associate a collection of InputActions with the user.

Declaration
public void AssociateActionsWithUser(IInputActionCollection actions)
Parameters
Type Name Description
IInputActionCollection actions

Actions to associate with the user, either an InputActionAsset or an InputActionMap. Can be null to unset the current association.
Remarks

Associating actions with a user will ensure that the devices and bindingMask property of the action collection are automatically kept in sync with the device paired to the user (see pairedDevices) and the control scheme active on the user (see controlScheme).

var gamepad = Gamepad.all[0];

// Pair the gamepad to a user.
var user = InputUser.PerformPairingWithDevice(gamepad);

// Create an action map with an action.
var actionMap = new InputActionMap():
actionMap.AddAction("Fire", binding: "<Gamepad>/buttonSouth");

// Associate the action map with the user (the same works for an asset).
user.AssociateActionsWithUser(actionMap);

// Now the action map is restricted to just the gamepad that is paired
// with the user, even if there are more gamepads currently connected.
Exceptions
Type Condition
InvalidOperationException

The user instance is invalid.
See Also

CreateUserWithoutPairedDevices()

Declaration
public static InputUser CreateUserWithoutPairedDevices()
Returns
Type Description
InputUser

Equals(Object)

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
Object obj
Returns
Type Description
Boolean
Overrides

Equals(InputUser)

Declaration
public bool Equals(InputUser other)
Parameters
Type Name Description
InputUser other
Returns
Type Description
Boolean
Implements

FindUserByAccount(InputUserAccountHandle)

Declaration
public static InputUser? FindUserByAccount(InputUserAccountHandle platformUserAccountHandle)
Parameters
Type Name Description
InputUserAccountHandle platformUserAccountHandle
Returns
Type Description
Nullable<InputUser>

FindUserPairedToDevice(InputDevice)

Find the user (if any) that device is currently paired to.

Declaration
public static InputUser? FindUserPairedToDevice(InputDevice device)
Parameters
Type Name Description
InputDevice device

An input device.
Returns
Type Description
Nullable<InputUser>

The user that device is currently paired to or null if the device is not currently paired to an user.
Remarks

Note that multiple users may be paired to the same device. If that is the case for device, the method will return one of the users with no guarantee which one it is.

To find all users paired to a device requires manually going through the list of users and their paired devices.

Exceptions
Type Condition
ArgumentNullException

device is null.
See Also

GetHashCode()

Declaration
public override int GetHashCode()
Returns
Type Description
Int32
Overrides

GetUnpairedInputDevices()

Return a list of all currently added devices that are not paired to any user.

Declaration
public static InputControlList<InputDevice> GetUnpairedInputDevices()
Returns
Type Description
InputControlList<InputDevice>

A (possibly empty) list of devices that are currently not paired to a user.
Remarks

The resulting list uses Temp. If not disposed of explicitly, the list will automatically be deallocated at the end of the frame and will become unusable.

See Also

GetUnpairedInputDevices(ref InputControlList<InputDevice>)

Add all currently added devices that are not paired to any user to list.

Declaration
public static int GetUnpairedInputDevices(ref InputControlList<InputDevice> list)
Parameters
Type Name Description
InputControlList<InputDevice> list

List to add the devices to. Devices will be added to the end.
Returns
Type Description
Int32

Number of devices added to list.
See Also

PerformPairingWithDevice(InputDevice, InputUser, InputUserPairingOptions)

Pair the given device to a user.

Declaration
public static InputUser PerformPairingWithDevice(InputDevice device, InputUser user = default(InputUser), InputUserPairingOptions options = InputUserPairingOptions.None)
Parameters
Type Name Description
InputDevice device

Device to pair to a user.
InputUser user

Optional parameter. If given, instead of creating a new user to pair the device to, the device is paired to the given user.
InputUserPairingOptions options

Optional set of options to modify pairing behavior.
Returns
Type Description
InputUser
Remarks

By default, a new user is created and device is added pairedDevices of the user and DevicePaired is sent on onChange.

If a valid user is supplied to user, the device is paired to the given user instead of creating a new user. By default, the device is added to the list of already paired devices for the user. This can be changed by using UnpairCurrentDevicesFromUser which causes devices currently paired to the user to first be unpaired.

The method will not prevent pairing of the same device to multiple users.

Note that if the user has an associated set of actions (actions), the list of devices on the actions (devices) will automatically be updated meaning that the newly paired devices will automatically reflect in the set of devices available to the user's actions. If the user has a control scheme that is currently activated (controlScheme), then controlSchemeMatch will also automatically update to reflect the matching of devices to the control scheme's device requirements.

// Pair device to new user.
var user = InputUser.PerformPairingWithDevice(wand1);

// Pair another device to the same user.
InputUser.PerformPairingWithDevice(wand2, user: user);
See Also

ToString()

Declaration
public override string ToString()
Returns
Type Description
String
Overrides

UnpairDevice(InputDevice)

Unpair a single device from the user.

Declaration
public void UnpairDevice(InputDevice device)
Parameters
Type Name Description
InputDevice device

Device to unpair from the user. If the device is not currently paired to the user, the method does nothing.
Remarks

If actions are associated with the user (actions), the list of devices used by the actions (devices) is automatically updated.

If a control scheme is activated on the user (controlScheme), controlSchemeMatch is automatically updated.

Sends DeviceUnpaired through onChange.

Exceptions
Type Condition
ArgumentNullException

device is null.
See Also

UnpairDevices()

Unpair all devices from the user.

Declaration
public void UnpairDevices()
Remarks

If actions are associated with the user (actions), the list of devices used by the actions (devices) is automatically updated.

If a control scheme is activated on the user (controlScheme), controlSchemeMatch is automatically updated.

Sends DeviceUnpaired through onChange for every device unpaired from the user.

See Also

UnpairDevicesAndRemoveUser()

Unpair all devices from the user and remove the user.

Declaration
public void UnpairDevicesAndRemoveUser()
Remarks

If actions are associated with the user (actions), the list of devices used by the actions (devices) is reset as is the binding mask (bindingMask) in case a control scheme is activated on the user.

Sends DeviceUnpaired through onChange for every device unpaired from the user.

Sends Removed.

See Also

Events

onChange

Event that is triggered when the InputUser setup in the system changes.

Declaration
public static event Action<InputUser, InputUserChange, InputDevice> onChange
Event Type
Type Description
Action<InputUser, InputUserChange, InputDevice>
Remarks

Each notification receives the user that was affected by the change and, in the form of InputUserChange, a description of what has changed about the user. The third parameter may be null but if the change will be related to an input device, will reference the device involved in the change.

onPrefilterUnpairedDeviceActivity

Callback that works in combination with onUnpairedDeviceUsed. If all callbacks added to this event return false for a

Declaration
public static event Func<InputDevice, InputEventPtr, bool> onPrefilterUnpairedDeviceActivity
Event Type
Type Description
Func<InputDevice, InputEventPtr, Boolean>
Remarks

Checking a given event for activity of interest is relatively fast but is still costlier than not doing it all. In case only certain devices are of interest for onUnpairedDeviceUsed, this "pre-filter" can be used to quickly reject entire devices and thus skip looking closer at an event.

The first argument is the InputDevice than an event has been received for. The second argument is the InputEvent that is being looked at.

A callback should return true if it wants onUnpairedDeviceUsed to proceed looking at the event and should return false if the event should be skipped.

If multiple callbacks are added to the event, it is enough for any single one callback to return true for the event to get looked at.

See Also

onUnpairedDeviceUsed

Event that is triggered when a device is used that is not currently paired to any user.

Declaration
public static event Action<InputControl, InputEventPtr> onUnpairedDeviceUsed
Event Type
Type Description
Action<InputControl, InputEventPtr>
Remarks

A device is considered "used" when it has magnitude (EvaluateMagnitude()) greater than zero on a control that is not noisy (noisy) and not synthetic (i.e. not a control that is "made up" like anyKey; synthetic).

Detecting the use of unpaired devices has a non-zero cost. While multiple levels of tests are applied to try to cheaply ignore devices that have events sent to them that do not contain user activity, finding out whether a device had real user activity will eventually require going through the device control by control.

To enable detection of the use of unpaired devices, set listenForUnpairedDeviceActivity to true. It is disabled by default.

The callback is invoked for each non-leaf, non-synthetic, non-noisy control that has been actuated on the device. It being restricted to non-leaf controls means that if, say, the stick on a gamepad is actuated in both X and Y direction, you will see two calls: one with stick/x and one with stick/y.

The reason that the callback is invoked for each individual control is that pairing often relies on checking for specific kinds of interactions. For example, a pairing callback may listen exclusively for button presses.

Note that whether the use of unpaired devices leads to them getting paired is under the control of the application. If the device should be paired, invoke PerformPairingWithDevice(InputDevice, InputUser, InputUserPairingOptions) from the callback. If you do so, no further callbacks will get triggered for other controls that may have been actuated in the same event.

Be aware that the callback is fired before input is actually incorporated into the device (it is indirectly triggered from onEvent). This means at the time the callback is run, the state of the given device does not yet have the input that triggered the callback. For this reason, the callback receives a second argument that references the event from which the use of an unpaired device was detected.

What this sequence allows is to make changes to the system before the input is processed. For example, an action that is enabled as part of the callback will subsequently respond to the input that triggered the callback.

// Activate support for listening to device activity.
++InputUser.listenForUnpairedDeviceActivity;

// When a button on an unpaired device is pressed, pair the device to a new
// or existing user.
InputUser.onUnpairedDeviceUsed +=
    usedControl =>
    {
        // Only react to button presses on unpaired devices.
        if (!(usedControl is ButtonControl))
            return;

        // Pair the device to a user.
        InputUser.PerformPairingWithDevice(usedControl.device);
    };

Another possible use of the callback is for implementing automatic control scheme switching for a user such that the user can, for example, switch from keyboard&mouse to gamepad seamlessly by simply picking up the gamepad and starting to play.

Operators

Equality(InputUser, InputUser)

Declaration
public static bool operator ==(InputUser left, InputUser right)
Parameters
Type Name Description
InputUser left
InputUser right
Returns
Type Description
Boolean

Inequality(InputUser, InputUser)

Declaration
public static bool operator !=(InputUser left, InputUser right)
Parameters
Type Name Description
InputUser left
InputUser right
Returns
Type Description
Boolean

See Also