Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

XR 動作對應¶

Godot 具有動作地圖功能，作為 XR 系統的一部分。此時該系統是 OpenXR 模組的一部分。有計劃在不久的將來將 WebXR 納入其中，因此我們在本文件中將其稱為 XR 動作地圖系統。它實作了 OpenXR 的內建動作地圖系統，基本上與它所提供的一樣。

XR 動作地圖系統會向您的遊戲/應用程式公開 XR 控制器的輸入、位置資料和輸出。它透過公開可根據您的遊戲/應用程式自訂的命名操作並將這些操作綁定到 XR 裝置上的實際輸入和輸出來實作此目的。

由於 XR 動作對應目前是 OpenXR 模組的一部分，因此需要在專案設定中啟用 OpenXR 才能顯示它：

然後，你會在螢幕底部看到 XR 行動地圖介面：

備註

Godot 的內建輸入系統與 XR 動作地圖系統有許多共同點。事實上，我們最初的想法是為現有輸入系統新增功能並將資料公開給 OpenXR 動作地圖系統。我們可能會在某個時候重新審視這個想法，但事實證明有太多的問題需要克服。僅舉幾例：

Godot 的輸入系統主要以按鈕輸入為中心，XR 增加了觸發器、軸、姿勢和觸覺（輸出）。這將使輸入系統變得非常複雜，其功能不適用於普通控制器或與目前方法相比。人們認為這會導致大多數 Godot 使用者感到困惑。

Godot 的輸入系統使用經過解析並觸發發出操作的原始輸入資料。此輸入資料可供最終使用者使用。 OpenXR 完全隱藏原始資料並為我們完成所有解析，我們只能存取已經解析的動作資料。當毫無戒心的使用者嘗試將 XR 裝置用作一般輸入裝置時，這種不一致可能會導致錯誤。

Godot 的輸入系統允許在運作時更改輸入與操作的綁定，而 OpenXR 則不允許。

Godot 的輸入系統基於裝置 ID，而這在 OpenXR 中毫無意義。

這確實意味著將傳統輸入與 XR 控制器混合在一起的遊戲/應用程式將會分開。對於大多數應用程式，使用其中之一，這不被視為問題。歸根結底，這是系統的限制。

光照動畫¶

如果找不到操作對應檔，Godot 會自動建立預設操作對應。

警告

該預設地圖旨在幫助開發人員將其XR 遊戲/應用程式從Godot 3 移植到Godot 4。因此，該地圖本質上將預設支援的所有控制器上的所有已知輸入綁定到一對一的操作。這不是設定行動圖的好例子。它確實讓新開發者在想要熟悉 Godot XR 時有一個起點。它避免了必須先為他們的遊戲/應用程式設計合適的動作地圖。

對於本演練，我們將從一張空白的操作地圖開始。您只需按下垃圾桶圖示即可刪除頂部的「Godot 操作集」條目。這將清除所有操作。您可能還想刪除不想設定的控制器，稍後將詳細介紹。

操作名稱¶

備註

在我們深入討論之前，您將看到本文件中使用的術語「XR 運作時」。對於 XR 運作時，我們指的是控制 AR 或 VR 耳機並與之互動的軟體。然後，XR 運作時透過 OpenXR 等 API 向我們公開這一點。所以：

對於 Steam，這是 SteamVR，

對於桌面上的 Meta，這是 Oculus 使用者端（包括使用 Quest 連結時），

對於 Quest 上的 Meta，這是 Quest 的原生 OpenXR 使用者端，

在 Linux 上，這可能是 Monado 等。

行動圖允許我們將行動組織成群組。每組都可以單獨啟用或停用。

這裡的概念是，您可以擁有不同的集合來在不同的場景中提供綁定。你可以有：

當你四處走動時設定“角色控制”，

當您操作車輛時設定的“車輛控制”，

當選單開啟時設定“Menu”。

然後只能啟用適用於遊戲/應用程式目前狀態的操作集。

如果您希望將控制器上的相同輸入綁定到不同的操作，這一點尤其重要。例如：

在你的“角色控制”集中，你可能有一個動作“跳躍”，

在你的“車輛控制”集中，你可能有一個動作“加速”，

在您的“選單”集中，您可能有一個操作“選擇”。

所有這些都綁定到控制器上的觸發器。

OpenXR 只會將輸入或輸出綁定到單一操作。如果相同的輸入或輸出綁定到多個操作，則活動操作集中具有最高優先權的操作將會更新/使用。因此，在我們上面的範例中，只有一個操作集處於活動狀態非常重要。

對於您的第一個 XR 遊戲/應用程式，我們強烈建議您從單一操作集開始，不要過度設計。

因此，對於本文件中的演練，我們將建立一個名為「my_first_action_set」的操作集。我們透過按下「新增操作集」按鈕來完成此操作：

../../_images/xr_my_first_action_set.webp

常見的使用情景如下：

顏色	值	說明
1	限制	這是操作集的內部名稱。除了大小之外，OpenXR 沒有對此名稱指定特定限制，但是某些 XR 運作時不喜歡空格或特殊字元。
2	我的第一個動作組	這是操作集的人類可讀名稱。某些 XR 運作時會向最終使用者顯示此名稱，例如在設定對話方塊中。
3	0	這是操作集的優先權。如果多個活動操作集的操作綁定到相同的控制器輸入或輸出，則具有最高優先權值的操作集將決定更新的操作。

動作¶

在 XR 動作地圖中，動作是您的遊戲/應用程式將與之互動的實體。例如，我們可以定義一個動作“Shoot”，綁定到該動作的輸入將使用“Shoot”觸發場景中相關 XRController3D <class_xrcontroller3d>` 節點上的“button_pressed”訊號` 作為訊號的 name 參數。

您也可以輪詢操作的目前狀態。 XRController3D 例如有一個 is_button_pressed 方法。

操作可用於輸入和輸出，每個操作都有一個定義其行為的型別。

“Bool”型別用於離散輸入，例如按鈕。
“Float”型別用於觸發器等類比輸入。

這兩者很特別，因為它們是唯一可以互換的。 OpenXR 將處理「Bool」和「Float」輸入和操作之間的轉換。您可以透過在 XRController3D <class_xrcontroller3d>` 節點上呼叫方法 get_float 來取得 Float 型別操作的值。更改時它會發出“input_float_changed”訊號。

備註

當類比輸入作為按鈕查詢時，會套用閾值。該閾值目前由 XR 運作時專門管理。我們計劃在未來擴充 Godot，以提供對這些閾值的某種程度的控制。

“Vector2”型別將輸入定義為軸輸入。觸控板、拇指操縱桿和類似的輸入都以向量形式公開。您可以透過在 XRController3D <class_xrcontroller3d> 節點上呼叫方法「get_vector2」來取得「Vector2」型別操作的值。更改時它會發出“input_vector2_changed”訊號。

“Pose”型別定義了空間追蹤輸入。 OpenXR 中提供多個「姿勢」輸入：「aim」、「grip」和「palm」。您的 XRController3D <class_xrcontroller3d> 節點會根據指派給該節點的「pose」屬性的姿勢動作自動定位。稍後詳細介紹姿勢。

備註

Godot 中的 OpenXR 實作也公開了一種名為「Skeleton」的特殊姿勢。這是手部追蹤實施的一部分。這個姿勢是透過動作地圖系統外部支援的「骨架」動作來暴露的。因此，如果支援手部跟踪，它就會始終存在。您不需要將動作綁定到此姿勢即可使用它。

最後，唯一的輸出型別是“觸覺”，它允許我們設定觸覺回饋的強度，例如控制器振動。控制器可以有多個觸覺輸出，而 OpenXR 即將支援觸覺背心。

因此，讓我們為我們的目標姿勢新增一個動作，我們透過點擊動作集的「+」按鈕來完成此操作：

常見的使用情景如下：

顏色	值	說明
1	aim_pose	這是操作的內部名稱。除了大小之外，OpenXR 沒有對此名稱指定特定限制，但是某些 XR 運作時不喜歡空格或特殊字元。
2	瞄準姿勢	這是該操作的人類可讀名稱。某些 XR 運作時會向最終使用者顯示此名稱，例如在設定對話方塊中。
3	姿勢	有名稱的型別

OpenXR 定義了許多可綁定的輸入姿勢，這些姿勢通常可用於控制器。對於不同控制器支援哪些姿勢沒有規則。 OpenXR 目前定義的姿勢是：

大多數控制器上的目標姿勢稍微位於控制器前方並向前瞄準。這是用於雷射筆或對準武器槍口的絕佳姿勢。

大多數控制器上的握持姿勢位於控制器上握持按鈕所在的位置。此姿勢的方向因控制器而異，並且對於不同 XR 運作時的相同控制器也可能不同。

大多數控制器上的手掌姿勢位於握住控制器的手掌的中心。這是一個新姿勢，並非在所有 XR 運作時都可用。

備註

如果使用手部追踪，目前不同 XR 運作時之間的實作存在很大差異。因此，動作地圖目前不適合手部追蹤。這方面的工作正在進行中，敬請關注。

讓我們完成一個非常簡單的射擊遊戲/應用程式的操作列表：

我們新增的操作是：

移動，允許使用者在正常房間規模追蹤之外移動。

抓取，它偵測到使用者想要握住某物。

射擊，它偵測到使用者想要使用他們持有的武器開火。

觸覺，它允許我們輸出觸覺回饋。

現在請注意，我們不區分左手和右手。這是下一階段確定的事。我們以這樣的方式實作了動作系統，您可以將相同的動作綁定到雙手。對應的 XRController3D <class_xrcontroller3d> 節點將發出訊號。

警告

對於抓取和射擊，我們都使用了“Bool”型別。如前所述，OpenXR 會從模擬控制進行自動轉換，但目前並非所有 XR 運作時都會套用合理的閾值。

手把按鈕互動時使用「Float」型別作為解決方法，並套用您自己的閾值。

對於 A/B/X/Y 等按鈕以及沒有模擬選項的類似按鈕，「Bool」型別效果很好。

備註

您可以將相同的操作綁定到同一設定檔上同一控制器的多個輸入。在這種情況下，XR 運作時將嘗試組合輸入。

對於“Bool”輸入，這將在按鈕之間執行“OR”操作。
對於“Float”輸入，這將採用綁定輸入的最高值。
“Pose” 輸入的行為未定義，但可能會使用第一個綁定輸入。

您不應將同一操作集的多個操作綁定到同一控制器輸入。如果您這樣做，或者如果操作是從多個操作集綁定的，但它們具有重疊的優先權，則行為是未定義的。 XR 運作時可能根本不接受您的操作圖，或者它可能會按照先到先得的原則接受此操作圖。

我們仍在研究將多個操作綁定到相同輸出的限制，因為這種情況是有意義的。 OpenXR 規格似乎不允許這樣做。

現在我們已經定義了基本操作，是時候將它們連接起來了。

分析工具¶

在 OpenXR 中，控制器綁定在所謂的「互動配置」中捕獲。我們只是將其縮短為“配置檔案”，因為它佔用的空間更少。

選擇此通用名稱是因為控制器不覆蓋整個系統。目前還有追蹤器、遙控器和追蹤筆的設定檔。還有針對跑步機、觸覺背心等裝置的規定，儘管這些裝置尚未包含在規範中。

警告

重要的是要知道 OpenXR 對支援的裝置有嚴格的檢查。核心規範確定了許多控制器和類似裝置及其支援的輸入和輸出。每個 XR 運作時都必須接受這些互動配置檔案，即使它們不適用。

新裝置是透過擴充功能新增的，XR 運作時必須指定它們支援哪些裝置。不支援透過擴充功能新增的裝置的 XR 運作時將不接受這些設定檔。如果提供不支援新增的輸入或輸出型別的 XR 運作時通常會當機。

因此，Godot 保留所有可用裝置的元資料、它們的輸入和輸出以及哪個擴充新增了對它們的支援。您可以為您希望支援的所有裝置建立互動設定檔。 Godot 將篩選掉使用者正在使用的 XR 執行時間不支援的內容。

這確實意味著為了支援新裝置，您可能需要更新到更新版本的 Godot。

然而，同樣重要的是要注意，行動地圖的設計就考慮到了這一點。當新裝置進入市場時，或當您的使用者使用您無權存取的裝置時，動作地圖系統將依賴 XR 運作時。 XR 運作時的工作是選擇已指定的最合適的互動設定檔並使其適應使用者正在使用的控制器。

XR 運作時如何做到這一點取決於運作時的實作，因此運作時之間存在巨大差異。某些運作時甚至可能允許使用者自行編輯綁定。

運作時的常見方法是先尋找配對的互動配置檔。如果未找到，它將檢查最常見的配置檔案，例如“觸摸控制器”的配置檔案並進行轉換。如果所有其他方法都失敗，它將檢查通用「簡單控制器」<doc_xr_action_map_simple>`。

備註

這裡有一個重要的結論：當找到控制器並將動作圖應用於它時，XR 運作時並不限於您在 Godot 的動作圖編輯器中設定的確切配置。雖然運作時通常會根據您在操作對應中設定的綁定之一選擇合適的對應，但它可能會偏離它。

例如，使用觸控控制器設定檔時，可能會出現以下任一情況：

VR控制器的程式碼

VR控制器的程式碼

我們可以使用 Quest Pro 控制器，但沒有給出 Quest Pro 設定檔案，或者正在使用的 XR 運作時不支援 Quest Pro 控制器，

它可能是一個完全不同的控制器，沒有給出配置檔案，但 XR 運作時使用觸摸綁定作為基礎。

因此，目前無法確定使用者實際使用哪個控制器。

警告

最後，這讓很多人感到困惑，綁定並不是一成不變的。 XR 運作時允許使用者自訂綁定是完全允許的，甚至是預期的。

目前，沒有任何 XR 運作時提供此功能，儘管 SteamVR 擁有來自 OpenVR 動作地圖系統的現有 UI，但仍然可以存取。不過，這方面的工作正在積極進行中。

第一個控制器綁定¶

讓我們以觸控控制器為例設定第一個控制器綁定。

按“新增設定檔”，找到觸控控制器並新增它。如果它不在列表中，則它可能已被新增。

../../_images/xr_add_touch_controller.webp

我們的 UI 現在顯示左右控制器的面板。面板包含每個控制器的所有可能的輸入和輸出。我們可以使用每個條目旁邊的“+”將其綁定到一個操作：

程式碼樣式設定

每個操作都綁定兩個控制器的給定輸入或輸出，以表示我們支援任一控制器上的操作。例外情況是移動動作僅綁定到右手控制器。我們很可能希望將左手拇指操縱桿用於不同的目的，例如傳送功能。

在開發遊戲/應用程式時，您必須考慮使用者更改綁定並將運動綁定到左手搖桿的可能性。

另請注意，我們的射擊和抓取布林操作與“Float”型別的輸入相關聯。如前所述，OpenXR 將在兩者之間進行轉換，但請閱讀本文件前面關於該主題的警告。

備註

有些輸入似乎多次出現在我們的列表中。

例如，我們可以找到“X”按鈕兩次，一次是“X click”，然後是“X touch”。這是由於觸控控制器具有電容式感測器。

如果使用者只是觸摸 X 按鈕，則「X touch」將為 true。
當使用者實際按下按鈕時，「X click」將為 true。

同樣，對於拇指操縱桿，我們有：

如果使用者觸摸拇指操縱桿，則「拇指操縱桿觸摸」為真。
「Thumbstick」給出了拇指桿被推動的方向的值。
當使用者按下拇指操縱桿時，會發生「拇指操縱桿點擊」。

值得注意的是，只有部分 XR 控制器支援觸控感應器或在搖桿上具有點擊功能。在設計遊戲/應用程式時請記住這一點。確保這些用於您的遊戲/應用程式的可選功能。

建立內容¶

「簡單控制器」是 OpenXR 作為後備提供的通用控制器。我們將應用我們的對應：

令人痛苦的是，顯而易見的是，簡單的控制器往往過於簡單，除了最簡單的 VR 遊戲/應用程式之外，其他任何東西都達不到要求。

這就是為什麼許多 XR 運作時僅將其用作最後手段，並首先嘗試使用來自更流行的系統之一的綁定作為後備。

備註

由於簡單的控制器可能無法滿足遊戲的需求，因此很容易為 OpenXR 支援的每個控制器提供綁定。預設的行動圖似乎顯示這是一個有效的行動方案。如前所述，預設的動作對應是為了方便從 Godot 3 遷移而設計的。

OpenXR 工作小組建議僅設定開發人員實際測試的控制器的綁定。 XR 運作時的設計就考慮到了這一點。他們可以比開發人員做出有根據的猜測更好地重新綁定所提供的綁定。特別是因為開發人員無法測試這是否會為最終使用者帶來舒適的體驗。

這也是我們的建議：將您的動作圖限制為您實際測試遊戲的裝置的互動設定檔。 Oculus Touch 控制器被許多運作時廣泛用作後備控制器。如果您能夠使用 Meta Rift 或 Quest 測試您的遊戲並新增此配置檔案，那麼您的遊戲很可能可以與其他耳機配合使用。