Oculus Mobile Unity Integration Guide移动整合包指南

Admin

1 . Introduction简介

This document provides a basic guide to the Unity mobile SDK,which includes several sample Unity applications,SDK Examples, and an integration package for creating your own Unity virtual reality application.

Before using this SDK and the documentation, if you have notalready done so, review the Device andEnvironment Setup Guide to ensure that you are using a supported device, and to ensure that your Android Development Environment and mobile deviceare configured and set up to build and run Androidapplications.

本文档为Unity移动SDK提供了一个基本指南，包括数个Unity应用范例、SDK范例，以及一个可以拿来创建属于你自己的Unity VR应用的整合包package。

1 .1 Requirements需求

Mobile SDK is compatible with Unity Pro 4.5 (supports multi-threadedrendering for Android).

We recommend Unity Pro 4.6.1 , which includes support for Lollipop (Android 5.0) as well as stability fixes for both Android and PC.

Unity Free support for Mobile SDK is available with Unity 4.5.5 orhigher. A feature set comparison between Unity Proand Unity Free may be found here:

移动SDK可以用Unity Pro 4.5来进行编译（支持安卓的多线程渲染）

我们推荐用Unity Pro 4.6.1，因为它支持Lollipop棒棒糖（安卓5.0）的同时在安卓和PC上还有更好的稳定性。

Unity对移动SDK的免费支持在Unity 4.5.5或者更高的版本上都有。在Pro版本和免费版本之间的区别在下文可以找到：

http://unity3d.com/unity/licenses Note: There are noteworthy feature support differences betweenUnity licenses. Please review the limitationscited below as well as the license comparison on Unity’s website before committing considerable resources to one path. Your license choicewill depend largely on the performancecharacteristics and distribution needs ofyour app.

For additional system and hardware requirements, see the Deviceand Environment Setup
Guide.

Oculus/GearVR开发者群 302294234
2. First Steps第一步
2.1 Package contents封包内容

Included with the mobile SDK, you will find a set of pre-builtUnity Demos, as well as an SDK Examples project withmultiple scenes demonstrating useful mobile VR scenarios and functionality. More information about both the pre-built demos andSDK Examples project can be found in the sectionswhich follow.

在移动SDK里你会找到一系列预制好的UnityDemo，以及一个SDK范例项目，包含了多个展现了有用的移动VR场景和功能体现的布景。更多相关信息可以在下文中找到。

2.2 Running thePre-built Unity Demos运行预制Demo

To run the pre-built demos, you mustfirst install the demo packages (.apk) and sample media to your Android device.

Connect to the device via USB and open a command prompt. Run the installToPhone.bat script includedwith the SDK. This script will copy and install both the Unity and Nativesample applications as well as any sample media to your Android device.

For more information about these sample apps please review theInitial SDK Setup section in Device andEnvironment Setup Guide.

要想运行预制Demo，你必须现在你的安卓设备上安装这个Demo的apk以及范例媒体（samplemedia）。

把设备用USB连上然后打开命令行。运行和SDK放在一起的installToPhone.bat脚本。这个脚本会连同Unity和原生的范例应用以及其他的范例媒体一并复制并安装到你的安卓设备上。

更多信息请参阅Deviceand Environment Setup Guide中的SDK安装初始化部分。

To test a sample application, perform the following steps:

1 . You should see new app icons on the Android Home screens.

2. A toast will appear with a dialog like the following: “InsertDevice: To open this application, insert yourdevice into your Gear VR”

3. Insert your device into the supported Gear VR hardware.

4. The app should now launch.

想测试范例应用，请按照如下步骤操作：

1.     首先在安卓的主界面你应该能看到新的app图标；

2.     会有一条新的提示出现：“插入设备：要打开这个应用，请先将设备插入您的Gear VR”；

3.     将设备插入受支持的Gear VR硬件里；

4.     然后启动App。

2.3 Control Layout控制布局

You may wish to begin by familiarizing yourself with Unity’s inputsystem, documented here: http://docs.unity3d.com/ScriptReference/Input.html

There are several ways to handle controller input in Unity for aVR app, ranging from using the InputManager.asset fileshipped with the SDK, which pre--populates all ofthe controller mappings, to completelywriting your own script that refers to the specific hardware keys.

Beginning developers may find it easiest to set up their ownInputManager settings and then write their own controllercode.

The mappings below are used by the Samsung El-GP20 gamepad andmost other third-party Bluetooth controllers. Theactual mapping between a controller and Unity’s input system is up to the controller vendor and the Android OS, but it is generallyconsistent with this schema.

如果你希望先从熟悉Unity的输入系统开始，那么文档在链接里：http://docs.unity3d.com/ScriptReference/Input.html

有好几种方法可以用来在Unity里掌握一个VRapp的控制器输入（controllerinput），你既可以使用SDK组件里的InputManager.asset文件（预填充了全套控制器的映射），也可以根据具体的硬件按键完全靠自己来写脚本。

刚入行的开发者也许会发现，自定义设置InputManager然后写一套自主的控制器代码是相对来说最容易的一件事情。

下列映射的对应分别是三星El-GP20游戏手柄以及几乎所有第三方的蓝牙控制器。控制器和Unity输入系统的实际映射是由控制器供应商以及安卓系统决定的，但总的来说还是和这个图表大体一致的。

