Meta XR Mixed Reality Utility Kit (MR Utility Kit, MRUK, com.meta.xr.mrutilitykit)

The Meta XR Mixed Reality Utility Kit (MR Utility Kit, MRUK) is a Unity package that provides high-level tools on top of the Scene API for building scene-aware Mixed Reality (MR) experiences. It is designed to be used in conjunction with the Meta XR Core SDK. It handles scene data loading and querying, spawning prefabs on real-world surfaces, world locking to prevent anchor drift, environment raycasting for instant placement without scanning, passthrough camera access, NavMesh generation from room geometry, and trackable detection (keyboards, QR codes).

Package: com.meta.xr.mrutilitykit

Finding the SDK Source

The package com.meta.xr.mrutilitykit may be located in different places depending on the project setup:

• Library/PackageCache/com.meta.xr.mrutilitykit@<hash>/ (cached from registry)
• Packages/com.meta.xr.mrutilitykit/ (local package reference)
• A custom on-disk path (embedded or local folder)

Before searching for SDK source, first locate the package root by searching for a known file by filename pattern:

**/com.meta.xr.mrutilitykit*/Core/Scripts/MRUK.cs

Then use the resolved parent path for all subsequent search operations.

Quick Reference

All source file paths are relative to the package root (see "Finding the SDK Source" above).

Architecture

Object Hierarchy

MRUK (singleton MonoBehaviour)
 └── MRUKRoom (child GameObjects, one per room)
      └── MRUKAnchor (children of rooms: walls, floors, furniture, etc.)

• MRUK.Instance is the central hub. It loads scene data, manages rooms, handles world locking, and provides the SceneSettings configuration.
• MRUKRoom represents a physical room. Provides spatial queries (raycasting, position checks, surface queries) and holds Anchors, WallAnchors, FloorAnchors, CeilingAnchors, GlobalMeshAnchor.
• MRUKAnchor represents a single scene element (wall, table, couch, etc.). Has a Label (SceneLabels flags), optional PlaneRect (2D bounds), VolumeBounds (3D bounds), and PlaneBoundary2D (polygon points).
• MRUKTrackable extends MRUKAnchor for runtime-detected objects (keyboards, QR codes).

Native Library

A C/C++ shared library handles world locking, anchor discovery, and coordinate conversion (OpenXR right-handed ↔ Unity left-handed). A hidden MRUKGlobalContext MonoBehaviour (DontDestroyOnLoad) ticks the native context every frame. You never call these directly.

Component Pattern

All feature components (AnchorPrefabSpawner, EffectMesh, FindSpawnPositions, SceneNavigation, SpaceMapGPU, RoomGuardian, DestructibleGlobalMeshSpawner) follow the same pattern:

1. A SpawnOnStart / CreateOnStart / BuildOnSceneLoaded property of type MRUK.RoomFilter controls automatic initialization
2. In Start(), they call MRUK.Instance.RegisterSceneLoadedCallback(...) which fires immediately if the scene is already loaded
3. They also expose manual methods (CreateMesh(), StartSpawn(), BuildSceneNavMesh(), etc.) for programmatic control

Dependencies

• Required: com.meta.xr.sdk.core (OVRCameraRig, OVRPlugin, OVRSpatialAnchor, OVRSemanticLabels)
• com.unity.ai.navigation (for SceneNavigation)
• com.unity.nuget.newtonsoft-json (for JSON scene serialization)

Key Enums

MRUKAnchor.SceneLabels (Flags)

FLOOR, CEILING, WALL_FACE, TABLE, COUCH, DOOR_FRAME, WINDOW_FRAME,
OTHER, STORAGE, BED, SCREEN, LAMP, PLANT, WALL_ART, GLOBAL_MESH,
INVISIBLE_WALL_FACE, UNKNOWN, INNER_WALL_FACE

Use as flags: SceneLabels.TABLE | SceneLabels.COUCH matches tables OR couches.

MRUKAnchor.ComponentType (Flags)

None = 0, Plane = 1, Volume = 2, All = Plane | Volume

Anchors can have plane geometry (2D rect), volume geometry (3D bounds), or both.

MRUK.SceneDataSource

Device                    // Load from device Scene API
Prefab                    // Load from room prefab GameObjects
DeviceWithPrefabFallback  // Device first, prefab if no scene data (recommended for dev)
Json                      // Load from JSON string
DeviceWithJsonFallback    // Device first, JSON if no scene data

MRUK.SurfaceType (Flags)

FACING_UP = 1    // Floors, table tops
FACING_DOWN = 2  // Ceilings, undersides
VERTICAL = 4     // Walls

MRUK.RoomFilter

None             // Don't auto-initialize
CurrentRoomOnly  // Only the room the user is in
AllRooms         // All loaded rooms

MRUK.SceneModel

V1               // Standard scene model
V2               // High Fidelity: multiple floors/ceilings, slanted ceilings, inner walls
V2FallbackV1     // Try V2, fall back to V1 if unsupported

LabelFilter

Struct for filtering anchors by label and component type. Used in raycast, surface query, and spawn methods.

var filter = new LabelFilter(SceneLabels.TABLE | SceneLabels.COUCH, ComponentType.Volume);
bool passes = filter.PassesFilter(anchor.Label);

MRUK.PositioningMethod

DEFAULT  // Standard positioning
CENTER   // Center of surface (e.g., center of table for chess board)
EDGE     // Edge of surface (e.g., edge of table for piano)

Core Classes

MRUK (Singleton)

Key Properties: Instance (static), IsInitialized, Rooms (List<MRUKRoom>), EnableWorldLock, IsWorldLockActive, TrackingSpaceOffset, SceneSettings

Key Methods:

• GetCurrentRoom() → MRUKRoom
• RegisterSceneLoadedCallback(UnityAction) — fires immediately if already loaded
• LoadSceneFromDevice(SceneModel) → Task<LoadDeviceResult>
• LoadSceneFromPrefab(GameObject) → Task<LoadDeviceResult>
• LoadSceneFromJsonString(string) → Task<LoadDeviceResult>
• SaveSceneToJsonString() → string
• ClearScene()
• HasSceneModel() → Task<bool> (static, checks if device has scene data)
• ShareRoomsAsync(...), LoadSceneFromSharedRooms(...) — co-located multiplayer

Events: SceneLoadedEvent, RoomCreatedEvent, RoomUpdatedEvent, RoomRemovedEvent

MRUKSettings (serialized config): DataSource, RoomPrefabs[], SceneJsons[], LoadSceneOnStartup, EnableHighFidelityScene, SeatWidth, TrackerConfiguration

MRUKRoom

Key Properties: Anchors, WallAnchors, FloorAnchors, CeilingAnchors, GlobalMeshAnchor, IsLocal, RoomMeshData

Key Methods:

• Raycast(Ray, float, out RaycastHit, out MRUKAnchor) — collisionless raycast against scene geometry
• RaycastAll(...) — all intersections
• IsPositionInRoom(Vector3), IsPositionInSceneVolume(Vector3)
• TryGetClosestSurfacePosition(Vector3, out Vector3, out MRUKAnchor, LabelFilter) → float (distance)
• GenerateRandomPositionOnSurface(SurfaceType, float, LabelFilter, out Vector3, out Vector3) → bool
• GenerateRandomPositionInRoom(float, bool) → Vector3?
• FindLargestSurface(SceneLabels) → MRUKAnchor
• GetRoomBounds() → Bounds
• GetKeyWall(out Vector2, float) → MRUKAnchor (widest wall facing room center)

Events: AnchorCreatedEvent, AnchorUpdatedEvent, AnchorRemovedEvent

MRUKAnchor

Key Properties: Label (SceneLabels), PlaneRect (Rect?), VolumeBounds (Bounds?), PlaneBoundary2D (List<Vector2>), Room (MRUKRoom), ParentAnchor, ChildAnchors, GlobalMesh (Mesh)

Key Methods:

• Raycast(Ray, float, out RaycastHit, ComponentType) — collisionless raycast
• HasAnyLabel(SceneLabels) → bool
• GetAnchorCenter() → Vector3
• GetClosestSurfacePosition(Vector3, out Vector3, out Vector3, ComponentType) → float
• IsPositionInVolume(Vector3), IsPositionInBoundary(Vector2)

MRUKTrackable (extends MRUKAnchor)

Runtime-tracked objects (keyboards, QR codes). Managed by MRUK via SceneSettings.TrackerConfiguration.

Key Properties: TrackableType (OVRAnchor.TrackableType), IsTracked, MarkerPayloadString, MarkerPayloadBytes

Events on SceneSettings: TrackableAdded, TrackableRemoved

Feature Components

AnchorPrefabSpawner (Scripts/AnchorPrefabSpawner.cs)

Spawns prefabs on scene anchors based on labels. Configure PrefabsToSpawn (List<AnchorPrefabGroup>) mapping labels to prefab lists with scaling/alignment modes.

AnchorPrefabGroup: Labels, Prefabs, PrefabSelection (Random/ClosestSize/Custom), Scaling (Stretch/UniformScaling/UniformXZScale/NoScaling/Custom), Alignment (Automatic/Bottom/Center/NoAlignment/Custom), MatchAspectRatio, CalculateFacingDirection

Methods: SpawnPrefabs(), SpawnPrefabs(MRUKRoom), ClearPrefabs()

