Nâng cấp Input SDK cho Java và Kotlin lên phiên bản 1.1

Hướng dẫn này giải thích cách nâng cấp trò chơi của bạn từ Input SDK phiên bản 1.0.0-beta lên 1.1.1-beta cho Java và Kotlin. Hãy xem Hướng dẫn nâng cấp Unity để biết các hướng dẫn dành riêng cho Unity.

Ghi chú phát hành

Google Play Games trên máy tính hỗ trợ tính năng ánh xạ lại các nút điều khiển bằng bàn phím dựa trên các liên kết phím mà trò chơi của bạn cung cấp thông qua Input SDK.

Để truy cập vào tính năng này, người dùng có thể mở lớp phủ, chọn các tuỳ chọn điều khiển, sau đó nhấp vào hành động họ muốn ánh xạ lại.

Google Play Games trên máy tính sẽ liên kết mọi dữ liệu cần ánh xạ lại do người dùng nhập với dữ liệu đầu vào mặc định của trò chơi. Như vậy, trò chơi của bạn không cần phải nhận biết thao tác ánh xạ lại của người chơi. Nếu cần biết dữ liệu đầu vào mới cho một hành động trong trò chơi, chẳng hạn như hiển thị các nút điều khiển trên bàn phím trong trò chơi, bạn có thể tuỳ ý đăng ký một lệnh gọi lại để được thông báo về các sự kiện ánh xạ lại.

Google Play Games trên máy tính lưu trữ từng chế độ điều khiển do người dùng ánh xạ lại trên máy tính để duy trì trong các phiên trò chơi. Vì được lưu trữ trên máy tính, nên các chế độ điều khiển này không ảnh hưởng đến trải nghiệm trên thiết bị di động và sẽ được xoá khi bạn gỡ cài đặt Google Play Games trên máy tính. Các chế độ điều khiển không được duy trì trên nhiều thiết bị máy tính.

Bạn không cần nâng cấp Input SDK để bật tính năng ánh xạ lại phím trong trò chơi, nhưng trò chơi của bạn sẽ bị tắt tính năng ánh xạ lại nếu hệ thống phát hiện thấy một cấu hình không được hỗ trợ.

Nếu bạn muốn kiểm soát trải nghiệm ánh xạ lại dữ liệu đầu vào hoặc nếu tính năng ánh xạ lại bị tắt cho trò chơi của bạn, hãy làm theo các bước sau để khắc phục:

• Nâng cấp lên Input SDK 1.1.1-beta.
• Cập nhật mọi liên kết phím để tránh dùng các cấu hình không được hỗ trợ.
• Cập nhật InputMap để đặt tính năng ánh xạ lại thành enabled (bật).

Nếu bạn muốn chọn không sử dụng tính năng ánh xạ lại cho trò chơi mà vẫn muốn hiển thị phiên bản chỉ đọc của các liên kết phím, hãy làm theo các bước sau:

• Nâng cấp lên Input SDK 1.1.1-beta.
• Cập nhật InputMap để đặt tính năng ánh xạ lại thành disabled (tắt).

Bạn có thể nâng cấp phiên bản Input SDK lên 1.1.1-beta để tận dụng các tính năng ánh xạ lại nâng cao trong Google Play Games trên máy tính bằng cách sử dụng InputContexts để xác định chế độ điều khiển cho các cảnh khác nhau của trò chơi, thêm lệnh gọi lại để theo dõi các sự kiện ánh xạ lại, xác định một tập hợp các phím dành riêng mà người dùng không thể ánh xạ lại và huỷ kích hoạt tính năng ánh xạ lại cho mỗi InputAction, InputGroup hoặc InputMap.

Hãy cân nhắc các trường hợp ngoại lệ sau khi nâng cấp lên phiên bản SDK mới:

Cấu hình không được hỗ trợ

Tính năng ánh xạ lại dữ liệu đầu vào sẽ bị tắt nếu không đáp ứng các điều kiện sau:

• Một InputAction sử dụng nhiều phím phải gồm một phím bổ trợ và một phím không phải phím bổ trợ. Ví dụ: tổ hợp phím Shift + A là hợp lệ nhưng tổ hợp phím A + B, Ctrl + Alt và Shift + A + Tab không hợp lệ.

• Hai hoặc nhiều đối tượng InputAction hoặc InputGroup không thể có cùng một mã nhận dạng duy nhất.

Nâng cấp

Input SDK 1.1.1-beta tương thích ngược với Input SDK 1.0.0-beta. Các trò chơi sử dụng những phương thức triển khai trước đây của Input SDK vẫn hỗ trợ tính năng ánh xạ lại cơ bản, trừ phi những trò chơi đó dùng cấu hình không được hỗ trợ. Nếu trò chơi của bạn đang dùng phiên bản Input SDK cũ, hãy cân nhắc đọc hướng dẫn nâng cấp từ phiên bản 0.0.4 lên 1.0.0-beta.

