diff --git a/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/PlayerInput.cs b/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/PlayerInput.cs index ce27ff2620..66929b7c2b 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/PlayerInput.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/PlayerInput.cs @@ -55,6 +55,7 @@ namespace UnityEngine.InputSystem /// to the player and a set of paired device. /// /// + /// /// PlayerInput is a high-level wrapper around much of the input system's functionality /// which is meant to help getting set up with the new input system quickly. It takes /// care of bookkeeping and has a custom UI(requires the "Unity UI" package) to help @@ -70,8 +71,76 @@ namespace UnityEngine.InputSystem /// to send messages to the /// that PlayerInput sits on. /// + /// When enabled, PlayerInput will create an and pair devices to the + /// user which are then specific to the player. The set of devices can be controlled explicitly + /// when instantiating a PlayerInput through + /// or . This also makes it possible + /// to assign the same device to two different players, e.g. for split-keyboard play. + /// + /// + /// + /// var p1 = PlayerInput.Instantiate(playerPrefab, + /// controlScheme: "KeyboardLeft", device: Keyboard.current); + /// var p2 = PlayerInput.Instantiate(playerPrefab, + /// controlScheme: "KeyboardRight", device: Keyboard.current); + /// + /// + /// + /// If no specific devices are given to a PlayerInput, the component will look for compatible + /// devices present in the system and pair them to itself automatically. If the PlayerInput's + /// have control schemes defined for them, PlayerInput will look for a + /// control scheme for which all required devices are available and not paired to any other player. + /// It will try first (if set), but then fall back to trying + /// all available schemes in order. Once a scheme is found for which all required devices are + /// available, PlayerInput will pair those devices to itself and select the given scheme. + /// + /// If no control schemes are defined, PlayerInput will try to bind as many as-of-yet unpaired + /// devices to itself as it can match to bindings present in the . This means + /// that if, for example, there's binding for both keyboard and gamepad and there is one keyboard + /// and two gamepads available when PlayerInput is enabled, all three devices will be paired to + /// the player. + /// + /// Note that when using , device pairing to players is controlled + /// from the joining logic. In that case, PlayerInput will automatically pair the device from which + /// the player joined. If control schemes are present in , the first one compatible + /// with that device is chosen. If additional devices are required, these will be paired from the pool + /// of currently unpaired devices. + /// + /// Device pairings can be changed at any time by either manually controlling pairing through + /// (and related methods) using a PlayerInput's + /// assigned or by switching control schemes (e.g. using + /// ), if any are present in the PlayerInput's + /// . + /// + /// When a player loses a device paired to it (e.g. when it is unplugged or loses power), + /// will signal which is also surfaced as a message, + /// , or (depending on ). + /// When a device is reconnected, will signal + /// which also is surfaced as a message, as , or + /// (depending on ). + /// + /// When there is only a single active PlayerInput in the game, joining is not enabled (see + /// ), and is not + /// set to true, device pairings for the player will also update automatically based on device usage. + /// + /// If control schemes are present in , then if a device is used (not merely plugged in + /// but rather receives input on a non-noisy, non-synthetic control) which is compatible with a control scheme + /// other than the currently used one, PlayerInput will attempt to switch to that control scheme. Success depends + /// on whether all device requirements for that scheme are met from the set of available devices. If a control + /// scheme happens, signals on + /// . + /// + /// If no control schemes are present in , PlayerInput will automatically pair any newly + /// available device to itself if the given device has any bindings available for it. + /// + /// Both behaviors described in the previous two paragraphs are automatically disabled if more than one + /// PlayerInput is active. + /// + /// /// /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; /// // Component to sit next to PlayerInput. /// [RequireComponent(typeof(PlayerInput))] /// public class MyPlayerLogic : MonoBehaviour @@ -110,14 +179,14 @@ namespace UnityEngine.InputSystem /// } /// } /// - /// - /// + /// /// It is also possible to use the polling API of s (see /// and ) /// in combination with PlayerInput. - /// - /// + /// /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; /// // Component to sit next to PlayerInput. /// [RequireComponent(typeof(PlayerInput))] /// public class MyPlayerLogic : MonoBehaviour @@ -152,72 +221,6 @@ namespace UnityEngine.InputSystem /// } /// /// - /// - /// When enabled, PlayerInput will create an and pair devices to the - /// user which are then specific to the player. The set of devices can be controlled explicitly - /// when instantiating a PlayerInput through - /// or . This also makes it possible - /// to assign the same device to two different players, e.g. for split-keyboard play. - /// - /// - /// - /// var p1 = PlayerInput.Instantiate(playerPrefab, - /// controlScheme: "KeyboardLeft", device: Keyboard.current); - /// var p2 = PlayerInput.Instantiate(playerPrefab, - /// controlScheme: "KeyboardRight", device: Keyboard.current); - /// - /// - /// - /// If no specific devices are given to a PlayerInput, the component will look for compatible - /// devices present in the system and pair them to itself automatically. If the PlayerInput's - /// have control schemes defined for them, PlayerInput will look for a - /// control scheme for which all required devices are available and not paired to any other player. - /// It will try first (if set), but then fall back to trying - /// all available schemes in order. Once a scheme is found for which all required devices are - /// available, PlayerInput will pair those devices to itself and select the given scheme. - /// - /// If no control schemes are defined, PlayerInput will try to bind as many as-of-yet unpaired - /// devices to itself as it can match to bindings present in the . This means - /// that if, for example, there's binding for both keyboard and gamepad and there is one keyboard - /// and two gamepads available when PlayerInput is enabled, all three devices will be paired to - /// the player. - /// - /// Note that when using , device pairing to players is controlled - /// from the joining logic. In that case, PlayerInput will automatically pair the device from which - /// the player joined. If control schemes are present in , the first one compatible - /// with that device is chosen. If additional devices are required, these will be paired from the pool - /// of currently unpaired devices. - /// - /// Device pairings can be changed at any time by either manually controlling pairing through - /// (and related methods) using a PlayerInput's - /// assigned or by switching control schemes (e.g. using - /// ), if any are present in the PlayerInput's - /// . - /// - /// When a player loses a device paired to it (e.g. when it is unplugged or loses power), - /// will signal which is also surfaced as a message, - /// , or (depending on ). - /// When a device is reconnected, will signal - /// which also is surfaced as a message, as , or - /// (depending on ). - /// - /// When there is only a single active PlayerInput in the game, joining is not enabled (see - /// ), and is not - /// set to true, device pairings for the player will also update automatically based on device usage. - /// - /// If control schemes are present in , then if a device is used (not merely plugged in - /// but rather receives input on a non-noisy, non-synthetic control) which is compatible with a control scheme - /// other than the currently used one, PlayerInput will attempt to switch to that control scheme. Success depends - /// on whether all device requirements for that scheme are met from the set of available devices. If a control - /// scheme happens, signals on - /// . - /// - /// If no control schemes are present in , PlayerInput will automatically pair any newly - /// available device to itself if the given device has any bindings available for it. - /// - /// Both behaviors described in the previous two paragraphs are automatically disabled if more than one - /// PlayerInput is active. - /// /// [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1724:TypeNamesShouldNotMatchNamespaces")] [AddComponentMenu("Input/Player Input")] @@ -229,29 +232,36 @@ public class PlayerInput : MonoBehaviour /// Name of the message that is sent with UnityEngine.Object.SendMessage when a /// player loses a device. /// - /// + /// + /// The default value is . + /// public const string DeviceLostMessage = "OnDeviceLost"; /// /// Name of the message that is sent with UnityEngine.Object.SendMessage when a /// player regains a device. /// - /// + /// + /// The default value is . + /// public const string DeviceRegainedMessage = "OnDeviceRegained"; /// /// Name of the message that is sent with UnityEngine.Object.SendMessage when the /// controls used by a player are changed. /// - /// + /// + /// The default value is . + /// public const string ControlsChangedMessage = "OnControlsChanged"; /// /// Whether input is on the player is active. /// /// If true, the player is receiving input. - /// - /// + /// + /// To activate and deactivate input use or . + /// public bool inputIsActive => m_InputActive; [Obsolete("Use inputIsActive instead.")] @@ -260,7 +270,6 @@ public class PlayerInput : MonoBehaviour /// /// Unique, zero-based index of the player. For example, 2 for the third player. /// - /// Unique index of the player. /// /// Once assigned, a player index will not change. /// @@ -274,19 +283,20 @@ public class PlayerInput : MonoBehaviour /// If split-screen is enabled (), /// this is the index of the screen area used by the player. /// - /// Index of split-screen area assigned to player or -1 if the player is not - /// using split-screen. /// + /// Index of split-screen area assigned to player or -1 if the player is not + /// using split-screen. + /// /// Split screen areas are enumerated row by row and within rows, column by column. So, if, for example, - /// there are four separate split-screen areas, the upper left one is #0, the upper right one is #1, + /// there are four separate areas, the upper left one is #0, the upper right one is #1, /// the lower left one is #2, and the lower right one is #3. /// /// Split screen areas are usually assigned automatically but players can also be assigned to /// areas explicitly through or /// . + /// + /// See /// - /// - /// public int splitScreenIndex => m_SplitScreenIndex; /// @@ -308,9 +318,9 @@ public class PlayerInput : MonoBehaviour /// Notifications will be sent 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, notifications will /// be sent for their actions as they receive input. + /// + /// Actions can also be associated with a user via . /// - /// - /// public InputActionAsset actions { get @@ -350,12 +360,12 @@ public InputActionAsset actions /// /// Name of the currently active control scheme or null. /// - /// Note that this property will be null if there are no control schemes + /// Note that this property will be null if there are no /// defined in . + /// + /// This can be set via . + /// When the player input is enabled it is dependent on . /// - /// - /// - /// public string currentControlScheme { get @@ -369,7 +379,7 @@ public string currentControlScheme } /// - /// The default control scheme to try. + /// The default control scheme to try to activate when the PlayerInput component is enabled /// /// Name of the default control scheme. /// @@ -382,9 +392,9 @@ public string currentControlScheme /// Note that this property only determines the first control scheme to try. If using the /// control scheme fails, PlayerInput will fall back to trying the other control schemes /// (if any) available from . + /// + /// Note that you can switch the manually using . /// - /// - /// public string defaultControlScheme { get => m_DefaultControlScheme; @@ -397,7 +407,7 @@ public string defaultControlScheme /// /// If true, do not switch control schemes when other devices are used. /// - /// By default, when there is only a single PlayerInput enabled, we assume that the game is in + /// By default, when there is only a single PlayerInput enabled (see ), 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 @@ -410,11 +420,9 @@ public string defaultControlScheme /// 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. /// - /// Note that you can still switch control schemes manually using manually using . /// - /// - /// public bool neverAutoSwitchControlSchemes { get => m_NeverAutoSwitchControlSchemes; @@ -435,9 +443,9 @@ public bool neverAutoSwitchControlSchemes ////REVIEW: this is inconsistent; currentControlScheme is a string, this is an InputActionMap /// - /// The currently enabled action map. + /// The currently enabled action map on the PlayerInput component. /// - /// Reference to the currently enabled action or null if no action + /// Reference to the currently enabled action map or null if no action /// map has been enabled by PlayerInput. /// /// Note that the concept of "current action map" is local to PlayerInput. You can still freely @@ -445,7 +453,6 @@ public bool neverAutoSwitchControlSchemes /// only tracks which action map has been enabled under the control of PlayerInput, i.e. either /// by means of or by using . /// - /// public InputActionMap currentActionMap { get => m_CurrentActionMap; @@ -473,9 +480,10 @@ public InputActionMap currentActionMap /// By default, when enabled, PlayerInput will not enable any of the actions in the /// asset. By setting this property, however, PlayerInput can be made to automatically enable the respective /// action map. + /// + /// It will impact the when the PlayerInput is enabled. + /// Note that you can still switch action map manually using . /// - /// - /// public string defaultActionMap { get => m_DefaultActionMap; @@ -491,10 +499,10 @@ public string defaultActionMap /// By default, the component will use to send messages /// to the . This can be changed by selecting a different /// behavior. + /// + /// Action Events are listed in . + /// Device events can be set via and . /// - /// - /// - /// public PlayerNotifications notificationBehavior { get => m_NotificationBehavior; @@ -519,6 +527,8 @@ public PlayerNotifications notificationBehavior /// /// This array is only used if is set to /// . + /// + /// The list of actions will be dependent on the specified in the Editor UI. /// public ReadOnlyArray actionEvents { @@ -604,6 +614,26 @@ public ControlsChangedEvent controlsChangedEvent /// The callbacks are called in sync (and with the same argument) with , /// , and . /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// // Component to sit next to PlayerInput. + /// [RequireComponent(typeof(PlayerInput))] + /// public class MyPlayerLogic : MonoBehaviour + /// { + /// public void OnEnable() + /// { + /// var playerInput = GetComponent<PlayerInput>(); + /// playerInput.onActionTriggered += OnAction; + /// } + /// + /// void OnAction(InputAction.CallbackContext context) + /// { + /// } + /// } + /// + /// /// /// /// @@ -636,6 +666,26 @@ public event Action onActionTriggered /// /// The argument is the player that lost its device (i.e. the player on which the callback is installed). /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// // Component to sit next to PlayerInput. + /// [RequireComponent(typeof(PlayerInput))] + /// public class MyPlayerLogic : MonoBehaviour + /// { + /// public void OnEnable() + /// { + /// var playerInput = GetComponent<PlayerInput>(); + /// playerInput.onDeviceLost += OnDeviceLost; + /// } + /// + /// void OnDeviceLost(PlayerInput context) + /// { + /// } + /// } + /// + /// /// /// public event Action onDeviceLost @@ -665,6 +715,26 @@ public event Action onDeviceLost /// /// The argument is the player that regained a device (i.e. the player on which the callback is installed). /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// // Component to sit next to PlayerInput. + /// [RequireComponent(typeof(PlayerInput))] + /// public class MyPlayerLogic : MonoBehaviour + /// { + /// public void OnEnable() + /// { + /// var playerInput = GetComponent<PlayerInput>(); + /// playerInput.onDeviceRegained += OnDeviceRegained; + /// } + /// + /// void OnDeviceRegained(PlayerInput player) + /// { + /// } + /// } + /// + /// /// /// public event Action onDeviceRegained @@ -694,6 +764,26 @@ public event Action onDeviceRegained /// for devices, the callback is invoked when the currently used /// keyboard layout (see ) changes. /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// // Component to sit next to PlayerInput. + /// [RequireComponent(typeof(PlayerInput))] + /// public class MyPlayerLogic : MonoBehaviour + /// { + /// public void OnEnable() + /// { + /// var playerInput = GetComponent<PlayerInput>(); + /// playerInput.onControlsChanged += OnControlsChanged; + /// } + /// + /// void OnControlsChanged(PlayerInput context) + /// { + /// } + /// } + /// + /// public event Action onControlsChanged { add @@ -714,14 +804,14 @@ public event Action onControlsChanged /// /// Optional camera associated with the player. /// - /// Camera specific to the player or null. /// + /// Camera specific to the player or null. /// This is null by default. /// /// Associating a camera with a player is necessary only when using split-screen (see ). /// public - #if UNITY_EDITOR +#if UNITY_EDITOR // camera property is deprecated and only available in Editor. new #endif @@ -760,12 +850,12 @@ public InputSystemUIInputModule uiInputModule public InputUser user => m_InputUser; /// - /// The devices paired to the player. + /// The list of devices paired to the player. /// /// List of devices paired to player. /// + /// An InputUser also has a list of /// - /// public ReadOnlyArray devices { get @@ -783,10 +873,10 @@ public ReadOnlyArray devices /// /// True if the player is missing devices required by the control scheme. /// - /// This can happen, for example, if the a device is unplugged during the game. + /// This can happen, for example, if a device is unplugged during the game. + /// This can also be queried at user level via . + /// The control scheme set on the PlayerInput component will specify the . /// - /// - /// public bool hasMissingRequiredDevices => user.valid && user.hasMissingRequiredDevices; /// @@ -812,20 +902,27 @@ public ReadOnlyArray devices /// while joining is not enabled in (if one exists). See . /// /// Automatic control scheme switching (if enabled) is predicated on single-player mode being active. + /// This is controlled by . /// - /// public static bool isSinglePlayer => s_AllActivePlayersCount <= 1 && (PlayerInputManager.instance == null || !PlayerInputManager.instance.joiningEnabled); /// /// Return the first device of the given type from paired to the player. - /// If no device of this type is paired to the player, return null. /// /// Type of device to look for (such as ). Can be a supertype /// of the actual device type. For example, querying for , may return a . /// The first device paired to the player that is of the given type or null if the player /// does not have a matching device. + /// + /// If no device of this type is paired to the player, return null. + /// + /// + /// + /// var device = PlayerInput.all[0].GetDevice<Mouse>(); + /// + /// /// public TDevice GetDevice() where TDevice : InputDevice @@ -837,16 +934,20 @@ public TDevice GetDevice() } /// - /// Enable input on the player. + /// Enable input on the player, by enabling the current action map /// /// /// Input will automatically be activated when the PlayerInput component is enabled. However, this method /// can be called to reactivate input after deactivating it with . /// /// Note that activating input will activate the current action map only (see ). + /// The state can be checked with . /// - /// - /// + /// + /// + /// PlayerInput.all[0].ActivateInput(); + /// + /// public void ActivateInput() { m_InputActive = true; @@ -860,7 +961,7 @@ public void ActivateInput() } /// - /// Disable input on the player. + /// Disable input on the player, by disabling the current action map /// /// /// Input is automatically activated when the PlayerInput component is enabled. This method can be @@ -868,8 +969,13 @@ public void ActivateInput() /// /// Note that activating input will deactivate the current action map only (see ). /// - /// - /// + /// + /// + /// PlayerInput.all[0].DeactivateInput(); + /// + /// + /// + /// public void DeactivateInput() { m_CurrentActionMap?.Disable(); @@ -894,15 +1000,13 @@ public void PassivateInput() /// has not been assigned. /// /// The player's currently paired devices (see ) will get unpaired. - /// + /// /// /// /// // Switch the first player to keyboard and mouse. - /// PlayerInput.all[0] - /// .SwitchCurrentControlScheme(Keyboard.current, Mouse.current); + /// PlayerInput.all[0].SwitchCurrentControlScheme(Keyboard.current, Mouse.current); /// /// - /// /// /// public bool SwitchCurrentControlScheme(params InputDevice[] devices) @@ -929,13 +1033,14 @@ public bool SwitchCurrentControlScheme(params InputDevice[] devices) /// Switch the player to use the given control scheme together with the given devices. /// /// Name of the control scheme. See . - /// A list of devices. + /// A list of input devices to consider for pairing against /// is null -or- is /// null or empty. /// /// This method can be used to explicitly force a combination of control scheme and a specific set of /// devices. - /// + /// The player's currently paired devices (see ) will get unpaired. + /// /// /// /// // Put player 1 on the "Gamepad" control scheme together @@ -945,9 +1050,6 @@ public bool SwitchCurrentControlScheme(params InputDevice[] devices) /// Gamepad.all[1]); /// /// - /// - /// The player's currently paired devices (see ) will get unpaired. - /// /// /// public void SwitchCurrentControlScheme(string controlScheme, params InputDevice[] devices) @@ -961,6 +1063,19 @@ public void SwitchCurrentControlScheme(string controlScheme, params InputDevice[ SwitchControlSchemeInternal(ref scheme, devices); } + /// + /// Switch the player to use the given action map + /// + /// Name of the action map or its ID. + /// + /// This method can be used to explicitly set an action map. + /// + /// + /// + /// PlayerInput.all[0].SwitchCurrentActionMap("Player"); + /// + /// + /// public void SwitchCurrentActionMap(string mapNameOrId) { // Must be enabled. @@ -989,11 +1104,19 @@ public void SwitchCurrentActionMap(string mapNameOrId) } /// - /// Return the Nth player. + /// Return the player with specified player index. /// - /// Index of the player to return. + /// The index into the active player list. /// The player with the given player index or null if no such /// player exists. + /// + /// Return the player with specified player index. + /// + /// + /// + /// PlayerInput player = PlayerInput.GetPlayerByIndex(0); + /// + /// /// public static PlayerInput GetPlayerByIndex(int playerIndex) { @@ -1006,18 +1129,19 @@ public static PlayerInput GetPlayerByIndex(int playerIndex) /// /// Find the first PlayerInput who the given device is paired to. /// - /// An input device. + /// An input device to query /// The player who is paired to the given device or null if no /// PlayerInput currently is paired to . /// is null. /// + /// There could be multiple players paired to the device. This function will return the first one found. + /// /// /// /// // Find the player paired to first gamepad. /// var player = PlayerInput.FindFirstPairedToDevice(Gamepad.all[0]); /// /// - /// public static PlayerInput FindFirstPairedToDevice(InputDevice device) { if (device == null) @@ -1033,18 +1157,26 @@ public static PlayerInput FindFirstPairedToDevice(InputDevice device) } /// - /// Instantiate a player object and set up and enable its inputs. + /// Instantiate a player object, set up and enable its inputs. /// /// Prefab to clone. Must contain a PlayerInput component somewhere in its hierarchy. /// Player index to assign to the player. See . /// By default will be assigned automatically based on how many players are in . - /// Control scheme to activate - /// + /// Control scheme to activate. + /// Which split screen to instantiate on. /// Device to pair to the user. By default, this is null which means /// that PlayerInput will automatically pair with available, unpaired devices based on the control schemes (if any) /// present in or on the bindings therein (if no control schemes are present). - /// + /// Newly created PlayerInput component. /// is null. + /// + /// Instantiate a player object, set up and enable its inputs. + /// + /// + /// + /// var p1 = PlayerInput.Instantiate(playerPrefab, controlScheme: "KeyboardLeft", device: Keyboard.current); + /// + /// public static PlayerInput Instantiate(GameObject prefab, int playerIndex = -1, string controlScheme = null, int splitScreenIndex = -1, InputDevice pairWithDevice = null) { @@ -1068,15 +1200,21 @@ public static PlayerInput Instantiate(GameObject prefab, int playerIndex = -1, s /// automatically pair one or more specific devices to the newly created player. /// /// A player prefab containing a component in its hierarchy. - /// - /// - /// - /// - /// + /// Player index to instantiate. + /// Control scheme to activate. + /// Which split screen to instantiate on. + /// Which devices to limit pairing to. + /// Newly created PlayerInput component. /// /// Note that unlike , this method will always activate the resulting /// and its components. /// + /// + /// + /// var devices = new InputDevice[] { Gamepad.all[0], Gamepad.all[1] }; + /// var p1 = PlayerInput.Instantiate(playerPrefab, controlScheme: "Gamepad", pairWithDevices: devices); + /// + /// public static PlayerInput Instantiate(GameObject prefab, int playerIndex = -1, string controlScheme = null, int splitScreenIndex = -1, params InputDevice[] pairWithDevices) { @@ -1761,8 +1899,32 @@ private void OnDisable() // ReSharper disable once UnusedMember.Global /// - /// Debug helper method that can be hooked up to actions when using . + /// Debug helper method that can be hooked up to actions. /// + /// Information about what triggered the action. + /// + /// Debug helper method that can be hooked up to actions when using . + /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// // Component to sit next to PlayerInput. + /// [RequireComponent(typeof(PlayerInput))] + /// public class MyPlayerLogic : MonoBehaviour + /// { + /// public void OnEnable() + /// { + /// var playerInput = GetComponent<PlayerInput>(); + /// playerInput.onActionTriggered += DebugLogAction; + /// } + /// public void OnDisable() + /// { + /// playerInput.onActionTriggered -= DebugLogAction; + /// } + /// } + /// + /// public void DebugLogAction(InputAction.CallbackContext context) { Debug.Log(context.ToString()); @@ -1953,7 +2115,7 @@ private void SwitchControlSchemeInternal(ref InputControlScheme controlScheme, p { Debug.Assert(devices != null); - // Note that we are doing two somwhat uncorrelated actions here: + // Note that we are doing two somewhat uncorrelated actions here: // - Switching control scheme // - Explicitly pairing with given devices regardless if making sense with respect to control scheme using (InputActionRebindingExtensions.DeferBindingResolution()) @@ -1978,19 +2140,68 @@ private void SwitchControlSchemeInternal(ref InputControlScheme controlScheme, p } } + /// + /// An event associated with an PlayerInput action. + /// + /// + /// Represents an event invoked in response to actions being triggered. + /// + /// Contains the ID and name of the being triggered and the associated to handle the action response. + /// + /// The list of action events is specified in Editor UI based on the selected . + /// The individual action callbacks are then specified in a . + /// + /// + /// + /// + /// public class MyPlayerScript : MonoBehaviour + /// { + /// void OnFireEvent(InputAction.CallbackContext context) + /// { + /// // Handle fire event + /// } + /// } + /// + /// + /// + /// [Serializable] public class ActionEvent : UnityEvent { + /// + /// Action GUID string for the action that triggered the event. + /// public string actionId => m_ActionId; + + /// + /// Name of the action that triggered the event. + /// public string actionName => m_ActionName; [SerializeField] private string m_ActionId; [SerializeField] private string m_ActionName; + /// + /// Construct an empty action event. + /// + /// + /// The event will not have an associated action. + /// + /// public ActionEvent() { } + /// + /// Construct an action event and associate it with an action. + /// + /// + /// The event will be associated with the specified action. The action must be part of an action asset. + /// + /// The action to associate with the event. The action must be part of an action asset. + /// The action is null. + /// The action is not part of an action asset. + /// public ActionEvent(InputAction action) { if (action == null) @@ -2004,6 +2215,15 @@ public ActionEvent(InputAction action) m_ActionName = $"{action.actionMap.name}/{action.name}"; } + /// + /// Construct an action event and associated it with an action by GUID. + /// + /// + /// The event will be associated with the specified action. + /// + /// Action GUID. + /// Name of the action. + /// public ActionEvent(Guid actionGUID, string name = null) { m_ActionId = actionGUID.ToString(); @@ -2014,7 +2234,9 @@ public ActionEvent(Guid actionGUID, string name = null) /// /// Event that is triggered when an paired to a is disconnected. /// - /// + /// + /// The device lost event can be set on via . + /// [Serializable] public class DeviceLostEvent : UnityEvent { @@ -2023,7 +2245,9 @@ public class DeviceLostEvent : UnityEvent /// /// Event that is triggered when a regains an previously lost. /// - /// + /// + /// The device regained event can be set on via . + /// [Serializable] public class DeviceRegainedEvent : UnityEvent { @@ -2032,7 +2256,9 @@ public class DeviceRegainedEvent : UnityEvent /// /// Event that is triggered when the set of controls used by a changes. /// - /// + /// + /// The changed event can be set on via . + /// [Serializable] public class ControlsChangedEvent : UnityEvent {