Use Instant Preview to skip the build process and test ARCore apps instantly on your phone. Click Play in Unity to preview your app using real input and output from your phone.
Instant Preview consists of an Android app for your ARCore-supported phone and a plugin for Unity.
Instant Preview is supported on Windows (discrete GPUs only) and OSX
On Windows machines with an integrated GPU, the Unity Editor's video feed is not mirrored back to your phone.
To use Instant Preview, you'll need:
A USB cable to connect your phone to your development machine
- ARCore SDK for Unity version 1.1.0 or later
- Unity 2017.3.0f2 or later
- Android SDK version 7.0 (API Level 24) or higher.
See the ARCore SDK for Unity quickstart guide for complete details on software version requirements and installation.
Use Instant Preview in Unity
This guide assumes that you have already created an ARCore project in Unity. If you are new to working with ARCore, see the ARCore SDK for Unity quickstart guide for installation and setup steps.
Set up Instant Preview
Open your ARCore scene in the Unity Editor.
Connect your phone to your development machine via USB. Make sure that developer options and debugging are enabled on your phone.
Click Play in the Unity Editor. The Instant Preview app launches and your ARCore scene starts streaming.
If you see a dialog on your computer or phone asking if you want to install the Instant Preview Android app, click or tap Okay to confirm.
If you do not have a recent enough version of ARCore installed on your phone, you might be sent to the Play Store to install ARCore before continuing.
Move your phone around to detect planes, place objects, or use other ARCore functionality that you are testing in your app.
See Handle input from your phone for details on previewing touch input in Instant Preview.
Click Pause in the Unity Editor or tap the system back button on your phone to stop streaming and exit the preview.
(Optional) You can change your streaming configuration to Wi-Fi while your app is paused.
Handle input from your phone
In Instant Preview, touch input on your app's AR scene does not automatically propagate input events to your Unity implementation.
To set up touch input propagation, use the
in any controller script that references the Unity
Input class. Add the
following code to the top of the controller script:
#if UNITY_EDITOR // NOTE: // - InstantPreviewInput does not support `deltaPosition`. // - InstantPreviewInput does not support input from // multiple simultaneous screen touches. // - InstantPreviewInput might miss frames. A steady stream // of touch events across frames while holding your finger // on the screen is not guaranteed. // - InstantPreviewInput does not generate Unity UI event system // events from device touches. Use mouse/keyboard in the editor // instead. using Input = InstantPreviewInput; #endif
As an example, the demo scene's HelloAR Controller
InstantPreviewInput to detect and propagate touch input events.
InstantPreviewInput class is similar to Unity's
Stream over a Wi-Fi connection
Instant Preview works the same way when streaming over USB or Wi-Fi.
By default, Instant Preview uses USB. Streaming over USB is best for longer development sessions.
Use Wi-Fi for shorter testing sessions or when a USB cable would restrict the phone movement that you need.
To stream over Wi-Fi:
Make sure that your phone and development machine are connected to the same Wi-Fi network.
Make sure that your network is configured for Instant Preview:
- Any firewall software on your development system must be configured to allow Unity to accept TCP connections on port 49838.
- Your router and/or network firewall must disable client isolation so that your phone and development machine can communicate directly with each other over your network.
- Your router and/or network firewall must allow broadcast traffic from your development machine to multicast address 184.108.40.206 on port 49838.
Make sure that Instant Preview is enabled. In Unity, verify that Instant Preview Enabled is checked in Edit > Project Settings > ARCore.
Click Play in the Unity Editor. This makes your development machine discoverable in the Instant Preview app on your phone.
On your phone, open the ARCore Instant Preview app. Follow the Set up Instant Preview steps to install this app if it is not currently installed.
On your phone, tap the "Preview via…" dropdown in the app.
- Your development machine should be listed as one of the available devices under the name of the Wi-Fi network that your phone is using. See Troubleshooting if your phone is not listed.
- Select your development machine to begin streaming.
- Use Play and Stop in the Unity Editor to start and stop streaming.
Disable Instant Preview
Instant Preview is enabled by default. To disable Instant Preview in the
Unity Editor, go to
Edit > Project Settings > ARCore and uncheck Instant Preview Enabled.
Instant Preview mirrors the game window on your phone. Set your window aspect ratio to match the phone you're using for testing. If the aspect ratio does not match, your app might appear stretched in your game window or on your phone.
Use Metal in OSX
If you are working in OSX, use Metal for rendering instead of OpenGL. Go to Player Settings > Settings for PC, Mac & Linux Standalone > Other Settings > Metal Editor Support to enable Metal rendering.
- Check for Instant Preview errors in the Unity Console.
Additionally, make sure that:
Another instance of Unity using Instant Preview is not running. Only one instance can run at the same time.
Instant Preview is enabled in your project. Make sure that Instant Preview Enabled is checked in Edit > Project Settings > ARCore.
Your phone is connected to your computer via USB or Wi-Fi.
Your phone is unlocked, with developer options and debugging enabled.
In Unity's Build Settings, your build platform is set to Android and you have player settings enabled for ARCore. If not, see the Unity quickstart guide for configuration details.
When you click Play in Unity, the Console displays Instant Preview version <version_number>.
If you are streaming via Wi-Fi:
Check your network and firewall settings.
On Windows development machines:
Open the Windows Firewall with Advanced Security management panel and delete any references to Unity in the Incoming or Outgoing rules.
Relaunch Unity and allow connections when prompted by Windows.
If you don't have a suitable Wi-Fi network, you might be able to use your phone as a hotspot:
On your phone, disable mobile data to prevent your development machine from using mobile data over the hotspot.
Configure and enable a secure Wi-Fi hotspot on your phone.
On your development machine, connect to the Wi-Fi hotspot on your phone.
Even without an internet connection, your development machine and phone should be able to establish an Instant Preview connection.
Instant Preview has the following limitations.
Activity pause/resume events not supported
App activity pause events that pause and resume the ARCore Session are not supported when using Instant Preview.
ARCore Session configuration changes not supported
Session configuration cahnges such as disabling light estimation and plane finding are not supported when using Instant Preview.
Limited support for touch input
InstantPreviewInput does not support:
- Input from multiple simultaneous screen touches in one frame.
- Long presses: A steady stream of touch events across frames while holding your finger on the phone screen might cause frames to be missed.
- Unity UI event system events: Use your mouse or keyboard to interact with these elements directly in the Unity Editor.
Screen orientation settings and auto rotation not supported
Instant Preview does not support auto-rotation of the preview window. In Unity, Player Settings > Android > Resolution & Presentation > Orientation settings also do not affect streaming orientation.
Instead, Instant Preview selects an orientation matching the aspect ratio of your game window when streaming starts.
To change the preview orientation:
- Exit Play mode in the Unity Editor.
- Use the system back button on your phone to:
- Stop streaming
- Background the Instant Preview app. You should not see the Instant Preview configuration menu on your phone screen.
In Unity, change the game view aspect ratio to portrait or landscape resolution. To avoid stretching, use an aspect resolution that matches the resolution of your phone.
Click "Play" in Unity. The app will start running again with orientation matching the game window aspect ratio you selected.