Налагодження ігрової логіки

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

Налагодження за допомогою виведення та візуалізації

Найпростіший спосіб налагоджувати гру в Defold — налагодження за допомогою виведення. Використовуйте виклики print() або pprint(), щоб спостерігати за змінними або відстежувати хід виконання. Якщо ігровий об’єкт (game object) без скрипту поводиться дивно, до нього можна додати скрипт лише для налагодження. Усі функції виведення надсилають текст на панель Console у редакторі та до журналу гри.

Крім виведення тексту, рушій також може малювати на екрані налагоджувальний текст і прямі лінії. Для цього надсилайте повідомлення до сокета @render:

-- Draw value of "my_val" with debug text on the screen
msg.post("@render:", "draw_text", { text = "My value: " .. my_val, position = vmath.vector3(200, 200, 0) })

-- Draw colored text on the screen
local color_green = vmath.vector4(0, 1, 0, 1)
msg.post("@render:", "draw_debug_text", { text = "Custom color", position = vmath.vector3(200, 180, 0), color = color_green })

-- Draw debug line between player and enemy on the screen
local start_p = go.get_position("player")
local end_p = go.get_position("enemy")
local color_red = vmath.vector4(1, 0, 0, 1)
msg.post("@render:", "draw_line", { start_point = start_p, end_point = end_p, color = color_red })

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

• "draw_line" додає дані, які відображаються за допомогою функції render.draw_debug3d() у скрипті рендерингу.
• "draw_text" відображається шрифтом /builtins/fonts/debug/always_on_top.font, який використовує матеріал /builtins/fonts/debug/always_on_top_font.material.
• "draw_debug_text" працює так само, як "draw_text", але текст відображається заданим кольором.

Зауважте, що ці дані, найімовірніше, потрібно оновлювати кожного кадру, тому доречно надсилати повідомлення у функції update().

Запуск налагоджувача

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

Щоб запустити налагоджувач, виберіть Debug ▸ Start/Attach. Ця команда запускає гру з під’єднаним налагоджувачем або під’єднує його до вже запущеної гри. Під час запуску для налагодження редактор встановлює ввімкнені точки зупину до виконання стартових скриптів, тож точку зупину в init() можна задати ще до запуску.

Щоб під’єднатися до пристрою, виберіть його в Project ▸ Targets, а потім виберіть Debug ▸ Start/Attach. Після під’єднання виконання призупиняється на наступному рядку Lua. Редактор автоматично налаштовує з’єднання налагоджувача для підтримуваних локальних і віддалених цілей. Вимоги до з’єднання див. у розділі Віддалені цілі, або дізнайтеся, як під’єднати зовнішній налагоджувач.

Щойно налагоджувач під’єднано, ви можете керувати виконанням гри за допомогою кнопок налагоджувача в консолі або меню Debug:

Break

Призупиніть виконання Lua на наступному рядку вихідного коду. Тепер ви можете інспектувати стан гри, виконувати її покроково або продовжити виконання до наступної точки зупину. Поточну точку виконання позначено в редакторі коду:

Continue

Продовжіть виконання гри. Код гри виконуватиметься, доки ви не натиснете кнопку паузи або виконання не дійде до встановленої вами точки зупину. Якщо виконання призупиниться на встановленій точці зупину, поточну точку виконання буде позначено в редакторі коду поверх маркера точки зупину:

Stop

Зупиніть налагоджувач. Натискання цієї кнопки негайно зупинить налагоджувач, від’єднає його від гри та завершить запущену гру.

Step Over

Виконайте один крок програми. Якщо цей крок передбачає виклик іншої функції Lua, виконання не перейде всередину функції, а продовжиться й зупиниться на наступному рядку після виклику функції. У цьому прикладі, якщо користувач натисне «step over», налагоджувач виконає код і зупиниться на інструкції end під рядком із викликом функції nextspawn():

Step Into

Виконайте один крок програми. Якщо цей крок передбачає виклик іншої функції Lua, виконання перейде всередину функції. Виклик функції додає запис до стека викликів. Ви можете натиснути будь-який запис у списку стека викликів, щоб переглянути точку входу та значення всіх змінних у відповідному замиканні. Тут користувач перейшов усередину функції nextspawn():

Step Out

Продовжіть виконання до повернення з поточної функції. Якщо ви перейшли всередину функції під час покрокового виконання, натискання кнопки «step out» продовжить виконання до повернення з цієї функції.

Встановлення й видалення точок зупину

Ви можете встановити довільну кількість точок зупину у своєму коді Lua. Коли гра працює з під’єднаним налагоджувачем, вона призупинить виконання на наступній точці зупину, якої досягне, і чекатиме на ваші подальші дії.

Щоб встановити або видалити точку зупину, натисніть у стовпці безпосередньо праворуч від номерів рядків у редакторі коду. Також можна вибрати в меню Edit ▸ Toggle Breakpoint.

Вимкнення й увімкнення точок зупину

