Class PlayerInputManager

Manages joining and leaving of players.

Inheritance

Object

PlayerInputManager

Namespace: UnityEngine.InputSystem

Syntax

public class PlayerInputManager : MonoBehaviour

Remarks

This is a singleton component. Only one instance is meant to be active in a game at any one time. To retrieve the current instance, use instance.

Note that a PlayerInputManager is not strictly required to have multiple PlayerInput components. What PlayerInputManager provides is the implementation of specific player join mechanisms (joinBehavior) as well as automatic assignment of split-screen areas (splitScreen). However, you can always implement your own custom logic instead and simply instantiate multiple GameObjects with PlayerInput yourself.

Fields

PlayerJoinedMessage

Name of the message that is sent when a player joins the game.

Declaration

public const string PlayerJoinedMessage = null

Field Value

Type	Description
String

PlayerLeftMessage

Declaration

public const string PlayerLeftMessage = null

Field Value

Type	Description
String

Properties

fixedNumberOfSplitScreens

Declaration

public int fixedNumberOfSplitScreens { get; }

Property Value

Type	Description
Int32

instance

Singleton instance of the manager.

Declaration

public static PlayerInputManager instance { get; }

Property Value

Type	Description
PlayerInputManager	Singleton instance or null.

joinAction

The input action that a player must trigger to join the game.

Declaration

public InputActionProperty joinAction { get; set; }

Property Value

Type	Description
InputActionProperty

Remarks

If the join action is a reference to an existing input action, it will be cloned when the PlayerInputManager is enabled. This avoids the situation where the join action can become disabled after the first user joins which can happen when the join action is the same as a player in-game action. When a player joins, input bindings from devices other than the device they joined with are disabled. If the join action had a binding for keyboard and one for gamepad for example, and the first player joined using the keyboard, the expectation is that the next player could still join by pressing the gamepad join button. Without the cloning behavior, the gamepad input would have been disabled.

For more details about joining behavior, see PlayerInput.

joinBehavior

Determines the mechanism by which players can join when joining is enabled (joiningEnabled).

Declaration

public PlayerJoinBehavior joinBehavior { get; set; }

Property Value

Type	Description
PlayerJoinBehavior

joiningEnabled

Whether new players can currently join.

Declaration

public bool joiningEnabled { get; }

Property Value

Type	Description
Boolean

Remarks

While this is true, new players can join via the mechanism determined by joinBehavior.

See Also

EnableJoining()

DisableJoining()

maintainAspectRatioInSplitScreen

If splitScreen is enabled, this property determines whether subdividing the screen is allowed to produce screen areas that have an aspect ratio different from the screen resolution.

Declaration

public bool maintainAspectRatioInSplitScreen { get; }

Property Value

Type	Description
Boolean

Remarks

By default, when splitScreen is enabled, the manager will add or remove screen subdivisions in steps of two. This means that when, for example, the second player is added, the screen will be subdivided into a left and a right screen area; the left one allocated to the first player and the right one allocated to the second player.

This behavior makes optimal use of screen real estate but will result in screen areas that have aspect ratios different from the screen resolution. If this is not acceptable, this property can be set to true to enforce split-screen to only create screen areas that have the same aspect ratio of the screen.

This results in the screen being subdivided more aggressively. When, for example, a second player is added, the screen will immediately be divided into a four-way split-screen setup with the lower two screen areas not being used.

This property is irrelevant if fixedNumberOfSplitScreens is used.

maxPlayerCount

Maximum number of players allowed concurrently in the game.

Declaration

public int maxPlayerCount { get; }

Property Value

Type	Description
Int32

Remarks

If this limit is reached, joining is turned off automatically.

By default this is set to -1. Any negative value deactivates the player limit and allows arbitrary many players to join.

notificationBehavior

Declaration

public PlayerNotifications notificationBehavior { get; set; }

Property Value

Type	Description
PlayerNotifications

playerCount

The current number of active players.

Declaration

public int playerCount { get; }

Property Value

Type	Description
Int32

Remarks

This count corresponds to all PlayerInput instances that are currently enabled.

playerJoinedEvent

Declaration

public PlayerInputManager.PlayerJoinedEvent playerJoinedEvent { get; }

Property Value

Type	Description
PlayerInputManager.PlayerJoinedEvent

playerLeftEvent

Declaration

public PlayerInputManager.PlayerLeftEvent playerLeftEvent { get; }

Property Value

Type	Description
PlayerInputManager.PlayerLeftEvent

