开发者中心

# 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/Pimax Portal

# 软件要求

  • Windows/Mac操作系统(推荐64位)
  • Unity编辑器 2019.3版本或更高

# 安装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. 搜索PvrManager脚本双击添加，PvrXRManager脚本控制部分SDK功能的开关与设置。

# 添加手柄模型

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

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

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

  3. 对RightHand Controller进行同样的操作，这次使用名为Auto_controller_right的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包含一些本指南没提到的功能，你可以浏览代码和示例来查看这些功能的用法。

← Unity PC XR SDK →