XR Simulation environments

XR Simulation environments are prefabs that contain the geometry of the environment as well as preconfigured components that control the simulation behavior. AR Foundation detects trackables in XR Simulation environments such as planes, images, and point clouds as if the environment were a physical space.

Create and edit XR Simulation environments

You can create, duplicate, or edit an XR Simulation environment prefab using the XR Environment view.

Create/edit environment dropdown in the XR Environment view

Create or edit an environment prefab

1. Go to Window > XR > AR Foundation > XR Environment to open the XR Environment view.
2. Optionally select an environment from the Environment dropdown if you wish to duplicate or edit that environment.
3. Click the Create/edit environment dropdown on the far right of the XR Environment overlay.
4. Click one of the following options:
   • Create environment: Create and save a new environment using the default XR Simulation environment as a template.
   • Duplicate environment: Create and save a copy of the active environment.
   • Edit environment: Open the active environment for editing in Prefab Mode.

Convert an existing prefab into an environment

1. Open any prefab for editing in Prefab Mode.
2. Add a Simulation Environment component to the root GameObject of the prefab. XR Simulation requires that the prefab only have one root GameObject.
3. You can optionally add additional XR Simulation components, such as a Simulated Tracked Image component, as needed to test your app's features.
4. Save the Prefab.
5. Refresh the Environment list in the XR Environment view by going to Assets > Refresh XR Environment List.

Tip

Since XR Simulation environments are prefabs, you can use any of the standard tools in the Unity Editor to create and edit them. The only requirement for a prefab to be considered an XR Simulation environment is for its root GameObject to have a Simulation Environment component attached.

Components and shaders

AR Foundation contains the following components and shaders you can use to create XR Simulation environments:

Component or shader		Description
Simulation Environment component		Add to the root GameObject of a prefab to designate it as an XR Simulation environment. XR Simulation automatically finds environment prefabs and adds them to the Environment list in the XR Environment view.
Simulated Tracked Image component		Add to a GameObject in an XR Simulation environment to designate it as a simulated tracked image for image tracking purposes.
Simulated Environment Probe component		Add to a GameObject in an XR Simulation environment to designate it as a simulated environment probe. At runtime this GameObject will appear as an automatically placed environment probe.
Simulated Anchor component		Add to a GameObject in an XR Simulation environment to designate it as a simulated anchor. At runtime this GameObject will appear as a pre-existing anchor in the environment.
Simulated Light component		Add to a GameObject in an XR Simulation environment to designate it as a simulated light. At runtime this GameObject will be used for lighting estimation.
X-ray rendering		Add the X Ray Region component and x-ray shaders to an XR Simulation environment to make it easier to prevent the camera from being obstructed by exterior walls.
	X Ray Region component	Defines the active area for any x-ray shaders in the scene.
	X-ray shaders	Shaders that clip exterior surfaces, allowing the camera to easily see into interior rooms from outside the walls.

Simulation Environment component

Add a Simulation Environment component to the root GameObject of a prefab to designate it as an XR Simulation environment. You can view and edit its properties in the Inspector window as shown:

Simulation Environment component

Property	Description
Camera Starting Pose	The position and rotation to spawn the camera in the environment when you enter Play mode. This pose is illustrated in the XR Environment view with a blue camera line drawing.
Camera Movement Bounds	The navigable area within the environment.
Default View Pose	The default scene camera position and orientation when previewing the environment in the XR Environment view.
Default View Pivot	The default pivot location of the scene camera when previewing the environment in the XR Environment view.
Default View Size	The default scene camera orbit radius when previewing the environment in the XR Environment view.
Render Settings	The RenderSettings object for rendering the environment.
Exclude from Selection UI	Hides the environment from the Environment dropdown menu in the XR Environment view.

Tip

If you have a base prefab in your project that serves as the basis for other environments, but should not be used itself, set Exclude from Selection UI to true. When this option is enabled, the prefab is hidden from the Environment dropdown in the XR Environment view.

Simulated Tracked Image component

Add a Simulated Tracked Image component to a GameObject in your XR Simulation environment to designate it as a simulated tracked image. Simulated tracked images simulate AR Foundation's image tracking feature, and you can respond to detected images in XR Simulation environments the same way that you would on device.

Simulated Tracked Image component

XR Simulation can detect and track all simulated tracked images in an environment, even if you have not included their textures in your reference image library. To optionally bind a simulated tracked image to your reference image library, set the Image field of its Simulated Tracked Image component to reference a texture asset that is also used in the reference image library.

