Vison Pro 开发笔记

前期准备

软硬件要求

• Apple Silicon Mac for development - 具备M1/M2/M3的Mac
• Unity 2022 LTS(2022.3.11f1 and higher) - Unity Pro会员使用
• Xcode 15.1 beta 1
• visionOS beta4(21N5259k) - SDK
• Unity Pro LTS

另外需要强调一下：不同于打包iOS的应用，Windows电脑没有办法安装Vision Pro的Build环境

参考文档/视频

Unity PolySpatial - 开发 visionOS 你所需要知道的每一件事情
Unity PolySpatial - 官方开发手册
Unity Apple Version Pro Develop - 官方免费教程
Unity 2022.3.18版本下载地址

初步了解

正式开始

• 在Package Manager中导入Poly Spatial必须模块
  – com.unity.polyspatial
  – com.unity.polyspatial.visionos
  – com.unity.polyspatial.xr
• 在Project Setting中开启Apple vision OS的选项配置
  – Hands Tracking Usage Description 输入内容为input
  – World Sensing Usage Description 输入内容为input
• 在Project Validation中进行警告和报错修复，进行Fix All
• 在Project Setting中开启Poly Spatial的选项

打包测试

使用XCode进行Build失败

• VR模式：在移除 com.unity.polyspatial.visionos & com.unity.polyspatial.xr后仍然可以成功运行
• MR模式：需要加入com.unity.polyspatial.visionos & com.unity.polyspatial.xr才能在Build Setting中选择PolySpatial中的选项Enable Poly Spatial Runtime进行开启

打包踩坑

• 2022.3.12f版本是开发时国内UnityHub中能下载的且能成功跑通的的版本，其他的版本都会导致iOS代码中的UnityCreateWebRequestBackend报错，因此花了不少时间来测试不同版本的Unity进行Vision OS打包。（直接下载2022.3.18，就修复了这些问题）
• Demo的Text Mesh Pro材质会丢失，需要将Packages/PolySpatial/Resources/Shaders进行Reimprt操作，重新导入文字的材质

各个Demo模块文件结构

BalloonGallery

这个场景是一个基于手势交互的气球爆破游戏，它不仅实现了通过捏合手势来爆破气球并获得分数的核心玩法，还集成了粒子特效和用户界面（UI）元素以增强用户体验。该项目旨在为开发者提供实践案例，使他们能够学习如何有效地利用Unity的输入系统处理复杂的手势操作，如何使用粒子系统来创建视觉效果，以及如何构建和交互UI组件。通过这个项目，开发者将掌握在Unity中创建交互式游戏和应用程序所需的关键技术和最佳实践。

• Animations&Materials&Meshes&Prefabs 动画材质模型预制体资源文件夹
• Scripts 脚本文件夹

脚本功能简述

脚本名称	描述
BalloonBehavior	定义了气球的行为，包括设置气球的颜色和得分值，处理气球被戳破时的动画效果和粒子效果，并在气球戳破时通知BalloonGalleryManager更新得分。
BalloonGalleryManager	负责跟踪气球游戏中的得分，更新气球戳破的计数，并在所有气球被戳破时显示庆祝的纸屑效果。它在游戏开始时初始化，并将所有气球的管理器设置为自身。
BalloonMovement	控制气球的移动行为，使气球按照正弦波形进行上下浮动，产生浮动效果。气球的初始移动延迟是随机的，介于最小和最大延迟时间之间，并通过Update函数更新气球的位置。
FadeOffText	实现文本的淡出效果，通过改变文本颜色的透明度来逐渐减少文本的可见性。在Start方法中保存文本的初始颜色，并在Update方法中根据时间的推移计算透明度的变化。
GalleryInputManager	处理触摸输入，管理气球的戳破动作，并在场景中可视化触摸的位置和旋转。它通过启用增强触摸支持来正确地处理输入阶段，并在检测到触摸开始时触发气球的戳破动作。
LoadNextGallery	用于加载下一个画廊场景，通过检测用户按下键盘上的“A”键来触发场景加载。当“A”键被按下时，调用LoadGallery方法使用SceneManager加载预设的画廊场景名称m_SceneName，实现简单的场景导航控制。

CharacterWalker

本场景是一个交互式角色移动游戏，它通过手势识别技术实现对角色模型在三维地图上的精确控制。该项目融合了摄像机动态追踪和路径寻路插件的集成应用，为开发者提供了一个实践平台，用以学习如何在Unity环境中高效地处理触摸输入、利用寻路工具进行角色导航，以及实现摄像机的平滑移动。

• Character/Animations&Character/Models 动画和任务模型文件
• Scripts脚本文件夹

脚本功能简述

