Class PlayerInput

A wrapper around the input system that takes care of managing input actions and players.

Inheritance

System.Object

PlayerInput

Namespace: UnityEngine.InputSystem

Syntax

public class PlayerInput : MonoBehaviour

Remarks

This is a helper to get set up with the new input system quickly. It takes care of InputAction bookkeeping and has a custom UI to help setting up input.

The component supports local multiplayer implicitly. Each PlayerInput instance represents a distinct user with its own set of devices and actions. To orchestrate player management and facilitate mechanics such as joining by device activity, use PlayerInputManager.

The way PlayerInput notifies script code of events is determined by notificationBehavior. By default, this is set to SendMessages which will use to send messages to the that PlayerInput sits on.

Notifications are sent

1) when actions are triggered, 2) when a player loses or regains a device, 3) when the player switches to a different control scheme, 4) when the player changes bindings,

If notificationBehavior is set to SendMessages or BroadcastMessages, then an ... OnFireStarted

// Component to sit next to PlayerInput.
public class MyPlayerLogic : MonoBehaviour
{
    public GameObject projectilePrefab;

    private Vector2 m_Look;
    private Vector2 m_Move;
    private bool m_Fire;

    // Player has joined the game.
    public void OnPlayerJoined()
    {
        // Put player at spawn point.
        transform.position = PickSpawnPoint().transform.position;
    }

    // 'Fire' input action has been triggered. For 'Fire' we want continuous
    // action (i.e. firing) while the fire buttion is held such that the action
    // gets triggered repeatedly while the button is down. We can easily set this
    // up by having a "Press" interaction on the button and setting it to repeat
    // at fixed intervals.
    public void OnFire()
    {
        Instantiate(projectilePrefab);
    }

    // 'Move' input action has been triggered.
    public void OnMove(InputValue value)
    {
        TODO
    }

    public void OnFixedUpdate()
    {
        TODO
    }

    private GameObject PickSpawnPoint()
    {
        // Pick a spawn point for the player...
    }
}

A player can be uniquely associated with a

When a game is started, a PlayerInput component will pick from the locally available devices to decide which to use with the component's input actions (devices). Once picked, the devices will be for the exclusive use by the PlayerInput component.

The picking process can be guided in one of several ways:

1) By control scheme. XXX

Note that this component prioritizes usability over performance and involves a certain overhead at runtime.

The implementation is based on the functionality made available by InputUser. If the component does not fit the specific requirements of an application, its functionality can be reimplemented on top of the same API.

Fields

DeviceLostMessage

Declaration

public const string DeviceLostMessage = "OnDeviceLost"

Field Value

Type	Description
System.String

DeviceRegainedMessage

Declaration

public const string DeviceRegainedMessage = "OnDeviceRegained"

Field Value

Type	Description
System.String

Properties

actionEvents

List of events invoked in response to actions being triggered.

Declaration

public ReadOnlyArray<PlayerInput.ActionEvent> actionEvents { get; set; }

Property Value

Type	Description
ReadOnlyArray<PlayerInput.ActionEvent>

Remarks

This array is only used if notificationBehavior is set to InvokeUnityEvents.

actions

Input actions associated with the player.

Declaration

public InputActionAsset actions { get; set; }

Property Value

Type	Description
InputActionAsset

Remarks

Note that every player will maintain a unique copy of the given actions such that each player receives an identical copy. When assigning the same actions to multiple players, the first player will use the given actions as is but any subsequent player will make a copy of the actions using .

The asset may contain an arbitrary number of action maps. However, the first action map in the asset is treated special ...

Notifications will be send for all actions in the asset, not just for those in the first action map. This means that if additional maps are manually enabled and disabled,

There is one exception to this, however. For any action from the asset that is also referenced by an InputSystemUIInputModule sitting on the of , no notification will be triggered when the action is fired.

See Also

actions

active

Declaration

public bool active { get; }

