GameObject Components for Input

Two MonoBehaviour components are available to simplify setting up and working with input. They are generally the quickest and easiest way to get started with input in Unity.

Component	Description
`PlayerInput`	Represents a single player along with the player's associated input actions.
`PlayerInputManager`	Handles setups that allow for several players including scenarios such as player lobbies and split-screen gameplay.

NOTE: These components are built on top of the public input system API. As such, they don't do anything that you cannot program yourself. They are meant primarily as an easy out-of-the-box setup to obsolete much of the need for custom scripting.

`PlayerInput` Component

PlayerInput

Each PlayerInput represents a separate player in the game. Multiple PlayerInput instances may coexist at the same time (though not on the same GameObject) to represent local multiplayer setups. Each player will be paired to a unique set of devices for exclusive use by the player, although it is possible to manually pair devices such that players share a device (e.g. for left/right keyboard splits or hotseat use).

Each PlayerInput corresponds to one InputUser. The InputUser can be queried from the component using PlayerInput.user.

You can use the following properties to configure PlayerInput.

Property	Description
`Actions`	The set of input actions associated with the player. To receive input, each player must have an associated set of actions. See here for details.
`Default Control Scheme`	Which control scheme to use from what is defined in `Actions` by default.
`Default Action Map`	Which action map in `Actions` to enable by default. If set to `None`, then the player will start out with no actions being enabled.
`Camera`	The individual camera associated with the player. This is only required when employing split-screen setups. It has no effect otherwise.
`Behavior`	How the `PlayerInput` component notifies game code about things that happen with the player. See here.

Actions

To receive input, each player requires an associated set of input actions. When creating these through the "Create Actions..." button in the PlayerInput inspector, a default set of actions will be created. However, the PlayerInput component places no restrictions on the arrangement of actions.

PlayerInput will handle enabling and disabling automatically and will also take care of installing callbacks on the actions. Also, when multiple PlayerInput components use the same actions, the components will automatically take care of creating private copies of the actions.

When first enabled, PlayerInput will enable all actions from the action map identified by Default Action Map. If no default action map has been set, no actions will be enabled by default. To manually enable actions, you can simply call Enable and Disable on the action maps or actions like you would do without PlayerInput. You can check or switch which action map is currently enabled using the PlayerInput.currentActionMap property. To switch action maps by action map name, you can also call PlayerInput.SwitchCurrentActionMap.

To disable input on a player, call PlayerInput.PassivateInput. To re-enable it, call PlayerInput.ActivateInput. The latter will enable the default action map, if set.

When PlayerInput is disabled, it will automatically disable the currently active action map (PlayerInput.currentActionMap) and disassociate any devices paired to the player.

See the following section for how to be notified when an action is triggered by a player.

`SendMessage`/`BroadcastMessage` Actions

When the notification behavior of PlayerInput is set to Send Messages or Broadcast Messages, actions can be responded to by defining methods in components like so:

public class MyPlayerScript : MonoBehaviour
{
    // "fire" action becomes "OnFire" method. If you're not interested in the
    // value from the control that triggers the action, simply have a method
    // without arguments.
    public void OnFire()
    {
    }

    // If you are interested in the value from the control that triggers an action,
    // you can declare a parameter of type InputValue.
    public void OnMove(InputValue value)
    {
        // Read value from control. The type depends on what type of controls
        // the action is bound to.
        var v = value.Get<Vector2>();

        // IMPORTANT: The given InputValue is only valid for the duration of the callback.
        //            Storing the InputValue references somewhere and calling Get<T>()
        //            later will not work correctly.
    }
}

The component must sit on the same GameObject if Send Messages is chosen or on the same or any child GameObject if Broadcast Messages is chosen.

`UnityEvent` Actions

When the notification behavior of PlayerInput is set to Invoke Unity Events, each action has to individually be routed to a target method. The methods have the same format as the started, performed, and canceled callbacks on InputAction.

public class MyPlayerScript : MonoBehaviour
{
    public void OnFire(InputAction.CallbackContext context)
    {
    }

    public void OnMove(InputAction.CallbackContext context)
    {
        var value = context.ReadValue<Vector2>();
    }
}

Notification Behaviors

You can use the Behavior property in the inspector to determine how a PlayerInput component notifies game code when something related to the player has occurred. The following options are available to choose the specific mechanism that PlayerInput employs.

You can listen to the following notifications:

Behavior	Description
`Send Messages`	Uses `GameObject.SendMessage` on the `GameObject` that the `PlayerInput` component belongs to. The messages that will be sent by the component are shown in the UI.
`Broadcast Messages`	Like `Send Message` but instead of `GameObject.SendMessage` uses `GameObject.BroadcastMessage`. This will broadcast the message down the `GameObject` hierarchy.
`Invoke Unity Events`	Uses a separate `UnityEvent` for each individual type of message. When this is selected, the events that are available on the given `PlayerInput` are accessible from the "Events" foldout. The argument received by events triggered for actions is the same as the one received by `started`, `performed`, and `canceled` callbacks.
`Invoke CSharp Events`	Similar to `Invoke Unity Events` except that the events are plain C# events available on the `PlayerInput` API. These cannot be initialized from the inspector but have to be manually registered callbacks for in script. The following events are available: `onActionTriggered` (collective event for all actions on the player) `onDeviceLost` `onDeviceRegained`