2.3.1 Application Specific Controls应用的具体控制

BlockSplosion

In BlockSplosion, the camera position does not change, but theGear VR will track the user’s head orientation, allowingthem to aim before launching a block.

● 1 -dot Button or Gear VR touchpad tap launches a block in thefacing direction.

● 2-dot Button resets the current level.

● Left Shoulder Button (L) skips to the next level.

在BlockSplosion里，摄像头的位置永远不会改变，但是Gear VR会跟踪用户的头部定位，在发射方块之前允许玩家进行瞄准。

● 单击按键或者在Gear VR的触摸板上点击一下会对着面前发射一个方块。

● 双击重置关卡。

● 左肩键（L）跳到下一关。

Shadowgun

In Shadowgun, locomotion allows the camera position to change.

● Left Analog Stick will move the player forward, back, left, andright.

● Right Analog Stick will rotate the player view left, right, up,and down. However, you will likely want to rotateyour view just by looking with the Gear VR.

在Shadowgun里，移动（locomotion）使得摄像头的位置发生改变。

●左摇杆允许玩家前进、后退、向左或是向右。

● 右摇杆会旋转玩家的视野，左右上下。当然了，你肯定更希望用Gear VR移动视角。

Oculus/GearVR开发者群 302294234
2.3.2 Supplied Gamepad Controller Button Mappings受支持的游戏手柄控制器按键映射

Button / Axis Name Input Manager Mapping/ Axis Value   Sensitivity

按键/轴名称  Input Manager 映射/轴值  灵敏度

Button A / 1 joystick button 0 1 000

Button B / 2 joystick button 1 1 000

Button X / 3 joystick button 2 1 000

Button Y / 4 joystick button 3 1 000

Left Shoulder Button joystick button 4 1 000

Right Shoulder Button joystick button 5 1 000

Left Trigger Button n/a 1 000

Right Trigger Button n/a 1 000

Left Analog X Axis X axis 1

Left Analog Y Axis Y axis 1

Right Analog X Axis 3rd axis (Joysticks and Scroll wheel) 1

Right Analog Y Axis 4th axis (Joysticks) 1

Dpad X Axis 5th axis (Joysticks) 1 000

Dpad Y Axis 6th axis (Joysticks) 1 000

Play Button n/a 1 000

Select Button joystick button 1 1 1 000

Start Button joystick button 1 0 1 000

按键A/1   摇杆按键0   1000

按键B/2   摇杆按键1   1000

按键X/3   摇杆按键2   1000

按键Y/4   摇杆按键3   1000

左肩键     摇杆按键4   1000

右肩键     摇杆按键5   1000

左扳机键   n/a          1000

右扳机键   n/a         1000

左摇杆X轴 X轴       1

左摇杆Y轴 Y轴       1

右摇杆X轴 第三轴（摇杆及滚轮） 1

右摇杆Y轴 第四轴（摇杆）        1

DpadX轴  第五轴（摇杆）1000

DpadY轴  第六轴（摇杆）1000

游戏键    n/a            1000

选择键    摇杆按键11   1000

开始键    摇杆按键10    1000

2.3.3 Supplied Gear VR Touchpad ControllerMappings受支持的Gear VR触摸板控制器映射

Button / Axis Name Input Manager Mapping / Axis Value Sensitivity

Mouse 0 / Button 1 mouse 0 and joystick button 0 1 000

Mouse 1 / Button 2 mouse 1 and joystick button 1 1 000

Mouse X Mouse Movement X axis 0.1

Mouse Y Mouse Movement Y axis 0.1

鼠标0/按键1  鼠标0以及摇杆按键0  1000

鼠标1/按键2  鼠标1以及摇杆按键1 1000

鼠标X    鼠标移动X轴   0.1

鼠标Y    鼠标移动Y轴    0.1

These controller and touchpad input mappings can be set up inUnity under Project Settings -> InputManager. The touchpad and the Back Button are mapped as Mouse 0 and Mouse 1, respectively. Note that anInputManager.asset file with default input settings suitable for use with the Moonlight Input Control script is included with the Oculus UnityIntegration Package.

上述控制器以及触摸板的输入映射可以再Unity里的Project>Settings>Input Manager里进行设置。特别说明，触摸板和返回键分别映射为鼠标0以及鼠标1。需要注意的是，具备默认输入设置的InputManager.asset文件适用于MoonlightInput 控制脚本，而且已经被包含在Oculus Unity整合包里。

3. Using the Oculus Mobile Unity Integration使用Oculus移动Unity整合包

The next section will walk you through setting up and buildingBlockSplosion for Android.

下面这个环节带你徜徉在如何于安卓上安装并生成BlockSplosion的情景里。

3.1 Installation安装

If you have Unity open, save your work before proceeding.

Create a new, empty project that will be used to import the Oculusassets into. From the Unity menu, select File -> New Project. Click the Browse button and selectthe folder where the Unity project will belocated.

如果你的Unity正打开着，在继续之前先保存一下目前的工作。

创建一个新的空项目来引入Oculus组件信息。

Oculus/GearVR开发者群 302294234

Make sure that the Setup defaults for: field is set to 3D.

You do not need to import any standard or pro Unity assetpackages; the Oculus Unity
Integration is fully self contained.

Click the Create button. Unity will re-open with the new project loaded.

