hz-unity-device-readiness

设备就绪度

背景

此技能会从两个方面为 Unity 项目做好适配 Meta VR Glasses 设备要求的准备：输入（以手部追踪作为主要输入方式，而非备用方式）和视野（设备视野范围比当前 Quest 头显更窄）。输入工作流紧接在下方；视野工作流则单独列在后面的章节中。

目标设备将手部追踪视为主要输入方式，而非备用方式。大多数现有 Quest 项目都是优先为控制器打造的，因此这项工作不只是“将按钮按压替换为手势”，还要重新思考交互设计，让手部操作感觉自然，而不是像更糟糕的控制器。进行系统性扫描很重要：找出每一处对控制器的依赖，了解其背后的游戏设计意图，并将其映射到合适的 ISDK 模式。

连接 Meta VR Glasses 或 Meta Quest 设备时，应先基于实际设备数据开展审查：metavr device list 会显示已连接的设备，metavr device info <id> 会报告审查应针对的设备输入和显示能力。

分析工作流

步骤 1：扫描项目

全面了解项目当前如何处理输入。对控制器的依赖可能藏在意想不到的地方——不仅有显而易见的 OVRInput.Get() 调用，还有 XR Interaction Toolkit 组件、Unity 的旧版 Input 系统，以及自定义抓取系统。请广泛搜索：

# Find controller input usage
grep -r "OVRInput\.\(Get\|GetDown\|GetUp\)" --include="*.cs" .
grep -r "OVRInput\.Button\|OVRInput\.Axis" --include="*.cs" .

# Find XR Interaction Toolkit usage
grep -r "XRGrabInteractable\|XRRayInteractor\|XRDirectInteractor" --include="*.cs" .

# Find legacy Input system usage
grep -r "Input\.GetButton\|Input\.GetAxis\|Input\.GetKey" --include="*.cs" .

# Find interaction patterns
grep -r "Grabbable\|IGrabbable\|OnGrab\|OnRelease" --include="*.cs" .
grep -r "Raycast\|RaycastHit\|Physics\.Raycast" --include="*.cs" .

步骤 2：对发现的问题分类

对每项发现的问题进行分类：

类别	查找内容	影响
控制器输入	OVRInput.Get()、按钮/轴引用	必须替换为手势或 ISDK 组件
抓取系统	基于扳机的抓取、距离抓取	转换为带有捏合检测的 HandGrabInteractable
UI 交互	基于射线的 UI、指针点击	转换为戳碰交互（PokeInteractable）
移动	摇杆移动、瞬间转向	重新设计为基于手部或注视的导航
物体操控	摇杆旋转、基于按钮的缩放	使用直接的手部旋转/缩放，并支持双手操作

步骤 3：提出适配方案

针对每个依赖控制器的系统，提出基于 ISDK 的具体替代方案。实现细节请参考 references/hand-tracking-patterns.md 中的手部追踪模式。

步骤 4：确定优先级

按照影响和工作量对建议排序：

• 高优先级——使用控制器 API、必须替换的核心游戏交互（例如基于 OVRInput 的抓取、基于扳机的射击）。
• 中优先级——依赖控制器 API 的次要交互（例如摇杆滚动、基于射线的 UI 导航）。
• 低优先级——针对已使用手部追踪的代码提出的改进建议（悬停反馈、音效提示、双手操作支持）。这些是可选增强，而非实现手部操作就绪的必要条件。

**重要。**如果项目已使用 ISDK 手部追踪（HandGrabInteractable、PokeInteractable 等），且没有依赖控制器的代码，请报告项目已适配手部操作。改进建议仅列为低优先级项目，不要将其视为必须进行的更改。已经支持手部操作的项目不应收到一长串改进建议。

输出格式

请以结构化报告的形式提供分析结果：

1. 项目摘要——说明项目类型及其核心机制。
2. 就绪度评分——估算当前已支持手部操作的交互所占百分比。
3. 必要更改——按优先级排列，并注明：
   • 发现的问题（具体文件/类），
   • 需要更改的内容，
   • 应使用的 ISDK 模式（参考 hand-tracking-patterns.md），
   • 预估复杂度（低/中/高）。
4. 快速见效项——简单且影响大的更改。
5. 迁移风险——需要留意的潜在问题。

关键参考

如需了解详细的实现模式，请阅读：

• references/hand-tracking-patterns.md — 7 种带组件参考的 ISDK 交互模式。
• references/migration-guide.md — 从控制器迁移到手部追踪的分步检查清单。

重要说明

