/hz-android-2d-porting

name: hz-android-2d-porting
license: Apache-2.0
description: "Guides porting existing Android 2D apps to Meta VR and Horizon OS — input adaptation, panel layout, and design requirements. Use when adapting a mobile Android app for Meta VR. For UI design decisions, use hz-panel-designer if available. Build path: Standard Android; use hz-quest-verify-first if the build path is unclear."
allowed-tools: Bash(metavr:*), Bash(hzdb:*)

Android 2D App Porting to Horizon OS

When to Use

Use this skill when:

• Porting an existing Android 2D app to run on Meta VR headsets
• Adapting a mobile Android app for Horizon OS panels
• Troubleshooting input, layout, or compatibility issues with a 2D app on Meta VR devices
• Preparing an Android app for Horizon Store submission
• Evaluating whether an existing Android app is compatible with 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 Meta VR devices 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. **Compatibility**: Dependencies and permissions must work without Google Play Services or unavailable hardware. 4. **Design and performance**: Apps must meet Horizon Store requirements on mobile hardware.

The goal of porting is to make the app feel native to the Meta VR experience while preserving existing functionality.

Porting Workflow

Step 1: Initial Testing

Build and install the existing app with its normal Android workflow. Android Studio, Gradle, and `adb` all work with a connected Meta VR device:

./gradlew installDebug
adb shell am start -n com.example.yourapp/.MainActivity

Prefer `metavr app install <apk>` and `metavr app launch <package>` over raw adb here, then stream `metavr adb logcat --follow` during this first run. Note any immediate crashes, black screens, input problems, or layout breakage.

Step 2: Compatibility Audit

Check whether the app depends on Google Play Services, unsupported hardware, or prohibited permissions before changing its UI. Make unsupported features optional or replace them with Horizon OS alternatives. See [Compatibility Requirements](references/compatibility-requirements.md).

Step 3: Input Adaptation

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](references/input-adaptation.md) for detailed guidance.

Step 4: Layout Adjustment

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 Android layouts and window-size breakpoints. See [Panel Layout Reference](references/panel-layout.md).

Step 5: Gradle and Manifest Updates

Update your build configuration to target Horizon OS:

// 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](references/gradle-setup.md).

Step 6: Input Testing

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 Meta Spatial Simulator for rapid desktop iteration, then validate on-device with the Meta Horizon OS Android Studio plugin or normal ADB tooling. Keep `metavr adb logcat --follow` running during each input pass — it catches input errors that don't visibly crash.

Step 7: Store Submission

Before submitting to the Horizon Store:

• Verify all [Compatibility Requirements](references/compatibility-requirements.md)
• Test on at least Quest 3, Quest 3S, and Quest 2 (if targeting them), plus Meta VR Glasses
• Confirm the app works in both passthrough and immersive home environments
• Review Meta's content policies and technical requirements

Quick Compatibility Check

Works on Horizon OS

| Feature | Status | Notes | |---|---|---| | Standard Android Views | Supported | TextView, RecyclerView, etc. | | Jetpack Compose | Supported | Full Compose UI toolkit | | React Native | Supported | Uses the standard Android application path | | WebView | Supported | Chromium-based | | Media playback (ExoPlayer) | Supported | Video and audio | | Networking (HTTP, WebSocket) | Supported | Wi-Fi connectivity | | Room / SQLite | Supported | Local database | | WorkManager | Supported | Background tasks | | Notifications | Supported | Horizon OS notification panel | | Bluetooth (peripherals) | Supported | Keyboard, mouse, gamepad | | Android Accessibility APIs | Supported | TalkBack equivalent available |

Restricted or Unavailable

| Feature | Status | Notes | |---|---|---| | Telephony / SMS | Not available | No cellular radio | | NFC | Not available | No NFC hardware | | GPS / Fine location | Limited | Wi-Fi-based location only | | Fingerprint / BiometricPrompt | Not available | Use Meta account auth instead | | Multiple app-owned panels | Limited | Use the current public multi-panel guidance when available | | Google Play Services | Not available | Use Meta equivalents or alternatives | | ARCore | Not available | Use Meta Spatial SDK for spatial features | | Mult