hz-new-project-creation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

New Project Creation Skill

新项目创建技能

Scaffold and configure new Meta Quest projects from scratch. This skill guides you through choosing the right platform and project type, then provides step-by-step setup instructions with recommended settings optimized for Quest hardware.

从零开始搭建并配置新的Meta Quest项目。本技能会引导你选择合适的平台和项目类型，然后提供针对Quest硬件优化的推荐设置，以及分步搭建指南。

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Create a brand-new project targeting Meta Quest (Quest 2, Quest 3, Quest 3S, Quest Pro)
Choose between Unity, Unreal Engine, Android/Spatial SDK, or WebXR
Configure a project with the correct render settings, SDK versions, and build targets for Quest
Set up a project template with recommended architecture and folder structure
Understand which platform best fits your application type

当你需要以下操作时，可使用本技能：

创建面向Meta Quest（Quest 2、Quest 3、Quest 3S、Quest Pro）的全新项目
在Unity、Unreal Engine、Android/Spatial SDK或WebXR之间进行选择
为Quest配置正确的渲染设置、SDK版本和构建目标
设置带有推荐架构和文件夹结构的项目模板
了解哪种平台最适合你的应用类型

Prerequisites

前置条件

Before creating any Meta Quest project, complete these steps regardless of platform:

Create a Meta developer account -- Sign up at developer.meta.com and create an organization.
Set up your Quest for development -- Enable developer mode in the Meta Horizon app on your phone under your headset's settings.
Enable USB debugging -- Connect your Quest via USB-C, put on the headset, and accept the "Allow USB debugging" prompt.
Use metavr via
npx
-- The
```
metavr
```
CLI is invoked on demand; no global install required:
bash
```
npx -y metavr --version
```
Examples below use the bare
```
metavr
```
command for brevity; if it is not installed globally, replace
```
metavr
```
with
```
npx -y metavr
```
.

Verify your device connection before starting any project:

bash

metavr device list

无论选择哪种平台，在创建任何Meta Quest项目前，请完成以下步骤：

创建Meta开发者账户——访问developer.meta.com注册并创建组织。
将你的Quest设置为开发模式——在手机端的Meta Horizon应用中，进入你的头戴设备设置，启用开发者模式。
启用USB调试——通过USB-C连接你的Quest，戴上头戴设备，接受“允许USB调试”提示。
通过
npx
使用metavr——
```
metavr
```
CLI可按需调用，无需全局安装：
bash
```
npx -y metavr --version
```
以下示例为简洁起见使用
```
metavr
```
命令；若未全局安装，请将
```
metavr
```
替换为
```
npx -y metavr
```
。

在开始任何项目前，验证设备连接：

bash

metavr device list

Decision Tree

决策树

When a user wants to create a new Quest project, walk through these questions in order:

当用户想要创建新的Quest项目时，请按以下顺序询问问题：

Step 1: What Platform?

步骤1：选择哪种平台？

Ask the user which development platform they prefer or are most experienced with:

Unity -- C# scripting, mature XR ecosystem, large asset store
Unreal Engine -- C++ and Blueprints, high-fidelity rendering, cinematic tools
Android / Spatial SDK -- Kotlin, native Android development, panel-based apps
Web / IWSDK / WebXR -- TypeScript, rapid prototyping, browser-based distribution

询问用户偏好或最熟悉的开发平台：

Unity——C#脚本、成熟的XR生态系统、庞大的资源商店
Unreal Engine——C++与Blueprints、高保真渲染、影视制作工具
Android / Spatial SDK——Kotlin、原生Android开发、基于面板的应用
Web / IWSDK / WebXR——TypeScript、快速原型开发、基于浏览器的分发

Step 2: What Type of Experience?

步骤2：选择哪种体验类型？

Ask what kind of application they are building:

Type	Description	Best Platforms
Fully Immersive VR	Complete virtual environment, no passthrough	Unity, Unreal
Mixed Reality	Blend virtual content with real world via passthrough	Unity, Unreal, Spatial SDK
2D Panel App	Flat UI panel floating in the user's space	Spatial SDK, Unity
Hybrid (2D + 3D)	Panels with optional 3D spatial content	Spatial SDK

