將適用於 Unity 的 Input SDK 升級至 1.1 版

本指南說明如何針對遊戲，將適用於 Unity 的 Input SDK 從 1.0 版升級至 1.1 版。如需 Java 和 Kotlin 操作說明，請按這裡。

版本資訊

Google Play 遊戲電腦版可根據遊戲使用 Input SDK 所提供的按鍵繫結，支援鍵盤控制項重新對應功能。

使用者只要開啟疊加層，在選取控制項後按一下要重新對應的動作，即可使用這項功能。

使用者重新對應輸入方式後，Google Play 遊戲電腦版會將這些新方式對應至遊戲的預設輸入方式。這樣一來，遊戲就不需要知道玩家所設定的重新對應方式。如果需要知道遊戲內動作的新輸入方式，例如要在遊戲中顯示鍵盤控制項，可選擇註冊回呼，接收重新對應事件的通知。

Google Play 遊戲電腦版會將使用者重新對應的控制項儲存在本機，方便在遊戲過程中保存這些設定。這些設定是儲存在本機，因此不會影響行動裝置體驗，且會 Google Play 遊戲電腦版解除安裝時一併刪除。系統不會跨電腦保存設定。

您不需要升級 Input SDK，即可啟用遊戲中的按鍵重新對應功能，但如果系統偵測到不支援的設定，就會停用遊戲的重新對應功能。

如要控管輸入方式的重新對應過程，或是停用遊戲的重新對應功能，請按照下列步驟操作：

• 升級至 Input SDK 1.1.1-beta。
• 更新所有按鍵繫結，避免使用不支援的設定。
• 更新 InputMap，將重新對應功能設為啟用。

如要停用遊戲中的重新對應功能，但繼續顯示按鍵繫結的唯讀版本，請按照下列步驟操作：

• 升級至 Input SDK 1.1.1-beta。
• 更新 InputMap，將重新對應功能設為停用。

只要將 Input SDK 版本升級至 1.1.1-beta，即可運用 Google Play 遊戲電腦版的進階重新對應功能，方法是使用 InputContexts 定義遊戲不同場景的控制項、新增回呼來監聽重新對應事件、定義使用者無法重新對應的按鍵組合，並依照 InputAction、InputGroup 或 InputMap 停用重新對應功能。

升級時，請考慮以下例外狀況：

不支援的設定

如果不符合以下條件，系統就會停用輸入方式重新對應功能：

• 使用多個鍵的 InputAction 必須由輔助鍵和非輔助鍵組成。舉例來說，Shift + A 是有效的動作組合，但 A + B、Ctrl + Alt 和 Shift + A + Tab 皆無效。

• 兩個以上的 InputAction 或 InputGroup 物件不得共用相同的專屬 ID。

InputContext 簡介

InputContext 可讓遊戲中不同的動作使用相同的按鍵，而不會產生衝突。這樣一來，如果遊戲同時將空白鍵用於遊戲過程中的跳躍動作和選單中的選項確認方式，玩家就可以分別將選單中的空白鍵重新對應到 Enter 鍵，並將遊戲過程中的空白鍵重新對應到向上鍵。

以下序列圖表說明 setInputContext() API 在執行階段的運作方式：

升級

如果遊戲使用先前的 Input SDK 實作方式，仍可支援基本的重新對應功能，除非使用不支援的設定，才會導致遊戲不支援該功能。如果遊戲使用的是舊版 Input SDK，請考慮參閱從 0.0.4 版升級至 1.0.0-beta 版的指南。

升級至 1.1.1-beta 即可啟用新功能，包括：

• 觸發情境變更。
• 接收按鍵重新對應事件的通知。
• 根據動作、群組、情境或對應方式停用重新對應功能。

安裝

您可以使用 Unity 外掛程式 1.1.1-beta 版。您需要刪除遊戲中安裝的任何 Input SDK 版本，然後升級至最新版本。

