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

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

版本資訊

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 定義遊戲不同場景的控制項、新增回呼來監聽重新對應事件、定義一組使用者無法重新對應的保留按鍵,並依 InputActionInputGroupInputMap 停用重新對應功能。

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

不支援的設定

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

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

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

升級

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

升級至 1.1.1-beta 即可啟用新功能,包括:

升級依附元件

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

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

定義靜態欄位

針對 1.1.1-beta 版本,建議您將 InputActionInputGroupInputContextInputMap 物件定義為 InputMappingProvider 類別的靜態欄位,因為這些欄位可從應用程式的其他部分存取:

Kotlin

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(...)
    }
}

Java

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-betaInputAction.create() 方法已淘汰。InputAction 現在具有版本 ID,且能標示是否可重新對應。根據預設,使用 Input SDK 1.0.0-beta create() 方法定義的 InputAction 可重新對應,且缺少版本資訊:

Input SDK 1.0.0-beta 中的 InputAction

Kotlin

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

Java

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

Input SDK 1.1.1-beta 中的 InputAction

Kotlin

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
}

Java

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.1-beta 中的 InputAction (使用版本字串)

Kotlin

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
)

Java

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.1-beta 中,您需要分別識別每個 InputGroup。每個 InputAction 都屬於 InputGroup,即相關動作組合。在遊戲過程中,這可以改善控制項的導覽功能和曝光度。就像在單一 InputContext 的所有動作中,InputAction 必須擁有「專屬」ID,InputGroup 在現有群組中也必須有專屬 ID。

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

Kotlin

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
}

Java

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

Input SDK 1.0.0-beta 中的 InputGroup

Kotlin

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

Java

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

Input SDK 1.1.1-beta 中的 InputGroup

Kotlin

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
    )
}

Java

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.1-beta 中的 InputGroup (含版本字串)

Kotlin

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
    )
}

Java

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

Input SDK 1.0.0-beta 中的 InputMap

Kotlin

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

Java

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

Input SDK 1.1.1-beta 中的 InputMap

Kotlin

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()))
  )
}

Java


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.1-beta,使用 InputContexts不同情境指派不同的控制項,或使用 InputRemappingListeners 接收重新對應事件通知,以便更新遊戲 UI。

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