询问用户要构建的应用类型：

类型	描述	最佳平台
完全沉浸式VR	完整虚拟环境，无透视功能	Unity、Unreal
混合现实	通过透视功能将虚拟内容与现实世界融合	Unity、Unreal、Spatial SDK
2D面板应用	悬浮在用户空间中的平面UI面板	Spatial SDK、Unity
混合（2D + 3D）	带有可选3D空间内容的面板	Spatial SDK

Step 3: What Features?

步骤3：需要哪些功能？

Identify which Quest-specific features the project needs:

Hand tracking -- Controller-free interaction using hand and finger detection
Eye tracking -- Gaze-based interaction and foveated rendering (Quest Pro, Quest 3)
Passthrough -- Camera-based view of the real world with virtual overlays
Multiplayer -- Networked multi-user experiences
Spatial audio -- 3D positional audio with HRTF spatialization
Scene understanding -- Room mesh, plane detection, semantic labels
Spatial anchors -- Persistent world-locked content placement

确定项目需要哪些Quest专属功能：

手部追踪——无需控制器，通过手部和手指检测实现交互
眼部追踪——基于视线的交互和注视点渲染（适用于Quest Pro、Quest 3）
透视功能——基于摄像头的现实世界视图，叠加虚拟内容
多人游戏——联网多用户体验
空间音频——带有HRTF空间化的3D位置音频
场景理解——房间网格、平面检测、语义标签
空间锚点——持久化的世界锁定内容放置

Platform Comparison

平台对比

Platform	Best For	Language	3D Engine	Learning Curve	Distribution
Unity	Games, complex 3D, social VR	C#	Unity	Moderate	Quest Store, App Lab
Unreal Engine	High-fidelity visuals, cinematic	C++ / Blueprint	Unreal	Steep	Quest Store, App Lab
Spatial SDK	Android panel apps, hybrid apps	Kotlin	Custom ECS	Moderate	Quest Store, App Lab
IWSDK / WebXR	Web-based, quick prototyping	TypeScript	Three.js	Low	Web, PWA, Store (via Bubblewrap)

平台	适用场景	编程语言	3D引擎	学习曲线	分发渠道
Unity	游戏、复杂3D内容、社交VR	C#	Unity	中等	Quest商店、App Lab
Unreal Engine	高保真视觉效果、影视内容	C++ / Blueprint	Unreal	较难	Quest商店、App Lab
Spatial SDK	Android面板应用、混合应用	Kotlin	自定义ECS	中等	Quest商店、App Lab
IWSDK / WebXR	基于Web的应用、快速原型	TypeScript	Three.js	较低	Web、PWA、商店（通过Bubblewrap）

Platform Selection Guidelines

平台选择指南

Choose Unity when you need the broadest XR feature support, a large ecosystem of third-party assets, or your team already knows C#.
Choose Unreal when visual fidelity is the top priority, you need cinematic sequences, or your team is experienced with C++ or Blueprints.
Choose Spatial SDK when building panel-based Android apps, hybrid 2D+3D experiences, or leveraging existing Android/Kotlin expertise.
Choose IWSDK/WebXR when you want the fastest iteration cycle, browser-based distribution, or are prototyping an idea before committing to a native engine.

选择Unity：当你需要最广泛的XR功能支持、庞大的第三方资源生态，或团队已掌握C#时。
选择Unreal：当视觉保真度为首要需求、需要影视级序列，或团队熟悉C++或Blueprints时。
选择Spatial SDK：当构建基于面板的Android应用、2D+3D混合体验，或利用现有Android/Kotlin技术栈时。
选择IWSDK/WebXR：当你想要最快的迭代周期、基于浏览器的分发，或在投入原生引擎前进行原型验证时。

After Choosing a Platform

选择平台后

Once the user has selected a platform, refer to the corresponding reference guide for detailed, step-by-step project setup:

Unity (Quest / VR) -- MUST use the
```
metavr_unity_setup
```
MCP tool to create the project. Do NOT run Unity CLI directly. Do NOT walk the user through manual Package Manager / XR Plug-in Management steps. See Unity Project Setup. Manual fallback at unity-project-manual.md only when the MCP tool is unavailable. (Note: this guidance applies to Quest/VR Unity projects only — for non-VR Unity projects use Unity Hub as normal.)
Unreal Engine -- Unreal Project Setup
Android / Spatial SDK -- Android Project Setup
Web / IWSDK / WebXR -- Web Project Setup

Each reference covers:

Required tool and SDK versions
Project creation steps
Recommended project settings for Quest
Build and deployment workflow
Testing and iteration workflow

一旦用户选定平台，请参考对应的参考指南获取详细的分步项目搭建说明：

Unity (Quest / VR)——必须使用
```
metavr_unity_setup
```
MCP工具创建项目。请勿直接运行Unity CLI。请勿引导用户手动完成Package Manager / XR Plug-in Management步骤。详见Unity项目搭建。仅当MCP工具不可用时，才使用Unity手动搭建（备选方案）。（注意：本指南仅适用于Quest/VR Unity项目——非VR Unity项目请正常使用Unity Hub。）
Unreal Engine——Unreal项目搭建
Android / Spatial SDK——Android项目搭建
Web / IWSDK / WebXR——Web项目搭建

每个参考指南涵盖：

所需工具和SDK版本
项目创建步骤
针对Quest的推荐项目设置
构建与部署流程
测试与迭代流程

Gotchas

常见陷阱

These are common pitfalls when setting up new Quest projects.

Android API level mismatch -- Quest requires a minimum Android API level of 29 (Android 10) and a target API level of 32+. Setting the wrong API level is the most common reason builds fail to install on the device. Unity defaults may not match these requirements — always verify in Player Settings > Other Settings.
ARM64 only, no x86 -- Quest devices are ARM64 (aarch64). If your build pipeline targets x86 or includes x86 native libraries, the APK will install but crash immediately on launch. In Unity, ensure "Target Architectures" has only ARM64 checked. In Android Studio, verify your ABI filters.
Gradle version compatibility -- Meta's Android/Spatial SDK samples often pin specific Gradle and AGP (Android Gradle Plugin) versions. Using a newer Gradle version than the samples expect can cause obscure build failures. Match the versions from the sample project's
```
gradle-wrapper.properties
```
and
```
build.gradle
```
.
Unity version matters -- Not every Unity version is compatible with the latest Meta XR SDK. Check the Meta XR SDK release notes for the supported Unity version range. Using an unsupported Unity version causes cryptic C# compilation errors or missing XR subsystem errors at runtime.
Vulkan vs. OpenGL ES -- Quest 3 supports Vulkan and it is recommended for best performance. Quest 2 also supports Vulkan but some older Meta XR SDK features had Vulkan-only bugs. If you see rendering artifacts on Quest 2 with Vulkan, try OpenGL ES 3.0 as a fallback and file a bug.
Missing Android manifest permissions -- Quest-specific features (hand tracking, passthrough, scene understanding, eye tracking) require explicit manifest permissions. The app will silently fail to access these features without the correct permissions. They are not added automatically by the SDK.
Forgetting to set the package name before first build -- Changing the package name after the first install on a device can cause data loss or install failures. Set the correct
```
com.company.appname
```
package name before your first build and deploy.
Unreal Engine: OpenXR vs. OVRPlugin -- Unreal supports both the OpenXR backend and the legacy OVRPlugin backend for Quest. New projects should use OpenXR. Mixing plugins in the same project causes undefined behavior.

以下是搭建新Quest项目时的常见误区：