Точки зупину можна тимчасово вимикати без видалення. Вимкнені точки ігноруються під час виконання, але їх можна будь-коли ввімкнути знову. Натисніть точку зупину правою кнопкою миші на полі редактора коду, а потім змініть стан прапорця Enabled. Вимкнені точки зупину відображаються порожніми всередині, що вказує на їхній неактивний стан.

Встановлення умовних точок зупину

Для точки зупину можна налаштувати умову, яка має бути істинною, щоб точка спрацювала. Умова може звертатися до локальних змінних, доступних на цьому рядку під час виконання коду.

Щоб змінити умову точки зупину, натисніть правою кнопкою миші у стовпці безпосередньо праворуч від номерів рядків у редакторі коду або виберіть у меню Edit ▸ Edit Breakpoint.

Обчислення виразів Lua

Коли гру призупинено, виберіть кадр у Call Stack, введіть вираз або інструкцію Lua внизу консолі й натисніть Enter. Обчислення використовує локальні змінні, upvalue та глобальні змінні вибраного кадру. Результати-таблиці містять їхній вкладений вміст.

Значення також можна змінювати через присвоєння, наприклад self.score = 100 у кадрі, де доступний self. Обчислюваний код впливає на стан гри так само, як код, який виконує сама гра.

Інспектування змінних

Виберіть кадр у Call Stack, щоб переглянути його локальні змінні й upvalue на панелі Variables. Розгорніть _G, щоб переглянути глобальні змінні, або таблиці чи self, щоб переглянути їхні поля. Під час крокування, перемикання кадрів або оновлення після обчислення редактор зберігає розгорнуті шляхи, вибір і позицію прокручування, отримуючи актуальні значення.

Від’єднання налагоджувача

Виберіть Debug ▸ Detach Debugger, щоб від’єднати налагоджувач від гри. Гра негайно продовжить виконання. Використовуйте Debug ▸ Start/Attach, щоб під’єднатися знову без перезапуску гри.

Нативні з’єднання DAP

Рушій надає нативний сервер Debug Adapter Protocol (DAP) через TCP. Для зовнішнього клієнта DAP запустіть прослуховувач у нативному налагоджувальному рушії Defold або рушії без графічного інтерфейсу, а потім під’єднайте клієнт до адреси й порту рушія. Редактор автоматично налаштовує прослуховувач, коли ви використовуєте Debug ▸ Start/Attach.

Поточний редактор не може під’єднатися до старіших рушіїв, які підтримують лише MobDebug. У поточних версіях виклик require "builtins.scripts.mobdebug" не потрібен і недоступний.

Запуск прослуховувача

Спочатку зберіть проєкт. Із каталогу проєкту, що містить build/default/game.projectc, запустіть нативний налагоджувальний рушій із такими перевизначеннями конфігурації під час запуску:

dmengine --config=debugger.enabled=1 \
  --config=debugger.port=8172 --config=debugger.wait=1

Під’єднайте клієнт DAP до 127.0.0.1:8172. Рушій чекає, доки клієнт налаштує точки зупину, перш ніж запускати стартові скрипти.

Ці значення також можна додати до розділу Debugger у game.project. Редактор налаштовує прослуховувач автоматично для Debug ▸ Start/Attach, тож ручне налаштування потрібне лише тоді, коли ви запускаєте його самостійно.

Журнал рушія повідомляє вибрані адресу й порт. За debugger.wait=0 гра запускається одразу, а під’єднатися можна пізніше. За debugger.wait=1 рушій чекає, доки клієнт завершить налаштування сеансу, зокрема точок зупину. Для локальних запусків налагодження редактор автоматично вибирає доступний порт.

Від’єднання клієнта відновлює виконання й залишає прослуховувач доступним для нового під’єднання. Від’єднання під час очікування стартового налаштування також звільняє рушій. Якщо прослуховувач не вдається запустити, рушій записує помилку в журнал і продовжує запуск; можна повторити спробу з Lua за допомогою debugger.start(0), щоб вибрати доступний порт.

Увімкнення прослуховувача під час виконання

Щоб увімкнути прослуховувач зі скрипту без перезапуску гри:

if debugger then
    local port = debugger.start(0)
    print("DAP listener port:", port)
end

debugger.start([port [, address]]) одразу повертає порт прослуховування. Функція не чекає клієнта й не призупиняє гру. Якщо аргументи пропущено, використовуються debugger.port і debugger.address; значення 0 вибирає доступний порт. Повторні виклики повертають порт наявного прослуховувача й не змінюють його адресу або порт. Модуль debugger надають нативні налагоджувальні рушії та рушії без графічного інтерфейсу.

Порт має бути цілим числом від 0 до 65535. Передайте nil як перший аргумент, щоб перевизначити лише адресу. Некоректні аргументи або неможливість прив’язати прослуховувач спричиняють помилку Lua.

Віддалені цілі

