Java 및 Kotlin용 입력 SDK를 버전 1.1로 업그레이드

이 가이드에서는 게임을 Java 및 Kotlin용 1.0.0-beta 입력 SDK에서 1.1.1-beta로 업그레이드하는 방법을 설명합니다. Unity 관련 안내는 Unity 업그레이드 가이드를 참고하세요.

출시 노트

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

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

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

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

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

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

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

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

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

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

새 SDK 버전으로 업그레이드하는 동안 다음 예외를 고려하세요.

지원되지 않는 구성

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

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

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

업그레이드

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

1.1.1-beta로 업그레이드하면 다음과 같은 새로운 기능을 사용할 수 있습니다.

종속 항목 업그레이드

Gradle을 사용하여 입력 SDK를 가져오는 경우 최신 버전으로 업그레이드하세요.

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

정적 필드 정의

1.1.1-beta 버전의 경우 InputAction, InputGroup, InputContext, InputMap 객체를 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;
    }
}

InputActions 업데이트

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

입력 SDK 1.0.0-beta의 InputAction

Kotlin

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

입력 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
}

자바

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

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

InputGroups 업데이트

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

입력 SDK 1.0.0-beta의 InputGroup

Kotlin

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

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

자바

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

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

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

입력 SDK 1.0.0-beta의 InputMap

Kotlin

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

자바

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

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

다음 단계

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

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