hz-new-project-creation

新建项目技能

在选定构建路径后，从头搭建并配置新的 Meta VR 项目。本技能提供分步设置说明，并针对 Meta VR 硬件优化了推荐设置。

何时使用此技能

在以下情况下使用此技能：

• 选定构建路径后，创建面向 Meta Quest（Quest 2、Quest 3、Quest 3S、Quest Pro）和 Meta VR Glasses 的全新项目
• 为 Meta VR 配置具有正确渲染设置、SDK 版本和构建目标的项目
• 使用推荐的架构和文件夹结构设置项目模板
• 按照先前选定的 Standard Android、Meta Spatial SDK、Unity、Unreal Engine 或 WebXR 项目的设置工作流进行操作

先决条件

无论平台如何，创建任何 Meta VR 项目之前，都请完成以下步骤：

1. 创建 Meta 开发者账号——在 developer.meta.com 注册并创建组织。
2. 设置 Meta VR 设备以供开发——在手机上的 Meta Horizon 应用中，前往头显设置并启用开发者模式。
3. 启用 USB 调试——通过 USB-C 连接 Meta VR 设备，戴上头显，并接受“允许 USB 调试”提示。
4. 安装 metavr——在 PATH 中安装独立的 metavr CLI 二进制文件（请参阅 metavr-cli 技能），或者通过 npx 按需调用，无需安装：

   metavr --version
   

   以下示例使用裸命令 metavr；如果使用 npm 发行版，请在命令前加上 npx -y。

启动任何项目之前，请验证设备连接：

metavr device list

从选定的构建路径开始

在搭建项目之前，使用 hz-quest-verify-first 确定构建路径。不要根据功能清单来选择 SDK：有些路径可以提供相似的 Meta VR 功能，但它们的项目结构和运行时模型各不相同。

构建路径	适用情况	设置参考或技能
Standard Android	应用主要是一个可调整大小的 Horizon OS 面板中的 2D UI，使用 Jetpack Compose、Android Views、React Native 或 Expo 实现。这是新建 2D 应用时的默认选择；不需要 Spatial SDK。	Standard Android 项目；React Native 或 Expo 项目请使用 hz-react-native-expo
Meta Spatial SDK	应用需要沉浸式场景、3D 实体、环境控制或 2D 与 3D 内容混合。	Spatial SDK 项目
Unity	应用是使用 C# 构建的沉浸式游戏或体验。	Unity 项目
Unreal Engine	应用是使用 C++ 或 Blueprints 构建的沉浸式项目。	Unreal 项目
IWSDK / WebXR	体验基于 Web，应在浏览器中运行或作为 Web 应用发布。	Web 项目

选择平台后

用户选定平台后，请参阅相应的参考指南，了解详细的分步项目设置说明：

• Unity（Meta VR） -- 必须使用 metavr_unity_setup MCP 工具创建项目。不要直接运行 Unity CLI。不要引导用户手动执行 Package Manager / XR Plug-in Management 步骤。请参阅 Unity Project Setup。仅当 MCP 工具不可用时，才可使用 unity-project-manual.md 中的手动备用方案。（注意：此指南仅适用于 Meta VR Unity 项目——非 VR Unity 项目请照常使用 Unity Hub。）
• Unreal Engine -- Unreal Project Setup
• 标准 Android -- Standard Android Project Setup；如果 UI 使用 React Native 或 Expo 实现，请使用 hz-react-native-expo
• Meta Spatial SDK -- Spatial SDK Project Setup
• Web / IWSDK / WebXR -- Web Project Setup

每份参考指南都涵盖：

1. 所需工具和 SDK 版本
2. 项目创建步骤
3. 针对 Meta VR 的推荐项目设置
4. 构建和部署工作流
5. 测试和迭代工作流

注意事项

以下是在设置新的 Meta VR 项目时常见的问题。