playerPrefab

Reference to the prefab that the manager will instantiate when players join.

Declaration

public GameObject playerPrefab { get; set; }

Property Value

Type	Description
GameObject	Prefab to instantiate for new players.

splitScreen

If enabled, each player will automatically be assigned a portion of the available screen area.

Declaration

public bool splitScreen { get; set; }

Property Value

Type	Description
Boolean

Remarks

For this to work, each PlayerInput component must have an associated object through camera.

Note that as player join, the screen may be increasingly subdivided and players may see their previous screen area getting resized.

splitScreenArea

The normalized screen rectangle available for allocating player split-screens into.

Declaration

public Rect splitScreenArea { get; }

Property Value

Type	Description
Rect

Remarks

This is only used if splitScreen is true.

By default it is set to (0,0,1,1), i.e. the entire screen area will be used for player screens. If, for example, part of the screen should display a UI/information shared by all players, this property can be used to cut off the area and not have it used by PlayerInputManager.

Methods

DisableJoining()

Inhibit players from joining the game.

Declaration

public void DisableJoining()

See Also

EnableJoining()

joiningEnabled

EnableJoining()

Allow players to join the game based on joinBehavior.

Declaration

public void EnableJoining()

See Also

DisableJoining()

joiningEnabled

JoinPlayer(Int32, Int32, String, InputDevice)

Spawn a new player from playerPrefab.

Declaration

public PlayerInput JoinPlayer(int playerIndex = null, int splitScreenIndex = null, string controlScheme = null, InputDevice pairWithDevice = null)

Parameters

Type	Name	Description
Int32	playerIndex	Optional explicit playerIndex to assign to the player. Must be unique within all. If not supplied, a player index will be assigned automatically (smallest unused index will be used).
Int32	splitScreenIndex	Optional splitScreenIndex. If supplied, this assigns a split-screen area to the player. For example, a split-screen index of
String	controlScheme	Control scheme to activate on the player (optional). If not supplied, a control scheme will be selected based on pairWithDevice. If no device is given either, the first control scheme that matches the currently available unpaired devices (see GetUnpairedInputDevices()) is used.
InputDevice	pairWithDevice	Device to pair to the player. Also determines which control scheme to use if controlScheme is not given.

Returns

Type	Description
PlayerInput	The newly instantiated player or null if joining failed.

Remarks

Joining must be enabled (see joiningEnabled) or the method will fail.

To pair multiple devices, use JoinPlayer(Int32, Int32, String, InputDevice[]).

JoinPlayer(Int32, Int32, String, InputDevice[])

Spawn a new player from playerPrefab.

Declaration

public PlayerInput JoinPlayer(int playerIndex = null, int splitScreenIndex = null, string controlScheme = null, params InputDevice[] pairWithDevices)

Parameters

Type	Name	Description
Int32	playerIndex	Optional explicit playerIndex to assign to the player. Must be unique within all. If not supplied, a player index will be assigned automatically (smallest unused index will be used).
Int32	splitScreenIndex	Optional splitScreenIndex. If supplied, this assigns a split-screen area to the player. For example, a split-screen index of
String	controlScheme	Control scheme to activate on the player (optional). If not supplied, a control scheme will be selected based on pairWithDevices. If no device is given either, the first control scheme that matches the currently available unpaired devices (see GetUnpairedInputDevices()) is used.
InputDevice[]	pairWithDevices	Devices to pair to the player. Also determines which control scheme to use if controlScheme is not given.

Returns

Type	Description
PlayerInput	The newly instantiated player or null if joining failed.

Remarks

Joining must be enabled (see joiningEnabled) or the method will fail.

JoinPlayerFromAction(InputAction.CallbackContext)

Join a new player based on input received through an InputAction.

Declaration

public void JoinPlayerFromAction(InputAction.CallbackContext context)

Parameters

Type	Name	Description
InputAction.CallbackContext	context

JoinPlayerFromActionIfNotAlreadyJoined(InputAction.CallbackContext)

Declaration

public void JoinPlayerFromActionIfNotAlreadyJoined(InputAction.CallbackContext context)

Parameters

Type	Name	Description
InputAction.CallbackContext	context

Events

onPlayerJoined

Declaration

public event Action<PlayerInput> onPlayerJoined

Event Type

Type	Description
Action<PlayerInput>

onPlayerLeft

Declaration

public event Action<PlayerInput> onPlayerLeft

Event Type

Type	Description
Action<PlayerInput>