com.unity.xr.interaction.toolkit@2.3.1

## [2.3.1] - 2023-03-27

### Added
- Added System Gesture Detector component to the Hands Interaction Demo sample to add system gesture and menu palm pinch gesture events. Added sound upon menu press as an example. Added Aim Flags input actions to the `XRI Default Input Actions` in the Starter Assets sample to support this.
- Added [Interaction filters](../manual/interaction-filters.md) documentation for `IXRHoverFilter`, `IXRSelectFilter`, `IXRInteractionStrengthFilter`, and the corresponding filter delegates with examples.

### Changed
- Changed the Poke Gesture Detector component in the Hands Interaction Demo sample to no longer end the poke gesture when hand tracking is lost. This fixes the Ray Interactor line visual reappearing when hand tracking is lost while doing the poke gesture.
- Changed `XRInteractorReticleVisual` to ensure consistent attempts to align the reticle prefab's `z` axis with the `transform.up` of the XROrigin when `AlignPrefabWithSurfaceNormal` is `true` and aligning with a non-horizontal surface.
- Changed `XRInteractorReticleVisual` to align the reticle prefab's `z` axis with the forward direction of the reticle's interactor when `AlignPrefabWithSurfaceNormal` is `true` and aligning with a horizontal surface.
- Updated installation documentation with convenience links for installing the XRI package on older versions of Unity 2021 where the package was not included in the main Editor manifest.
- Changed so UGUI poke interactions are now considered to be blocking interactions for interaction groups. This allows rays to be properly hidden when hovering or selecting a UGUI canvas with poke.
- Changed to use velocity estimation of poke interactor to add an extra validation mechanism in the XR Poke Filter hover validation check to allow poke selection to occur in cases where it was previously rejected, while still preventing poking from behind and other non-desireable cases.
- Changed to cache poke selection validation check so that it's easier to hold a poke when the selection conditions are met. This makes scrolling UGUI canvases easier and makes poke interactions feel more consistent.
- Changed AR Scale Interactable so changing the Min Scale and/or Max Scale during runtime will keep the current object scale if still within range instead of resizing the object to keep the same scale ratio.