When XR Simulation detects images that are not part of the reference image library, the corresponding ARTrackedImage trackables will not contain a fully initialized referenceImage. Instead, the guid property of the referenceImage is set to zero, and its texture is set to null.

Property	Description
Image	A reference to the Texture2D asset of the image. Optionally, this can also match a texture asset in your reference image library.
Image Physical Size Meters	The size in meters of the image in the environment. This influences the distance at which an image can be detected by the simulated device. Set this value to the expected size of the image in the real world.

Simulated Tracked Image setup

For XR Simulation to track images properly, a simulated tracked image's transform must be orientated such that its local y-axis (the green arrow) points in the same direction as the image surface normal: perpendicular to the image plane with its positive direction pointing forward from the image. Likewise, a tracked image's z-axis (the blue arrow) must point upward to the top of the image. See the example simulated tracked image below as a reference:

An example simulated tracked image with green arrow pointing forward and blue arrow pointing up

To help you visualize simulated tracked images in your XR Simulation environments, the Simulated Tracked Image component adds MeshFilter and MeshRenderer components to your GameObject and uses them to render a textured mesh. Use this textured mesh to help you set up your image:

• Size: Set the mesh size with the Image Physical Size Meters property.
• Texture: Set the mesh texture with the Image property.
• Placement: Move and rotate the GameObject so that the textured mesh is oriented correctly in your environment.

Note

Visually representing a simulated tracked image in an XR Simulation environment is optional. XR Simulation only uses the Simulated Tracked Image component to detect and track images. It does not use textured meshes rendered in the environment for this purpose. You can disable the Mesh Renderer component on the image GameObject if you prefer not to render the image mesh.

Simulated Environment Probe component

Add a Simulated Environment Probe component to a GameObject in your XR Simulation environment to designate it as a simulated environment probe. Simulated environment probes simulate automatic placement of environment probes.

Simulated Environment Probe component

Property	Description
Cubemap	An optional pre-existing user-generated Cubemap asset. If not set, a Cubemap will be generated when the environment probe is discovered during simulation.
Size	Size in meters of the simulated environment probe. Sets both the box size of the underlying Reflection Probe and the bounds for discovery.

Simulated Anchor component

Add a Simulated Anchor component to a GameObject in your XR Simulation to designate the GameObject as a simulated anchor.

Simulated anchors simulate loading existing anchors using automatically supplied AR data outside of the users control.

A simulated anchor requires no additional configuration. Anchor Pose data comes from its GameObject's Transform component.

Simulated Light component

Add a Simulated Light component to a GameObject in your XR Simulation to designate it as a simulated light. Simulated lights supply data to AR Foundation's light estimation API, which your app can access via the ARLightEstimationData object passed by ARCameraManager.frameReceived.

A simulated light requires no additional configuration. Light data comes from its GameObject's Light component.

X-ray rendering

XR Simulation provides specialized x-ray shaders that allow the camera to see through exterior walls as you navigate around the environment. This x-ray perspective can make it easier to test your app by preventing your camera view from being obstructed as you move around.

Bedroom environment with x-ray shader

To enable x-ray rendering, use the Simulation/Room X-Ray shader on your exterior walls, ceiling and floor. You must also add an X Ray Region component to a GameObject in your environment.

X-ray shaders

Add the Simulation/Room X-Ray shader to the walls and ceilings of enclosed environments, such as rooms, to clip exterior walls in the AR Environment view. Find the Room X-Ray shader under Simulation in the Shader menu of a material asset.

Simulation shader menu

Note

You do not need to select the Legacy or URP versions of the shader directly. The Simulation/Room X-Ray shader falls back to the URP or legacy built-in versions as needed.

The XR Simulation sample environments include materials that use the X-ray shaders. If you have installed the sample environments, you can use these materials, which are located in the Assets folder under UnityXRContent/ARFoundation/SimulationEnvironments/Common/Materials.

X Ray Region component

The X Ray Region component defines information used by the X-ray shaders.

X Ray Region component

Property	Description
Floor Height	The floor in local coordinates.
Ceiling Height	The ceiling in local coordinates.
Clip Offset	How much the camera clipping plane moves forward from the center of this region.
View Bounds	The size of the x-ray clipping region.

Tip

In the sample environments, the GameObjects with X-Ray Region components attached are named ClippingRegion.