The Oculus Unity Integration package must be imported into the newproject. Go to the Assets menu, choose ImportPackage, then Custom Package. In the file dialog, browse to the location ofBlocksplosion.unitypackage (e.g., C:\Dev\Oculus\Mobile\VrUnity\Blocksplosion). Select the file and click the Open button. The Importingpackage dialog will appear. The import process maytake a few minutes to complete.

Alternately, you can navigate to the location ofBlocksplosion.unitypackage and double-click the file.

Click Import and Unity will decompress the package contents into the projectfolder.

确保SetupDefaults for：这个选项选的是3D。

不用输入任何标准或pro Unity组件包，因为OculusUnity整合包里已经全都包含了。

点击Create按键，Unity会重新打开一个新的项目。

Oculus Unity整合包必须引入在一个新的项目工程里。点开Assets ，选择ImportPackage, 然后选择Custom Package. 在filedialog里，在浏览界面打开Blocksplosion.unitypackage的位置（比如C:\Dev\Oculus\Mobile\VrUnity\Blocksplosion）。选择文件并点击打开。Importing package dialog会出现。这个过程可能要持续几分钟。

当然，你也可以直接到文件夹里双击Blocksplosion.unitypackage来打开。

点击Import，Unity就会自动解压缩这个包并把内容引入项目文件夹。

3.2 Working with the Unity Integration开始使用整合包

Click on the project browser tab and navigate intoBlocksplosion/Scenes. Double-click on the Main.scene to loadit as the current scene. If you are prompted to save the current scene,
select Don’t save.

The BlockSplosion sample includes a Project Settings folder whichprovides default settings for a VR mobile application.You may manually copy this to your [Project]/Assets/ProjectSettingsfolder.

We will walk through setting these options, as well as a fewadditional options, below.

点击projectbrowser分页来定位到Blocksplsion/Scenes。双击Main.scene作为当前的场景。如果提示存储的话，选择Don’tsave。

BlockSplosion范例包含一个projectsettings文件夹，为VR移动应用提供了默认设置。你可以人工把它拷到你的[Project]/Assets/ProjectSettings路径下。

我们现在来设置一下那些选项，包括下文提到的一些额外的选项。

3.2.1 Configuring Build Settings调试生成设置

From the File menu, select Build Settings…. From the Build Settings menu, select Android as the platform.

从File菜单里选择BuildSettings…。从菜单中选择安卓作为平台。

Set Texture Compression to ETC2 (GLES 3.0).

设置TextureCompression为ETC2（GLES3.0）。

3.2.2 Configuring Player Settings调整玩家设置

Click the Player Settings… button and select the Android tab. Set DefaultOrientation to
Landscape Left.

点击PlayerSettings…按钮并选择安卓分页。设置默认定位为Landscape Left。

Note: The Use 24-bit Depth Buffer option appears to beignored for Android. A 24-bit window depth buffer always appears to be created.

注意： Use 24-bit DepthBuffer选项似乎会被安卓忽略。一个24位窗口深度缓冲区似乎总是会被创建。

As a minor optimization, 1 6 bit buffers, color and/or depth maybe used. Most VR scenes should be built to work with1 6 bit depth buffer resolution and 2x MSAA. If your world is mostly pre-lit to compressed textures, there will be little differencebetween 1 6 and 32 bit color buffers.

Note: You may change thecamera render texture depth buffer precision from 24 to 16 bits by modifying the value of the following variableOVRCameraController.eyeDepth.

Select the  Splash Image  section. For Mobile Splash image, choose a solid black texture.

Note: Custom Splash Screen support is not available with Unity Free. A head-tracked Unity logo screen will be provided for Unity Free in an upcoming release. While still in Player Settings, select  Other Settings and make sure both Forward Rendering and  Multithreaded Rendering* are selected as shown below:

作为最低优化手段，16位缓冲区、颜色和/或深度可能会用到。大部分VR场景都可能需要用16位深度缓冲方案和2x MSAA来生成。如果你的游戏世界里大部分都是用预处理的手段来压缩材质的话，那么用16位还是32位颜色缓冲其实没什么区别。

注意：你可以通过在变量OVRCameraController.eyeDepth里自定义值的方式来更改摄像头的渲染材质深度缓冲精度，从24位改到16位。

选择SplashImage部分。在MobileSplash image那里选择固态黑色材质（solid black texture）。

注意：在免费版Unity里不提供CustomSplash Screen 支持。在接下来的版本中我们将会提供一个头部追踪版Unity标志给免费版Unity。同样在PlayerSettings里，选择OtherSettings ，保证同时选中ForwardRendering和MultithreadedRendering 如下图所示：

Set the Stripping Level to the maximum level your app allows. It willreduce the size of the installed .apk file. Note: Thisfeature is not available for Unity Free.

Checking Optimize Mesh Data may improve rendering performance if there areunused
components in your mesh data.

将StrippingLevel设置为你的应用能允许的最大级别。这个选择会降低你的已安装的.apk文件的尺寸。需要注意的是：这个功能免费版Unity不提供:-D

如果在你的mesh文件里存在没有用到的组件的话，检查Optimize Mesh Data可以改善渲染表现。

3.2.3 Configuring Quality Settings调试质量设置

