Java および Kotlin 用の Input SDK をバージョン 1.1 にアップグレードする

このガイドでは、ゲームを Java および Kotlin 用の 1.0.0 ベータ版 Input SDK から 1.1.0 ベータ版にアップグレードする方法について説明します。Unity 用の手順については、Unity のアップグレード ガイドをご覧ください。

リリースノート

PC 版 Google Play Games は、Input SDK を使用してゲームが提供するキー バインディングに基づくキーボード コントロールの再マッピングをサポートしています。

ユーザーがこの機能にアクセスするには、オーバーレイを開き、コントロールを選択してから、再マッピングするアクションをクリックします。

PC 版 Google Play Games は、ユーザーが再マッピングしたすべての入力をゲームのデフォルト入力にマッピングします。これにより、ゲームがプレーヤーの再マッピングを認識する必要がなくなります。ゲーム内のキーボード コントロールの表示など、ゲーム内アクションの新しい入力を把握する必要がある場合は、必要に応じてコールバックを登録してイベントの再マッピングを通知できます。

PC 版 Google Play Games では、各ユーザーの再マッピングされたコントロールがローカルに保存され、ゲーム セッション間で永続的に維持されます。これはローカルに保存されるため、モバイル エクスペリエンスに影響はなく、PC 版 Google Play Games をアンインストールすると削除されます。コントロール設定は、複数の PC デバイス間では保持されません。

ゲーム内でキーの再マッピングを有効にするために Input SDK をアップグレードする必要はありませんが、サポートされていない設定が検出された場合、ゲームで再マッピングが無効になることがあります。

入力再マッピング エクスペリエンスを制御する場合、またはゲームで再マッピング機能が無効になっている場合は、次の手順で解決します。

• Input SDK 1.1.0-beta にアップグレードします。
• サポートされていない設定を避けるため、キー バインディングを更新します。
• InputMap を更新して、再マッピング機能を有効にします。

ゲームの再マッピング機能を無効にし、一方でキー バインディングの読み取り専用バージョンを引き続き表示するには、次の手順を行います。

• Input SDK 1.1.0-beta にアップグレードします。
• InputMap を更新して、再マッピング機能を無効にします。

Input SDK のバージョンを 1.1.0-beta にアップグレードすると、InputContexts を使用して、PC 版 Google Play Games の高度な再マッピング機能を利用できます。これにより、ゲームのさまざまなシーンのコントロールの定義、再マッピング イベントをリッスンするためのコールバックの追加、ユーザーが再マッピングできない予約済みキーのセットの定義、InputAction、InputGroup、InputMap による再マッピング機能の無効化ができます。

新しい SDK バージョンにアップグレードする際は、次の例外を考慮してください。

サポートされていない設定

次の条件が満たされない場合、入力の再マッピングは無効になります。

• 複数のキーを使用する InputAction は、修飾キーと非修飾子キーで構成する必要があります。たとえば、Shift+A は有効ですが、A+B、Ctrl+Alt、Shift+A+Tab は有効ではありません。

• 2 つ以上の InputAction オブジェクトまたは InputGroup オブジェクトで同じ一意の ID を共有できません。

アップグレード

Input SDK 1.1.0-beta は、Input SDK 1.0.0-beta と下位互換性があります。Input SDK の以前の実装を使用しているゲームでも、サポートされていない設定を使用している場合を除き、基本的な再マッピングがサポートされます。以前のバージョンの Input SDK をゲームで使用している場合は、0.0.4 から 1.0.0 ベータ版へのアップグレード ガイドをご覧ください。

1.1.0 ベータ版にアップグレードすると、次のような新機能を利用できます。

• シーン制御の変更をトリガーする。
• キーマッピング イベントの通知を受信する。
• アクション、グループ、コンテキスト、マップにより再マッピングを無効化する。

依存関係をアップグレードする

Input SDK のインポートに Gradle を使用している場合は、最新バージョンにアップグレードしてください。

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

静的フィールドを定義する

バージョン 1.1.0-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 を更新する

注: InputAction の設計時には、Android ゲームのキーボードとマウスのコントロールに関するおすすめの方法を考慮して、サポートされていない設定が生じないよう注意してください。

Input SDK 1.0.0-beta の InputAction.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.0-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.0-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 を更新する

Input SDK 1.1.0-beta では、各 InputGroup を一意に識別する必要があります。各 InputAction は、関連するアクションのコレクションである InputGroup に属します。これにより、ゲームプレイ中のコントロールのナビゲーションと見つけやすさが向上します。InputAction では 1 つの InputContext のすべてのアクションの間で一意の ID が必要ですが、同様に InputGroup でも既存のグループ間で一意の ID が必要です。

このセクションの例では、ゲームに 2 つの 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-beta の InputGroup.create() メソッドも非推奨になりました。ゲームの InputGroup を更新し、バージョン ID と、グループ内の 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.0-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.0-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-beta の InputMap.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.0-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.0-beta へのアップグレードを続けます。

キー バインディングを更新する場合は、キー バインディングの設計に関するベスト プラクティスを参照し、再マッピング機能の制約と制限を考慮してください。