Gamepads

Mit Gamepad-Eingabeauslösern kannst du Standardeingaben von Gamepads an Spielfunktionen binden. Bei Gamepad-Eingaben kannst du eine Eingabebindung (input binding) für folgende Bedienelemente anlegen:

• Linker und rechter Stick (Richtung und Klicks)
• Linkes und rechtes digitales Steuerkreuz. Das rechte Steuerkreuz entspricht normalerweise den Tasten „A“, „B“, „X“ und „Y“ des Xbox-Controllers sowie den Tasten „Quadrat“, „Kreis“, „Dreieck“ und „Kreuz“ des PlayStation-Controllers.
• Linker und rechter Trigger
• Linke und rechte Schultertaste
• Tasten Start, Back und Guide

Digitale Tasten

Digitale Tasten erzeugen die Ereignisse pressed, released und repeated. Das folgende Beispiel zeigt, wie du Eingaben einer digitalen Taste erkennst (Drücken oder Loslassen):

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lpad_left") then
        if action.pressed then
            -- start moving left
        elseif action.released then
            -- stop moving left
        end
    end
end

Analogsticks

Analogsticks erzeugen fortlaufend Eingabeereignisse, wenn der Stick außerhalb der Totzone bewegt wird, die in der Gamepad-Einstellungsdatei definiert ist (siehe unten). Das folgende Beispiel zeigt, wie du Eingaben eines Analogsticks erkennst:

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lstick_down") then
        -- left stick was moved down
        print(action.value) -- a value between 0.0 an -1.0
    end
end

Analogsticks erzeugen auch die Ereignisse pressed und released, wenn sie in eine der vier Hauptrichtungen über einen bestimmten Schwellenwert hinaus bewegt werden. So lässt sich ein Analogstick einfach auch als digitale Richtungseingabe verwenden:

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lstick_down") and action.pressed then
        -- left stick was moved to its extreme down position
    end
end

Mehrere Gamepads

Defold unterstützt mehrere Gamepads über das Betriebssystem des Geräts. Aktionen setzen das Feld gamepad der Tabelle action auf die Nummer des Gamepads, von dem die Eingabe stammt:

function on_input(self, action_id, action)
    if action_id == hash("gamepad_start") then
        if action.gamepad == 0 then
          -- gamepad 0 wants to join the game
        end
    end
end

Verbinden und Trennen

Gamepad-Eingabebindungen bieten auch zwei separate Bindungen namens Connected und Disconnected, mit denen du erkennst, wenn ein Gamepad verbunden (einschließlich der bereits beim Start verbundenen Geräte) oder getrennt wird.

function on_input(self, action_id, action)
    if action_id == hash("gamepad_connected") then
        if action.gamepad == 0 then
          -- gamepad 0 was connected
        end
    elseif action_id == hash("gamepad_disconnected") then
        if action.gamepad == 0 then
          -- gamepad 0 was disconnected
        end
    end
end

Gamepad-Rohdaten

Gamepad-Eingabebindungen bieten außerdem eine separate Bindung namens Raw, die ungefilterte Eingaben (ohne Anwendung der Totzone) der Tasten, Achsen und Rundblickschalter (Hats) jedes verbundenen Gamepads liefert.

function on_input(self, action_id, action)
    if action_id == hash("raw") then
        pprint(action.gamepad_buttons)
        pprint(action.gamepad_axis)
        pprint(action.gamepad_hats)
    end
end

Gamepad-Einstellungsdatei

Zum Einrichten der Gamepad-Eingabe wird für jeden Gamepad-Hardwaretyp eine separate Zuordnungsdatei verwendet. Die Zuordnungen für bestimmte Gamepad-Modelle werden in einer gamepads-Datei festgelegt. Defold enthält eine integrierte gamepads-Datei mit Einstellungen für gängige Gamepads:

Wenn du eine neue Gamepad-Einstellungsdatei erstellen musst, steht dir dafür ein einfaches Werkzeug zur Verfügung:

Klicke hier, um gdc.zip herunterzuladen.

Es enthält ausführbare Dateien für Windows, Linux und macOS. Starte es über die Kommandozeile:

./gdc

