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

RequirementMinimum
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

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

Install from the command line

  1. Install Meta VR CLI (metavr). That page covers the native installer and npm.
  2. 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. 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

  1. Start Meta Spatial Simulator. The device appears in Android Studio only while the simulator is running.
  2. Select Meta Spatial Simulator in the device dropdown in the Android Studio toolbar.
  3. 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.
  1. Install and launch your APK:
    metavr app install path/to/your-app.apk
metavr app launch com.example.myapp
  2. 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

What you can also test

The simulator also covers:
  • Platform SDK testing: user management, in-app purchases, group presence, and application lifecycle, in a sandbox.
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.
Nav Logo
English (US)
© 2026 Meta