Android API版本不匹配——Quest要求最低Android API级别为29（Android 10），目标API级别为32+。设置错误的API级别是构建无法在设备上安装的最常见原因。Unity默认设置可能不符合这些要求——请务必在Player Settings > Other Settings中验证。
仅支持ARM64，不支持x86——Quest设备为ARM64架构（aarch64）。如果构建流水线目标为x86或包含x86原生库，APK将安装但启动后立即崩溃。在Unity中，确保“Target Architectures”仅勾选ARM64。在Android Studio中，验证ABI过滤器。
Gradle版本兼容性——Meta的Android/Spatial SDK示例通常固定特定的Gradle和AGP（Android Gradle Plugin）版本。使用比示例要求更新的Gradle版本可能导致难以排查的构建失败。请匹配示例项目
```
gradle-wrapper.properties
```
和
```
build.gradle
```
中的版本。
Unity版本至关重要——并非所有Unity版本都兼容最新的Meta XR SDK。请查看Meta XR SDK发布说明获取支持的Unity版本范围。使用不支持的Unity版本会导致模糊的C#编译错误或运行时缺少XR子系统的错误。
Vulkan vs. OpenGL ES——Quest 3支持Vulkan，推荐使用以获得最佳性能。Quest 2也支持Vulkan，但部分旧版Meta XR SDK功能存在仅Vulkan的bug。如果在Quest 2上使用Vulkan出现渲染异常，请尝试使用OpenGL ES 3.0作为备选方案并提交bug。
缺少Android清单权限——Quest专属功能（手部追踪、透视、场景理解、眼部追踪）需要明确的清单权限。没有正确的权限，应用将无法正常访问这些功能，且不会给出提示。SDK不会自动添加这些权限。
首次构建前忘记设置包名——在设备上首次安装后更改包名可能导致数据丢失或安装失败。在首次构建和部署前，设置正确的
```
com.company.appname
```
包名。
Unreal Engine: OpenXR vs. OVRPlugin——Unreal支持OpenXR后端和旧版OVRPlugin后端用于Quest。新项目应使用OpenXR。在同一项目中混合使用插件会导致未定义行为。

Common Post-Setup Tasks

常见搭建后任务

After the project is created and configured on any platform, these tasks are typically needed:

无论选择哪种平台，项目创建并配置完成后，通常需要完成以下任务：

Register the App on the Developer Dashboard

在开发者控制台注册应用

Create an application entry at developer.meta.com to obtain an App ID. This is required for platform features like entitlement checks, multiplayer, achievements, and store submission.

在developer.meta.com创建应用条目以获取App ID。这是使用平台功能（如授权检查、多人游戏、成就、商店提交）的必要步骤。

Set Up Version Control

设置版本控制

Initialize a Git repository and configure

.gitignore

for the chosen platform:

bash

git init

初始化Git仓库并为所选平台配置

.gitignore

：

bash

git init

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

使用适合平台的.gitignore（Unity、Unreal、Android或Node.js）

undefined

undefined

First Build and Deploy

首次构建与部署

Build the project and install it on a connected Quest device:

bash

undefined

构建项目并安装到已连接的Quest设备：

bash

undefined

After building, install the APK

构建完成后，安装APK

metavr app install path/to/build.apk

Launch the app

启动应用

metavr app launch com.yourcompany.yourapp

Monitor logs during first run

首次运行时监控日志

metavr log --tag yourapp

undefined

metavr log --tag yourapp

undefined

Performance Baseline

性能基准测试

On first successful run, verify the application meets baseline performance targets:

Frame rate: 72 Hz minimum (90 Hz or 120 Hz preferred on Quest 3)
Frame timing: Consistent frame times without spikes
Thermal: No thermal throttling warnings during normal use

首次成功运行后，验证应用是否达到基准性能目标：

帧率：最低72 Hz（Quest 3推荐90 Hz或120 Hz）
帧时间：帧时间稳定，无峰值
散热：正常使用时无热节流警告

References

参考资料

Skill References

技能参考

Unity Project Setup -- One-shot Unity project setup via the
```
metavr_unity_setup
```
MCP tool
- Unity Manual Setup (fallback) -- Step-by-step manual configuration; only needed when the MCP tool is unavailable
Unreal Project Setup -- Step-by-step Unreal Engine project creation and configuration
Android Project Setup -- Step-by-step Android/Spatial SDK project creation and configuration
Web Project Setup -- Step-by-step IWSDK/WebXR project creation and configuration

Unity项目搭建——通过
```
metavr_unity_setup
```
MCP工具一键完成Unity项目搭建
- Unity手动搭建（备选方案）——分步手动配置；仅当MCP工具不可用时使用
Unreal项目搭建——分步Unreal Engine项目创建与配置
Android项目搭建——分步Android/Spatial SDK项目创建与配置
Web项目搭建——分步IWSDK/WebXR项目创建与配置