Das Werkzeug fordert dich auf, verschiedene Tasten auf deinem verbundenen Controller zu drücken. Anschließend gibt es eine neue gamepads-Datei mit den korrekten Zuordnungen für deinen Controller aus. Speichere die neue Datei oder führe sie mit deiner vorhandenen gamepads-Datei zusammen. Aktualisiere dann die Einstellung in game.project:

Nicht identifizierte Gamepads

Wenn ein Gamepad verbunden wird und keine Zuordnung dafür vorhanden ist, erzeugt es nur die Aktionen connected, disconnected und raw. In diesem Fall musst du die Gamepad-Rohdaten manuell den Aktionen in deinem Spiel zuordnen.

Du kannst prüfen, ob eine Eingabeaktion für ein Gamepad von einem unbekannten Gamepad stammt, indem du den Wert gamepad_unknown aus action ausliest:

function on_input(self, action_id, action)
    if action_id == hash("connected") then
        if action.gamepad_unknown then
            print("The connected gamepad is unidentified and will only generate raw input")
        else
            print("The connected gamepad is known and will generate input actions for buttons and sticks")
        end
    end
end

Gamepads in HTML5

Gamepads werden in HTML5-Builds unterstützt und erzeugen dieselben Eingabeereignisse wie auf anderen Plattformen. Die Gamepad-Unterstützung basiert auf der Gamepad API, die von den meisten Browsern unterstützt wird (siehe diese Kompatibilitätsübersicht). Wenn der Browser die Gamepad API nicht unterstützt, ignoriert Defold alle Gamepad-Eingabeauslöser in deinem Projekt ohne Meldung. Du kannst feststellen, ob der Browser die Gamepad API unterstützt, indem du prüfst, ob die Funktion getGamepads am Objekt navigator vorhanden ist:

local function supports_gamepads()
    return not html5 or (html5.run('typeof navigator.getGamepads === "function"') == "true")
end

if supports_gamepads() then
    print("Platform supports gamepads")
end

Wenn dein Spiel innerhalb eines iframe läuft, musst du außerdem sicherstellen, dass dem iframe die Berechtigung gamepad hinzugefügt wurde:

<iframe allow="gamepad"></iframe>

Standard-Gamepad

Wenn der Browser ein verbundenes Gamepad als Standard-Gamepad erkennt, verwendet es die Zuordnung für Standard Gamepad in der Gamepad-Einstellungsdatei (eine Zuordnung für Standard Gamepad ist in der Datei default.gamepads unter /builtins enthalten). Ein Standard-Gamepad ist als Gerät mit 16 Tasten und 2 Analogsticks definiert, dessen Tastenanordnung der eines PlayStation- oder Xbox-Controllers ähnelt (weitere Informationen findest du in der W3C-Definition und Tastenanordnung). Wenn das verbundene Gamepad nicht als Standard-Gamepad erkannt wird, sucht Defold in der Gamepad-Einstellungsdatei nach einer Zuordnung, die dem Gamepad-Hardwaretyp entspricht.

Gamepads unter Windows

Unter Windows werden derzeit nur XBox-360-Controller unterstützt. Um deinen 360-Controller mit deinem Windows-Rechner zu verbinden, stelle sicher, dass er korrekt eingerichtet ist.

Gamepads unter Android

Gamepads werden in Android-Builds unterstützt und erzeugen dieselben Eingabeereignisse wie auf anderen Plattformen. Die Gamepad-Unterstützung basiert auf dem Android-Eingabesystem für Tasten- und Bewegungsereignisse. Die Android-Eingabeereignisse werden mithilfe derselben gamepad-Datei wie oben beschrieben in Defold-Gamepad-Ereignisse umgewandelt.

Wenn du unter Android zusätzliche Gamepad-Bindungen hinzufügst, kannst du die folgenden Zuordnungstabellen verwenden, um Android-Eingabeereignisse in Werte für die gamepad-Datei zu übersetzen:

(Android-Definitionen für KeyEvent)

(Android-Definitionen für MotionEvent)

Verwende diese Zuordnungstabelle zusammen mit einer Gamepad-Test-App aus dem Google Play Store, um herauszufinden, welchem Tastenereignis jede Taste deines Gamepads zugeordnet ist.