Develop

Test your app on Meta Spatial Simulator

Updated: Sep 4, 2026

About Meta Spatial Simulator

Meta Spatial Simulator runs your 2D Android app as a panel on your desktop. You test and iterate there instead of loading the app onto a physical device every time. It is for 2D Android apps only. Other ways to build for Horizon OS, such as Spatial SDK, OpenXR, Unity, and Unreal, use their own simulation tools or a physical device.

A 2D Android recipe app running as a flat panel in Meta Spatial Simulator, floating in a simulated living room

Requirements

Requirement	Minimum
macOS	Apple silicon (M1 or later), macOS 12 or later, with Xcode Command Line Tools (`xcode-select --install`)
Windows	Windows 10 or later, 64-bit, 8 or more cores, hardware virtualization enabled in BIOS
GPU	Vulkan-capable, with current drivers
Disk space	8 GB free
Memory	4 GB free
Android SDK	The `platform-tools` package for `adb`, and the `emulator` package
Android Studio	Otter 2025.2 or later, for the Android Studio workflow

Install the simulator

There is no standalone installer. Install the simulator from Android Studio or from the command line, whichever fits your workflow.

Install from Android Studio

Install the Meta Horizon Android Studio plugin if you do not have it yet.
Click the Meta logo in the sidebar to open the Meta Horizon tool window, and log in with your Meta Horizon account.
In Virtual Devices and Tools, click the download icon beside Meta Spatial Simulator.
Click the green play button to start the simulator.

Install from the command line

Install Meta VR CLI (metavr). That page covers the native installer and npm.

Install and start the simulator:

metavr tools install spatialsim
metavr ssim start
metavr ssim status

If you are signed in to Meta VR CLI, metavr ssim start signs the simulator in to the same account, which removes the separate sign-in step. Starting the simulator from the Android Studio plugin does the same. A simulator that is already signed in keeps the account it has.

The download, update, and sign-in flags are listed in Set up your environment and tools.

Run your app

Your app appears as a panel. You can test it by clicking UI elements, typing into text fields, and scrolling with your mouse wheel or trackpad.

Run from Android Studio

Start Meta Spatial Simulator. The device appears in Android Studio only while the simulator is running.
Select Meta Spatial Simulator in the device dropdown in the Android Studio toolbar.
Click Run.

Run from the command line

Meta VR CLI has no build command. Build your APK as usual with Android Studio or Gradle, then use the CLI to deploy it.

Install and launch your APK:

metavr app install path/to/your-app.apk
metavr app launch com.example.myapp

Capture a screenshot when you need the rendered panel as a file rather than something to look at on screen. Use it in a CI check, in a bug report, or with a coding agent that has no view of the simulator window:
```
metavr capture screenshot -o app.png
```

Test Look and Pinch input

The simulator reproduces the Look and Pinch input model of Meta VR Glasses, the pre-release Meta device that replaces controllers with eye tracking and hand input. Look and Pinch is on by default, so the simulator starts in that model.

See Test Look and Pinch for the settings menu, the interactive element overlay, and what to fix in your app. For the interaction model itself, see Look and Pinch for 2D apps.

What you can also test

The simulator also covers:

Test multiple windows: how your app behaves alongside other apps, in the background, and on return.
Sign in to the simulator: the parts of your app that need an account.
Built-in apps: flows that leave your app for Browser, Store, Files, or Gallery and come back, such as an OAuth handoff or a file picker.

Platform SDK testing: user management, in-app purchases, group presence, and application lifecycle, in a sandbox.

Billing Compatibility SDK testing: your Google Play Billing integration, on SDK 2.0.0 or later.

The metavr commands on this page drive the device and the simulator. They are unrelated to the Platform SDK on Spatial Simulator command-line interface, which uses adb broadcasts to simulate Platform SDK events such as in-app purchases, users, and leaderboards.

Troubleshooting

The download fails or the simulator will not start

Check your machine against the requirements first, then:

Update your GPU drivers to the current release.
Free up memory. The simulator needs 4 GB.
On Windows, confirm hardware virtualization is enabled in BIOS.

The simulator never finishes booting

Read the simulator log output for errors, and allow up to five minutes on the first boot.

Android Studio or the CLI cannot find the simulator

metavr resolves your Android SDK from ANDROID_HOME first, then its own managed SDK, then the per-OS default (~/Library/Android/sdk on macOS, %LOCALAPPDATA%\Android\Sdk on Windows). Set ANDROID_HOME to keep Android Studio, adb, and the CLI on one SDK, and put the SDK’s platform-tools directory first on your PATH so adb resolves to the SDK copy.

On macOS, add this to ~/.zshrc or ~/.bash_profile, then reload the shell:

export ANDROID_HOME="$HOME/Library/Android/sdk"
export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"

On Windows, run this in PowerShell. It persists the values for new terminals and applies them to the one you are in:

$sdk = "$env:LOCALAPPDATA\Android\Sdk"
$dirs = "$sdk\platform-tools;$sdk\emulator"

$userPath = [System.Environment]::GetEnvironmentVariable("Path", "User")
$newPath = if ($userPath) { "$dirs;$userPath" } else { $dirs }
[System.Environment]::SetEnvironmentVariable("ANDROID_HOME", $sdk, "User")
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")

$env:ANDROID_HOME = $sdk
$env:PATH = "$dirs;$env:PATH"

Read the User-scope Path rather than $env:PATH. The latter is the Machine and User values merged, so writing it back to the User scope copies every Machine entry into your account.

To see which adb wins, run which -a adb, or where.exe adb on Windows.

`adb` does not detect the simulator

Restart the ADB server with adb kill-server && adb start-server.
Confirm no second virtual device is running on the same port.
Update your platform-tools package.

A command fails with “Multiple devices connected”

A physical device, phone, or second virtual device is attached at the same time, so a command that expects a single device fails with Multiple devices connected. Please specify a device with --device. List what is attached:

metavr device list

Then pin the target with -d, the short form of --device, and the simulator’s serial. metavr ssim status also reports the serial:

metavr -d emulator-5554 capture screenshot -o app.png

Your app crashes on launch

Read logcat for the error.
Confirm your app targets API 34 (Android 14) or later.
The simulator does not include Google Play services, so an app that depends on GMS does not run.