FindSpawnPositions (Scripts/FindSpawnPositions.cs)

Generates random valid positions for spawning objects. Supports floating, surface-mounted, and hanging positions with physics overlap checking.

SpawnLocation enum: Floating, AnySurface, VerticalSurfaces, OnTopOfSurfaces, HangingDown

Key props: SpawnObject, SpawnAmount, MaxIterations, Labels, CheckOverlaps, SurfaceClearanceDistance

GridSliceResizer (Scripts/GridSliceResizer.cs)

27-slice 3D mesh resizer (3D analogue of 9-slice). Preserves mesh borders/corners while stretching the interior to match anchor dimensions. Attach to prefabs used with AnchorPrefabSpawner.

EffectMesh (Scripts/EffectMesh.cs)

Generates visual meshes from scene anchors. Supports materials, colliders, hole cutting (for doors/windows), shadow casting, and visibility toggling.

Key props: MeshMaterial, Colliders, CutHoles (SceneLabels to cut holes for), CastShadow, HideMesh

Methods: CreateMesh(), DestroyMesh(), ToggleEffectMeshVisibility(bool), ToggleEffectMeshColliders(bool)

Passthrough Relighting (PTRL)

Casts virtual lights' shadows and highlights onto real-world surfaces by rendering an EffectMesh with the Meta/MRUK/Scene/HighlightsAndShadows shader (TransparentSceneAnchor.mat). Silent-failure heavy — the most common gotcha is the URP Renderer asset's Transparent Receive Shadows flag must be ON, otherwise shadows never appear on the floor.

For setup, URP/EffectMesh/passthrough requirements, common failure modes, and editor verification, see references/passthrough-relighting.md.

DestructibleGlobalMeshSpawner (Scripts/DestructibleGlobalMeshSpawner.cs)

Segments the global mesh into breakable fragments using Voronoi-based segmentation.

Key props: GlobalMeshMaterial, PointsPerUnitX/Y/Z (density), ReservedTop/Bottom (unbreakable zones)

SpaceMapGPU (Scripts/SpaceMapGPU.cs)

GPU-computed 2D top-down distance field of the room layout. Outputs to RenderTexture.

Key props: TextureDimension, MapGradient; Methods: GetSpaceMap() → RenderTexture, GetColorAtPosition(Vector3) → Color

Sets shader global _SpaceMapProjectionViewMatrix for UV calculation.

RoomGuardian (Scripts/RoomGuardian.cs)

Fades a boundary material as the user approaches room walls. Sets _GuardianFade float on the material.

Key props: GuardianMaterial, GuardianDistance (meters, default 1.0)

SceneNavigation (Scripts/SceneNavigation.cs)

Generates Unity NavMesh from scene geometry. Requires com.unity.ai.navigation.

Key props: NavigableSurfaces (SceneLabels), Agents (List<NavMeshAgent>), AgentRadius

Events: OnNavMeshInitialized

For more info see references/scene-navigation.md.

EnvironmentRaycastManager (Scripts/EnvironmentRaycastManager.cs)

Depth API raycasting against the physical environment without requiring pre-scanned scene data. Requires Quest 3+. Namespace: Meta.XR.

Check EnvironmentRaycastManager.IsSupported before use.

Methods: Raycast(Ray, out EnvironmentRaycastHit, float), PlaceBox(Ray, Vector3, Vector3, out EnvironmentRaycastHit), CheckBox(Vector3, Vector3, Quaternion)

PassthroughCameraAccess (Scripts/PassthroughCameraAccess.cs)

Raw passthrough camera image access. Requires horizonos.permission.HEADSET_CAMERA in AndroidManifest. Quest 3+ only. Namespace: Meta.XR.

Key props: CameraPosition (Left/Right), RequestedResolution, MaxFramerate, TargetMaterial

Methods: GetTexture() → Texture, GetColors() → NativeArray<Color32> (expensive), GetCameraPose() → Pose, ViewportPointToRay(), WorldToViewportPoint()

Struct CameraIntrinsics: FocalLength, PrincipalPoint, SensorResolution, LensOffset

Instant Content Placement (Scripts/BuildingBlocks/InstantContentPlacement/)

Building block scripts using EnvironmentRaycastManager for device-scan-free placement:

• SpaceLocator (abstract): TryLocateSpace(out Pose), OnSpaceLocateCompleted event, PreferredSurfaceOrientation
• PointAndLocate: raycast from a Transform, Locate() method
• GrabAndLocate: grab-and-release placement via Interaction SDK
• PlaceWithAnchor: creates OVRSpatialAnchor at placed position to prevent drift

Common Patterns

Scene Loaded Callback

void Start()
{
    MRUK.Instance.RegisterSceneLoadedCallback(OnSceneLoaded);
}

