SteamVR Unity Tool Kit（一）：概览和控制器事件

在学习的过程中找到的官方文档，并进行了部分的翻译。

Quick Start 快速上手

· Clone this repository git clone https://github.com/thestonefox/SteamVR_Unity_Toolkit.git

· Open the SteamVR_Unity_Toolkit within

· Import the SteamVR Plugin from the Unity Asset Store

· Browse the Examples scenes for example usage of the scripts

· 克隆仓库  git clone https://github.com/thestonefox/SteamVR_Unity_Toolkit.git

· 用Unity3d打开SteamVR_Unity_Toolkit

· 从Unity资源商店导入SteamVR Plugin

· 浏览Examples场景作为例子来看脚本的用法

Summary 概要

This toolkit provides many common VR functionality within Unity3d such as (but not limited to):

这个工具包提供了很多Unity3d里的常用VR功能，如下（但并不局限于此）：

· Controller button events with common aliases

· Controller world pointers (e.g. laser pointers)

· Player teleportation

· Grabbing/holding objects using the controllers

· Interacting with objects using the controllers

· 带有通用别名的控制器按钮事件

· 控制器世界指针（如激光指针）

· 玩家传送

· 用控制器抓取对象

· 用控制器和对象交互

The toolkit is heavily inspired and based upon the SteamVR Plugin for Unity3d Github Repo.

这个工具类基本是受到 SteamVR Plugin for Unity3d Github Repo的启发，并基于此。

The reason this toolkit exists is because I found the SteamVR plugin to contain confusing to use or broken code and I decided to build a collection of scripts/assets that I would find useful when building for VR within Unity3d.

这个工具存在的原因是因为SteamVR plugin含有令人困惑或不完善的代码，所以我决定创建一个脚本/资源集合，这在用Unity3d创建VR时是很有用处的。

Prefabs 预制

The available Prefabs are:

可用预制：

· [CameraRig]

· FramesPerSecondCanvas

[CameraRig]

The [CameraRig] has been taken directly from the SteamVR Unity plugin example: SteamVR/Extras/SteamVR_TestThrowscene as it includes the relevant Model children on the controller (which seem to b missing from the default prefab in the SteamVR plugin SteamVR/Prefabs/[CameraRig].prefab.

The SteamVR_Unity_Toolkit/Prefabs/[CameraRig] can be dropped into any scene to provide instant access to a VR game camera via the VR headset and tracking of the VR controllers including model representations.

[CameraRig]直接从SteamVR Unity plugin例子——SteamVR/Extras/SteamVR_TestThrow场景中拿来，因为它包含了控制器上相关模型的子物体（这在SteamVR plugin默认预制SteamVR/Prefabs/[CameraRig].prefab中似乎是缺失的）。 SteamVR_Unity_Toolkit/Prefabs/[CameraRig]可以被拖到任何场景中，通过VR头盔和包括模型呈现的VR控制器的追踪来提供对VR游戏相机的即时访问。

FramesPerSecondCanvas 帧率显示

This canvas adds a frames per second text element to the headset. To use the prefab it must be placed into the scene then the headset camera needs attaching to the canvas:

这个画布添加一个表示帧率的文本元素到头盔上。使用这个预制必须把它放到场景中，然后头盔的相机需要被添加到画布上。

· Select FramesPerSecondCanvas object from the scene objects

· Find the Canvas component

· Set the Render Camera parameter to Camera (eye) which can be found in the [CameraRig] prefab.

· 选择场景中的FremesPerSecondCanvas对象

· 找到Canvas组件

· 设置Render Camera参数为 [CameraRig]预制里的Camera（eye）

There are a number of parameters that can be set on the Prefab. Expanding the FramesPerSecondCanvas object in the hierarchy view shows the child FramesPerSecondText obejct and clicking on that reveals additional paramters which can be set via theFramesPerSecondViewer script (which can be found in SteamVR_Unity_Toolkit/Scripts/Helper/FramesPerSecondViewer)

The following script parameters are available:

预制上有很多可以被设置的参数。展开层级视图中的FramesPerSecondCanvas对象,显示子对象FramesPerSecondText并点击显示额外参数，这些参数可以通过FramesPerSecondViewer脚本（可以在SteamVR_Unity_Toolkit/Scripts/Helper/FramesPerSecondViewer找到）来设置。

可用脚本参数如下：

· Display FPS: Toggles whether the FPS text is visible.

· Target FPS: The frames per second deemed acceptable that is used as the benchmark to change the FPS text colour.

· Font Size: The size of the font the FPS is displayed in.

· Position: The position of the FPS text within the headset view.

· Good Color: The colour of the FPS text when the frames per second are within reasonable limits of the Target FPS.

· Warn Color: The colour of the FPS text when the frames per second are falling short of reasonable limits of the Target FPS.

· Bad Color: The colour of the FPS text when the frames per second are at an unreasonable level of the Target FPS.

· Display FPS:FPS文本可视切换。

· TargetFPS：认为可接受的帧率，被用来作为改变FPS文本颜色的基准。

· Font Size：FPS显示字体尺寸。

· Position：FPS 文本在头盔视野的位置。

· Good Color：当处在目标FPS的合理范围之内的FPS文本颜色。

· WarnColor：当FPS降到低于目标FPS合理范围的FPS文本颜色。

· Bad Color：当FPS处在相对目标FPS为不合理水平时FPS文本的颜色。

An example of the FramesPerSecondCanvas Prefab can be viewed in the sceneSteamVR_Unity_Toolkit/Examples/018_CameraRig_FramesPerSecondCounter which displays the frames per second in the centre of the headset view. Pressing the trigger generates a new sphere and pressing the touchpad generates ten new spheres. Eventually when lots of spheres are present the FPS will drop and demonstrate the prefab.

FramesPerSecondCanvas 预制的例子可以在SteamVR_Unity_Toolkit/Examples/018_CameraRig_FramesPerSecondCounter场景中找到，在头盔视野中间显示了帧率。按下扳机键（trigger）生成一个新的小球，按下触摸版（touchpad）生成10个新的小球。通过最终当很多小球出现的时FPS将下降来演示这个预设。

Scripts 脚本

This directory contains all of the toolkit scripts that add VR functionality to Unity.

这个目录包含了所有添加到Unity的VR功能的工具脚本。

The current available scripts are:

当前可用脚本有：

Controller Actions (VRTK_ControllerActions)控制器行为(VRTK_ControllerActions)

The Controller Actions script provides helper methods to deal with common controller actions. The following public methods are available:

控制器行为脚本提供了处理常见控制器行为的帮助方法。如下可用公共方法：

· IsControllerVisible(): returns true is the controller model is visible, returns false if it is not visible.

· ToggleControllerModel(bool on): sets the visibility of the controller model to the given boolean state. If true is passed then the controller model is displayed, if false is passed then the controller model is hidden.

· TriggerHapticPulse(int duration, ushort strength): initiates the controller to begin vibrating for the given tick duration provided in the first parameter at a vibration intensity given as the strength parameter. The max strength that can be provided is 3999, any number higher than that will be capped.

· IsControllerVisible(): 如果控制器模型是可见的返回真，否则返回假。

· ToggleControllerModel(bool on):根据所给布尔值状态设置控制器模型的可见性。如果传入true，控制器模型就被显示出来，如果传入false，控制器就被隐藏了。

· TriggerHapticPulse(int duration, ushort strength):启动控制器开始震动，根据给定的持续计时（第一个参数）和震动强度（第二个strength参数）。最大强度可以是3999，超过就限制为3999。

An example of the VRTK_ControllerActions script can be viewed in the sceneSteamVR_Unity_Toolkit/Examples/016_Controller_HapticRumble which demonstrates the ability to hide a controller model and make the controller vibrate for a given length of time at a given intensity.

VRTK_ControllerActions脚本的例子在SteamVR_Unity_Toolkit/Examples/016_Controller_HapticRumble场景中，展现了隐藏控制器和让控制器在给定强度下震动给定时长的能力。

Controller Events (VRTK_ControllerEvents)控制器事件(VRTK_ControllerEvents)

The Controller Events script is attached to a Controller object within the [CameraRig] prefab and provides event listeners for every button press on the controller (excluding the System Menu button as this cannot be overriden and is always used by Steam).

控制器事件脚本被添加到 [CameraRig]预制里的控制器对象上，为控制器上的每个按钮按下提供事件监听（除了系统菜单按钮，因为这个按钮不能被重载，只能总是由Steam使用）。

When a controller button is pressed, the script emits an event to denote that the button has been pressed which allows other scripts to listen for this event without needing to implement any controller logic.

当一个控制器按钮被按下，脚本发出一个事件表明按钮被按下了，这使得其他脚本去监听这个事件而不需要实现任何控制器逻辑。

The script also has a public boolean pressed state for the buttons to allow the script to be queried by other scripts to check if a button is being held down.

脚本也有一个公共的布尔类型的按下状态变量，允许被其他脚本查询按钮是否被按下。

When a controller button is released, the script also emits an event denoting that the button has been released.

当一个控制器按钮被释放，脚本也发送一个事件表示按钮被释放了。

The controller touchpad has two states, it can either be touched where the user simply presses their finger on the pressure sensitive pad or it can be clicked where the user presses down on the pad until it makes a clicking sound.

控制器触摸板有两个状态，既可以用户只把手指放到压力传感板上来触摸，也可以用户在板上按下去直到发出声响来点击。

The Controller Events script deals with both touchpad touch and click events separately.

控制器事件脚本同时分别处理触摸板触摸和点击事件。

There are two button axis on the controller:

控制器上有两个按钮轴：

· Touchpad touch position, which has an x and y value depending on where the touchpad is currently being touched.

· Trigger button, which has an x value depending on how much the trigger button is being depressed.

· 触摸板触摸位置，位置的x和y值基于触摸板当前被触摸位置。

· 扳机按钮，有个基于扳机键被按下去程度的x值。

There are two additional events emitted when either the Touchpad axis or the Trigger axis change their value which can be used to determine the change in either of the axis for finer control such as using the Touchpad to move a character, or knowing the pressure that the trigger is being pressed.

当触摸板的轴或者扳机键的轴值改变时，会有两个额外的事件发出，这可以被用来确定两个轴的变化来进行精确控制，如用触摸板来移动角色，或者知道扳机键被按下程度。

The Touchpad Axis is reported via the TouchpadAxis payload variable which is updated on any Controller Event.

触摸板的轴由变量TouchpadAxis 记录，在所有控制器事件的脚本中更新。

The Trigger Axis is reported via the buttonPressure payload variable which is updated on any Controller Event. Any other button press will report a button pressure of 1 or 0 as all other buttons are digital (they are either clicked or not clicked) but because the Trigger is analog it will report a varying button pressure.

扳机键的轴由变量buttonPressure 记录，在所有控制事件脚本中更新。任何其他按钮按压只记录一个为1或者0按钮压力，因为所有其他按钮都是数字量（要么就是点击要么就没有），但扳机是一个可以记录不同按钮压力的模拟量。

The amount of fidelity in the changes on the axis can be determined by the axisFidelity parameter on the script, which is defaulted to 1. Any number higher than 2 will probably give too sensitive results.

The event payload that is emitted contains:

轴值变化的精确度可以由脚本中的axisFidelity 参数来决定，默认值为1。值只要超过2就可能会产生灵敏过度的结果。

事件发出的有效载体信息包含：

· controllerIndex: The index of the controller that was used.

· buttonPressure: A float between 0f and 1f of the amount of. pressure being applied to the button pressed.

· touchpadAxis: A Vector2 of the position the touchpad is touched at.

· touchpadAngle: A float that shows the rotational position the touchpad is being touched at, 0 being top, 180 being bottom and all other angles accordingly.

· controllerIndex：所使用控制器的索引。

· buttonPressure：0到1的浮点数，表示按钮按下的所施加的压力值。

· touchpadAxis: 一个表示触摸板触摸位置的Vector2类型变量。

· touchpadAngle：一个表示触摸板触摸位置的转动位置的浮点数，0是顶部，180是底部，其他角度随之对应。

There are also common action aliases that are emitted when controller buttons are pressed. These action aliases can be mapped to a preferred controller button. The aliases are:

当控制器被按下时也会有通用动作的别名事件被发出。这些动作别名可以被映射到想要的控制器按钮上。这些别名是：

· Toggle Pointer: Common action of turning a laser pointer on/off

· Toggle Grab: Common action of grabbing game objects

· Toggle Use: Common action of using game objects

· Toggle Menu: Common action of bringing up an in-game menu

· Toggle Pointer：打开关闭镭射棒

· Toggle Grab：抓取游戏对象

· Toggle Use：使用对象

· Toggle Menu：打开一个游戏内菜单

Each of the above aliases can have the preferred controller button mapped to their usage by selecting it from the drop down on the script parameters window.

每个上面的别名都可以通过在脚本参数窗口的下拉栏里选择映射其使用到喜好的控制器按钮上。

When the set button is pressed it will emit the actual button event as well as an additional event that the alias is "On". When the set button is released it will emit the actual button event as well as an additional event that the alias button is "Off".

当所设置的映射按钮被按下时将发出一个实际按钮事件以及一个额外别名开启的事件。当按钮释放的时候就发出一个实际按钮事件以及一个额外的别名关闭的事件。

Listening for these alias events rather than the actual button events means it's easier to customise the controller buttons to the actions they should perform.

监听这些别名事件而不是实际的按钮事件意味着可以很轻易的自定义控制器按钮到它们应该执行的行为上。

An example of the VRTK_ControllerEvents script can be viewed in the sceneSteamVR_Unity_Toolkit/Examples/002_Controller_Events and code examples of how the events are utilised and listened to can be viewed in the scriptSteamVR_Unity_Toolkit/Examples/Resources/Scripts/VRTK_ControllerEvents_ListenerExample.cs

VRTK_ControllerEvents脚本的例子可以在SteamVR_Unity_Toolkit/Examples/002_Controller_Events场景中看到，事件怎样被使用和监听的代码例子可以参见SteamVR_Unity_Toolkit/Examples/Resources/Scripts/VRTK_ControllerEvents_ListenerExample.cs脚本。