Class PlayerInputManager

Manages joining and leaving of players.

Inheritance
object
Object
Component
Behaviour
MonoBehaviour
PlayerInputManager
Inherited Members
Namespace: UnityEngine.InputSystem
Assembly: Unity.InputSystem.dll
Syntax
[AddComponentMenu("Input/Player Input Manager")]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.inputsystem@1.8/manual/PlayerInputManager.html")]
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 = "OnPlayerJoined"
Field Value
Type Description
string

PlayerLeftMessage

Declaration
public const string PlayerLeftMessage = "OnPlayerLeft"
Field Value
Type Description
string

Properties

fixedNumberOfSplitScreens

If splitScreen is enabled, this property determines how many screen divisions there will be.

Declaration
public int fixedNumberOfSplitScreens { get; }
Property Value
Type Description
int
Remarks

This is only used if splitScreen is true.

By default this is set to -1 which means the screen will automatically be divided to best fit the current number of players i.e. the highest player index in PlayerInput

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
bool
Remarks

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

See Also

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
bool
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
int
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
int
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
bool
Remarks

For this to work, each PlayerInput component must have an associated Camera 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()

Allow players to join the game based on joinBehavior.

Declaration
public void EnableJoining()
See Also

JoinPlayer(int, int, string, InputDevice)

Spawn a new player from playerPrefab.

Declaration
public PlayerInput JoinPlayer(int playerIndex = -1, int splitScreenIndex = -1, string controlScheme = null, InputDevice pairWithDevice = null)
Parameters
Type Name Description
int 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).
int 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(int, int, string, params InputDevice[]).

JoinPlayer(int, int, string, params InputDevice[])

Spawn a new player from playerPrefab.

Declaration
public PlayerInput JoinPlayer(int playerIndex = -1, int splitScreenIndex = -1, string controlScheme = null, params InputDevice[] pairWithDevices)
Parameters
Type Name Description
int 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).
int 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(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(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>