SteamVR 插件使用文档

admin管理员组

文章数量:1531412

文档目录

• Introduction
• 1 Quickstart（快速开始）
• • 1.1 Download（下载插件）
  • 1.2 SteamVR Input Window（输入窗口）
  • 1.3 Copy JSONs（复制 JSON）
  • 1.4 Save and Generate（保存并生成）
  • 1.5 Interaction System（交互系统）
• 2 Render Models（渲染模式）
• • 2.1 The Component（组件）
  • 2.2 Attaching Objects（附着对象）
  • 2.3 Notes（注意）
• 3 SteamVR Input（输入系统）
• • 3.1 Boolean 类型
  • 3.2 Single 类型
  • 3.3 Vector2 类型
  • 3.4 Vector3 类型
  • 3.5 Pose 类型
  • 3.6 Skeleton 类型
  • 3.7 Vibration 类型
  • 3.8 Using actions（动作使用）
  • 3.9 New action sets（新建动作集）
• 4 Skeleton Input（骨骼输入）
• • 4.1 Range Of Motion（运动范围）
  • 4.2 Skeletal Transform Space（骨骼变换空间）
  • 4.3 Finger Curls（手指弯曲）
  • 4.3 Finger Splays（手指伸展）
  • 4.4 Skeletal Tracking Level（骨骼跟踪级别）
  • 4.5 SteamVR_Behaviour_Skeleton
  • 4.6 SteamVR_Behaviour_Skeleton Events
• 5 Interaction System（交互系统）
• • 5.1 Getting started（入门指南）
  • 5.2 Sample scene（示例场景）
  • 5.3 Documentation（文件）
  • • 5.3.1 Core
    • 5.3.2 Player
    • 5.3.3 Hand
    • 5.3.4 Interactable
    • 5.3.5 Throwable
    • 5.3.6 LinearDrive
    • 5.3.7 CircularDrive
    • 5.3.8 LinearMapping
    • 5.3.9 VelocityEstimator
    • 5.3.10 IgnoreHovering
    • 5.3.11 UIElement
    • 5.3.12 ItemPackage
    • 5.3.13 ItemPackageSpawner
    • 5.3.14 ItemPackageReference
    • 5.3.15 PlaySound
    • 5.3.16 SoundPlayOneShot
    • 5.3.17 Util
    • 5.3.18 InteractableHoverEvents
    • 5.3.19 InteractableButtonEvents
    • 5.3.20 ComplexThrowable
    • 5.3.21 DistanceHaptics
    • 5.3.22 Player (Prefab)
    • 5.3.23 BlankController (Prefab)
  • 5.4 Teleport（传送）
  • • 5.4.1 Teleport
    • 5.4.2 TeleportMarkerBase
    • 5.4.3 TeleportArea
    • 5.4.4 TeleportPoint
    • 5.4.5 TeleportArc
    • 5.4.6 AllowTeleportWhileAttachedToHand
    • 5.4.7 IgnoreTeleportTrace
    • 5.4.8 Teleporting (Prefab)
    • 5.4.9 TeleportPoint (Prefab)
  • 5.5 Render Model（渲染模型）
  • • 5.5.1 Hints
    • 5.5.2 ControllerButtonHints
    • 5.5.3 Longbow
    • • 5.5.3.1 Longbow.cs
      • 5.5.3.2 ArrowHand.cs
      • 5.5.3.3 Arrow.cs
      • 5.5.3.4 ArrowheadRotation.cs
      • 5.5.3.5 SoundBowClick
      • 5.5.3.6 ArcheryTarget.cs
      • 5.5.3.7 FireSource.cs
      • 5.5.3.8 ExplosionWobble.cs
      • 5.5.3.9 Balloon.cs
      • 5.5.3.10 BalloonColliders.cs
      • 5.5.3.11 BalloonHapticBump.cs
      • 5.5.3.12 BalloonSpawner.cs
  • 5.6 Samples（示例）
  • • 5.6.1 ControllerHintsExample
    • 5.6.2 InteractableExample
• 6 Skeleton Poser（骨骼姿态）
• • 6.1 The Basics（基本需求）
  • 6.2 Using the Skeleton Poser with the SteamVR Interaction system（将 Skeleton Poser 与 SteamVR 交互系统结合使用）
  • 6.3 Pose Editor（姿态编辑器）
  • 6.4 Blending Editor（混合编辑器）
  • 6.5 Manual Behaviours（手动行为）
  • 6.6 Scaling（缩放）
• 7 文档更新记录
• 8 小结

---

Introduction

  本文基于 SteamVR 插件的开发文档翻译并总结 SteamVR 开发过程中的基本用法。本文总结汇总了 SteamVR 插件文档的内容，对文档部分内容进行了删减。目前仅仅只是翻译并结合部分内容进行补充，部分内容可能存在纰漏，后续会结合开发过程逐步更新修改此文章的内容。
  插件文档地址：https://valvesoftware.github.io/steamvr_unity_plugin/articles/intro.html

