Back to Details

hz-android-2d-porting

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Android 2D App Porting to Horizon OS

将Android 2D应用移植到Horizon OS

When to Use

适用场景

Use this skill when:
  • Porting an existing Android 2D app to run on Meta Quest headsets
  • Adapting a mobile Android app for Horizon OS panels
  • Troubleshooting input, layout, or compatibility issues with a 2D app on Quest
  • Preparing an Android app for Horizon Store submission
  • Evaluating whether an existing Android app is compatible with Horizon OS
在以下场景中使用本技能：
  • 将现有Android 2D应用移植到Meta Quest头显运行
  • 为Horizon OS面板适配移动Android应用
  • 排查Quest上2D应用的输入、布局或兼容性问题
  • 为Horizon Store提交准备Android应用
  • 评估现有Android应用是否与Horizon OS兼容

Overview

概述

Horizon OS is built on Android (AOSP) and can run standard Android applications inside panels -- floating 2D windows positioned in 3D space. Most well-built Android apps work on Quest with minimal changes, but several areas require attention:
  1. Input: There is no touchscreen. Users interact via controller pointer (ray-casting), hand tracking, or connected peripherals.
  2. Layout: Apps run in resizable panels, not full-screen on a fixed display.
  3. Design: Apps must meet Horizon OS design requirements for Horizon Store approval.
  4. Performance: Quest uses a mobile GPU (Adreno) with thermal constraints.
The goal of porting is to make the app feel native to the Quest experience while preserving existing functionality.
Horizon OS基于Android（AOSP）构建，可在面板中运行标准Android应用——即位于3D空间中的浮动2D窗口。大多数构建完善的Android应用只需少量修改即可在Quest上运行，但有几个方面需要重点关注：
  1. 输入：无触摸屏。用户通过控制器指针（射线投射）、手部追踪或连接的外设进行交互。
  2. 布局：应用在可调整大小的面板中运行，而非在固定显示屏上全屏显示。
  3. 设计：应用必须满足Horizon OS的设计要求才能通过Horizon Store审核。
  4. 性能：Quest采用移动GPU（Adreno），存在散热限制。
移植的目标是在保留现有功能的同时，让应用在Quest上拥有原生体验。

Porting Workflow

移植流程

Step 1: Initial Testing

步骤1：初始测试

Invoke metavr (the Quest device CLI) via 
metavr <args>
. The command is published as the npm package 
metavr
, so if 
metavr
is not on PATH you can run the same CLI via 
npx -y metavr <args>
— no global install needed; npx fetches the latest published version on demand.
The examples in this doc call 
metavr
directly; the 
npx -y metavr <args>
form above is the equivalent when 
metavr
is not on PATH (the published npm package is still 
metavr
).
Install the existing APK on a connected Quest device and test basic functionality:
bash
metavr app install path/to/your-app.apk
metavr app launch com.example.yourapp
Note any immediate issues: crashes, black screens, input problems, or layout breakage.
通过
metavr <args>
调用metavr（Quest设备CLI）。该命令作为npm包
metavr
发布，因此如果
metavr
不在PATH中，你可以通过
npx -y metavr <args>
运行相同的CLI——无需全局安装；npx会按需获取最新发布的版本。
本文档中的示例直接调用
metavr
；当
metavr
不在PATH中时，上述
npx -y metavr <args>
形式是等效的（发布的npm包仍为
metavr
）。
将现有APK安装到已连接的Quest设备上并测试基本功能：
bash
metavr app install path/to/your-app.apk
metavr app launch com.example.yourapp
记录任何即时问题：崩溃、黑屏、输入问题或布局损坏。

Step 2: Input Adaptation

步骤2：输入适配

The most common porting issue is input. Touch events are translated from the controller pointer, but:
  • Hover states are now visible (users point before clicking)
  • Scrolling uses the thumbstick, not swipe gestures
  • Multi-touch gestures (pinch-to-zoom) do not translate directly
  • Tap targets must be large enough for pointer accuracy (48dp minimum)
See Input Adaptation Reference for detailed guidance.
最常见的移植问题是输入。触摸事件会从控制器指针转换而来，但存在以下差异：
  • 悬停状态现在可见（用户点击前会先指向）
  • 滚动使用摇杆，而非滑动手势
  • 多点触控手势（捏合缩放）无法直接转换
  • 点击目标必须足够大以保证指针精度（最小48dp）
有关详细指导，请参阅输入适配参考。

Step 3: Layout Adjustment

步骤3：布局调整

Panels are resizable and can have various aspect ratios. Your app must handle:
  • Dynamic width and height changes
  • Landscape and portrait orientations
  • Different effective DPI values
