Gamepady

Wiązania gamepada pozwalają przypisać standardowe wejście z gamepada do funkcji gry. Wejście z gamepada obejmuje wiązania dla:

• lewej i prawej gałki analogowej: kierunek i kliknięcie
• lewej i prawej krzyżaka cyfrowego. Prawy krzyżak zwykle odpowiada przyciskom “A”, “B”, “X” i “Y” na kontrolerze Xbox oraz przyciskom “square”, “circle”, “triangle” i “cross” na kontrolerze PlayStation
• lewego i prawego spustu
• lewego i prawego przycisku naramiennego
• przycisków Start, Back i Guide

Przyciski cyfrowe

Przyciski cyfrowe generują zdarzenia pressed, released i repeated. Poniższy przykład pokazuje, jak wykryć wejście z przycisku cyfrowego (naciśnięcie albo zwolnienie):

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lpad_left") then
        if action.pressed then
            -- rozpocznij ruch w lewo
        elseif action.released then
            -- zatrzymaj ruch w lewo
        end
    end
end

Gałki analogowe

Gałki analogowe generują ciągłe zdarzenia wejścia, gdy gałka zostanie przesunięta poza martwą strefę zdefiniowaną w pliku ustawień gamepada (patrz niżej). Poniższy przykład pokazuje, jak wykryć wejście z gałki analogowej:

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lstick_down") then
        -- lewa gałka została przesunięta w dół
        print(action.value) -- wartość między 0.0 a -1.0
    end
end

Gałki analogowe generują też zdarzenia pressed i released, gdy są przesuwane w kierunkach kardynalnych powyżej określonej wartości progowej. Dzięki temu można też używać gałki analogowej jako cyfrowego wejścia kierunkowego:

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lstick_down") and action.pressed then
        -- lewa gałka została przesunięta do skrajnej dolnej pozycji
    end
end

Wiele gamepadów

Defold obsługuje wiele gamepadów przez system operacyjny hosta, a akcje ustawiają pole gamepad w tabeli akcji na numer gamepada, z którego pochodzi dane wejście:

function on_input(self, action_id, action)
    if action_id == hash("gamepad_start") then
        if action.gamepad == 0 then
          -- gamepad 0 chce dołączyć do gry
        end
    end
end

Podłączanie i odłączanie

Wiązania wejścia z gamepada udostępniają też dwa osobne wiązania o nazwach Connected i Disconnected, aby wykrywać moment podłączenia gamepada, także wtedy, gdy był podłączony od początku, lub jego odłączenia.

function on_input(self, action_id, action)
    if action_id == hash("gamepad_connected") then
        if action.gamepad == 0 then
          -- gamepad 0 został podłączony
        end
    elseif action_id == hash("gamepad_disconnected") then
        if action.gamepad == 0 then
          -- gamepad 0 został odłączony
        end
    end
end

Surowe gamepady

(Od wersji Defold 1.2.183)

Wiązania wejścia z gamepada udostępniają także osobne wiązanie o nazwie Raw, które daje nieprzefiltrowane dane wejściowe przycisków, osi i hatów dowolnego podłączonego gamepada, bez zastosowanej martwej strefy.

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

Plik ustawień gamepadów

Konfiguracja wejścia z gamepada używa osobnego pliku mapowań dla każdego typu sprzętowego gamepada. Mapowania dla konkretnych sprzętowych gamepadów są zapisane w pliku gamepads. Defold dostarcza wbudowany plik gamepads z ustawieniami dla popularnych gamepadów:

Jeśli musisz utworzyć nowy plik ustawień gamepadów, dostępne jest proste narzędzie pomocnicze:

Kliknij, aby pobrać gdc.zip.

Zawiera ono pliki binarne dla systemów Windows, Linux i macOS. Uruchom je z wiersza poleceń:

./gdc

Narzędzie poprosi o naciskanie kolejnych przycisków na podłączonym kontrolerze. Następnie wygeneruje nowy plik gamepads z poprawnymi mapowaniami dla Twojego kontrolera. Zapisz nowy plik albo scal go z istniejącym plikiem gamepads, a potem zaktualizuj ustawienie w game.project:

Niezidentyfikowane gamepady

(Od wersji Defold 1.2.186)

Gdy gamepad jest podłączony i nie ma dla niego mapowania, będzie generował tylko akcje connected, disconnected i raw. W takim przypadku trzeba ręcznie zmapować surowe dane gamepada na akcje w grze.

(Od wersji Defold 1.4.8)

Można sprawdzić, czy akcja wejścia z gamepada pochodzi z nieznanego gamepada, odczytując wartość gamepad_unknown z akcji:

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

Gamepady w HTML5

Gamepady są obsługiwane w buildach HTML5 i generują te same zdarzenia wejścia co na innych platformach. Obsługa gamepadów opiera się na Gamepad API, które jest obsługiwane przez większość przeglądarek (sprawdź tabelę zgodności). Jeśli przeglądarka nie obsługuje Gamepad API, Defold po prostu zignoruje wszystkie wiązania gamepada w projekcie. Możesz sprawdzić, czy przeglądarka obsługuje Gamepad API, testując, czy funkcja getGamepads istnieje w obiekcie navigator:

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

Jeśli gra działa wewnątrz iframe, upewnij się też, że iframe ma dodane uprawnienie gamepad:

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

Standardowe gamepady

(Od wersji Defold 1.4.1)

Jeśli podłączony gamepad zostanie rozpoznany przez przeglądarkę jako standardowy gamepad, użyje mapowania “Standard Gamepad” z pliku ustawień gamepads (mapowanie standardowego gamepada jest dołączone do pliku default.gamepads w /builtins). Standardowy gamepad ma 16 przycisków i 2 gałki analogowe, a układ przycisków jest podobny do kontrolera PlayStation lub Xbox (więcej informacji znajdziesz w definicji i układzie przycisków W3C). Jeśli podłączony gamepad nie zostanie rozpoznany jako standardowy, Defold poszuka w pliku ustawień gamepadów mapowania pasującego do jego typu sprzętowego.

Gamepady w Windows

W systemie Windows obecnie obsługiwane są tylko kontrolery Xbox 360. Aby podłączyć kontroler 360 do komputera z Windows, upewnij się, że został poprawnie skonfigurowany zgodnie z tym poradnikiem.

Gamepady w Android

(Od wersji Defold 1.2.183)

Gamepady są obsługiwane w buildach Android i generują te same zdarzenia wejścia co na innych platformach. Obsługa gamepadów opiera się na systemie wejścia Android dla zdarzeń klawiszy i ruchu. Zdarzenia wejścia Android są tłumaczone na zdarzenia gamepada Defold przy użyciu tego samego pliku gamepad opisanego powyżej.

Przy dodawaniu dodatkowych wiązań gamepada w Android możesz użyć poniższych tabel do przetłumaczenia zdarzeń wejścia Android na wartości pliku gamepad:

(Definicje KeyEvent Android)

(Definicje MotionEvent Android)

Użyj tej tabeli razem z aplikacją testową gamepadów ze Sklepu Google Play, aby ustalić, do jakiego zdarzenia przypisany jest każdy przycisk na Twoim gamepadzie.