Go to the Edit menu and choose Project Settings, then QualitySettings. In the Inspector, set Vsync CounttoDon’t Sync. The TimeWarp rendering performed by the Oculus Mobile SDK already synchronizes with the display refresh.

前往Edit菜单并选择ProjectSettings，然后是QualitySettings。在Inspector窗口里，设置VsyncCount为Don’tSync。Oculus移动SDK早就把TimeWarp渲染表现和displayrefresh给同步到一起了。

Note: Antialiasing should not be enabled for the main framebuffer.

注意：在当前的帧缓冲区里不要置反锯齿选项为enabled。

You may change the camera render texture antiAliasing by changingthe value of the following parameter:OVRCameraController.eyeSamples. The current default is 2x MSAA. Be mindful of the performance implications. 2x MSAA runs at fullspeed on chip, but may still increase the number of tilesfor mobile GPUs which use variable bin sizes, so there is some performance cost. 4x MSAA runs at half speed, and is generally notfast enough unless the scene is very undemanding.

Pixel Light Count is another attribute which may significantly impact rendering performance. A model is re-rendered for each pixel light that affects it. For best performance, set Pixel Light Count to zero. In this case, vertex lighting will be used for all models depending on the
shader(s) used.

你可以通过更改OVRCameraController.eyeSamples里的参数来改变摄像头渲染材质的反锯齿部分。当前默认为2x MSAA。要注意对性能的影响。2x MSAA在芯片上会全速运行，但对于使用多种尺寸的bin的移动版GPU来说仍会增加tiles的数量，所以会造成性能的消耗。4xMSAA会半速运行，除非场景要求不高，否则大体上还是不够快。

Pixel Light Count是另一个会明显影响渲染表现的属性。对每一个pixel light来说，一个重新渲染的模型都会对它造成影响。为了追求最佳性能，我们应该将Pixel Light Count设置为0.在这个情况下，顶点光（vertex lighting）会在着色器shaders的影响下用在所有的模型上。

3.2.4 Configuring TimeSettings调试时间设置

Note: The following Time Settings advice is for applications whichhold a solid 60FPS, updating all gameand/or application logic with each frame. The following Time Settings recommendations may be detrimental for apps that don’t hold 60FPS.

Go to the Edit -> Project Settings -> Time and change both FixedTimestep and Maximum
Allowed Timestep to “0.01 66666” (i.e., 60 frames per second).

Fixed Timestep is the frame--rate-independent interval at which the physics simulation calculations are performed. In script, it is the interval at whichOnFixedUpdate()iscalled. The Maximum Allowed Timestep sets an upper bound on howlong physics calculations may
run.

注意：下列TimeSettings建议是为那些固定60FPS的应用准备的，每一帧都在updating所有游戏及/或应用的逻辑。下列TimeSettings 推荐也许会对那些不强制60FPS的应用造成麻烦。

前往Edit -> Project Settings -> Time，同时把Fixed Timestep和Maximum Allowed Timestep设置为“0.0166666”（也就是60帧每秒）。

FixedTimestep意思是物理模拟计算实现时的独立帧率间隔。在脚本里，它就是每次OnFixedUpdate（）被唤起时的间隔。而Maximum Allowed Timestep设置了一个上限来决定这个物理计算能持续多长时间。

3.2.5 Configuring theAndroid Manifest File 调试安卓清单文件

Open the AndroidManifest.xml file located underAssets/Plugins/Android/. You will need to configure yourmanifest with the necessary VR settings, as shown in the following manifest segment:

打开位于Assets/Plugins/Android/下的AndroidManifest.xml文件。你也许会需要用必要的VR设置来调试你的manifest，如下列所示的manifest段：

<applicationandroid:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen" >

<meta-dataandroid:name="com.samsung.android.vr.application.mode"android:value="vr_only"/>   

   <activity android:screenOrientation="landscape" android:configChanges="screenSize|orientation|keyboardHidden|keyboard"> </activity> </application> <activityandroid:name="com.oculusvr.vrlib.PlatformActivity" android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen"android:launchMode="singleTask" android:screenOrientation="landscape" android:configChanges="screenSize|orientation|keyboardHidden|keyboard"> </activity> <uses-sdkandroid:minSdkVersion="1 9" android:targetSdkVersion="1 9"/> <uses-featureandroid:glEsVersion="0x00030000" /> <uses-permission android:name="android.permission.CAMERA"/>

● The Android theme should be set to the solid black theme forcomfort during application transitioning: Theme.Black. NoTitleBar. Fullscreen

● The vr_only meta data tag should be added for VR mode detection.

● The required screen orientation is landscape: android: screenOrientation="landscape"

● We recommended setting your configChanges as follows: android: configChanges="screenSize|orientation| keyboardHidden| keyboard"

● The minSdkVersion and targetSdkVersion are set to the API level supported by the device. Forthe current set of devices, the API level is 1 9.

● PlatformActivity represents the Universal Menu and is activated when the user long-presses the HMT button. The Universal Menu is implemented inVrLib and simply requires the activity to beincluded in your manifest.

● CAMERA permission is needed for the pass-through camera in theUniversal Menu.

● Do not add the noHistory attribute to your manifest.

Note that submission requirements will have a few adjustments tothese settings. Please refer to the submission guidelinesavailable in our Developer Center: https://developer.oculus.com

