快速开始

本文介绍如何安装 Kmax XR Core，并为现有 Unity 场景配置立体显示和空间交互。以下说明以 2.7.2 为基准；界面截图可能来自较早版本，菜单名称以正文为准。

安装 SDK

以下三种方式任选其一。同一项目不要重复导入同一个包。

通过 Scoped Registry 安装

在 Edit > Project Settings > Package Manager 中添加注册表：

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

添加 Kmax 包注册表

打开 Window > Package Manager，切换到 My Registries，选择 Kmax XR Core 并点击 Install。注册表便于查看和选择已发布版本，不会自动将项目升级到最新版本。

安装 Kmax XR Core

也可以将下列配置合并到 Packages/manifest.json。保留项目原有的注册表和依赖；示例中的 2.7.2 是本文档对应版本，安装时应确认注册表中已提供该版本。

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

通过 Git URL 安装

打开 Window > Package Manager。
点击 + > Add package from git URL。
输入以下地址并安装：

https://github.com/kmaxsdk/com.kmax.xr.core.git

该地址使用仓库默认分支。需要固定版本时，在 URL 后追加 # 和已确认存在的标签或提交哈希。Git 安装的更新由开发者主动管理。

从本地磁盘安装

将 SDK 包解压到固定目录，或使用已有的包源码目录。
打开 Window > Package Manager，点击 + > Add package from disk。
选择 com.kmax.xr.core 目录中的 package.json。

本地安装会引用该目录，后续不要随意移动或删除它。

从磁盘安装包

配置目标平台

面向 M1 的 Android 项目，沿用设备接入配置：最低 API 级别为 26，脚本后端为 IL2CPP，目标架构按设备选择 ARMv7/ARM64，图形接口使用 OpenGLES3。不要将 Vulkan 作为未经验证的替代接口。

Android 脚本后端与目标架构

Android 图形接口

Windows/Linux 项目不需要上述 Android 设置。WebGL 的发布与显示模式切换见发布到 WebGL。

配置场景

1. 添加 XRRig

禁用或移除原有的主相机，避免重复渲染。在 Hierarchy 中右键选择 Kmax > Add XRRig。需要独立修改预制体内容时，可选择 Add XRRig Unpacked。

添加 XRRig

XRRig 预制体包含立体相机、眼部追踪和触笔相关组件。配置完成后，应检查场景中没有重复的 XRRig。

2. 配置输入模块

场景需要一个 EventSystem。选中该对象，右键选择 Kmax > Convert to KmaxInputModule。此菜单会移除对象上原有的输入模块，并根据当前输入系统配置添加对应的 Kmax 模块：

Active Input Handling	使用的模块
Input Manager (Old)	`KmaxInputModule`
Input System Package (New)	安装并启用 Input System 后使用 `KmaxInputSystemUIInputModule`。
Both	自动转换优先选择可用的 `KmaxInputSystemUIInputModule`；也可显式选择 Legacy 模块。

转换前记录原输入模块的自定义参数和 Actions 绑定，转换后重新检查。详细步骤见输入系统。

3. 配置 UI 画布

选中 Canvas，右键选择 Kmax > Fix Canvas。此操作将画布设为 World Space，添加 KmaxUIRaycaster 和 UIScaler，并使画布尺寸与姿态适配虚拟屏幕。

世界空间画布配置

检查 Canvas 的 Event Camera，将其指定为 XRRig 中立体相机的中心相机。Fix Canvas 不会自动填写该引用。运行时也可以通过 XRRig.MainCamera 获取中心相机。

UIScaler.SyncAlways 默认开启，会持续同步画布与虚拟屏幕的姿态和尺寸。如果需要将画布固定在场景中的其他位置，应根据布局需求关闭同步并自行设置位置。

4. 配置物体拖拽

为需要拖拽的物体添加 Collider 和 StylusDragable。同时检查物体所在层是否包含在触笔的射线检测层中。

物体拖拽组件

运行与验证

进入 Play 模式，检查 Console 中是否有错误，并验证鼠标、触笔和目标设备支持的触摸输入。

普通 PC 上通常以单目画面开发。选中 XRRig，点击 Switch to Side By Side 可检查左右眼画面；这不等同于设备已经开启硬件立体显示。在支持的设备上预览立体效果，参见编辑器立体预览。M1 的输入调试还可使用远程调试。

Table of Contents