Table of Contents

快速开始

本文档将指导你如何在一个新的或现有的Unity项目中集成 Kmax XR SDK。

导入SDK

SDK 主要通过 Unity Package Manager 导入。并支持以下三种方式：

  • 通过 Scoped Registry 导入
  • 通过 Git URL 导入
  • 通过本地磁盘导入
Tip

开发者可以根据自己的需求和习惯在以上三种方式中任选一种即可。
推荐使用通过 Scoped Registry 导入的方式，因为这种方式可以确保你总是使用最新版本的SDK。

通过 Scoped Registry 导入(推荐)

使用 Scoped Registry 无需手动下载 SDK 包。你只需要在 Unity 中按照如下步骤操作即可。

通过 Unity Project Settings 添加 Kmax Registry 源：

{
  "name": "kmaxxr",
  "url": "https://registry.npmjs.com",
  "scopes": [
    "com.kmax"
  ]
}

pkg-registry

然后在 Package Manager 中切换到 My Registries 并选择 Kmax XR Core 并点击 Install 按钮：

pkg-install

或者 直接修改 manifest 文件(Packages/manifest.json)：

{
  "scopedRegistries": [
    {
      "name": "kmaxxr",
      "url": "https://registry.npmjs.com",
      "scopes": [
        "com.kmax"
      ]
    }
  ],
  "dependencies": {
    "com.kmax.xr.cor": "2.5.0",
    ...
  }
}

通过Git URL导入

按照以下步骤通过Git URL导入SDK：

  • 打开目标unity工程
  • 打开package manager
  • 点击左上角+，选择from git URL
  • 在弹出的对话框中输入以下URL：
https://github.com/kmaxsdk/com.kmax.xr.core.git
Tip

这种方法的缺点是无法及时感知 SDK 的更新。

通过本地磁盘导入

假设你已经下载好了SDK包，你可以按照以下步骤导入SDK。

Tip

如果你还没有SDK，你可以从这里下载最新版本的SDK。
这种方法同样无法及时感知 SDK 的更新。

  • 将下载的zip文件解压到一个你认为合适的地方，但不是你的工程内。
  • 打开目标unity工程
  • 打开package manager
  • 点击左上角+，选择from disk
  • 选择刚才解压的目录中的package.json文件

package manager

成功后你的package manager中应该已经包含了我们的SDK。

package manager

项目配置

SDK 导入完成后，你需要对项目进行一些配置以确保 SDK 能够正常工作。

1. PlayerSettings配置

如果你的目标设备是 Kmax M1 (即目标平台是安卓)，请按照以下步骤配置：

Tip

如果你的目标设备是 Kmax K1系列或 G系列 (即目标平台是 Windows / Linux)，你可以跳过这一步。

  • 打开 Player Setting，选择 Other Settings
  • 最低安卓API版本使用 API level 26 或更高
  • Scripting Backend 使用 IL2CPP
  • Target Architectures 勾选 ARMv7 和 ARM64
    playersetting-0
  • Graphic API 优先 OpenGLES3 (我们还不支持Vulkan，你可以移除它或者像下图一样将它放在OpenGLES3的下面)
    playersetting-1

2. 在现有项目上稍加修改

修改主要包含两部分：

  • 替换传统相机为支持立体渲染的相机
  • 替换常规输入模块为支持空间交互的输入模块

修改相机

  • 删除或隐藏原有的相机；
  • 在 Hierarchy 面板通过右键菜单 Kmax -> Add XRRig / Add XRRig Unpacked 将 XRRig 加入场景，替代原有相机。 xrrig

修改输入模块

在 Hierarchy 面板选择原有的 EventSystem，通过右键菜单 Kmax -> Convert to KmaxInputModule 使用 KmaxInputModule 替代默认的InputModule(如：StandaloneInputModule)

效果如下:
eventsystem

Tip

你也可以手动删除原有的InputModule组件，然后在EventSystem物体上添加KmaxInputModule组件。效果是一样的。

此时你的场景已经具备了支持 Kmax XR 必备的元素，包含了眼镜和笔的追踪，以及3D立体显示，基于笔的空间交互支持。
实际上SDK集成了鼠标、射线笔、触摸三种事件检测，它是基于Unity Event System的。

Warning

需要注意如果你项目已经有了除StandaloneInputModule外的其他InputModule组件也需要移除，我们不能保证KmaxInputModule与其他组件的兼容性。

UI

调整现有的 UI 画布以适应XR环境：
在 Hierarchy 面板选择你的 Canvas 画布，通过右键菜单 Kmax -> Fix Canvas 将其转换为适用于 XR 的 UI 画布。

效果如下:
canvas01

对于场景中的画布，它的渲染模式必须是world space，它的 EventCamera 需要指定为 XRRig 下的主相机。满足以上条件才能确保 UI 画布在 XR 环境下正常显示和交互。

Warning

需要注意的是，你的UICanvas需要跟 XRRig 的物体位置一致，这样才能保证UI画面不会由于眼镜跟随而发生偏移。

运行测试

通常我们都是在PC上进行项目开发，最终发布到设备上验证实际的效果。
这个过程有许多不便之处，我们已经推出类似unity remote的远程调试功能，详情请看这里。

Tip

运行场景默认显示为单眼画面，但实际上立体显示是需要双眼画面的。如果你需要确认双眼画面，可以选中xrrig在Inspector面板中点击Switch to Side By Side切换为左右格式。

其他

如果需要支持拖拽物体，我们在SDK中内置了StylusDragable.cs脚本，只需要将该脚本挂载在需要拖拽的物体上即可（该物体需要包含Collider否则射线检测将无法生效）。

dragable