● 安卓主题最好设置为solid black，这样在应用程序的过渡期能变得舒适一点：Theme.Black.NoTitleBar.Fullscreen

●vr_only 元数据（meta data）标签应该添加到VR模式侦测（mode detection）里。

● 需要的屏幕定位是landscape：android:screenOrientation  = “landscape”

● 我们推荐把你的configChanges设置为如下：

android: configChanges="screenSize|orientation| keyboardHidden| keyboard"

●minSdkVersion和targetSdkVersion被设置为由硬件支持的APIlevel。对于目前的硬件设置来说，API level是19。

● PlatformActivity关联到通用菜单上，而且当用户长按HMT按钮式会唤起它。通用菜单是用VrLib实现的，只要把activity加入到你的manifest里就可以了。

● 因为通用菜单里的passthrough camera的缘故，需要加入一个CAMERA 允许条件。

● 不要在你的manifest里加入noHistory属性。

要注意的是对于这些设置来说，提交需求（submission requirements）可能会有一些调整。具体情况可以参考开发者中心的提交指南文档：

Oculus/GearVR开发者群 302294234

https://developer.oculus.com

3.2.6 Running the Build运行这个Build

Now that the project is properly configured for VR, it’s time toinstall and run the application on the Androiddevice.

First, make sure the project settings from the steps above aresaved with File -> Save Project.

From the File menu, select Build Settings…. While in the Build Settings menu, add the Main.scene to Scenes in Build. Next, verify that Android is selected as your TargetPlatform and select Build andRun.If asked, specify a name and location for the .apk.

The .apk will be installed and launched on your Android device.

现在这个项目已经针对VR做了相关的调整，那么应该开始在安卓设备上安装并运行这个应用程序了。

首先，确保按照上述步骤做的设置已经在File -> SaveProject里存过了。

从File菜单里选择BuildSettings…。在BuildSettings menu里，加入Main.scene到Scenesin Build中。下一步，确认一下安卓是否是你当前的目标平台，并选择Build and Run。如果有询问框弹出来的话，为.apk设一个姓名和路径。

然后这个apk文件就应该会在你的安卓设备上安装并运行了。

4. A Detailed Look at the Unity Integration详细浏览一下unity整合包

In general, the mobile Unity SDK projects are structured as shownbelow.

The OVR folder contains the bulk of the Oculus SDK Unity integration codeand assets in the following directories:

● Editor: Contains scripts that add functionality to the Unity Editor, andenhance several C# component scripts.

● Materials: Contains materials that are used for graphical components withinthe integration, such as the Magnetometer compass and the main GUIdisplay.

● OVRImageEffects: Contains scripts and lens correction shaders for the PC and Mac OS X. For mobile, the lens correction is handled by TimeWarp.

● Prefabs: Contains the main prefabs used to provide the framework for VRinto a Unity scene: OVRCameraControllerand OVRPlayerController.

● Resources: Contains prefabs and other objects that are required andinstantiated by some OVR scripts, such as themagnetometer compass geometry, and the volume popup.

● Scripts: Contains the C# files that are used to tie the VR interface andUnity components together. Many of these scripts work together within thePrefabs. The script code interfaces to theOculus Unity plugin.

● Shaders: Contains the OVRGUIShader for GUI rendering.

● Textures: Contains image assets required by some of the script components.、

总的来说，移动UnitySDK项目的结构应该如下所示。

文件夹OVR包含了OculusSDK Unity整合包里大部分代码和组件，如下列路径所示：

● Editor:包含了可以为UnityEditor添加功能模块的脚本，而且增强了数个C#组件脚本。

● Materials:包含了整合包中图形组件会用到的材质，比如Magnetometer 罗盘以及主要GUI展示。

● OVRImageEffects: 包含了一部分脚本以及对应PC/Mac OS X的透镜纠正shader。对于移动平台，透镜纠正主要由TimeWarp负责。

● Prefabs:包含了为了将VR嵌入Unity场景而提供框架的主要预制体：OVRCameraController和OVRPlayerController。

● Resources: 包含了部分需要被OVR脚本实例化的预制体和其他对象，比如磁力罗盘几何体（magnetometercompass geometry）以及音量弹出框。

● Scripts: 包含了将VR接口和Unity组件结合起来的C#文件。许多脚本都要结合预制体一起使用。脚本代码接口在Oculus Unity插件上。

● Shaders: 包含了用于GUI渲染的OVRGUIshader。

● Textures: 包含了某些脚本组件需要用到的图片部件。

The Moonlight folder contains some utility classes that exist in the mobileversion of the Oculus Unity SDK. In futurereleases of the SDK these files may be integrated into the OVR folder.

Moonlight文件夹包含了一些比较实用的、存在于Oculus Unity SDK的移动版里的类。在新的SDK版本中这些文件也许会整合进OVR文件夹。

The Plugins folder contains the DLLs that interface to Oculus LibOVR andnative Android code. The native code talksto the hardware to collect and manage sensor data from the Gear VR and also implements the Timewarp functionality. If the Pluginsfolder is not present directly under the Assets folder,Unity will not find the Oculus plugin and nothing will render.

Plugins文件夹包含了对应Oculus LibOVR接口的DLL文件，还有一些原生的安卓代码。原生代码直接与硬件对话来收集和管理从Gear VR带来的传感器数据，同时实现Timewarp功能。如果Plugins文件夹没有直接处于Assets文件夹下，那么Unity找不到Oculus 插件，也就不会进行渲染了。

