com.unity.polyspatial.visionos@0.1.2

## [0.1.2] - 2023-08-16

Author: Unity Technologies

CHANGELOG.md

@@ -1,9 +1,14 @@
+---
+uid: psvos-changelog
+---
 # Changelog
 All notable changes to this package will be documented in this file.
 
 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).
 
+## [0.1.2] - 2023-08-16
+
 ## [0.1.0] - 2023-07-19
 
 ## [0.0.4] - 2023-07-18

Documentation~/Assets.md

@@ -1,3 +1,6 @@
+---
+uid: psl-vos-assets
+---
 # PolySpatial Asset Support
 
 ## Meshes
@@ -8,16 +11,16 @@ As Unity and RealityKit use different coordinate systems, some vertex attributes
 ## Materials
 Please refer to [PolySpatial Material Support](Materials.md) for detailed information about material and shader support on visionOS.
 
-### Unity ShaderGraphs
-Please refer to [Shader Graph Support](ShaderGraph.md) for detailed information about how custom shaders defined via Unity ShaderGraph are converted to MaterialX to interop with RealityKit.
+### Unity Shader Graphs
+Please refer to [Shader Graph Support](ShaderGraph.md) for detailed information about how custom shaders defined via Unity Shader Graph are converted to MaterialX to interop with RealityKit.
 
 ## Textures
 Unity provides support for 2D textures on visionOS, and takes advantage of native texture compression options. 
 
 RealityKit for visionOS does not support 3D textures or cubemaps, so users must reimplement these texture assets in terms of 2D textures instead.
 
 ### Render Textures 
-Unity will replicate render targets to RealityKit in real time, but currently only a limited number of submissions can be made at rate. Introducing additional render targets may contend with Unity's own graphics buffer sumbmission, hindering overall performance.
+Unity will replicate render targets to RealityKit in real time, but currently only a limited number of submissions can be made at rate. Introducing additional render targets may contend with Unity's own graphics buffer submission, hindering overall performance.
 
 Also note that you must manually mark RenderTextures as dirty after modifying them; currently, no such dirtying occurs automatically, and if the texture isn't dirtied it won't be replicated over to RealityKit.
 

Documentation~/DevelopmentAndIteration.md

@@ -1,3 +1,6 @@
+---
+uid: psl-vos-development
+---
 # Development & Iteration
 
 ## Prerequisites
@@ -12,14 +15,14 @@ visionOS support for Mixed Reality is provided by Unity PolySpatial, which can b
 Unity provides several options for iterating and previewing content that targets visionOS. These options are on par with Unity's support for other non-desktop platforms.
 
 ### Play Mode
-The fastest way to preview content is to enter Play Mode within the Unity Editor. This provides the fastest iteration cycle, but uses Unity's rendering system rather than RealityKit. This mode is optimized for rapid iteration, such as iterating on gameplay or UX, but may not always provide a faithful representation of the visuals or performance characteristics of a target platform. Visuals, optimization, and similar tasks typically benefit from other preview options provided by Unity. In addition, Play Mode doesn't currently preview volumes or the new input modalities provided by visionOS.
+The fastest way to preview content is to enter Play Mode within the Unity Editor. This provides the fastest iteration cycle, but uses Unity's rendering system rather than RealityKit. This mode is optimized for rapid iteration, such as iterating on game play or UX, but may not always provide a faithful representation of the visuals or performance characteristics of a target platform. Visuals, optimization, and similar tasks typically benefit from other preview options provided by Unity. In addition, Play Mode doesn't currently preview volumes or the new input modalities provided by visionOS.
 
 In order to better approximate the visionOS runtime, Play Mode for PolySpatial apps creates a parallel hierarchy of **backing** GameObjects  that are linked to your app's **simulation** GameObjects, but perform all the rendering. This means you will observe some differences based on the state of the `Enable PolySpatial Runtime` project setting. These differences are intentional, as they allow developers to better preview how their content will look on device.
 
 ### visionOS Player builds. 
 Choose visionOS from the Build Settings window to target your build for visionOS. Most options in build settings are analogous to those provided for iOS. visionOS player builds will generate an Xcode project that needs to be compiled on a Mac (currently, this must be a Mac with Apple silicon), but may target either the visionOS simulator or an Apple Vision Pro headset connected to your Mac. 
 
