com.unity.xr.interaction.toolkit@2.3.0

## [2.3.0] - 2023-02-17

### Added
- Added a Raycast Snap Volume Interaction property to control whether the XR Ray Interactor will collide with or ignore trigger snap colliders from an XR Interactable Snap Volume (used by gaze assistance). This allows a user to set Raycast Trigger Interaction to Ignore but still collide with trigger colliders that are associated with a snap volume.
- Added options to XR Poke Follow Affordance in the Starter Assets sample to apply the follow animation if the poke target is a child and to clamp the follow target to a maximum distance from the poke target.
- Added an XR Poke Follow Affordance to the `TextButton` prefab in the Starter Assets sample so that the button graphics can move in response to poke.
- Added Tracking State and Is Tracked input actions to the `XRI Default Input Actions` in the Starter Assets sample.
- Added [Meta Gaze Adapter](../manual/samples.md#meta-gaze-adapter) sample to allow developers to request permission and initialize eye tracking for the Meta Quest Pro.
- Added [Hands Interaction Demo](../manual/samples.md#hands-interaction-demo) sample to demonstrate interactions with hand tracking.
- Added poke interaction examples to the `DemoScene` in the Starter Assets sample.
- Added ability to customize the layer mask and trigger interaction when the XR Poke Interactor performs the physics sphere overlap call.
- Added documentation regarding behavior when Select Action Trigger is set to State on XR Direct Interactor and XR Ray Interactor.

### Changed
- Changed the Stop Manipulation action (default binding `Escape`) in the XR Device Simulator to always stop manipulation every time it is pressed instead of cycling between None and FPS mode. Trigger the Cycle Devices action (default binding `Tab`) to switch back to FPS mode instead.
- Changed `Ray Interactor` prefab in the Starter Assets sample to enable Treat Selection As Valid State on the XR Interactor Line Visual.
- Changed the  **GameObject** > **XR** > **Grab Interactable** menu item to set the Rigidbody Interpolate property on the created GameObject to Interpolate.
- Changed the Rigidbody Interpolate property from None to Interpolate in each of the Starter Assets sample grab interactable prefabs.
- Changed the default value of the Color Property Name property on the Color Material Property Affordance Receiver component to an empty string instead of `"_BaseColor"`. An empty string will now use either `"_BaseColor"` or `"_Color"` depending on the current render pipeline to add support for the Built-In Render Pipeline.
- Changed `GetValidTargets` on each interactor type to return an empty list when the interactor is disabled.
- Changed `ActionBasedControllerManager` in Starter Assets sample to make use of XR Interaction Group and removed some unused serialized fields.
- Changed `XR Origin Preconfigured` in Starter Assets sample so it instantiates the controller model prefab at runtime instead of being in the prefab hierarchy to make it easier for users to override the model used.
- Changed `Teleport Interactor` in Starter Assets sample so it instantiates the reticle prefabs at runtime instead of being in the prefab hierarchy to make it easier for users to override the reticle used.
- Changed `com.unity.xr.core-utils` dependency to 2.2.0.

### Fixed
- Fixed Teleportation Anchor incorrectly triggering a teleport when the Ray Interactor stops pointing at the anchor when it no longer has any ray cast hits.
- Fixed Starter Assets sample prefabs and `DemoScene` to have the Gaze Interactor prefab.
- Fixed `XRPokeInteractor` so it uses the `targetFilter` for filtering the valid targets returned by `GetValidTargets`.
- Fixed the Fix button for project validation issue "Interaction Layer 31 is not set to 'Teleport'" not persisting to the settings asset when closing the Unity Editor.
- Fixed missing references in device simulator UI button images by assigning to null.
- Fixed the `PokeStateData` that is generated from UI poke interaction so that its `axisAlignedPokeInteractionPoint` is relative to the world position of the target transform.
- Fixed broken click animations in `XRInteractableAffordanceStateProvider`.
- Fixed XR Device Simulator so it will use the new main camera if the previous one is disabled or destroyed.
- Fixed issue where AR gestures did not take into account UI in `ARBaseGestureInteractable` behaviors (such as AR Placement Interactable) by adding an `excludeUITouches` property, which is enabled by default.
- Fixed potential invalid stayed colliders list in `XRDirectInteractor` and `XRSocketInteractor` when the interactor is disabled while in contact with a collider.
- Fixed hover and select events being incorrectly fired when an `XRDirectInteractor` or `XRSocketInteractor` GameObject or component is disabled while in contact with an interactable, moved away from the interactable, and then enabled.
- Fixed XR Poke Interactor to query the local [PhysicsScene](https://docs.unity3d.com/ScriptReference/PhysicsScene.html) instead of using static physics calls.
- Fixed poke in UI scrolling in a scroll view outside of the viewport by ensuring the Tracked Device Graphic Raycaster respects the alpha hit test threshold.
- Fixed the `Teleport Anchor` prefab in Starter Assets to place the teleport destination at the top of the platform, fixing a bump that would occur when moving with locomotion after teleporting.

Author: Unity Technologies

CHANGELOG.md

@@ -5,6 +5,47 @@ 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.0] - 2023-02-17
+
+### Added
+- Added a Raycast Snap Volume Interaction property to control whether the XR Ray Interactor will collide with or ignore trigger snap colliders from an XR Interactable Snap Volume (used by gaze assistance). This allows a user to set Raycast Trigger Interaction to Ignore but still collide with trigger colliders that are associated with a snap volume.
+- Added options to XR Poke Follow Affordance in the Starter Assets sample to apply the follow animation if the poke target is a child and to clamp the follow target to a maximum distance from the poke target.
+- Added an XR Poke Follow Affordance to the `TextButton` prefab in the Starter Assets sample so that the button graphics can move in response to poke.
+- Added Tracking State and Is Tracked input actions to the `XRI Default Input Actions` in the Starter Assets sample.
+- Added [Meta Gaze Adapter](../manual/samples.md#meta-gaze-adapter) sample to allow developers to request permission and initialize eye tracking for the Meta Quest Pro.
+- Added [Hands Interaction Demo](../manual/samples.md#hands-interaction-demo) sample to demonstrate interactions with hand tracking.
+- Added poke interaction examples to the `DemoScene` in the Starter Assets sample.
+- Added ability to customize the layer mask and trigger interaction when the XR Poke Interactor performs the physics sphere overlap call.
+- Added documentation regarding behavior when Select Action Trigger is set to State on XR Direct Interactor and XR Ray Interactor.
+
+### Changed
+- Changed the Stop Manipulation action (default binding `Escape`) in the XR Device Simulator to always stop manipulation every time it is pressed instead of cycling between None and FPS mode. Trigger the Cycle Devices action (default binding `Tab`) to switch back to FPS mode instead.
+- Changed `Ray Interactor` prefab in the Starter Assets sample to enable Treat Selection As Valid State on the XR Interactor Line Visual.
+- Changed the  **GameObject** &gt; **XR** &gt; **Grab Interactable** menu item to set the Rigidbody Interpolate property on the created GameObject to Interpolate.
+- Changed the Rigidbody Interpolate property from None to Interpolate in each of the Starter Assets sample grab interactable prefabs.
+- Changed the default value of the Color Property Name property on the Color Material Property Affordance Receiver component to an empty string instead of `"_BaseColor"`. An empty string will now use either `"_BaseColor"` or `"_Color"` depending on the current render pipeline to add support for the Built-In Render Pipeline.
+- Changed `GetValidTargets` on each interactor type to return an empty list when the interactor is disabled.
+- Changed `ActionBasedControllerManager` in Starter Assets sample to make use of XR Interaction Group and removed some unused serialized fields.
+- Changed `XR Origin Preconfigured` in Starter Assets sample so it instantiates the controller model prefab at runtime instead of being in the prefab hierarchy to make it easier for users to override the model used.
+- Changed `Teleport Interactor` in Starter Assets sample so it instantiates the reticle prefabs at runtime instead of being in the prefab hierarchy to make it easier for users to override the reticle used.
+- Changed `com.unity.xr.core-utils` dependency to 2.2.0.
+
+### Fixed
+- Fixed Teleportation Anchor incorrectly triggering a teleport when the Ray Interactor stops pointing at the anchor when it no longer has any ray cast hits.
+- Fixed Starter Assets sample prefabs and `DemoScene` to have the Gaze Interactor prefab.
+- Fixed `XRPokeInteractor` so it uses the `targetFilter` for filtering the valid targets returned by `GetValidTargets`.
+- Fixed the Fix button for project validation issue "Interaction Layer 31 is not set to 'Teleport'" not persisting to the settings asset when closing the Unity Editor.
+- Fixed missing references in device simulator UI button images by assigning to null.
+- Fixed the `PokeStateData` that is generated from UI poke interaction so that its `axisAlignedPokeInteractionPoint` is relative to the world position of the target transform.
+- Fixed broken click animations in `XRInteractableAffordanceStateProvider`.
+- Fixed XR Device Simulator so it will use the new main camera if the previous one is disabled or destroyed.
+- Fixed issue where AR gestures did not take into account UI in `ARBaseGestureInteractable` behaviors (such as AR Placement Interactable) by adding an `excludeUITouches` property, which is enabled by default.
+- Fixed potential invalid stayed colliders list in `XRDirectInteractor` and `XRSocketInteractor` when the interactor is disabled while in contact with a collider.
+- Fixed hover and select events being incorrectly fired when an `XRDirectInteractor` or `XRSocketInteractor` GameObject or component is disabled while in contact with an interactable, moved away from the interactable, and then enabled.
+- Fixed XR Poke Interactor to query the local [PhysicsScene](https://docs.unity3d.com/ScriptReference/PhysicsScene.html) instead of using static physics calls.
+- Fixed poke in UI scrolling in a scroll view outside of the viewport by ensuring the Tracked Device Graphic Raycaster respects the alpha hit test threshold.
+- Fixed the `Teleport Anchor` prefab in Starter Assets to place the teleport destination at the top of the platform, fixing a bump that would occur when moving with locomotion after teleporting.
+
 ## [2.3.0-pre.1] - 2022-12-07
 
 ### Added
@@ -774,4 +815,4 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [0.0.3-preview] - 2019-05-07
 
 ### Added
-- Initial preview release of the XR Interaction framework.
+- Initial preview release of the XR Interaction framework.

CHANGELOG.md.meta

@@ -1,15 +1,45 @@
 # Affordance system
 
-The XR Interaction Toolkit package provides an affordance system which enables users to create visual and auditory responses to [interaction states](architecture.md#states).
+The XR Interaction Toolkit package provides an affordance system which enables users to create visual and auditory feedback to [interaction states](architecture.md#states). The general flow of information starts by adding an `Affordance State Provider` to the scene (typically an interactable) and pointing it to the interactable we want to monitor the interaction state of. Once it reads the current interaction state of the interactable, it then fires off a more generalized affordance state event to any subscribers, or affordance receivers. The receivers then act on the state change event and trigger the affordance effect, whether it is a material color change, transform scale, or switching out and playing an audio clip. The receivers get their configuration from a referenced `Affordance Theme` but may also be configured locally on the component itself. We recommend using theme assets to help accelerate your development process and improve consistency across your creations. You can refer to the diagram below to help visualize how everything is connected together.
 
-The [XR Interactable Affordance State Provider](xr-interactable-affordance-state-provider.md) connects to an interactable component to determine new affordance states, which then power affordance receivers to animate tweens using affordance themes.
+![affordance-system-information-flow](images/affordance-system-information-flow.svg)
+
+## Affordance state providers
+
+The [XR Interactable Affordance State Provider](xr-interactable-affordance-state-provider.md) connects to an interactable component and reads the interaction state as it changes (Hover, Select, or Activate) to determine and provide the appropriate [Affordance State](xref:UnityEngine.XR.Interaction.Toolkit.AffordanceSystem.State.AffordanceStateShortcuts) to any affordance receivers subscribed to this particular provider. It is also possible to update an affordance state directly from a script without the need for checking the state of an interactable, such as through a network synchronization script. Writing a custom provider is also possible, extended the possibilities to use the affordance system for non-interactable objects as well.
 
 ## Affordance receivers
 
-Affordance receivers are components that animate tweens using a referenced theme, which can be a ScriptableObject so that it can be reused across multiple interactable components.
+Affordance receivers are components that receive `Affordance State` change events and then perform specific effects using the referenced theme or configuration. Many affordance receivers handle animating tweens to achieve specific visual effects. There are various affordance receiver components for different primitive data types, such as `Color` or `Vector3` or `Float`. Custom affordance receivers can also be built to achieve a variety of effects depending on the properties you wish to enhance on or around a given object.
 
-There are various affordance receiver components for different primitive data types, such as `Color` or `Vector3`.
+## Affordance themes
 
-The theme contains a list of affordance states and the values that should be blended during interactions. The Audio Affordance Theme contains Audio Clip references for when the state is either entered (**State Entered**) or exited (**State Exited**), and Unity will play them using `AudioSource.PlayOneShot`. The other Affordance Theme types (Color, Float, Vector2, Vector3, and Vector4) contains that typed value that is interpolated between two values: the start value (**Animation State Start Value**) and the target value (**Animation State End Value**).
+Themes are a convenient way to encapsulate configuration for a specific type of `Affordance Receiver`. This makes it easy to create themes for any of the affordance data types and drive a uniform look and feel for the project. It also allows you to tweak settings in one place and not have to worry about updating each GameObject or prefab with those changes. Under the hood, an `Affordance Theme` is merely a [ScriptableObject](https://docs.unity3d.com/Manual/class-ScriptableObject.html) designed to use the newer [Datum](https://docs.unity3d.com/Packages/com.unity.xr.core-utils@2.2/api/Unity.XR.CoreUtils.Datums.Datum-1.html) architecture along with some editor code to make them easier to visualize and configure.
+
+The theme contains a list of affordance states and the values that should be blended during interactions. The Audio Affordance Theme contains Audio Clip references for when the state is either entered (**State Entered**) or exited (**State Exited**), and Unity will play them using [`AudioSource.PlayOneShot`](https://docs.unity3d.com/ScriptReference/AudioSource.PlayOneShot.html). The other Affordance Theme types (Color, Float, Vector2, Vector3, and Vector4) contains that typed value that is interpolated between two values: the start value (**Animation State Start Value**) and the target value (**Animation State End Value**). Above the list of states is the State Animation Curve. When each animation is triggered by the Affordance Receiver, it will use this curve to determine the value. 0 on the curve corresponds to the Start Value and 1 corresponds to the End Value. This animation curve can also be driven by the interaction strength or a custom script to provide even more flexibility in the way you want your effects to look and feel.
 
 The theme assets are created by using the **Assets** > **Create** > **Affordance Theme** menu.
+
+## How to set up your project using the affordance system
+
+The [Starter Assets](samples.md#starter-assets) sample contains a few different uses of various affordance effects to help understand how they are intended to be used. However, if you are starting from scratch, you can use the following steps to get started with the affordance system.
+
+### Add an XR Interactable Affordance State Provider
+
+Pick an existing XR Interactable in your scene and create an empty child object (**Assets** > **Create Empty**). Click on the newly created GameObject to bring up the Inspector. Click on **Add Component** and then navigate to **Affordance System** > **XR Interactable Affordance State Provider**. Under the new component editor, locate the **Interactable Source** property and drag the parent XR Interactable object into the property. Feel free to rename the object to something meaningful like Interaction Affordance. The result will look something like the following:
+
+![affordance-state-provider](images/affordance-state-provider.png)
+
+### Add an Affordance Receiver
+
+From here we will be able to add affordance receivers to add effects to the interactable object based on its state. You can add the next components to the same GameObject as before or create another empty child GameObject. If you created a new child object, click on it to bring it up in the Inspector. Next, click on **Add Component** and navigate to **Affordance System** > **Rendering** > **Color Material Property Affordance Receiver**. This will add an additional Material Property Block Helper component which should be automatically assigned in the **Material Property Block Helper** property of the Color Material Property Affordance Receiver component. Next, drag the GameObject from the last section into the **Affordance State Provider** property on the Color Material Property Affordance Receiver component and the appropriate mesh renderer into the **Renderer** property on the Material Property Block Helper component. Last, check the box labeled **Replace Idle State Value With Initial Value** to ensure the original color of the material is used when the state returns to idle. The result will look similar to the image below.
+
+![affordance-receiver](images/affordance-receiver.png)
+
+### Adding a theme
+
+Next we will create and setup the theme asset. In the Project window, navigate to a folder you wish to store your themes in. Open the **Assets** menu and navigate to **Create** > **Affordance Theme** > **Color Affordance Theme** to create the new [ScriptableObject](https://docs.unity3d.com/Manual/class-ScriptableObject.html) asset. Click on the newly created theme to bring up the Inspector window. By default, all colors will be set to black and transparent. Feel free to set the colors to match the aesthetic you are looking for. Below is an image of a fully configured theme included with the Starter Assets.
+
+![affordance-theme-color](images/affordance-theme-color.png)
+
+Once the theme is configured to your liking, navigate back to the Color Material Property Affordance Receiver component created in the last section. Drag the Color Affordance Theme asset into the **Affordance Theme Datum** property. You are now ready to test it all out. Feel free to explore the other Affordance Receiver types to add helpful effects to your Interactables to help your players more easily discover them.

Documentation~/affordance-system.md

@@ -15,5 +15,6 @@ Controls displaying one or more annotations when hovering over the `GameObject`
 |  Multiple | Set **Select Mode** to **Multiple** to allow simultaneous selections on the Interactable from multiple Interactors. |
 | **XR Origin** | The `XROrigin` that this Interactable will use (such as to get the `Camera` or to transform from Session space). Will find one if **None**. |
 | **AR Session Origin** | This is deprecated. Use the above **XR Origin** instead. |
+| **Exclude UI Touches** | Enable to exclude touches that are over UI. Used to make screen space canvas elements block touches from hitting planes behind it. |
 | **Annotations** | The list of annotations, which appear when the user hovers over the `GameObject` that this component is attached to. |
 | **Interactable Events** | See the [Interactable Events](interactable-events.md) page. |

Documentation~/ar-annotation-interactable.md

@@ -16,4 +16,5 @@ To make use of this, add an `ARGestureInteractor` to your scene and an `ARBaseGe
 | **Keep Selected Target Valid** | Whether to keep selecting an Interactable after initially selecting it even when it is no longer a valid target.<br />Enable to make the `XRInteractionManager` retain the selection even if the Interactable is not contained within the list of valid targets.<br />Disable to make the Interaction Manager clear the selection if it isn't within the list of valid targets. A common use for disabling this is for XR Ray Interactors used for teleportation to make the teleportation Interactable no longer selected when not currently pointing at it. |
 | **XR Origin** | The `XROrigin` that this Interactor will use (such as to get the `Camera` or to transform from Session space). Will find one if **None**. |
 | **AR Session Origin** | This is deprecated. Use the above **XR Origin** instead. |
+| **Exclude UI Touches** | Enable to exclude touches that are over UI. Used to make screen space canvas elements block touches from hitting planes behind it. |
 | **Interactor Events** | See the [Interactor Events](interactor-events.md) page. |

Documentation~/ar-gesture-interactor.md

@@ -15,6 +15,7 @@ Controls the placement of Prefabs via a tap gesture.
 |  Multiple | Set **Select Mode** to **Multiple** to allow simultaneous selections on the Interactable from multiple Interactors. |
 | **XR Origin** | The `XROrigin` that this Interactable will use (such as to get the `Camera` or to transform from Session space). Will find one if **None**. |
 | **AR Session Origin** | This is deprecated. Use the above **XR Origin** instead. |
+| **Exclude UI Touches** | Enable to exclude touches that are over UI. Used to make screen space canvas elements block touches from hitting planes behind it. |
 | **Placement Prefab** | A `GameObject` to place when a ray cast from a user touch hits a plane. |
 | **Fallback Layer Mask** | The `LayerMask` that Unity uses during an additional ray cast when a user touch does not hit any AR trackable planes. |
 | **Interactable Events** | See the [Interactable Events](interactable-events.md) page. |

Documentation~/ar-placement-interactable.md

@@ -15,6 +15,7 @@ Manipulates the rotation of an object via a drag or a twist gesture. If an objec
 |  Multiple | Set **Select Mode** to **Multiple** to allow simultaneous selections on the Interactable from multiple Interactors. |
 | **XR Origin** | The `XROrigin` that this Interactable will use (such as to get the `Camera` or to transform from Session space). Will find one if **None**. |
 | **AR Session Origin** | This is deprecated. Use the above **XR Origin** instead. |
+| **Exclude UI Touches** | Enable to exclude touches that are over UI. Used to make screen space canvas elements block touches from hitting planes behind it. |
 | **Rotation Rate Degrees Drag** | The rate at which Unity rotates the attached object with a drag gesture. |
 | **Rotation Rate Degrees Twist** | The rate at which Unity rotates the attached object with a twist gesture. |
 | **Interactable Events** | See the [Interactable Events](interactable-events.md) page. |