In addition to per-action notifications, the following general notifications are employed by PlayerInput.

Notification	Description
`DeviceLostMessage`	The player has lost one of the devices assigned to it. This can happen, for example, if a wireless device runs out of battery.
`DeviceRegainedMessage`	Notification that is triggered when the player recovers from device loss and is good to go again.

Control Schemes

Device Assignments

Each PlayerInput can be assigned one or more devices. By default, no two PlayerInput components will be assigned the same devices — although this can be forced explicitly by manually assigning devices to a player when calling PlayerInput.Instantiate or by calling InputUser.PerformPairingWithDevice on the InputUser of a PlayerInput.

The devices assigned .

UI Input

The PlayerInput component can work together with a InputSystemUIInputModule to drive the UI system.

To set this up, assign a reference to a InputSystemUIInputModule component in the UI Input Module field of the PlayerInput component. The PlayerInput and InputSystemUIInputModule components should be configured to work with the same InputActionAsset for this to work.

Now, when the PlayerInput component configures the actions for a specific player, it will assign the same action configuration to the InputSystemUIInputModule. So the same device used to control the player will now be set up to control the UI.

If you use MultiplayerEventSystem components to dispatch UI events, you can also use this setup to simultaneously have multiple UI instances on the screen, controlled by separate players.

`PlayerInputManager` Component

The PlayerInput system has been designed to facilitate setting up local multiplayer games, with multiple players sharing a single device with a single screen and multiple controllers. This is set up using the PlayerInputManager component, which automatically manages the creation and livetime of PlayerInput instances as players join and leave the game.

PlayerInputManager

Property	Description
`Notification Behavior`	How the `PlayerInputManager` component notifies game code about things that happen with the. This works the same way as for the `PlayerInput` component.
`Join Behavior`	Determines the mechanism by which players can join when joining is enabled. See Join Behaviors.
`Player Prefab`	A prefab representing a player in the game. The [`PlayerInputManager`]((../api/UnityEngine.InputSystem.PlayerInputManager.html) component will create an instance of this prefab whenever a new player joins. This prefab must have one `PlayerInput` component in it's hierarchy.
`Joining Enabled By Default`	While this is enabled, new players can join via the mechanism determined by `Join Behavior`.
`Limit Number of Players`	Enable this if you want to limit the number of players who can join the game.
`Max Player Cou nt`(Only shown when `Limit number of Players` is enabled.)	The maximum number of players allowed to join the game.
`Enable Split-Screen`	If enabled, each player will automatically be assigned a portion of the available screen area. See Split-Screen

Join Behaviors

You can use the Join Behavior property in the inspector to determine how a PlayerInputManager component decides when to add new players to the game. The following options are available to choose the specific mechanism that PlayerInputManager employs.

Behavior	Description
`Join Players When Button IsPressed`	Listen for button presses on devices that are not paired to any player. If they occur and joining is allowed, join a new player using the device the button was pressed on.
`Join Players When Join Action Is Triggered`	Similar to `Join Players When Button IsPressed`, but this will only join a player if the control which was triggered matches a specific action you can define. That way, you can set up players to join when pressing a specific gamepad button for instance.
`Join Players Manually`	Do not join players automatically. Call `JoinPlayerFromUI` or `JoinPlayerFromAction` explicitly in order to join new players. Alternatively, just create GameObjects with `PlayerInput` components directly and they will be joined automatically.

Split-Screen

If you enable the Split-Screen option, then the PlayerInputManager will automatically split the available screen space between the active players. For this to work, the Camera property must be configured on the PlayerInput prefab. The PlayerInputManager will then automatically resize and reposition each camera instance to let each player have it's own part of the screen.

If you enable the Split-Screen option, the following additional properties will be shown in the inspector:

Property	Description
`Maintain Aspect Ratio`	Determines whether subdividing the screen is allowed to produce screen areas that have an aspect ratio different from the screen resolution.
`Set Fixed Number`	If this value is larger then zero, then the `PlayerInputManager` will always split the screen into a fixed number of rectangles, regardless of the actual number of players.
`Screen Rectangle`	The normalized screen rectangle available for allocating player split-screens into.

By default, any UI elements can be interacted with by any player in the game. However, in split-screen setups, it is possible to have screen-space UIs that are restricted to just one specific camera. See the (UI Input)[#ui-input] section above on how to set this up using the PlayerInput, InputSystemUIInputModule and MultiplayerEventSystem components.

`PlayerInputManager` Notifications

PlayerInputManager sends notifications when something notable happens with the current player setup. How these notifications are delivered through the Notification Behavior property the same way as for PlayerInput.