Use responsive layout strategies such as 
ConstraintLayout
or Jetpack Compose. See Panel Layout Reference.
面板可调整大小，且具有多种宽高比。你的应用必须处理：
  • 动态宽度和高度变化
  • 横向和纵向方向
  • 不同的有效DPI值
使用响应式布局策略，例如
ConstraintLayout
或Jetpack Compose。请参阅面板布局参考。

Step 4: Gradle and Manifest Updates

步骤4：Gradle和清单更新

Update your build configuration to target Horizon OS:
kotlin
// build.gradle.kts
android {
    defaultConfig {
        minSdk = 29       // Android 10 minimum
        targetSdk = 34    // API 34 or higher required for all new 2D panel apps
    }
}
Add required manifest entries for device targeting. See Gradle Setup Reference.
更新构建配置以适配Horizon OS：
kotlin
// build.gradle.kts
android {
    defaultConfig {
        minSdk = 29       // 最低要求Android 10
        targetSdk = 34    // 所有新2D面板应用要求API 34或更高
    }
}
添加针对设备的必需清单条目。请参阅Gradle设置参考。

Step 5: Input Testing

步骤5：输入测试

Test with all supported input methods:
  • Controller: point-and-click, thumbstick scroll, trigger tap
  • Hand tracking: pinch-to-select, hand scroll
  • Keyboard/mouse: Bluetooth peripherals, system keyboard for text fields
Use the XR Simulator for rapid iteration, then validate on-device.
使用所有支持的输入方法进行测试：
  • 控制器：指向点击、摇杆滚动、扳机点击
  • 手部追踪：捏合选择、手部滚动
  • 键盘/鼠标：蓝牙外设、文本字段使用系统键盘
使用XR Simulator进行快速迭代，然后在设备上验证。

Step 6: Store Submission

步骤6：商店提交

Before submitting to the Horizon Store:
  • Verify all Compatibility Requirements
  • Test on at least Quest 3 and Quest 2 (if targeting both)
  • Confirm the app works in both passthrough and immersive home environments
  • Review Meta's content policies and technical requirements
提交到Horizon Store之前：
  • 验证所有兼容性要求
  • 至少在Quest 3和Quest 2上测试（如果同时针对这两款设备）
  • 确认应用在透视模式和沉浸式主环境中均可正常工作
  • 查看Meta的内容政策和技术要求

Quick Compatibility Check

快速兼容性检查

Works on Horizon OS

可在Horizon OS上运行的功能

FeatureStatusNotes
Standard Android ViewsSupportedTextView, RecyclerView, etc.
Jetpack ComposeSupportedFull Compose UI toolkit
WebViewSupportedChromium-based
Media playback (ExoPlayer)SupportedVideo and audio
Networking (HTTP, WebSocket)SupportedWi-Fi connectivity
Room / SQLiteSupportedLocal database
WorkManagerSupportedBackground tasks
NotificationsSupportedHorizon OS notification panel
Bluetooth (peripherals)SupportedKeyboard, mouse, gamepad
Android Accessibility APIsSupportedTalkBack equivalent available
功能状态说明
标准Android视图支持TextView、RecyclerView等
Jetpack Compose支持完整的Compose UI工具包
WebView支持基于Chromium
媒体播放（ExoPlayer）支持视频和音频
网络（HTTP、WebSocket）支持Wi-Fi连接
Room / SQLite支持本地数据库
WorkManager支持后台任务
通知支持Horizon OS通知面板
蓝牙（外设）支持键盘、鼠标、游戏手柄
Android无障碍API支持有等效的TalkBack功能

Restricted or Unavailable

受限或不可用的功能

FeatureStatusNotes
Camera (front-facing)Not availableNo standard camera in 2D mode
Telephony / SMSNot availableNo cellular radio
NFCNot availableNo NFC hardware
GPS / Fine locationLimitedWi-Fi-based location only
Fingerprint / BiometricPromptNot availableUse Meta account auth instead
Split-screen (multi-window)LimitedUse Spatial SDK panels instead
Google Play ServicesNot availableUse Meta equivalents or alternatives
ARCoreNot availableUse Meta Spatial SDK for spatial features
Multi-touch gesturesLimitedSingle pointer from controller
功能状态说明
前置摄像头不可用2D模式下无标准摄像头
电话/SMS不可用无蜂窝无线电
NFC不可用无NFC硬件
GPS/精确定位受限仅支持基于Wi-Fi的定位
指纹/BiometricPrompt不可用改用Meta账号认证
分屏（多窗口）受限改用Spatial SDK面板
Google Play服务不可用使用Meta等效服务或替代方案
ARCore不可用使用Meta Spatial SDK实现空间功能
多点触控手势受限仅支持控制器的单指针

Common Issues and Fixes

