# Unity一体机XR SDK

# 简介

Pimax Unity XR SDK是Pimax为Unity开发者准备的一体机开发工具包,提供了一系列XR功能包括渲染,输入,追踪等。使用本SDK,你可以轻松的构建在Pimax一体机头显上运行的XR应用。

# 快速开始

# 概览

本指南介绍了如何使用Pimax Unity XR SDK搭建基于Unity XR的简单场景并构建成可在Pimax VR一体机上运行的XR应用。

对于新手开发者,建议在开始前先浏览Unity XR文档 (opens new window)以获取必要的基础知识,然后顺序阅读本指南各部分,一步步地开发你的第一个XR应用。

如果是有经验的开发者,也可以单独浏览一部分用作参考。

本指南包含以下部分:

  • 配置开发环境
  • 导入Pimax Unity XR SDK
  • 配置自定义设置
  • 搭建XR场景
  • 打包应用程序

# Pimax平台SDK

如果想要将你的游戏发布到Pimax商店,你需要集成Pimax平台SDK。

你可以在下载页面获取最新的平台SDK,然后参照平台SDK文档将它集成到游戏。

# 配置开发环境

此部分介绍在开始进行PimaxXR应用开发之前,你需要做的准备,包括软硬件要求,安装与设置等。

# 硬件要求

  • Pimax Crystal

# 软件要求

  • Windows/Mac操作系统(推荐64位)
  • Unity编辑器

# 安装Unity编辑器

Pimax XR应用最低支持在Unity编辑器2019.4LTS版本上开发,我们推荐使用2020.3LTS或更高的版本。

下面简单地介绍了Unity安装步骤,需要更多详细信息请参阅Unity安装文档 (opens new window)

  1. 下载Unity Hub,然后进行安装。

  2. 切换到"Install"选项卡,点击"Install Editor"。

  3. 选择你需要的编辑器版本,点击安装。

  4. 为构建Android平台应用,必须安装Android Build Support 模块和三个Android开发工具包:SDK,NDK,JDK。在"Add Module"窗口的"PLATFORM"部分,勾选上Android Build Support,Android SDK & NDK Tools和OpenJDK。

  5. 点击安装,等待安装完成。

如果你已经安装了Unity却没有安装Android Build Support 模块,你随时可以在Unity Hub添加此模块,在"安装"选项卡中选择想要添加的Unity版本,点击旁边的齿轮图标,然后点击"添加模块",勾选上Android Build Support,Android SDK & NDK Tools和OpenJDK后点击安装即可。

# 创建新项目

  1. 打开Unity Hub。
  2. 在"Project"选项卡中,点击"New Project",选择你想使用的编辑器版本。
  3. 选择"3D core"模板,输入项目名称和路径,点击"Create Project"。

# Android开发环境配置

在开始之前,你需要一条USB数据线连接连接头显,并通过adb工具与设备进行通信,你可以访问[Andorid开发者网站]获取更多相关信息。

# 导入Pimax Unity XR SDK

Pimax Unity XR SDK是一个标准upm包,关于这一点,可以参考Unity Package Manager 文档 (opens new window)

通过以下步骤将Pimax Unity XR SDK包导入你的项目:

  1. 下载页面获取最新的Pimax Unity XR SDK。

  2. 打开你想要导入Pimax Unity XR SDK的Unity项目,点击顶部工具栏的"Window"-"Package Manager",打开Unity包管理器。

  3. 点击包管理器左上角的加号图标,选择"Add a package from the disk"。

  4. 在弹出的对话框中选择Pimax Unity XR SDK包文件夹中的package.json文件。

  5. 弹出的对话框中依次选择No,No Thanks。

  6. 等待导入完成,完成后即可关闭Package Manager窗口,之后你可以在"项目"窗口的Package路径下找到sdk包。

# 配置自定义设置

# 设置目标平台

在进行其他设置前,务必将Unity项目切换到正确的目标平台,因为对于每个平台Unity都有独特的设置。

要为Ppimax一体机开发应用,你需要将目标平台设为安卓,最终生成的程序包会包含APK文件和APK扩展文件(OBB)(如果已启用)。

  1. 点击顶部工具栏上的"File"-"Build Settings"。

  2. 在"Platform"一栏选择"Android"。

  3. 点击右下角的"Switch Platform"。

# 启用XR

为了支持应用的XR功能,需要启用Unity的XR模块并为想要运行的头显选择对应插件。

  1. 点击顶部工具栏上的"Edit"-"Project Settings"。

  2. 在"Project Settings"窗口中,选择"XR Plug-in Management"选项卡。

  3. 在窗口右方安卓平台选项卡中勾选PimaxXR。

  4. 切换到"XR Plug-in Management"选项卡下方的"PimaxXR"选项卡,这里包含一部分重要的全局XR设置,可根据需要勾选。

