Введення

Рушій перехоплює всі дані введення користувача й передає їх як дії компонентам-скриптам (script components) і компонентам зі скриптами GUI в ігрових об’єктах (game objects), які отримали фокус введення та реалізують функцію on_input(). Цей посібник пояснює, як налаштувати прив’язки для перехоплення введення та написати код, що на нього реагує.

Система введення спирається на набір простих і потужних понять, завдяки яким ви можете керувати введенням відповідно до потреб своєї гри.

Пристрої

Пристрої введення, вбудовані у ваш комп’ютер чи мобільний пристрій або під’єднані до нього, передають необроблені дані введення системного рівня до середовища виконання Defold. Підтримуються такі типи пристроїв:

1. Клавіатура (натискання окремих клавіш і введення тексту)
2. Миша (позиція, натискання кнопок і дії коліщатка миші)
3. Одиночні та множинні дотики (на пристроях iOS і Android, а також у HTML5 на мобільних пристроях)
4. Геймпади (які підтримує операційна система та для яких задано відповідності у файлі gamepads)

Прив’язки введення

Перш ніж введення буде надіслано скрипту, необроблені дані з пристрою перетворюються на змістовні дії за допомогою таблиці прив’язок введення.

Дії

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

Слухачі введення

Будь-який компонент-скрипт або скрипт GUI може отримувати дії введення, отримавши фокус введення. Одночасно можуть бути активними кілька слухачів.

Стек введення

Список слухачів введення, у якому перший отримувач фокуса розташований унизу стека, а останній — угорі.

Поглинання введення

Скрипт може поглинути отримане введення, щоб слухачі нижче у стеку його не отримали.

Налаштування прив’язок введення

Прив’язки введення — це спільна для всього проєкту таблиця, у якій ви задаєте, як введення з пристроїв перетворюється на іменовані дії, перш ніж їх буде передано компонентам-скриптам і скриптам GUI. Щоб створити новий файл прив’язок введення, клацніть правою кнопкою миші потрібне місце на панелі Assets і виберіть New... ▸ Input Binding. Щоб рушій використовував новий файл, змініть значення Game Binding у game.project.

Стандартний файл прив’язок введення автоматично створюється в усіх шаблонах нових проєктів, тому зазвичай створювати новий файл прив’язок не потрібно. Стандартний файл має назву game.input_binding і розташований у папці input у корені проєкту. Двічі клацніть файл, щоб відкрити його в редакторі:

Щоб створити нову прив’язку, натисніть кнопку + унизу розділу відповідного типу тригерів. Кожен запис має два поля:

Input

Необроблене введення, яке потрібно відстежувати; його вибирають зі списку доступних варіантів із прокручуванням.

Action

Ім’я, яке отримують дії введення під час створення й передавання вашим скриптам. Одне ім’я дії можна призначити кільком джерелам введення. Наприклад, можна прив’язати клавішу Space і кнопку A геймпада до дії jump. Зауважте, що через відому помилку введення дотиками, на жаль, не може мати ті самі імена дій, що й інші джерела введення.

Типи тригерів

Ви можете створювати п’ять типів тригерів для різних пристроїв:

Тригери клавіш (Key Triggers)

Введення окремими клавішами клавіатури. Кожна клавіша окремо зіставляється з відповідною дією. Докладніше читайте в посібнику з введення клавішами й тексту.

Текстові тригери (Text Triggers)

Текстові тригери призначені для зчитування довільного тексту, який вводить користувач. Докладніше читайте в посібнику з введення клавішами й тексту

Тригери миші (Mouse Triggers)

Введення з кнопок миші й коліщаток прокручування. Докладніше читайте в посібнику з введення мишею та дотиками.

Тригери дотиків (Touch Triggers)

Тригери одиночних і множинних дотиків доступні на пристроях iOS і Android у нативних застосунках і пакетах HTML5. Докладніше читайте в посібнику з введення мишею та дотиками.

Тригери геймпада (Gamepad Triggers)

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

Введення з акселерометра

Окрім п’яти наведених вище типів тригерів, Defold також підтримує введення з акселерометра в нативних застосунках Android та iOS. Установіть прапорець Use Accelerometer у розділі Input вашого файлу game.project.

function on_input(self, action_id, action)
    if action.acc_x and action.acc_y and action.acc_z then
        -- react to accelerometer data
    end
end