Property Value

Type	Description
System.Boolean

all

Declaration

public static ReadOnlyArray<PlayerInput> all { get; }

Property Value

Type	Description
ReadOnlyArray<PlayerInput>

camera

The camera associated with the player.

Declaration

public Camera camera { get; set; }

Property Value

Type	Description
Camera

Remarks

This is null by default.

Associating a camera with a player is necessary when using split-screen.

controlScheme

Declaration

public string controlScheme { get; }

Property Value

Type	Description
System.String

currentActionMap

Declaration

public InputActionMap currentActionMap { get; set; }

Property Value

Type	Description
InputActionMap

defaultActionMap

Name or ID (in the form of "{...}") of the action map to enable by default.

Declaration

public string defaultActionMap { get; set; }

Property Value

Type	Description
System.String

Remarks

TODO

defaultControlScheme

Declaration

public string defaultControlScheme { get; set; }

Property Value

Type	Description
System.String

deviceLostEvent

Event that is triggered when the player loses a device (e.g. the batteries run out).

Declaration

public PlayerInput.DeviceLostEvent deviceLostEvent { get; }

Property Value

Type	Description
PlayerInput.DeviceLostEvent

Remarks

This event is only used if notificationBehavior is set to InvokeUnityEvents.

deviceRegainedEvent

Event that is triggered when the player recovers from device loss and is good to go again.

Declaration

public PlayerInput.DeviceRegainedEvent deviceRegainedEvent { get; }

Property Value

Type	Description
PlayerInput.DeviceRegainedEvent

Remarks

This event is only used if notificationBehavior is set to InvokeUnityEvents.

devices

The devices used by the player.

Declaration

public ReadOnlyArray<InputDevice> devices { get; }

Property Value

Type	Description
ReadOnlyArray<InputDevice>

See Also

pairedDevices

hasMissingRequiredDevices

Declaration

public bool hasMissingRequiredDevices { get; }

Property Value

Type	Description
System.Boolean

isSinglePlayer

Declaration

public static bool isSinglePlayer { get; }

Property Value

Type	Description
System.Boolean

neverAutoSwitchControlSchemes

If true, do not automatically switch control schemes even when there is only a single player. By default, this property is false.

Declaration

public bool neverAutoSwitchControlSchemes { get; set; }

Property Value

Type	Description
System.Boolean	If true, do not switch control schemes when other devices are used.

Remarks

By default, when there is only a single PlayerInput enabled, we assume that the game is in single-player mode and that the player should be able to freely switch between the control schemes supported by the game. For example, if the player is currently using mouse and keyboard, but is then switching to a gamepad, PlayerInput should automatically switch to the control scheme for gamepads, if present.

When there is more than one PlayerInput, this behavior is automatically turned off as we wouldn't know which player is switching if a currently unpaired device is used.

By setting this property to true, auto-switching of control schemes is forcibly turned off and will thus not be performed even if there is only a single PlayerInput in the game.

This property is most useful for games that do not have an explicit lobby but rather allow joining throughout the game. Classic beat 'em up games where a second player may join the brawl at any time are a good example.

Note that you can still switch control schemes manually using SwitchControlScheme(String, InputDevice[]).

See Also

controlScheme

notificationBehavior

Determines how the component notifies listeners about input actions and other input-related events pertaining to the player.

Declaration

public PlayerNotifications notificationBehavior { get; set; }

Property Value

Type	Description
PlayerNotifications

Remarks

By default, the component will use to send messages to the . This can be changed by selecting a different PlayerNotifications behavior.

See Also

actionEvents

deviceLostEvent

deviceRegainedEvent

playerIndex

Unique index of the player.

Declaration

public int playerIndex { get; }

Property Value

Type	Description
System.Int32

Remarks

Once assigned, a player index will not change.