# 设置通用标识信息

  1. 打开"Project Settings"中的"Player"选项卡。
  2. 修改窗口上方的"Company Name"和"Product Name"。这里的信息为多平台共用,通常会显示在应用窗口的标题栏和用于安卓应用名称。
  3. 修改"Version",确保每次发布时版本号比上一次大。

# 图像API设置

  1. 打开下方安卓平台选项卡中的"Other Settings"部分,取消勾选"Auto Graphics API"。

  2. 在"Graphics APIs"列表中选择其他选项并点击右下角减号按钮将其删去。

    只保留"OpenGLES3"一项。

  3. 确保颜色空间为"Gamma"。

# 安卓设置

每个安卓应用都必须包含AndroidManifest.xml文件,它包含应用运行需要的重要信息,包括权限,软硬件支持,元数据,安卓版本支持等。

安卓一般使用包名来识别应用,每个应用都拥有唯一的包名,一旦应用发布,请尽量避免对包名作任何改动。

  1. 打开下方安卓平台选项卡中的"Other Settings"部分,找到"Identification",检查是否有"Override Default Package Name"选项。

  2. 如果有"Override Default Package Name",则你可以选择是否勾选,如果不勾选此选项,Unity会按照"com.公司名称.产品名称"的方式生成默认包名。

  3. 如果没有"Override Default Package Name"选项,或者你选择勾选此项,则你需要手动指定包名,一般也推荐使用"com.公司名称.产品名称"的方式指定包名。

  4. 在"Identification"中,将"minimum API level"设置为"Android 8.0 'Oreo' (API level 26)"。"Target API level"设置为"Automatic (Highest installed)"。

默认情况下Unity引擎会自动生成AndroidManifest.xml文件并打包到APK中,如果需要自定义AndroidManifest.xml文件,请向Application项中添加

<meta-data android:name="com.pimax.vr.application.mode" android:value="VR" />

标签。

# 搭建XR场景

此部分可以帮助你搭建你的第一个XR场景,包含基本的摄像机与手柄。

# 添加XR Origin

  1. 点击"Hierarchy"窗口左上角的加号图标,选择"XR"-"Device-based"-"XR Origin"。将XR Origin添加至当前场景

  2. XR Origin层级结构如下:

  3. 选中XR Origin,点击点Inspector窗口底部的Add Component按钮。

  4. 搜索PvrXRManager脚本双击添加,PvrXRManager脚本控制部分SDK功能的开关与设置。

  5. 由于现版本SDK对Unity新版输入系统InputSystem支持不完善,使用时请注意避免使用InputAction及基于InputAction的组件。

# 添加手柄模型

SDK中包含了Pimax手柄的3d模型供你使用,你也可以添加自己独特的模型,比如法杖,弓箭,枪械等,从而配合游戏风格。

  1. 选择XR Origin里包含的LeftHand Controller,在Inspector中找到XR Controller(Device-based)组件。

  2. 在Project窗口Package-Pimax XR Plugin-Resources-Prefab路径找到名为C1_handle_L的Prefab,将其拖入第一步中找到的XR Controller组件的Model Prefab属性上。

  3. 对RightHand Controller进行同样的操作,这次使用名为C1_handle_R的Prefab。

# 构建和调试应用

将XR场景编译打包为apk文件,安装到Pimax一体机上并运行。

  1. 使用USB数据线连接Pimax一体机和PC。
  2. 在上方工具栏点击File-Build Settings。
  3. 在打开的Build Settings窗口中,点击Add Open Scene按钮将现在打开的场景添加到场景列表中。
  4. 场景列表中的0号场景为打开游戏时的默认场景。
  5. 在Run Device一项设置为当前连接的Pimax一体机的型号。
  6. 点击Build And Run。
  7. 在弹出的对话框中选择APK的储存位置。

# 输入

此部分文档介绍如何在XR应用中使用Pimax手柄,包括追踪,摇杆,按键等功能。

你可以使用Unity XR Input系统获取手柄状态,也可以使用Unity XR Interaction Toolkit。

# Unity XR Input

Unity XR Input 提供跨平台的输入方案,你可以浏览XR Input文档 (opens new window)获取更多信息。

Pimax手柄按键映射:

按键 输入事件
Menu CommonUsages.menuButton
Trigger CommonUsages.TriggerButton
Grip CommonUsages.GripButton
Joystick按下 CommonUsages.primary2DAxisClick
X/A CommonUsages.primaryButton
Y/B CommonUsages.secondaryButton
输入事件
Trigger CommonUsages.Trigger
Grip CommonUsages.Grip
Joystick CommonUsages.primary2DAxis

# Unity XR Interaction Toolkit

Unity XR Interaction Toolkit是一个是一个基于组件的高级交互系统,你可以利用它轻松的创建各种交互。

你可以浏览Unity XR Interaction Toolkit文档 (opens new window)获取更多信息。

# 探索更多

SDK包含一些本指南没提到的功能,你可以浏览代码和示例来查看这些功能的用法。