void OnSceneLoaded()
{
    var room = MRUK.Instance.GetCurrentRoom();
    // Scene is ready — query anchors, spawn objects, etc.
}

RegisterSceneLoadedCallback fires immediately if the scene is already loaded — safe to call at any time.

Iterating Anchors with LabelFilter

var room = MRUK.Instance.GetCurrentRoom();
foreach (var anchor in room.Anchors)
{
    if (anchor.HasAnyLabel(MRUKAnchor.SceneLabels.TABLE | MRUKAnchor.SceneLabels.STORAGE))
    {
        Debug.Log($"{anchor.Label} at {anchor.GetAnchorCenter()}");
    }
}

Raycasting Against Room Geometry

var room = MRUK.Instance.GetCurrentRoom();
var ray = new Ray(origin, direction);
if (room.Raycast(ray, Mathf.Infinity, out var hit, out var anchor))
{
    Debug.Log($"Hit {anchor.Label} at {hit.point}, normal {hit.normal}");
}

Editor Testing with Prefab Fallback

Set MRUK.SceneSettings.DataSource to DeviceWithPrefabFallback and assign room prefabs in SceneSettings.RoomPrefabs. On device, real scene data is used. In editor (no device), prefab rooms load automatically. The package includes ~50 sample room prefabs under Core/Rooms/Prefabs/ (Bedroom, LivingRoom, Office, LargeScale).

Project Setup

1. Install com.meta.xr.mrutilitykit package
2. In OVRManager > Quest Features, set Scene Support to "Required"
3. In OVRManager > Quest Features, enable Anchor Support
4. Ensure OVRCameraRig is in the scene
5. Add an MRUK GameObject with the MRUK component to the scene
6. Configure SceneSettings.DataSource (use DeviceWithPrefabFallback for development)
7. For PassthroughCameraAccess: add horizonos.permission.HEADSET_CAMERA to AndroidManifest and regenerate via OVRManifestPreprocessor.GenerateOrUpdateAndroidManifest(true) — silentMode: true is required, or the generator opens a modal dialog that blocks the request. See hz-unity-meta-core-sdk for the full manifest workflow.

Running MRUK code — drive a live Editor with unity-cli

MRUK setup is Editor-only C#. Run it against an open Editor rather than hand-editing scene or settings files:

unity status --format json          # look for state "ready"
unity command run_script --file AgentScripts/SetupMRUK.cs --entry SetupMRUK.Run --format json

Keep the .cs outside Assets/ (path relative to the project root) so writing it triggers no import or domain reload, and add --dry_run true to compile-check before mutating anything.

run_script references every loaded assembly, so the Meta.XR.MRUtilityKit namespace is directly referenceable — no reflection:

// AgentScripts/SetupMRUK.cs
using Meta.XR.MRUtilityKit;

public static class SetupMRUK
{
    public static string Run()
    {
        var room = MRUK.Instance.GetCurrentRoom();
        return room == null ? "no current room" : $"room: {room.name}";
    }
}

• using System.Reflection; and BindingFlags overloads both work here, so reflection is only for genuinely non-public members.
• Anything async completes after the script returns — verify in a separate follow-up run_script, never Task.Wait() on the main thread.
• Finish scene changes with EditorSceneManager.MarkSceneDirty + SaveScene, or unity command save_scene, then read the value back.

MRUK is a runtime system, so most of it only produces data in Play mode. Drive that from the CLI:

unity command clear_console --format json
unity command editor_play --format json           # blocks until play mode is live
unity command get_console_logs --severity error --format json
unity command editor_stop --format json

Give the scene time before stopping. editor_play returns once play mode is live, not once MRUK has finished — LoadSceneFromDevice / LoadSceneFromPrefab return a Task, and EffectMesh, SceneNavigation and friends only run off SceneLoadedEvent. Stopping straight away truncates all of it. Poll get_console_logs (or a run_script reading MRUK.Instance.IsInitialized) until the scene has loaded, and only then read errors and stop.

Connecting, --project-path, and Safe Mode recovery are in the unity-cli skill. The reflection-based MCP version is in references/unity-mcp-fallback.md.

Using metavr Tools for Latest Docs

If the metavr MCP server is available, use the mcp__metavr__vr_docs_search and mcp__metavr__vr_docs_get_page tools to verify current API details, as Meta SDK documentation updates frequently. Use mcp__metavr__vr_api_search with engine='unity' to look up exact method signatures for MRUK, MRUKRoom, MRUKAnchor, and other classes. The same backend is reachable from the CLI: metavr docs search "<topic>" and metavr docs api-search "<Class.method>".

Documentation Links

• MR Utility Kit Overview
• MRUK API Reference
• GitHub Samples (12 sample scenes, moved from package since v76)
• Scene API Overview