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).

A user may be associated with a platform user account (platformUserAccountHandle), if supported by the platform and the devices used. Support for this is commonly found on consoles. Note that the account associated with an InputUser may change if the player uses the system's facilities to switch to a different account (AccountChanged). On Xbox and Switch, this may also be initiated from the application by passing ForcePlatformUserAccountSelection to PerformPairingWithDevice(InputDevice, InputUser, InputUserPairingOptions).

Platforms that support user account association are , , , , , and . Note that for WSA/UWP apps, the "User Account Information" capability must be enabled for the app in order for user information to come through on input devices.

Fields

InvalidId

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

Properties

actions

Actions associated with the user.

Declaration
public 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.

If are applied with customized bindings (customBindings), these are applied automatically to the actions.

See Also

all

List of all current users.

Declaration
public static 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 InputControlScheme? controlScheme { get; }
Property Value
Type Description
System.Nullable<InputControlScheme>
Remarks

This is null by default.

Any time the value of this property changes (whether by 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 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 bool hasMissingRequiredDevices { get; }
Property Value
Type Description
System.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 uint id { get; }
Property Value
Type Description
System.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.

Note that this is not the same as the platform's internal user ID (if relevant on the current platform). To get the ID that the platform uses to identify the user, use platformUserAccountHandle.

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

See Also

index

The sequence number of the user.

Declaration
public int index { get; }
Property Value
Type Description
System.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
System.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 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 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

If the user is is associated with a user account at the platform level, this is the handle used by the underlying platform API for the account.

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

Users may be associated with user accounts defined by the platform we are running on. Consoles, for example, have user account management built into the OS and marketplaces like Steam also have APIs for user management.

If this property is not null, it is the handle associated with the user at the platform level. This can be used, for example, to call platform-specific APIs to fetch additional information about the user (such as user profile images).

Be aware that there may be multiple InputUsers that have the same platformUserAccountHandle in case the platform allows different players to log in on the same user account.

See Also

platformUserAccountId

Platform-specific user ID that is valid across sessions even if the platformUserAccountName of the user changes.

Declaration
public string platformUserAccountId { get; }
Property Value
Type Description
System.String
Remarks

This is only valid if platformUserAccountHandle is not null.

Use this to, for example, associate application settings with the user. For display in UIs, use platformUserAccountName instead.

See Also

platformUserAccountName

Human-readable name assigned to the user account at the platform level.

Declaration
public string platformUserAccountName { get; }
Property Value
Type Description
System.String
Remarks

This property will be null on platforms that do not have user account management. In that case, platformUserAccountHandle will be null as well.

On platforms such as Xbox, PS4, and Switch, the user name will be the name of the user as logged in on the platform.

See Also

valid

Whether this is a currently active user record in all.

Declaration
public bool valid { get; }
Property Value
Type Description
System.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
System.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 an .inputactions asset with the user.

Declaration
public void AssociateActionsWithUser(IInputActionCollection actions)
Parameters
Type Name Description
IInputActionCollection actions
Exceptions
Type Condition
System.InvalidOperationException

CreateUserWithoutPairedDevices()

Declaration
public static InputUser CreateUserWithoutPairedDevices()
Returns
Type Description
InputUser

Equals(Object)

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

Equals(InputUser)

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

FindUserByAccount(InputUserAccountHandle)

Declaration
public static InputUser? FindUserByAccount(InputUserAccountHandle platformUserAccountHandle)
Parameters
Type Name Description
InputUserAccountHandle platformUserAccountHandle
Returns
Type Description
System.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
System.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
System.ArgumentNullException

device is null.
See Also

GetHashCode()

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

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 temporary, unmanaged memory. 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
System.Int32

Number of devices added to list.
See Also

PerformPairingWithDevice(InputDevice, InputUser, InputUserPairingOptions)

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

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
System.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
System.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.

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
System.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 = true;

// 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);
    };

InputUser.onChange +=
    (user, change) =>
    {
        ////TODO
    };

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
System.Boolean

Inequality(InputUser, InputUser)

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

See Also