Upgrade des Input SDK für Java und Kotlin auf Version 1.1 durchführen

In dieser Anleitung wird erläutert, wie Sie Ihr Spiel von der Betaversion 1.0.0 des Input SDK für Java und Kotlin auf die Betaversion 1.1.1 aktualisieren. Eine Unity-spezifische Anleitung finden Sie im Unity-Upgradeleitfaden.

Versionshinweise

Google Play Spiele auf dem PC unterstützt die Neuzuordnung der Tastatursteuerung anhand der Tastenbelegungen, die dein Spiel mit dem Input SDK bereitstellt.

Nutzer greifen auf diese Funktion zu, indem sie das Overlay öffnen, Steuerelemente auswählen und dann auf die Aktion klicken, die sie neu zuordnen möchten.

In Google Play Spiele auf dem PC wird jede vom Nutzer neu belegte Eingabe der Standardeingabe Ihres Spiels zugeordnet. So muss Ihr Spiel nicht über die Neuzuordnung des Spielers informiert werden. Wenn du die neue Eingabe für eine In-Game-Aktion wie die Anzeige der Tastatursteuerung in deinem Spiel wissen musst, kannst du optional einen Callback registrieren, der über die Neuzuordnung von Ereignissen benachrichtigt wird.

In Google Play Spiele auf dem PC werden die neu zugewiesenen Steuerelemente jedes Nutzers lokal gespeichert, sodass sie über mehrere Spielsitzungen hinweg erhalten bleiben. Da diese Daten lokal gespeichert werden, haben sie keine Auswirkungen auf die Nutzung auf Mobilgeräten und werden gelöscht, wenn Google Play Spiele auf dem PC deinstalliert wird. Die Steuereinstellungen werden nicht auf mehreren PC-Geräten gespeichert.

Sie müssen das Input SDK nicht aktualisieren, um die Tastenneuzuordnung in Ihrem Spiel zu aktivieren. Die Neuzuordnung kann jedoch für Ihr Spiel deaktiviert werden, wenn eine nicht unterstützte Konfiguration erkannt wird.

Wenn Sie die Eingabeumwandlung steuern möchten oder die Funktion für Ihr Spiel deaktiviert ist, führen Sie die folgenden Schritte aus, um das Problem zu beheben:

• Führen Sie ein Upgrade auf das Input SDK 1.1.1-beta durch.
• Aktualisieren Sie alle Tastaturbindungen, um die nicht unterstützten Konfigurationen zu vermeiden.
• Aktualisieren Sie Ihre InputMap, um die Funktion zum Neuzuordnen zu aktivieren.

Wenn Sie die Neuzuordnungsfunktion für Ihr Spiel deaktivieren, aber die schreibgeschützte Version Ihrer Tastenkombinationen weiterhin anzeigen lassen möchten, gehen Sie so vor:

• Führen Sie ein Upgrade auf das Input SDK 1.1.1-beta durch.
• Aktualisieren Sie Ihre InputMap, um die Funktion zum Neuzuordnen auf deaktiviert zu setzen.

Sie können Ihre Version des Input SDK auf 1.1.1-beta aktualisieren, um die erweiterten Funktionen zur Tastenbelegung in Google Play Spiele auf dem PC zu nutzen. Verwenden Sie dazu InputContexts, um Steuerelemente für verschiedene Szenen Ihres Spiels zu definieren, Callbacks hinzuzufügen, um auf Tastenbelegungsereignisse zu warten, eine Reihe reservierter Tasten zu definieren, auf die der Nutzer nicht umverknüpfen kann, und die Tastenbelegungsfunktion für InputAction, InputGroup oder InputMap zu deaktivieren.

Beachten Sie beim Upgrade auf die neue SDK-Version die folgenden Ausnahmen:

Nicht unterstützte Konfigurationen

Die Eingabeumwandlung ist deaktiviert, wenn die folgenden Bedingungen nicht erfüllt sind:

• Eine InputAction, die mehrere Tasten verwendet, muss aus einer Modifikatortaste und einer anderen Taste bestehen. Umschalttaste + A ist beispielsweise gültig, A + B, Strg + Alt und Umschalttaste + A + Tabulatortaste hingegen nicht.

• Mindestens zwei InputAction- oder InputGroup-Objekte können nicht dieselbe eindeutige ID haben.

Upgrade

Das Input SDK 1.1.1-Beta ist abwärtskompatibel mit dem Input SDK 1.0.0-Beta. Spiele, die frühere Implementierungen des Input SDK verwenden, unterstützen weiterhin die grundlegende Neuzuordnung, es sei denn, sie verwenden eine nicht unterstützte Konfiguration. Wenn in Ihrem Spiel eine frühere Version des Input SDK verwendet wird, lesen Sie den Leitfaden zum Upgrade von 0.0.4 auf 1.0.0-Beta.