### Fixed
- Fixed the Hands Interaction Demo sample to wait to activate the controller GameObjects until they are reconnected instead of each time hand tracking is lost. Also fixed the controllers appearing at the origin if they have never been tracked.
- Fixed the Hands Interaction Demo sample so it disables the hand interactors while doing a system gesture (such as a user looking at their open palm at eye level).
- Fixed warning about a self-intersecting polygon in the `Frame.fbx` model in the Hands Interaction Demo sample.
- Fixed warning in Hands Interaction Demo sample about obsolete API usage coming from the hands subsystem.
- Fixed `XRSimulatedController` and `XRSimulatedHMD` to have identifying characteristics information in the `capabilities` field of their corresponding `InputDeviceDescription`. ([XRIT-50](https://issuetracker.unity3d.com/product/unity/issues/guid/XRIT-50))
- Fixed an issue in the `XRController` class where the `inputDevice` property was not reinitialized when the `controllerNode` property was changed. ([XRIT-52](https://issuetracker.unity3d.com/product/unity/issues/guid/XRIT-52))
- UGUI ray interactions are now correctly blocked when interaction groups block ray interactions and the ray is hidden.
- Fixed an issue with `TrackedDeviceGraphicRaycaster`, when using the `XRPokeInteractor` on UGUI canvases with different sort orders, where interaction was blocked on all but the highest Order in Layer valued canvas. ([XRIT-48](https://issuetracker.unity3d.com/product/unity/issues/guid/XRIT-48))
- Fixed an issue with `TrackedDeviceGraphicsRaycaster`, where opening a dropdown would block all other UGUI canvases to become non-interactable with an `XRPokeInteractor` until the dropdown was closed.
- Fixed the `Starter Assets` and `Hands Interaction Demo` prefabs which contained components and shaders with a mix of both Built-in Render Pipeline and Universal Render Pipeline. They are all now using Built-in Render Pipeline for consistency.
- Fixed `XRInteractorReticleVisual` incorrect rotation around `y` axis when aligning prefab to surface normal. ([XRIT-18](https://issuetracker.unity3d.com/product/unity/issues/guid/XRIT-18))
- Fixed `XRInteractorReticleVisual` incorrect rotation when `AlignPrefabWithSurfaceNormal` is `false`.
- Fixed `XRInteractorReticleVisual` inconsistent rotation when `AlignPrefabWithSurfaceNormal` and `DrawOnNoHit` are `true` but there is no active hit.
- Fixed `UIInputModule` issue where tracked devices cannot drag on UI elements when `Cursor.lockState` is set to `Locked`.

Author: Unity Technologies

CHANGELOG.md

@@ -5,6 +5,38 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 <!-- Headers should be listed in this order: Added, Changed, Deprecated, Removed, Fixed, Security -->
+## [2.3.1] - 2023-03-27
+
+### Added
+- Added System Gesture Detector component to the Hands Interaction Demo sample to add system gesture and menu palm pinch gesture events. Added sound upon menu press as an example. Added Aim Flags input actions to the `XRI Default Input Actions` in the Starter Assets sample to support this.
+- Added [Interaction filters](../manual/interaction-filters.md) documentation for `IXRHoverFilter`, `IXRSelectFilter`, `IXRInteractionStrengthFilter`, and the corresponding filter delegates with examples.
+
+### Changed
+- Changed the Poke Gesture Detector component in the Hands Interaction Demo sample to no longer end the poke gesture when hand tracking is lost. This fixes the Ray Interactor line visual reappearing when hand tracking is lost while doing the poke gesture.
+- Changed `XRInteractorReticleVisual` to ensure consistent attempts to align the reticle prefab's `z` axis with the `transform.up` of the XROrigin when `AlignPrefabWithSurfaceNormal` is `true` and aligning with a non-horizontal surface.
+- Changed `XRInteractorReticleVisual` to align the reticle prefab's `z` axis with the forward direction of the reticle's interactor when `AlignPrefabWithSurfaceNormal` is `true` and aligning with a horizontal surface.
+- Updated installation documentation with convenience links for installing the XRI package on older versions of Unity 2021 where the package was not included in the main Editor manifest.
+- Changed so UGUI poke interactions are now considered to be blocking interactions for interaction groups. This allows rays to be properly hidden when hovering or selecting a UGUI canvas with poke.
+- Changed to use velocity estimation of poke interactor to add an extra validation mechanism in the XR Poke Filter hover validation check to allow poke selection to occur in cases where it was previously rejected, while still preventing poking from behind and other non-desireable cases.
+- Changed to cache poke selection validation check so that it's easier to hold a poke when the selection conditions are met. This makes scrolling UGUI canvases easier and makes poke interactions feel more consistent.
+- Changed AR Scale Interactable so changing the Min Scale and/or Max Scale during runtime will keep the current object scale if still within range instead of resizing the object to keep the same scale ratio.
+
+### Fixed
+- Fixed the Hands Interaction Demo sample to wait to activate the controller GameObjects until they are reconnected instead of each time hand tracking is lost. Also fixed the controllers appearing at the origin if they have never been tracked.
+- Fixed the Hands Interaction Demo sample so it disables the hand interactors while doing a system gesture (such as a user looking at their open palm at eye level).
+- Fixed warning about a self-intersecting polygon in the `Frame.fbx` model in the Hands Interaction Demo sample.
+- Fixed warning in Hands Interaction Demo sample about obsolete API usage coming from the hands subsystem. 
+- Fixed `XRSimulatedController` and `XRSimulatedHMD` to have identifying characteristics information in the `capabilities` field of their corresponding `InputDeviceDescription`. ([XRIT-50](https://issuetracker.unity3d.com/product/unity/issues/guid/XRIT-50))
+- Fixed an issue in the `XRController` class where the `inputDevice` property was not reinitialized when the `controllerNode` property was changed. ([XRIT-52](https://issuetracker.unity3d.com/product/unity/issues/guid/XRIT-52))
+- UGUI ray interactions are now correctly blocked when interaction groups block ray interactions and the ray is hidden.
+- Fixed an issue with `TrackedDeviceGraphicRaycaster`, when using the `XRPokeInteractor` on UGUI canvases with different sort orders, where interaction was blocked on all but the highest Order in Layer valued canvas. ([XRIT-48](https://issuetracker.unity3d.com/product/unity/issues/guid/XRIT-48))
+- Fixed an issue with `TrackedDeviceGraphicsRaycaster`, where opening a dropdown would block all other UGUI canvases to become non-interactable with an `XRPokeInteractor` until the dropdown was closed.
+- Fixed the `Starter Assets` and `Hands Interaction Demo` prefabs which contained components and shaders with a mix of both Built-in Render Pipeline and Universal Render Pipeline. They are all now using Built-in Render Pipeline for consistency.
+- Fixed `XRInteractorReticleVisual` incorrect rotation around `y` axis when aligning prefab to surface normal. ([XRIT-18](https://issuetracker.unity3d.com/product/unity/issues/guid/XRIT-18))
+- Fixed `XRInteractorReticleVisual` incorrect rotation when `AlignPrefabWithSurfaceNormal` is `false`.
+- Fixed `XRInteractorReticleVisual` inconsistent rotation when `AlignPrefabWithSurfaceNormal` and `DrawOnNoHit` are `true` but there is no active hit.
+- Fixed `UIInputModule` issue where tracked devices cannot drag on UI elements when `Cursor.lockState` is set to `Locked`.
+
 ## [2.3.0] - 2023-02-17
 
 ### Added

Documentation~/images/hover-filter-setup.png

@@ -1 +1 @@
-2.3.0
+2.3.1

Documentation~/images/installation-add-package-by-name.png

@@ -4,7 +4,8 @@ To install this package, refer to the instructions that match your Unity Editor
 
 ## Version 2022.1 and later
 
-To install this package, follow the [installation instructions in the Unity User Manual](https://docs.unity3d.com/2022.1/Documentation/Manual/upm-ui-install.html).
+To install this package, follow the [installation instructions in the Unity User Manual](https://docs.unity3d.com/2022.1/Documentation/Manual/upm-ui-install.html) or click the following link to open Package Manager in your currently open project:
+[com.unity.xr.interaction.toolkit](com.unity3d.kharma:upmpackage/com.unity.xr.interaction.toolkit). This will bring up the **Add package by name** box with an optional version field. Click **Add** to install the latest verified version of XRI for your Unity Editor version.
 
 ## Version 2021.3
 
@@ -14,13 +15,24 @@ To install this package (minimum version: 2.0.4), follow the [installation instr
 
 ### 2021.3.8f1 and earlier
 
-To install this package, follow the instructions for [adding a package by name](https://docs.unity3d.com/2021.3/Documentation/Manual/upm-ui-quick.html) in the Unity Editor.
+This package was not listed in the Editor manifest in earlier versions of Unity 2021. Due to this, installation is a manual process. To install this package:
+1. Open the project that you plan to use.
+1. Click the following link to bring up the **Add package by name** window in Package Manager: 
+[com.unity.xr.interaction.toolkit](com.unity3d.kharma:upmpackage/com.unity.xr.interaction.toolkit@2.3.1) 
+
+   ![installation-add-package-by-name](images/installation-add-package-by-name.png)
+
+1. The version should be automatically populated, but please ensure that it is the correct version by referring to the table below.
+1. Click **Add**.
 
 |Text Field|Value|
 |---|---|
 |**Name**|`com.unity.xr.interaction.toolkit`|
 |**Version (optional)**|**[!include[](includes/version.md)]**|
 
+> [!NOTE]
+> Computer configuration issues can prevent package links from opening directly in the Unity Editor. If this happens, follow the instructions in [Adding a registry package by name](https://docs.unity3d.com/2021.3/Documentation/Manual/upm-ui-quick.html), using the information in the table above.
+
 ## Version 2020.3
 
 To install this package, follow the [installation instructions in the Unity User Manual](https://docs.unity3d.com/2020.3/Documentation/Manual/upm-ui-install.html).

Documentation~/images/interaction-strength-filter-setup.png

@@ -0,0 +1,215 @@
+# Interaction filters
+
+Interaction filters are used to add additional checks to an Interactor and Interactable interaction after the base class validations are passed. 
+
+The interaction filters also include an implementation of a filter delegate that forwards the filter processing to a delegate. This enables users to add additional filter logic without needing to create new classes.
+
+The current interaction filters supported in XRI  are:
+
+- [Hover filter](#hover-filter)
+- [Select filter](#select-filter)
+- [Interaction strength filter](#interaction-strength-filter)
+
+## Hover filter
+
+[`IXRHoverFilter`](xref:UnityEngine.XR.Interaction.Toolkit.Filtering.IXRHoverFilter) is an interface that allows additional filter processing between an [`IXRHoverInteractor`](xref:UnityEngine.XR.Interaction.Toolkit.IXRHoverInteractor) and an [`IXRHoverInteractable`](xref:UnityEngine.XR.Interaction.Toolkit.IXRHoverInteractable).
+
+### Usage
+
+An `IXRHoverFilter` can be added to the following objects to extend its hover validation:
+
+|Object|Usage|
+|---|---|
+|**[`XRInteractionManager`](xref:UnityEngine.XR.Interaction.Toolkit.XRInteractionManager)**|A hover filter added to the Interaction Manager is used to validate all hover interactions globally in the manager.|
+|**[`XRBaseInteractor`](xref:UnityEngine.XR.Interaction.Toolkit.XRBaseInteractor)**|A hover filter added to an Interactor is used to validate the hover interactions in the Interactor.|
+|**[`XRBaseInteractable`](xref:UnityEngine.XR.Interaction.Toolkit.XRBaseInteractable)**|A hover filter added to an Interactable is used to validate the hover interactions in the Interactable.|
+
+### Interface definition
+
+|Property|Description|
+|---|---|
+|**bool `canProcess`**|Whether this hover filter can process interactions. Hover filters that can process interactions receive calls to `IXRHoverFilter.Process`; hover filters that cannot process do not call `IXRHoverFilter.Process`. It's recommended to return `isActiveAndEnabled` when implementing this interface in a `MonoBehaviour`.|
+
+|Method|Description|
+|---|---|
+|**bool `Process(IXRHoverInteractor interactor, IXRHoverInteractable interactable)`**|Called by the host object (`XRInteractionManager`, `XRBaseInteractor` or `XRBaseInteractable`) to verify if the hover interaction between the given Interactor and Interactable can be performed. Returns `true` when the given Interactor can hover the given Interactable. Otherwise, returns `false`.|
+
+### Setup
+
+Add the implementation of `IXRHoverFilter` component to a GameObject and add it to the `Starting Hover Filters` property of an `XRInteractionManager`, `XRBaseInteractor`, or `XRBaseInteractable`. Filters in the `Starting Hover Filters` list will automatically be linked and applied to their respective host object.
+
+![hover-filter-setup](images/hover-filter-setup.png)
+
+Multiple hover filters can be added to a single Interaction Manager, Interactor, or Interactable.
+
+### Example
+
+```c#
+using UnityEngine;
+using UnityEngine.XR.Interaction.Toolkit;
+using UnityEngine.XR.Interaction.Toolkit.Filtering;
+
+public class CustomHoverFilter : MonoBehaviour, IXRHoverFilter
+{
+    public bool canProcess => isActiveAndEnabled;
+
+    public bool Process(IXRHoverInteractor interactor, IXRHoverInteractable interactable)
+    {
+        bool canHover = true;
+        // Do any additional validation checks on the interactor and interactable.
+        return canHover;
+    }
+}
+```
+
+## Select filter
+
+[`IXRSelectFilter`](xref:UnityEngine.XR.Interaction.Toolkit.Filtering.IXRSelectFilter) is an interface that allows additional filter processing between an [`IXRSelectInteractor`](xref:UnityEngine.XR.Interaction.Toolkit.IXRSelectInteractor) and an [`IXRSelectInteractable`](xref:UnityEngine.XR.Interaction.Toolkit.IXRSelectInteractable).
+
+### Usage
+
+An `IXRSelectFilter` can be added following objects to extend its select validation:
+
+|Object|Usage|
+|---|---|
+|**[`XRInteractionManager`](xref:UnityEngine.XR.Interaction.Toolkit.XRInteractionManager)**|A select filter added to the Interaction Manager is used to validate all select interactions globally in the manager.|
+|**[`XRBaseInteractor`](xref:UnityEngine.XR.Interaction.Toolkit.XRBaseInteractor)**|A select filter added to an Interactor is used to validate the select interactions in the Interactor.|
+|**[`XRBaseInteractable`](xref:UnityEngine.XR.Interaction.Toolkit.XRBaseInteractable)**|A select filter added to an Interactable is used to validate the select interactions in the Interactable.|
+
+### Interface definition
+
+|Property|Description|
+|---|---|
+|**bool `canProcess`**|Whether this select filter can process interactions. Select filters that can process interactions receive calls to `IXRSelectFilter.Process`. Select filters that cannot process do not call `IXRSelectFilter.Process`. It's recommended to return `isActiveAndEnabled` when implementing this interface in a `MonoBehaviour`.|
+
+|Method|Description|
+|---|---|
+|**bool `Process(IXRSelectInteractor interactor, IXRSelectInteractable interactable)`**|Called by the host object (`XRInteractionManager`, `XRBaseInteractor` or `XRBaseInteractable`) to verify if the select interaction between the given Interactor and Interactable can be performed. Returns `true` when the given Interactor can select the given Interactable. Otherwise, returns `false`.|
+
+### Setup
+
+Add the implementation of `IXRSelectFilter` component to a GameObject and add it to the `Starting Select Filters` property of an `XRInteractionManager`, `XRBaseInteractor`, or `XRBaseInteractable`. Filters in the `Starting Select Filters` list will automatically be linked and applied to their respective host object.
+
+![select-filter-setup](images/select-filter-setup.png)
+
+Multiple select filters can be added to a single Interaction Manager, Interactor, or Interactable.
+
+
+### Example
+
+```c#
+using UnityEngine;
+using UnityEngine.XR.Interaction.Toolkit;
+using UnityEngine.XR.Interaction.Toolkit.Filtering;
+
+public class CustomSelectFilter : MonoBehaviour, IXRSelectFilter
+{
+    public bool canProcess => isActiveAndEnabled;
+
+    public bool Process(IXRSelectInteractor interactor, IXRSelectInteractable interactable)
+    {
+        bool canSelect = true;
+        // Do additional validation checks on the interactor and interactable.
+        return canSelect;
+    }
+}
+```
+
+## Interaction strength filter
+
+[`IXRInteractionStrengthFilter`](xerf:UnityEngine.XR.Interaction.Toolkit.Filtering.IXRInteractionStrengthFilter) is an interface used to adjust or set the interaction strength between an [`IXRInteractor`](xref:UnityEngine.XR.Interaction.Toolkit.IXRInteractor) and [`IXRInteractable`](xref:UnityEngine.XR.Interaction.Toolkit.IXRInteractable).
+
+### Usage
+
+An `IXRInteractionStrengthFilter` can be added following objects to extend its interaction strength computation:
+
+|Object|Usage|
+|---|---|
+|**[`XRBaseInteractable`](xref:UnityEngine.XR.Interaction.Toolkit.XRBaseInteractable)**| An interaction strength filter added to an Interactable is used to modify the interaction strength in the Interactable for a hovering or selecting Interactor.|
+
+### Interface definition
+
+|Property|Description|
+|---|---|
+|**bool `canProcess`**|Whether this interaction strength filter can process interactions. Interaction strength filters that can process interactions receive calls to `IXRInteractionStrengthFilter.Process`. Interaction strength filters that cannot process do not receive calls to `IXRInteractionStrengthFilter.Process`. It's recommended to return `isActiveAndEnabled` when implementing this interface in a `MonoBehaviour`.|
+
+|Method|Description|
+|---|---|
+|**float `Process(IXRInteractor interactor, IXRInteractable interactable, float interactionStrength)`**|Called by the host object (`XRBaseInteractable`) to calculate the interaction strength between the given Interactor and Interactable. Returns the modified interaction strength that is the result of passing the interaction strength through the filter.|
+
+### Setup
+
+Add the implementation of `IXRInteractionStrengthFilter` component to a GameObject and add it to the `Starting Interaction Strength Filters` property of an `XRBaseInteractable`. Filters in the `Starting Interaction Strength Filters` list will automatically be linked and applied to their respective host object.
+
+![select-filter-setup](images/select-filter-setup.png)
+
+Multiple interaction strength filters can be added to a single Interactable.
+
+### Example
+
+```c#
+using UnityEngine;
+using UnityEngine.XR.Interaction.Toolkit;
+using UnityEngine.XR.Interaction.Toolkit.Filtering;
+
+public class CustomInteractionStrengthFilter : MonoBehaviour, IXRInteractionStrengthFilter
+{
+    public bool canProcess => isActiveAndEnabled;
+
+    public float Process(IXRInteractor interactor, IXRInteractable interactable, float interactionStrength)
+    {
+        float modifiedInteractionStrength = interactionStrength;
+        // Do any modification the interaction strength value based on the interactor and the interactable.
+        return modifiedInteractionStrength;
+    }
+}
+```
+
+## Delegates
+
+`IXRHoverFilter`, `IXRSelectFilter`, `IXRInteractionStrength` each contain an implementation of a filter delegate that forwards the filter processing to a delegate. This enables users to add additional filter logic without needing to create new classes.
+
+With filter delegates you provide a callback function that runs as the filter's `Process` method. Filter delegates also provide access to a `canProcess` property as well.
+
+### Example
+
+```c#
+using UnityEngine.XR.Interaction.Toolkit;
+using UnityEngine.XR.Interaction.Toolkit.Filtering;
+
+public class FilterDelegateExampleInteractable : XRBaseInteractable
+{
+    // Call this method to add the custom filters
+    void SetupFilters()
+    {
+        var hoverFilterDelegate = new XRHoverFilterDelegate((interactor, interactable) =>
+        {
+            bool canHover = false;
+            // Do any additional validation checks on the interactor and interactable.
+            return canHover;
+        });
+
+        var selectFilterDelegate = new XRSelectFilterDelegate((interactor, interactable) =>
+        {
+            bool canSelect = false;
+            // Do any additional validation checks on the interactor and interactable.
+            return canSelect;
+        });
+
+        var interactionStrengthFilterDelegate = new XRInteractionStrengthFilterDelegate((interactor, interactable, interactionStrength) =>
+        {
+            float modifiedInteractionStrength = interactionStrength;
+            // Do any modification the interaction strength value based on the interactor and the interactable.
+            return modifiedInteractionStrength;
+        });
+
+        // Filter delegates can modify the filter's canProcess property. Example:
+        hoverFilterDelegate.canProcess = false;
+
+        // Link the filter by adding the filter delegate to the filters list to ensure it is processed
+        hoverFilters.Add(hoverFilterDelegate);
+        selectFilters.Add(selectFilterDelegate);
+        interactionStrengthFilters.Add(interactionStrengthFilterDelegate);
+    }
+}
+```