脚本名称	描述
CameraMovementBehavior	控制相机的移动，使其根据角色与相机的当前距离来调整位置。如果角色与相机的距离超过设定的阈值，相机将以设定的速度朝角色位置移动，提供平滑的跟随效果。
CharacterInputManager	根据触摸输入移动游戏中的角色。使用增强触摸支持来处理用户的触摸动作，根据触摸位置调整角色的目标位置，并控制角色的移动速度和动画，使角色平滑地移动到指定位置。

ImageTracking

• Art&Images&Prefabs数字模型、材质、图片以及预制体
• Scripts脚本文件夹
• ReferenceImageLibrary.asset
• Tracking.prefab追踪点位预制体对象

脚本功能简述

脚本名称	描述
DistanceManager	用于在两个图像跟踪对象之间的距离小于特定阈值时显示一个预制体。游戏开始时创建预制体实例，并在更新过程中检查距离，根据情况激活或隐藏预制体，并将其放置在两个对象的中间位置。
ImageTrackingObjectManager	管理增强现实应用中与特定图像关联的预设对象。监听图像跟踪状态变化，实例化、定位或销毁预设对象，确保虚拟内容在用户环境中的准确展示。
NumberBehavior	控制游戏中的数字对象，确保其始终面向主摄像机。在Awake方法中配置AimConstraint组件，如果缺少该组件，则在控制台输出错误信息。

Manipulation

本演示场景旨在展示如何利用Unity的手势交互API来实现物体的抓取功能，同时融入了重力系统和混合现实（MR）中的旋转交互。该场景为用户提供了一个交互式的学习平台，使他们能够深入理解并实践在Unity中处理复杂用户输入、物理模拟以及空间跟踪的技术。通过这个Demo，开发者将学习到如何精确地捕捉和响应用户的手势动作，以及如何在MR环境中实现物体的自然重力响应和直观的旋转控制。

脚本功能简述

脚本名称	描述
ManipulationInputManager	允许用户通过增强触摸输入（如捏合手势）选择和移动场景中的物体。在启用时配置触摸支持，并响应触摸事件以执行物体的选择、移动或释放操作。
PieceSelectionBehavior	为游戏对象添加选择和高亮显示的功能。被选中时改变材质颜色，并临时设置为新父对象下，同时管理刚体组件的isKinematic属性，以控制物理模拟。
ResetObjectZone	当游戏对象进入特定触发区域时，将其重置到预设的重生位置。检查对象是否有PieceSelectionBehavior组件，并在有的情况下重置其位置和物理状态。

MixedReality

• Materials&Prefabs&Textures 整个游戏的通用材质、预制体、贴图
• Scripts 脚本文件夹

脚本功能简述

脚本名称	描述
HandVisualizer	用于在虚拟现实或增强现实场景中可视化用户手部的脚本。通过XRHandSubsystem追踪手部关节并更新游戏对象的位置和旋转，反映手部实际状态，并在手部追踪丢失时隐藏模型。
PinchManager	用于检测和处理捏合手势的脚本。通过XR手部跟踪系统获取手部关节位置，计算食指和拇指间的距离，当距离小于阈值时在捏合位置实例化游戏对象。适用于需要捏合手势交互的XR应用。
PinchSpawn	在XR环境中检测捏合手势，并在捏合发生时在指定位置生成预设游戏对象的脚本。通过XR手部跟踪子系统更新手部关节数据，并在食指和拇指尖端接近时实例化对象。
PlaceOnPlane	在AR应用中将对象放置到平面上的脚本。使用射线投射从相机发出，检测AR平面交点，并在交点处创建或更新游戏对象的位置和旋转，使其与物理表面对齐。
PlaneDataUI	用于在AR应用中显示AR平面分类和对齐信息的脚本。监听AR平面边界变化事件，并更新UI组件显示平面的分类和对齐属性，同时将UI位置设置到平面中心点。

ProjectLauncher

-Materials&Prefabs 关卡气泡材质、按钮预制体

• Scripts 脚本文件夹

脚本功能简述

脚本名称	描述
ArrowButton	响应按下事件，通知LevelBubbleManager左/右箭头按钮被按下。
BubbleLayoutManager	用于在圆形轨道上布局级别气泡，计算并设置气泡的位置以均匀分布。
BubbleSize	控制游戏对象的缩放动画，允许设置不同目标缩放大小并平滑过渡。
LevelBubbleManager	管理级别选择界面的气泡布局和交互，响应用户导航并加载选中的关卡。
PlayButton	当玩家按下空格键时，触发加载当前选中的关卡。

SpatialUI

