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

Gamepad-Zuordnungen übersetzen Tasten, Achsen und Steuerkreuze eines Controllers in die Standardsteuerungen deiner Eingabebindungen. Defold kombiniert zwei Zuordnungsquellen, die im Abschnitt Input von game.project konfiguriert werden:

SDL-Datenbankzuordnungen und automatische Plattformzuordnungen verwenden Gamepad Deadzone. Bisherige .gamepads-Einträge definieren ihre eigenen Totzonen. Unter Android kann ein Controller ohne Datenbankeintrag auch eine automatische Zuordnung erhalten.

Bisherige .gamepads-Zuordnungen

Eine .gamepads-Datei kann Zuordnungen für mehrere Controller enthalten. Bestehende bisherige Zuordnungen werden weiterhin unterstützt. Die Standarddatei von Defold enthält Zuordnungen für gängige Controller:

Wenn du auf einer Desktop-Plattform eine bisherige .gamepads-Zuordnung erstellen musst, kann das folgende Werkzeug helfen. Für Android siehe Gamepads unter Android.

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 weder eine konfigurierte noch eine automatische Plattformzuordnung verfügbar ist, erzeugt das Gamepad nur die an Connected, Disconnected und Raw gebundenen Aktionen. Du kannst eine Controller-Zuordnung hinzufügen oder die Roheingaben im Spiel verarbeiten.

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 Eingabeaktionen wie auf anderen Plattformen. Defold verwendet die konfigurierten Gamepad-Zuordnungen und kann einige Controller ohne passenden Eintrag automatisch zuordnen.

Wird ein Controller nicht erkannt oder funktionieren seine Steuerungen falsch, teste ihn auf dem Android-Gerät und ergänze oder aktualisiere seine Zuordnung. Hinweise zur Fehlerbehebung findest du unter Nicht erkannte Gamepads und Gamepad-Roheingaben.