hz-unity-meta-mixed-reality-utility-kit

Meta XR Mixed Reality Utility Kit（MR Utility Kit、MRUK、com.meta.xr.mrutilitykit）

Meta XR Mixed Reality Utility Kit（MR Utility Kit、MRUK）は、Scene API を基盤として、シーン認識型の Mixed Reality（MR）体験を構築するための高レベルなツールを提供する Unity パッケージです。Meta XR Core SDK と併用するように設計されています。 シーンデータの読み込みとクエリ、現実世界のサーフェスへのプレハブのスポーン、アンカーのドリフトを防ぐワールドロック、スキャンせずに即座に配置できる環境レイキャスト、パススルーカメラへのアクセス、部屋のジオメトリからの NavMesh 生成、トラッカブルの検出（キーボード、QR コード）を処理します。

パッケージ：com.meta.xr.mrutilitykit

SDK ソースの検索

com.meta.xr.mrutilitykit パッケージの場所は、プロジェクトの設定によって異なる場合があります。

• Library/PackageCache/com.meta.xr.mrutilitykit@<hash>/（レジストリからキャッシュされたもの）
• Packages/com.meta.xr.mrutilitykit/（ローカルパッケージ参照）
• カスタムのディスク上のパス（埋め込みまたはローカルフォルダー）

SDK ソースを検索する前に、まず既知のファイル名パターンでファイルを検索し、パッケージルートを特定してください。

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

次に、以降のすべての検索操作で、解決した親パスを使用してください。

クイックリファレンス

タスク	クラス／コンポーネント	ソースファイル	主なエントリーポイント
デバイスからシーンを読み込む	MRUK	Scripts/MRUK.cs	LoadSceneFromDevice()
プレハブ／JSON からシーンを読み込む	MRUK	Scripts/MRUK.cs	LoadSceneFromPrefab()、LoadSceneFromJsonString()
現在の部屋を取得する	MRUK	Scripts/MRUK.cs	GetCurrentRoom()
アンカーのドリフトを防ぐ	MRUK	Scripts/MRUK.cs	EnableWorldLock = true
部屋のジオメトリをクエリする	MRUKRoom	Scripts/MRUKRoom.cs	Raycast()、IsPositionInRoom()
サーフェス／最も近い点を検索する	MRUKRoom	Scripts/MRUKRoom.cs	TryGetClosestSurfacePosition()、GenerateRandomPositionOnSurface()
アンカーのプロパティを取得する	MRUKAnchor	Scripts/MRUKAnchor.cs	Label、PlaneRect、VolumeBounds
アンカーにプレハブをスポーンする	AnchorPrefabSpawner	Scripts/AnchorPrefabSpawner.cs	PrefabsToSpawn、SpawnOnStart
ランダムなスポーン位置を検索する	FindSpawnPositions	Scripts/FindSpawnPositions.cs	StartSpawn()、SpawnLocations
27 スライスメッシュのサイズ変更	GridSliceResizer	Scripts/GridSliceResizer.cs	ResizeTo(Vector3)
ビジュアルメッシュを生成する	EffectMesh	Scripts/EffectMesh.cs	CreateMesh()、CutHoles
破壊可能なシーンジオメトリ	DestructibleGlobalMeshSpawner	Scripts/DestructibleGlobalMeshSpawner.cs	CreateOnRoomLoaded
GPU 距離フィールドテクスチャ	SpaceMapGPU	Scripts/SpaceMapGPU.cs	GetSpaceMap()、StartSpaceMap()
境界への近接フェード	RoomGuardian	Scripts/RoomGuardian.cs	GuardianDistance、GuardianMaterial
シーンから NavMesh を生成する	SceneNavigation	Scripts/SceneNavigation.cs	BuildSceneNavMesh()
Depth API のレイキャスト	EnvironmentRaycastManager	Scripts/EnvironmentRaycastManager.cs	Raycast()、PlaceBox()
パススルーカメラ画像	PassthroughCameraAccess	Scripts/PassthroughCameraAccess.cs	GetTexture()、GetCameraPose()
キーボード／QR コードをトラッキングする	MRUKTrackable	Scripts/MRUKTrackable.cs	TrackableType、MarkerPayloadString
即時配置（スキャン不要）	PointAndLocate	Scripts/BuildingBlocks/InstantContentPlacement/	TryLocateSpace()
部屋を共有する（マルチプレイヤー）	MRUK	Scripts/MRUK.cs	ShareRoomsAsync()、LoadSceneFromSharedRooms()