这个场景精心设计了一系列混合现实（MR）中的用户界面（UI）组件，以提供一个交互式的学习体验。在这个Demo实例场景中，用户不仅能够探索和理解各种UI元素的基本用途，还能够学习如何实际应用这些元素来构建引人入胜的MR体验。具体来说，用户将学习如何使用Option（选项）组件来提供多个选择项，利用Toggle（切换）组件进行开/关状态的切换，操作Slider（滑块）组件以选择数值范围，以及点击Button（按钮）组件来触发事件或动作。通过这些交互，用户可以更深入地理解MR应用中的UI设计原则和最佳实践。

XRIDebug

这个场景专门设计了两个可在虚拟现实（VR）中抓握的立方体，旨在提供一个交互式的学习环境，让用户亲身体验和掌握抓握交互功能。在这个Demo中，用户将有机会直接与虚拟对象进行物理模拟的抓握操作，学习如何使用VR控制器的输入来抓取、提起、移动和释放物体。通过实际操作，用户将理解抓握机制的工作原理，包括触摸检测，这些都是开发丰富VR体验时不可或缺的交互元素。

熟悉Demo使用到的相关API

EnhancedSpatialPointerSupport

命名空间：Unity.PolySpatial.InputDevices
使用位置：GalleryInputManager.cs
整体来看，这个类提供了触摸输入状态的查询和管理功能，允许系统跟踪和处理触摸输入的历史状态。简单来说就是用于获取手势的各种数据，用于增强触摸输入的处理，以下是代码中的各个函数：

这段代码是Unity PolySpatial插件的一部分，用于增强触摸输入的处理。PolySpatial是Unity的一个插件，旨在提高多人协作和远程交互的体验。下面是对代码中各个函数的分析和作用说明：

1. TryGetPointerState 方法:

   • 尝试获取指定触摸点的状态。
   • 参数: Touch touch - 要查询状态的触摸对象。
   • 返回值: SpatialPointerState - 触摸点的状态。

2. GetPointerState 方法:

   • 获取指定触摸点的状态。
   • 参数: Touch touch - 要查询状态的触摸对象。
   • 返回值: SpatialPointerState - 触摸点的状态。

3. AddInputs 方法:

   • 向系统添加输入设备。
   • 参数: SpatialPointerDevice pointerDevice - 要添加的指针设备。

4. ShouldRecordTouch 方法:

   • 判断是否应该记录触摸事件。
   • 参数:
     • InputControl control - 当前输入控制。
     • double time - 当前时间戳。
     • InputEventPtr eventPtr - 输入事件指针。
   • 返回值: bool - 是否应该记录事件。

GalleryInputManager.cs
这段Unity脚本GalleryInputManager用于处理画廊场景中的触摸输入。当触摸开始时，脚本检查触摸类型，如果是通过间接捏合或直接触摸，它会找到并戳破气球对象。同时，脚本会在场景中实时更新和显示一个输入轴（m_InputAxisTransform），以反映触摸的位置和旋转，增强用户交互的可视化体验。
CharacterInputManager.cs
这段Unity脚本CharacterInputManager这段Unity代码通过启用增强触摸支持，允许角色响应触摸输入进行移动。它使用SpatialPointerState类来获取触摸的位置和状态，然后根据触摸输入更新角色的目标位置，并控制角色朝着该目标移动。同时，它还会根据角色与目标的距离来调整角色的移动速度和动画。

SpatialPointerState

命名空间：UnityEngine.InputSystem.LowLevel
使用位置：CharacterInputManager.cs
以下是SpatialPointerState类中各个参数的名称和它们的作用（这些参数共同描述了一个空间指针的状态，包括它的位置、变化、目标对象以及当前的交互阶段等信息。）：

参数名称	作用	类型
interactionId	交互ID，用于标识特定的输入事件。	int
interactionPosition	交互位置，表示输入设备在空间中的位置。	Vector3
deltaInteractionPosition	交互位置的变化量，表示输入设备位置的变化。	Vector3
startInteractionPosition	开始交互时的位置，用于记录输入开始时的空间位置。	Vector3
startInteractionRayOrigin	开始交互时的射线起点，通常用于表示输入设备发出的射线的起始点。	Vector3
startInteractionRayDirection	开始交互时的射线方向，用于确定输入设备发出的射线的方向。	Vector3
devicePosition	设备位置，表示输入设备在空间中的全局位置。	Vector3
deviceRotation	设备旋转，表示输入设备的旋转状态。	Quaternion
targetId	目标ID，用于标识输入事件的目标对象。	int
modifierKeys	修饰键，表示当前被按下的修饰键（如Shift、Ctrl等）的状态。	ushort
kindId	指针种类ID，用于标识输入设备的类型（如触摸、抓取等）。	byte
phaseId	触摸阶段ID，用于标识当前的触摸阶段（如开始、移动、结束等）。	byte