设备	版本
Unity	2019.1.2.f1
SteamVR Plugin	V2.7.3
HMD	HTC VIVE Pro 2.0

1 Quickstart（快速开始）

1.1 Download（下载插件）

  插件下载有很多方式，可以前往 Steam 平台下载，也可以在 Unity Asset Store 搜索 Steam VR 进行下载。
  Steam：https://store.steampowered/app/250820/SteamVR/
  Unity Asset Store：https://assetstore.unity/packages/tools/integration/steamvr-plugin-32647
  安装教程详情参考：https://blog.csdn/xiaofeiyu321/article/details/120163304?spm=1001.2014.3001.5501

1.2 SteamVR Input Window（输入窗口）

  在 Unity 中导入 Steam VR 插件，导入完成后可以在 Window 菜单栏中打开 Steam VR 的输入窗口。

1.3 Copy JSONs（复制 JSON）

  单击确定复制默认的 “SteamVR Input JSON” 文件。 这些 actions（动作）和 binding（绑定）将帮助交互系统工作，并为您提供如何开始的示例。

  在打开SteamVR Input 窗口的过程中，插件会检测项目中是否存在 actions.json 文件，该文件存储了项目中动作（Action）与动作集（Action Sets）的信息，在打开SteamVR Input窗口时会读取该文件。如果没有 actions.json，插件会建议使用默认提供的示例文件

  点击 Yes 后，会生成默认的与输入有关的 json 配置文件：

  插件会将示例文件 actions.json 以及一些当前主流控制器的按键绑定配置文件拷贝到项目中的 StreamingAssets/SteamVR 下，在之后程序运行时，也将从此文件夹中读取用户关于动作（action）的配置信息。

1.4 Save and Generate（保存并生成）

  拷贝上述 Json 文件并打开窗口后，点击底部的 “保存并生成” 按钮。 这将保存您的操作并生成一些类来初始化它们，并使您可以在编辑器中和通过代码轻松访问它们。

  在窗口中有四个 Action Sets（动作集）以及动作集包含的 Actions（动作），我们可以在面板中根据需求自定义动作集（添加自己的动作集或者删除原有动作集的内容）。

  我们自定义完成动作的设置后，可以点击 Open binding UI 就可以对动作进行绑定。

  当点击 Save and Generate 按钮后，插件将为动作以及动作集生成可编程访问的对象类，将它们放置在项目的 SteamVR_Input 目录下。

1.5 Interaction System（交互系统）

  完成上述操作后，打开 “交互系统” 示例场景，我们可以在 Assets/SteamVR/InteractionSystem/Samples/Interaction_Example 找到示例场景。

  然后连接头盔，控制器等设备，点击 Unity 的播放，开始探索 “交互系统” 的示例场景。
  注：示例场景中包含很多常用的功能，在日后的开发过程中，可能需要实现类似示例场景中的功能。例如，利用射线实现 UI 交互、利用手柄抓握物体、传送等。可以多体验一下示例场景，学习相关功能的实现。

2 Render Models（渲染模式）

  由于沉浸在虚拟现实中时您的整个视野​​都会被覆盖，因此拥有您所握持的控制器的虚拟表示会很有帮助。SteamVR 提供了一种简单的方法，不仅可以获取通用控制器模型，还可以获取具有单独驱动组件的模型。 因此，当您在现实生活中扣动控制器上的扳机时，您也可以在虚拟世界中看到它也在拉动。 这有助于提高可用性并有力地促进存在感。

2.1 The Component（组件）

  交互系统和简单示例场景都有使用渲染模型的装备。 在 [Camera Rig] 预制件的 Simple Sample 场景中，您将找到Controller (left)和Controller (right)。 这些游戏对象上有一个SteamVR_Behaviour_Pose组件，用于设置变换的位置和旋转。

  在这些对象下，您将看到名为Model的 GameObjects，其中包含我们的SteamVR_RenderModel组件。 它有几个成员：

• Index 索引：这是控制器的 “跟踪设备索引”。 它是渲染模型系统用来向底层系统标识控制器的整数 id。 在之前的 SteamVR 迭代中，这也用于访问该控制器上的输入，但现在这是通过 “输入系统” 完成的。
• Model Override 模型覆盖：通常出于测试目的，您可以指定要显示的模型，而不是动态评估连接的设备类型。
• Shader 着色器：如果您更喜欢使用不同的着色器来渲染模型，您可以在此处指定它。 默认情况下，使用 Unity 的标准着色器。
• Verbose 详细：将输出调试日志以告诉您脚本发生了什么。
• Create Components 创建组件：在勾选的情况下为每个组件创建单独的游戏对象。
• Update Dynamically 动态更新：将移动单个组件与其物理对应物内联。

2.2 Attaching Objects（附着对象）

  开发人员通常希望将游戏对象附加到控制器上的特定点。 为此，我们在控制器的每个部分下放置了一个名为 “attach” 的游戏对象，该部分以相关部分为中心。 为便于访问，您可以访问SteamVR_RenderModel脚本并调用GetComponentTransform(string componentName)，它将返回 \a Transform（不进行任何 GC 分配）。 此处的 componentName 参数区分大小写，因此请确保传入的组件名称与运行时在 Hierarchy 视图中显示的完全相同。

2.3 Notes（注意）

  SteamVR_RenderModel组件需要与设置其索引的对象位于同一游戏对象上。 在[CameraRig]预制件中，这是由SteamVR_Behaviour_Pose脚本完成的。

3 SteamVR Input（输入系统）

  SteamVR Unity 插件的核心是 action(动作)。 虚拟现实正在快速发展，我们需要我们的软件能够与硬件一起发展。 SteamVR 输入将代码的设备特定部分抽象化，因此您可以专注于用户的意图 - 他们的 action(动作)。 而不是编写代码来识别 “将 Trigger 按钮下拉 75% 的方式来抓取块”，您现在可以只关注最后一点， “抓住块”。 您仍然可以为 “抓取” 的含义配置默认值，但用户可以在标准界面中将其重新绑定到他们设定的偏好（首选项）。 当新的输入设备出现时，您的用户可以发布绑定以共享该设备，而无需更改代码。

  Input System 与之前处理用户输入有显著的不同，使用 SteamVR Input System，开发人员可以在应用程序之外定义默认的动作并与按键进行绑定，而不需要将输入视为某一特定设备的特定按键。这样新的设备可以快速适配应用程序，无需更改代码。比如，当开发者检测玩家是否抓取某个物体的时候，不是检测 Vive 控制器的 Trigger 键或 Oculus Touch 控制器的 Grip 键是否被按下，而是检测预定义的 “Grab” 动作是否为 True 即可。作为开发者，可以在 SteamVR 中为 Grab 动作设置默认按键和阈值，当程序运行时，也可修改这些数值以满足玩家的个人偏好。基于这种机制，不光能够解决控制器碎片化的问题，也可以快速适配未来发布的设备。

action（动作）：程序中定义的用户行为，例如：传送、左右转动等。我们可以将这些动作与不同设备手柄的按键进行绑定。
开发过程中，我们只需要定义好用户可执行的动作，使用不同设备的用户只需要在手柄设置面板中自定义动作与按键的绑定就可以使用我们开发的程序了。
也即不需要重新编写代码，只需在设置面板更改动作的绑定。

  [核心]：关注动作而不是按键本身！因为不同设备按键不同，但对于应用只需知道动作而不用在意按键。这样就能使得开发者在编程中专注于用户的动作，而不是具体的控制器按键。

  这种抽象输入的风格与许多其他公司正在考虑的类似。 大多数主要虚拟现实硬件公司的成员都加入了 Khronos，创建了仍在开发中的 OpenXR 标准。（OpenXR 是一套标准接口，它介于设备生产商与内容制作之间。）

  SteamVR 将动作分为 6 种不同类型的输入和一种输出类型：

• Boolean - true or false
• Single - an analog value
• Vector2 - two analog values
• Vector3 - three analog values
• Pose- position, rotation, velocity, and angular velocity（位置、旋转、速度和角速度）
• Skeleton - Orientations for each bone in a hand（手中每根骨头的方向）
• Vibration - Actuating haptic motors（驱动触觉电机——震动输出）

3.1 Boolean 类型

  Boolean 类型的动作是 True 或 False 的值。 例如，Grab 是一个常见的动作，要么为真，要么为假。 要么打算抓取某物，要么不抓取，不存在中间状态。 对于 Vive Wand，这可能意味着将扳机扣动 75%，对于 Oculus Touch，这可能意味着将手柄扳机扣动 25%，对于 Knuckles，这可能是电容感应和力感应的某种组合。 但最终它分解为真值或假值。在 Unity 中对应类为SteamVR_Action_Boolean，通常用于按钮动作。

3.2 Single 类型

  Single 类型的动作是从 0 到 1 的模拟值，类似于浮点型（float）。在这些场景中，您需要更多数据而不仅仅是真或假。 这些比您预期的要少。 如果之前您正在读取 0 到 1 的值，然后等待它达到某个点，即阈值，那么您可以使用布尔操作完成相同的操作，从而使您的最终用户更容易进行自定义。 单个动作的一个很好的例子是 SteamVR 交互系统中遥控车的油门。 您作为用户所采取的动作可能因您希望汽车行驶的速度而异。在 Unity 中对应类为SteamVR_Action_Single，常用于获取 Trigger 键的键程值。