Note that the player index does not necessarily correspond to the player's index in all. The array will always contain all currently enabled players so when a player is disabled or destroyed, it will be removed from the array. However, the player index of the remaining players will not change.

splitScreenIndex

If split-screen is enabled (splitScreen), this is the index of the screen area used by the player.

Declaration

public int splitScreenIndex { get; }

Property Value

Type	Description
System.Int32

See Also

camera

uiInputModule

UI InputModule that should have it's input actions synchronized to this PlayerInput's actions.

Declaration

public InputSystemUIInputModule uiInputModule { get; set; }

Property Value

Type	Description
InputSystemUIInputModule

user

The internal user tied to the player.

Declaration

public InputUser user { get; }

Property Value

Type	Description
InputUser

Methods

ActivateInput()

Declaration

public void ActivateInput()

DebugLogAction(InputAction.CallbackContext)

Debug helper method that can be hooked up to actions when using InvokeUnityEvents.

Declaration

public void DebugLogAction(InputAction.CallbackContext context)

Parameters

Type	Name	Description
InputAction.CallbackContext	context

FindFirstPairedToDevice(InputDevice)

Declaration

public static PlayerInput FindFirstPairedToDevice(InputDevice device)

Parameters

Type	Name	Description
InputDevice	device

Returns

Type	Description
PlayerInput

GetPlayerByIndex(Int32)

Declaration

public static PlayerInput GetPlayerByIndex(int playerIndex)

Parameters

Type	Name	Description
System.Int32	playerIndex

Returns

Type	Description
PlayerInput

Instantiate(GameObject, Int32, String, Int32, InputDevice)

Declaration

public static PlayerInput Instantiate(GameObject prefab, int playerIndex = -1, string controlScheme = null, int splitScreenIndex = -1, InputDevice pairWithDevice = null)

Parameters

Type	Name	Description
GameObject	prefab
System.Int32	playerIndex
System.String	controlScheme
System.Int32	splitScreenIndex
InputDevice	pairWithDevice

Returns

Type	Description
PlayerInput

Instantiate(GameObject, Int32, String, Int32, InputDevice[])

A wrapper around that allows instantiating a player prefab and automatically pair one or more specific devices to the newly created player.

Declaration

public static PlayerInput Instantiate(GameObject prefab, int playerIndex = -1, string controlScheme = null, int splitScreenIndex = -1, params InputDevice[] pairWithDevices)

Parameters

Type	Name	Description
GameObject	prefab	A player prefab containing a PlayerInput component in its hierarchy.
System.Int32	playerIndex
System.String	controlScheme
System.Int32	splitScreenIndex
InputDevice[]	pairWithDevices

Returns

Type	Description
PlayerInput

Remarks

Note that unlike , this method will always activate the resulting and its components.

PassivateInput()

Declaration

public void PassivateInput()

SwitchControlScheme(String, InputDevice[])

Declaration

public void SwitchControlScheme(string controlScheme, params InputDevice[] devices)

Parameters

Type	Name	Description
System.String	controlScheme
InputDevice[]	devices

SwitchControlScheme(InputDevice[])

Declaration

public bool SwitchControlScheme(params InputDevice[] devices)

Parameters

Type	Name	Description
InputDevice[]	devices

Returns

Type	Description
System.Boolean

SwitchCurrentActionMap(String)

Declaration

public void SwitchCurrentActionMap(string mapNameOrId)

Parameters

Type	Name	Description
System.String	mapNameOrId

Events

onActionTriggered

Declaration

public event Action<InputAction.CallbackContext> onActionTriggered

Event Type

Type	Description
System.Action<InputAction.CallbackContext>

onDeviceLost

Declaration

public event Action<PlayerInput> onDeviceLost

Event Type

Type	Description
System.Action<PlayerInput>

onDeviceRegained

Declaration

public event Action<PlayerInput> onDeviceRegained

Event Type

Type	Description
System.Action<PlayerInput>

See Also

PlayerInputManager