Фокус введення

Щоб компонент-скрипт або скрипт GUI отримував дії введення, надішліть повідомлення acquire_input_focus ігровому об’єкту, що містить цей компонент:

-- tell the current game object (".") to acquire input focus
msg.post(".", "acquire_input_focus")

Це повідомлення вказує рушію додати до стека введення компоненти ігрового об’єкта, здатні отримувати введення: компоненти-скрипти, компоненти GUI та проксі колекцій (collection proxy). Компоненти ігрового об’єкта розміщуються на вершині стека введення; останній доданий компонент буде на самій вершині. Зауважте: якщо ігровий об’єкт містить кілька компонентів, здатних отримувати введення, до стека буде додано їх усі:

Якщо ігровий об’єкт, що вже отримав фокус введення, отримує його знову, його компонент або компоненти переміщуються на вершину стека.

Передавання введення та on_input()

Дії введення передаються відповідно до стека введення, згори донизу.

Для кожного компонента у стеку, який містить функцію on_input(), ця функція викликається один раз для кожної дії введення протягом кадру з такими аргументами:

self

Поточний екземпляр (instance) скрипту.

action_id

Хешоване ім’я дії, задане у прив’язках введення.

action

Таблиця з корисними даними про дію, як-от значення введення, його розташування (абсолютні позиції та їхні зміни), чи було натиснуто кнопку (pressed) тощо. Докладніше про доступні поля дії див. у on_input().

function on_input(self, action_id, action)
  if action_id == hash("left") and action.pressed then
    -- move left
    local pos = go.get_position()
    pos.x = pos.x - 100
    go.set_position(pos)
  elseif action_id == hash("right") and action.pressed then
    -- move right
    local pos = go.get_position()
    pos.x = pos.x + 100
    go.set_position(pos)
  end
end

Фокус введення й компоненти проксі колекцій

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

Звільнення фокуса введення

Щоб припинити отримувати дії введення, надішліть ігровому об’єкту повідомлення release_input_focus. Це повідомлення вилучить усі компоненти ігрового об’єкта зі стека введення:

-- tell the current game object (".") to release input focus.
msg.post(".", "release_input_focus")

Поглинання введення

Функція on_input() компонента може безпосередньо керувати тим, чи слід передавати дії далі вниз стеком:

• Якщо on_input() повертає false або оператор повернення пропущено (це означає повернення nil, яке в Lua вважається хибним значенням), дії введення передаватимуться наступному компоненту у стеку введення.
• Якщо on_input() повертає true, введення поглинається. Жоден компонент нижче у стеку введення його не отримає. Зауважте, що це стосується всіх стеків введення. Компонент у стеку світу, завантаженого через проксі, може поглинути введення, через що компоненти в головному стеку його не отримають:

Є багато ситуацій, у яких поглинання введення дає простий і потужний спосіб перемикати введення між різними частинами гри. Наприклад, якщо вам потрібне спливне меню, яке тимчасово буде єдиною частиною гри, що отримує введення:

Меню паузи спочатку приховане (вимкнене), а коли гравець торкається елемента PAUSE на HUD, воно вмикається:

function on_input(self, action_id, action)
    if action_id == hash("mouse_press") and action.pressed then
        -- Did the player press PAUSE?
        local pausenode = gui.get_node("pause")
        if gui.pick_node(pausenode, action.x, action.y) then
            -- Tell the pause menu to take over.
            msg.post("pause_menu", "show")
        end
    end
end

GUI меню паузи отримує фокус введення й поглинає введення, блокуючи будь-яке введення, що не стосується спливного меню:

function on_message(self, message_id, message, sender)
  if message_id == hash("show") then
    -- Show the pause menu.
    local node = gui.get_node("pause_menu")
    gui.set_enabled(node, true)

    -- Acquire input.
    msg.post(".", "acquire_input_focus")
  end
end

function on_input(self, action_id, action)
  if action_id == hash("mouse_press") and action.pressed then

    -- do things...

    local resumenode = gui.get_node("resume")
    if gui.pick_node(resumenode, action.x, action.y) then
        -- Hide the pause menu
        local node = gui.get_node("pause_menu")
        gui.set_enabled(node, false)

        -- Release input.
        msg.post(".", "release_input_focus")
    end
  end

  -- Consume all input. Anything below us on the input stack
  -- will never see input until we release input focus.
  return true
end