The BlockSplosion folder contains all non-OVR scripts and assets specific to thisparticular project.

BlockSplosion文件夹包含了所有具体到这个项目的非OVR脚本和部件。

Note: We strongly recommend that developers do not directly modifythe included OVR scripts.

注意：我们强烈建议开发者们不要直接修改包含在里面的OVR脚本。

5.Oculus Mobile Unity Examples移动Unity实例

Included with the Mobile SDK is an SDK Examples project whichdemonstrates useful scenarios and functionality.

Open the SDK Examples project in Unity by selecting File -> OpenProject. Click Open Other… and choose the SDKExamplesprojectfolder located in your SDK install location. Click Open.

You will find the following sample scenes located inAssets/Scenes:

移动SDK里有一个SDK实例，可以证明许多有用的场景和功能。

打开SDK实例项目。File -> Open Project>Open Other…选择在你的SDK安装路径下的SDKExamples项目文件夹，点击打开。

你会找到下列位于Assets/Scenes下的实例场景：

● 30Hz_Sample - An example of how to set the TimeWarp vsync rate to support 30Hz apps, as well as how to enable Chromatic Aberration Correction andMonoscopic Rendering for Android. Formore information on 30Hz TimeWarp and Chromatic AberrationCorrection for Android, please review the TimeWarp Technical Note.

● Box_Room - A simple box room for testing.

● Crosshair_Sample - An example of how to use a 3D cursor in the world with three different modes.

● FirstPerson_Sample - An example of how to attach avatar geometry tothe OVRPlayerController.

● GlobalMenu_Sample - An example demonstrating Back Key long-press action and the Universal Menu. Additionally demonstrates a gaze cursor withtrail. For more 16 information onInterface Guidelines and requirements, please review the following documents: Interface Guidelines and UniversalMenu.

● Menu_Sample - An example demonstrating a simple in-game menu activated by Back Key short-press action. The menu also uses the Battery Level APIfor displaying the current battery level andtemperature.

● MoviePlayer_Sample - An example demonstrating basic in-game videousing Android MediaPlayer.

● SaveState_Sample - An example demonstrating saving the state of the game on pause and loading it on resume. Click on the objects in the sceneto change their color. When you run the sceneagain, the objects should be in the color you had selected beforeexiting.

● Startup_Sample - An example of a quick, comfortable VR app loading experience utilizing a black splash screen, VR enabled logo scene, and anasync main level load. For more information oninterface guidelines, please review the following documents: Interface Guidelines and UniversalMenu.

The example scripts are located in Assets/Moonlight/:

● Crosshair3D.cs - Detailed code for how to create judder-free crosshairs tied tothe camera view.

● StartupSample.cs - Example code for loading a minimal-scene on startup while loading the main scene in the background.

● TimeWarp30HzSample.cs - Example code for setting up TimeWarp tosupport 30Hz apps as well as togglingChromatic Aberration Correction and Monoscopic Rendering on and off.

● HomeMenu.cs - Example code for an animated menu.

● HomeButton.cs - Example code which provides button commands (used in conjunction with HomeMenu.cs).

● HomeBattery.cs - Example code for using the SDK Battery Level API and interactively modifying a visual indicator.

● MoviePlayerSample.cs - Example code and documentation for how to playan in-game video on a textured quad using Android MediaPlayer.

● OVRChromaticAberration.cs - Drop-in component fortoggling chromatic aberration correction on and off forAndroid.

● OVRDebugGraph.cs - Drop-in component for toggling the TimeWarp debug graph on and off. Information regarding the TimeWarp Debug Graph may befound here: TimeWarp.

● OVRModeParms.cs - Example code for de-clocking your application to reduce power and thermal load as well as how to query the current power levelstate.

● OVRMonoscopic.cs - Drop-in component for toggling Monoscopic rendering on and off for Android.

● OVRResetOrientation.cs - Drop-in component for resetting the cameraorientation.

● OVRScreenFade.cs - Drop-in component for issuing screen fades on level loads.

● OVRWaitCursor.cs - Helper component for auto-rotating a wait cursor.

● OVRPlatformMenu.cs - Helper component for detecting Back Key long-pressto bring-up the Universal Menu and Back Key short-press to bring upthe Confirm-Quit to Home Menu. Additionallyimplements a Wait Timer for displaying Long Press Time. For moreinformation on interface guidelines and requirements, please review the following documents: Interface Guidelines and UniversalMenu.

● 30Hz_Sample 一个用来展示如何设置TimeWarpvsync比率来支持30Hz的app，以及展示怎样启用安卓下的色差校正和单屏显示。相关信息可以参照TimeWarp的技术指南。

● Box_Room - 一个简单的盒子空间用来测试。

● Crosshair_Sample -一个展示如何用三种不同的模式在一个游戏世界里使用3D光标。

● FirstPerson_Sample -一个实例示范怎样将一个avatar geometry绑定到OVRPlayerController上面。

● GlobalMenu_Sample -展示返回键长按来弹出通用菜单的过程。另外还展现了一个带有拖曳尾迹的注视光标。更多信息参阅文档Interface Guidelines 和 Universal Menu。