如要在遊戲中新增 Input SDK 1.1.1-beta 版，請參閱「新增 SDK」。

定義靜態欄位

針對 1.1.1-beta 版，建議您將 InputActions、InputGroups、InputContexts 和 InputMap 定義為 InputMappingProvider 類別的靜態欄位，因為這些欄位可從應用程式的其他部分存取：

#if PLAY_GAMES_PC
using Java.Lang;
using Java.Util;
using Google.Android.Libraries.Play.Games.Inputmapping;
using Google.Android.Libraries.Play.Games.Inputmapping.Datamodel;

public class InputSDKMappingProvider : InputMappingProviderCallbackHelper
{
    public static readonly string INPUT_MAP_VERSION = "1.0.0";

    private static readonly InputAction driveInputAction =
            InputAction.Create(...);
    private static readonly InputGroup roadInputGroup = InputGroup.Create(...);
    public static readonly InputContext roadControlsContext =
            InputContext.Create(...);
    public static readonly InputMap inputMap = InputMap.Create(...);

    public override InputMap OnProvideInputMap()
    {
        return inputMap;
    }
}
#endif

更新 InputAction

注意：設計 InputAction 時，請考量 Android 遊戲的鍵盤和滑鼠控制項最佳做法，並務必避免使用不支援的設定。

Input SDK 1.0.0-beta 的 InputAction.create() 方法已淘汰。InputAction 具有版本 ID，且能標示是否可重新對應。根據預設，使用 Input SDK 1.0.0-beta create() 方法定義的 InputAction 可重新對應，且缺少版本資訊：

Input SDK 1.0.0-beta 中的 InputAction

var driveAction = PlayInputAction.Create(
    "Drive",
    (long)InputEventIds.DRIVE,
    PlayInputControls.Create(
        new[] { AndroidKeyCode.KEYCODE_SPACE },
        new List<PlayMouseAction>()
    )
);

Input SDK 1.1.1-beta 中的 InputAction

private static readonly InputAction driveInputAction = InputAction.Create(
    "Drive",
    (long)InputEventIds.DRIVE,
    InputControls.Create(
        new[] { new Integer(AndroidKeyCode.KEYCODE_SPACE) }.ToJavaList(),
        new ArrayList<Integer>()),
    InputEnums.REMAP_OPTION_ENABLED
);

Input SDK 1.1.1-beta 中的 InputAction (使用版本字串)

private static readonly InputAction driveInputAction = InputAction.Create(
    "Drive",
    InputControls.Create(
        new[] { new Integer(AndroidKeyCode.KEYCODE_SPACE) }.ToJavaList(),
        new ArrayList<Integer>()),
    InputIdentifier.Create(
        INPUT_MAP_VERSION, (long)InputEventIds.DRIVE),
    InputEnums.REMAP_OPTION_ENABLED
);

如要進一步瞭解按鍵繫結的版本管理，請參閱「追蹤按鍵 ID」。

更新 InputGroup

在 Input SDK 1.1.1-beta 中，您需要分別識別每個 InputGroup。每個 InputAction 都屬於 InputGroup，即相關動作集合。在遊戲過程中，這可以改善控制項的導覽情形和曝光度。就像在單一 InputContext 的所有動作中，InputAction 必須擁有「專屬」ID，InputGroup 在現有群組中也必須有專屬 ID。

以本節的例子來說，遊戲有兩個 InputContext 物件，分別代表主選單和遊戲過程。在這些情況下，系統會使用以下列舉追蹤每個 InputGroup 的適當 ID：

public enum InputGroupsIds
{
    // Main menu scene
    BASIC_NAVIGATION, // WASD, Enter, Backspace
    MENU_ACTIONS, // C: chat, Space: quick game, S: store
    // Gameplay scene
    BASIC_MOVEMENT, // WASD, space: jump, Shift: run
    MOUSE_ACTIONS, // Left click: shoot, Right click: aim
    EMOJIS, // Emojis with keys 1,2,3,4 and 5
    GAME_ACTIONS, // M: map, P: pause, R: reload
}

和 InputAction 一樣，Input SDK 1.0.0-beta 的 InputGroup.create() 方法已淘汰。您必須使用版本 ID 和布林值更新遊戲中的 InputGroup，指出群組中的 InputAction 物件是否可重新對應。使用已淘汰的 Input SDK 1.0.0-beta create() 方法建立的群組可重新對應，ID 為 0，版本 ID 則是空白字串 ("")：

Input SDK 1.0.0-beta 中的 InputGroup

var gameInputGroup = PlayInputGroup.Create(
    "Road controls",
    new List<PlayInputAction>
    {
        driveAction,
        turboAction,
        openGarageAction,
        openPgsAction,
        openStoreAction
    }
);

Input SDK 1.1.1-beta 中的 InputGroup

private static readonly InputGroup roadInputGroup = InputGroup.Create(
    "Road controls",
    new[]
    {
        driveInputAction,
        turboInputAction,
        openGarageInputAction,
        openPgsInputAction,
        openStoreInputAction,
    }.ToJavaList(),
    (long)InputGroupsIds.ROAD_CONTROLS,
    // All input actions of this group will be remappable unless specified
    // the contrary by the individual input actions.
    InputEnums.REMAP_OPTION_ENABLED
);

Input SDK 1.1.1-beta 中的 InputGroup (含版本字串)

private static readonly InputGroup roadInputGroup = InputGroup.Create(
    "Road controls",
    new[]
    {
        driveInputAction,
        turboInputAction,
        openGarageInputAction,
        openPgsInputAction,
        openStoreInputAction,
    }.ToJavaList(),
    InputIdentifier.Create(
        INPUT_MAP_VERSION, (long)InputGroupsIds.ROAD_CONTROLS),
    // All input actions of this group will be remappable unless specified
    // the contrary by the individual input actions.
    InputEnums.REMAP_OPTION_ENABLED
);

如要進一步瞭解按鍵繫結的版本管理，請參閱「追蹤按鍵 ID」。

更新 InputMap

Input SDK 1.0.0-beta 的 InputMap.create() 方法已淘汰。請更新 InputMap，即可指派版本 ID、完全停用重新對應功能，或是針對遊戲中不想讓使用者重新對應的按鍵，指派保留按鍵清單。根據預設，使用 Input SDK 1.0.0-beta create() 方法定義的所有 InputMap 皆可重新對應，ID 會識別為 0，也沒有任何保留按鍵。

Input SDK 1.0.0-beta 中的 InputMap

var gameInputMap = PlayInputMap.Create(
    new List<PlayInputGroup>
    {
        gameInputGroup,
        menuInputGroup
    },
    PlayMouseSettings.Create(false, false)
);

Input SDK 1.1.1-beta 中的 InputMap

public static readonly string INPUT_MAP_VERSION = "1.0.0";
public static readonly long INPUT_MAP_ID = 0;

public static readonly InputMap inputMap = InputMap.Create(
    new[] { roadInputGroup, menuInputGroup }.ToJavaList(),
    MouseSettings.Create(false, false),
    InputIdentifier.Create(INPUT_MAP_VERSION, INPUT_MAP_ID),
    // Use ESC as reserved key
    InputEnums.REMAP_OPTION_ENABLED,
    new[]
    {
        InputControls.Create(new[]
        {
            new Integer(AndroidKeyCode.KEYCODE_ESCAPE)
        }.ToJavaList(),
        new ArrayList<Integer>())
    }.ToJavaList()
);

後續步驟

請繼續升級至 1.1.1-beta，使用 InputContexts 為不同情境指派不同的控制項，或使用 InputRemappingListeners 接收重新對應事件通知，以便更新遊戲 UI。

更新按鍵繫結時，請查看設計按鍵繫結的最佳做法，並考量重新對應功能的限制規定和本身限制。