diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index 4b025827ef..c5fbf9f2ae 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1075,19 +1075,22 @@ public unsafe object ReadValueAsObject() /// Returns the current level of control actuation (usually [0..1]) or -1 if /// the control is actuated but does not support computing magnitudes. /// + /// /// Magnitudes do not make sense for all types of controls. Controls that have no meaningful magnitude /// will return -1 when calling this method. Any negative magnitude value should be considered an invalid value. - ///
+ /// + /// /// The magnitude returned by an action is usually determined by the /// that triggered the action, i.e. by the - /// control referenced from . - ///
+ /// control referenced from . See and + /// for additional information. + /// + /// /// However, if the binding that triggered is a composite, then the composite /// will determine the magnitude and not the individual control that triggered. /// Instead, the value of the control that triggered the action will be fed into the composite magnitude calculation. + /// /// - /// - /// public unsafe float GetControlMagnitude() { var state = GetOrCreateActionMap().m_State; @@ -1366,13 +1369,16 @@ public unsafe bool WasPerformedThisFrame() /// /// True if the action completed this frame. /// + /// /// Although is technically a phase, this method does not consider disabling /// the action while the action is in to be "completed". - /// + /// + /// /// This method is different from in that it depends directly on the /// interaction(s) driving the action (including the default interaction if no specific interaction /// has been added to the action or binding). - /// + /// + /// /// For example, let's say the action is bound to the space bar and that the binding has a /// assigned to it. In the frame where the space bar /// is pressed, will be true (because the button/key is now pressed) @@ -1383,7 +1389,8 @@ public unsafe bool WasPerformedThisFrame() /// the phase will change to and stay and /// will be true for one frame as it meets the duration threshold. Once released, WasCompletedThisFrame will be true /// (because the action is no longer performed) and only in the frame where the hold transitioned away from Performed. - /// + /// + /// /// For another example where the action could be considered pressed but also completed, let's say the action /// is bound to the thumbstick and that the binding has a Sector interaction from the XR Interaction Toolkit assigned /// to it such that it only performs in the forward sector area past a button press threshold. In the frame where the @@ -1395,11 +1402,21 @@ public unsafe bool WasPerformedThisFrame() /// the thumbstick was no longer within the forward sector. For more details about the Sector interaction, see /// SectorInteraction /// in the XR Interaction Toolkit Scripting API documentation. - ///
+ /// + /// /// Unlike , which will reset when the action goes back to waiting /// state, this property will stay true for the duration of the current frame (that is, until the next /// runs) as long as the action was completed at least once. - /// + /// + /// + /// This method will disregard whether the action is currently enabled or disabled. It will keep returning + /// true for the duration of the frame even if the action was subsequently disabled in the frame. + /// + /// + /// The meaning of "frame" is either the current "dynamic" update (MonoBehaviour.Update) or the current + /// fixed update (MonoBehaviour.FixedUpdate) depending on the value of the setting. + /// + /// /// /// /// var teleport = playerInput.actions["Teleport"]; @@ -1409,13 +1426,6 @@ public unsafe bool WasPerformedThisFrame() /// StopTeleport(); /// /// - /// - /// This method will disregard whether the action is currently enabled or disabled. It will keep returning - /// true for the duration of the frame even if the action was subsequently disabled in the frame. - /// - /// The meaning of "frame" is either the current "dynamic" update (MonoBehaviour.Update) or the current - /// fixed update (MonoBehaviour.FixedUpdate) depending on the value of the setting. - /// /// /// /// @@ -1791,8 +1801,88 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// Information provided to action callbacks about what triggered an action. /// /// - /// This struct should not be held on to past the duration of the callback. + /// + /// The callback context represents the current state of an associated with the callback + /// and provides information associated with the bound , its value, and its + /// . + /// + /// + /// The callback context provides you with a way to consume events (push-based input) as part of an update when using + /// input action callback notifications. For example, , + /// , rather than relying on + /// pull-based reading. Also see + /// Responding To Actions for additional information on differences between callbacks and polling. + /// + /// + /// Use this struct to read the current input value through any of the read-method overloads: + /// , , + /// or (unsafe). If you don't know the expected value type, + /// you might need to check before reading the value. + /// + /// + /// Use the property to get the current phase of the associated action or + /// evaluate it directly using any of the convenience methods , , + /// . + /// + /// + /// To obtain information about the current timestamp of the associated event, or to check when the event + /// started, use or respectively. + /// + /// + /// You should not use or keep this struct outside of the callback. + /// /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// using UnityEngine.InputSystem.Interactions; + /// + /// public class MyController : MonoBehaviour + /// { + /// [SerializeField] InputActionReference move; + /// [SerializeField] InputActionReference fire; + /// + /// void Awake() + /// { + /// /// Receive notifications when move or fire actions are performed + /// move.action.performed += MovePerformed; + /// fire.action.performed += FirePerformed; + /// } + /// + /// void OnEnable() + /// { + /// /// Enable actions as part of enabling this behavior. + /// move.action.Enable(); + /// fire.action.Enable(); + /// } + /// + /// void OnDisable() + /// { + /// /// Disable actions as part of disabling this behavior. + /// move.action.Disable(); + /// fire.action.Disable(); + /// } + /// + /// void MovePerformed(InputAction.CallbackContext context) + /// { + /// /// Read the current 2D vector value reported by the associated input action. + /// var direction = context.ReadValue<Vector2>(); + /// Debug.Log("Move: " + direction * Time.deltaTime); + /// } + /// + /// void FirePerformed(InputAction.CallbackContext context) + /// { + /// /// If underlying interaction is a slow-tap fire charged projectile, otherwise fire regular + /// /// projectile. + /// if (context.interaction is SlowTapInteraction) + /// Debug.Log("Fire charged projectile"); + /// else + /// Debug.Log("Fire projectile"); + /// } + /// } + /// + /// /// /// /// @@ -1832,34 +1922,32 @@ public unsafe InputActionPhase phase /// /// Whether the has just been started. /// - /// If true, the action was just started. + /// If true, the action was just started. /// public bool started => phase == InputActionPhase.Started; /// /// Whether the has just been performed. /// - /// If true, the action was just performed. + /// If true, the action was just performed. /// public bool performed => phase == InputActionPhase.Performed; /// /// Whether the has just been canceled. /// - /// If true, the action was just canceled. + /// If true, the action was just canceled. /// public bool canceled => phase == InputActionPhase.Canceled; /// - /// The action that got triggered. + /// The associated action that triggered the callback. /// - /// Action that got triggered. public InputAction action => m_State?.GetActionOrNull(bindingIndex); /// /// The control that triggered the action. /// - /// Control that triggered the action. /// /// In case of a composite binding, this is the control of the composite that activated the /// composite as a whole. For example, in case of a WASD-style binding, it could be the W key. @@ -1877,18 +1965,34 @@ public unsafe InputActionPhase phase /// The interaction that triggered the action or null if the binding that triggered does not /// have any particular interaction set on it. /// - /// Interaction that triggered the callback. /// /// /// - /// void FirePerformed(InputAction.CallbackContext context) + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// using UnityEngine.InputSystem.Interactions; + /// + /// class Example : MonoBehaviour /// { - /// // If SlowTap interaction was performed, perform a charged - /// // firing. Otherwise, fire normally. - /// if (context.interaction is SlowTapInteraction) - /// FireChargedProjectile(); - /// else - /// FireNormalProjectile(); + /// public InputActionReference fire; + /// + /// public void Awake() + /// { + /// fire.action.performed += FirePerformed; + /// } + /// + /// void OnEnable() => fire.action.Enable(); + /// void OnDisable() => fire.action.Disable(); + /// + /// void FirePerformed(InputAction.CallbackContext context) + /// { + /// /// If SlowTap interaction was performed, perform a charged + /// /// firing. Otherwise, fire normally. + /// if (context.interaction is SlowTapInteraction) + /// Debug.Log("Fire charged projectile"); + /// else + /// Debug.Log("Fire projectile"); + /// } /// } /// /// @@ -1911,9 +2015,10 @@ public IInputInteraction interaction /// /// The time at which the action got triggered. /// - /// Time relative to Time.realtimeSinceStartup at which - /// the action got triggered. /// + /// Time is relative to at which the action got + /// triggered. + /// /// This is usually determined by the timestamp of the input event that activated a control /// bound to the action. What this means is that this is normally not the /// value of Time.realtimeSinceStartup when the input system calls the @@ -1932,10 +2037,8 @@ public unsafe double time } /// - /// Time at which the action was started. + /// Time at which the action was with relation to Time.realtimeSinceStartup. /// - /// Value relative to Time.realtimeSinceStartup when the action - /// changed to . /// /// This is only relevant for actions that go through distinct a /// cycle as driven by interactions. @@ -1957,11 +2060,10 @@ public unsafe double startTime /// /// Time difference between and . /// - /// Difference between and . /// /// This property can be used, for example, to determine how long a button /// was held down. - /// + /// /// /// /// // Let's create a button action bound to the A button @@ -1986,22 +2088,18 @@ public unsafe double startTime /// }; /// /// - /// public double duration => time - startTime; /// /// Type of value returned by and expected /// by . /// - /// Type of object returned when reading a value. /// /// The type of value returned by an action is usually determined by the /// that triggered the action, i.e. by the - /// control referenced from . - /// - /// However, if the binding that triggered is a composite, then the composite - /// will determine values and not the individual control that triggered (that - /// one just feeds values into the composite). + /// control referenced from . However, if the binding that + /// triggered is a composite, then the composite will determine values and + /// not the individual control that triggered (that one just feeds values into the composite). /// /// /// @@ -2009,21 +2107,24 @@ public unsafe double startTime public Type valueType => m_State?.GetValueType(bindingIndex, controlIndex); /// - /// Size of values returned by . + /// Size of values returned by in bytes. /// - /// Size of value returned when reading. /// + /// /// All input values passed around by the system are required to be "blittable", /// i.e. they cannot contain references, cannot be heap objects themselves, and /// must be trivially mem-copyable. This means that any value can be read out /// and retained in a raw byte buffer. - /// + /// + /// /// The value of this property determines how many bytes will be written /// by . + /// + /// + /// This property indirectly maps to the value of or + /// . + /// /// - /// - /// - /// public int valueSizeInBytes { get @@ -2036,16 +2137,15 @@ public int valueSizeInBytes } /// - /// Read the value of the action as a raw byte buffer. This allows reading - /// values without having to know value types but also, unlike , - /// without allocating GC heap memory. + /// Read the value of the action as a raw byte buffer. /// /// Memory buffer to read the value into. /// Size of buffer allocated at . Must be /// at least . - /// is null. - /// is too small. /// + /// This allows reading values without having to know value types but also, + /// unlike , without allocating GC heap memory. + /// /// /// /// // Read a Vector2 using the raw memory ReadValue API. @@ -2061,7 +2161,8 @@ public int valueSizeInBytes /// } /// /// - /// + /// is null. + /// is too small. /// /// /// @@ -2085,17 +2186,53 @@ public unsafe void ReadValue(void* buffer, int bufferSize) } /// - /// Read the value of the action. + /// Read the current value of the associated action. /// /// Type of value to read. This must correspond to the /// expected by either or, if it is a composite, by the /// in use. - /// The value read from the action. + /// The current value of type associated with the action. /// The given type /// does not match the value type expected by the control or binding composite. /// - /// + /// /// + /// + /// The following example shows how to read the current value of a specific type: + /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class Example : MonoBehaviour + /// { + /// public InputActionReference move; + /// + /// void Awake() + /// { + /// if (move.action != null) + /// { + /// move.action.performed += context => + /// { + /// // Note: Assumes the underlying value type is Vector2. + /// Debug.Log($"Value is: {context.ReadValue<Vector2>()}"); + /// }; + /// } + /// } + /// + /// void OnEnable() + /// { + /// move.action.Enable(); + /// } + /// + /// void OnDisable() + /// { + /// move.action.Disable(); + /// } + /// } + /// + /// public TValue ReadValue() where TValue : struct { @@ -2120,6 +2257,39 @@ public TValue ReadValue() /// of the button will be taken into account (if set). If there is no custom button press point, the /// global will be used. /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class Example : MonoBehaviour + /// { + /// public InputActionReference fire; + /// + /// void Awake() + /// { + /// if (fire.action != null) + /// { + /// fire.action.performed += context => + /// { + /// // ReadValueAsButton attempts to interpret the value as a button. + /// Debug.Log($"Is firing: {context.ReadValueAsButton()}"); + /// }; + /// } + /// } + /// + /// void OnEnable() + /// { + /// fire.action.Enable(); + /// } + /// + /// void OnDisable() + /// { + /// fire.action.Disable(); + /// } + /// } + /// + /// /// /// public bool ReadValueAsButton() @@ -2131,15 +2301,52 @@ public bool ReadValueAsButton() } /// - /// Same as except that it is not necessary to - /// know the type of value at compile time. + /// Same as except that it is not necessary to know the type of the value + /// at compile time. /// /// The current value from the binding that triggered the action or null if the action /// is not currently in progress. /// - /// This method allocates GC heap memory. Using it during normal gameplay will lead + /// This method allocates GC heap memory due to boxing. Using it during normal gameplay will lead /// to frame-rate instabilities. /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class Example : MonoBehaviour + /// { + /// public InputActionReference move; + /// + /// void Awake() + /// { + /// if (move.action != null) + /// { + /// move.action.performed += context => + /// { + /// // ReadValueAsObject allows reading the associated value as a boxed reference type. + /// object obj = context.ReadValueAsObject(); + /// if (obj is Vector2) + /// Debug.Log($"Current value is Vector2 type: {obj}"); + /// else + /// Debug.Log($"Current value is of another type: {context.valueType}"); + /// }; + /// } + /// } + /// + /// void OnEnable() + /// { + /// move.action.Enable(); + /// } + /// + /// void OnDisable() + /// { + /// move.action.Disable(); + /// } + /// } + /// + /// /// /// public object ReadValueAsObject() @@ -2153,6 +2360,37 @@ public object ReadValueAsObject() /// Return a string representation of the context useful for debugging. /// /// String representation of the context. + /// + /// The following example illustrates how to log callback context to console when a callback is received + /// for debugging purposes: + /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class Example : MonoBehaviour + /// { + /// public InputActionReference move; + /// + /// void Awake() + /// { + /// if (move.action != null) + /// { + /// move.action.performed += context => + /// { + /// // Outputs the associated callback context in its textual representation which may + /// // be useful for debugging purposes. + /// Debug.Log(context.ToString()); + /// }; + /// } + /// } + /// + /// void OnEnable() => move.action.Enable(); + /// void OnDisable() => move.action.Disable(); + /// } + /// + /// public override string ToString() { return $"{{ action={action} phase={phase} time={time} control={control} value={ReadValueAsObject()} interaction={interaction} }}";