Durch das Upgrade auf 1.1.1-Beta stehen Ihnen neue Funktionen zur Verfügung, darunter:

• Änderungen der Szenensteuerung auslösen
• Benachrichtigungen zu Tastenbelegungsereignissen erhalten
• Neuzuordnung nach Aktion, Gruppe, Kontext oder Karte deaktivieren

Abhängigkeit aktualisieren

Wenn Sie das Input SDK mit Gradle importieren, führen Sie ein Upgrade auf die neueste Version durch:

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

Statische Felder definieren

Für Version 1.1.1-beta empfiehlt es sich, die Objekte InputAction, InputGroup, InputContext und InputMap als statische Felder der Klasse InputMappingProvider zu definieren, da auf diese Felder von anderen Teilen Ihrer Anwendung aus zugegriffen werden kann:

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 aktualisieren

Hinweis: Berücksichtigen Sie die Best Practices für die Tastatur- und Maussteuerung in Android-Spielen, wenn Sie eine InputAction entwerfen, und vermeiden Sie die nicht unterstützten Konfigurationen.

Die Methode InputAction.create() des Input SDK 1.0.0-beta ist veraltet. Ein InputAction hat jetzt eine Versionskennung und kann als umkehrbar oder nicht umkehrbar gekennzeichnet werden. Eine InputAction, die mit der create()-Methode des Input SDK definiert wird, ist standardmäßig anpassbar und enthält keine Versionsinformationen:1.0.0-beta

InputAction in 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 im 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 im Input SDK 1.1.1-Beta (mit Versionsstring)

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

Weitere Informationen zur Versionierung von Tastenkombinationen finden Sie unter Schlüssel-IDs erfassen.

InputGroups aktualisieren

Im Input-SDK 1.1.1-beta müssen Sie jeden InputGroup eindeutig identifizieren. Jedes InputAction gehört zu einem InputGroup, einer Gruppe ähnlicher Aktionen. Dadurch wird die Navigation und Sichtbarkeit der Steuerelemente während des Spiels verbessert. Genauso wie InputAction eine eindeutige Kennung unter allen Aktionen in einer einzelnen InputContext haben muss, muss eine InputGroup eine eindeutige ID für alle vorhandenen Gruppen haben.

In den Beispielen in diesem Abschnitt hat ein Spiel zwei InputContext-Objekte, die das Hauptmenü und das Gameplay darstellen. In diesen Kontexten werden für jede InputGroup die entsprechenden IDs mithilfe der folgenden Aufzählung erfasst:

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
}

Wie InputAction wurde auch die Methode InputGroup.create() des Input SDKs 1.0.0-beta eingestellt. Sie müssen Ihre InputGroup in Ihrem Spiel mit einer Versions-ID und einem booleschen Wert aktualisieren, der angibt, ob die InputAction-Objekte in Ihren Gruppen neu zugewiesen werden können. Gruppen, die mit der verworfenen Methode 1.0.0-beta create() des Eingabe-SDK erstellt wurden, sind anpassbar, haben die ID 0 und die Versions-ID ist ein leerer String (""):

InputGroup im 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 im 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 im Input SDK 1.1.1-beta (mit Versionsstring)

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

Weitere Informationen zur Versionierung von Tastenkombinationen finden Sie unter Schlüssel-IDs erfassen.

InputMap aktualisieren

Die Methode InputMap.create() des Input SDK 1.0.0-beta ist eingestellt. Aktualisieren Sie Ihre InputMap, um eine Versions-ID zuzuweisen, die Funktion zum Neuzuordnen vollständig zu deaktivieren oder Ihrem Spiel eine Liste reservierter Tasten zuzuweisen, die nicht vom Nutzer neu zugeordnet werden sollen. Jede InputMap, die mit der Input SDK-Methode 1.0.0-beta create() definiert ist, kann standardmäßig neu zugeordnet werden, wird mit der ID 0 identifiziert und hat keine reservierten Schlüssel.

InputMap im 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 in 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()
                )
        )
);

Nächste Schritte

Fahren Sie mit dem Upgrade auf 1.1.1-Beta fort, indem Sie mit InputContexts verschiedene Steuerelemente für verschiedene Szenen zuweisen oder die Benutzeroberfläche Ihres Spiels mit InputRemappingListeners aktualisieren, indem Sie Benachrichtigungen zur Neuzuordnung von Ereignissen erhalten.

Beachten Sie beim Aktualisieren Ihrer Tastenkürzel die Best Practices für die Gestaltung von Tastenkürzeln und die Einschränkungen und Einschränkungen der Funktion zum Neuverknüpfen.