Phiên bản nâng cấp lên 1.1.1-beta sẽ cho phép các tính năng mới, bao gồm việc:

• Kích hoạt các thay đổi về tuỳ chọn điều khiển cảnh.
• Nhận thông báo về các sự kiện ánh xạ phím.
• Tắt tính năng ánh xạ lại cho từng Hành động, Nhóm, Ngữ cảnh hoặc Mục ánh xạ.

Nâng cấp phần phụ thuộc

Nếu bạn đang sử dụng Gradle để nhập Input SDK, hãy nâng cấp lên phiên bản mới nhất:

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

Xác định các trường tĩnh

Đối với phiên bản 1.1.1-beta, bạn nên xác định các đối tượng InputAction, InputGroup, InputContext và InputMap làm trường tĩnh của lớp InputMappingProvider vì những trường này có thể truy cập được từ các phần khác của ứng dụng:

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

Cập nhật InputAction

Lưu ý: Hãy xem các phương pháp hay nhất dành cho nút điều khiển bằng bàn phím và chuột trong các trò chơi trên Android khi bạn thiết kế InputAction. Bạn cũng cần cẩn thận để tránh dùng bất kỳ cấu hình nào không được hỗ trợ.

Phương thức InputAction.create() của Input SDK 1.0.0-beta không dùng được nữa. InputAction hiện có giá trị nhận dạng phiên bản và có thể được đánh dấu là có thể ánh xạ lại hoặc không. Một InputAction được xác định bằng phương thức create() của Input SDK 1.0.0-beta có thể ánh xạ lại theo mặc định nhưng thiếu thông tin phiên bản:

InputAction trong Input SDK 1.0.0-beta

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

InputAction trong Input SDK 1.1.1-beta

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

InputAction trong Input SDK 1.1.1-beta (có chuỗi phiên bản)

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

Để biết thêm thông tin về cách tạo các phiên bản liên kết phím, hãy xem phần Theo dõi mã nhận dạng phím.

Cập nhật InputGroup

Trong Input SDK 1.1.1-beta, bạn cần xác định riêng từng InputGroup. Mỗi InputAction thuộc một InputGroup – một tập hợp các hành động liên quan. Điều này giúp cải thiện khả năng điều hướng và phát hiện các nút điều khiển trong khi chơi. Tương tự như InputAction phải có giá trị nhận dạng duy nhất giữa tất cả các hành động trong một InputContext, InputGroup phải có một mã nhận dạng duy nhất trên các nhóm.

Trong các ví dụ ở phần này, một trò chơi có 2 đối tượng InputContext đại diện cho trình đơn chính và quá trình chơi. Bạn có thể theo dõi các mã nhận dạng phù hợp cho từng InputGroup trong các ngữ cảnh này thông qua bản liệt kê sau:

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
}

Giống như InputAction, phương thức InputGroup.create() của Input SDK 1.0.0-beta không được dùng nữa. Bạn phải cập nhật InputGroup trong trò chơi bằng giá trị nhận dạng phiên bản và boolean cho biết liệu các đối tượng InputAction trong nhóm của bạn có thể ánh xạ lại hay không. Các nhóm được tạo bằng phương thức create() của Input SDK 1.0.0-beta không dùng nữa có thể ánh xạ lại, có mã nhận dạng là 0 và mã phiên bản là một chuỗi trống (""):

InputGroup trong Input SDK 1.0.0-beta

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

InputGroup trong Input SDK 1.1.1-beta

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

InputGroup trong Input SDK 1.1.1-beta (có chuỗi phiên bản)

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

Để biết thêm thông tin về cách tạo các phiên bản liên kết phím, hãy xem phần Theo dõi mã nhận dạng phím.

Cập nhật InputMap

Phương thức InputMap.create() của Input SDK 1.0.0-beta không được dùng nữa. Hãy cập nhật InputMap để gán giá trị nhận dạng phiên bản, chọn hoàn toàn không sử dụng tính năng ánh xạ lại hoặc gán danh sách các phím dành riêng cho trò chơi mà bạn không muốn người dùng ánh xạ lại. Mỗi InputMap được xác định thông qua phương thức create() của Input SDK 1.0.0-beta có thể ánh xạ lại theo mặc định, được xác định bằng mã nhận dạng 0 và không có bất kỳ phím dành riêng nào.

InputMap trong Input SDK 1.0.0-beta

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

InputMap trong Input SDK 1.1.1-beta

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

Các bước tiếp theo

Tiếp tục nâng cấp lên phiên bản 1.1.1-beta bằng cách dùng InputContexts để ánh xạ các nút điều khiển khác nhau cho các cảnh khác nhau hoặc dùng InputRemappingListeners để cập nhật giao diện người dùng của trò chơi bằng cách Nhận thông báo về các sự kiện ánh xạ lại.

Khi cập nhật các liên kết phím, hãy xem Các phương pháp hay nhất để thiết kế liên kết phím, đồng thời xem các hạn chế và giới hạn của tính năng ánh xạ lại.