Геймпади

Тригери геймпада дають змогу прив’язати стандартне введення з геймпада до функцій гри. Для введення з геймпада доступні прив’язки до таких елементів:

• Лівий і правий стіки (напрямок і натискання)
• Ліва та права групи цифрових кнопок. Права група зазвичай відповідає кнопкам «A», «B», «X» і «Y» на контролері Xbox та кнопкам «квадрат», «коло», «трикутник» і «хрестик» на контролері Playstation.
• Лівий і правий курки
• Ліва та права плечові кнопки
• Кнопки Start, Back і Guide

Цифрові кнопки

Цифрові кнопки генерують події pressed, released і repeated. Приклад виявлення введення з цифрової кнопки (натискання або відпускання):

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

Аналогові стіки

Аналогові стіки безперервно генерують події введення, коли стік відхилено за межі мертвої зони, визначеної у файлі налаштувань геймпадів (див. нижче). Приклад виявлення введення з аналогового стіка:

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

Аналогові стіки також генерують події pressed і released, коли відхилення в основних напрямках перетинає певне порогове значення. Завдяки цьому аналоговий стік також легко використовувати для цифрового введення напрямку:

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

Кілька геймпадів

Defold підтримує кілька геймпадів через операційну систему пристрою. У полі gamepad таблиці action для дії вказується номер геймпада, з якого надійшло введення:

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

Підключення й відключення

Прив’язки введення з геймпада також містять дві окремі прив’язки з назвами Connected і Disconnected, які дають змогу виявляти підключення геймпада (навіть якщо він був підключений від початку) або його відключення.

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

Необроблені дані геймпадів

Прив’язки введення з геймпада також містять окрему прив’язку з назвою Raw, яка надає нефільтроване (без застосування мертвої зони) введення з кнопок, осей і перемикачів напрямку (hat) будь-якого підключеного геймпада.

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

Файл налаштувань геймпадів

Відповідності геймпадів перетворюють кнопки, осі й перемикачі hat контролера на стандартні елементи керування, які використовують прив’язки введення. Defold поєднує два джерела відповідностей, налаштовані в розділі Input файлу game.project:

Відповідності бази SDL й автоматичні відповідності платформи використовують Gamepad Deadzone. Застарілі записи .gamepads визначають власні мертві зони. На Android контролер без запису в базі також може отримати автоматичну відповідність.

Застарілі відповідності .gamepads

Файл .gamepads може містити відповідності для кількох контролерів. Наявні застарілі відповідності залишаються підтримуваними. Defold містить відповідності поширених контролерів у типовому файлі:

Якщо потрібно створити застарілу відповідність .gamepads на настільній платформі, допоможе наведений нижче інструмент. Для Android див. Геймпади на Android.

Натисніть, щоб завантажити gdc.zip.

Він містить виконувані файли для Windows, Linux і macOS. Запустіть його з командного рядка:

./gdc

Інструмент попросить вас натискати різні кнопки на підключеному контролері. Після цього він створить новий файл gamepads із правильними відповідностями для вашого контролера. Збережіть новий файл або об’єднайте його з наявним файлом gamepads, а потім оновіть налаштування в game.project:

Нерозпізнані геймпади

Якщо немає ані налаштованої відповідності, ані автоматичної відповідності платформи, геймпад генерує лише дії, прив’язані до Connected, Disconnected і Raw. Ви можете додати відповідність контролера або обробляти його необроблене введення у грі.

Щоб перевірити, чи надійшла дія введення з невідомого геймпада, прочитайте значення gamepad_unknown у таблиці action:

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

Геймпади в HTML5

Геймпади підтримуються у збірках HTML5 і генерують ті самі події введення, що й на інших платформах. Підтримка геймпадів ґрунтується на Gamepad API, який підтримується більшістю браузерів (див. цю таблицю підтримки). Якщо браузер не підтримує Gamepad API, Defold без жодних повідомлень ігноруватиме всі тригери геймпадів у вашому проєкті. Щоб перевірити, чи підтримує браузер Gamepad API, перевірте наявність функції getGamepads в об’єкті 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

Якщо ваша гра працює всередині iframe, також переконайтеся, що для цього iframe додано дозвіл gamepad:

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

Стандартний геймпад

Якщо браузер розпізнає підключений геймпад як стандартний, для нього використовуватимуться відповідності Standard Gamepad із файлу налаштувань геймпадів (відповідності Standard Gamepad включено до файлу default.gamepads у /builtins). Стандартний геймпад визначається як пристрій із 16 кнопками та 2 аналоговими стіками, розташування кнопок якого подібне до контролера PlayStation або Xbox (докладніше див. визначення та розташування кнопок у W3C). Якщо підключений геймпад не розпізнано як стандартний, Defold шукатиме у файлі налаштувань геймпадів відповідності для типу цього фізичного геймпада.

Геймпади у Windows

У Windows наразі підтримуються лише контролери XBox 360. Щоб підключити контролер 360 до комп’ютера з Windows, переконайтеся, що його правильно налаштовано.

Геймпади на Android

Геймпади підтримуються у збірках Android і генерують ті самі дії введення, що й на інших платформах. Defold використовує налаштовані відповідності геймпадів і може автоматично зіставляти деякі контролери, що не мають відповідного запису.

Якщо контролер не розпізнано або його елементи керування працюють неправильно, перевірте його на пристрої Android і додайте або оновіть відповідність. Для діагностики див. Нерозпізнані геймпади і Необроблені дані геймпадів.