Firstborn/Library/PackageCache/com.unity.inputsystem@1.4.4/Documentation~/UserManagement.md

User Management

The Input System supports multi-user management through the InputUser class. This comprises both user account management features on platforms that have these capabilities built into them (such as Xbox and PS4), as well as features to manage Device allocations to one or more local users.

Note: The user management API is quite low-level in nature. The stock functionality of PlayerInputManager (see Components) provides an easier way to set up user management. The API described here is useful when you want more control over user management.

In the Input System, each InputUser represents a human interacting with the application. For example, you can have multiple users playing a game together on a single computer or device (local multiplayer), where each user has one or more paired Input Devices.

The PlayerInputManager class uses InputUser internally to handle users.

Note: In the editor, all InputUser instances are automatically removed when exiting play mode thus also removing any device pairings. In essence, InputUser is considered a player-only API.

Device pairing

You can use the InputUser.PerformPairingWithDevice method to create a new InputUser instance and pair it with an InputDevice. You can also optionally pass in an existing InputUser instance to pair it with the Device, if you don't want to create a new user instance.

To query the Devices paired to a specific InputUser, use InputUser.pairedDevices. To remove the pairing, use InputUser.UnpairDevice or InputUser.UnpairDevices.

Initial engagement

After you create a user, you can use InputUser.AssociateActionsWithUser to associate Input Actions to it, and use InputUser.ActivateControlScheme to associate and activate a Control Scheme. You can use InputControlScheme.FindControlSchemeForDevice to pick a control scheme that matches the selected Actions and Device:

var scheme = InputControlScheme.FindControlSchemeForDevice(user.pairedDevices[0], user.actions.controlsSchemes);
if (scheme != null)
    user.ActivateControlScheme(scheme);

When you activate a Control Scheme, the Input System automatically switches the active Binding mask for the user's Actions to that Control Scheme.

Loss of Device

If paired Input Devices disconnect during the session, the system notifies the InputUser class. It still keeps track of the Device, and automatically re-pairs the Device if it becomes available again.

To get notifications about these changes, subscribe to the InputUser.onChange event.

Debugging

Check the debugger documentation to learn how to debug active users.