OpenXR 設定

OpenXR 有其專屬的一組設定，會在 OpenXR 啟動時套用。雖然透過 Godot 外掛實作的 OpenXR 擴充功能可以額外加入設定，本章僅說明 Godot 核心中的設定。

一般設定

已啟用

此設定會在 Godot 啟動時啟用 OpenXR 模組。若使用 Vulkan 後端，這是必要的。對於其他後端，你可以隨時呼叫 OpenXRInterface 的 initialize 方法來啟用 OpenXR。

若要使用動作對應編輯器，也必須啟用此設定。

你可以在啟動時加入 --xr-mode on 命令列參數來強制啟用此功能。

預設動作對應

這裡設定 OpenXR 載入並傳遞給 XR 執行時（Runtime）的動作對應檔案路徑。

裝置型態

這裡指定你的遊戲是針對以下哪一種裝置設計：

「頭戴式」裝置，例如 Meta Quest、Valve Index 或 Magic Leap，
「手持式」裝置，例如智慧型手機。

若執行遊戲的裝置與此處選擇的類型不符，OpenXR 將無法初始化。

視圖配置

這裡設定你的遊戲設計所使用的視圖配置：

「單眼」：遊戲僅提供單一畫面輸出。例如：基於手機的 AR;
「立體」：遊戲提供立體畫面輸出。例如：頭戴式裝置。

若執行遊戲的裝置與此處選擇的類型不符，OpenXR 將無法初始化。

備註

OpenXR 還有其他專為特定裝置設計的視圖配置，目前 Godot 尚未支援。例如 Varjo 頭戴裝置有四視圖（Quad View）配置，可輸出兩組立體畫面。未來可能會陸續支援。

參考空間

在 XR 中，玩家的頭部、手部等所有元素都會在一個追蹤空間（tracking volume）內進行追蹤。這個追蹤空間的基準點（origin）負責將虛擬空間對應到現實空間。根據不同 XR 系統，這個基準點的位置會有所不同。在 OpenXR 中，這些情境有明確定義，並可透過設定參考空間來選擇。

本地

「本地」參考空間預設會將原點設在玩家的頭部。有些 XR 執行時會在每次遊戲啟動時這麼做，其他則會讓此位置在多次遊玩期間持續保持。

此參考空間無法防止使用者離開原點，因此如果你希望玩家不要離開所控制的載具等，必須自行偵測玩家是否已移動，否則可能會導致遊戲體驗破壞。

這種參考空間最適合像是飛行模擬或賽車模擬等遊戲，在這些遊戲中我們希望將 XROrigin3D 節點放在玩家頭部的位置。

當使用者在頭戴裝置上執行重新置中（recenter）操作時（不同 XR 執行時方式不同），XR 執行時會將 XRCamera3D 移動到 XROrigin3D 節點上。OpenXRInterface 也會發出 pose_recentered 訊號，讓遊戲可以做出相應反應。

備註

其他所有受 XR 追蹤的元素，例如控制器或錨點，也會一併進行調整。

警告

使用此參考空間時， 不應該 呼叫 center_on_hmd 。

舞台

舞台（Stage）參考空間是預設的參考空間，會將原點設置於遊玩區域的中心。對於允許繪製防護邊界的 XR 執行時，這個位置及方向通常由使用者設定。其他 XR 執行時則可能用不同方式決定基準點，但這個點在現實世界中通常是固定的。

這種參考空間最適合房間規模（Room Scale）遊戲，玩家預期會在較大的空間內移動，或是需要切換不同遊戲模式的情境。詳見 Room Scale。

當使用者在頭戴裝置上執行重新置中時（每種 XR 執行時方式不同），XR 執行時不會更動原點位置。OpenXRInterface 會發出 pose_recentered 訊號，遊戲需自行做出正確反應。若未妥善處理，遊戲可能無法在多個平台通過審核。

在 Godot 中，你可以呼叫 XRServer 的 center_on_hmd 方法來達成此目的：

呼叫 XRServer.center_on_hmd(XRServer.RESET_BUT_KEEP_TILT, false) 會將 XRCamera3D 節點移動到 XROrigin3D 節點，類似於 Local 參考空間。
呼叫 XRServer.center_on_hmd(XRServer.RESET_BUT_KEEP_TILT, true) 會將 XRCamera3D 節點移動到 XROrigin3D 節點上方並保留玩家高度，類似於「本地地板」參考空間。

備註

其他所有受 XR 追蹤的元素，例如控制器或錨點，也會一併進行調整。

本地地板

本地地板參考空間與本地參考空間類似，都是將原點設於玩家所在位置，但此模式會保留玩家的高度。與本地參考空間一樣，有些 XR 執行時會讓這個位置於多次遊戲期間持續存在。

因此無法保證玩家始終站在原點上，只能保證他們在上次重新置中時站在那裡。玩家之後仍可自由離開原點。

這種參考空間最適合預期玩家會站在原地的遊戲，或是類 AR 遊戲，其 UI 元素綁定於原點節點並可在重置時快速對齊玩家位置。

當玩家在頭戴裝置上進行重新置中時（不同 XR 執行時方式不同），XR 執行時會將 XRCamera3D 移動到 XROrigin3D 上方並保留玩家高度。OpenXRInterface 也會發出 pose_recentered 訊號，讓遊戲可以相應處理。

警告

若你讓玩家進行虛擬移動時使用此模式要特別小心。玩家在這種情境下執行重新置中會產生不可預期的結果，除非你在處理重新置中訊號時自行修正移動，否則可能造成玩家瞬間被傳送至虛擬移動時設定的原點座標，甚至進入不應進入的區域。這種情境建議改用舞台（Stage）模式，並僅在收到 pose_recentered 訊號時重設方向。

備註

其他所有受 XR 追蹤的元素，例如控制器或錨點，也會一併進行調整。

警告

使用此參考空間時， 不應該 呼叫 center_on_hmd 。

環境混合模式

環境混合模式決定渲染結果如何與「真實世界」進行混合（前提是頭戴裝置有支援）。

「Opaque」（不透明）：渲染結果完全遮蔽現實世界，即 VR 模式。
「Additive」（加法）：渲染結果以加法方式疊加於現實畫面，屬於光學無法完全遮蔽現實的 AR 模式（如 Hololens），
「Alpha」：使用 Alpha 混合模式與現實畫面結合（檢視區需啟用透明背景），屬於光學能完全遮蔽現實的 AR 模式（如 Magic Leap、各種穿透式設備等）。

若選擇的混合模式未被頭戴裝置支援，將自動選擇第一個可用的模式。

備註

部分 OpenXR 裝置有獨立的穿透啟用/關閉系統。從 Godot 4.3 起，選擇 Alpha 混合模式時也會自動執行這些額外步驟。此功能需安裝最新的廠商外掛。

注視點最佳化等級

設定渲染時使用的注視點最佳化（Foveation）等級，前提是硬體有支援。注視點最佳化是一種根據畫面中心距離動態降低解析度的技術。大多數 XR 執行時只支援固定注視點，也有部分能配合眼動追蹤，以視覺焦點調整效果。

等級越高，效能提升越顯著，但使用者周邊視覺的畫質降低也會更明顯。

備註

僅限相容性渲染器，若使用 Mobile 或 Forward+ 渲染器，請將 Viewport 的 vrs_mode 屬性設為 VRS_XR。

警告

若使用發光、泛光或景深等後製特效，則此功能會自動停用。

動態注視點最佳化

啟用後，注視點最佳化等級會根據 GPU 當前負載自動調整，變動範圍在低至你於前一設定選擇的等級之間。建議將本設定與高等級注視點最佳化一同使用。

備註

僅限相容性渲染器

提交深度緩衝區

啟用後，渲染時會使用由 OpenXR 提供的深度緩衝區，並於影像一同提交。XR 執行時可以利用這項資訊提升重投影品質。

備註

啟用此功能會關閉渲染時的遮罩（stencil）支援。大多數 XR 執行時不會用到此功能，建議除非確實對你有幫助，否則保持關閉。

啟動警示

啟用後，若 OpenXR 啟動失敗，將會顯示警示訊息給使用者。我們不一定能從 XR 系統取得失敗原因，若有資訊會記錄在主控台。常見失敗原因包括：

主機系統尚未安裝 OpenXR 執行時環境。
目前啟用的是 Microsoft 的 WMR OpenXR 執行時，僅支援 DirectX，若使用 OpenGL 或 Vulkan 將會失敗。
SteamVR 已啟動，但未連接或開啟頭戴裝置。

若你的遊戲有設計後備模式（例如未連接 VR 裝置時可用桌面模式遊玩），或你已透過 OpenXRInterface.is_initialized() 自行處理失敗情境，則可停用此選項。

擴充功能

本小節可啟用各種選用的 OpenXR 擴充功能。請注意，只有在執行此專案的 OpenXR 執行階段（SteamVR、Oculus 等）支援這些擴充功能時，它們才會生效。

偵錯工具

啟用後會記錄來自 XR 執行階段的偵錯訊息。

偵錯訊息類型

可選擇要記錄哪些偵錯訊息。

手部追蹤

啟用後會在裝置支援時開啟手部追蹤擴充功能（預設為開啟，為了相容舊專案）。此擴充功能能取得資料，讓你能正確顯示用戶的手部與手指位置。依平台能力不同，手部追蹤資料可從控制器、資料手套、光學手部追蹤感測器或其他來源推算取得。

若你的遊戲僅支援控制器，建議關閉此功能。

更多細節請參見手部追蹤頁面。

手部追蹤無遮蔽資料來源

啟用後，手部追蹤可使用手指的精確位置，通常是頭戴裝置相機所看到的位置。

手部追蹤控制器資料來源

啟用後，手部追蹤可使用控制器本身，並根據控制器的輸入或其感測器來推估手指的位置。

手部互動設定檔

啟用此擴充功能後，可使用兩種新的手部追蹤姿勢：Pinch（拇指與食指朝前並以兩指之間的位置為準），以及 Poke（以食指指尖為準）。

同時還新增 3 種基於手勢的輸入：Pinch，當使用者將拇指與食指捏合時；Aim activation，當食指完全伸直時；以及 Grasps，當使用者握拳時。

同時提供手部互動與控制器互動設定檔時，執行階段會視是否使用光學追蹤、或使用者是否手持控制器，在設定檔之間切換。

若只提供手部互動設定檔，無論是否手持控制器，各種執行階段都應使用手部互動。

視線互動

啟用後，若裝置支援，會開啟視線互動擴充功能。啟用時，系統會根據眼動追蹤回傳一個位於用戶雙眼之間、朝向用戶注視方向的姿態（Pose），此方向是統一的。

要使用此功能，請先編輯你的動作對應表，新增一個姿態（Pose）動作，例如取名為 eye_pose。接著，為視線互動新增一個互動設定檔，並將 eye_pose 對應到該設定：

../../_images/openxr_eye_gaze_interaction.webp

別忘了儲存設定！

然後，在你的原點（origin）節點下新增一個 XRController3D 節點，將其 tracker 屬性設為 /user/eyes_ext，pose 屬性設為 eye_pose。

現在你可以在這個控制器節點下新增射線（Raycast）等元件，實現以眼睛控制互動的功能。

算繪模型

此擴充功能可向 XR 執行階段查詢正在使用之硬體（通常是控制器）的 3D 資產，以及該硬體的位置。詳細的使用指南可參考此處。

綁定修飾器

這些選項控制是否允許使用綁定修飾器。綁定修飾器可用來套用臨界值或位移。如何使用與設定，請見 XR 動作對應頁面：此處。

類比閾值

允許使用類比閾值綁定修飾器。

方向鍵綁定

允許使用方向鍵綁定修飾器。