• Android API 级别不匹配 -- 对于新的沉浸式项目，最低 API 级别应设为 32，目标 API 级别应设为 34。请查看 hz-store-submit，了解商店受理的最低要求，并查看 hz-api-upgrade，了解当前目标范围；沉浸式应用和 2D 面板应用的要求有所不同。API 级别设置错误是导致构建无法安装或上传的常见原因。Unity 默认值可能不符合这些要求——请务必在 Player Settings > Other Settings 中以及通过 metavr docs search "target API" 进行核实。
• 仅支持 ARM64，不支持 x86 -- Meta VR 设备采用 ARM64（aarch64）。如果构建流程以 x86 为目标平台或包含 x86 原生库，APK 将能安装，但启动时会立即崩溃。在 Unity 中，请确保“Target Architectures”仅勾选 ARM64。在 Android Studio 中，请检查 ABI 过滤器。
• Gradle 版本兼容性 -- Meta 的 Android 和 Spatial SDK 示例通常会固定使用兼容的 Gradle、Android Gradle Plugin、Kotlin 和 KSP 版本。请从最新的官方模板或示例中复制完整的版本组合；单独升级其中一个版本可能会导致难以排查的构建失败。
• Unity 版本很重要 -- 并非所有 Unity 版本都与最新的 Meta XR SDK 兼容。请查看 Meta XR SDK 发行说明，了解受支持的 Unity 版本范围。使用不受支持的 Unity 版本会导致难以理解的 C# 编译错误或运行时缺少 XR 子系统错误。
• Vulkan 与 OpenGL ES -- Quest 3 支持 Vulkan，推荐使用它以获得最佳性能。Quest 2 也支持 Vulkan，但较旧的 Meta XR SDK 功能曾存在仅在 Vulkan 下出现的问题。如果 Quest 2 使用 Vulkan 时出现渲染异常，请尝试回退到 OpenGL ES 3.0，并提交错误报告。
• Android 清单权限缺失 -- Meta VR 专属功能（手部追踪、透视、场景理解、眼动追踪）需要显式声明清单权限。如果缺少正确的权限，应用将无法访问这些功能，且不会显示任何提示。SDK 不会自动添加这些权限。
• 忘记在首次构建前设置包名 -- 在设备上首次安装后更改包名可能导致数据丢失或安装失败。请在首次构建和部署前设置正确的 com.company.appname 包名。
• Unreal Engine：OpenXR 与 OVRPlugin -- Unreal 同时支持 OpenXR 后端和适用于 Quest 的旧版 OVRPlugin 后端。新项目应使用 OpenXR。在同一项目中混用插件会导致未定义行为。

常见的设置后任务

项目在任何平台上创建并配置完成后，通常还需要执行以下任务：

在开发者控制面板中注册应用

在 developer.meta.com 上创建应用条目，以获取 App ID。启用平台功能（例如权益检查、多人游戏、成就和商店提交）时，必须提供此 ID。

设置版本控制

初始化 Git 仓库，并为所选平台配置 .gitignore：

git init
# Use a platform-appropriate .gitignore (Unity, Unreal, Android, or Node.js)

首次构建和部署

构建项目并将其安装到已连接的 Meta VR 设备上：

# After building, install the APK
metavr app install path/to/build.apk

# Launch the app
metavr app launch com.yourcompany.yourapp

# Monitor logs during first run
metavr adb logcat --follow --tag yourapp

性能基线

首次成功运行后，确认应用达到基线性能目标：

• 帧率：最低 72 Hz（Quest 3 上建议达到 90 Hz 或 120 Hz）
• 帧时间：帧时间稳定，没有突增
• 温度：正常使用期间没有热降频警告

参考资料

技能参考资料

• Unity 项目设置 -- 通过 metavr_unity_setup MCP 工具一次性设置 Unity 项目
  • Unity 手动设置（备用方案） -- 逐步进行手动配置；仅在 MCP 工具不可用时使用
• Unreal 项目设置 -- 逐步创建并配置 Unreal Engine 项目
• 标准 Android 项目设置 -- 创建不使用沉浸式 SDK 的 2D Horizon OS 面板应用
• Spatial SDK 项目设置 -- 使用 Meta Spatial SDK 创建沉浸式或混合 Android 应用
• Web 项目设置 -- 逐步创建并配置 IWSDK/WebXR 项目