Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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 執行階段的偵錯訊息。

偵錯訊息類型

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

Frame Synthesis

When enabled, provided it's supported by the XR runtime, lower resolution motion vector and depth buffers are rendered and provided to the XR runtime. The XR runtime can now inject reprojection frames and compensate for lower framerates.

It currently has the following limitations:

• Does NOT work in the Forward+ renderer.

• Only works with stereo rendering.

手部追蹤

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

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

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

手部追蹤無遮蔽資料來源

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

手部追蹤控制器資料來源

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

手部互動設定檔

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

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

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

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

Spatial Entities

This extension and its settings are used to obtain and interact with information about the user's real world environment. You can find more detailed information on how it works on the spatial entities page.

視線互動

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

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

別忘了儲存設定！

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

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

算繪模型

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

綁定修飾器

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

類比閾值

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

方向鍵綁定

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