Геймпади

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

• Лівий і правий стіки (напрямок і натискання)
• Ліва та права групи цифрових кнопок. Права група зазвичай відповідає кнопкам «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

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

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

Якщо вам потрібно створити новий файл налаштувань геймпадів, у нас є простий інструмент, який у цьому допоможе:

Натисніть, щоб завантажити 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 і генерують ті самі події введення, що й на інших платформах. Підтримка геймпадів ґрунтується на системі введення Android для подій клавіш і руху. Події введення Android перетворюються на події геймпадів Defold за допомогою того самого файлу gamepad, що описаний вище.

Додаючи додаткові прив’язки геймпадів в Android, ви можете використовувати наведені нижче таблиці відповідностей, щоб перетворювати події введення Android на значення файлу gamepad:

(Визначення KeyEvent в Android)

(Визначення MotionEvent в Android)

Використовуйте цю таблицю відповідностей разом із застосунком для тестування геймпадів із Google Play Store, щоб визначити, якій події клавіші відповідає кожна кнопка вашого геймпада.