-Note: unlike iOS, there is no need to switch to a different SDK in Project Settings to run your content in the simulator.  Simply select the RealityDevice simulator target in Xcode.
+Note: unlike iOS, there is no need to switch to a different SDK in Project Settings to run your content in the simulator. Simply select the RealityDevice simulator target in Xcode.
 
 For building to a development kit make sure you have setup a valid provisioning profile and signing certificate for Apple Development (that includes visionOS) platform. You will also need to make sure the device is correctly registered to your development account.
 
@@ -30,6 +33,9 @@ PolySpatial for visionOS supports a unique recording and playback workflow that
 The standard debugging workflow works normally when using PolySpatial. You enable Script Debugging in the build settings and optionally Wait for Managed Debugger. Then attach a managed debugger/IDE to your running application and debug your script code.
 
 ## Building Blocks in PolySpatial XR
-The building blocks system is an overlay window in the scene view that can help you quickly access commonly used items in your project. To open the building blocks overlay click on the hamburger menu on the scene view > Overlay menu Or move the mouse over the scene view and press the "tilde" key. Afterwards just enable the Building Blocks overlay.
+
+![Building Blocks Menu](images/BuildingBlocks/buildingblocksmenu.png)
+
+The Building Blocks system is an overlay window in the Scene view that can help you quickly access commonly used items in your project. To open the Building Blocks overlay click on the hamburger menu on the Scene view > Overlay menu. Or move the mouse over the Scene view and press the "tilde" key. Afterwards, just enable the Building Blocks overlay.
 
 You can find more info about the building blocks system in the [XR Core Utils package](https://docs.unity3d.com/Packages/com.unity.xr.core-utils@latest).

Documentation~/FAQ.md

@@ -1,5 +1,5 @@
 ---
-uid: polyspatialxr-faq
+uid: psl-vos-faq
 ---
 
 # Frequently Asked Questions (FAQ)
@@ -9,23 +9,23 @@ uid: polyspatialxr-faq
 * Please note that Unity is still building towards feature parity with the Metal API on XCode, so you might observe warnings from Metal’s API validation layer. To work around this, you can turn off the Metal API Validation Layer via XCode’s scheme menu.
 
 ## Q: How can I bring an existing mobile project to the PolySpatial XR platform?
-Please check the Project conversion guide on the [getting started page](GettingStarted.md#unity-project-conversion-guide-for-unity-polyspatial-xr) for information on enabling and using PolySpatial.
+Please check the Project conversion guide on the [getting started page](GettingStarted.md#porting-existing-projects) for information on enabling and using PolySpatial.
 
 ## Q: How can I bring an existing XR project to the PolySpatial XR platform?
-You can check for a Project conversion guide on the [getting started page](GettingStarted.md#unity-project-conversion-guide-for-unity-polyspatial-xr)
+You can check for a Project conversion guide on the [getting started page](GettingStarted.md#porting-existing-projects)
 
 ## Q: I enter Play Mode and see no visual or execution difference in my project!
 This may indicate you haven't yet turned on support for the PolySpatial Runtime. To do so, go to **Project Settings > PolySpatial** and make sure that **Enable PolySpatial Runtime** is toggled.
 
 ## Q: The runtime is enabled, but nothing shows up!
-* Ensure you have a Volume Camera in your scene.   An Unbounded Volume Camera with its origin positioned in the middle of your scene is a good starting point.
+* Ensure you have a Volume Camera in your scene. An Unbounded Volume Camera with its origin positioned in the middle of your scene is a good starting point.
 If one is not present a default one will be created that will include the bounds of every object in the scene, but this may cause objects in the scene within the bounds of the volume camera to be too small to see.
-* Verify that the in-editor preview runtime is functioning.  Open the “DontDestroyOnLoad” scene in the hierarchy while playing, and check if there is a "PolySpatial Root” object present.  If there is not, ensure that the PolySpatial runtime is enabled.  If it is enabled and nothing shows up, please contact the Unity team.
-* When using an Unbounded camera, the platform is responsible for choosing the (0,0,0) origin and may choose  position for it that is unexpected.  Look around (literally) to see if your content is somewhere other than here you think it should be. Rebooting the device can also help to reset its session space. It can be helpful to ensure that it is in a consistent location (for example, sitting on the desk, facing forward) every time you boot it up.
+* Verify that the in-editor preview runtime is functioning. Open the “DontDestroyOnLoad” scene in the hierarchy while playing, and check if there is a "PolySpatial Root” object present. If there is not, ensure that the PolySpatial runtime is enabled. If it is enabled and nothing shows up, please contact the Unity team.
+* When using an Unbounded camera, the platform is responsible for choosing the (0,0,0) origin and may choose  position for it that is unexpected. Look around (literally) to see if your content is somewhere other than here you think it should be. Rebooting the device can also help to reset its session space. It can be helpful to ensure that it is in a consistent location (for example, sitting on the desk, facing forward) every time you boot it up.
 
 ## Q: Skinned Meshes are not animating!
 * On the **Animator** component, ensure **Culling Mode** is set to **Always Animate**. 
-* If the model is imported, navigate to the **Import Settings** for the model. Under the **Rig** tab, ensure **Optimize Game Object** is unticked. Some models may not even have this setting; in that case, it should be good as-is.
+* If the model is imported, navigate to the **Import Settings** for the model. Under the **Rig** tab, ensure **Optimize Game Objects** is unticked. Some models may not even have this setting; in that case, it should be good as-is.
 * Certain models may contain a skeleton (a set of bones in a hierarchy) that are incompatible with RealityKit. To be compatible, a skeleton must have the following attributes:
 	1. A group of bones must have a common ancestor GameObject in the transform hierarchy. 
 	2. Each bone in the skeleton must be able to traverse up the transform hierarchy without passing any non-bone GameObjects. 

Documentation~/GettingStarted.md

@@ -1,3 +1,6 @@
+---
+uid: psl-vos-getting-started
+---
 # Getting Started
 This section covers several important topics to get you up to speed when developing for the visionOS platform. Here you will find links to a step-by-step guide for building your first Unity PolySpatial XR app and some development best practices when developing for PolySpatial XR.
 
@@ -13,8 +16,8 @@ you will find a wide range of vertical slices demo projects explaining how to de
 
 ## Porting Existing Projects
 
-When porting existing Unity projects to visonOS, several considerations need to be taken into account. The biggest limitation is that some core Unity features aren't supported, and others provide a reduced feature set. In addition, input is different, and processing power and supported components will vary. Sometimes you will have to develop your own systems to support your unique project features and work around these limitations.
+When porting existing Unity projects to visionOS, several considerations need to be taken into account. The biggest limitation is that some core Unity features aren't supported, and others provide a reduced feature set. In addition, input is different, and processing power and supported components will vary. Sometimes you will have to develop your own systems to support your unique project features and work around these limitations. 
 
-You can find information about [porting VR experiences to visionOS](VRApps.md#porting-vr-experiences-to-visionos), find out which [Unity features and components](SupportedFeatures.md) are currently supported for immersive apps, or how to use [Project Validation](PolySpatialXRProjectValidation.md) for helpful in-editor assistance to port a project. For more information on input and other dev topics, review the [Reference documentation](TableOfContents.md#reference-documentation).
+You can find information about [porting VR experiences to visionOS](VRApps.md#porting-vr-experiences-to-visionos), find out which [Unity features and components](SupportedFeatures.md) are currently supported for immersive apps, or how to use [Project Validation](PolySpatialXRProjectValidation.md) for helpful in-editor assistance to port a project.
 
 <!-- ## Development best practices -->

Documentation~/Glossary.md

@@ -1,6 +1,9 @@
+---
+uid: psl-vos-glossary
+---
 # Glossary
 
-- **PolySpatial Core** (com.unity.polyspatial): The foundational PolySpatial Package, where initialization and all setup begins. It performs change tracking and processing, serialization/deserialization, and includes the ShaderGraph to MaterialX converter
+- **PolySpatial Core** (com.unity.polyspatial): The foundational PolySpatial Package, where initialization and all setup begins. It performs change tracking and processing, serialization/deserialization, and includes the Shader Graph to MaterialX converter
 
 - **PolySpatial XR** (com.unity.polyspatial.xr): Includes scene validation, capability profiles, building blocks, and coaching UI. Adds package dependencies on XRI, AR Foundation, and XR hands.
 
@@ -18,10 +21,11 @@
     - **Host (or Backend) Space**: The world space of the backend or Host in which a PolySpatial app is running. This may differ from **Unity Sim Space** because the host environment may allow apps to be moved around independently (for example, relocated to another position and volume in the real world).
     - **Host (or Backend) Physics**: The physics and colliders implemented within the backend to model the full shared environment for purposes such as input, selection, and cross-app interactions.
 
+
 - **PolySpatial Layer**: A Unity layer that is created to house the backing objects of the Unity SceneGraph. If no such layer already exists *and* there are no free layers in which to create a new layer, the PolySpatial runtime will not initialize when you enter Play Mode, and you will instead get vanilla Unity rendering.
 
 - **Volume Camera**: A new component which defines what content within a Sim scene that should be displayed on the Host. A volume camera consists of a mode, an oriented bounding box (OBB), and a culling mask. There are currently two modes:
-    - Bounded Mode: In this mode, all content within the volume camera's OBB *and* whose layer matches the culling mask will be replicated to the host. Content that falls on the border (partially inside and partially outside the OBB) will be clipped.  
+    - Bounded Mode: In this mode, all content within the volume camera's OBB *and* whose layer matches the culling mask will be replicated to the host. Content that falls on the border (partially inside and partially outside the OBB) will be clipped. 
     - Unbounded Mode: In this mode, the OBB is ignored, and all content in the scene whose layer matches the culling mask will be replicated to the host. No content is explicitly clipped. See (see [VolumeCamera](VolumeCamera.md)) for more details.
 
 - **Exclusive Mode**: Refers to the runtime behavior where an app is the only active and visible application

Documentation~/HoverEffect.md

@@ -1,6 +1,12 @@
+---
+uid: psl-vos-hover-effect
+---
 # PolySpatial Hover Effect
-Provides a hint to the platform to apply a system hover effect when the user is hovering over this object. This is typically used to provide a visual cue to the user that the object is interactive. This effect gets triggered by gaze or a hand poke. The effect is applied to the object that is being hovered over, and not the object that is doing the hovering.
+
+This component provides a hint to the platform to apply a system hover effect when the user is hovering over this object. This is typically used to provide a visual cue to the user that the object is interactive. This effect gets triggered by gaze or a hand poke. The effect is applied to the object that is being hovered over, and not the object that is doing the hovering.
 
 For privacy reasons, visionOS does not permit apps access to user gaze directly. However, it is often helpful to visually highlight objects at which the user is gazing in order to hint which object will receive input if the user performs a pinch gesture. To this end, Unity PolySpatial provides a `PolySpatialHoverEffect` component for visionOS, which can be added to GameObjects that might receive input via gaze. The presence of this component instructs the host platform (RealityKit) to apply a coloration effect to `GameObject`'s `MeshRenderer` any time the user's gaze ray intersects its corresponding collider(s). 
 
 All three components must be present to achieve an effect: the `PolySpatialHoverEffect` indicates a `GameObject` should display hover, a `Collider` component defines the collision shape against which the gaze ray is cast, and the `MeshRenderer` provides the mesh and geometry on which the coloration affect will be applied.
+
+![PolySpatialHoverEffect](images/ReferenceGuide/PolySpatialHoverEffect.png)

Documentation~/Input.md

@@ -1,3 +1,6 @@
+---
+uid: psl-vos-input
+---
 ## Input
 <a name="input"></a>
 
@@ -10,7 +13,7 @@ In both bounded and unbounded volumes, a 3D touch input is provided when the use
 
 3D touch events are exposed via the **PolySpatialTouchSpace Input device**, which is built on top of the `com.unity.inputsystem` package, otherwise known as the New Input System. Existing actions bound to a touchscreen device should work for 2D input. For 3D input, users can bind actions to the specific **PolySpatialTouchSpace** device for a 3D position vector.
 
-A collider with the collision mask set to the PolySpatial Input layer is required on any object that can receive 3D touch events.  Only touches against those events are reported.  At this time, the platform does not make available the gaze ray at the start of a tap gesture.
+A collider with the collision mask set to the PolySpatial Input layer is required on any object that can receive 3D touch events. Only touches against those events are reported. At this time, the platform does not make available the gaze ray at the start of a tap gesture.
 
 
 ### Skeletal Hand Tracking