すべてのソースファイルパスはパッケージルートからの相対パスです（上記の「SDK ソースの検索」を参照）。

アーキテクチャ

オブジェクト階層

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

• MRUK.Instance は中心的なハブです。シーンデータを読み込み、ルームを管理し、ワールドロックを処理して、SceneSettings 設定を提供します。
• MRUKRoom は物理的なルームを表します。空間クエリ（レイキャスト、位置チェック、サーフェスクエリ）を提供し、Anchors、WallAnchors、FloorAnchors、CeilingAnchors、GlobalMeshAnchor を保持します。
• MRUKAnchor は単一のシーン要素（壁、テーブル、ソファなど）を表します。Label（SceneLabels フラグ）、任意の PlaneRect（2D 境界）、VolumeBounds（3D 境界）、PlaneBoundary2D（ポリゴンの点）を持ちます。
• MRUKTrackable は MRUKAnchor を拡張し、実行時に検出されたオブジェクト（キーボード、QR コード）を表します。

ネイティブライブラリ

C/C++ の共有ライブラリが、ワールドロック、アンカーの検出、座標変換（OpenXR の右手座標系 ↔ Unity の左手座標系）を処理します。非表示の MRUKGlobalContext MonoBehaviour（DontDestroyOnLoad）が、毎フレームネイティブコンテキストを更新します。これらを直接呼び出すことはありません。

コンポーネントパターン

すべての機能コンポーネント（AnchorPrefabSpawner、EffectMesh、FindSpawnPositions、SceneNavigation、SpaceMapGPU、RoomGuardian、DestructibleGlobalMeshSpawner）は、同じパターンに従います。

1. MRUK.RoomFilter 型の SpawnOnStart / CreateOnStart / BuildOnSceneLoaded プロパティで、自動初期化を制御します。
2. Start() で MRUK.Instance.RegisterSceneLoadedCallback(...) を呼び出します。このコールバックは、シーンがすでに読み込まれている場合は直ちに実行されます。
3. プログラムから制御するための手動メソッド（CreateMesh()、StartSpawn()、BuildSceneNavMesh() など）も公開します。

依存関係

• 必須：com.meta.xr.sdk.core（OVRCameraRig、OVRPlugin、OVRSpatialAnchor、OVRSemanticLabels）
• com.unity.ai.navigation（SceneNavigation 用）
• com.unity.nuget.newtonsoft-json（JSON シーンのシリアル化用）

主要な列挙型

MRUKAnchor.SceneLabels（フラグ）

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

フラグとして使用します：SceneLabels.TABLE | SceneLabels.COUCH は、テーブルまたはソファに一致します。

MRUKAnchor.ComponentType（フラグ）

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

アンカーは、平面ジオメトリ（2D 矩形）、ボリュームジオメトリ（3D 境界）、またはその両方を持つことができます。

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（フラグ）

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

ラベルとコンポーネントタイプでアンカーをフィルタリングする構造体です。レイキャスト、サーフェスクエリ、スポーンメソッドで使用します。

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)

コアクラス

MRUK（シングルトン）

主なプロパティ：Instance（static）、IsInitialized、Rooms（List<MRUKRoom>）、EnableWorldLock、IsWorldLockActive、TrackingSpaceOffset、SceneSettings

主なメソッド：

• GetCurrentRoom() → MRUKRoom
• RegisterSceneLoadedCallback(UnityAction) — シーンがすでに読み込まれている場合は直ちに実行されます
• LoadSceneFromDevice(SceneModel) → Task<LoadDeviceResult>
• LoadSceneFromPrefab(GameObject) → Task<LoadDeviceResult>
• LoadSceneFromJsonString(string) → Task<LoadDeviceResult>
• SaveSceneToJsonString() → string
• ClearScene()
• HasSceneModel() → Task<bool>（static。デバイスにシーンデータがあるかを確認します）
• ShareRoomsAsync(...)、LoadSceneFromSharedRooms(...) — 同一位置でのマルチプレイヤー

イベント：SceneLoadedEvent、RoomCreatedEvent、RoomUpdatedEvent、RoomRemovedEvent

MRUKSettings（シリアル化された設定）：DataSource、RoomPrefabs[]、SceneJsons[]、LoadSceneOnStartup、EnableHighFidelityScene、SeatWidth、TrackerConfiguration

MRUKRoom

主なプロパティ：Anchors、WallAnchors、FloorAnchors、CeilingAnchors、GlobalMeshAnchor、IsLocal、RoomMeshData

主なメソッド：

• Raycast(Ray, float, out RaycastHit, out MRUKAnchor) — シーンジオメトリに対する、衝突判定を伴わないレイキャスト
• RaycastAll(...) — すべての交差箇所
• IsPositionInRoom(Vector3)、IsPositionInSceneVolume(Vector3)
• TryGetClosestSurfacePosition(Vector3, out Vector3, out MRUKAnchor, LabelFilter) → float（距離）
• GenerateRandomPositionOnSurface(SurfaceType, float, LabelFilter, out Vector3, out Vector3) → bool
• GenerateRandomPositionInRoom(float, bool) → Vector3?
• FindLargestSurface(SceneLabels) → MRUKAnchor
• GetRoomBounds() → Bounds
• GetKeyWall(out Vector2, float) → MRUKAnchor（部屋の中心を向いている、最も幅の広い壁）

イベント：AnchorCreatedEvent、AnchorUpdatedEvent、AnchorRemovedEvent

MRUKAnchor

主なプロパティ：Label（SceneLabels）、PlaneRect（Rect?）、VolumeBounds（Bounds?）、PlaneBoundary2D（List<Vector2>）、Room（MRUKRoom）、ParentAnchor、ChildAnchors、GlobalMesh（Mesh）

主なメソッド：

• Raycast(Ray, float, out RaycastHit, ComponentType) — 衝突判定を伴わないレイキャスト
• HasAnyLabel(SceneLabels) → bool
• GetAnchorCenter() → Vector3
• GetClosestSurfacePosition(Vector3, out Vector3, out Vector3, ComponentType) → float
• IsPositionInVolume(Vector3)、IsPositionInBoundary(Vector2)

MRUKTrackable（MRUKAnchor を拡張）

キーボードや QR コードなど、実行時にトラッキングされるオブジェクトです。SceneSettings.TrackerConfiguration を通じて MRUK が管理します。

主なプロパティ：TrackableType（OVRAnchor.TrackableType）、IsTracked、MarkerPayloadString、MarkerPayloadBytes

SceneSettings のイベント：TrackableAdded、TrackableRemoved

機能コンポーネント

AnchorPrefabSpawner（Scripts/AnchorPrefabSpawner.cs）

ラベルに基づいてシーンアンカー上にプレハブを生成します。PrefabsToSpawn（List<AnchorPrefabGroup>）を設定し、ラベルを、スケーリングや配置モードを含むプレハブリストに対応付けます。

AnchorPrefabGroup：Labels、Prefabs、PrefabSelection（Random/ClosestSize/Custom）、Scaling（Stretch/UniformScaling/UniformXZScale/NoScaling/Custom）、Alignment（Automatic/Bottom/Center/NoAlignment/Custom）、MatchAspectRatio、CalculateFacingDirection

メソッド：SpawnPrefabs()、SpawnPrefabs(MRUKRoom)、ClearPrefabs()

FindSpawnPositions（Scripts/FindSpawnPositions.cs）

オブジェクトを生成するための、有効なランダム位置を生成します。浮遊、面への設置、吊り下げに対応し、物理演算による重なり判定も行います。

SpawnLocation 列挙型：Floating、AnySurface、VerticalSurfaces、OnTopOfSurfaces、HangingDown

主なプロパティ：SpawnObject、SpawnAmount、MaxIterations、Labels、CheckOverlaps、SurfaceClearanceDistance

GridSliceResizer（Scripts/GridSliceResizer.cs）

27 スライス方式の 3D メッシュリサイザー（9 スライス方式の 3D 版）です。アンカーの寸法に合わせて内部を引き伸ばしながら、メッシュの境界や角を維持します。AnchorPrefabSpawner で使用するプレハブにアタッチします。

EffectMesh（Scripts/EffectMesh.cs）

シーンアンカーからビジュアルメッシュを生成します。マテリアル、コライダー、穴あけ（ドアや窓用）、シャドウの投影、表示の切り替えに対応しています。

主なプロパティ：MeshMaterial、Colliders、CutHoles（穴をあける対象の SceneLabels）、CastShadow、HideMesh

メソッド：CreateMesh()、DestroyMesh()、ToggleEffectMeshVisibility(bool)、ToggleEffectMeshColliders(bool)

パススルー・リライティング（PTRL）

Meta/MRUK/Scene/HighlightsAndShadows シェーダー（TransparentSceneAnchor.mat）を使って EffectMesh をレンダリングすることで、仮想ライトのシャドウやハイライトを現実世界の面に投影します。設定ミスがあってもエラーが表示されないことが多く、最もよくある見落としは URP の Renderer アセットで Transparent Receive Shadows フラグを ON にする必要があることです。そうしないと、床にシャドウが表示されません。

セットアップ、URP／EffectMesh／パススルーの要件、よくある失敗例、エディターでの検証については、references/passthrough-relighting.md を参照してください。

DestructibleGlobalMeshSpawner (Scripts/DestructibleGlobalMeshSpawner.cs)

グローバルメッシュをボロノイベースのセグメンテーションで、破壊可能なフラグメントに分割します。

主なプロパティ：GlobalMeshMaterial、PointsPerUnitX/Y/Z（密度）、ReservedTop/Bottom（破壊不可ゾーン）

SpaceMapGPU (Scripts/SpaceMapGPU.cs)

部屋のレイアウトを上から見た2D距離フィールドをGPUで計算します。出力先はRenderTextureです。

主なプロパティ：TextureDimension、MapGradient。メソッド：GetSpaceMap() → RenderTexture、GetColorAtPosition(Vector3) → Color

UV計算用にシェーダーのグローバル変数_SpaceMapProjectionViewMatrixを設定します。

RoomGuardian (Scripts/RoomGuardian.cs)

ユーザーが部屋の壁に近づくと、境界マテリアルをフェードさせます。マテリアルの_GuardianFade float値を設定します。

主なプロパティ：GuardianMaterial、GuardianDistance（メートル、デフォルト値1.0）

SceneNavigation (Scripts/SceneNavigation.cs)

シーンジオメトリからUnity NavMeshを生成します。com.unity.ai.navigationが必要です。

主なプロパティ：NavigableSurfaces（SceneLabels）、Agents（List<NavMeshAgent>）、AgentRadius

イベント：OnNavMeshInitialized

詳細はreferences/scene-navigation.mdを参照してください。

EnvironmentRaycastManager (Scripts/EnvironmentRaycastManager.cs)

事前スキャンしたシーンデータが不要な、物理環境に対する深度APIのレイキャストです。Quest 3以降が必要です。 名前空間：Meta.XR。

使用前にEnvironmentRaycastManager.IsSupportedを確認してください。

メソッド：Raycast(Ray, out EnvironmentRaycastHit, float)、PlaceBox(Ray, Vector3, Vector3, out EnvironmentRaycastHit)、CheckBox(Vector3, Vector3, Quaternion)

PassthroughCameraAccess (Scripts/PassthroughCameraAccess.cs)

パススルーカメラの生画像にアクセスします。AndroidManifestにhorizonos.permission.HEADSET_CAMERAが必要です。Quest 3以降のみ対応です。名前空間：Meta.XR。

主なプロパティ：CameraPosition（Left/Right）、RequestedResolution、MaxFramerate、TargetMaterial

メソッド：GetTexture() → Texture、GetColors() → NativeArray<Color32>（処理負荷が高い）、GetCameraPose() → Pose、ViewportPointToRay()、WorldToViewportPoint()

構造体CameraIntrinsics：FocalLength、PrincipalPoint、SensorResolution、LensOffset

インスタントコンテンツ配置（Scripts/BuildingBlocks/InstantContentPlacement/）

EnvironmentRaycastManagerを使用して、デバイススキャン不要で配置するビルディングブロックのスクリプトです。

• SpaceLocator（抽象クラス）：TryLocateSpace(out Pose)、OnSpaceLocateCompletedイベント、PreferredSurfaceOrientation
• PointAndLocate：Transformからレイキャストし、Locate()メソッドを使用します
• GrabAndLocate：Interaction SDKを介して、つかんで離す操作で配置します
• PlaceWithAnchor：配置した位置にOVRSpatialAnchorを作成し、ずれを防ぎます

共通パターン

シーン読み込み時のコールバック

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

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

シーンがすでに読み込まれている場合、RegisterSceneLoadedCallbackはすぐに実行されます。いつでも安全に呼び出せます。

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()}");
    }
}

部屋のジオメトリへのレイキャスト

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}");
}

Prefabフォールバックを使用したエディターでのテスト

MRUK.SceneSettings.DataSourceをDeviceWithPrefabFallbackに設定し、SceneSettings.RoomPrefabsに部屋のPrefabを割り当てます。デバイス上では実際のシーンデータが使用されます。エディターでは（デバイスがない場合）、Prefabの部屋が自動的に読み込まれます。このパッケージには、Core/Rooms/Prefabs/の下に約50個のサンプル部屋Prefab（Bedroom、LivingRoom、Office、LargeScale）が含まれています。

プロジェクトのセットアップ

1. com.meta.xr.mrutilitykit パッケージをインストールします
2. OVRManager > Quest Features で、Scene Support を「Required」に設定します
3. OVRManager > Quest Features で、Anchor Support を有効にします
4. シーンに OVRCameraRig があることを確認します
5. MRUK コンポーネントを持つ MRUK GameObject をシーンに追加します
6. SceneSettings.DataSource を設定します（開発時は DeviceWithPrefabFallback を使用します）
7. PassthroughCameraAccess の場合：AndroidManifest に horizonos.permission.HEADSET_CAMERA を追加し、OVRManifestPreprocessor.GenerateOrUpdateAndroidManifest(true) で再生成します。リクエストをブロックするモーダルダイアログをジェネレーターが開かないよう、silentMode: true が必要です。マニフェストのワークフロー全体については hz-unity-meta-core-sdk を参照してください。

MRUK コードの実行 — unity-cli で実行中の Editor を操作する

MRUK のセットアップは Editor 専用の C# です。シーンや設定ファイルを手動編集するのではなく、開いている Editor に対して実行します。

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

.cs ファイルは Assets/ の外側（プロジェクトルートからの相対パス）に置いてください。そうすれば、書き込みによるインポートやドメインリロードは発生しません。また、変更を加える前にコンパイルを確認するため、--dry_run true を追加します。

run_script は読み込み済みのすべてのアセンブリを参照するため、リフレクションを使わずに Meta.XR.MRUtilityKit 名前空間を直接参照できます。

// 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; と BindingFlags のオーバーロードはどちらも使用できます。そのため、リフレクションは本当に非公開のメンバーにのみ使用します。
• 非同期処理はスクリプトの終了後に完了します。別の run_script で後から確認し、メインスレッドで Task.Wait() を呼び出さないでください。
• シーンの変更後は EditorSceneManager.MarkSceneDirty と SaveScene、または unity command save_scene を実行し、その後値を読み戻します。

MRUK はランタイムシステムであるため、そのほとんどは Play モードでのみデータを生成します。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

停止する前に、シーンの読み込みを待ってください。 editor_play は Play モードが開始すると戻りますが、MRUK の処理完了を待つわけではありません。LoadSceneFromDevice / LoadSceneFromPrefab は Task を返し、EffectMesh、SceneNavigation などは SceneLoadedEvent の発生後にのみ動作します。すぐに停止すると、これらの処理は途中で打ち切られます。シーンの読み込みが完了するまで get_console_logs（または MRUK.Instance.IsInitialized を読み取る run_script）でポーリングし、その後でエラーを確認して停止してください。

接続方法、--project-path、Safe Mode からの復旧については unity-cli スキルを参照してください。リフレクションベースの MCP バージョンについては references/unity-mcp-fallback.md を参照してください。

最新ドキュメントの確認に metavr ツールを使用する

metavr MCP サーバーを利用できる場合、Meta SDK のドキュメントは頻繁に更新されるため、mcp__metavr__vr_docs_search と mcp__metavr__vr_docs_get_page ツールを使って現在の API の詳細を確認してください。mcp__metavr__vr_api_search では engine='unity' を指定して、MRUK、MRUKRoom、MRUKAnchor などのクラスの正確なメソッドシグネチャを検索します。同じバックエンドには CLI からもアクセスできます：metavr docs search "<topic>" および metavr docs api-search "<Class.method>"。

ドキュメントへのリンク

• MR Utility Kit の概要
• MRUK API リファレンス
• GitHub サンプル（12 個のサンプルシーン。v76 以降、パッケージから移動）
• Scene API の概要