• 迁移期间始终保留控制器支持，作为备用方案。
• 考虑无障碍需求：部分用户可能更喜欢或需要使用控制器输入。
• 性能很重要：手部追踪会增加 CPU 开销；请建议高效的实现方式。
• 使用左手和右手进行测试；不要假设用户以右手为主。
• 手部追踪最适合用于手臂可及范围内的交互。

视场角就绪情况（头部锁定 UI）

当准备将项目部署到视场角比开发者当前目标设备更窄的设备时，运行此检查。它会查找适用于较宽视场角、但在较窄设备边缘会被裁切的头部锁定（HUD）UI，并为每项提供迁移修复建议，例如瞄准标线、生命值／弹药计数器、小地图、教程标记、渐晕／信箱遮罩。这是与上方输入工作流不同的独立检查。

“视场角溢出”是什么意思

在 VR 中，没有任何内容会永久处于屏幕之外——用户可以转动头部。真正会被裁切的情况是头部锁定内容：UI 以固定的角度偏移附加到摄像机上。如果该偏移适合较宽的视场角，却超出较窄设备的视锥体，那么每一帧都会被裁切，也永远无法进入视野。此检查声称能够完整查找的仅限于这一类内容。

可靠性规则

计算几何数据，绝不估算。不要读取场景／预制件 YAML 后在脑中对嵌套变换做三角计算。应从正在运行的项目获取解析后的变换——进入 Play 模式（或运行构建版本）并读取实时对象——然后应用下方确定性的视锥体测试。由数学计算结果决定；你只负责分类并提出建议。

如需到达游戏的 HUD 状态并自动执行检查，而不是手动逐项点击，请使用 Meta XR Operator 驱动正在运行的构建版本——它可以运行项目并为你体验游戏状态，然后你可以检查每个状态下解析后的对象。如果无法实时运行并检查项目，仅凭静态文件无法可靠地完成此检查——请明确说明，而不是猜测。

视场角规格来源

视锥体测试需要将两个视锥体都表示为正切半角：

• { leftTan, rightTan, upTan, downTan } — 目标（视场角较窄）设备
• { leftTan, rightTan, upTan, downTan } — 当前设备（用于计算“之前适配、现在不适配”的差异）

这些值应取自目标设备发布的视场角规格。如果缺少任意一组值，请跳过视场角检查并说明原因——绝不要猜测未知数值。

流程

1. 确认可以实时运行并检查项目（例如，使用 Meta XR Operator 驱动构建版本），且已获得两组视锥体参数。如果缺少任意一项，请停止并说明原因。
2. 枚举头部锁定 UI 候选项：Canvas 的 renderMode 为 ScreenSpaceOverlay/ScreenSpaceCamera；任何变换祖先经过受追踪摄像机／CenterEyeAnchor／OVRCameraRig 中心眼的 Canvas／RectTransform／Renderer；以及全屏渐晕／信箱遮罩。排除未以头部为父级的世界锁定内容。
3. 对每个候选项，从正在运行的项目中获取解析后的角点世界坐标和中心眼摄像机世界变换——不要从 YAML 获取。
4. 视锥体测试（将每个角点变换到眼空间后，针对 z > 0）：tanX = x/z、tanY = y/z；当角点满足 -leftTan <= tanX <= rightTan 且 -downTan <= tanY <= upTan 时，该角点位于设备视野内。溢出 = 至少一个角点位于当前设备视野内，但位于目标设备视野外。
5. 按严重程度排序报告每处溢出，并注明每个角点超出目标边缘的角度余量。

严重程度

• 严重 — 玩家依赖的常驻 HUD（准星、生命值、弹药、目标标记）被裁切。
• 警告 — 次要 HUD 部分被裁切，或舒适度叠加层的尺寸不适合较窄的视场角。
• 建议 — 靠近边缘的装饰性头部锁定元素。

迁移指南

• 在目标的角度范围内将 HUD 向内移动；必须清晰可见的 HUD 应优先放在 0–30° 的主要区域。
• 减小 HUD 半径／参考距离，让 HUD 组合占据更小的角度。
• 必须位于外围的边缘 HUD，应改为屏幕外指示器（箭头／边缘发光效果）。
• 根据较窄的视场角，而非较宽的视场角，重新调整渐晕／宽银幕遮幅。
• 不要只是隐藏被裁切的 HUD，而应将其移至其他位置；玩家通常需要这些信息。

限制（在报告中说明）

• 仅对头部锁定 UI 保证完整性；不适用于预期从外围视野中看到的世界锁定内容，也不适用于仅在特定游戏状态下才会出现的内容。
• 一阶模型：单目中心视锥体。立体视觉（元素仅对一只眼睛可见）和镜头畸变属于改进项，不在覆盖范围内。
• 如果视锥体配置不可用，应说明本次检查已跳过；若检查未运行，切勿报告“未发现问题”。