常见问题及修复方案

IssueCauseFix
App crashes on launchMissing Google Play Services dependencyRemove or make GMS optional
Buttons too small to tapTouch targets under 48dpIncrease minimum tap target size
No scroll in listsSwipe-based scroll not triggeredEnsure 
RecyclerView
/
LazyColumn
handles generic scroll events
Keyboard doesn't appearCustom input field not using 
InputConnection
Use standard 
EditText
or 
TextField
Layout brokenFixed-size layout assumptionsUse responsive layouts with 
ConstraintLayout
or Compose
App requests unavailable permissionsCamera, telephony, etc.Guard with 
hasSystemFeature()
checks
APK rejected for prohibited permissionsLibrary or plugin silently added a prohibited permissionRun 
aapt dump permissions your-app.apk
, then check prohibited list
APK rejected for invalid signatureSigned with v1-only schemev2 signing is default in AGP 7.0+; for older AGP, add 
v2SigningEnabled = true
to your signing config
问题原因修复方案
应用启动崩溃缺少Google Play Services依赖移除该依赖或设为可选
按钮过小无法点击点击目标小于48dp增加最小点击目标尺寸
列表无法滚动未触发基于滑动的滚动确保
RecyclerView
/
LazyColumn
支持通用滚动事件
键盘不弹出自定义输入字段未使用
InputConnection
使用标准
EditText
或
TextField
布局损坏假设布局尺寸固定使用
ConstraintLayout
或Compose实现响应式布局
应用请求不可用权限摄像头、电话等权限使用
hasSystemFeature()
检查进行防护
APK因权限被拒库或插件静默添加了禁用权限运行
aapt dump permissions your-app.apk
，然后查看禁用权限列表
APK因签名无效被拒仅使用v1签名方案AGP 7.0+默认使用v2签名；对于旧版AGP，在签名配置中添加
v2SigningEnabled = true

Key Concepts

核心概念

Compatibility Mode vs Native Targeting

兼容模式 vs 原生适配

Apps not specifically targeting Horizon OS run in compatibility mode:
  • Fixed panel size (simulating a phone screen)
  • Limited resizing
  • Basic input translation
Apps that target Horizon OS with proper manifest entries run in native mode:
  • Resizable panels
  • Full input API support
  • Access to Spatial SDK features (optional)
  • Better integration with Horizon OS shell
未专门针对Horizon OS的应用将在兼容模式下运行：
  • 固定面板尺寸（模拟手机屏幕）
  • 调整大小受限
  • 基础输入转换
通过正确的清单条目针对Horizon OS的应用将在原生模式下运行：
  • 可调整大小的面板
  • 完整的输入API支持
  • 可访问Spatial SDK功能（可选）
  • 与Horizon OS shell更好地集成

Testing Tools

测试工具

  • metavr: Command-line tool for installing, launching, and debugging apps on Quest
  • XR Simulator: Desktop tool for testing Quest apps without a headset
  • Meta Quest Developer Hub (MQDH): GUI tool for device management and debugging
  • Android Studio: Full IDE with Quest device support via ADB
  • metavr：用于在Quest上安装、启动和调试应用的命令行工具
  • XR Simulator：无需头显即可测试Quest应用的桌面工具
  • Meta Quest Developer Hub (MQDH)：用于设备管理和调试的GUI工具
  • Android Studio：通过ADB支持Quest设备的完整IDE

Performance Considerations

性能注意事项

Quest devices have mobile-class hardware with strict thermal limits:
  • GPU: Qualcomm Adreno (varies by Quest model)
  • RAM: 6-12 GB shared between system and apps
  • Thermal: Sustained workloads may trigger thermal throttling
  • Avoid heavy overdraw and complex shader effects in 2D UI
  • Minimize background work to reduce power consumption
  • Test with representative data loads (large lists, images, etc.)
Quest设备采用移动级硬件，具有严格的散热限制：
  • GPU：高通Adreno（因Quest型号而异）
  • RAM：6-12 GB，由系统和应用共享
  • 散热：持续工作负载可能触发热节流
  • 避免2D UI中过度绘制和复杂着色器效果
  • 尽量减少后台工作以降低功耗
  • 使用代表性数据负载进行测试（大型列表、图像等）

References

参考资料

  • Compatibility Requirements -- store requirements and API compatibility
  • Input Adaptation -- adapting touch to controller and hand input
  • Panel Layout -- responsive layout for Horizon OS panels
  • Gradle Setup -- build configuration and manifest entries
  • 兼容性要求——商店要求和API兼容性
  • 输入适配——将触摸适配为控制器和手部输入
  • 面板布局——Horizon OS面板的响应式布局
  • Gradle设置——构建配置和清单条目