Для прямого з’єднання з іншого комп’ютера прив’яжіть прослуховувач до інтерфейсу IPv4 пристрою або до 0.0.0.0 (усі інтерфейси IPv4). Наприклад, використовуйте debugger.start(8172, "0.0.0.0") або додайте --config=debugger.address=0.0.0.0 до наведеної вище команди запуску. Під’єднайте клієнт до фактичної IP-адреси пристрою й дозвольте доступ TCP до порту прослуховування. 0.0.0.0 — адреса прив’язки, а не адреса для введення в клієнті.

Редактор Defold автоматично запитує таку віддалену прив’язку й використовує порт 8172 + project.instance_index для віддалених цілей. Він не може виявити динамічно вибраний віддалений порт. Якщо ви вже запустили віддалений прослуховувач на localhost або іншому порту, перезапустіть рушій перед під’єднанням із редактора.

Налагоджувач може виконувати Lua й не має автентифікації. Вмикайте віддалений доступ лише в довіреній мережі розробки.

Зовнішні клієнти

Використовуйте клієнт, який підтримує пряме під’єднання до сервера DAP через TCP. Налаштуйте зіставлення вихідного коду з папкою, що містить game.project (аргумент під’єднання DAP localRoot). Спочатку запустіть прослуховувач рушія, а потім під’єднайте клієнт.

VS Code

Установіть розширення Lua Debug (actboy168.lua-debug), відкрийте папку з game.project у VS Code і додайте таку конфігурацію до .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Defold Lua",
      "type": "lua",
      "request": "attach",
      "address": "127.0.0.1:8172",
      "debugServer": 8172,
      "localRoot": "${workspaceFolder}",
      "stopOnEntry": false
    }
  ]
}

Якщо VS Code відкриває файл .script, .gui_script або .render_script як звичайний текст, перед установленням точок зупину виберіть Lua в індикаторі мови на панелі стану.

Установіть точку зупину, наприклад у функції init() скрипту. Запустіть рушій за допомогою наведеної вище команди, а потім виберіть Attach to Defold Lua на панелі Run and Debug у VS Code. За debugger.wait=1 рушій запускає стартові скрипти після того, як клієнт встановить точки зупину. Задайте stopOnEntry значення true, якщо також хочете призупиняти виконання на наступному рядку Lua після під’єднання.

Параметр VS Code debugServer під’єднується безпосередньо до локального прослуховувача TCP рушія. Поле address потрібне конфігурації під’єднання розширення Lua Debug. Якщо змінюєте порт прослуховувача, оновіть обидва поля. localRoot має вказувати на папку проєкту, щоб клієнт міг зіставляти назви вихідних файлів Lua в рушії з вашими файлами.

Для віддаленого рушія перенаправте його порт DAP на localhost і вкажіть перенаправлений порт в обох полях або використовуйте клієнт DAP, який під’єднується безпосередньо до віддаленого вузла.

Вкладка Breakpoints

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

Керування окремими точками зупину

Для роботи з окремими точками зупину:

• Натисніть червону піктограму кошика, щоб видалити точку зупину
• Двічі натисніть рядок (поза областю умови), щоб перейти до відповідного рядка коду в Code View
• Двічі натисніть комірку умови або натисніть піктограму пера, щоб змінити умовну точку зупину
• Наведіть вказівник на комірку умови та натисніть кнопку очищення X, щоб видалити умову

Групові операції

Виберіть кілька точок зупину за допомогою Ctrl/Cmd+click або Shift+click, а потім натисніть правою кнопкою миші, щоб виконати групові дії. Ви можете одночасно змінювати умови кількох точок зупину, перемикати їхній активний стан або повністю видаляти їх.

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

Бібліотека налагодження Lua

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

Перелік перевірок для налагодження

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

1. Перевірте виведення консолі та переконайтеся, що немає помилок під час виконання.

2. Додайте виклики print до коду, щоб переконатися, що він справді виконується.

3. Якщо код не виконується, перевірте, чи зроблено в редакторі всі налаштування, потрібні для його виконання. Чи додано скрипт до правильного ігрового об’єкта? Чи отримав скрипт фокус введення? Чи правильно налаштовано тригери введення? Чи додано код шейдера до матеріалу? Тощо.

4. Якщо ваш код залежить від значень змінних (наприклад, в умовній конструкції if), виведіть ці значення за допомогою print там, де вони використовуються або перевіряються, або інспектуйте їх за допомогою налагоджувача.

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

1. Визначте, яка половина коду (або менша частина) має містити помилку.
2. Знову визначте, яка половина цієї половини має містити помилку.
3. Продовжуйте звужувати область коду, що має спричиняти помилку, доки не знайдете її.

Вдалого полювання!

Налагодження проблем із фізикою

Якщо виникли проблеми з фізикою й колізії працюють не так, як очікувалося, рекомендується ввімкнути налагодження фізики. Установіть прапорець Debug у розділі Physics файлу game.project:

Коли цей прапорець установлено, Defold малюватиме всі форми колізій і точки контакту колізій: