Вузли і термінологія

Перш ніж продовжувати, слід зауважити, що термін Вузол потрібно використовувати обережно. Коли йдеться про візуальні вузли скриптів (або взагалі Вузли), у цьому тексті будуть матися на увазі маленькі поля, які ви з'єднуєте з лініями, і які є частиною графіка. А під Вузлами сцени, маються на увазі елементи, що складають Сцену і є частиною її дерева. Їх назви схожі, але функції різні. Тут під словом Вузол маються на увазі Вузли візуального скрипта, звісно якщо не вказано інше.

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

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

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

Порти та з'єднання

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

Порти

Вузли у Godot Visual Scripting мають порти. Це кінцеві точки, які з'являються зліва та справа від вузлів і які можна використовувати для підключення: Є два типи портів: Послідовність і Дані.

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

Порти даних містять типізовані значення. Типи можуть бути будь-якими регулярними типами Godot, такими як булеві (логічні), цілі числа, текст (строка), Vector3, масив, будь-який вузол об'єкта, або сцени, тощо. Порт даних у правій частині вузла вважається вихідним, тоді як, порт зліва - вхідний. Підключення їх дозволяє передавати інформацію до наступного вузла.

Не всі типи портів даних сумісні і можуть бути з'єднані. Зверніть особливу увагу на кольори та піктограми, оскільки кожен тип має різне представлення:

З'єднання

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

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

Така система може здатися дивною, але їй є пояснення. Порти даних підключаються по схемі 1:N (один вихідний порт може з'єднуватися з багатьма входами), а порти послідовності - N:1 (Багато послідовних виходів можна підключити до одного входу).

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

Для даних відкриється контекстне меню задавання/отримання/виклику:

Додавання вузлів

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

Доступ до вузлів сцени

One of the most common tasks is accessing Scene Tree Nodes (again, not to mistake with Visual Script Nodes). Dragging from the Scene Tree and dropping into the canvas will ask you to call a method (sometimes referred to as member function) on this node.

Хоча доступ до властивостей бажаний у більшості випадків (докладніше про це нижче), іноді виклик методів може бути корисним. Методи виконують конкретні дії над об'єктами. У наведеному вище випадку вказівник миші може бути перекручений до положення в локальних координатах до елемента управління. Ще один поширений випадок використання - це черга вузла для видалення, що робиться методом queue_free.

Майте на увазі що це працює лише в тому випадку, коли редагована сцена, містить ваш Visual Script в одному з вузлів! В іншому випадку буде показано попередження.

Доступ до властивостей вузла сцени

Це найпоширеніший спосіб редагування Вузлів Сцени у візуальних скриптах. Виберіть Вузол Сцени з Дерева сцени, перейдіть до Інспектора, знайдіть Ім'я властивості, яку ви хочете редагувати (підказка, а не значення!) І перетягніть його на полотно:

В результаті це значення можна змінити з вашого скрипту, записавши в Порт Даних.

Якщо замість цього потрібне зчитування цього значення, перетягніть вузол ще раз, але утримуйте Ctrl`(або :kbd:`Cmd на macOS). Це створить геттер:

У цьому випадку значення можна прочитати з Порту Даних.

Змінні

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

Щоб додати змінну, натисніть кнопку "+" у розділі Змінні на панелі "Члени". Двічі клацніть нову змінну, щоб перейменувати її:

Клацніть правою кнопкою миші по змінній, щоб налаштувати її властивості:

Як видно вище, тип і початкове значення змінної можуть бути змінені, а також деякі підказки (hints) властивості. Опція "Export" ("Експорт") робить змінну видимою в Інспекторі під час вибору вузла. Це також робить її доступною для інших скриптів через метод, описаний у попередньому кроці.

Щоб використовувати змінну в скрипті, просто перетягніть її на полотно, щоб створити сеттер:

Так само утримуйте Ctrl (або Cmd на macOS), щоб отримати геттер:

Сигнали

Також можна створити власні сигнали в скрипті та використовувати їх. Для цього виконайте ті самі кроки, які ви робили для змінних на попередньому кроці, але використовуйте Сигнали:

Сигнал також можна редагувати через меню правою кнопкою миші, щоб налаштувати його аргументи:

Створений вами сигнал з’явиться в Інспекторі разом із вбудованими сигналами вузла. Це дозволяє підключити його до іншого скрипту в іншому Вузлі сцени:

Нарешті, щоб випромінювати сигнал, перетягніть його на полотно:

Пам'ятайте, що випромінювання сигналу є послідовною операцією, тому він повинен надходити з порту послідовності.

Додавання додаткових вузлів

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

Натискання Ctrl + F (або Cmd + F на macOS) дозволяє відкрити список для пошуку.

Будь-якого з них можна перетягнути на сцену. На відміну від вузлів (наприклад, перетягування властивості з Інспектора встановлює контекст для редагування вузла автоматично), вони додаються без будь-якої "контекстуальної" інформації, тому це потрібно робити вручну.

Пам'ятайте, що ви можете перевірити посилання класу на те, що робить кожен вузол, оскільки вони там задокументовані. Далі короткий огляд типів вузлів:

Константи

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

Перший з них - "Constant", який дозволяє вибрати будь-яке значення будь-якого типу як постійне, від цілого числа (42) до текстового ("Привіт!"). Взагалі, цей вузол використовується не часто, через дефолтне введення значень в портах даних, але добре знати, що він існує.

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

Третій - "MathConstant", забезпечує типові математичні константи, такі як PI, E, тощо.

Дані

Вузли даних мають справу з усіляким доступом до інформації. Будь-яка інформація в Godot доступна через ці вузли, тому вони є одними з найважливіших для використання та досить різноманітними.

Тут існує безліч типів цікавих вузлів, далі йде спроба їх короткого опису:

Дія

Вузли дій є життєво важливими при роботі з введенням з пристрою. Детальніше про дії ви можете прочитати в (@TODO ACTION TUTE LINK). Нижче приклад керування переміщенням праворуч коли дія "move_right" натиснута.

Синглтон двигуна

Engine singleton - це глобальний інтерфейс (це означає, що до нього можна отримати доступ без посилання; на відміну від вузлів сцени, такі інтерфейси завжди доступні). Ці інтерфейси мають кілька цілей, але загалом вони корисні для доступу низького рівня, або доступу до ОС.

Пам'ятайте, що перетягування з'єднання на порожній простір допоможе вам викликати функції, або встановити/отримати ці властивості:

Локальні змінні

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

Як вказано вище доступні два вузли: Простий гетер та послідовний гетер (налаштування вимагає послідовного порту).

Вузол сцени

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

Цей об'єкт

У деяких рідкісних випадках може знадобитися передача цього Вузла Сцени в якості аргумента. Він може використовуватися для виклику функцій та встановлення/отримання властивостей, або перетягування вузлів (або подій самого вузла, у якого є скрипт) із Дерева сцени до полотна.

Дерево Сцен

Цей вузол схожий на вузол Singleton, оскільки він посилається на SceneTree (Дерево Сцени), яке містить активну сцену. Однак SceneTree працює лише тоді, коли вузол сидить у сцені та активний, інакше при зверненні до нього повернеться помилка.

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

Попередньо завантажити

Preload (Попереднє завантаження) виконує ту ж функцію, що і preload() у GDScript. Він підтримує цей ресурс завантаженим і готовим до використання. Замість того, щоб вставляти екземпляр вузла, простіше перетягнути потрібний ресурс з панелі Файлова система на полотно.

Шлях до ресурсу

Resource Path (Шлях до ресурсу) є простим помічником для отримання рядка зі шляхом до ресурсу, який ви можете вибрати. Це корисно у функціях, які завантажують речі з диска.

Коментар

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

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

Вузли управління потоком дозволяють виконанню приймати різні розгалуження, залежно від заданої умови.

Умова

Condition (Умова) це простий вузол, який перевіряє логічний (булевий) порт. Якщо true він передасть послідовність через "true" ("істинний") порт. Якщо false, через другий. Після переходу по будь-якому з них він переходить через порт "done" ("зроблено"). Добре залишати порти послідовності відключеними, якщо вони не всі використовуються.

ітератор

Деякі типи даних у Godot (тобто масиви, словники) є ітерованими. Це означає, що частина коду може повторно виконуватися для кожного елемента всередині такого типу.

Вузол Iterator (Ітератор) перебирає всі елементи, і кожен елемент передає через порт послідовностей "each" ("кожен"), роблячи його доступним у порту даних "elem" ("елемент").

По завершенні він проходить через порт послідовності "exit" ("вихід").

Повернутися

Деякі функції можуть повертати значення. Зазвичай Godot використовує для цього вузол Return (Повернення). Цей вузол змушує функцію завершуватися.

Послідовність

Вузол Sequence (Послідовність) здебільшого корисний для організації вашого графіка. Він викликає порти послідовності по порядку.

TypeCast

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

Також можливий переведення в скрипт, що дозволить отримати всі властивості та функції скрипту:

Перемкнутися

Вузол Switch (Перемикач) схожий на вузол Condition (Умова), але він перевіряє багато значень одночасно.

Доки

Це примітивніша форма ітерації. Порт послідовності "repeat" буде викликатися до тих пір, поки не буде виконана умова в порту даних "cond".

Функції

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

Built-In (Вбудовані)

Є список вбудованих помічників. Список майже ідентичний списку з GDScript. Більшість з них є математичними функціями, але деякі можуть бути корисними помічниками. Обов'язково подивіться список при нагоді.

За типом

Це методи, доступні для основних типів. Наприклад, якщо ви хочете крапковий продукт, ви можете шукати "dot" ("крапка") замість категорії Vector3. У більшості випадків використовуйте пошуковий рядок в списку вузлів, це буде скоріше.

Виклик

Call (Виклик) це основний вузол виклику. Він рідко використовується безпосередньо, але його можна перетягнути на порожній простір на вже налаштований вузол.

Конструктори

Конструктори (Constructor) це всі функції, необхідні для створення основних типів даних Godot. Наприклад, якщо вам потрібно створити Vector3 з 3 дійсних чисел, потрібно використовувати конструктор.

Деструктор

Це протилежність Конструктора, дозволяє розділити будь-який базовий тип (наприклад, Vector3) на його піделементи.

Emit Signal (Випромінювання сигналу)

Випромінює сигнали з будь-якого об'єкта. Але просте перетягування сигналу на полотно зручніше.

Get/Set (Отримувати/Задавати)

Спільний вузол Getter/Setter. Знову ж таки, зручніше перетягування властивостей з Інспектора, оскільки тоді вони здаються належним чином налаштованими.

Очікування

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

Результат

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

Yield Signal

Те саме, що і Yield, але буде чекати, поки подається заданий сигнал.

Індекс

Загальний оператор індексації, не часто використовується, але добре, що він існує (на всякий випадок).

Оператори

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

Expression Node (Вузол виразу)

Серед операторів вузол Expression є найпотужнішим. Якщо його правильно використовувати, він дозволяє надзвичайно спростити візуальні скрипти, які важкі для математики, чи логіки. Введіть в нього будь-який вираз, і він буде виконуватися в режимі реального часу.

Вузли виразів можуть:

• Виконувати математичні та логічні вирази на основі введень користувача (наприклад: "a* 5+b", де a і b - введення користувача):

• Мати доступ до локальних змінних, чи властивостей:

• Використовувати більшість наявних вбудованих функцій, доступних для GDScript, таких як sin(), cos(), print(), а також конструктори, такі як Vector3(x, y, z), Rect2(...), тощо:

• Викликати функції API:

• Використовувати режим послідовностей, який має більше сенсу у випадку дотримання порядку обробки: