Unity용 입력 SDK를 버전 1.1로 업그레이드

이 가이드에서는 게임을 1.0에서 Unity용 1.1 입력 SDK로 업그레이드하는 방법을 설명합니다. Java 및 Kotlin 안내는 여기를 클릭하세요.

출시 노트

PC용 Google Play 게임즈는 입력 SDK를 사용하여 게임에서 제공하는 키 바인딩을 기반으로 키보드 컨트롤의 재매핑을 지원합니다.

사용자는 오버레이를 열고 컨트롤을 선택한 후 재매핑하려는 작업을 클릭하여 이 기능에 액세스합니다.

PC용 Google Play 게임즈는 사용자가 재매핑한 모든 입력을 게임의 기본 입력에 매핑합니다. 이렇게 하면 게임이 플레이어의 재매핑을 인식할 필요가 없습니다. 게임 내 키보드 컨트롤 표시와 같은 인게임 작업의 새로운 입력을 알아야 하는 경우 재매핑 이벤트에 관한 알림을 받을 콜백을 선택적으로 등록할 수 있습니다.

PC용 Google Play 게임즈는 사용자의 재매핑 컨트롤을 로컬에 저장하여 게임 세션 전반에 걸쳐 유지합니다. 이러한 설정은 로컬에 저장되므로 모바일 환경에 영향을 미치지 않으며 PC용 Google Play 게임즈를 제거하면 삭제됩니다. 설정은 여러 PC 기기에서 유지되지 않습니다.

게임에서 키 재매핑을 사용 설정하기 위해 입력 SDK를 업그레이드할 필요는 없지만 지원되지 않는 구성이 감지되면 게임에서 재매핑이 사용 중지됩니다.

입력 재매핑 환경을 제어하려는 경우 또는 게임에서 재매핑 기능이 사용 중지된 경우 다음 단계를 따르세요.

• 입력 SDK 1.1.0-beta로 업그레이드합니다.
• 지원되지 않는 구성을 방지하려면 모든 키 바인딩을 업데이트합니다.
• InputMap을 업데이트하여 재매핑 기능을 사용 설정합니다.

읽기 전용 키 바인딩 버전을 계속 표시하면서 게임의 재매핑 기능을 선택 해제하려면 다음 단계를 따르세요.

• 입력 SDK 1.1.0-beta로 업그레이드합니다.
• InputMap을 업데이트하여 재매핑 기능을 사용 중지합니다.

입력 SDK 버전을 1.1.0-beta로 업그레이드하면 InputContexts를 사용하여 게임의 다양한 장면에 관한 컨트롤을 정의하고, 재매핑 이벤트를 수신 대기하는 콜백을 추가하고, 사용자가 재매핑할 수 없는 예약된 키 집합을 정의하고, InputAction, InputGroup 또는 InputMap별로 재매핑 기능을 사용 중지하는 방식으로 PC용 Google Play 게임즈의 고급 재매핑 기능을 활용할 수 있습니다.

업그레이드할 때 다음 예외를 고려하세요.

지원되지 않는 구성

다음 조건이 충족되지 않으면 입력 재매핑이 사용 중지됩니다.

• 여러 키를 활용하는 InputAction은 특수키와 비 특수키로 구성되어야 합니다. 예를 들어 Shift + A는 유효하지만 A + B, Ctrl + Alt, Shift + A + Tab은 유효하지 않습니다.

• 둘 이상의 InputAction 또는 InputGroup 객체는 동일한 고유 ID를 공유할 수 없습니다.

InputContext 소개

InputContext를 사용하면 게임에서 충돌 없이 게임의 여러 작업에 동일한 키를 사용할 수 있습니다. 이렇게 하면 게임플레이 중에 점프하고 메뉴 선택을 확인하는 데 게임에서 스페이스바를 사용하는 경우 플레이어는 개별적으로 메뉴에서 space를 enter로, 게임플레이 중에 space를 up arrow로 재매핑할 수 있습니다.

다음 시퀀스 다이어그램은 setInputContext() API가 런타임에 작동하는 방식을 보여줍니다.

업그레이드

입력 SDK의 이전 구현을 사용하는 게임은 지원되지 않는 구성을 사용하지 않는 한 기본 재매핑을 계속 지원합니다. 게임에서 이전 버전의 입력 SDK를 사용하는 경우 0.0.4에서 1.0.0-beta로의 업그레이드 가이드를 읽어보세요.

1.1.0-beta로 업그레이드하면 다음과 같은 새로운 기능이 제공됩니다.

• 컨텍스트 변경 트리거
• 키 매핑 이벤트 알림 수신
• Action, Group, Context 또는 Map별로 재매핑 사용 중지

설치

Unity 플러그인 v1.1.0-beta를 사용할 수 있습니다. 게임에 설치된 이전 버전의 입력 SDK를 삭제하고 현재 버전으로 업그레이드해야 합니다.

입력 SDK v1.1.0-beta를 게임에 추가하려면 SDK 추가를 참고하세요.

정적 필드 정의

버전 1.1.0-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

InputActions 업데이트

입력 SDK 1.0.0-beta의 InputAction.create() 메서드는 지원 중단되었습니다. InputAction은 버전 식별자가 있으며 매핑 가능 또는 불가능으로 표시할 수 있습니다. 입력 SDK 1.0.0-beta create() 메서드를 사용하여 정의된 InputAction은 기본적으로 재매핑할 수 있으며 버전 관리 정보를 포함하지 않습니다.

입력 SDK 1.0.0-beta의 InputAction

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

입력 SDK 1.1.0-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
);

입력 SDK 1.1.0-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 추적을 참고하세요.

InputGroups 업데이트

입력 SDK 1.1.0-beta에서는 각 InputGroup을 고유하게 식별해야 합니다. 각 InputAction은 관련 작업 모음인 InputGroup에 속합니다. 이를 통해 게임플레이 중에 컨트롤의 탐색 및 검색 가능성이 향상됩니다. InputAction이 단일 InputContext의 모든 작업 간에 고유 식별자를 가져야 하는 것처럼 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과 마찬가지로 입력 SDK 1.0.0-beta의 InputGroup.create() 메서드가 지원 중단되었습니다. 그룹의 InputAction 객체를 재매핑할 수 있는지 나타내는 불리언 값과 버전 식별자를 사용하여 게임의 InputGroup을 업데이트해야 합니다. 지원 중단된 입력 SDK 1.0.0-beta create() 메서드로 만든 그룹은 재매핑할 수 있고, ID는 0이며, 버전 ID는 빈 문자열("")입니다.

입력 SDK 1.0.0-beta의 InputGroup

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

입력 SDK 1.1.0-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
);

입력 SDK 1.1.0-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 업데이트

입력 SDK 1.0.0-beta의 InputMap.create() 메서드가 지원 중단되었습니다. InputMap을 업데이트하여 버전 식별자를 할당하거나, 재매핑 기능을 완전히 선택 해제하거나, 사용자가 재매핑하는 데 사용하지 않을 게임의 예약된 키 목록을 할당합니다. 입력 SDK 1.0.0-beta create() 메서드를 사용하여 정의된 모든 InputMap은 기본적으로 재매핑할 수 있으며, ID 0으로 식별되고, 예약된 키를 포함하지 않습니다.

입력 SDK 1.0.0-beta의 InputMap

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

입력 SDK 1.1.0-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()
);

다음 단계

InputContexts를 사용하여 다른 장면에 다른 컨트롤을 할당하거나, InputRemappingListeners를 사용하여 재매핑 이벤트에 관한 알림을 받아 게임의 UI를 업데이트하여 1.1.0-beta로 계속 업그레이드하세요.

키 바인딩을 업데이트할 때는 키 바인딩 설계 권장사항을 살펴보고 재매핑 기능의 제약사항과 제한사항을 고려하세요.