● Menu_Sample - 展示返回键短按触发游戏内菜单的过程。这个菜单同样调用了Battery Level的API，并且可以展示当前的电池余量以及设备温度。

● MoviePlayer_Sample -展示如何利用安卓媒体播放器来在游戏内播放视频。

● SaveState_Sample -展示如何暂停并存储游戏状态，并在之后回到游戏。点击游戏中的对象来更改其颜色。当你再次回到场景的时候，对象会处于你在退出之前选择的颜色上。

● Startup_Sample -展示一个快速的、令人感到舒适的VR应用读取体验，利用了黑色版权页（splash screen），VR启用的图标页，以及一个异步的主要关卡负载（main level load）。更多关于接口指南的信息，请参阅Interface Guidelines 和 Universal Menu。

实例的脚本位于Assets/Moonlight/下。

● Crosshair3D.cs -关于如何创建一个防抖动的与摄像头视角绑定的十字瞄准线的详细代码部分。

● StartupSample.cs -当后台在读取主要场景时，怎样在启动环节读取一个最小的次场景的实例代码。

● TimeWarp30HzSample.cs 一段实例代码，内容是通过-设置TimeWarp来支持30Hz的应用的同时切换色差校正以及单屏渲染的开关。

● HomeMenu.cs - 一段动画化的菜单的代码。

● HomeButton.cs -供按键指令的代码（主要用在结合HomeMenu.cs上）

● HomeBattery.cs -展示如何通过代码使用SDK电池水平API以及交互自定义一个视觉指示器（visualindicator）。

● MoviePlayerSample.cs - 本段实例代码以及文档展示如果利用安卓的MediaPlayer来在一块材质化过的quad上播放一段游戏内视频。

● OVRChromaticAberration.cs -用于在安卓上切换色差校正开关的组件。

● OVRDebugGraph.cs - 一个切换TimeWarp的debug图开关的Drop--in组件。更多相关信息参阅 TimeWarp.

● OVRModeParms.cs - declocking你的应用来降低电量消耗和热负荷，同时查询当前的电量。

● OVRMonoscopic.cs -为安卓切换单屏渲染开关的Drop-in组件。

● OVRResetOrientation.cs -重置摄像头定位的Drop-in组件。

● OVRScreenFade.cs -在关卡负载（levelloads）上发布屏幕渐变的Drop-in组件。

● OVRWaitCursor.cs -自动旋转待机光标的辅助组件。

● OVRPlatformMenu.cs - 一个侦测返回键长按/短按的辅助组件，长按触发通用菜单，短按触发确认退出对话框。另外还实现一个待机Timer来展示长按时间（LongPress Time）。更多信息参阅Interface Guidelines andUniversal Menu

6. DK2 Compatibility 兼容性

While this revision of the mobile UnitySDK fully supports the DK1 , the DK2 does have some support.

In order to use the DK2 with this SDK, youwill need to do the following:

- Open the Oculus Config Utility

- Go to Tools -> Service and select Pause.

The Service needs to be paused in order for head-tracking to work,otherwise the Service will grab the sensor full-time.

移动UnitySDK的修改版完全支持DK1，同时也在一定程度上支持DK2。

为了能把这个SDK用在DK2上，你可能需要如下做些调整：

打开OculusConfig Utility（Oculus配置实用工具）

点Tools>Service，选择Pause。

这个Service需要暂停才能让头部追踪展开工作，否则它会全程抓着光标不放。

7. Known Issues已知的问题

The following section outlines some currently known issues withUnity and Android that will either be fixed in laterreleases of Unity or the Mobile Unity Integration Package.

NGUI with Multi-threaded Rendering

When multithreaded rendering is enabled, NGUI geometry appears stretched/distortedand may flicker.

This issue has been fixed in Unity 4.5.3.f3.

Random Crashes with Dynamic Batching Enabled

This issue has been fixed in Unity 4.5.5.p1 .

DK1 HMDs do not display correctly or have double vision

This has been known to occur at certain resolutions when mirroringa display and while the current platform is set to Android.

Switch the platform back to PC, Mac and LinuxStandalone if you are testing with a DK1 HMD.

Mac OS X Game View Render

The rendered game view in the editor currently draws over the topof the Scene and Game tabs.

The issue has been reported to Unity.

Flipped Rendering in Editor with UseCameraTexture set to false

The rendered game view in the editor renders flipped when Use CameraTexture on the camera controller is set to false and Android is selected as thetarget platform. This only occurs when using the PCeditor.

OnGui Calls Fail to Render

The drawing of the screen edge vignettes and flushing of commandswith the camera occurs in OnPostRender. Ifany other post rendering happens after this, at a minimum performance will be badly affected due to a double buffer flush/resolve, butgenerally is not expected to work at all.

It may be possible to interject the post effect rendering usingthe OnCustomPostRenderEventHandler in OVRCamera.cs. OVRScreenFade usesthis approach.

There is no workaround at this time.

GLES 3.0 Instability

When Force GL ES 3.0 is enabled, the app will crash when runningon device.

A fix for this issue is expected in Unity 4.6.1 .p1 .

Android Ion Memory Leak

When pausing and resuming the app, memory buffers are orphaned inion memory.

A fix for this issue is expected in Unity 4.6.1 .p1 .

下列概述是目前已知的与Unity和安卓有关的问题，应该会在最新的Unity版本或者移动Unity整合包里解决。

