com.unity.xr.interaction.toolkit@2.1.0-pre.1

## [2.1.0-pre.1] - 2022-05-02

### Added
- Added properties to XR Grab Interactable to use dynamic attach transforms so the grab pose will be based on the pose of the Interactor when the selection is made. You can enable the Use Dynamic Attach property to keep the object in the same position and rotation when grabbed. ([1373337](https://issuetracker.unity3d.com/product/unity/issues/guid/1373337))
- Added filtering for interactions to help determine the intent of the user. The new abstractions XR Target Filter and XR Target Evaluator let users configure and extend the logic of how an Interactor ranks an Interactable from a list of valid ones, specifically in the `GetValidTargets` method. Several different evaluators are included in this update, and custom ones can be created. This makes it easier to customize the Interactor without needing to create a derived behavior.
- Added the `XRBaseInteractable.distanceCalculationMode` property. This give users the ability to configure how an Interactable calculates its distance to a location, such as to an Interactor for sorting its valid targets, at varying tradeoffs between accuracy and performance.
- Added the `XRBaseInteractable.getDistanceOverride` property that lets users assign a method to be called when the Interactable is performing a distance calculation to a location, which is used when the Interactor is ordering its valid targets. This property makes it easier to customize the Interactable without needing to create a derived behavior.
- Added `IsOverUIGameObject` function to `XRRayInteractor` that does a simple check to see if the ray cast result is hitting a UI GameObject.
- Added `InputActionReference` properties to the `XRUIInputModule` for left/right/middle clicks, navigation move, submit, cancel, scroll and pointer movement actions. This allows for greater flexibility and customization of what devices can drive UI input when using the `XRUIInputModule`.
- The `XRI Default Input Actions` asset in the `Starter Assets` sample package now includes an `XRI UI` Action Map for UI-specific Input Actions. Also included is a Preset asset to quickly map the actions onto the `XRUIInputModule` component.
- Added a Tunneling Vignette sample. It contains assets to let users set up and configure the tunneling vignette as a comfort mode intended to mitigate motion sickness in VR.
- Added a Tunneling Vignette Controller component used for driving the vignette material included with the Tunneling Vignette sample. Locomotion Provider components can be drag-and-dropped into a list of Locomotion Providers that will trigger the tunneling vignette effect. A custom inspector allows previewing each effect for the corresponding Locomotion Provider.
  * Added `ITunnelingVignetteProvider` interface to allow custom behaviors to control the vignette effect.
  * Added a `LocomotionPhase` enum in `LocomotionProvider` that can be used to describe different phases of a locomotion for use with the tunneling vignette. Added code in `ContinuousMoveProviderBase`, `ContinuousTurnProviderBase`, `SnapTurnProviderBase`, and `TeleportationProvider` to compute their `LocomotionPhase`.
  * Added a Delay Time property to the Teleportation Provider and Snap Turn Provider components to support customization of timing for use with fading in the tunneling vignette.

### Changed
- Updated code paths with macro protections around `InputSystem` or `Input Manager` based code to prevent attempted usage when either one is not active.
- Scroll speed when using the ScrollWheel Input System Action is now being divided by 20 pixels per line instead of 120 pixels per line to match the `InputSystemUIInputModule` scrolling speed.
- Changed `XRSocketInteractor` hover mesh pose calculation to only ignore the current pose of the attach transform for `XRGrabInteractable` when Use Dynamic Attach is disabled instead of for all types of `IXRSelectInteractable`.
- Changed `XRControllerRecorder.recording` from `internal` to `public`.

### Fixed
- Fixed `UIInputModule` so pointer clicks set the correct button (left/right/middle) for the `EventSystem` in the `PointerEventData`.
- Fixed compilation errors on platforms such as Game Core where `ENABLE_VR` is not currently defined.

Author: Unity Technologies

CHANGELOG.md

@@ -5,6 +5,32 @@ 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.1.0-pre.1] - 2022-05-02
+
+### Added
+- Added properties to XR Grab Interactable to use dynamic attach transforms so the grab pose will be based on the pose of the Interactor when the selection is made. You can enable the Use Dynamic Attach property to keep the object in the same position and rotation when grabbed. ([1373337](https://issuetracker.unity3d.com/product/unity/issues/guid/1373337))
+- Added filtering for interactions to help determine the intent of the user. The new abstractions XR Target Filter and XR Target Evaluator let users configure and extend the logic of how an Interactor ranks an Interactable from a list of valid ones, specifically in the `GetValidTargets` method. Several different evaluators are included in this update, and custom ones can be created. This makes it easier to customize the Interactor without needing to create a derived behavior.
+- Added the `XRBaseInteractable.distanceCalculationMode` property. This give users the ability to configure how an Interactable calculates its distance to a location, such as to an Interactor for sorting its valid targets, at varying tradeoffs between accuracy and performance.
+- Added the `XRBaseInteractable.getDistanceOverride` property that lets users assign a method to be called when the Interactable is performing a distance calculation to a location, which is used when the Interactor is ordering its valid targets. This property makes it easier to customize the Interactable without needing to create a derived behavior.
+- Added `IsOverUIGameObject` function to `XRRayInteractor` that does a simple check to see if the ray cast result is hitting a UI GameObject.
+- Added `InputActionReference` properties to the `XRUIInputModule` for left/right/middle clicks, navigation move, submit, cancel, scroll and pointer movement actions. This allows for greater flexibility and customization of what devices can drive UI input when using the `XRUIInputModule`.
+- The `XRI Default Input Actions` asset in the `Starter Assets` sample package now includes an `XRI UI` Action Map for UI-specific Input Actions. Also included is a Preset asset to quickly map the actions onto the `XRUIInputModule` component.
+- Added a Tunneling Vignette sample. It contains assets to let users set up and configure the tunneling vignette as a comfort mode intended to mitigate motion sickness in VR.
+- Added a Tunneling Vignette Controller component used for driving the vignette material included with the Tunneling Vignette sample. Locomotion Provider components can be drag-and-dropped into a list of Locomotion Providers that will trigger the tunneling vignette effect. A custom inspector allows previewing each effect for the corresponding Locomotion Provider.
+  * Added `ITunnelingVignetteProvider` interface to allow custom behaviors to control the vignette effect.
+  * Added a `LocomotionPhase` enum in `LocomotionProvider` that can be used to describe different phases of a locomotion for use with the tunneling vignette. Added code in `ContinuousMoveProviderBase`, `ContinuousTurnProviderBase`, `SnapTurnProviderBase`, and `TeleportationProvider` to compute their `LocomotionPhase`.
+  * Added a Delay Time property to the Teleportation Provider and Snap Turn Provider components to support customization of timing for use with fading in the tunneling vignette.
+
+### Changed
+- Updated code paths with macro protections around `InputSystem` or `Input Manager` based code to prevent attempted usage when either one is not active.
+- Scroll speed when using the ScrollWheel Input System Action is now being divided by 20 pixels per line instead of 120 pixels per line to match the `InputSystemUIInputModule` scrolling speed.
+- Changed `XRSocketInteractor` hover mesh pose calculation to only ignore the current pose of the attach transform for `XRGrabInteractable` when Use Dynamic Attach is disabled instead of for all types of `IXRSelectInteractable`.
+- Changed `XRControllerRecorder.recording` from `internal` to `public`.
+
+### Fixed
+- Fixed `UIInputModule` so pointer clicks set the correct button (left/right/middle) for the `EventSystem` in the `PointerEventData`.
+- Fixed compilation errors on platforms such as Game Core where `ENABLE_VR` is not currently defined.
+
 ## [2.0.2] - 2022-04-29
 
 ### Fixed

Documentation~/TableOfContents.md

@@ -6,6 +6,7 @@
   * [UI setup](ui-setup.md)
   * [Locomotion](locomotion.md)
   * [Interaction layers](interaction-layers.md)
+  * [Target filters](target-filters.md)
   * [AR interaction](ar-interaction.md)
   * [Debugger window](debugger-window.md)
 * Reference

Documentation~/architecture.md

@@ -17,7 +17,7 @@ These interaction states always involve both an [Interactor](#interactors) and [
 ## Components
 
 ### Interactors
-Interactor components handle the actions of hovering and selecting Interactable objects in the world. This component is responsible for creating a list of valid targets that it could potentially hover or select each frame.
+Interactor components handle the actions of hovering and selecting Interactable objects in the world. This component is responsible for creating a list of Interactables (called Valid Target) that it could potentially hover or select each frame. The Valid Target list is sorted by priority, and by default the closest Interactables have highest priority. This priority criteria can be changed or extended using [Target filters](target-filters.md).
 
 ### Interactables
 Interactables are objects in a scene that an Interactor can hover, select, and/or activate. This component is responsible for defining the behavior of those interaction states. The same Interactor might be able to pick up and throw a ball, shoot a gun, or press a 3D button on a keypad.

Documentation~/components.md

@@ -1,6 +1,7 @@
 # Components
 
 ## Controller Components
+
 - [XR Controller (Action-based)](xr-controller-action-based.md)
 - [XR Controller (Device-based)](xr-controller-device-based.md)
 - [XR Controller Recorder](xr-controller-recorder.md)
@@ -42,6 +43,7 @@
 - [Snap Turn Provider (Action-based)](snap-turn-provider-action-based.md)
 - [Snap Turn Provider (Device-based)](snap-turn-provider-device-based.md)
 - [Teleportation Provider](teleportation-provider.md)
+- [Tunneling Vignette Controller](tunneling-vignette-controller.md)
 
 ## Visuals
 
@@ -50,6 +52,8 @@
 - [XR Tint Interactable Visual](xr-tint-interactable-visual.md)
 
 ## Other Components
+
 - [Input Action Manager](input-action-manager.md)
 - [XR Device Simulator](xr-device-simulator.md)
 - [XR Interaction Manager](xr-interaction-manager.md)
+- [XR Target Filter](target-filters.md#xr-target-filter)

Documentation~/debugger-window.md

@@ -5,3 +5,11 @@ The XR Interaction Toolkit Debugger window displays a top-down view of all the I
 You must be in Play mode to use this window.
 
 ![interaction-debugger](images/interaction-debugger.png)
+
+## Target filters
+
+The Target Filters tab displays all active and enabled `XRTargetFilters` in the scene. It also displays the Interactors and `XRTargetFilters` that are linked at the moment.
+
+You can select an `XRTargetFilter` in the Filters tree to inspect its Evaluators' scores in the Score tree. The Score tree displays the final and weighted scores for an Interactable in a Valid Target list. The Interactors are shown as the parent of their respective Valid Target list.
+
+![xr-target-filter-debugger](images/xr-target-filter-debugger.png)

Documentation~/extending-xri.md

@@ -70,6 +70,44 @@ public class ExampleInteractable : XRBaseInteractable
 {
 }
 ```
+
+## Extending target filters
+
+You can derive from `XRBaseTargetFilter` (a `MonoBehaviour`) or implement `IXRTargetFilter` to create a custom Target Filter. At runtime, you can link an instance of your custom Target Filter by assigning it to the `targetFilter` property of an Interactor.
+
+An instance of an `XRBaseTargetFilter` can also be assigned in the Inspector to the **Starting Target Filter** property of an Interactor. During the Interactor runtime initialization, it'll link itself with the filter in this property.
+
+### Extending evaluators
+
+You can derive from `XRTargetEvaluator` to create a custom Evaluator. An `XRTargetEvaluator` has virtual lifecycle callbacks similar to a `MonoBehaviour` and an additional method (`CalculateNormalizedScore`) for its score calculation. All these callbacks are invoked by its `XRTargetFilter`. The `CalculateNormalizedScore` method can be invoked several times in a single frame, as it can be called one time for each target Interactable in the linked Interactors.
+
+An `XRTargetEvaluator` can optionally implement the interface `IXRTargetEvaluatorLinkable` to receive callbacks whenever an Interactor links to or unlinks from its filter.
+
+For Evaluators that do binary tests, it's recommended that its `CalculateNormalizedScore` method returns `1` when the condition is met, and `0` otherwise.
+
+```csharp
+using System;
+using UnityEngine.XR.Interaction.Toolkit;
+using UnityEngine.XR.Interaction.Toolkit.Filtering;
+
+[Serializable]
+public class ExcludeByTagEvaluator : XRTargetEvaluator
+{
+    public string tagToExclude;
+
+    protected override float CalculateNormalizedScore(IXRInteractor interactor, IXRInteractable target)
+    {
+        return target.transform.CompareTag(tagToExclude) ? 0f : 1f;
+    }
+}
+```
+
+#### Troubleshooting missing evaluator types
+
+Evaluators are [serialized as reference](https://docs.unity3d.com/ScriptReference/SerializeReference.html) in the `XRTargetFilter`, and Unity does not keep track of the script (or its GUID) that the Evaluator objects originated from. If an Evaluator type becomes missing, Unity will log an error in the Console window. Follow the instructions below to fix this issue:
+- If you are changing the Evaluator type (by renaming its class, namespace, etc) or moving it to another assembly, then you should decorate the Evaluator class with the [MovedFromAttribute](https://github.com/Unity-Technologies/UnityCsReference/blob/master/Runtime/Export/Scripting/APIUpdating/UpdatedFromAttribute.cs) passing the information of the old type.
+- Before deleting an Evaluator script, make sure that no other `XRTargetFilter` in your project is using it. If you are using Unity version 2021.2 or above, you can select the missing types from the filter Inspector and delete them. Otherwise, to delete these objects, you'll need to create a new Evaluator script, and decorate it with a `MovedFromAttribute` containing the deleted type information.
+
 ## Inspectors
 
 Custom [Editor](https://docs.unity3d.com/ScriptReference/Editor.html) classes are used to change the appearance and order of properties that appear in the Inspector, particularly for Interactors and Interactables. Derived behaviors that add additional serialized fields (those that are `public` or have the `SerializeField` attribute) will automatically have those appear in the Inspector. The Editor classes can be extended to further customize the Inspector, at which point any declared `SerializedProperty` fields that are assigned will no longer be automatically drawn during `DrawDerivedProperties`. Within those derived Editor classes, you will typically only need to override methods such as `DrawProperties` in `XRBaseInteractorEditor` or `XRBaseInteractableEditor` rather than the entire `OnInspectorGUI`.
@@ -104,4 +142,4 @@ Custom [Editor](https://docs.unity3d.com/ScriptReference/Editor.html) classes ar
       }
   }
   ```
-The [`Editor.DrawDefaultInspector`](https://docs.unity3d.com/ScriptReference/Editor.DrawDefaultInspector.html) method can be used to draw the built-in Inspector instead. The [`PropertyDrawer`](https://docs.unity3d.com/ScriptReference/PropertyDrawer.html) class can also be utilized rather than creating custom `Editor` classes.
+The [`Editor.DrawDefaultInspector`](https://docs.unity3d.com/ScriptReference/Editor.DrawDefaultInspector.html) method can be used to draw the built-in Inspector instead. The [`PropertyDrawer`](https://docs.unity3d.com/ScriptReference/PropertyDrawer.html) class can also be utilized rather than creating custom `Editor` classes.

Documentation~/filter.yml

@@ -98,3 +98,6 @@ apiRules:
   - exclude:
       uidRegex: XRSocketInteractorEditor
       type: Type
+  - exclude:
+      uidRegex: TunnelingVignetteControllerEditor
+      type: Type