Nâng cấp SDK đầu vào cho Unity 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ừ phiên bản SDK đầu vào 1.0 lên 1.1 cho Unity. Hãy nhấp vào đây để xem hướng dẫn dành cho Java và Kotlin.

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 nút điều khiển, sau đó nhấp vào hành động họ muốn gán 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 gán lại.

Google Play Games trên máy tính lưu trữ các chế độ điều khiển do người dùng gán lại trên máy tính để duy trì trong các phiên trò chơi. Vì các chế độ cài đặt này được lưu trữ trên máy tính, nên chúng 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ế độ cài đặt 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 SDK đầu vào để bật tính năng gán 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 gán 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 gán lại dữ liệu đầu vào hoặc tính năng gán lại bị tắt cho trò chơi của bạn, hãy làm theo các bước sau:

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 SDK đầu vào 1.1.0-beta.
  • Cập nhật InputMap để đặt tính năng gán lại thành disabled (tắt).

Bạn có thể nâng cấp SDK đầu vào lên phiên bản 1.1.0-beta để tận dụng các tính năng gán 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 nút điều khiển cho các cảnh khác nhau trong trò chơi, thêm lệnh gọi lại để theo dõi các sự kiện gán 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ể gán lại và tắt tính năng gán lại theo InputAction, InputGroup hoặc InputMap.

Khi nâng cấp, hãy xem xét các trường hợp ngoại lệ sau:

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

Tính năng gán 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 hay InputGroup không thể có cùng một mã nhận dạng duy nhất.

Giới thiệu InputContext

InputContext cho phép trò chơi sử dụng cùng một phím cho nhiều hành động trong trò chơi mà không tạo ra sự xung đột. Như vậy, nếu một trò chơi sử dụng phím cách để thực hiện hành động nhảy trong quá trình chơi và để xác nhận một tuỳ chọn trong trình đơn, thì người chơi có thể gán lại phím cách thành phím Enter trong các trình đơn và gán lại phím cách thành mũi tên lên trong hoạt động chơi trò chơi.

Sơ đồ trình tự sau đây biểu thị cách hoạt động của API setInputContext() trong thời gian chạy:

Sơ đồ cho thấy luồng SDK đầu vào khi liên kết lại các phím.

Nâng cấp

Các trò chơi sử dụng những phương thức triển khai trước đây của SDK đầu vào vẫn hỗ trợ tính năng gán 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 SDK đầu vào cũ hơn, 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.0-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ề ngữ cảnh.
  • Nhận thông báo về các sự kiện gán phím
  • Tắt tính năng gán lại cho mỗi Hành động, Nhóm, Ngữ cảnh hoặc Mục gán.

Cài đặt

Bạn có thể dùng trình bổ trợ Unity phiên bản 1.1.0-beta. Bạn cần xoá mọi phiên bản SDK đầu vào trước đó đã cài đặt trong trò chơi và nâng cấp lên phiên bản hiện tại.

Để thêm SDK đầu vào phiên bản 1.1.0-beta vào trò chơi, hãy xem phần Thêm SDK.

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

Đối với phiên bản 1.1.0-beta, bạn nên xác định InputActions, InputGroups, InputContexts 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:

#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

Cập nhật InputAction

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

InputAction trong SDK đầu vào 1.0.0-beta

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

InputAction trong Input SDK 1.1.0-beta

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

InputAction trong SDK đầu vào 1.1.0-beta (có chuỗi phiên bản)

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

Để biết thêm thông tin về cách xác định phiên bản của các 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.0-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. Giống như InputAction phải có giá trị nhận dạng duy nhất trên 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:

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 SDK đầu vào 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 SDK đầu vào 1.0.0-beta

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

InputGroup trong Input SDK 1.1.0-beta

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

InputGroup trong SDK đầu vào 1.1.0-beta (có chuỗi phiên bản)

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

Để biết thêm thông tin về cách xác định phiên bản của các 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 SDK đầu vào 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, bỏ chọn hoàn toàn không sử dụng tính năng gán 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 sử dụng để gán lại. Mỗi InputMap được xác định thông qua phương thức create() của SDK đầu vào 1.0.0-beta có thể gán 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 SDK đầu vào 1.0.0-beta

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

InputMap trong Input SDK 1.1.0-beta


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

Các bước tiếp theo

Tiếp tục nâng cấp lên phiên bản 1.1.0-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.