NGUI与多线程渲染

当多线程渲染开启的时候，NGUI几何图形会出现拉伸/扭曲或者不停闪烁。

在Unity4.5.3.f3里被修复。

动态批处理开启时随机崩溃

在Unity4.5.5.p1里修复。

DK1的HMD无法正确显示或者有两个视像。

已知会在当前平台设置为安卓，且在某个特定分辨率下镜像展示时出现这个问题。

如果你是在用DK1HMD测试的话，把平台改回PC,Mac and Linux Standalong。

MacOS X游戏视图渲染

在当前编辑器中渲染过的游戏视图会绘制在Scene和Game分页的上方。

这个问题已经上报Unity。

当把UseCameraTexture设置为false时编辑器中的渲染会翻转过来

目标平台为安卓，且camera controller里面的Use Camera Texture被设置为false时编辑器中的渲染过的游戏界面会翻转。只有在使用PC编辑器时才会出现。

GLES3.0 不稳定

当ForceGLES 3.0启用时，app在硬件上运行时会崩溃。

Unity4.6.1.p1应该会修复这个问题。

安卓Ion 内存溢出

当暂停和回到app时，在ion内存区的内存缓冲会被孤立。

Unity4.6.1.p1会修复这个问题。

8. Troubleshooting故障排除

Game scene is missing or just renders the background color whenpressing Play in Unity.

Check the [Project Path]/Assets/Plugins/ folder and make sure thatthe Oculus plugins have not moved. See the Unityconsole for additional information.

After importing the latest Oculus Unity Integration package, yourgame is generating exceptions.

It is possible there were changes made to the OVR framework thatrequire you to update your camera prefabs. The easiestway to do this is to compare the changes between the Camera Controller preb you were using (OVRCameraController or OVRPlayerController) and the new one and compare changes.

After importing the latest Oculus Unity Integration package yourexisting OVRPlayerControllertransform is changed.

It is possible there were changes made to the OVR framework thatmay cause the OVRPlayerController transform to beswapped with the child OVRCameraController transform. Swapping the values back should fix the issue.

After importing the latest Oculus Unity Integration package therendering is corrupted. We require the orientation tobe landscape. Check that your defaultOrientation in Player Settings is set to Landscape Left.

After importing the latest Oculus Unity Integration package theapp does not launch as a VR app.

Ensure you have administrator rights to the system you areinstalling the integration to.

Issues with updating to the latest Oculus Unity Integration withTeam Licensing and Perforce Integrationenabled.

If you have Team Licensing and Perforce Integration enabled, youmay need to check out the OVR and Plugins foldersmanually before importing the updated unity package.

Building Application for Android may fail with Zipalign Error.

If you have build failures with the following error aboutzipalign:

Error building Player: Win32Exception:

ApplicationName='D:/Android/sdk\tools\zipalign.exe', CommandLine='4 "C:\Users\Username\Documents\New Unity Project 1\Temp/StagingArea/Package_unaligned.apk" "C:\Users\Username\Documents\New Unity Project 1\Temp/StagingArea/Package.apk"', CurrentDirectory='Temp/StagingArea'

This can be fixed by copying the zipalign.exe from the API level you’re building for into the sdk\tools directory. To find this, look in the build-tools directory in your SDK installation, in the folder for the API level you’re building for. For example, if you’re targeting APIlevel 19, the directory is sdk\build-tools\19.1.0. Copy zipalign.exe into sdk\tools and try building yourproject again.

在按下play之后游戏画面缺失或者只渲染了背景色

检查[项目路径 /Assets/Plugins/folder，确认Oculus插件没有被移动，看一下console以查阅更多信息。

引入最新的Oculus unity整合包之后，游戏发生了异常

有可能是OVR框架发生了变化，需要升级摄像头预制体。最佳解决方案就是对比现在正在使用的摄像头预制体和最新的预制体之间有什么不同（OVRCameraController或者OVRPlayerController）。

引入最新的Oculus Unity整合包之后，已有的OVRPlayerController变换矩阵发生了改变

OVR框架是有可能发生这种情况，一般会引起OVRPlayerController的transform和子OVRPlayerController的transform发生了交换，换回来应该能解决这个问题。

引入最新的整合包之后渲染被中断了

我们需要定位来进行landscape。在PlayerSetting里面把DefaultOrientation设置为landscapeleft。

引入最新的整合包之后，app没有作为一个VR app来运行

确保你在安装整合包的系统中有管理员权限。

生成安卓app的时候因为Zipalign错误而失败

如果你在生成的时候发生了错误，日志如下：

Error building Player: Win32Exception:

ApplicationName='D:/Android/sdk\tools\zipalign.exe', CommandLine='4 "C:\Users\Username\Documents\New Unity Project 1\Temp/StagingArea/Package_unaligned.apk" "C:\Users\Username\Documents\New Unity Project 1\Temp/StagingArea/Package.apk"', CurrentDirectory='Temp/StagingArea'

把zipalign.exe从你生成的APIlevel复制到sdk\tools目录下。在SDK安装包的生成路径下找一找，就在你生成的API level文件夹下。举个例子，如果你的目标API level是19，那么路径就是sdk\build-tools\19.1.0。把zipalign.exe复制到sdk\tools下面，重新在生成一遍试试。