From 208f8dda1ace1cf1e68d783ce4bff4a78b4e6e91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Mon, 2 Dec 2024 12:29:38 +0100 Subject: [PATCH 01/18] FIX: Added struct example and extended remarks section in xml docs. --- .../InputSystem/Actions/InputAction.cs | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index 4b025827ef..3f74e7ccec 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1791,7 +1791,80 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// Information provided to action callbacks about what triggered an action. /// /// + /// The callback context represents the current state of an associated with the callback + /// and provides information associated with the bound , its value as well as its + /// . + /// + /// The callback context provides means to consume events (push-based input) as part of an update when using + /// input action callback notifications, e.g. , + /// , rather than relying on + /// pull-based reading. + /// + /// Use this struct to read the current input value through any of the read-method overloads: + /// , , + /// or (unsafe). If the expected value type is not + /// known, it maye be required to check before reading the value. + /// + /// Use the property to get the current phase of the associated action or + /// evaluate it directly via any of the convenience methods , , + /// . + /// + /// To obtain information about the current timestamp of the associated event or reason about for how + /// long the action have been performing use or respectively. + /// /// This struct should not be held on to past the duration of the callback. + /// + /// + /// + /// public class MyController : MonoBehavior + /// { + /// [SerializeFiled] Character target; + /// [SerializeField] InputActionReference move; + /// [SerializeField] InputActionReference fire; + /// + /// void Awake() + /// { + /// // Get reference to an associated character behavior + /// character = GetComponent<Character>(); + /// + /// // 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.Enable(); + /// fire.Enable(); + /// } + /// + /// void OnDisable() + /// { + /// // Disable actions as part of disabling this behavior. + /// move.Disable(); + /// fire.Disable(); + /// } + /// + /// void MovePerformed(InputAction.CallbackContext context) + /// { + /// // Read the current 2D vector value reported by the associated input action. + /// var direction = context.ReadValue<Vector2>(); + /// target.Move( direction ); + /// } + /// + /// void FirePerformed(InputAction.CallbackContext context) + /// { + /// // If underlying interaction is a slow-tap fire charged projectile, otherwise fire regular + /// // projectile. + /// if (context.interaction is SlowTapInteraction) + /// target.FireChargedProjectile(); + /// else + /// target.FireProjectile(); + /// } + /// } + /// + /// /// /// /// From b352085ab39b90b14eba524a7cd803a8da2d7796 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Mon, 2 Dec 2024 13:57:06 +0100 Subject: [PATCH 02/18] Added more examples to methods. --- .../InputSystem/Actions/InputAction.cs | 111 +++++++++++++++++- 1 file changed, 108 insertions(+), 3 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index 3f74e7ccec..89e83722fa 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -2169,6 +2169,40 @@ public unsafe void ReadValue(void* buffer, int bufferSize) /// /// /// + /// + /// + /// 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. + /// Vector2 value = context.ReadValue<Vector2>(); + /// Debug.Log($"Value is: {value}"); + /// }; + /// } + /// } + /// + /// void OnEnable() + /// { + /// move.action?.Enable(); + /// } + /// + /// void OnDisable() + /// { + /// move.action?.Disable(); + /// } + /// } + /// + /// public TValue ReadValue() where TValue : struct { @@ -2192,6 +2226,40 @@ public TValue ReadValue() /// If the currently active control is a , the /// 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. + /// bool value = context.ReadValueAsButton(); + /// Debug.Log($"Button state is: {value}"); + /// }; + /// } + /// } + /// + /// void OnEnable() + /// { + /// fire.action?.Enable(); + /// } + /// + /// void OnDisable() + /// { + /// fire.action?.Disable(); + /// } + /// } + /// + /// /// /// /// @@ -2204,14 +2272,51 @@ 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(); + /// } + /// } + /// + /// /// /// /// From 2eefe5a8bffd0e8d99496c08308e7ef71e636d09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Mon, 2 Dec 2024 14:21:07 +0100 Subject: [PATCH 03/18] Fixed example that would not compile. --- .../InputSystem/Actions/InputAction.cs | 125 ++++++++++-------- 1 file changed, 71 insertions(+), 54 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index 89e83722fa..d0677038d9 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1816,53 +1816,53 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// /// /// - /// public class MyController : MonoBehavior - /// { - /// [SerializeFiled] Character target; - /// [SerializeField] InputActionReference move; - /// [SerializeField] InputActionReference fire; - /// - /// void Awake() - /// { - /// // Get reference to an associated character behavior - /// character = GetComponent<Character>(); - /// - /// // 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.Enable(); - /// fire.Enable(); - /// } - /// - /// void OnDisable() - /// { - /// // Disable actions as part of disabling this behavior. - /// move.Disable(); - /// fire.Disable(); - /// } - /// - /// void MovePerformed(InputAction.CallbackContext context) - /// { - /// // Read the current 2D vector value reported by the associated input action. - /// var direction = context.ReadValue<Vector2>(); - /// target.Move( direction ); - /// } - /// - /// void FirePerformed(InputAction.CallbackContext context) - /// { - /// // If underlying interaction is a slow-tap fire charged projectile, otherwise fire regular - /// // projectile. - /// if (context.interaction is SlowTapInteraction) - /// target.FireChargedProjectile(); - /// else - /// target.FireProjectile(); - /// } - /// } + /// 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(); + /// move.action?.Enable(); + /// } + /// + /// void OnDisable() + /// { + /// /// Disable actions as part of disabling this behavior. + /// move.action?.Disable(); + /// move.action?.Disable(); + /// } + /// + /// void MovePerformed(InputAction.CallbackContext context) + /// { + /// /// Read the current 2D vector value reported by the associated input action. + /// var direction = context.ReadValue(); + /// 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"); + /// } + /// } /// /// /// @@ -1954,14 +1954,31 @@ public unsafe InputActionPhase phase /// /// /// - /// 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"); + /// } /// } /// /// From e02fd35539f5e73bc55b6fef9b4340d7320d26ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Mon, 2 Dec 2024 15:40:39 +0100 Subject: [PATCH 04/18] Fixed xml syntax --- .../com.unity.inputsystem/InputSystem/Actions/InputAction.cs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index d0677038d9..c74906fd2e 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -2186,6 +2186,9 @@ public unsafe void ReadValue(void* buffer, int bufferSize) /// /// /// + /// + /// The following example shows how to read the current value of a specific type: + /// /// /// /// using UnityEngine; @@ -2220,6 +2223,7 @@ public unsafe void ReadValue(void* buffer, int bufferSize) /// } /// /// + /// public TValue ReadValue() where TValue : struct { From 1eebb720ddeb508914deb354c26f49550cde64cf Mon Sep 17 00:00:00 2001 From: Ben Pitt Date: Mon, 2 Dec 2024 16:17:11 +0000 Subject: [PATCH 05/18] Fixed some doc wording --- .../InputSystem/Actions/InputAction.cs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index c74906fd2e..97a84e6a55 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1792,27 +1792,27 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// /// /// The callback context represents the current state of an associated with the callback - /// and provides information associated with the bound , its value as well as its + /// and provides information associated with the bound , its value, and its /// . /// - /// The callback context provides means to consume events (push-based input) as part of an update when using - /// input action callback notifications, e.g. , + /// 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. /// /// Use this struct to read the current input value through any of the read-method overloads: /// , , - /// or (unsafe). If the expected value type is not - /// known, it maye be required to check before reading the value. + /// 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 via any of the convenience methods , , + /// evaluate it directly using any of the convenience methods , , /// . /// - /// To obtain information about the current timestamp of the associated event or reason about for how - /// long the action have been performing use or respectively. + /// To obtain information about the current timestamp of the associated event, or to check when the event + /// started, use or respectively. /// - /// This struct should not be held on to past the duration of the callback. + /// You should not use or keep this struct outside of the callback. /// /// /// From fe9c8c07a66b20b95edc9824e36b1fe15a2b7542 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Tue, 3 Dec 2024 07:36:10 +0100 Subject: [PATCH 06/18] Fixed typo in example --- .../InputSystem/Actions/InputAction.cs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index 97a84e6a55..18870db8cc 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1836,14 +1836,14 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// { /// /// Enable actions as part of enabling this behavior. /// move.action?.Enable(); - /// move.action?.Enable(); + /// fire.action?.Enable(); /// } /// /// void OnDisable() /// { /// /// Disable actions as part of disabling this behavior. /// move.action?.Disable(); - /// move.action?.Disable(); + /// fire.action?.Disable(); /// } /// /// void MovePerformed(InputAction.CallbackContext context) @@ -2188,7 +2188,7 @@ public unsafe void ReadValue(void* buffer, int bufferSize) /// /// /// The following example shows how to read the current value of a specific type: - /// + /// /// /// /// using UnityEngine; From f8ba4f649709ad3650b42a2c486a851a24785bec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Tue, 3 Dec 2024 14:17:16 +0100 Subject: [PATCH 07/18] Added paragraph formatting and removed redundant tags. --- .../InputSystem/Actions/InputAction.cs | 36 ++++++++----------- 1 file changed, 14 insertions(+), 22 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index 18870db8cc..f3f0f4589b 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1794,26 +1794,25 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// 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. - /// + ///
/// 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; @@ -1905,34 +1904,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. @@ -1950,7 +1947,6 @@ 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. /// /// /// @@ -2001,9 +1997,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 @@ -2022,10 +2019,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. @@ -2047,7 +2042,6 @@ 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. @@ -2083,7 +2077,6 @@ public unsafe double 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 @@ -2099,9 +2092,8 @@ 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 From ff657a5e8fe8590c6f64cb5fe8452dde2e80d118 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Tue, 3 Dec 2024 14:25:46 +0100 Subject: [PATCH 08/18] Swapped br for para tags --- .../InputSystem/Actions/InputAction.cs | 39 +++++++++++++------ 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index f3f0f4589b..c43e2c58a9 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1077,14 +1077,16 @@ public unsafe object ReadValueAsObject() /// /// 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 . - ///
+ /// + /// /// 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. + /// /// /// /// @@ -1369,10 +1371,13 @@ public unsafe bool WasPerformedThisFrame() /// 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 +1388,9 @@ 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,12 @@ 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. - /// + /// /// /// /// var teleport = playerInput.actions["Teleport"]; @@ -1794,25 +1802,30 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// 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. - ///
+ /// + /// /// 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, + /// 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; @@ -2081,10 +2094,11 @@ public unsafe double startTime /// 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). + /// /// /// /// @@ -2099,9 +2113,10 @@ public unsafe double startTime /// 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 . + /// /// /// /// From 13a60218915ab9201c69fb2770b32ced05dd6db9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Tue, 3 Dec 2024 14:38:13 +0100 Subject: [PATCH 09/18] Addressed issues turning up as negative score in docs audit. --- .../InputSystem/Actions/InputAction.cs | 54 ++++++++++++++----- 1 file changed, 42 insertions(+), 12 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index c43e2c58a9..b2cace50a6 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -2182,12 +2182,12 @@ 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. /// @@ -2212,20 +2212,19 @@ public unsafe void ReadValue(void* buffer, int bufferSize) /// move.action.performed += context => /// { /// // Note: Assumes the underlying value type is Vector2. - /// Vector2 value = context.ReadValue<Vector2>(); - /// Debug.Log($"Value is: {value}"); + /// Debug.Log($"Value is: {context.ReadValue<Vector2>()}"); /// }; /// } /// } /// /// void OnEnable() /// { - /// move.action?.Enable(); + /// move.action.Enable(); /// } /// /// void OnDisable() /// { - /// move.action?.Disable(); + /// move.action.Disable(); /// } /// } /// @@ -2270,20 +2269,19 @@ public TValue ReadValue() /// fire.action.performed += context => /// { /// // ReadValueAsButton attempts to interpret the value as a button. - /// bool value = context.ReadValueAsButton(); - /// Debug.Log($"Button state is: {value}"); + /// Debug.Log($"Is firing: {context.ReadValueAsButton()}"); /// }; /// } /// } /// /// void OnEnable() /// { - /// fire.action?.Enable(); + /// fire.action.Enable(); /// } /// /// void OnDisable() /// { - /// fire.action?.Disable(); + /// fire.action.Disable(); /// } /// } /// @@ -2335,12 +2333,12 @@ public bool ReadValueAsButton() /// /// void OnEnable() /// { - /// move.action?.Enable(); + /// move.action.Enable(); /// } /// /// void OnDisable() /// { - /// move.action?.Disable(); + /// move.action.Disable(); /// } /// } /// @@ -2359,6 +2357,38 @@ 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} }}"; From 4735c2a911ad9a872aaa0d8b58d25e92781d9dd7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Tue, 3 Dec 2024 16:52:57 +0100 Subject: [PATCH 10/18] Moved example out of remarks --- .../InputSystem/Actions/InputAction.cs | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index b2cace50a6..e1d3bcfdb1 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -2191,11 +2191,11 @@ public unsafe void ReadValue(void* buffer, int bufferSize) /// 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; @@ -2229,7 +2229,6 @@ public unsafe void ReadValue(void* buffer, int bufferSize) /// } /// /// - /// public TValue ReadValue() where TValue : struct { @@ -2253,6 +2252,7 @@ public TValue ReadValue() /// If the currently active control is a , the /// 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; @@ -2286,7 +2286,6 @@ public TValue ReadValue() /// } /// /// - /// /// /// public bool ReadValueAsButton() @@ -2306,6 +2305,7 @@ public bool ReadValueAsButton() /// /// This method allocates GC heap memory due to boxing. Using it during normal gameplay will lead /// to frame-rate instabilities. + /// /// /// /// using UnityEngine; @@ -2343,7 +2343,6 @@ public bool ReadValueAsButton() /// } /// /// - /// /// /// public object ReadValueAsObject() @@ -2360,7 +2359,7 @@ public object ReadValueAsObject() /// /// The following example illustrates how to log callback context to console when a callback is received /// for debugging purposes: - /// + /// /// /// /// using UnityEngine; @@ -2388,7 +2387,6 @@ public object ReadValueAsObject() /// } /// /// - /// public override string ToString() { return $"{{ action={action} phase={phase} time={time} control={control} value={ReadValueAsObject()} interaction={interaction} }}"; From adf6ff85a1d36e9cdacef02553738675c61f15ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Tue, 3 Dec 2024 18:17:01 +0100 Subject: [PATCH 11/18] Removewd paragraph --- .../InputSystem/Actions/InputAction.cs | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index e1d3bcfdb1..76eeda3e3e 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -2093,12 +2093,9 @@ public unsafe double startTime /// /// 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). /// /// /// From 4ffceef0195fe025b92c9f0e5d3126acfcf91498 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Wed, 4 Dec 2024 14:17:32 +0100 Subject: [PATCH 12/18] Fixed malformed xml --- .../InputSystem/Actions/InputAction.cs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index 76eeda3e3e..91f48cb1b2 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1847,21 +1847,21 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// void OnEnable() /// { /// /// Enable actions as part of enabling this behavior. - /// move.action?.Enable(); - /// fire.action?.Enable(); + /// move.action.Enable(); + /// fire.action.Enable(); /// } /// /// void OnDisable() /// { /// /// Disable actions as part of disabling this behavior. - /// move.action?.Disable(); - /// fire.action?.Disable(); + /// 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(); + /// var direction = context.ReadValue<Vector2>(); /// Debug.Log("Move: " + direction * Time.deltaTime); /// } /// From 98ccafc5add84735fc39a5edd03439320ee0ea65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Wed, 4 Dec 2024 15:11:36 +0100 Subject: [PATCH 13/18] xmldoc fixes --- .../InputSystem/Actions/InputAction.cs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index 91f48cb1b2..93a760c3c3 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -2113,11 +2113,11 @@ public unsafe double startTime /// /// 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 @@ -2130,16 +2130,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. @@ -2155,7 +2154,8 @@ public int valueSizeInBytes /// } /// /// - /// + /// is null. + /// is too small. /// /// /// From 826386a7fc297f8caed277be5015056e2cc620b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Wed, 4 Dec 2024 21:23:01 +0100 Subject: [PATCH 14/18] Fixed xmldoc violations. --- .../InputSystem/Actions/InputAction.cs | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index 93a760c3c3..beb35318b9 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1417,12 +1417,14 @@ 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. + /// /// /// /// @@ -2058,7 +2060,7 @@ public unsafe double startTime /// /// 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 @@ -2083,7 +2085,6 @@ public unsafe double startTime /// }; /// /// - /// public double duration => time - startTime; /// @@ -2113,7 +2114,8 @@ public unsafe double startTime /// /// The value of this property determines how many bytes will be written /// by . - /// + /// + /// /// This property indirectly maps to the value of or /// . /// From 7b377f025bf149924959f7e81b8ce2f4b46d18ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Wed, 4 Dec 2024 21:52:40 +0100 Subject: [PATCH 15/18] Adressed more xmldoc errors in validation tool --- .../com.unity.inputsystem/InputSystem/Actions/InputAction.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index beb35318b9..ec9e5a88e4 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1408,6 +1408,7 @@ public unsafe bool WasPerformedThisFrame() /// 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. /// + /// /// /// /// var teleport = playerInput.actions["Teleport"]; @@ -1425,7 +1426,6 @@ public unsafe bool WasPerformedThisFrame() /// 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. /// - /// /// /// /// @@ -1828,6 +1828,7 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// /// You should not use or keep this struct outside of the callback. /// + /// /// /// /// using UnityEngine; @@ -1879,7 +1880,6 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// } /// /// - /// /// /// /// From 29ab9abd9fc949693e5672ed56623866b78a1b84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Wed, 11 Dec 2024 14:46:24 +0100 Subject: [PATCH 16/18] Added link to manual on responding to actions. --- .../com.unity.inputsystem/InputSystem/Actions/InputAction.cs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index ec9e5a88e4..8e2755cab1 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1808,7 +1808,8 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// 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. + /// 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: From 2a7a882633b31e0b1b038f366c4ca92716a14382 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Wed, 11 Dec 2024 15:12:41 +0100 Subject: [PATCH 17/18] Fixed xml doc errors --- .../InputSystem/Actions/InputAction.cs | 25 +++++++++++-------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index 8e2755cab1..5f929d8a1f 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1368,15 +1368,15 @@ 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 @@ -1389,7 +1389,6 @@ public unsafe bool WasPerformedThisFrame() /// 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 @@ -1408,6 +1407,14 @@ public unsafe bool WasPerformedThisFrame() /// 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. + /// /// /// /// @@ -1418,14 +1425,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. - /// /// /// /// @@ -1801,9 +1800,11 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// Information provided to action callbacks about what triggered an action. /// /// + /// /// 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, , @@ -2108,10 +2109,12 @@ public unsafe double startTime /// Size of values returned by in bytes. /// /// + /// /// 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 . From ee490c4b0f549f8f1d4dc13044dca9cc55a4f86d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akan=20Sidenvall?= Date: Wed, 11 Dec 2024 15:52:08 +0100 Subject: [PATCH 18/18] Fixing xmldoc violations. --- .../InputSystem/Actions/InputAction.cs | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs index 5f929d8a1f..c5fbf9f2ae 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs @@ -1075,12 +1075,15 @@ 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 @@ -1088,8 +1091,6 @@ public unsafe object ReadValueAsObject() /// 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; @@ -1809,8 +1810,8 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap) /// 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. + /// 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: