Skip to main content
如果您正在為 XBOX 開發,從 2510 GDK 開始,v.0 版是 GDK 中可用的預設版本。運用 v1.0+ API 的遊戲可以透過整合 Microsoft.GameInput NuGet 套件,在 PC (v1.0+) 和主機 (v2.2+) 上使用這些 API。若要在主機上使用此 NuGet 套件,需要 GDK 2510 或更新版本。PC 應用程式需要在目標電腦上安裝 NuGet 套件中隨附的最新 GameInput 可轉散發套件。主機應用程式必須針對 NuGet 套件中最新的 GameInput 標頭和程式庫進行編譯和連結,但不需要可轉散發套件,因為最新的 GameInput 執行階段已隨附於 XBOX 上的 GDK 映像中。
GameInput 是一個持續演進的 API,會隨著新增功能以及移除不需要或過時的功能而不斷發展。您可以在官方 NuGet 套件中找到最新版本的 GameInput。此套件也包含最新的版本歷程記錄。此套件一律包含最新的 GameInput 標頭、二進位檔和可轉散發套件,供您隨遊戲一起提供。 升級至較新版本的 GameInput 既快速又輕鬆。此外,無論最新 GameInput 標頭中描述的 API 為何,針對舊版 GameInput 編譯的應用程式都會維持二進位和功能相容性。在此模型中,已發行的遊戲可以享受 GameInput 的改進,並可在必要時轉換為最新版本的 GameInput,以運用新功能。

升級執行階段和 API 版本

不同版本的 GameInput 具有外觀相似的名稱和方法,但會以不同的 UUID 明確區分版本。從 GameInput API v.1 開始,每個版本都定義在唯一的命名空間中 (例如 GameInput::v1)。GameInput 中相同的基礎物件會實作這些介面。您可以使用 QueryInterface 在版本之間切換,這表示您可以視需要在遊戲中混合使用 API。 如果您是從 API 定義在全域命名空間中的 GameInput v.0 升級,您可能會發現新增 using namespace GameInput::v1 陳述式有助於減少為了採用 v.1 及後續 API 修訂版本而需要更新的 GameInput 呼叫位置數目。 除了執行階段版本檢查之外,您也可以透過檢查 GAMEINPUT_API_VERSION 前置處理器定義來使用條件式編譯。此定義對應至目前使用中的 GameInput API 版本以及 GameInput 主要版本。v.0 API 沒有此定義,因此如果您想要有條件地測試此版本,可以在 GameInput 標頭 include 之後新增下列程式碼片段。

僅升級執行階段

GameInput 可讓您取得最新的錯誤修正,而不需強制您更新 API 使用方式。若要取得這些錯誤修正,請安裝最新 Microsoft.GameInput NuGet 套件中隨附的 GameInput 可轉散發套件。由於 GameInput 與舊版 API 保持二進位相容,您可以繼續將現有的標頭與新的執行階段搭配使用。請記得隨遊戲重新散發最新的 GameInput 二進位檔,以確保測試環境中的功能與生產環境一致。

GameInput v.1 變更

如果您使用的是舊版 GameInput,請注意,從 v.1 API 開始, 許多未實作的函式及對應的列舉和常數都已移除。 此外,API 會放在 GameInput::v1 命名空間中, 以便進行版本控制。由於這些變更,使用此 (及未來) 版本建置該程式碼時,您可能會遇到 編譯錯誤。值得注意的變更包括:
  1. IGameInputDevice::GetDeviceInfo 先前會將產生的 IGameInputDeviceInfo 結構作為函式的傳回值傳回。此 結構現在會作為函式的輸出參數傳回,而 函式的傳回值現在是 HRESULT。
  2. IGameInput::UnregisterCallback 先前接受逾時值作為 其第二個參數,但此參數已移除。
  3. IGameInputReading::GetSequenceNumber 已移除。請改用 IGameInputReading::GetTimestamp。

版本控制提示

  • v.0 與 v.1 之間可用 API 介面的變更極少,僅移除了從未實作的功能,以及先前描述的函式簽章變更。
  • 原始 GameInput.h 標頭中的原始 v.0 API 仍受支援,但該 API 會維持不變。在此情況下,您會繼續使用來自 GDK、舊版 NuGet 套件或 Windows SDK 的原有標頭。
  • 無論您使用哪個版本的 API,都必須在開發期間從 NuGet 套件安裝最新的可轉散發套件,並在遊戲向終端使用者提供的安裝程序中納入該可轉散發套件 (或更新版本)。此可轉散發套件包含較新的 GameInput 執行階段實作,可為所有 API 版本增強功能,例如擴充的控制器支援、觸控板支援、遠端桌面支援,以及各種其他錯誤修正。

另請參閱

GameInput NuGet 套件
Last modified on October 6, 2026