GUI

Defold надає спеціалізований редактор GUI та потужні можливості написання скриптів, призначені для побудови й реалізації інтерфейсів користувача.

Графічний інтерфейс користувача у Defold — це компонент (component), який ви створюєте, додаєте до ігрового об’єкта (game object) і розміщуєте в колекції (collection). Цей компонент має такі властивості:

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

Компоненти GUI відображаються незалежно від ігрового зображення. Тому вони не розміщуються в конкретному місці в редакторі колекцій і не мають у ньому візуального представлення. Однак компоненти GUI мають належати ігровому об’єкту, який має позицію в колекції. Змінення цієї позиції не впливає на GUI.

Створення компонента GUI

Компоненти GUI створюються з файлу прототипу сцени GUI (в інших рушіях такі файли також відомі як префаби (prefabs) або шаблони (blueprints)). Щоб створити новий компонент GUI, клацніть правою кнопкою миші потрібне місце у браузері Assets і виберіть New ▸ Gui. Введіть назву нового файлу GUI та натисніть Ok.

Defold автоматично відкриє файл у редакторі сцен GUI.

У панелі Outline перелічено весь вміст GUI: список вузлів і всі залежності (див. нижче).

У центральній області редагування показано GUI. Панель інструментів у правому верхньому куті області редагування містить інструменти Move, Rotate і Scale, а також засіб вибору компонування.

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

Властивості GUI

Якщо вибрати кореневий вузол “Gui” у панелі Outline, у панелі Properties з’являться властивості компонента GUI:

Script

Скрипт GUI, прив’язаний до цього компонента GUI.

Material

Матеріал, який використовується для рендерингу цього GUI. Зауважте, що через панель Outline до Gui також можна додати кілька матеріалів і призначити їх окремим вузлам.

Adjust Reference

Визначає, як обчислюється Adjust Mode кожного вузла:

• Per Node коригує кожен вузол відповідно до скоригованого розміру батьківського вузла або зміненого розміру екрана.
• Disable вимикає режим коригування вузлів. Усі вузли зберігатимуть заданий розмір.

Current Nodes

Кількість вузлів, які зараз використовуються в цьому GUI.

Max Nodes

Максимальна кількість вузлів для цього GUI.

Max Dynamic Textures

Максимальна кількість динамічних текстур, які відстежує цей компонент GUI; за замовчуванням — 128. До них належать текстури, створені за допомогою gui.new_texture(), і зовнішні текстури, призначені GUI за допомогою go.set(..., "textures", ...) або gui.set(msg.url(), "textures", ...). У проєктах, які замінюють багато зовнішніх текстур, може знадобитися збільшити це обмеження.

Керування під час виконання

Ви можете змінювати властивості GUI під час виконання з компонента-скрипту за допомогою go.get() і go.set():

Шрифти

Отримання або встановлення шрифту, який використовується в GUI.

go.property("mybigfont", resource.font("/assets/mybig.font"))

function init(self)
  -- get the font file currently assigned to the font with id 'default'
  print(go.get("#gui", "fonts", { key = "default" })) -- /builtins/fonts/default.font

  -- set the font with id 'default' to the font file assigned to the resource property 'mybigfont'
  go.set("#gui", "fonts", self.mybigfont, { key = "default" })

  -- get the new font file assigned to the font with id 'default'
  print(go.get("#gui", "fonts", { key = "default" })) -- /assets/mybig.font
end

Матеріали

Отримання або встановлення матеріалу, який використовується в GUI.

go.property("myeffect", resource.material("/assets/myeffect.material"))

function init(self)
  -- get the material file currently assigned to the material with id 'effect'
  print(go.get("#gui", "materials", { key = "effect" })) -- /effect.material

  -- set the material id 'effect' to the material file assigned to the resource property 'myeffect'
  go.set("#gui", "materials", self.myeffect, { key = "effect" })

  -- get the new material file assigned to the material with id 'effect'
  print(go.get("#gui", "materials", { key = "effect" })) -- /assets/myeffect.material
end

Текстури

Отримання або встановлення текстури (атласу), яка використовується в GUI.

go.property("mytheme", resource.atlas("/assets/mytheme.atlas"))

function init(self)
  -- get the texture file currently assigned to the texture with id 'theme'
  print(go.get("#gui", "textures", { key = "theme" })) -- /theme.atlas

  -- set the texture with id 'theme' to the texture file assigned to the resource property 'mytheme'
  go.set("#gui", "textures", self.mytheme, { key = "theme" })

  -- get the new texture file assigned to the texture with id 'theme'
  print(go.get("#gui", "textures", { key = "theme" })) -- /assets/mytheme.atlas
end

Залежності

Дерево ресурсів у грі на Defold статичне, тому всі залежності, потрібні для вузлів GUI, необхідно додати до компонента. Панель Outline групує всі залежності за типами в «папках»:

Щоб додати нову залежність, перетягніть її з панелі Asset в область редактора.

Також можна клацнути правою кнопкою миші кореневий вузол “Gui” у панелі Outline, а потім вибрати Add ▸ [type] у контекстному меню.

Крім того, ви можете клацнути правою кнопкою миші піктограму папки потрібного типу та вибрати Add ▸ [type].

Типи вузлів

Компонент GUI складається з набору вузлів. Вузли — це прості елементи. Їх можна трансформувати (переміщувати, масштабувати й повертати) та впорядковувати в батьківсько-дочірні ієрархії як у редакторі, так і під час виконання за допомогою скриптів. Існують такі типи вузлів:

Вузол Box

Прямокутний вузол з одним кольором, текстурою або покадровою анімацією. Докладніше див. у документації вузла Box.

Вузол Text

Відображає текст. Докладніше див. у документації вузла Text.

Вузол Pie

Круглий або еліптичний вузол, який можна частково заповнити або інвертувати. Докладніше див. у документації вузла Pie.

Вузол Template

Шаблони використовуються для створення екземплярів (instances) на основі інших файлів сцен GUI. Докладніше див. у документації вузла Template.

Вузол ParticleFX

Відтворює ефект частинок. Докладніше див. у документації вузла ParticleFX.

Щоб додати вузли, клацніть правою кнопкою миші папку Nodes, виберіть Add ▸, а потім Box, Text, Pie, Template або ParticleFx.

Також можна натиснути A і вибрати тип, який потрібно додати до GUI.

Властивості вузлів

Кожен вузол має великий набір властивостей, які керують його виглядом:

Id

Ідентифікатор вузла. Ця назва має бути унікальною в межах сцени GUI.

Position, Rotation і Scale

Визначають розташування, орієнтацію та розтягування вузла. Ви можете змінювати ці значення за допомогою інструментів Move, Rotate і Scale. Значення можна анімувати зі скрипту (докладніше).

Size (вузли Box, Text і Pie)

За замовчуванням розмір вузла визначається автоматично, але якщо встановити Size Mode у Manual, ви зможете змінювати це значення. Розмір визначає межі вузла та використовується під час вибору вузла за координатами введення. Це значення можна анімувати зі скрипту (докладніше).

Size Mode (вузли Box і Pie)

Якщо встановлено Automatic, редактор задаватиме розмір вузла. Якщо встановлено Manual, ви зможете задавати розмір самостійно.

Enabled

Якщо прапорець знято, вузол не відображається, не анімується та не може бути вибраний за допомогою gui.pick_node(). Використовуйте gui.set_enabled() і gui.is_enabled(), щоб програмно змінювати й перевіряти цю властивість.

Visible

Якщо прапорець знято, вузол не відображається, але його все ще можна анімувати й вибирати за допомогою gui.pick_node(). Використовуйте gui.set_visible() і gui.get_visible(), щоб програмно змінювати й перевіряти цю властивість.

Text (вузли Text)

Текст, який відображається у вузлі.

Line Break (вузли Text)

Увімкніть, щоб текст переносився відповідно до ширини вузла.

Font (вузли Text)

Шрифт, який використовується для рендерингу тексту.

Texture (вузли Box і Pie)

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

Material (вузли Box, Pie, Text і ParticleFX)

Матеріал, який використовується для малювання вузла. Можна вказати матеріал, доданий до розділу Materials у панелі Outline, або залишити поле порожнім, щоб використовувати матеріал за замовчуванням, призначений компоненту GUI.

Slice 9 (вузли Box)

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

Inner Radius (вузли Pie)

Внутрішній радіус вузла, заданий уздовж осі X. Докладніше див. у документації вузла Pie.

Outer Bounds (вузли Pie)

Керує поведінкою зовнішніх меж. Докладніше див. у документації вузла Pie.

Perimeter Vertices (вузли Pie)

Кількість сегментів, які використовуватимуться для побудови форми. Докладніше див. у документації вузла Pie.

Pie Fill Angle (вузли Pie)

Визначає, яку частину вузла Pie слід заповнити. Докладніше див. у документації вузла Pie.

Template (вузли Template)

Файл сцени GUI, який використовується як шаблон для вузла. Докладніше див. у документації вузла Template.

ParticleFX (вузли ParticleFX)

Ефект частинок, який використовується в цьому вузлі. Докладніше див. у документації вузла ParticleFX.

Color

Колір вузла. Якщо вузол має текстуру, колір забарвлює її. Колір можна анімувати зі скрипту (докладніше).

Alpha

Прозорість вузла. Значення альфа можна анімувати зі скрипту (докладніше).

Inherit Alpha

Увімкнення цього прапорця змушує вузол успадковувати значення альфа батьківського вузла. Значення альфа вузла тоді множиться на значення альфа батьківського вузла.

Leading (вузли Text)

Коефіцієнт масштабування міжрядкового інтервалу. Значення 0 прибирає міжрядковий інтервал. 1 (за замовчуванням) — звичайний міжрядковий інтервал.

Tracking (вузли Text)

Коефіцієнт масштабування міжлітерного інтервалу. За замовчуванням — 0.

Layer

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

Blend mode

Визначає, як графіка вузла змішується з графікою тла:

• Alpha змішує значення пікселів вузла й тла з урахуванням альфа. Це відповідає режиму змішування “Normal” у графічних редакторах.
• Add додає значення пікселів вузла до значень пікселів тла. Це відповідає режиму “Linear dodge” у деяких графічних редакторах.
• Multiply множить значення пікселів вузла на значення пікселів тла.
• Screen обернено множить значення пікселів вузла й тла. Це відповідає режиму змішування “Screen” у графічних редакторах.

Pivot

Задає опорну точку вузла. Її можна вважати «центральною точкою» вузла. Будь-який поворот, масштабування або змінення розміру відбуватимуться відносно цієї точки.

Можливі значення: Center, North, South, East, West, North West, North East, South West або South East.

Якщо змінити опорну точку вузла, вузол переміститься так, щоб нова опорна точка опинилася в позиції вузла. Для текстових вузлів Center задає вирівнювання тексту по центру, West — по лівому краю, а East — по правому краю.

X Anchor, Y Anchor

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

Доступні такі режими прив’язки:

• None (для X Anchor і Y Anchor) зберігає позицію вузла відносно центру батьківського вузла або сцени з урахуванням скоригованого розміру.
• Left або Right (X Anchor) масштабує горизонтальну позицію вузла, щоб зберігати ту саму відсоткову відстань від лівого та правого країв батьківського вузла або сцени.
• Top або Bottom (Y Anchor) масштабує вертикальну позицію вузла, щоб зберігати ту саму відсоткову відстань від верхнього та нижнього країв батьківського вузла або сцени.

Adjust Mode

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

Вузол, створений у сцені з типовою логічною роздільною здатністю в альбомній орієнтації:

Пристосування сцени до екрана в портретній орієнтації розтягує сцену. Обмежувальний прямокутник кожного вузла розтягується так само. Однак налаштування режиму коригування дає змогу зберегти співвідношення сторін вмісту вузла. Доступні такі режими:

• Fit масштабує вміст вузла відповідно до ширини або висоти розтягнутого обмежувального прямокутника — залежно від того, яка з них менша. Інакше кажучи, вміст уміщуватиметься всередині розтягнутого обмежувального прямокутника вузла.
• Zoom масштабує вміст вузла відповідно до ширини або висоти розтягнутого обмежувального прямокутника — залежно від того, яка з них більша. Інакше кажучи, вміст повністю покриватиме розтягнутий обмежувальний прямокутник вузла.
• Stretch розтягує вміст вузла так, щоб він заповнив розтягнутий обмежувальний прямокутник вузла.

Якщо властивість сцени GUI Adjust Reference має значення Disabled, це налаштування ігнорується.

Clipping Mode (вузли Box і Pie)

Задає режим обрізання вузла:

• None відображає вузол як зазвичай.
• Stencil використовує межі вузла для визначення трафаретної маски, яка обрізає дочірні вузли цього вузла.

Докладніше див. у посібнику з обрізання GUI.

Clipping Visible (вузли Box і Pie)

Увімкніть, щоб відображати вміст вузла в області трафарету. Докладніше див. у посібнику з обрізання GUI.

Clipping Inverted (вузли Box і Pie)

Інвертує трафаретну маску. Докладніше див. у посібнику з обрізання GUI.

Опорна точка, прив’язки та режим коригування

Поєднання властивостей Pivot, Anchors і Adjust Mode дає змогу дуже гнучко проєктувати GUI, але без конкретного прикладу може бути складно зрозуміти, як усе це працює. Розгляньмо макет GUI, створений для екрана 640x1136:

Інтерфейс створено зі значенням None для X і Y Anchors, а Adjust Mode кожного вузла залишено зі значенням за замовчуванням Fit. Опорну точку Pivot верхньої панелі встановлено в North, нижньої панелі — у South, а смуг у верхній панелі — у West. Решта вузлів мають опорну точку Center. Ось що станеться, якщо розширити вікно:

А що, як ми хочемо, щоб верхня й нижня панелі завжди мали ширину екрана? Можна змінити Adjust Mode сірих фонових панелей угорі та внизу на Stretch:

Так краще. Сірі фонові панелі тепер завжди розтягуватимуться на всю ширину вікна, але смуги у верхній панелі та два прямокутники внизу розташовані неправильно. Якщо ми хочемо, щоб смуги вгорі залишалися ліворуч, потрібно змінити X Anchor з None на Left:

Саме цього ми й хотіли для верхньої панелі. Опорні точки Pivot смуг у верхній панелі вже мали значення West, тому смуги розташовуватимуться належним чином: їхній лівий, або західний, край (Pivot) буде прив’язаний до лівого краю батьківської панелі (X Anchor).

Тепер, якщо встановити X Anchor у Left для лівого прямокутника, а X Anchor у Right для правого, отримаємо такий результат:

Це не зовсім очікуваний результат. Два прямокутники мали б залишатися так само близько до лівого й правого країв, як дві смуги у верхній панелі. Причина в тому, що опорну точку Pivot задано неправильно:

Обидва прямокутники мають опорну точку Pivot зі значенням Center. Це означає, що коли екран стає ширшим, центральна точка (опорна точка) прямокутників залишається на тій самій відносній відстані від країв. Для лівого прямокутника в початковому вікні 640x1136 ця відстань становила 17% від лівого краю:

Коли розмір екрана змінюється, центральна точка лівого прямокутника залишається на тій самій відстані — 17% від лівого краю:

Якщо змінити опорну точку Pivot з Center на West для лівого прямокутника та на East для правого, а потім перемістити прямокутники, ми отримаємо бажаний результат навіть після змінення розміру екрана:

Порядок малювання

Усі вузли відображаються в тому порядку, у якому вони перелічені в папці “Nodes”. Вузол угорі списку малюється першим і тому буде позаду всіх інших вузлів. Останній вузол у списку малюється останнім, тобто буде попереду всіх інших вузлів. Змінення значення Z вузла не керує порядком його малювання; однак якщо задати Z поза діапазоном рендерингу вашого скрипту рендерингу, вузол більше не відображатиметься на екрані. Ви можете перевизначити порядок вузлів за індексами за допомогою шарів (див. нижче).

Виберіть вузол і натисніть Alt + Up/Down, щоб перемістити його вгору або вниз і змінити його місце в порядку індексів.

Порядок малювання можна змінити зі скрипту:

local bean_node = gui.get_node("bean")
local shield_node = gui.get_node("shield")

if gui.get_index(shield_node) < gui.get_index(bean_node) then
  gui.move_above(shield_node, bean_node)
end

Батьківсько-дочірні ієрархії

Щоб зробити вузол дочірнім до іншого вузла, перетягніть його на вузол, який має стати батьківським. Дочірній вузол успадковує трансформацію (позицію, поворот і масштаб), застосовану до батьківського вузла, відносно опорної точки батьківського вузла.

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

Шари та виклики малювання

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

• Вузли мають бути одного типу.
• Вузли мають використовувати той самий атлас або джерело плиток.
• Вузли мають відображатися з тим самим режимом змішування.
• Вузли мають використовувати той самий шрифт.

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

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

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

Призначивши вузлам шари, можна впорядкувати їх інакше, щоб конвеєр рендерингу міг згрупувати вузли в меншу кількість викликів малювання. Спочатку додайте до сцени потрібні шари. Клацніть правою кнопкою миші піктограму папки “Layers” у панелі Outline та виберіть Add ▸ Layer. Виберіть новий шар і задайте йому властивість Name у панелі Properties.

Потім задайте властивість Layer кожного вузла відповідно до потрібного шару. Порядок малювання шарів має пріоритет над звичайним порядком вузлів за індексами, тому якщо призначити вузлам Box із графікою кнопок шар “graphics”, а текстовим вузлам кнопок — шар “text”, порядок малювання буде таким:

• Спочатку всі вузли шару “graphics”, згори вниз:

  1. “button-1”
  2. “button-2”
  3. “button-3”

• Потім усі вузли шару “text”, згори вниз:

  1. “button-text-1”
  2. “button-text-2”
  3. “button-text-3”

Тепер вузли можна згрупувати у два виклики малювання замість шести. Це суттєво підвищує продуктивність!

Зауважте, що дочірній вузол без заданого шару неявно успадковує налаштування шару батьківського вузла. Якщо шару для вузла не задано, він неявно додається до шару “null”, який малюється перед усіма іншими шарами.