將適用於 Java 和 Kotlin 的 Input SDK 升級至 1.1 版

本指南說明如何針對遊戲，將適用於 Java 和 Kotlin 的 Input SDK 從 1.0.0-beta 版升級至 1.1.0-beta 版。如需 Unity 相關操作說明，請參閱 Unity 升級指南。

版本資訊

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

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

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

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

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

如要控管輸入方式重新對應體驗，或是遊戲的重新對應功能已停用，請按照下列步驟解決問題：

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

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

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

您可以將 Input SDK 版本升級至 1.1.0-beta，這樣就能利用 Google Play 遊戲電腦版的進階重新對應功能，包括運用 InputContexts 為不同的遊戲情境定義控制項、新增可監聽重新對應事件的回呼、定義一組使用者無法重新對應的保留按鍵，以及根據 InputAction、InputGroup 或 InputMap 停用重新對應功能。

升級至新版 SDK 時，請考量下列例外狀況：

不支援的設定

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

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

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

升級

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

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

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

升級依附元件

如要使用 Gradle 匯入 Input SDK，請升級至最新版本：

// build.gradle
dependencies {
   ...
   implementation 'com.google.android.libraries.play.games:inputmapping:1.1.0-beta'
   ...
}

定義靜態欄位

針對 1.1.0-beta 版本，建議您將 InputAction、InputGroup、InputContext 和 InputMap 物件定義為 InputMappingProvider 類別的靜態欄位，因為這些欄位可從應用程式的其他部分存取：

class InputSDKProvider : InputMappingProvider {
    override fun onProvideInputMap(): InputMap { return gameInputMap }

    companion object {
        const val INPUTMAP_VERSION = "1.0.0"

        private val moveUpInputAction = InputAction.create(...)
        private val movementInputGroup = InputGroup.create(...)
        val menuContext = InputContext.create(...)
        val gameInputMap = InputMap.create(...)
    }
}

public class MyInputMappingProvider implements InputMappingProvider {
    private static final String INPUTMAP_VERSION = "1.0.0";

    private static final InputAction moveUpInputAction =
        InputAction.create(...);
    private static final InputGroup movementInputGroup = InputGroup.create(...);
    public static final InputContext menuContext = InputContext.create(...);
    public static final InputMap gameInputMap = InputMap.create(...);

    @Override
    public InputMap onProvideInputMap() {
        return gameInputMap;
    }
}

更新 InputAction

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

val jumpInputAction = InputAction.create(
    "Jump",
    InputEventIds.JUMP.id,
    InputControls.create(
        listOf(KeyEvent.KEYCODE_SPACE),
        emptyList()
    )
)

InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputEventIds.MOVE_UP.ordinal(),
    InputControls.create(
        Collections.singletonList(KeyEvent.KEYCODE_W),
        Collections.emptyList()
    )
);

Input SDK 1.1.0-beta 中的 InputAction

companion object {
  private val moveUpInputAction = InputAction.create(
    "Move Up",
    InputActionsIds.DRIVE.ordinal.toLong(),
    InputControls.create(listOf(KeyEvent.KEYCODE_W), emptyList()),
    InputEnums.REMAP_OPTION_ENABLED) // This action is remappable
}

private static final InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputEventIds.MOVE_UP.ordinal(),
    InputControls.create(
            Collections.singletonList(KeyEvent.KEYCODE_W),
            Collections.emptyList()),
    InputEnums.REMAP_OPTION_ENABLED // this action is remappable
);

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

private val enterMenuInputAction = InputAction.create(
    "Enter menu",
    InputControls.create(listOf(KeyEvent.KEYCODE_ENTER), emptyList()),
    InputIdentifier.create(
    INPUTMAP_VERSION, InputActionsIds.ENTER_MENU.ordinal.toLong()),
    InputEnums.REMAP_OPTION_ENABLED
)

private static final InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputControls.create(
            Collections.singletonList(KeyEvent.KEYCODE_W),
            Collections.emptyList()),
    InputIdentifier.create(
            INPUTMAP_VERSION,
            InputEventIds.MOVE_UP.ordinal()),
    InputEnums.REMAP_OPTION_ENABLED // this action is remappable
);

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

更新 InputGroup

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

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

enum class 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
}

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

val movementInputGroup = InputGroup.create(
    "Basic Movement",
    listOf(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction)
)

InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction
    )
);

Input SDK 1.1.0-beta 中的 InputGroup

companion object {
    private val movementInputGroup = InputGroup.create(
        "Basic movement",
        listOf(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction),
        InputGroupsIds.BASIC_MOVEMENT.ordinal.toLong(),
        // All the actions in this groups can't be remapped
        InputEnums.REMAP_OPTION_DISABLED
    )
}

private static final InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction
    ),
    InputGroupsIds.BASIC_MOVEMENT.ordinal(),
    // All the actions in this groups can't be remapped
    InputEnums.REMAP_OPTION_DISABLED
);

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

companion object {
    private val movementInputGroup  = InputGroup.create(
        "Basic movement",
        listOf(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction),
        InputIdentifier.create(
            INPUTMAP_VERSION, InputGroupsIds.BASIC_MOVEMENT.ordinal.toLong()),
        // All the actions in this groups can't be remapped
        InputEnums.REMAP_OPTION_DISABLED
    )
}

private static final InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction
    ),
    InputIdentifier.create(
            INPUTMAP_VERSION,
            InputGroupsIds.BASIC_MOVEMENT.ordinal()),
    // All the actions in this groups can't be remapped
    InputEnums.REMAP_OPTION_DISABLED
);

如要進一步瞭解按鍵繫結的版本管理，請參閱「追蹤按鍵 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

val gameInputMap = InputMap.create(
    listOf(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
)

InputMap gameInputMap = InputMap.create(
    Arrays.asList(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
);

Input SDK 1.1.0-beta 中的 InputMap

companion object {

  const val INPUTMAP_VERSION = "1.0.0"
  const val INPUT_MAP_ID = 0

  val gameInputMap = InputMap.create(
    listOf(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false),
    InputIdentifier.create(INPUTMAP_VERSION, INPUT_MAP_ID.toLong()),
    InputEnums.REMAP_OPTION_ENABLED,
    // Use ESCAPE as reserved key
    listof(InputControls.create(listOf(KeyEvent.KEYCODE_ESCAPE), emptyList()))
  )
}

public static final String INPUT_MAP_VERSION = "1.0.0-beta";
public static final long INPUT_MAP_ID = 0;

public static final InputMap gameInputMap = InputMap.create(
        Arrays.asList(movementInputGroup, mouseMovementInputGroup),
        MouseSettings.create(true, false),
        InputIdentifier.create(INPUTMAP_VERSION, INPUT_MAP_ID),
        InputEnums.REMAP_OPTION_ENABLED,
        // Use ESC key as reserved key
        Arrays.asList(
                InputControls.create(
                        Collections.singletonList(KeyEvent.KEYCODE_ESCAPE),
                        Collections.emptyList()
                )
        )
);

後續步驟

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

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