diff --git a/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/InputValue.cs b/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/InputValue.cs index c781ae9418..c6f9020f44 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/InputValue.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/InputValue.cs @@ -25,7 +25,7 @@ public class InputValue /// Read the value as an object. /// /// - /// This method allocates GC memory and will thus created garbage. If used during gameplay, + /// This method allocates GC memory and will thus create garbage. If used during gameplay, /// it will lead to GC spikes. /// /// The current value in the form of a boxed object. @@ -35,6 +35,43 @@ public object Get() } ////TODO: add automatic conversions + /// + /// Read the value of the action. + /// + /// The current value from the action cast to the specified type. + /// Type of value to read. This must correspond to the + /// expected by either or, if it is a composite, by the + /// in use. + /// Common types are float and Vector2, and depend on the type of the associated action + /// The given type + /// does not match the value type expected by the control or binding composite. + /// + /// The following example shows how to read a value from a message. + /// + /// + /// + /// [RequireComponent(typeof(PlayerInput))] + /// public class MyPlayerLogic : MonoBehaviour + /// { + /// private Vector2 m_Move; + /// + /// // 'Move' input action has been triggered. + /// public void OnMove(InputValue value) + /// { + /// // Read value from control. The type depends on what type of controls the action is bound to. + /// m_Move = value.Get<Vector2>(); + /// } + /// + /// public void OnUpdate() + /// { + /// // Update transform from m_Move + /// } + /// } + /// + /// + /// The given InputValue is only valid for the duration of the callback. Storing the InputValue references somewhere and calling Get<T>() later does not work correctly. + /// + /// public TValue Get() where TValue : struct { @@ -45,6 +82,36 @@ public TValue Get() } ////TODO: proper message if value type isn't right + /// + /// Check if the action button is pressed + /// + /// True if the button is activated over the button threshold. False otherwise + /// + /// The following example shows how to read a value from a message. + /// + /// + /// + /// [RequireComponent(typeof(PlayerInput))] + /// public class MyPlayerLogic : MonoBehaviour + /// { + /// private bool m_Fire; + /// + /// // 'Fire' input action has been triggered. + /// public void OnFire(InputValue value) + /// { + /// m_Fire = value.isPressed; + /// } + /// + /// public void OnUpdate() + /// { + /// // Perform fire action if m_Fire is true + /// } + /// } + /// + /// + /// The given InputValue is only valid for the duration of the callback. Storing the InputValue references somewhere and calling Get<T>() later does not work correctly. + /// + /// public bool isPressed => Get() >= ButtonControl.s_GlobalDefaultButtonPressPoint; internal InputAction.CallbackContext? m_Context; diff --git a/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/PlayerInput.cs b/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/PlayerInput.cs index ce27ff2620..5f864d024a 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/PlayerInput.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/PlayerInput.cs @@ -519,6 +519,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 UI. /// public ReadOnlyArray actionEvents { @@ -1978,19 +1980,54 @@ 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 action being triggered and the associated UnityAction to handle the action response. + /// + /// + /// + /// + /// + /// [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 associated 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 +2041,14 @@ 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();