3.3 Vector2 类型

  Vector2 类型的动作是两个模拟值的组合，是二维数据。 一般在 VR 中，这类动作最好通过径向菜单或 2D 定位来表示。 在 SteamVR 交互系统中，我们有一个驾驶遥控车和游戏平台（platformer）类型角色的示例。 在 Vive Wand 上，它映射到触摸板，但在 Oculus Touch 和 Knuckles 上，它映射到操纵杆。 对于遥控车，我们使用 y 轴来确定向前或向后的方向，使用 x 轴来确定转弯。 使用游戏平台（platformer），我们将 x/y 输入映射到角色移动的方向和幅度。在 Unity 中对应类为SteamVR_Action_Vector2，与 Unity 或 C# 中的 Vector2 类型相似，常用于获取 Trackpad 上手指接触点坐标。

3.4 Vector3 类型

  Vector3 类型的动作不常用，是三维数据，有 3 个数据成员。 在 SteamVR Home 中，这用于滚动，x、y 和 z 是要滚动的页面数量。在 Unity 中对应类为SteamVR_Action_Vector3。

3.5 Pose 类型

  Pose 类型的动作表示三维空间中位置和旋转，一般用于跟踪 VR 控制器。 用户可以通过在控制器上设置姿势代表的点来自定义这些绑定。 一些用户可能会发现稍微不同的跟踪位置或旋转对他们来说感觉更好。在 Unity 中对应类为SteamVR_Action_Pose，用于获取手柄控制器的运动数据。

3.6 Skeleton 类型

  Skeleton 类型的动作使用 SteamVR 骨骼输入来获得我们对握住 VR 控制器时手指方向的最佳估计。这种类型的动作能够获取用户在持握手柄控制器时的手指关节数据，通过返回数据，结合手部渲染模型，能够更加真实的呈现手部在虚拟世界的姿态，虽然不及像 LeapMotion 等设备获取手指输入那样精确，但是足以获得良好的沉浸感。在 Unity 中对应类为SteamVR_Action_Skeleton（提供用于呈现手部模型的骨骼数据，每个关节点的位置和旋转）。

3.7 Vibration 类型

  Vibration 类型的动作用于触发 VR 设备上的触觉反馈。 这可以是控制器、背心，甚至是椅子。

3.8 Using actions（动作使用）

  创建动作后，您可以在自己的脚本中使用它们，也可以使用我们创建的用于处理一些常见任务的统一组件。 它们被命名为 SteamVR_Action_Boolean、SteamVR_Action_Single、SteamVR_Action_Vector2、SteamVR_Action_Vector3、SteamVR_Action_Pose和SteamVR_Action_Skeleton。 将它们拖到 GameObject 上以查看它们可以做什么。

  我们可以在 C# 脚本中定义对应类型的动作（具体代码参照后面文件所示）：

  将脚本挂载到物体身上，在 Inspector 面板中可以给定义的动作进行赋值：

  动作的完整路径参照 action.json 文件中所示：

  也可以通过代码直接获取动作，获取动作的方法有很多种（可以参照 SteamVR 插件的 API 文档），如下图所示：

//通过该动作的完整路径获取动作--/actions/[actionSet]/[direction]/[actionName]
//动作的路径参照上图--/actions/default/in/InteractUI

//T--期望返回的动作类型，actionName--动作的名字，caseSensitive--检索时是否区分大小写
public static T GetAction<T>(string actionName, bool caseSensitive = false)
public static SteamVR_Action_Single GetSingleAction(string actionName, bool caseSensitive = false)

  代码如下图所示，可以通过这两种方式指定动作：

  赋值后运行程序，在 Inspector 面板中可以看到已经赋好的值：

  创建动作之后，可以进行动作测试。打开 SteamVR Input Live View 窗口，可以看到动作的触发情况：

  红色代表动作未绑定按键，绿色代表就是触发了的 action（动作）：

  获取手柄输入，利用代码获取手柄的输入：

//如果 action（state）当前值为 true，则返回 true--返回当前动作的状态，检测按键是否一直被按住
//传入 SteamVR_Input_Sources
public bool GetState(SteamVR_Input_Sources inputSource)

//如果 action 的值在最近的更新中已更改为 true（从 false），则返回 true--按下按键
//传入 SteamVR_Input_Sources
public bool GetStateDown(SteamVR_Input_Sources inputSource)

//如果 action 的值在最近的更新中已更改为 false（从 true），则返回 true--松开按键
//传入 SteamVR_Input_Sources
public bool GetStateUp(SteamVR_Input_Sources inputSource)

  SteamVR_Input_Sources 输入源：方法传入参数类型：

  代码示例：

private 

本文标签： 插件文档SteamVR