diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/about/complying-with-licenses.md b/i18n/ru/docusaurus-plugin-content-docs/current/about/complying-with-licenses.md new file mode 100644 index 0000000..6a8b6a5 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/about/complying-with-licenses.md @@ -0,0 +1,104 @@ +--- +sidebar_position: 5 +toc_max_heading_level: 4 +--- + +# Соблюдение лицензий + +## Что такое лицензии? + +Orchestrator создается и распространяется под лицензией Apache License, версия 2.0. +Проект не имеет единственного владельца, так как каждый участник, который вносит код в проект, делает это под той же лицензией и сохраняет право собственности на свои вклад. + +Лицензия является юридическим требованием для вас (или вашей компании) использовать и распространять программное обеспечение (и производные работы, включая игры, сделанные с его использованием). +Ваша игра или проект могут иметь другую лицензию, но они все равно должны соответствовать исходной лицензии. + +:::tip +На экране с указанием авторов вашего проекта не забудьте включить уведомления третьих сторон о ресурсах, которые вы используете, таких как текстуры, модели, звуки, музыка и шрифты. +Особенно часто бесплатные ресурсы сопровождаются лицензиями, требующими указания авторства. +Тщательно проверьте их лицензии перед использованием в публичных проектах. +::: + +### Требования {#requirements} + +Для производных работ, которые включают Orchestrator, но не изменяют его исходный код, включите следующее: + +```text + Эта игра использует Orchestrator, который доступен под следующей лицензией: + + Copyright (c) 2023-настоящее время Crater Crash Studios, LLC и его участники. + + Лицензировано по Apache License, Version 2.0 (далее "Лицензия"); + вы не можете использовать этот файл, кроме как в соответствии с Лицензией. + Вы можете получить копию Лицензии по адресу + + http://www.apache.org/licenses/LICENSE-2.0 + + Если это не требуется по применимому законодательству или письменно согласовано, программное + обеспечение, распространяемое по Лицензии, распространяется на условиях "КАК ЕСТЬ", + БЕЗ ГАРАНТИЙ ИЛИ УСЛОВИЙ ЛЮБОГО РОДА, явных или подразумеваемых. + См. Лицензию для получения конкретных управляющих прав и ограничений. + + +:::danger[Критично] +Для работ, которые не только включают Orchestrator, но и включают модифицированную версию плагина, убедитесь, что вы соблюдаете все требования Apache License, версия 2.0. +Эти требования включают не только вышеуказанный текст, но и то, что все исходные файлы оригинальной работы должны сохранять исходное авторское право и преамбулу лицензии. +Кроме того, любые изменения, внесенные в исходный код, должны быть зафиксированы в заголовках исходных файлов. +Хотя изменения не обязательно должны быть отправлены обратно в исходный проект, они приветствуются! +::: + + + +:::tip +Ваша игра не обязательно должна быть под той же лицензией, что и Orchestrator. +Вы можете выпустить свой проект Godot под любой лицензией и создавать коммерческие игры с этим плагином. +::: + +### Включение + +Лицензия не указывает конкретно, как она должна быть включена в вашу игру. +Существует несколько вариантов, которые вы можете использовать в зависимости от того, как вы распространяете или хотите поделиться информацией о лицензии с вашими пользователями. +Это наиболее распространенные подходы, и вам нужно реализовать только один, а не все. + +#### Экран с указанием авторов + +Включите вышеупомянутый [текст лицензии](#requirements) где-нибудь на экране с указанием авторов. +Он может быть внизу после отображения остальных авторов. +Большинство студий используют этот подход с лицензиями с открытым исходным кодом. + +#### Экран с лицензиями + +Некоторые игры имеют специальное меню (часто в настройках) для отображения лицензий. +Это меню обычно доступно через кнопку `Лицензии третьих сторон` или `Лицензии с открытым исходным кодом`. +Если ваша игра использует такой стиль, включите вышеупомянутый [текст лицензии](#requirements) там. + +#### Сопроводительный файл + +Если игра распространяется на настольных платформах, файл, содержащий [текст лицензии](#requirements), может быть добавлен к программному обеспечению, установленному на ПК пользователя. + +#### Печатное руководство + +Если игра включает печатные руководства, [текст лицензии](#requirements) можно включить туда. + +### Лицензии третьих сторон + +Orchestrator бесплатен и имеет открытый исходный код, и его создание стало возможным благодаря другим бесплатным и открытым технологиям. +Каждая из этих технологий имеет свои собственные лицензии, и благодаря им Orchestrator возможен. + +#### Godot GDExtension (godot-cpp) +```text +Copyright (c) 2017-настоящее время участники Godot Engine. + +Настоящим предоставляется разрешение, бесплатно, любому лицу, получившему копию этого программного обеспечения +и сопутствующих файлов документации (далее "Программное обеспечение"), использовать Программное обеспечение без ограничений, +включая, помимо прочего, права на использование, копирование, изменение, слияние, публикацию, распространение, +сублицензирование и/или продажу копий Программного обеспечения, а также разрешение лицам, которым Программное обеспечение предоставляется, +делать это, при соблюдении следующих условий: + +Вышеуказанное уведомление об авторских правах и это разрешение должны быть включены во все копии +или значительные части Программного обеспечения. + +ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ", БЕЗ ГАРАНТИЙ ЛЮБОГО РОДА, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, +НО НЕ ОГРАНИЧИВАЯСЬ, ГАРАНТИЯМИ КОММЕРЧЕСКОЙ ПРИГОДНОСТИ, ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ. +НИ В КОЕМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ ИСКИ, УБЫТКИ ИЛИ ДРУГИЕ ОБЯЗАТЕЛЬСТВА, +НЕЗАВИСИМО ОТ ФОРМЫ ДЕЙСТВИЯ, ВОЗНИКШИЕ ИЗ ИЛИ В СВЯЗИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ИСПОЛЬЗОВАНИЕМ ИЛИ ИНЫМИ ДЕЙСТВИЯМИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/about/credits.md b/i18n/ru/docusaurus-plugin-content-docs/current/about/credits.md new file mode 100644 index 0000000..561bf0e --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/about/credits.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 7 +--- + +# Благодарности + +Это ресурсы, используемые в данной документации, но взятые из других источников. + +| Названия изображений | Авторство | Лицензия | +|:--------------------------------------------------|:------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------| +| scripting_first_script_rotating_godot.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| scripting_first_script_add_sprite_node.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| scripting_first_script_add_sprite_node.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| scripting_first_script_scene_tree.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| scripting_first_script_setting_texture.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| scripting_first_script_centering_sprite.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| scripting_first_script_print_hello_world.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| scripting_first_script_godot_turning_in_place.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| scripting_first_script_rotating_godot.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| scripting_first_script_moving_with_input.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| key_concepts_main_menu.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| key_concepts_character_nodes.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | +| key_concepts_signals.gif | Juan Linietsky, Ariel Manzur and the Godot community | LICENSE.txt | diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/about/docs_changelog.md b/i18n/ru/docusaurus-plugin-content-docs/current/about/docs_changelog.md new file mode 100644 index 0000000..cea6705 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/about/docs_changelog.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 6 +--- + +# Журнал изменений документации + +Документация постоянно улучшается. +Новые выпуски включают новые страницы, исправления и обновления существующих страниц, а также множество обновлений в [Справочнике по узлам скриптов](../nodes/all_nodes). +Ниже приведен список новых страниц, добавленных с версии 2.0. + +:::info +Этот документ содержит только новые страницы, поэтому не все изменения отражены. +::: + +### Новые страницы с версии 2.0 + +- Добавлены узлы [Memory](../nodes/memory) для [Создания объектов](../nodes/memory#creating-objects) и [Освобождения объектов](../nodes/memory#freeing-objects). +- Добавлены детали [Цепочки методов](../nodes/functions#method-chaining). diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/about/faq.md b/i18n/ru/docusaurus-plugin-content-docs/current/about/faq.md new file mode 100644 index 0000000..991b54e --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/about/faq.md @@ -0,0 +1,34 @@ +--- +sidebar_position: 4 +--- + +# Часто задаваемые вопросы + +## Общие вопросы + +* **Под какой лицензией находится код Orchestrator?**
+Orchestrator лицензирован под лицензией Apache, версия 2.0. + +* **Под какой лицензией находятся логотип и маркетинговые изображения Orchestrator?**
+Логотип и маркетинговые изображения Orchestrator, включая этот веб-сайт, являются Copyright © 2023 Crater Crash Studios. Все права защищены. + +* **Предоставляете ли вы поддержку для этого плагина?**
+Да, мы обязуемся предоставлять поддержку для нашего плагина, просто оставьте свои вопросы в нашем Discord. + +* **Где я могу найти исходный код Orchestrator?**
+Вы можете найти исходный код в нашем репозитории GitHub. + +* **У меня есть предложение или идея, как я могу поделиться этим с вами?**
+Не стесняйтесь оставить его в нашем канале `#suggestions` на Discord или в нашем репозитории GitHub. + +* **Вы аффилированы с Godot или движком Godot?**
+Нет, Crater Crash Studios не аффилирована с Godot или движком Godot. + +* **Поддерживает ли Orchestrator Godot 4.2 и выше?**
+Да, Orchestrator поддерживает Godot 4.2 и выше. Он не работает с версиями Godot ниже 4.2. + +## Устранение неполадок + +* **Ошибка: "Required virtual method ScriptExtension::_get_language must be overridden before calling."**
+Это досадная ошибка в движке Godot, и это нормально для плагинов GDExtension. +Это не повлияет на стабильность плагина, так что можно безопасно игнорировать. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/about/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/about/index.md new file mode 100644 index 0000000..6cd508b --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/about/index.md @@ -0,0 +1,31 @@ +--- +sidebar_position: 1 +title: О проекте +slug: / +--- + +# Документация Godot Orchestrator + +:::info +Документация Orchestrator доступна на различных языках и в различных версиях. Разверните селектор языка или версии в верхней панели навигации, чтобы увидеть возможные варианты. +::: +:::info +Обратите, пожалуйста, внимание, что основная документация Orchestrator написана на английском языке. Документация Orchestrator на русском языке может быть не полностью переведена с английского языка, а также учитывайте, что документация по Orchestrator регулярно обновляется, и актуализация документации на русском языке занимает время. Если вы хотите получить всегда самую актуальную документацию, используйте, пожалуйста, документацию на английском языке. +::: + +Добро пожаловать в официальную документацию Orchestrator, лучшего решения для визуального скриптинга, специально разработанного для платформы Godot. Если вы новичок в этой документации, мы рекомендуем прочитать [введение](./introduction.md), чтобы получить общее представление о том, что эта документация предлагает. + +Оглавление в боковой панели позволит вам легко получить доступ к документации по интересующей вас теме. + +## Примите участие + +Orchestrator — это проект с открытым исходным кодом, разработанный Crater Crash Studios, LLC в сотрудничестве с сообществом волонтеров. +Команде, занимающейся документацией, всегда полезна обратная связь и помощь в улучшении учебных материалов, справочников по классам и многого другого. +Если вы не понимаете что-то или не можете найти то, что ищете в документации, помогите нам улучшить документацию, сообщив об этом! Отправьте запрос на создание проблемы или pull request в репозиторий GitHub или помогите перевести документацию на другие языки. + +## Офлайн документация + +Чтобы просматривать документацию офлайн, вы можете клонировать репозиторий GitHub. + +Эта документация построена с использованием Docusaurus, используя React и Node.JS. +Просто установите менеджер пакетов Node.JS `npm`, и вы сможете легко собрать и запустить эту документацию локально. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/about/introduction.md b/i18n/ru/docusaurus-plugin-content-docs/current/about/introduction.md new file mode 100644 index 0000000..ad5e8a3 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/about/introduction.md @@ -0,0 +1,67 @@ +--- +sidebar_position: 1 +--- + +# Введение + +Добро пожаловать в официальную документацию **Orchestrator**, лучшего визуально-скриптового плагина для Godot. +Orchestrator — это мощный, но при этом удобный в использовании плагин, который вы можете использовать для разработки любого типа игр. + +Эта страница дает общее представление о плагине и документации, чтобы вы знали, с чего начать, если вы новичок, или где искать более конкретную информацию о функции. + +## Прежде чем начать + +На странице [Уроки и ресурсы](../community/tutorials-and-resources) представлен список видеоуроков от различных авторов, включая авторов плагина. +Если вы предпочитаете видео вместо текста, обратите внимание на них. +В противном случае, [Начало работы](../getting-started/introduction) — отличная отправная точка. + +Если у вас возникли проблемы с одним из уроков или вашим проектом, вы всегда можете найти помощь в сообществе Crater Crash Studios на Discord, на наших форумах или в Discord-сообществе Godot. + +## О Orchestrator + +Каждая игра начинается с одной идеи, и создание игры включает множество движущихся частей. +Цель Orchestrator — предоставить серию простых в использовании, высоко настраиваемых функций для создания игровой логики, взаимодействий и поддерживающей логики с использованием визуального скриптинга, а не традиционного текстового кода. + +Orchestrator полностью бесплатен и имеет открытый исходный код под лицензией Apache License, Version 2.0. +Игра, которую вы создаете, принадлежит вам, до последней строки кода. +Разработка этого плагина полностью независима и полностью ориентирована на сообщество, что дает сообществу возможность формировать будущее плагина в соответствии с их потребностями и ожиданиями. + +## Организация документации + +Эта документация организована в несколько разделов: + +* **О проекте** содержит это введение, а также информацию о плагине, его истории, лицензировании, авторах и многом другом. +Он также содержит раздел [Часто задаваемые вопросы](../about/faq), помогающий ответить на некоторые из самых распространенных вопросов. + +* **Начало работы** содержит всю необходимую информацию по использованию плагина для создания игр. +Он начинается с **пошагового** руководства, которое должно быть отправной точкой для всех новых пользователей. +**Это лучшее место для начала, если вы новичок**! + +* **Руководство** можно читать или использовать по мере необходимости, в любом порядке. +Оно содержит руководства и документацию по конкретным функциям. + +* **Участие** предоставляет информацию, связанную с внесением вклада в Orchestrator, будь то код плагина, документация, примеры или другие аспекты. +Оно описывает, как сообщать об ошибках, как организованы рабочие процессы участников и многое другое. +Также есть разделы, предназначенные для опытных пользователей и участников, с информацией о компиляции плагина. + +* **Сообщество** посвящено жизни сообщества плагина Orchestrator. +Он ссылается на различные сообщества и Discord-каналы, а также содержит список рекомендуемых уроков и материалов за пределами этой документации. + +* **Справочник по узлам скриптов** документирует каждый тип узла визуального скрипта Orchestrator, как вы можете их использовать, их назначение и как их настраивать. +Здесь следует искать, если вы не понимаете конкретный узел или не уверены, как найти конкретный узел или функцию. + +В дополнение к этой документации, вы также можете взглянуть на различные примеры проектов Orchestrator. + +## О документации + +Сообщество Orchestrator постоянно пишет, исправляет, редактирует и улучшает эту документацию. +Мы всегда ищем больше помощи. +Вы также можете внести свой вклад, открывая вопросы на GitHub или переводя документацию на свой язык. +Если вы хотите помочь, смотрите [Способы участия](../contributing/ways-to-contribute) и [Написание документации](../contributing/writing-documentation), или свяжитесь с командой на Discord. + +Все содержимое документации лицензировано по свободной лицензии Creative Commons Attribution 3.0 (CC BY 3.0) с указанием авторства *"Crater Crash Studios, LLC и сообщество"*, если не указано иное. + +***Приятного чтения и создания игр с Orchestrator!*** + + + diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/about/release-policy.md b/i18n/ru/docusaurus-plugin-content-docs/current/about/release-policy.md new file mode 100644 index 0000000..5dcb696 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/about/release-policy.md @@ -0,0 +1,109 @@ +--- +sidebar_position: 5 +--- + +# Политика релизов + +Политика релизов Orchestrator постоянно развивается. +Описание ниже дает общее представление о том, чего ожидать, но фактически происходящее зависит от множества факторов, включая потребности сообщества в любой данный момент. + +## Версионирование + +Orchestrator вольно следует семантическому версионированию с системой версий `major.minor.patch`. + +* `major` версия увеличивается, когда происходят серьезные несовместимости, которые предполагают значительную работу по переносу проектов с одной основной версии на другую. + + Например, перенос проектов, основанных на Orchestrator, с версии Orchestrator v2.x на Orchestrator v3.x требует запуска проекта через инструмент конверсии, а затем, возможно, выполнения ряда дополнительных корректировок вручную для того, что инструмент не смог сделать автоматически. + +* `minor` версия увеличивается для релизов с новыми функциями, которые не приводят к серьезным несовместимостям. +Незначительные несовместимости в очень специфических обстоятельствах *могут* происходить в минорных версиях, но подавляющее большинство проектов не должны быть затронуты или требовать значительной работы по переносу. + + Это связано с тем, что Orchestrator предоставляет функции, охватывающие широкий спектр возможностей игрового движка Godot, таких как рендеринг, физика и скриптинг. +Исправление ошибок или реализация новых функций в одной области может потребовать изменений в поведении функции или модификации некоторого аспекта кода, даже если изменение остается в основном обратно совместимым. + + :::tip + Рекомендуется обновляться до новой минорной версии всем пользователям, но необходимо провести тестирование, чтобы убедиться, что ваши проекты работают как ожидалось. + ::: + +* `patch`, или часто называемая версиями обслуживания или исправления ошибок, увеличивается для выпусков обслуживания, которые фокусируются на исправлении ошибок, проблем безопасности, реализации новых требований и обратном переносе безопасных улучшений. +Patch-релизы являются обратно совместимыми. + + Patch-версии могут включать небольшие новые функции, которые не влияют на существующий API, и, следовательно, не представляют риска для существующих проектов. + + :::tip + Обновление до новых patch-версий считается безопасным и настоятельно рекомендуется всем пользователям. + ::: + +Мы называем комбинации `major.minor` _стабильными ветками_. +Каждая стабильная ветка начинается с релиза `major.minor` без `0` для `patch`, и далее развивается для выпусков обслуживания в Git-ветке с тем же именем (например, обновления для стабильной ветки 2.0 разрабатываются в Git-ветке `2.0`). + +## Таймлайн поддержки релизов + +Стабильные ветки поддерживаются *как минимум* до выпуска следующей стабильной ветки и получения ею первого обновления patch. +На практике, мы поддерживаем стабильные ветки на *максимально возможных* основаниях, пока у них есть активные пользователи, которым нужны обновления обслуживания. + +Каждый раз, когда выпускается новая основная версия, мы делаем предыдущую стабильную ветку выпуском с долгосрочной поддержкой и делаем все возможное, чтобы предоставлять исправления для проблем, с которыми сталкиваются пользователи этой ветки, которые не могут перенести сложные проекты на новую основную версию. + +В каждой серии минорных релизов поддерживаются только последние patch-релизы. +Если у вас возникла проблема с использованием более старого patch-релиза, пожалуйста, обновитесь до последнего patch-релиза этой серии и протестируйте снова перед тем, как сообщать о проблемах на GitHub. + +| Версия | Дата релиза | Уровень поддержки | +|:-----------------------|:-------------------------|:--------------------------------------------------------------------------------------------------------------------------------| +| Orchestrator 2.1 (основная) | Июнь 2024
(оценка) | *Разработка.* Получает новые функции, улучшения удобства использования и производительности, а также исправления ошибок, пока находится в разработке. | +| Orchestrator 2.0 | Март 2024 | Получает исправления ошибок и проблем безопасности, а также патчи, которые обеспечивают поддержку платформ и другие небольшие функции. | +| Orchestrator 1.1 | Декабрь 2023 | Больше не поддерживается. | +| Orchestrator 1.0 | Август 2023 | Больше не поддерживается (последнее обновление: 1.0.5). | + +Предрелизные версии плагина Orchestrator не предназначены для использования в производственных условиях и предоставляются только для тестирования. + +## Какую версию следует использовать для нового проекта? + +Мы рекомендуем использовать Orchestrator 2.0 для всех новых проектов, так как серия Orchestrator 1.x больше не поддерживается. + +## Когда выйдет следующий релиз? + +Участники Orchestrator не работают по строгим срокам, но мы стремимся публиковать минорные релизы относительно часто. +Мы обычно стараемся придерживаться трехмесячного цикла для минорного релиза, начиная с первого месяца календарного квартала и выпуская стабильную версию этого минорного релиза к концу квартала. + +Например, Orchestrator 2.0 вошел в предрелизное рассмотрение для тестирования в начале января 2024 года, был выпущен стабильным в марте 2024 года. +Кроме того, Orchestrator 2.1 вошел в разработку в начале апреля и планируется к стабильному выпуску к концу июня 2024 года. + +## Каковы критерии совместимости между версиями? + +:::info +Этот раздел предназначен для использования участниками, чтобы определить, какие изменения безопасны для данного релиза. +Этот список никоим образом не исчерпывающий; он только описывает наиболее распространенные ситуации, наблюдаемые во время разработки. +::: + +Следующие изменения допустимы в patch-релизах: + +* Исправление ошибки таким образом, чтобы это не имело серьезного негативного влияния на большинство проектов, например, визуальной или физической ошибки. +Если исправление ошибки имеет негативное влияние, которое может поставить под угрозу многие проекты, оно должно быть сделано опциональным (используя настройку проекта). +* Добавление нового опционального параметра к методу. +* Небольшие улучшения удобства использования редактора. + +:::info +Обратите внимание, что мейнтейнеры могут быть более консервативными с исправлениями в последующих patch-релизах. +Например, 2.0.1 может получить более значительные исправления, чем 2.0.2. +::: + +Следующие изменения допустимы в минорных релизах, но не в patch-релизах: + +* Значительные новые функции. +* Переименование параметров методов из-за ограничений интеграции с C# и GDScript. +* Устаревание методов, переменных или классов. +Это делается путем добавления флага устаревания в справочник классов, который должен отображаться в редакторе. +Когда метод помечен как устаревший, он планируется к удалению в следующем *основном* релизе. +* Изменения, влияющие на визуальное оформление по умолчанию. +* Исправления ошибок, которые значительно изменяют поведение или вывод, с целью лучше соответствовать ожиданиям пользователей. +Для сравнения, в patch-релизах мы предпочитаем сохранять неправильное поведение, чтобы избежать нарушения существующих проектов, которые могут полагаться на это неправильное поведение или использовать обходные пути. +* Оптимизации производительности, которые приводят к визуальным изменениям. + +Следующие изменения считаются **нарушающими совместимость** и могут происходить только в новых основных релизах: + +* Переименование или удаление методов, переменных или классов. +* Изменение наследования или поведения узла таким образом, что узел действует совершенно иначе. +* Изменение значения настройки по умолчанию таким образом, что это влияет на существующие проекты. + +Поскольку Orchestrator 3.0 еще не был выделен в отдельную ветку, мы настоятельно не рекомендуем вносить изменения, нарушающие совместимость. + diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/about/requirements.md b/i18n/ru/docusaurus-plugin-content-docs/current/about/requirements.md new file mode 100644 index 0000000..7cf8fda --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/about/requirements.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 3 +--- + +# Системные требования + +Эта страница описывает системные требования для плагина Orchestrator. +Эти спецификации предоставлены только для информационных целей, но их можно использовать, если вы планируете создать или обновить систему для разработки игр с использованием Orchestrator. + +## Orchestrator + +Orchestrator — это плагин, который работает внутри редактора Godot во время разработки. +Поэтому использование плагина полностью зависит от соответствия требованиям для запуска редактора Godot. + +Текущие **минимальные** спецификации, необходимые для запуска редактора Godot, доступны в документации Godot. + +## Экспортированный проект Orchestrator + +Аналогично, для использования Orchestrator в экспортированной игре Godot, плагин должен работать внутри движка Godot. +Поэтому использование плагина полностью зависит от соответствия требованиям для запуска движка Godot. + +Текущие **минимальные** спецификации, необходимые для запуска экспортированного проекта Godot, доступны в документации Godot. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/community/_category_.json b/i18n/ru/docusaurus-plugin-content-docs/current/community/_category_.json new file mode 100644 index 0000000..846df39 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/community/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Community", + "position": 6 +} \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/community/tutorials-and-resources.md b/i18n/ru/docusaurus-plugin-content-docs/current/community/tutorials-and-resources.md new file mode 100644 index 0000000..72eb4ba --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/community/tutorials-and-resources.md @@ -0,0 +1,17 @@ + +# Уроки и ресурсы + +На этой странице содержится список различных уроков и ресурсов, созданных Crater Crash Studios и участниками сообщества. + +Если вы считаете, что здесь чего-то не хватает, отправьте Pull Request. + +## Уроки + +* Документация Godot: Урок 2D с Orchestrator +* Документация Godot: Урок 3D с Orchestrator +* [Пошаговое руководство](../getting-started/step-by-step) + +## Видеоролики + +* Визуальный скрипт Godot вернулся! - Автор: @Gamesfromscratch, февраль 2024. +* Я попробовал Godot VisualScript в 2024 году (и нашел альтернативу) - Автор: @Code_It_All, апрель 2024. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contributing/_category_.json b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/_category_.json new file mode 100644 index 0000000..a52fe9b --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 5 +} \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contributing/contribution-workflow.md b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/contribution-workflow.md new file mode 100644 index 0000000..02230ba --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/contribution-workflow.md @@ -0,0 +1,83 @@ +--- +sidebar_position: 2 +--- + +# Contribution workflow + +## Pull request workflow + +The so-called "PR workflow" used by Orchestrator is common to many projects using Git, and should be familiar to veteran free software contributors. +The idea is that only a small number (if any) commit directly to the master branch. +Instead, contributors fork the project (i.e. create a copy of it, which they can modify as they wish), and then use the GitHub interface to request a pull from one of their fork's branches to one branch of the original (often named upstream) repository. + +The resulting *pull request* (PR) can then be reviewed by other contributors, which might approve it, reject it, or most often request that modifications be done. +Once approved, the PR can then be merged by one of the core developers, and its commit(s) will become part of the target branch (usually the master branch). + +We will go together through an example to show the typical workflow and associated Git commands. +But first, let's have a quick look at the Orchestrator Git repository. + +### Git source repository + +The repository on GitHub is a Git code repository together with an embedded issue tracker and PR system. + +:::info +If you are contributing to the documentation, its repository can be found here. +::: + +The branches on the Git repository are organized as follows: + +* The `main` branch is where development for the next major version occurs. +As a development branch, it's considered unstable and not meant for production use. +This is where pull requests should __always__ be done. +* The stable branches are named after their respective version, e.g. `1.1` and `2.0`. +They are used to backport bugfixes and enhancements from the `main` branch to the currently maintained stable release. +As a rule of thumb, the last stable branch is maintained until the next minor version (e.g. the `2.0` branch maintained until `2.1.`). +If you want to open pull requests against a stable branch, please check first if your changes are relevant for the `main` branch, and make the PR against `main` if so. +The core team will cherry-pick from `main` if they believe the change should be included in a maintenance release for a stable branch. + +### Forking and cloning + +The first step to contributing is to _fork_ the repository on GitHub. +To do so, you must have a GitHub account, be logged in, and click the button in the top right that reads "Fork". +You will need to answer a series of questions. Once complete, you will find a repository under your username in the URL with the same upstream repository name of `godot-orchestrator`. + +Once you have forked the repository, it's time to make a local copy, so you can more easily make changes. +In Git speak, you must clone your fork to your local computer. +To clone your repository, use the following command in a terminal window: + +```bash +git clone https://github.com//godot-orchestrator.git +``` + +After Git has cloned the repository, you will find a new directory called `godot-orchestrator`. +Next, change directories into the `godot-orchestrator` directory and execute the following commands: + +```bash +git remote add upstream https://github.com/Vahera/godot-orchestrator.git +git fetch upstream +``` + +The above creates a reference named `upstream` to the original `godot-orchestrator` repository maintained by Crater Crash Studios. +This reference will be helpful because you want to keep your local repository up-to-date with new commits added to the original repository. +You will also have another reference to `origin`, which points to your _fork_ repository on GitHub. + +### Rebasing changes on conflicts + +Ideally, it would help if you created a feature or bugfix branch locally. +This branch is where you will make all the necessary changes to add your new feature or bug fix. + +When submitting pull requests for code changes, the commit history should be linear, not contain merge commits, and be free of merge conflicts. +If you contribute a pull request and GitHub states there are conflicts, consider pulling down the latest upstream changes and rebasing your work on those changes before opening the pull request. + +Assuming you have set up the `upstream` reference and you have committed all your changes in your local fork's branch, execute the following commands to rebase: + +```bash +git checkout main +git pull upstream main +git checkout +git rebase main +``` + +If there are conflicts, you must compare the upstream changes with your local changes in your feature branch. +You can continue the rebase by running `git rebase --continue` after resolving all conflicts. +Once the rebase has finished, you must update your feature branch using `push --force` to your GitHub fork's branch. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contributing/development/code-style-guidelines.md b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/development/code-style-guidelines.md new file mode 100644 index 0000000..7fb83bb --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/development/code-style-guidelines.md @@ -0,0 +1,198 @@ +# Руководство по стилю кода + +При внесении вклада в исходный код Orchestrator от вас ожидается соблюдение приведенных ниже рекомендаций по стилю. +Некоторые из них проверяются с помощью непрерывной интеграции, и рецензенты могут попросить вас исправить потенциальные проблемы, поэтому, в общем, хорошей идеей будет настроить вашу систему, как указано ниже, чтобы уменьшить количество проблем с вашими коммитами на раннем этапе. + +## C++ и Objective-C + +Письменных рекомендаций нет, но общий стиль кода согласован с основными разработчиками и применяется с помощью beautifier `clang-format`. +Это делает следующее для вас: + +* Отступы и выравнивание основаны на табуляциях (соответственно один и два таба) +* Один пробел вокруг операторов соответствия и присваивания, а также после запятых +* Операторы указателей и ссылок присоединяются к имени типа, а не к идентификатору переменной +* См. ниже для включений заголовков + +Правила для clang-format изложены в файле `.clang-format` в репозитории Orchestrator на Git. + +Пока ваш стиль соответствует окружающему коду и вы не вводите конечные пробелы или пробелы-отступы, все должно быть в порядке. +Однако, если вы планируете регулярно вносить вклад, настоятельно рекомендуем настроить clang-format для проверки и исправления всех ваших коммитов. + +:::warning +Руководство по стилю кода Orchestrator не должно применяться к коду сторонних или внешних подмодулей git. +Другими словами, оно должно применяться только к файлам, находящимся в каталоге `/src`. +::: + +## Имена файлов + +Используйте `snake_case` для имен файлов. +Избегайте использования заглавных букв, так как они обрабатываются по-разному в разных операционных системах. + +## Включения заголовков + +При добавлении новых файлов C++ или Objective-C или включении новых заголовков в существующие файлы, должны соблюдаться следующие правила: + +* Первые строки в файле должны содержать заголовок авторских прав Orchestrator и лицензию Apache 2.0, скопированные из другого файла. +* В заголовке `.h` должны использоваться охранители включения в форме `ORCHESTRATOR_FILENAME_H` или `OSCRIPT_FILENAME_H`. +* В файле `.cpp` (например, `filename.cpp`) первым должно быть включение, где объявлен класс (например, `#include "filename.h"`), за которым следует пустая строка для разделения. +* Затем идут заголовки из базы кода Orchestrator, включенные в алфавитном порядке, с путями относительно корневого каталога. Включения должны быть окружены кавычками, например, `#include "core/object.h"`. +Блок включений Orchestrator должен быть отделен пустой строкой. +* Затем идут заголовки из библиотеки `godot-cpp` Godot, включенные в алфавитном порядке. Включения должны быть окружены скобками, например, `#include `, за которыми следует пустая строка для разделения. +* Наконец, должны быть включены все оставшиеся заголовки, опять же используя скобки, перечисленные в алфавитном порядке. + +```text title="Пример заголовка" +// Этот файл является частью проекта Godot Orchestrator. +// +// Copyright (c) 2023-настоящее время Crater Crash Studios LLC и его участники. +// +// Лицензировано по Apache License, версия 2.0 (далее "Лицензия"); +// вы не можете использовать этот файл, кроме как в соответствии с Лицензией. +// Вы можете получить копию Лицензии по адресу +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Если это не требуется по применимому законодательству или письменно согласовано, программное +// обеспечение, распространяемое по Лицензии, предоставляется "КАК ЕСТЬ", +// БЕЗ ГАРАНТИЙ ИЛИ УСЛОВИЙ ЛЮБОГО РОДА, явных или подразумеваемых. +// См. Лицензию для получения конкретных управляющих прав и ограничений. +// +#ifndef ORCHESTRATOR_ABOUT_DIALOG_H +... +#endif ORCHESTRATOR_ABOUT_DIALOG_H + + +// Этот файл является частью проекта Godot Orchestrator. +// +// Copyright (c) 2023-настоящее время Crater Crash Studios LLC и его участники. +// +// Лицензировано по Apache License, версия 2.0 (далее "Лицензия"); +// вы не можете использовать этот файл, кроме как в соответствии с Лицензией. +// Вы можете получить копию Лицензии по адресу +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Если это не требуется по применимому законодательству или письменно согласовано, программное +// обеспечение, распространяемое по Лицензии, предоставляется "КАК ЕСТЬ", +// БЕЗ ГАРАНТИЙ ИЛИ УСЛОВИЙ ЛЮБОГО РОДА, явных или подразумеваемых. +// См. Лицензию для получения конкретных управляющих прав и ограничений. +// +#include "about_dialog.h" + +#include "authors.gen.h" +#include "donors.gen.h" +#include "license.gen.h" +#include "common/version.h" +#include "plugin/plugin.h" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +## Имена классов + +Все имена классов C++ должны использовать **Pascal Case**. + +Кроме того, существуют два соглашения об именах, которых следует придерживаться в зависимости от контекста класса. +Классы, связанные с функциональностью редактора, должны иметь префикс `Orchestrator`. +Классы, связанные с функциональностью скриптов во время выполнения, должны иметь префикс `OScript`. + +* **Пример для редактора**: `OrchestratorMainView` или `OrchestratorPlugin`. +* **Пример для скрипта**: `OScriptNodeConstant` или `OScriptNodeInitContext`. + +Как правило, мы предпочитаем один класс на файл, но есть случаи, когда имеет смысл включать несколько классов в один файл. +Пожалуйста, делайте это редко, предпочтительно один класс на файл. + +## Имена функций и переменных + +Все функции и переменные должны быть определены с использованием `snake_case`. +Если функция или переменная не является публичной, она должна иметь префикс подчеркивания (`_`). + +Кроме того, все аргументы функций должны иметь префикс `p_`, если значение не возвращается вызывающему, в этом случае оно должно иметь префикс `r_`. + +```cpp title="Пример" +class MyClass : public Resource +{ + GDCLASS(MyClass, Resource) + +protected: + String _the_name; + + void _set_the_name(const String& p_name); + +public: + String get_the_name() const; +}; + + +Additionally, function and variables of like scope should be grouped together. +Lastly, all functions that do not override a parent class method should be documented. +See the [Comment style guide](#comment-style-guide) for more details. + +## Constants and enums + +Constants should use `CONSTANT_CASE` (also called screaming snake case), that is all caps with an underscore (`_`) to separate words. + +```cpp title="Example constant" +const MAX_SPEED = 10; +``` + +Define enums using `PascalCase`, with a prefix of `E`: + +```cpp title="Example enum" +enum EDataType +{ + EDT_ANY, + EDT_NUMERIC +}; +``` + +## Comment style guide {#comment-style-guide} + +This comment style guide applies to all languages within the Orchestrator code base. + +* Begin comments with a space character to distinguish them from disabled code. +* Use sentence case for comments, beginning with an uppercase character and ending with a period. +* Reference variables/functions using backticks +* Wrap comments to ~120 characters. +* Use `TODO:`, `FIXME:`, `NOTE:`, or `HACK:` as admonitions as needed. + +```cpp title="Example" +// Compute the first 10,000 decimals of Pi. +// FIXME: Don't crash when computing due to `increment` being negative. +``` + +Don't repeat what the code says in comments, explain *why* rather than *how*. + +```cpp title="Poor example" +// Draws loading screen. +draw_loading_screen(); +``` + +Ideally all methods should be documented, using doxygen style comments. + +```cpp title="C++ method documentation example +/// Returns the number of nodes in the universe. +/// @param p_root the root node, should not be null +/// @return the number of nodes +uint64_t Universe::get_nodes_from_root(Node* p_root) { + // ... +} +``` + +For member variables, use single-line comments at the end of the variable declarations: + +```cpp title="C++ member variable documentation" +public: + boolean _is_visible; //! Specifies whether this object is visible +``` \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contributing/development/cpp-usage-guidelines.md b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/development/cpp-usage-guidelines.md new file mode 100644 index 0000000..af22d8a --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/development/cpp-usage-guidelines.md @@ -0,0 +1,66 @@ + +# C++ usage guidelines + +## Rationale + +Since Orchestrator 2.0, Orchestrator was written in C++ and the standard used throughout the code base is **C++20**. +While modern C++ brings a lot of opportunities to write faster, more readable code, we chose to restrict the usage for a number of reasons: + +* It makes it easier to review code in online editors. +This is because contributors don't always have access to a full-featured IDE while reviewing code. +* It makes the code easier to grasp for beginner contributors who may not be as proficient in C++. + +For your pull request to be merged, it must follow the C++ usage guidelines outlined here. +If you are extending Orchestrator in your own fork, you can use features not allowed in your own code, but any contributions upstream should follow these rules. + +## Disallowed features + +**Any feature that isn't listed is allowed**. + +Using features like `constexpr` variables and `nullptr` is encouraged when possible. +Still, try to keep your use of modern C++ features conservative. +Their use needs to serve a real purpose, such as improving the code's readability or performance. + +### Standard Template Library + +We do not allow the use of the STL as Orchestrator utilizes all of Godot's own data types. + +This means that pull requests should **not** use `std::string`, `std::vector`, and the like. +Instead, use the Godot data types described below: + +* Use `String` rather than `std::string`. +* Use `Vector` rather than `std::vector`. In some cases `LocalVector` can be an alternative. +* Use `Array` rather than `std::array`. + +:::important +There are some Godot CPP data structures that do use `std::vector`, such as `MethodInfo`. +For these specific corner cases, the use of `std::vector` is allowed, but it should be minimal. +::: + +### `auto` keyword + +Please do not use the `auto` keyword for type inference. +While it can avoid repetition, it can also lead to confusing code: + +```cpp title="Example" +// Not so confusing... +auto button = memnew(Button); + +// ...but what about this? +auto result = EditorNode::get_singleton()->get_complex_result(); +``` + +Keep in mind that intellisense and hover documentation isn't readily available for pull request reviewers. +Most of the time, reviewers will use GitHub's online viewer to review pull requests. + +We chose to forbid `auto` instead of allowing it on a case-by-case basis to avoid having to decide on difficult edge cases. + +### Lambdas + +Lambdas should be used conservatively when they make code effectively faster or simpler, and do not impede readability. +Please ask before using lambdas in a pull request. + +### `#pragma once` directives + +Please follow the existing style and use standard `#ifdef`-based include directives. +Pull requests that use the `#pragma once` directive will not be merged until changed. \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contributing/development/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/development/index.md new file mode 100644 index 0000000..fcb18a0 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/development/index.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 3 +title: Plugin development +--- + +# Plug-in development + +The guides below explain how to contribute to the plug-in's code base. +You will learn the best practices when working on solutions and features, the source code style requirements, and the internal structure of the code base, how to set up your working environment, and more. + +* [Code style guidelines](code-style-guidelines) +* [C++ usage guidelines](cpp-usage-guidelines) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contributing/ways-to-contribute.md b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/ways-to-contribute.md new file mode 100644 index 0000000..fd2f924 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/ways-to-contribute.md @@ -0,0 +1,75 @@ +--- +sidebar_position: 1 +--- + +# Ways to contribute + +Orchestrator is a community-driven, free, and open-source project. +All developers work on this plug-in *pro bono*, meaning they contribute their free time and skills for the love of making tools for others. + +This means that for Orchestrator to thrive, it needs contributors to help improve the plug-in. +There are multiple ways to contribute to a project, making it possible for everyone to bring something positive to the project, regardless of your skill set.s + +- **Be part of the community**.
+The best way to contribute to Orchestrator, and to help it grow is to simply use the plug-in and promote it by word-of-mouth, in the credits or splash screen of your games, blog posts, tutorials, videos, demos, you name it. +Participate! Being a user and advocating for the plug-in helps spread the word about Orchestrator, which is not professionally marketed, and therefore relies on its community. + +- **Make games**.
+It's no secret, no convince new users that visual scripting with Orchestrator can be fun, we need games made with it. +We know that visual scripting has tremendous potential, it's one of the most common ways to use other engines like Unreal. +So work on your awesome projects, each new game increases the plug-ins ability to illustrate it's potential. + +- **Get involved in the plug-in's development**.
+Many people think that getting involved in develop means contributing code, but that's far from the truth. +While contributing code via pull requests are much appreciated, testing the development snapshots, reporting bugs or suggesting enhancements on GitHub, improving this documentation, or even translations go a long way to increasing the availabiility and success of the project. +The following sections will cover some of these direct ways to contribute. + +- **Donate**.
+Orchestrator is a plug-in that is defined completely free of charge, and in the spare time of willing contributors. +Donations help cover certain operating costs for hosting our websites, content, and more. +If you want to donate to the project, check our website for details. + +## Contributing code + +The possibility to study, use, and contribute to the Orchestrator project is made possible because the project is open-source. + +If you want to get started contributing to open source, check out the repository by creating a fork, and getting familiar with the code base. +One of the most direct ways to contribute to the project is to submit bug fixes or improvements to the project through a GitHub pull request. + +Contributing code has two big advantages: + +* Your own code will be reviewed and improved by other developers, and will be further maintained directly in the upstream project, so you won't have to reapply the change to your fork if you're extending Orchestrator. +On the other hand, it comes with a responsibility, as your changes to be generic to be beneficial to all, and not only to your project; so in some cases it may still be relevant to keep your changes in your own fork should they be too specific. + +* The whole community benefits from your work, consequentially other contributors will contribute code that benefits you. + +To aid in collaboration and overall quality, the core developers will enforce some rules for code contributions, for example regarding the style to use in the C++ code (indentations, brackets, etc) or the Git and PR workflow will. + +All pull requests go through a review process before being accepted. +Depending on the scope of the changes, it may take sometime for a maintainer to provide their review. +We value all contributors, and ask for patience when submitting pull requests. + +## Testing and reporting issues + +Another excellent way to contribute to the plug-in is to test development releases and report issues. +It is also helpful to report issues discovered during stable releases, so that they can be fixed in the development branch and in future maintenance releases. + +### Testing development versions + +To help with testing, test our official pre-release binaries when they are announced (using on the blog and other community platforms). +Pre-release builds are tagged with the `dev`, `beta`, or `rc` designators. + +It's also helpful to be on the lookout for bugs in stable releases. + +### Filing an issue on GitHub + +Orchestrator uses GitHub's issue tracker for bug reports. +When you start filing a bug report, you'll be given a form to fill out. +Please try and follow it so that all issues are consistent and provide the necessary information. + +## Contributing to the documentation + +The documentation is maintained in the Orchestrator docs repository. +This repository maintains not only the raw markdown files used for documentation, but also all translations used for various languages. + +Should you find outdated information in the documentation or parts that could be improved, contributions are welcomed. \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contributing/writing-documentation.md b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/writing-documentation.md new file mode 100644 index 0000000..f3b76b2 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/contributing/writing-documentation.md @@ -0,0 +1,7 @@ +--- +sidebar_position: 4 +--- + +# Writing documentation + +We always can use help to improve documentation, be it the script node reference or the manuals. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/_category_.json b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/_category_.json new file mode 100644 index 0000000..14fe602 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/first-look-at-the-plugin.md b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/first-look-at-the-plugin.md new file mode 100644 index 0000000..888d63b --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/first-look-at-the-plugin.md @@ -0,0 +1,237 @@ +--- +sidebar_position: 4 +--- + +# First look at the plug-in + +This page will give you a brief overview of Orchestrator's interface. +We're going to look at the main workspace, the integration with Godot, and its intuitive integrated class reference subsystems. + +## The main workspace + +You access the main workspace of the plug-in by clicking on the tab labeled **Orchestrator** at the top of the Godot Editor. + +### Graph view + +Initially, the main workspace is empty, only showing the file list. +This is because no `Orchestration` resources have been opened. +By either creating a new orchestration using `File > New Orchestration`, or opening an existing orchestration, the main workspace will include other widgets. + +
+ +In the above example, an orchestration has been opened. +To the left is the **Graph** canvas where you place visual script nodes to create logic. +At the top of the **Graph**, there is a tab bar, where you can quickly navigate between different **Graph** components or user-defined **Function**s. + +On the right is the **Component** view, where high-level components can be added. + +### Component view + +The **Component** view is where you can quickly add, rename, and remove various components from the orchestration. + +
+ +* The **Graph** section always defines at least one graph called **EventGraph**. +This is where you will define all your interactions with the Godot engine to handle overrides, such as when your script receives *input* or updates each game tick. + +* The **Functions** section allows for defining user-defined functions. +User-defined functions are a great way to not only expose functionality to the outside of your script, but to also organize your code so that the visual scripts do not become cluttered. + +* The **Macros** section is currently unimplemented, and will be enabled in a future patch. + +* The **Variables** section allows creating unique named objects for storing values. +Variables are associated with a specific Godot type and can be publicly accessible or scoped to the script. +A variable will be publicly accessible if it has the icon. +This means that the variable is exported, in Godot terms. +The variable is not publicly accessible when using the icon. +This means that the variable is not exported, in Godot terms. + +* The **Signals** section is for user-defined signals, allowing outside observers to connect and be notified when you emit a signal. + +To add a new **Component** type to the `Orchestration`, use the button. +Additionally, for **Functions**, you can also override several Godot built-in virtual functions using the button. + +### All actions dialog + +To begin adding logic to your script, use the right-mouse button to open the **All Actions** dialog. + +
+ +This dialog is where you can search for specific nodes that you wish to add to the graph. +To add a node, either select the choice and press the **Add** button or simply press **Enter**. + +Actions are grouped into the following high-level categories: + +* Functions that you can call on the object, denoted with the icon. +* Properties that you can access, denoted with the icon. +* Signals you can connect and react to, denoted with the icon. +* Overridable functions, denoted with the icon. +* And Orchestrator script nodes, denoted with the icon. + +:::tip +The icon identifies an action that is currently not a favorite. +If you use a specific action frequently, it's recommended that you click the button to make it a favorite. +Favorites are listed at the top of the **All Actions** dialog and will have a new icon. +If you later wish to unfavorite an action, simply click the button. +::: + +:::tip +Right-clicking the graph canvas opens the **All Actions** dialog using the script's base type as the context. +If you drag from a visual script node's pin and release the mouse, the **All Actions** dialog will be opened using the context of the pin. +::: + +### Visual script nodes + +All orchestration scripts are comprised of various visual script nodes. +A visual script node is the building block of an orchestration, that you connect with other script nodes to build behaviors. + +
+ +Script nodes consist of two types of pins, execution or control flow pins, and data pins which are identified by colored dots. + +* **Inputs**
+The pins on the left side of a script node are called inputs, which allow you to pass data or control flow to the node. +* **Outputs**
+The pins on the right side a script node are called outputs, which allow you to pass data or control to another node. + +Visual script nodes can be added to an orchestration using various methods, which include: + +- Opening the **All Actions** dialog +- Or by dragging from various editor docks and the **Component Panel**. + +For details on all the script nodes available, please see the [Script Node Reference](../../nodes/all_nodes). + +## Customization and configuration + +Orchestrator also provides a number of customizations inside the `Project > Project Settings > Orchestrator` section. + +### Settings + +The `Settings` subsection provides access to several global Orchestrator settings. + +##### Base Settings + +| Setting | Description | +|:-------------|:-------------------------------------------------------------------------------------------| +| Default Type | The default class type to be used when creating new orchestrations, defaults to `Node`. | +| Log Level | Specifies the logging level when writing to `user://orchestrator.log`, defaults to `INFO`. | + +##### Runtime Settings + +| Setting | Description | +|:--------------------|:---------------------------------------------------------------------------------------------------| +| Max Call Stack | The maximum possible number of `Variant` (data) slots to allocate per stack, defaults to `1024`. | +| Max Loop Iterations | The maximum number of loop iterations, before a loop is auto-terminated, defaults to 1000000`. | +| Tickable | Whether or not `Orchestration` scripts have their `_process` functions called, defaults to `true`. | + +### UI (User interface) + +The `UI` subsection provides access to many user-interface controls used by Orchestrator. + +##### Action Menu + +| Setting | Description | +|:----------------|:------------------------------------------------------------------------------------------| +| Center on Mouse | Whether the **All Actions** dialog opens centered at the mouse click, defaults to `true`. | + +##### Nodes + +| Setting | Description | +|:-------------------------------|:---------------------------------------------------------------------------| +| Show Type Icons | Whether the data pins on nodes show the icon types, defaults to `true`. | +| Highlight Selected Connections | Highlights any nodes connected to any selected nodes, defaults to `false`. | + +##### Node colors + +In this section, you can customize the colors used for different node type title bars. + +##### Connection colors + +In this section, you can customize the data pin and wire connection colors for each data type. +By default, Orchestrator maps the connection and data pin colors to match the Godot data type icon styles. + +## Seamless editor integration + +One of the major goals of the Orchestrator team is to make sure that the user experience is seamless with the Godot Editor. +We want users to feel as though the plug-in is a fundamental, core part of the Editor. +To achieve this goal, not only do we do our best to follow the same design principals of the Editor, but we also provide seamless integration with the Editor. + +### Drag-n-drop anywhere + +One of the major benefits of Orchestrator is it recognizes data elements that are from other parts of the Editor interface. + +The following drag-n-drop options exist: + +- Drag a scene node from the **Scene** view to get a reference to that scene node in the script. +- Drag a property from the **Inspector** view to access either a **Get** or a **Set** for the specific property. +- Drag a resource from the **FileSystem** view to either obtain its path or to create a **Preload** node for the resource. + +### Multi-node operations + +Bulk operations improves efficiency, and having access to such tools makes working with visual scripting less tedious. +You can use the **Left Mouse Button** to click on the graph and begin to drag to select multiple script nodes. + +With multiple node selected, you can cut (`Ctrl+X`), copy (`Ctrl+C`), and paste (`Ctrl+V`) as needed. + +:::tip +You can also quickly duplicate script nodes using `Ctrl+D`, which is a shortcut for copy-n-paste. +::: + +### Undo and redo + +At this time, Orchestrator does not officially support Undo/Redo operations in the Godot Editor. + +:::info +This feature is currently under development and is planned for a future release. +::: + +## File formats + +Orchestrator supports two file formats: + +* `.torch`, which is text-based +* `.os` which is binary-based. + +The text-based format was introduced with Orchestrator 2.1, and will be the default moving forward. +This format is more human-readable and is easier to work with version control systems, as text-based files allow for significantly easier diffing between changes. +The binary-based format was originally introduced with Orchestrator 2.0, and is planned to be deprecated in a future release. + +### Converting between formats + +In order to convert from one format to another, simply follow these steps: + +1. Open the desired orchestration. +This can be performed by double-clicking the file in the **Filesystem Dock** by using the Orchestrator plug-in's **File** menu by selecting **Open Orchestration**. +2. Click on the **File** menu and select **Save As**. +3. In the **Save As** dialog, provide a new file name with the desired format extension (`.os` or `.torch`). + +:::warning +When converting an Orchestration between formats, the scenes that import and use the Orchestrations are not automatically updated. +You will need to open each scene that uses the Orchestration and re-attach the new Orchestration file that uses the new format you selected. +::: + +:::tip +If you want to change the default format used by the plug-in, this can be done in the `Project > Project Settings` dialog. +Simply open the dialog and navigate to the `Orchestrator > Settings` section where you will find the `Storage Type` configuration option. +Here you can select between either **Text** or **Binary**, which controls the default format used when creating new Orchestrations. +::: + +### Exporting games + +In a Godot project, not every resource is exported in the same format that it's saved with in the project workspace. +This is because often times resources are saved using human-readable formats in the project workspace, but are converted to a binary format when the game is exported for performance reasons. +Several built-in Godot resources are converted to binary when exporting games, such as `.tres` and `.tscn` files, which become `.res` and `.scn`, respectively. + +Orchestrator also uses this same technique when the project's Orchestration is storede in text-based format with the `.torch` extension. +During the export process, the `.torch` file is converted to a compressed, binary format using the `.os` extension, which greatly reduces the file size and speeds up game load times. + +:::tip +When exporting a game, any `.os` binary format that is used in the project is exported as-is without any transformation. +This is because the binary format is already in a compressed format that is suitable for fast game loads. +::: + +## Integrated help + +You can access the documentation related to any visual script node by selecting the node, right-click, and selecting the **View Documentation** option. +This automatically redirects the Editor's main view to the Editor Help window, where the script, associated Godot method, or other related object's help will be shown. + diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/index.md new file mode 100644 index 0000000..23e6fce --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/index.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 1 +--- + +# Introduction + +This series will introduce you to Orchestrator and give you an overview of its features. + +In the following pages, you will get answers to questions such as *"Is Orchestrator right for me?"* or *"What is it that I can do with Orchestrator?"*. +We will introduce the plug-in's most essential concepts, showcase the in-editor interface, and provide tips to make the most of your time learning how to use Orchestrator. + +* [Introduction to Orchestrator](introduction-to-orchestrator) +* [Overview of key concepts](key_concepts) +* [Installation Guide](installation-guide) +* [First look at the plug-in](first-look-at-the-plugin) +* [Learning new features](learning-new-features) +* [Orchestrator's design philosophy](orchestrator-design-philosophy) \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/installation-guide.md b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/installation-guide.md new file mode 100644 index 0000000..a9783e4 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/installation-guide.md @@ -0,0 +1,78 @@ +--- +sidebar_position: 3 +--- + +# Installation guide + +There two ways to install the plug-in: + +* Using the Godot Asset Library in the Godot Editor. +* Downloading the plug-in from our GitHub repository. + +In this section, we'll cover how to use both. + +## Godot asset library + +The Godot Editor has a built-in asset library feature, which allows users to search, download, and install Godot plug-ins, tools, and assets directly from their online asset catalog. + +To access the **Asset Library**, we'll use the **AssetLib** tab at the top of the Godot Editor. + +
+ +In the search box, type `Orchestrator` or simply `Scripting` to locate the plug-in. + +
+ +Click the plug-in's name to open the **Information** dialog. + +
+ +Press the **Download** button to begin the download process. +When the download finishes, you'll be prompted to **Configure Asset Before Installing**, shown here: + +
+ +Uncheck the `Ignore asset root` option. + +
+:::warning +Failing the uncheck this option will not install the plug-in correctly into your project. +::: + +Finally, click the **Install** button, installing the plug-in into the `res://addons/orchestrator` directory. +After installation, the Godot Editor will prompt you to restart. + +:::tip +There is currently an issue with the Godot Editor with loading textures used by GDExtension plug-ins. +The plug-in will be loaded before the textures are imported, causing the textures to not render initially or appear broken in some scenarios. +Restarting the Godot Editor one final time fixes the issue. +::: + +## Download from GitHub + +If you are interested in pre-release builds or are having trouble installing the plug-in using the Godot Asset Library, you can also download the plug-in binaries directly from our GitHub Repository. +To install from GitHub, simply follow these steps: + +1. Locate the latest release on the repository's Releases page. + :::note + While the repository page will show the latest **stable** release, if you are interested in pre-release builds, you will need to specifically look at the **Releases** page as pre-release builds are not listed on the main GitHub repository page. + ::: +2. Once you've located the desired release, expand the **Assets** section if it isn't already. +
+3. Locate the asset labeled `godot-orchestrator--plugin.zip`, and click it.
+ This will download the artifact to your PC. + +Once the artifact has been downloaded, it needs to be unzipped into your Godot project. +If you have not already created a Godot project, you should create one first following these steps. + +With the Godot project created, navigate to where you saved the downloaded file, and extract its contents directly into your Godot project's root-directory. +This should create a directory path like `\addons\orchestrator`. + +Once the files have been installed, focusing the Godot Editor will request to restart. +Simply follow the prompt, restarting Godot, and the plug-in should be active when the editor restarts. + +:::tip +There is currently an issue with the Godot Editor with loading textures used by GDExtension plug-ins. +The plug-in will be loaded before the textures are imported, causing the textures to not render initially or appear broken in some scenarios. +Restarting the Godot Editor one final time fixes the issue. +::: \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/introduction-to-orchestrator.md b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/introduction-to-orchestrator.md new file mode 100644 index 0000000..66deb43 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/introduction-to-orchestrator.md @@ -0,0 +1,79 @@ +--- +sidebar_position: 1 +--- + +# Introduction to Orchestrator + +This article is to help you determine if Orchestrator might be a good fit for you. +We will introduce some broad features of the plug-in and give you a feel for what is achievable while also answering questions such as "what do I need to know to get started?". + +This is by no means an exhaustive overview. +We will introduce many more features in this getting started series. + +## What is Orchestrator? + +Orchestrator is a Godot plug-in designed to provide visual-scripting capabilities to any Godot game project. +It can be used to create games or applications that are released on a myriad of platforms, including desktop, mobile, or the web. + +You can also create console games using Orchestrator, although you either need strong programming skills or a developer to port the game for you. + +:::note +The Orchestrator development team cannot provide an open source console export due to licensing terms imposed by console manufacturers. +Regardless of the engine used, releasing games on consoles is always a lot more work than other platforms. +You can read more in the Godot documentation. +::: + +## What can the plug-in do? + +The idea of Orchestrator as a visual-scripting tool began as an in-house experiment for several unpublished games at Crater Crash Studios. +The team soon began to see the benefit of open sourcing the project for other Godot developers, especially after the Godot engine officially discontinued its own visual scripting support at the end of Godot 3. + +The plug-in is designed to fully integrate with the Godot engine, allowing developers to visually design game logic, code, behaviors, state machines, RPG-based conversations, and more using visual nodes and a graph canvas instead of text-based editors used for Godot's built-in script languages: `C#` and `GDScript`. + +Here is a very simple example of an `Orchestration`, the main visual script resource. +This script is designed to rotate an object at constant speed each frame tick: + +
+ +You can find many more examples in our GitHub examples repository. + +## How to install the plug-in? + +Orchestrator does not ship with the Godot Editor, and instead it must be installed into your Godot project as a plug-in. +For information on how to install the plug-in into a new project, please read the [Installation Guide](installation-guide). + +## How does it work and look? + +Orchestrator provides you with an entirely new workspace tab in the main editor viewport to create visual graphs for connecting nodes that represent logical actions, constructing game logic that powers your game. + +
+ +The team strives to not only provide a feature-rich experience with the power of visual scripting without its traditional drawbacks, but to do so consistently so where you don't realize you are using a plug-in rather than out of the box Godot. +Any project is also evolving, so while we believe the integration is done quite well, there is always room for improvement. + +## What language is an Orchestration? + +The Godot engine provides two core programming languages out of the box, `GDScript` and `C#`. +These two languages provide seamless, powerful scripting opportunities in the engine; however, both of these are entirely text-driven. + +Orchestrator provides a new type of programming language to Godot, to create new script resource types called `Orchestration`s. +An orchestration, offered called an `OrchestratorScript` or `OScript` for short, is a visual-scripting language where you connect visual blocks together to build games. + +Orchestrator's code base is written in C++, the most popular language used in the gaming industry. +Developers use C++ because it's highly optimized and efficient, which is critical in high-performance games. + +However, as a developer using Orchestrator, you aren't required to know C++, or really any type of language syntax. +The plug-in is designed to connect visual blocks of functionality together to create logic. +An `Orchestration` is translated automatically to machine instructions at runtime, so that the script runs at optimal speeds under the most taxing game requirements. + +And finally, the plug-in seamlessly integrates with the Godot Editor and Godot Engine thanks to the GDExtension technology, a binding provided by the Godot development team for creating high-performance plug-ins and code in C and C++, that can run inside the Godot Editor or in exported Godot games. + +## What do I need to know to use Orchestrator? + +Orchestrator is a feature packed plug-in for Godot, with thousands of features. +Its goal is to abstract away a lot of the technical noise around syntax and specific language features, enabling you to conceptualize what you need and to combine high-level behavior nodes to create game logic. + +While we try and make the plug-in accessible to the most junior of developers, having a basic understanding programming concepts can help tremendously. +As we continue to refine the plug-in and find more ways to simplifying its design, your input will help shape this effort more than anything else possible. + +In the next part, you will get an overview of the plug-ins essential concepts. \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/key_concepts.md b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/key_concepts.md new file mode 100644 index 0000000..cca04ed --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/key_concepts.md @@ -0,0 +1,103 @@ +--- +sidebar_position: 2 +--- + +# Overview of key concepts + +Orchestrator is a Godot-plugin that is based on a set of key abstractions. + +An `Orchestration` is the main resource that you will be creating and managing using the Orchestrator plug-in. +It represents a Godot `Script` object that contains one or more graphs with any number of connected nodes. + +Orchestrations also support user-defined functions, variables, and signals, much like you would see in `GDScript` or `C#` script. +Since an orchestration is considered a Godot `Script`, you can attach it to any scene node, and it will be able to interact with the engine just like Godot's text-based script options. + +There are **6** major concepts, and we're going to look at them briefly to give you a sense of how the plug-in works. + +### Scenes + +While scenes are not something specific to Orchestrator, they are the foundation to which Orchestrator stands. +It's extremely important to understand what scenes are, how they're used, and why they're important in a Godot project. + +In Godot, developers break down a game into reusable components, called *scenes*. + +A scene can literally be anything, a character, a weapon, a menu in the user interface, a single house, an entire level, and the list continues. +Godot's scene system is designed to be flexible; providing the role of both prefabs (archetypes) and scenes/levels, terms often used in other engines. + +
+ +### Nodes + +A scene is composed of one or more *nodes*. +Nodes are Godot's smallest building blocks that you arrange into tree hierarchies. + +
+ +In this example, it is made up of a `CharacterBody2D` node named "Player", a `Camera2D`, a `Sprite2D`, and a `CollisionShape2D`. +The `CharacterBody2D` or "Player", is the root of this scene. +The other nodes are children of the root scene node, which creates a set of node hierarchies in the scene tree. + +:::info +The node names end with `2D` because this is a two-dimensional scene; however 3D counterparts end with `3D`. +::: + +If you look closely at the node in the scene called "Player", there is an icon to the right. +This icon signifies that the node has a script attached. + +The visual scripts you create with Orchestrator, called `Orchestration`s, are scripts that can be attached to scene nodes. +When they are attached, the is shown in the scene view next to the node. + +### Graph workspace + +The **Graph** is the main workspace where you will spend the vast majority of your time creating orchestrations. +It is the canvas where you will place nodes, connecting them to create complex behaviors. + +
+ +To the right of the **Graph** canvas is what is called the **Component** view. +The **Component** view is where you can add, rename, and remove a variety of high-level components in an Orchestration. + +An `Orchestration` is not restricted to just a single **Graph** workspace. +You can add multiple graphs using the button at the top of the **Graph** panel in the **Component** view. + +In addition, when you add a user-defined function, these will also have their own **Graph** and will be opened in separate tabs. +In the image above, you can see several tabs for **EventGraph**, **apply_rotation**, and others. +This technique allows for optimal organization in visual scripts, preventing clutter and *spaghetti* code. + +The **Component** view also allows for creating **Variables** and **Signals**. + +### Signals + +All Godot objects can emit signals, a notification to an observer when a specific event occurs. + +:::info +Signals are Godot's version of the *observer* pattern. +::: + +Signals allow you to communicate with other parts of the game without creating a hard dependency between two parts of the code. +This allows for a significant amount of flexibility when building scenes, and how you can construct orchestrations. + +To add a signal to the `Orchestration`, use the **Component** view and click the icon in the **Signals** panel header. + +Observers can be connected to signals either through code or using the Editor's interface. +The way to connect a signal to an `Orchestration` is using the Editor's interface. + +
+ +Locate the **Node** view, this is in the same dock where you will find the **Inspector** and **History** tab views. +In the **Node** view, there are two distinct subsections, _Signals_ and _Groups_. +Make sure that the _Signals_ section is highlighted, as shown above. + +In this view, signals are represented with the icon next to its name. +If a signal has any connections, there will be child items listed under the signal, denoted with the icon. + +For example, the above image shows that the function `_on_area_2d_body_entered()` will be called when the `body_entered` signal is emitted. +This is an example of creating an `Area2D`, a 2D area trigger, and notifying some observer that an object has entered the trigger's area. + +### Variables + +A **Variable** represents a named value that can be assigned a value or its value read in the visual script. +Variables are useful for passing data between different parts of the script, and for maintaining state that is managed by the `Orchestration`. + +To add a new variable, use the **Component** view and click the icon in the **Variables** panel header. + diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/learning-new-features.md b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/learning-new-features.md new file mode 100644 index 0000000..4c96fc3 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/learning-new-features.md @@ -0,0 +1,46 @@ +--- +sidebar_position: 5 +--- + +# Learning new features + +Orchestrator a tremendously feature-rich plug-in, directly driven by Godot's extensive library of features. +There is most certainly a lot to learn. +This page explains how you can use the online documentation, built-in code reference, and other tools to learn new features and techniques. + +## Making the most of the manual + +What you are reading now is called the user manual. +It documents the plug-in's concepts and features. +When learning a new topic, you can start by browsing the corresponding section of this website. +The left menu allows you to explore broad topics, while the right menu provides more targeted topics within the current page. + +The user manual has a companion [Script Node Reference](../../nodes/all_nodes) that explains each Orchestrator script node, their properties, how to use them, and their purpose. +While the manual covers general features, concepts, and how to use the plug-in, the reference is focused on using the Orchestrator Node API. + +:::tip +At this time, the [Script Node Reference](../../nodes/all_nodes) is only available online. +::: + +## Thinking like a programmer + +Teaching programming foundations and how to think like a game designer is beyond the scope of this documentation. +If you are new to programming, we recommend this free online course to get started: + +- Harvard University offers free courses to learn to program, CS50. +It teaches programming fundamentals and how to think like a programmer. +Even when using visual tools, having this basic knowledge can easily improve your efficiency at making games. + +## Learn with the community + +Orchestrator has a growing community of users. +If you are stuck on a program or need help to understand how to achieve something, you can ask other users for help in our Discord. + +The best place to ask questions and find already answered ones is on our official discord. + +## Tutorials and examples + +This manual aims to provide a comprehensive reference to Orchestrator's features. +Aside from the 2D and 3D getting started series, it does not contain tutorials to implement specific game genres or features. +If you are looking for a tutorial about creating a role-playing game, platformer, or other, please see our [Tutorials and resources](../../community/tutorials-and-resources), which lists examples and content made not only by the plug-in authors, but the Orchestrator community. + diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/orchestrator-design-philosophy.md b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/orchestrator-design-philosophy.md new file mode 100644 index 0000000..aa2f58b --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/introduction/orchestrator-design-philosophy.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 6 +--- + +# Orchestrator's design philosophy + +Now that you've gotten your feet wet, let's talk about Orchestrator's design. + +:::important +Every visual scripting engine is different and fits different needs. +::: + +Not only do various visual scripting systems offer a range of features, how those features are designed and interact with the underlying game engine is also unique. +Orchestrator attempts to take some of the best practices and concepts from other visual scripting engines, and incorporates those into a plug-in that works well for Godot. + +## All-inclusive + +Orchestrator aims to provide answers to most questions. +We want game developers to be able to use full, visual tools to build game logic rather than having to rely on traditional text-based scripts. + +We acknowledge that visual scripting is not for everyone, and we expect that respect to be reciprocated. +It's equally important to understand that there are those who simply struggle to learn text-based languages, and can thrive using visual tools. + +Our mission and prime directive is to provide state-of-the-art tooling, and let you decide if it fits your needs. + +Games do not have to be made solely with or without one scripting technology like Orchestrator. +You can safely mix-n-match, using Orchestrator for certain game aspects and combine GDScript or C# for others. + +## Open source + +Orchestrator is a fully, open-source code base under the **Apache License 2.0**. +Anyone can freely use Orchestrator in any type of project, public, commercial, and proprietary as long as you comply with the license requirements. + +See the [Complying with licenses](../../about/complying-with-licenses) section for details. + +## Community-driven + +**Orchestrator is made by its community, for the community, and for all game creators**. +The needs of users and open discussions are what drive the core updates we make to the plug-in. +New features from the core developers often focus on what will benefit most users first, and foremost. \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/step-by-step/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/step-by-step/index.md new file mode 100644 index 0000000..0bfdc94 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/getting-started/step-by-step/index.md @@ -0,0 +1,672 @@ +--- +sidebar_position: 2 +toc_max_heading_level: 4 +--- + +# Step by step + +This series builds upon the [Introduction to Orchestrator](../introduction) and will get you started using the plug-in. +If you have not yet reviewed the [Godot Step-by-Step Guide](https://docs.godotengine.org/en/stable/getting_started/step_by_step/), we **strongly recommend** doing so before proceeding. + +* [Creating your first orchestration](#creating-your-first-orchestration) +* [Listening for player input](#listening-for-player-input) + +## Creating your first orchestration {#creating-your-first-orchestration} + +In this lesson, you will code your first `Orchestration` to make the Godot icon turn in circles using Orchestrator. +As we mentioned [in the introduction](../introduction), we assume you have read all the prerequisites. + +
+ +### Project setup + +Please create a new project to start with a clean slate. +Your project should contain one picture: the Godot icon, which we often use for prototyping in the community. + +#### Install the plug-in + +Before we can proceed, we need to install the Orchestrator plug-in. +The plug-in can be installed from the Godot Asset Library or manually by downloading from our GitHub repository. + +See the [Installation Guide](../introduction/installation-guide) on how to install the plug-in. + +#### Creating the scene + +We need to create a `Sprite2D` node to display the Godot icon in our game. +In the **Scene** view, click the **Other Node** button. + +
+ +Type "Sprite2D" into the search box to filter the nodes, double-clicking on `Sprite2D` to create the node. + +
+ +Once the Sprite2D node is added, your **Scene** view should now look like this: + +
+ +A `Sprite2D` node requires a texture to display. + +In the **Inspector** view on the right, the **Texture** property shows that it is *empty*. +To display the Godot icon, drag the file `icon.svg` from the **FileSystem** view onto the `Texture` property in the **Inspector** view. + +
+ +:::important +You can create `Sprite2D` nodes automatically by dragging and dropping images onto the viewport. +::: + +Lastly, click and drag the icon in the viewport to center it in the game view. + +
+ +### Creating a new orchestration + +To create and attach a new `Orchestration` to our node, right-click on the `Sprite2D` in the **Scene** view and select ** Attach Script**. + +
+ +The **Attach Node Script** dialog will appear. +This dialog allows you to select the script's language, the file path, and other options. +Make sure the language is set to `Orchestrator`, leaving all the other options as their defaults. + +Click the **Create** button to create the script. + +
+ +The Orchestrator ** EventGraph** workspace should appear with your `sprite_2d.os` orchestration open. + +
+ +### Hello world! + +Our `Orchestration` script currently doesn't do anything. + +Let's make it print the text "Hello, world!" to the output bottom panel to get started. + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for `Print String`, and select the `Print String` action. +3. To add the node, either press the **Add** button or simply hit **Enter**. +4. Change the value of the `Text` parameter to `Hello, world!`. + +Lastly, we need to add a Godot event callback so that our **Print String** node outputs the value. + +1. Press the button located at the top right of the **Functions** panel. +2. Search or the `Call Init` action. +3. To add the node, either press the **Add** button or simply hit **Enter**. + +With the two nodes in the **Graph**, using your mouse: + +1. Left-mouse click the white *output* arrow on the right side of the **Call Init** node. +2. Drag from this output pin to the *input* arrow on the left side of the **Print String** node. + +If done successfully, the two nodes should be connected. + +:::note +The **Init Event** is a special callback that represents the `_init()` function in GDScript, which acts like a constructor. +The Godot Engine calls this `_init()` on every object or node when it gets created, as long as this function is defined. +::: + +Now, save the scene as `script_2d.tscn` if you have not already, then press `F6` (`Cmd+R` on MacOS), to run it. +Look at the **Output** panel in the editor, it should display "Hello, world!". + +
+ +Lastly, we need to remove this "Hello, world" logic, so: + +1. Click on the **Print String** node, and right-click, selecting the **Delete** option to remove the node. +2. Click on the **_init** entry in the **Graphs** section of the **Component Panel**. +3. Right-click and select the **Remove** option from the context-menu. + +You should end up with an empty canvas. + +### Turning around + +It's time to make our node move and rotate. +To do so, we're going to add two member variables to our Orchestration: + +* The movement speed in pixels per second +* The angular speed in radians per second + +
+ +#### Add movement speed + +To define the movement speed variable: + +1. Click the button to add a new variable in the **Variables** component section. +2. Give the variable the name `speed`, and press enter. +3. Select the variable in the **Component** view to have the **Inspector** display the variable's details. +4. In the **Inspector**, change the `Type` to an `Integer` and assign a default value of `400`. + +#### Add angular speed {#add-angular-speed} + +To define the angular speed variable: + +1. Click the button to add a new variable in the **Variables** component section. +2. Give the variable the name `angular_speed`, and press enter. +3. Select the variable in the **Component** view to have the **Inspector** display the variable's details. +4. In the **Inspector**, change the `Type` to an `Float` and assign a default value of `3.14`. + +:::important +Angles in Godot work in radians by default, but you have built-in functions available if you prefer to work with degrees. +::: + +#### Apply rotation + +To move our icon, we need to update its position and rotation every frame in the game loop. + +We can use the **Process Event**, a Godot virtual override function, to do this. +If your orchestration extends a class that extends the `Node` class, like `Sprite2D`, this function will be called every frame and provide an argument called `delta`, which is the elapsed time since the last frame in `seconds`. + +:::important +Games work by rendering many images per second, each called a frame, and they perform this in a loop. +We measure the rate at which a game produces these images in Frames Per Second (FPS). +Most games aim for 60 FPS, although you might find values lower or higher. +::: + +We are going to add the **Process Event** node much like we did the **Init Event** node. + +1. Press the button on the top-right of the **Functions** panel. +2. In the **All Actions** dialog, locate the `Call Process Event` node. +3. To add the node, either press **Add** or simply hit **Enter**. + +With the **Process Event** node on the graph, we need to connect logic to this node to perform this computation, but visually: + +```python +rotation += angular_speed * delta +``` + +The above line increment's the sprite's rotation every frame. +Here `rotation` is a property inherited from the `Node2D` class, which `Sprite2D` extends. +This means that we can work directly with the `rotation` property in the orchestration. + +To do this visually, we need to add several more nodes to our graph: + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for `Get Rotation`. +3. Select the `Get Rotation` choice and either press **Add** or simply hit **Enter**. +4. Right-click the graph again to open the **All Actions** dialog. +5. Search for `Set Rotation`. +6. Select the `Set Rotation` choice and either press **Add** or simply hit **Enter**. +7. Right-click the graph area once more to open the **All Actions** dialog. +8. Search for `Multiply`. +9. Select the "Multiply (Float)" choice that is under the **Float** category. +10. Either press **Add** or simply hit **Enter**. + +Finally, match all the nodes as shown here. +This visually represents the `rotation += angular_speed * delta` logic. + +
+ +Run the scene in the editor to see the icon turn in-place. + +
+ +#### Apply movement + +Let's now make the node move. +In order to do this, we need to add one additional step inside the **Process Event** node logic. + +```python +var velocity = Vector2.UP.rotated(rotation) * speed +position += velocity * delta +``` + +In this code, we are using a variable named `velocity` to represent the direction and speed. +To make the node move forward, we start from `Vector2.UP`, a vector that simply points up, and we rotate it by calling the Vector2 method `rotated()`. +This expression, `Vector2.UP.rotated(rotation)`, is a vector that points forward relative to our icon. +By multiply this by our `speed` property, it gives us a velocity that we can use to move the node. +And finally we multiply this `velocity` with the `delta` time, and add that the node's current position for it to move per frame. + +To set this up visually, we need to: + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for `Type Constant` +3. Select the **Type Constant** node and set the type as `Vector2` and the constant as `UP` in the **Inspector**. +4. Right-click the graph to open the *All Actions** dialog. +5. Search for `Rotated`, selection the choice under the **Vector2** category. +6. Next add three math operator nodes + * Multiply `Vector2` by `Integer`. + * Multiply `Vector2` by `Float`. + * Multiply `Vector2` by `Vector2`. +7. Finally add two function call nodes + * Search for `Get Position` + * Search for `Set Position` + +With the nodes, we connect them as shown here: + +
+ +Run the scene to see the Godot head run in circles. + +
+ +:::note +Moving nodes like this does not take into account collisions with other objects. +In a future tutorial, you will learn another approach to moving and detecing collisions. +::: + +### Complete script + +Here is what the complete `sprite_2d.os` orchestration script looks like for reference. + +
+ +## Refactor and use functions + +A common task in programming is to polish code so that it's easier to digest and understand. +One of the common complaints of visual scripting is that it's a massive web of connections, and what we've done already is shaping up to be just that. +Thankfully, Orchestrator provides multiple tools to help with this, and the first is to use user-defined functions. + +### Moving apply rotation to a function + +The first task we're going to focus on is moving the **Apply Rotation** logic to a user-defined function called `apply_rotation`. +This user-defined function will accept the `delta` time in seconds. + +To create the user-defined function: + +1. Press the button on the top-right of the **Functions** panel in the **Component** view. +2. When prompted for a function name, enter `apply_rotation` and press **Enter**. +3. In the **Inspector** view, adjust the function properties by setting the following properties: + * Set the `Argument Count` to a value of `1`. + * Adjust the **new** argument's type as `Float` and the name as `delta`. + +The **Function Entry** node should now look like this in the graph: + +
+ +You will have noticed that a new tab has been created at the top of the graph workspace called `apply_rotation()`. +One of the benefits with Orchestrator is that all user-defined functions are organized into their own graph. +This helps to declutter large graphs, and serves as a really neat way to organize your code.s + +Now, you may wonder how do we get the nodes we created in the **EventGraph** into this user-defined graph. +Orchestrator supports bulk operations, so we're going to use **Cut** and **Paste** to move that logic. +So at the top of the graph workspace, click the **EventGraph** tab to go back to the main **Graph**. + +Left-click anywhere on the graph canvas and select the nodes that are specific to the rotation logic. +The following shows the nodes you should be selecting in case you may have forgotten, they're highlighted with a **yellow** border: + +
+ +:::tip +You can also hold the `Ctrl` key and left click each node separately to select multiple nodes. +::: + +Now to move these nodes to the user-defined function, we're going to first **Copy** them rather than use **Cut**: + +1. Press the `Ctrl+C` shortcut to copy the selected nodes into the selection buffer. +2. In the **Component** view, double-click the `apply_rotation` function or click the `apply_rotation()` tab. +3. In the `apply_rotation` graph, press `Ctrl+V` to paste the selected nodes onto the graph. + +:::note +The nodes may have been pasted near the center of the graph. +You can click the **Toggle the graph minimap** at the top of the graph to quickly find them. +Simply drag the selected nodes or the **Function Entry** node together. +::: + +The next step here is to wire up the **Function Entry** node and the nodes that you just added. + +1. Connect the `delta` output pin to the `A` input pin of the multiplication node. +2. Connect the output execution pin from the **Function Entry** node to the input execution pin of the **Call Set Rotation** node. + +The user-defined function, `apply_rotation()` should look like this: + +
+ +The last step is to replace the logic in the **EventGraph** with our new function, `apply_rotation`. +Click on the **EventGraph** in the **Graphs** section of the **Component** view or select the **EventGraph** tab. + +1. Right select all the currently selected nodes. +2. Press the `Del` key to remove the nodes from the graph. +3. Drag the `apply_function` from the **Component** view onto the graph. +4. Connect the output execution pin from **Process Event** node to the input execution pin of **Call Apply Rotation** node. +5. Connect the output `delta` pin from the **Process Event** node to the input `delta` pin of **Call Apply Rotation** node. +6. Connect the output execution pin from **Call Apply Rotation** to the **Call Rotated** node. +7. Open the **All Actions** dialog, search for `Get Rotation` and add it to the graph. +8. Lastly connect the output in from **Call Get Rotation** node to the `angle` pin of the **Call Rotated** node. + +Your **EventGraph** should now look like this: + +
+ +### Moving apply movement to a function + +Now that we have moved the logic for rotation to a user-defined function, the next step is to do the same for **Apply Movement**. + +1. Press the button on the top-right of the **Functions** panel in the **Component** view. +2. When prompted for a function name, enter `apply_movement` and press **Enter**. +3. In the **Inspector** view, adjust the function properties by setting the following properties: + * Set the `Argument Count` to a value of `1`. + * Adjust the **new** argument's type as `Float` and the name as `delta`. + +The **Function Entry** node should look like this in the graph: + +
+ +Now again, we're going to select and **Copy** the nodes from the **EventGraph** into our new `apply_movement` user-defined function. + +1. Navigate back to the **EventGraph**. +2. Select **ALL** nodes except the **Process Event** and **Call Apply Rotation** nodes. +3. Press `Ctrl+C` to copy the nodes into the buffer. +4. Navigate back to the **Apply Movement** graph. +5. Press `Ctrl+V` to paste the nodes onto the graph. + +With the nodes pasted, you need to wire up the **Function Entry** node with the other nodes. + +1. Connect the output execution pin from the **Function Entry** node to the input execution pin of the **Call Rotated** node. +2. Connect the `delta` output pin from the **Function Entry** node to the `B` input pin that isn't connected.
+This will be the `B` input pin on the **Multiplication** node between a `Vector2` and a `Float`. + +The user-defined function graph should look like this: + +
+ +The last step is to replace the selected nodes in the **EventGraph** with the call to the new user-defined function that handles applying movement, `apply_movement`. + +1. Delete all nodes in the **EventGraph** except the **Process Event** and **Call Apply Rotation** nodes. +2. Drag the `apply_movement` function from the **Component** view onto the graph. +3. Connect the **Call Apply Function** output execution pin to the **Call Apply Movement** input execution pin. +4. Connect the **Process Event** `delta` output pin to the **Call Apply Movement** `delta` input pin. + +The new refactored **EventGraph** should now look like this: + +
+ +By refactoring the logic from the **EventGraph** into two distinct **Function** graphs, this makes the graphs more readable. + +:::tip +Any user-defined function can be focused by double-clicking the **Call Function** node. +For example, double-clicking the **Call Apply Rotation** node will open the `apply_rotation` function graph, and focus the function's **Function Entry** node. +::: + +## Listening for player input {#listening-for-player-input} + +Building upon the steps from [Creating your first orchestration](#creating-your-first-orchestration) and [Reactor and use functions](#refactor-and-use-functions), let's look at another important feature of any game: giving control to the player. +To add this, we need to modify our `sprite_2d.os` orchestration. + +
+ +You have two main tools to process player input in Godot using Orchestrator: + +* Using the built-in event callbacks, mainly **Unhandled Input Event**. +Like **Process Event**, it's a built-in function call that Godot will call every time the player presses a key. +It's the tool you want to use to react to events that don't happen each frame, like pressing `Space` to jump. +* Using the **Engine Singleton** node to access the `Input` singleton. +A singleton is a globally accessible object. +Godot provides access to several of these, and they're available in Orchestrator. +It's generally the right tool for checking for input every frame. + +We are going to use the `Input` singleton here as we need to know if the player wants to turn or move each frame. + +### Turning + +For turning, we should use a new variable: `direction`. +In the **Component** panel, we're also going to create a new user-defined function to calculate the direction. + +#### Calculating the direction + +To add the new function, follow these steps: + +1. Press the on the **Functions** panel in the **Component** view. +2. Set the new function name as `calculate_direction`. + +In this function, what we ultimately want to accomplish is this logic: + +```python title="GDScript" +func calculate_direction(): + var direction = 0 + if Input.is_action_pressed("ui_left"): + direction = -1 + if Input.is_action_pressed("ui_right"): + direction = 1 + return direction +``` + +Since this function will return an `Integer` value, we need to add a **Function Result** node to the graph. + +1. Click on the **Function Entry** node if it isn't already selected. +2. In the **Inspector** view, enable the `Has Return Value` property.
+ If this is not enabled, you cannot add a **Function Result** node to the graph. +3. In the **Inspector** view, set the `Return Type` to `Integer`. +4. Now, right-click on the graph to open the **All Actions** dialog. +5. Search for `Add Return` +6. Select the `Add Return Node` and press the **Add** button or simply press **Enter**. + +The `calculate_direction` graph should look like this: + +
+ +Our `direction` variable is a multiplier representing the direction in which the player wants to turn. +A value of `0` means the player isn't pressing the left nor the right arrow key. +A value of `1` means the player wants to turn right, while a value of `-1` means they want to turn left. + +In Orchestrator, to check whether an action is pressed, we need to use the **Input Action** node. +This node allows you to check whether a specific action mapping is _pressed_, _released_, _just pressed_, or _just released_. + +1. Right-click on the graph to open the **All Actions** dialog. +2. Search for `Input Action`. +3. Select the `Input Action` choice and press the **Add** button or simply press **Enter**. + +We need two of these nodes, one to check `ui_left` and another to check `ui_right`. +We can duplicate an existing node by using the `Ctrl+D` shortcut. + +To duplicate the **Input Action** node: + +1. Select the **Input Action** node, if it isn't already selected. +2. Press the `Ctrl+D` shortcut or right-click and select the **Duplicate** option. + +You should now have two **Input Action** nodes, as shown here: + +
+ +With these two nodes, you need to configure each of them to check for the desired state: + +1. Select one **Input Action** node. +2. In the **Inspector** panel, set the `Action` to `ui_left`. +3. Select the other **Input Action** node. +4. In the **Inspector** panel, se the `Action` to `ui_right`. + +These two nodes should now look like this: + +
+ +Next, to apply the two `if` conditions, we need use two **Branch** nodes. + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for `Branch`. +3. Select the `Branch` option and press **Add** or simply hit **Enter**. +4. Select the **Branch Node** and duplicate it, so that you have two **Branch** nodes. + +The next thing we need before we can wire up these nodes is a variable to represent the `direction` value. +In this case, define a variable named `direction` using the type `Integer` like had previously defined for `speed`. +For `direction`, leave its default value unchanged, as it will default to `0`. +If you need a reminder of how to do that, see the [Add angular speed](#add-angular-speed) section. + +With the `direction` variable setup, drag the `direction` variable from the **Component** panel onto the graph **3** times. +Each time, making sure to select that you want to create a **Get direction** node. + +Now one of the cleanest ways to represent a sequence of operations, like checking two `if` (**Branch**) conditions followed by some logic that will run based on the prior stages is to use a **Sequence** node. +In our case, we're going to create a **Sequence** node that will have **4** output execution pins, one to initialize our `direction` variable, two to handle the two `if` checks, and lastly one to handle the incrementing of the `rotation`. + +1. Right-click the graph and open the **All Actions** dialog. +2. Search for `Sequence`. +3. Select the `Sequence` option and press **Add** or simply press **Enter**. +4. In the **Sequence** node, press the button so that there are **4** output execution pins. +5. Connect the `Then 0` output execution pin to one of the **Set direction** nodes. +6. In that **Set direction** node, make sure that the `direction` value is `0` (the default). + +Now, lets wire up the nodes. + +1. Starting with the **Sequence** node, connect the `Then 1` output pin to one of the **Branch** nodes. +2. Connect the **Action ui_left** node's output pin to the `Condition` input pin of that **Branch** node. +3. Connect the **Branch** node's `True` output execution pin to one of the **Set direction** nodes. +4. Set the `direction` input value to `-1` on the **Set direction** node. + +At this point, we've taken care of setting up the first `if` condition for `Input.is_action_pressed("ui_left")`. +Now, we need to repeat this process for the other `if` condition. + +1. Starting with the **Sequence** node, connect the `Then 2` output pin to the **Branch** node that isn't connected. +2. Connect the **Action ui_right** node's output pin to the `Condition` input pin of that **Branch** node. +3. Connect the **Branch** node's `True` output execution pin to the **Set direction** node that isn't connected. +4. Set the `direction` input value to `1` on the **Set direction** node. + +With this, your graph should look similar to this: + +
+ +Now, you need to wire the **Function Entry** and **Function Result** nodes with this, returning the `direction`. + +1. Connect the **Function Entry** output execution pin to the input execution pin of the **Sequence** node. +2. Drag the `direction` variable from the **Component** view, and spawn a **Get direction** node. +3. Connect the `Then 3` output pin from the **Sequence** node to the input execution pin of the **Function Result** node. +4. Finally, connect the **Get direction** node's data output to the input `Return Value` pin of the **Function Result** node. + +The graph for `calculate_direction()` should look like this: + +
+ +#### Using the direction calculation + +The last step is to use the the `calculate_direction` function inside our `apply_rotation` function. + +1. Navigate to the `apply_rotation` function. +2. Drag the `calculate_direction` function onto the graph from the **Component** view. +3. Select the **Multiplication** node that multiplies two `Float` values and press `Ctrl+D` to duplicate. +4. Connect the **Apply Rotation** entry node output pin to the input execution pin of the **Call Calculate Direction** node. +5. Connect the `delta` output pin on **Apply Rotation** to the `B` input of the duplicated node. +6. Connect the `Return value` output pin on the **Call Calculate Direction** to the `A` input of the duplicated node. +7. Connect the duplicated node's output pin to the unconnected **Multiplication** node `A` pin. +8. Lastly connect the **Call Calculate Direction** output execution pin to the **Call Set Rotation** input execution pin. + +The final graph should look like this: + +
+ +If you run the scene, the icon should rotate when pressing the `Left` and `Right` arrow keys. + +:::tip +If you don't press either of the arrow keys, it will simply move forward, and off the screen.
+So be sure to constantly press the `Left` or `Right` arrows to keep in on the screen. +::: + +### Moving forward + +Now, as nice as this simple game is at this point, we'd like to have better control of our Godot icon. + +In this section, we're going to adjust how `apply_movement` works, and only have the icon move when the player presses the `Up` arrow key. +This will make the icon easier to control and keep on on the screen. + +#### Calculating the velocity + +If you recall when we originally designed the `apply_movement` function, we used the following to calculate the `velocity`. + +```python title="GDScript" +var velocity = Vector2.UP.rotated(rotation) * speed +``` + +Now instead, we want to conditionalize this, having the `velocity` set to `Vector2.ZERO`, and only applying the calculation if the player has pressed the `Up` arrow key. + +```python title="GDScript" +var velocity = Vector2.ZERO +if Input.is_action_pressed("ui_up"): + velocity = Vector2.UP.rotated(rotation) * speed +``` + +We're going to accomplish this by introducing a new function called `calculate_velocity`. + +1. Press the button at the top of the **Functions** panel in the **Component** view. +2. When asked for a function name, enter `calculate_velocity`. + +In this function, we either want to return `Vector2.ZERO` if the player has not pressed the `Up` arrow key, or return the velocity based on the current `rotation` and `speed` values. +The first step we need to is to add the **Function Return** node, returning a `Vector2` value. + +1. Select the **Function Entry** node. +2. In the **Inspector** view, enable the `Has Return Value`. +3. In the **Inspector** view, set the `Return Type` as `Vector2`. +4. In the graph, right-click to open the **All Actions** dialog. +5. Search for `Add Return`. +6. Select the `Add Return Node` option and press the **Add** button or simply hit **Enter**. + +Now to simplify things, navigate back to the `apply_movement` graph and select these nodes. +The nodes to select are highlighted with a **yellow** border: + +
+ +1. Press the `Ctrl+C` shortcut to copy the nodes into the copy buffer. +2. Navigate back to the `calculate_velocity` function. +3. Press the `Ctrl+V` shortcut to paste the nodes onto the graph. + +With these nodes in the `calculate_velocity` function, you are going to use a similar technique that was used for `direction`, relying on a **Sequence** node to: + +- Initialize the `velocity` value to `Vector2.ZERO` +- Check whether the `ui_up` action is pressed, and only modifying the `velocity` if `true`. +- Return the calculated `velocity` value. + +Before we add nodes, you need to create a `velocity` variable. +This variable should be of type `Vector2`, and its default value left unchanged. +If you don't remember the steps, you can refer to the [Add angular speed](#add-angular-speed) section once more. + +With the `velocity` variable added, perform these steps: + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for `Sequence`. +3. Select the `Sequence` option and press the **Add** button or simply hit **Enter**. +4. Connect the output execution pin from the **Calculate Velocity** node to the input execution pin of the **Sequence** node. +5. Drag the `velocity` variable from the **Component** panel onto the graph. +6. Connect the `Then 0` output pin on the **Sequence** node to the input execution pin on the **Set Velocity** node. +7. Open the **All Actions** dialog, and add a **Branch** node to the graph. +8. Connect the `Then 1` output execution pin to the input execution pin of the **Branch** node. +9. Open the **All Actions** dialog, and add an **Input Action** node to the graph. +10. Select the **Input Action** node. +10. In the **Inspector** view, change the `Action` property to be `ui_up`. +11. Connect the **Input Action** output pin with the input `Condition` pin on the **Branch** node. +12. Connect the `True` output pin from the **Branch** node to the input execution pin on the **Call Rotated** node. +13. Select the `velocity` variable in the **Component** panel and drag onto the graph, selecting **Set velocity**. +14. Connect the output execution pin from **Call Rotated** to the input execution pin of **Set Velocity. +15. Connect the output pin from the **Multiplication** (A*B) node to the input pin of **Set Velocity**. +16. Drag the `velocity` variable from the **Component** panel and select **Get velocity**. +17. Connect the `Then 2` output execution pin to the **Return Node** input execution pin. +18. Finally, connect the **Get velocity** output pin to the **Return Node** input `Return Value` pin. + +At the end, your graph for `calculate_velocity` should look like this: + +
+ +#### Using the velocity calculation + +With the `calculate_velocity` function done, we need to use this in the `apply_movement` function. +Navigate back to the `apply_movement` function and perform these steps: + +1. Remove the node that you copied to the `calculate_velocity` function.
In case you forgot, they're the ones shown here with a **yellow** border: +
+2. Drag the `caculate_velocity` function from the **Component** view onto the graph. +3. Connect the output execution pin from **Apply Movement** to the input pin on **Call Calculate Velocity** node. +4. Connect the output execution pin from **Call Calculate Velocity** to the input execution pin on **Call Set Position** node. +5. Finally, connect the `Return Value` output pin on **Call Calculate Velocity** node to the input `A` pin on the **Multiplication** node that's currently unconnected. + +The new simplified `apply_movement` function should look like this: + +
+ +If you now run the scene, you'll notice the following happens: + +* The Godot icon does not move unless you press the `Left`, `Right`, or `Up` arrow keys. +* The `Left` arrow key rotates the icon to the left. +* The `Right` arrow key rotates the icon to the right. +* The `Up` arrow key makes the icon move forward in its current facing direction. + +
+ +## Summary + +In summary, every script in Godot represents a class that extends one of the engine's built-in classes. +The node types your classes inherit from give you access to properties, such as `rotation` and `position` in our sprite's case. +You also inherit many functions, which we didn't use in this example. + +In an Orchestration, using variables is an excellent way to store and manage state. +Additionally, user-defined functions are a great way to organize smaller pieces of code to reduce the complexity of large visual script graphs. + +And who would believe, in the end, all this was possible using three nodes in a graph: + +
\ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/_category_.json b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/_category_.json new file mode 100644 index 0000000..956bad3 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Script Node Reference", + "position": 6 +} \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/all_nodes.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/all_nodes.md new file mode 100644 index 0000000..e571410 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/all_nodes.md @@ -0,0 +1,55 @@ + +# All nodes + +All Orchestrator visual script nodes are based on the `ScriptNode` class. +The following hierarchy represents all the node types available that can be added to an `Orchestration` script. + +* Script Node + * [Autoloads](autoloads) + * [Comments](comments) + * [Constants](constants) + * [Class-specific constants](constants#class-specific-constants) + * [Global constants](constants#global-constants) + * [Math-specific constants](constants#math-specific-constants) + * [Singleton-specific constants](constants#singleton-specific-constants) + * [Type-specific constants](constants#type-specific-constants) + * [Dialogue](dialogue) + * [Choice](dialogue#dialogue-choice-node) + * [Show Message](dialogue#show-message-node) + * [Events](events) + * [Flow Control](flow-control) + * [Branch](flow-control.md#branch) + * [Chance](flow-control.md#chance) + * [Delay](flow-control.md#delay) + * [For loop](flow-control#for-loop) + * [For each](flow-control#for-each-loop) + * [Random](flow-control#random) + * [Select](flow-control#select) + * [Sequence](flow-control#sequence) + * [Switch](flow-control#switch-nodes) + * [Type Cast](flow-control#type-cast) + * [While](flow-control#while) + * [Functions](functions) + * [Input](input) + * [Math](math) + * [Memory](memory) + * [New / Create Objects](memory#creating-objects) + * [Free / Destroy Objects](memory#freeing-objects) + * [Properties](properties) + * [Get Property](properties#get-property) + * [Set Property](properties#set-property) + * [Resources](resources) + * [Get Resource Path](resources#resource-paths) + * [Preload Resource](resources#preload-resources) + * [Scene](scene) + * [Get Scene Node](scene#scene-nodes) + * [Get Scene Tree](scene#scene-tree) + * [Instantiate Scene](scene#instantiating-scenes) + * [Signals](signals) + * [Await Signal](signals#await-a-signal) + * [Emit Signal](signals#emit-a-signal) + * [Singletons](singletons) + * [Variables](variables) + * [Get Variable](variables#get-nodes) + * [Set Variable](variables#set-nodes) + \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/autoloads.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/autoloads.md new file mode 100644 index 0000000..c4bd798 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/autoloads.md @@ -0,0 +1,79 @@ + +# Autoloads + +## Godot's autoload concepts + +Godot's scene system, while powerful and flexible, has a drawback: there is no method for storing information (e.g. a player's score or inventory) that is needed by more than one scene. + +It's possible to address this with some workarounds, but they come with their own limitations: + +* You can use a "master" scene that loads and unloads other scenes as children. +However, this means you can no longer run those scenes individually and expect them to work correctly. +* Information can be stored to disk in `user://` and then loaded by other scenes that require it, but frequently saving and loading data is cumbersome and inefficient. + +The Singleton pattern is a useful tool for solving this common use case. +In Godot's case, it's possible to reuse the same scene or class for multiple singletons, as long as they have different names. + +Using this concept, you can create objects that: + +* Are always loaded, no matter which scene is currently running. +* Can store global state such as player data. +* Can handle switching scenes and in-between scene transitions. +* *Act* like a singleton, since Orchestrator and GDScript neither support global variables by design. + +Godot uses a concept called **Autoloads** to achieve these characteristics. +You can read more about Godot's implementation in the Godot documentation. + +## Registering autoloads {#registering-autoloads} + +Before you can use an **Autoload** in Godot, it must first be registered. +To register an autoload: + +1. Open `Project > Project Settings > Autoloads` dialog. +2. Select the path to the Orchestration, GDScript, or C# script. +3. Assign a unique `Node Name` for the autoload. +4. Press the `+ Add` button to register the autoload. + +## Accessing autoloads in orchestrations + +Accessing an autoload in an Orchestration requires using the **Get Autoload** node. +The **Get Autoload** node returns a reference to the specific Autoload as its *output* pin. + +
+ +In the above example, the **Autoload Node** returns a reference to the **GameData** autoload. + +There are two ways to add an **Autoload** node: + +1. Selecting the registered autoload from the `Project > Autoloads` **All Actions** category list. +
+ :::note + This choice is only permitted when right-clicking the graph; it will not be shown when dragging from an input/output pin. + ::: + +2. Adding a generic **Get Autoload** node to the graph. + +To add a generic **Autoload** node: + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for `autoload`. +3. Select the **Get Autoload** choice and press the **Add** button or simply press **Enter**. + +## Changing the autoload reference + +If the project has only defined a single autoload, the **Get Autoload** node will default to that autoload. +If you have defined multiple autoloads in your project, you may need to change the autoload reference. + +To change the autoload reference: + +1. Select the **Get Autoload** node. +2. In the **Inspector** view, change the `Autoload` property. + +## Orchestrations as autoloads + +An orchestration can also be used as an *Autoload*, just like `.gd` and `.cs` scripts. +To use an `Orchestration` as an **Autoload**, follow the [Registering autoloads](#registering-autoloads) procedure, and select the `Orchestration` rather than a GDScript (`.gd`) or C# (`.cs`) script files. + +:::tip +When adding or removing an autoload from `Project > Project Settings` autoload tab, the **All Actions** choices will automatically update to reflect the changes. +::: \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/comments.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/comments.md new file mode 100644 index 0000000..0995524 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/comments.md @@ -0,0 +1,43 @@ + +# Comments + +
+ +Multiple **Comment Nodes** can be added to a visual script graph. +These can be used for organizational purposes to make the **Graphs** more readable, but they can also be used for informational purposes as they allow for text-based descriptions to be added just like adding comments in code. + +## Creating comment nodes + +Creating comment nodes requires a few short steps: + +1. **Right-click** and choose `Add Comment` from the all actions window. +
+2. Selecting the node will display several configurable properties in the editor Inspector, including the ability to customize the titlebar text, the titlebar alignment, the node's background color along with the font size, color, and text. +
+3. The comment node can be resized by dragging the lower right corner. +Note that if you want to move the comment box and any nodes that it contains, double-clicking the comment node's titlebar will toggle between selecting and unselecting all nodes within the comment box's boundary. +This serves as a useful way to rearrange groups of nodes that are related. + +## Editing comment node properties + +All comment node properties are maintained in the **Inspector** view. +See the [Properties](#properties) section for details on what node properties can be customized. + +## Deleting comment nodes + +Clicking on any comment node and pressing the **Delete** key, or **Right-Click** and selecting **Delete** from the pop-up menu will remove the comment node from the graph. +Removing a comment node will have no impact on the nodes that it contains, as long as the nodes contained are unselected when the comment node is deleted. + +## Properties {#properties} + +Comment nodes have a number of properties that can be adjusted in the **Inspector** view. +Simply select the comment node to show its properties in the **Inspector** view. + +| Property | Description | +|:-----------------|:-----------------------------------------------------------------------------------------------------------------------------------------| +| Titlebar Text | The text that will be shown in the comment node's title bar. | +| Align Center | If this is checked, the titlebar text will be center aligned. | +| Background Color | This allows you to change the background color of the comment node. Remember to use Alpha to adjust the transparency of the background. | +| Font Size | This allows specifying the text size of the text in the node's panel area. | +| Text Color | This allows you to change the text color of the text in the node's panel area. | +| Comments | This allows you to provide an extended description using a multi-lined text area that will be added to the node's panel area. | \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/constants.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/constants.md new file mode 100644 index 0000000..184384a --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/constants.md @@ -0,0 +1,117 @@ +--- +toc_max_heading_level: 4 +--- + +# Constants + +Constants are an integral part of any programming language, as they provide a human-readable names to special values. +For example, in mathematics, there are numerous constants called `TAU` and `PI`, and Orchestrator supports these and many more. + +In this section, you will learn what are Orchestrator's constant types, and how to use them. + +:::warning +Constant nodes are considered _experimental_, and may change in the future. +While it is safe to use these in your Orchestrations, they may be replaced by a more consolidated, and user-friendly node in the future. +::: + +## Class-specific constants + +
+ +Class-specific constants are constants that must be accessed by using the class as a prefix. +For example, if your game needs to access the `SYSTEM_DIR_DESKTOP`, you would do so by using the `OS` class. + +In GDScript, the code would look like: +```gdscript +var desktop_directory = OS.SYSTEM_DIR_DESKTOP +``` + +To access a class-specific constant in Orchestrator: + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for `Class constant`. +3. Press the **Add** button or simply press **Enter**. + +Once the node has spawned, select the node in the **Graph** and adjust its properties in the **Inspector** view. + +| Property | Description | +|:-----------|:-------------------------------------------------------------------------------------| +| Class Name | The Godot class that owns the constant, i.e. `OS`. | +| Constant | The constant value to output from the node when executed, i.e. `SYSTEM_DIR_DESKTOP`. | + +## Global constants + +
+ +Global constants are very similar to class-specific constants; however, since they are in the global namespace, they do not require the use of a prefix to access. +For example, if your game needs base behavior around the constant for the `ESC` key, you would use the `KEY_ESCAPE` global constant. + +To access global constants in Orchestrator: + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for `Global constant` +3. Press the **Add** button or simply press **Enter**. + +Once the node has spawned, select the node in the **Graph** and adjust the properties in the **Inspector** view. + +| Property | Description | +|:---------|:-----------------------------------------------------------------------------| +| Constant | The constant value to output from the node when executed, i.e. `KEY_ESCAPE`. | + +## Math-specific constants + +
+ +Godot specifically registers math-specific constants slightly differently, therefore in order to access constants such as `One`, `PI`, `PI/2`, `TAU`, and others, you must use a **Math Constant** node. + +To access math constants in Orchestrator: + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for `Math constant` +3. Press the **Add** button or simply press **Enter**. + +Once the node has spawned, select the node in the **Graph** and adjust the properties in the **Inspector** view. + +| Property | Description | +|:---------|:---------------------------------------------------------------------| +| Constant | The constant value to output from the node when executed, i.e. `PI`. | + +## Singleton-specific constants + +
+ +Singleton-specific constants are very similar to class-specific constants; however, these are related specifically to Godot's registered singleton objects, such as `Input` or `AudioServer`. +For example, to access `MOUSE_MODE_HIDDEN` or `MOUSE_MODE_CAPTURED`, you would use a **Singleton Constant** node. + +To access singleton constants in Orchestrator: + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for `Singleton constant` +3. Press the **Add** button or simply press **Enter**. + +Once the node has spawned, select the node in the **Graph** and adjust the properties in the **Inspector** view. + +| Property | Description | +|:-----------|:------------------------------------------------------------------------------------| +| Class Name | The singleton class to scope the constants based upon, i.e. `Input`. | +| Constant | The constant value to output from the node when executed, i.e. `MOUSE_MODE_HIDDEN`. | + +## Type-specific constants + +
+ +Type-specific constants are similar to class-specific constants; however, these are related specifically to Godot built-in data types. +For example, if you want to use `Vector3.ZERO` to set a Vector3 to its default value, you would use a **Type Constant** node. + +To access type constants in Orchestrator: + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for `Type constant` +3. Press the **Add** button or simply press **Enter**. + +Once the node has spawned, select the node in the **Graph** and adjust the properties in the **Inspector** view. + +| Property | Description | +|:-----------|:---------------------------------------------------------------------------| +| Basic Type | The Godot built-in type to scope the constants based upon, i.e. `Vector3`. | +| Constant | The constant value to output from the node when executed, i.e. `ZERO`. | diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/dialogue.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/dialogue.md new file mode 100644 index 0000000..0cc7e1a --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/dialogue.md @@ -0,0 +1,87 @@ +--- +toc_max_heading_level: 4 +--- + +# Dialogue + +Any RPG game heavily relies on a solid foundation for telling a story and providing an immersive experience for the player. +One the tools that help facilitate this is using a conversation system to drive the interaction between the player and the game's story. + +Orchestrator provides two key nodes to support conversation: + +- Show Message node +- Dialogue Choice node + +## Show message node + +
+ +The **Show Message** node is the foundation of the dialogue and RPG conversation system. +It allows you to define who is speaking, and the text they're going to say. +Additionally, you can define any number of choice inputs that allow the player to control the execution flow throughout the conversation. + +### Using a custom scene + +Orchestrator provides a default basic scene for conversations in the `res://addons/orchestrator/scenes` directory. +While you may edit this scene directly, we **strongly recommend** that you make a copy and customize the scene in a different path. + +To use a custom scene with the conversation system: + +1. Locate your **Show Message** node(s) in the graph. +2. Click on the `Default Scene` button for the **Scene** property. +3. Locate your new custom scene file in the project, and press **Open**. + +:::info +We understand that it may be cumbersome to set the **Scene** on each **Show Message** node manually. +We will be adding an Orchestrator setting in the future to allow setting a custom default scene in the `Project Settings`. +::: + +### Non-linear conversation flow + +One of the most powerful ways to create immersive RPG conversation is to provide options when interacting with non-player characters, creating responses that are tailored based on the choices selected by the player. +Orchestrator's **Show Message** node provides for this using the button. + +To add one or more conversation choices: + +1. Press the button to add a conversation choice. +2. Add a **Dialogue Choice** node to the graph and wire its output pin to the input pin of the message node's choice. +3. Connect any output logic to that choice's output pin, which will receive the output pulse when the player selects that choice. + +:::tip +Use choice output pins in **Show Message** nodes to alter the global game state can that influence future interactions with non-player characters for a truly immersive experience. +::: + +### Properties + +The following properties can be set on the **Show Message** node: + +| Pins | Description | +|:---------|:----------------------------------------------------------------------------------------------------| +| Speaker | The name of the character that is currently speaking the `Message` text. | +| Message | The text being spoken by the `Speaker`. | +| Scene | The file path to the custom scene to be rendered when the node executes. | +| Choice n | Optional choices that can be selected by the player when interacting with the non-player character. | + +:::note +If no choices are specified, the player will be prompted to press a `Continue` button when using the default scene. +::: + +## Dialogue choice node + +
+ +The **Dialogue Choice** node is a special type of node that describes a specific choice that can be picked by the player when interacting with a **Show Message** node. +Therefore, for **Dialogue Choice** nodes to be useful, they must be paired with a **Show Message** node. + +
+ +In the above example, there are two **Dialogue Choice** nodes that are connected to a **Show Message** node. +When the **Show Message** node executes, each choice's `visible` input condition is evaluated to determine whether that specific choice should be shown to the player. +This can be extremely useful for creating varied responses and actions the player can take based on game state. + +| Pins | Description | +|:--------|:----------------------------------------------------------------------------------------------------| +| Text | The text to be diplayed in the conversation dialogue window for that specific choice. | +| Visible | Whether the this choice should be visible to the player | +| Choice | The output pin that should be connected to one of the `Choice n` input pins of a Show Message node. | + diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/events.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/events.md new file mode 100644 index 0000000..dc9856e --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/events.md @@ -0,0 +1,151 @@ +--- +toc_max_heading_level: 4 +--- + +# Events + +**Events** are nodes that are called directly by the Godot game engine, to begin the execution of logic within a **Graph**. +They enable orchestrations to perform a series of actions in response to well-defined callbacks within the Godot game engine, such as when the node is *ready*, *enters the tree*, *receives input*, and more. + +**Events** are used to implement new functionality or to override or alter the default functionality of Godot objects. +Any number of **Events** can be used within a single **Graph**, although you can only define one event node of each event type. + +An event can only execute a single, linear series of execution steps. +If you want to trigger multiple actions from one event, you will need to string them linearly together. + +
+ +To add an event to the **Graph**: + +1. Press the button in the **Functions** section of the **Components** view. +2. Search for the desired Godot event to override in the search box, i.e. `ready`. +3. Press the **Add** button or simply press **Enter**. + +Once the function override has been added, connect your behavior or add behavior to the output pins of the event node. + +## Init event + +
+ +The **Init Event** is called when the object's script is instantiated, often times after the object has been initialized in memory. +This method is very similar to a *constructor* in most programming languages. + +This is useful when you need to perform some initialization steps when the Orchestration is first created. + +:::important +Orchestrator does not currently support arguments in the `init()` event callback. +::: + +## Notification event + +
+ +The **Notification Event** is called when the owning node, and by extension the Orchestration, receives a specific notification from Godot. +Notifications are identified by a `what` numeric constant, such as `NOTIFICATION_PREDELETE`. + +Normally an Orchestration will prefer to use one of the other overridable events rather than using the **Notification Event**. + +## Enter tree event + +
+ +The **Enter Tree Event** is called when the Orchestration's owning node is added as a child to a node in the scene tree. +You will use this event to define behavior that should happen everytime the owning node enters the scene. + +## Exit tree event + +
+ +The **Exit Tree Event** is called when the Orchestration's owning node is removed from the scene tree. +You will use this event to define behavior that should happen everytime the owning node leaves the scene, such as clean-up specific resources that may have been allocated during the script's lifetime. + +## Input event + +
+ +The **Input Event** is called when the Orchestration's owning node receives some type of *input*. +The output pin `event` will provide the orchestration with the input event that was received by the engine. + +## Physics process event + +
+ +The **Physics Process Event** is called during the physics processing in during the main game loop. +This event is synchronized with the physics frame rate, i.e. the `delta` value should always be constant and in `seconds`. + +This event callback is great to perform logic that should be synchronized with physics. + +:::info +If the owning node does not have physics enabled, the **Physics Process Event** will not be called. +Additionally, if the owning node has been removed from the scene, this event will not be called. +::: + +## Process event + +
+ +The **Process Event** is called during the processing step of the main game loop. +This event is fired every frame and as fast as possible, meaning that `delta` will not be consistent and can vary. +The `delta` represents the time since the previous frame, and is represented in `seconds`. + +This event callback is great to perform per-frame (per tick) logic. + +:::info +If the owning node does not have processing enabled, the **Process Event** will not be called. +Additionally, if the owning node has been removed from the scene, this event will not be called. +::: + +## Ready event + +
+ +The **Ready Event** is called when the owning node, and by extension the Orchestration, is "ready". +Godot implies readiness when the owning node, and any children, have all entered the scene and their respective **Enter Tree Event** callbacks have executed. + +This event callback is typically used for initialization, especially if the behavior expects the Orchestration to exist in the scene. + +:::tip +Godot executes the **Ready Event** of child nodes before parent nodes. +::: + +:::info +This callback is only fired once for each Orchestration. +If the Orchestration's owning node is removed from the scene and later added, the **Ready Event** is not called a subsequent time. +If the Orchestration's **Ready Event** should be called again when added back to the scene, a prior call to the Orchestration's `request_ready()` function must be made. +::: + +## Unhandled input event + +
+ +The **Unhandled Input Event** is called when an `InputEvent` has not been consumed by any `_input` or UI `Control` objects. +It is called after the **Unhandled Key Input Event**, and is called in a bottom up order through the scene tree. +The output pin `event` contains the received `InputEvent` object. + +This callback is an excellent place to handle non-key related input, such as mouse interactions. + +:::info +If the owning node has disabled processing of unhandled input via `set_process_unhandled_input` with `false`, this method is not called. +Additionally, if the owning node has been removed from the scene, this event will not be called. +::: + +## Unhandled key input event + +
+ +The **Unhandled Key Event** is called when an `InputKeyEvent` has not been consumed by any `_input` or UI `Control` objects. +It is called before the **Unhandled Input Event**, and is called in a bottom up order through the scene tree. +The output pin `event` contains the received `InputKeyEvent` object. + +This callback is an excellent place to handle key-related input, such as key pressed or releases. + +:::info +If the owning node has disabled processing of unhandled input via `set_process_unhandled_key_input` with `false`, this method is not called. +Additionally, if the owning node has been removed from the scene, this event will not be called. +::: + +## Custom Events + +Other game engines provide the ability add user-defined custom events. +In Godot, these are known as **Signals**. +Please see the [Signals](signals) section for details on how to add and work with signals using Orchestrator. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/flow-control.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/flow-control.md new file mode 100644 index 0000000..c9598f4 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/flow-control.md @@ -0,0 +1,290 @@ +--- +toc_max_heading_level: 4 +--- + +# Flow Control + +**Flow Control** nodes are some of the most common types of nodes used in visual scripting, as they provide the control over the sequence of how an Orchestration's nodes are executed. + +## Switch nodes + +A switch node reads a data *input*, and based on that value, sends the execution flow out to the matching (or optional default) execution *output* pin. +There are several types of switches available: **Integer**, **String**, and **Enumeration**. + +In general, switches have an *execution* input, and a *data* input for the type of data they evaluate. +The outputs are all *execution* outputs. +**Enumeration** switches automatically generate the output execution pins based on the enumeration's properties, while **Integer** and **String** switches provide customizable output execution pins. + +### Editing switch nodes + +When an **Integer** or **String** switch node is added to an Orchestration, the only output execution pin that is available is the **Default** pin. +The **Default** output execution pin will fire if the input fails to match any of the other specified output pins, or if no other output pins are defined. +It can be removed by unchecking the `Has Default Pin` property in the **Inspector** view. + + +
+
+
+ + +#### Editing an Integer switch + +1. Select the switch node in the **Graph** to display its properties in the **Inspector** view. +2. Change the **Start Index** to the lowest integer value that you want to check against. +
+3. Click on the button to add a new *output* pin with the **Start Index** value. +
+ +Clicking on the button will add additional output pins, with the value incremented by 1 each time. +To remove an execution pin, right-click on the pin and select **Remove Pin**. + +:::note +Removing an output execution pin on a **Switch on Integer** node causes any higher-valued pins to decrease their value by 1. +::: + +#### Editing a String switch + +1. Select the switch node in the **Graph** to display its properties in the **Inspector** view. +
+2. Click on the button on the node in the **Graph** to add new *output* pins. +
+3. A new expandable section called **Pin Names** will appear in the **Inspector** view. +
+4. Adjust the names of all the *output* pins accordingly. + +
+
+ + +Repeat the process for any additional output pins you would like to add. +To remove an output execution pin, right-click on the pin name and select **Remove Pin**. + +## Standard flow control nodes + +These nodes provide a variety of means to control the execution flow of an orchestration. + +### Branch + +
+ +The **Branch** node serves as a simple way to create decision-based flow from a single true/false condition. +Once executed, the Branch node looks at the incoming value of the attached boolean input, and outputs an execution pulse down the appopriate output. + +In this simple example, the branch is checking the current state of a boolean variable. +If `true`, it sets the color of a light to be red. +If `false`, it sets the color to blue. + +
+ +| Pin | Description | +|:----------|:--------------------------------------------------------------------------------| +| Condition | Takes a boolean value used to indicate which output pin that will be triggered. | +| True | This outputs an execution pulse if the incoming condition was `true`. | +| False | This outputs an execution pulse if the incoming condition was `false`. | + +### Chance + +
+ +The **Chance** node works by calculating a value between 0 and 100, and sending the execution out one of two output pins. +The percentage chance is set in the **Inspector** view by setting the value of `Chance` to a value between 0 and 100. + +* If the random value generated is between 0 and the specified `Chance`, the top output pin will be chosen. +* If the random value generated is greater than the `Chance` value and less-than equal to 100, the bottom output pin will be chosen. + +| Pin | Description | +|:------------------|:--------------------------------------------------------------------------------------------------------| +| Top Output Pin | The output pin that emits a pulse if the random value is between `0` and `Chance` (chance inclusive). | +| Bottom Output Pin | The output pin that emits a pulse if the random value is between `Chance` and `100` (chance exclusive). | + +### Delay + +
+ +A **Delay** node works by temporarily yielding the execution of the orchestration without blocking the game loop. +The is done by using coroutines and Godot signals to *await* on the internal timer's `timeout` callback. + +| Pin | Description | +|:---------|:---------------------------------------------------------------------------------------| +| Duration | Specifies the number of seconds to yield the orchestration by, defaults to `1` second. | + +### For loop + +
+ +The **For Loop** node works like a standard code loop, firing off an execution pulse for each index between a start and end value. + +In the following simple example, the loop is triggered when the player touches a simple level trigger. +The loop iterates 10 times, each time calling a **Print String**, logging a prefix message with the current iteration. + +
+ +| Property | Description | +|:------------|:---------------------------------------------------------------------------------------------------| +| First Index | Takes an integer representing the first index in the loop (inclusive). | +| Last Index | Takes an integer representing the last index in the loop (inclusive) | +| Loop Body | This outputs an execution pulse on each iteration of the loop as it moves between the two indices. | +| Index | This outputs the current index in the loop. | +| Completed | This outputs an execution pulse when the loop has reached the for loop has completed. | + +### For loop with break + +
+ +The **For Loop With Break** node works in a very similar manner to the **For Loop** node, except that it includes an *input* pin that allows for the loop's execution to terminate early. + +In this simple example, the loop is triggered when the player touches a simple level trigger. +The loop iterates 1000 times, each time hitting a Branch which checks if the loop has hit 500 iterations. +If it has not, then a message with the current iteration is placed on the screen. +Once it exceeds 500, the Branch sends a pulse into the **Break** pin, which breaks the loop. + +
+ +:::tip +In a future Orchestrator update, wires will be controlled by user-driven **Knots**, which can be used to render the wire connecting **False** to the **Break** input so that they do not automatically pass behind other objects in the graph. +::: + +| Property | Description | +|:------------|:---------------------------------------------------------------------------------------------------| +| First Index | Takes an integer representing the first index in the loop (inclusive). | +| Last Index | Takes an integer representing the last index in the loop (inclusive) | +| Break | This execution input pin breaks the loop when triggered. | +| Loop Body | This outputs an execution pulse on each iteration of the loop as it moves between the two indices. | +| Index | This outputs the current index in the loop. | +| Completed | This outputs an execution pulse when the loop has reached the for loop has completed. | +| Aborted | This outputs whether the loop broke early due to the **Break** input pin. | + +### For each loop + +
+ +The **For Each Loop** node works in a very similar manner ot the **For Loop** node, except that this node specifically iterates over a collection. + +
+ +In the above example, the loop is triggered when a player touches a simple level trigger. +The loop iterates over a collection, output each element to the screen. +Once all elements in the collection have been iterated, the loop exits through the **Completed** output pin. + +| Property | Description | +|:----------|:---------------------------------------------------------------------------------------------------| +| Array | The collection to be iterated. | +| Loop Body | This outputs an execution pulse on each iteration of the loop as it moves between the two indices. | +| Element | This outputs the current array element. | +| Index | This outputs the current index in the loop. | +| Completed | This outputs an execution pulse when the loop has reached the for loop has completed. | + +### For each loop with break + +
+ +The **For Each Loop With Break** node works in a very similar manner to the **For Each Loop** node, except that it includes an *input* pin that allows for the loop's execution to terminate early. + +In this simple example, the loop is triggered when the player touches a simple level trigger. +The loop iterates for each element in the array, each time hitting a Branch which checks if the loop has hit the second element. +If it has not, then a message with the current element is placed on the screen. +Once the second element is reached, the Branch sends a pulse into the **Break** pin, which breaks the loop. + +
+ +:::tip +In a future Orchestrator update, wires will be controlled by user-driven **Knots**, which can be used to render the wire connecting **False** to the **Break** input so that they do not automatically pass behind other objects in the graph. +::: + +| Property | Description | +|:----------|:---------------------------------------------------------------------------------------------------| +| Array | The collection to be iterated. | +| Break | This execution input pin breaks the loop when triggered. | +| Loop Body | This outputs an execution pulse on each iteration of the loop as it moves between the two indices. | +| Element | This outputs the current array element. | +| Index | This outputs the current index in the loop. | +| Completed | This outputs an execution pulse when the loop has reached the for loop has completed. | +| Aborted | This outputs whether the loop broke early due to the **Break** input pin. | + +### Random + +
+ +A **Random** node allows specifying one or more output execution pins, and one will be chosen randomly when the node executes. + +To add a new output execution, simply click the button to add a new choice output. +To remove an output execution, simply right-click the name of the choice and select **Remove Pin** from the context-menu. + +| Pin | Description | +|:---------|:-----------------------------------------------------------------------------------------------| +| Choice_n | A random choice output execution between 0..n depending on the number of random choices added. | + +### Select + +
+ +A **Select** node acts like a *gate*, emitting one of two different input values referred to as `A` and `B` based on a condition. +If the condition is `true`, the **Select** node allows the value of `A` to be sent as the output value. +If the condition is `false`, the **Select** node allows the value of `B` to be sent as the output value. + +:::info +By default, the **Select** node uses the Godot **Any** type to allow any value to be attached to its input pins. +To restrict the **Select** node to a specific Godot type, right-click on the `A`, `B`, or `Result` pins and pick a type from the `Change Type` context-menu. +::: + +| Pin | Description | +|:-------|:----------------------------------------------------------------------------| +| A | One of two values that will be output if the `Pick A` condition is `true`. | +| B | One of two values that will be output if the `Pick A` condition is `false`. | +| Pick A | Controls whether the value of `A` or `B` is emitted as the `Return Value` | +| Result | The output value of the gate, depends on what the `Pick A` condition is. | + +### Sequence + +
+ +A **Sequence** node allows the execution of two or more execution chains in sequential order, by first executing the connections of **Then 0**, followed by **Then 1**, and so on until all output connections have been called. + +Additionally, new output connections can be added by pressing the button on the graph node. +If an output connection should be removed, right-click the output pin name and select **Remove Pin**. + +| Pin | Description | +|:-------|:------------------------------------------------------------------------------------------| +| Then 0 | The first output connection chain to be executed, and cannot be removed. | +| Then 1 | The second output connection chain to be executed, and cannot be removed. | +| Then n | The next output connection chain to be executed, any chain where `n >= 2` can be removed. | + +### Type cast + +
+ +A **Type Cast** node is a special type of flow control type that allows for checking the input value's logical type. +When the input value's type matches the configured type in the node, the **Yes** output pin will receive the output pulse, and the `as ...` output data pin will contain the value cast to the desired type. +When the input value's type does not match the configured type in the node, the **No** output pin will receive the output pulse, and the `as ...` output data pin will be `null`. + +To change the type in the cast operation: + +1. Select the **Type Cast** node in the graph. +2. In the **Inspector** view, press the button in the `Type` property. +3. Select the desired type from the dialog. + +| Pin | Description | +|:---------|:--------------------------------------------------------------------------------------------------| +| Instance | The input value to be checked against the configured `Type` property. | +| Yes | The output pin that receives the execution pulse if the `Instance` is a `Type`. | +| No | The output pin that receives the execution pulse if the `Instance` is not a `Type`. | +| as ... | The output data pin that will contain the casted instance as `Type`, if the cast outputs **Yes**. | + + +### While + +
+ +The **While** node provides a construct similar to a **For Loop** except the iteration of the loop is driven by an input boolean condition. + +In the following example, we have an integer variable `x` that is initialized as `0`. +The while loop has a boolean condition that checks if `x` is less-than 10, and if so, will output an execution pulse to the **Repeat** pin, printing some text onto the screen and incrementing `x` by one. +When `x` finally reaches 10, the boolean condition is no longer true, and the while loop ends by emitting an output execution pulse to the **Done** pin. + +
+ +| Pin | Description | +|:----------|:----------------------------------------------------------------------------------| +| Condition | The condition that is evaluated on each loop iteration. | +| Repeat | The output pin that receives the execution pulse if the condition remains `true`. | +| Done | The output pin that receives the execution pulse if the condition is `false`. | diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/functions.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/functions.md new file mode 100644 index 0000000..3cd6eb0 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/functions.md @@ -0,0 +1,167 @@ +--- +toc_max_heading_level: 4 +--- + +# Functions + +**Functions** are graphs that belong to a specific orchestration that can be executed, or called, from another graph within the orchestration. +Functions have a single entry point designated by a node with the name of the Function containing a single execution *ouptut* pin. +When the function is called from another graph, such as the EventGraph, the *output* execution pin is activated causing the function's graph to execute. + +## Access specifiers + +When creating Functions in an orchestration, there is no concept of public or private visibility. +Any user-defined function on the orchestration can be accessed by any outside entity, including other scripts. + +However, in Godot there is a general rule that functions that are private or not publicly accessible, are defined with a prefixed `_` (underscore) character. +If you want a function to be publicly accessible, you generally omit the underscore. + +:::info +While other engines like Unreal provide the ability to toggle function visibility, this is currently not available. +We may choose to add this in the future if there is reasonable demand. +::: + +## Creating a function + +To create a Function within an orchestration: + +1. In the **Component** panel, press the button in the **Functions** section. +2. Enter a name for the Function. +
+ +The Function will open in a new tab in the **Graph Editor**. + +## Editing a function + +Once you have created a Function, you then need to define its functionality. +This is a step-step process: + +* Create the necessary input and output parameters. +* Add nodes to the function graph between the **Functon Entry** and **Function Return** node. + +Once the function is created, you modify the details in the **Inspector** view. +To open the **Inspector** view to modify the function, you can: + +* Select the **Function Entry** node in the graph. +* Select the **Function Result** node in the graph. +* Select your defined function in the **Functions** panel. + +### Input and output parameters + +You can set the input and output parameters in the **Inspector** view for the Function. + +To add an **Input** argument: + +1. Modify the `Argument Count` property in the inspector, setting a value greater than `0`. +2. For each `Argument n` group, set the argument's `Type` and `Name`. + +To add an **Output** argument: + +1. Check the `Has Return Value` option in the **Inspetor**. +2. A new property, `Return Type` will be shown, select the return value's `Type`. + +Any changes made to the input or output configurations will directly be reflected in the Function graph. +Once the appropriate input and output arguments have been specified, the Function is now ready for you to define its functionality. + +### Define functionality + +A Function is defined by creating an Orchestration graph that connects behavior between the **Function Entry** and the **Function Result** nodes. +In this example, we will create the necessary nodes to apply the 3D version of Pythagorean Theorem, returning the distance between 2 points in 3D space. + +```gdscript +dx = (x2 - x1)^2 +dy = (y2 - y1)^2 +dz = (z2 - z1)^2 +D = sqrt(dx + dy + dz) +``` + +Representing this in an `Orchestration` may look like this: + +
+ +1. Break the two `Vector3` positions (`start` and `end`) into their respective `(x1,y1,z1)` and `(x2,y2,z2)` values. +2. Calculate the values for `dx`, `dy`, and `dz`. +3. Add `dx`, `dy`, `dz`, and then take the `sqrt` of that value. +4. Return the result using a **Function Return** node. + +## Calling functions + +Once you have created and defined your Function, it is time to call it from within the orchestration. +To create a node that will call your Function: + +* Drag your Function from the **Components** view onto the graph. +* Right-click in the graph or drag from an appropriate execution or data pin to open the **All Actions** dialog. +Search for your function, and select it to add the **Function Call** node. + +The graph below takes two vector variables, and on every tick, calculates the distance between the two and pints it to the screen. + +
+ +### Calling functions from external orchestrations + +You can also call a **Function** in an Orchestration from inside another Orchestration, as long as you have a reference to the Orchestration that contains the Function. + +## Built-in functions + +Godot provides thousands of functions, some which are global such as `min` or `max`, but most are functions that are associated with a specific object, such as `Node`. +Orchestrator uses the **Call Function** node to also call Godot's built-in functions. + +To add a Godot built-in function: + +1. Right-click the graph to open the **All Actions** dialog. +2. Search for the function you wish to call, such as `rotate_y`. +3. Select the desired option, such as `Call Rotate Y`. +4. To spawn the node, pressing the **Add** button or simply pressing **Enter**. + +The number of *input* and *output* pins vary based on how Godot defines the function. + +### Variable argument functions + +Some functions are called variable argument functions, or *vararg* for short. +These functions are designed to take zero or more static arguments, followed by zero or more variable arguments. + +In many languages, variable argument functions are defined like: + +```gdscript +def min(Variant x, Variant y, Variant...) { +} +``` + +In this example, the `min` function accepts at a minimum two `Variant` values called **x** and **y**; however, the function may be called with additional `Variant` values if the caller wishes to compute the minimum across more than two values. +Orchestrator supports variable argument functions, and you can recognize these as they'll have a button in the bottom right corner, allowing you to add additional *input* pins to the node. + +
+ +If you decide at a later time that you want to remove a variable argument from the node, simply right-click on the name of the argument and select `Remove pin`. + +
+ +:::info +Only user added dynamic pins can be removed. +::: + +## Method chaining + +In text-based programming languages, method chaining is a technique to simplify code by calling multiple methods on the same object in a single line. +In visual scripting tools, method chaining is not as common, but Orchestrator supports method chaining by allowing you to connect the output of one function to the input of another. + +For example, in the following graph, we are applying a position and rotation to the camera. +You will notice that we have to not only call **Set Position** and **Set Rotation**, but we have to link the Camera node to each function call. +If you were to add additional steps that you needed to perform on the Camera, you would begin to have a spaghetti of connections. + +
+ +Now, thanks to method chaining, you can connect the target output to the input of the next function call. + +
+ +This makes the graph easier to read and understand, as well as easier to maintain. + +To enable method chaining: + +1. Click the **Call Function** node. +2. Open the **Inspector** view. +3. Check the `Chain` option. +
+ +Once enabled, a new output pin labeled `Target` will appear, allowing you to chain the functions together. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/input.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/input.md new file mode 100644 index 0000000..5d26169 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/input.md @@ -0,0 +1,74 @@ + +# Input + +Input is one of the most critical requirements in games, as it's used to drive all types of interactions with the game world, such as player movement. +In Godot, it's preferred to use the `Project > Project Settings > Input Map` dialog to define mappings between input keys or sequences and actions that are triggered when those input keys or sequences are triggered. + +Orchestrator works directly with the engine's `Input Map` using an **Input Action** node. +The **Input Action** node is designed to return whether the action is triggered as an *output* pin, which can then be used as an *input* into other nodes that drive specific behavior. + +
Input action node that checks for action ui_up being pressed.
+ +## Defining input mappings + +Input mappings are defined in Godot using the `Project > Project Settings > Input Map` dialog. +In this screen, you define the relationship between a key press or input sequence and an action that should be toggled on when that key press or input sequence is detected by the engine. + +For example, to define an action called `move_forward` to be triggered when pressing the `W` key: + +1. Open the `Input Map` tab by navigating the `Project > Project Settings` menu. +2. In the **Add New Action** field, type `move_forward`. +3. Press the `+ Add` button to add the new action to the input map. +4. In the lower section of the dialog, find the action `move_forward`, and press the button. +5. In the **Event Configuration** pop-up dialog, press the `W` key followed by clicking the `OK` button. +6. A child row will be added to the action that reads `W (Physical)`. +7. Press the `Close` button to close the **Input Map** dialog. + +## Using an input mapping + +Once an input mapping has been defined, you can use the **Input Action** node in an orchestration. +The **Input Action** node checks the current state of the action defined in the input map, and returns either `true` if the action is triggered; otherwise, it returns `false`. + +To add an **Input Action** node: + +1. Right-click in the graph to open the **All Actions** dialog. +2. Search for `input action` in the search box. +3. Select the **Input Action** choice and either press the **Add** button or simply hit the **Enter** key. + +By default, an **Input Action** node does not default to any specific action, so it's important to set the `Action` property in the **Inspector** view. +See [Setting the input action name](#setting-the-input-action-name) for details. + +## Setting the input action name {#setting-the-input-action-name} + +The **Input Action** does not default to any specific action, so the action must be explicitly set in the **Inspector** view. + +To set the action name: + +1. Select the **Input Action** node in the graph. +2. Modify the `Action` property in the **Inspector** view by setting the action name, i.e. `move_forward`. + +## Input action trigger modes + +Each **Input Action** node has a `Mode` property that describes precisely how the node should react to the action being triggered. +For example, if you want to react only when the user pressed the key that triggers the action in the current frame but not in any future frames, you may want to select `Just pressed` rather than the default of `Pressed`. + +The following describes each mode and how it's interpreted: + +| Input Action Mode | Description | +|:------------------|:------------------------------------------------------------------------------------------------------| +| Pressed | Returns `true` if the key or sequence that triggers the action is pressed. | +| Released | Returns `true` if the key or sequence that triggers the action is not pressed. | +| Just Pressed | Returns `true` if the key or sequence that triggers the action is pressed in the current frame only. | +| Just Released | Returns `true` if the key or sequence that triggers the action is released in the current frame only. | + +## Input action properties + +To set the properties for an **Input Action**: + +1. Select the **Input Action** node in the graph. +2. Open the **Inspector** view and modify its properties. + +| Property | Description | +|:---------|:--------------------------------------------------------------------------------------------| +| Action | This is the user-defined action from `Project > Project Settings > Input Map`. | +| Mode | This defines how the action's triggering effect is recognized, whether pressed or released. | diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/math.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/math.md new file mode 100644 index 0000000..d0251a2 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/math.md @@ -0,0 +1,51 @@ + +# Math + +**Math** nodes are essential to every game, allowing a script to do anything from moving an object each frame to computing the probability of specific scenarios based on a wide array of input chracteristics. +Godot, and by extension Orchestrator, provide dozens of mathematical nodes to perform any type of computation. + +## Operators + +Orchestrator classifies math operations into **5** key groups: + +| Type | Description | +|:--------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Boolean | Compares two values to determine their equality or relative coparison.
*Examples: `==`, `!=`, `<`, `<=`, `>`, or `>=`* | +| Numeric Math | Performs a unary operation on a single value or binary operation on two or more values.
*Examples: `+`, `-`, `*`, `/`, `-Unary`, `+Unary`, `%`, or `^` (power).* | +| Bitwise | Performs bitwise operations on a given numeric value.
*Examples: Shift left, Shift right, And, Or, Xor, or Negate.* | +| Logic | Performs a logical comparison between one or two values.
*Examples: And, Or, Xor, and Not* | +| Containment | Checks whether a value is contained within a collection.
*Examples: `has` or `contains`* | + +Orchestrator looks at all the possible combinations of operations between various data types and generates a unique operator node for each combination. +For example, the node to add two `Integer` values differs from a node that adds two `Float` values. + +At first glance, this may seem strange, but it's generally better in visual scripting to enforce a bit more type safety than in text-based code where it's much easier to point the user to a specific line when a type coercion or invalid value is recognized. +The following shows several different examples of various math operator nodes. + +
+ +## Add math nodes {#add-math-nodes} + +To add a math node to the orchestration, simply: + +1. Right-click the graph to access the **All Actions** dialog. +2. Search for the math operation, for example `Multiply`. +3. Select the right math operation for the two operand types. + +:::note +**Math** nodes are initially categorized by the first operand type. +For example, the **Multiply** node that accepts an `Integer` as the first argument will be under the `Math > Integer` category. +The operand type included in the parenthesis that follows the operation specifies the second argument type. + +So to add a node that multiplies an `Integer` with a `Float`, you would search for the **Multiply** node under the `Math > Integer` category, selecting the action labeled `Multiply (Float)`. +::: + +## Changing math operands + +After placing a **Math** node, if you need to change the operand type of one of the input values, then you must select a new node that matches your desired operands. +By following the [Add math nodes](#add-math-nodes) procedure, you can add the appropriate node and connect all the input/output pins before removing the old node. + +To remove the old node, simply: + +1. Select the node in the graph. +2. Either Right-Click and select **Delete** from the context-menu or simply press the `Del` button. \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/memory.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/memory.md new file mode 100644 index 0000000..8fdb7a5 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/memory.md @@ -0,0 +1,54 @@ + +# Memory + +**Memory** nodes are used to dynamically allocate and free objects in an `Orchestration`. + +For example, you may add a `Button` to your user interface and based on some interaction, remove the button from the scene. +In this case, you would use a `New` node to create the button and the `Free` node to free it. + +:::note +These nodes are currently considered experimental .
+While it's okay to use these nodes, be aware that their implementation may change in the future. +::: + +## Creating objects + +The **New** or **Create Instance** node is responsible for creating a new instance of a given object. +You can use this node to allocate a new instance of a any `Node`, `Resource`, or `Object` type, as long as the type is not a singleton. + +
Create a new instance of a Button node
+ +To create a **New** or **Create Instance** node: + +1. Right-click in the graph to access the **All Actions** view. +2. Search for `New`, locating the `Memory > New` node. +3. Either press the **Add** button or simply hit **Enter**. +4. In the **Inspector** view, select the desired `Class Name` from the inspector, defaults to `Object`. + +:::warning +Godot's **Object** selector window shows all possible object class names; however, not all choices can be used. +If the class name is a singleton, i.e. `OS`, this value will not be accepted and you will need to select another value. +::: + +### Properties + +| Property | Description | +|:-----------|:------------------------------------------------------| +| Class Name | Specifies the class name of the object to be created. | + +## Freeing objects + +The **Free** or **Deallocate Instance** node is responsible for destroying an instance of a given object. +This node uses a combination of `queue_free()`, `memdelete`, and `unreference()` to deallocate the object based on its type. +For example, if the node is still in the scene tree, the `queue_free()` method is used. +If the object is a `Resource`, the `unreference()` method is used because resources are reference counted. + +
Free an instance of a Button node
+ +To create a **Free** or **Deallocate Instance** node: + +1. Right-click in the graph to access the **All Actions** view. +2. Search for `Free`, locating the `Memory > Free` node. +3. Either press the **Add** button or simply hit **Enter**. +4. Connect the object to be freed to the input `Target` pin. + diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/properties.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/properties.md new file mode 100644 index 0000000..b8fe69d --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/properties.md @@ -0,0 +1,39 @@ + +# Properties + +**Properties** are attributes on an object, that describe certain object state. +For example, a `Button` in a user interface may have an icon property to provide some visual indicator of what the button does. + +## Property types + +Properties are associated with a specific data type, such as `Boolean`, `Integer`, or `Float`, but can also be represented by more complex types such as `Object`, `Array`, `Dictionary`, or specialized packed array types. +Properties are specifically color coded for easy identification, just like [variables](variables#variable-types). + +## Accessing properties + +Properties can be accessed in two ways: by using the **Get** node (called an accessor) or the **Set** node (called a mutator). + +You can create a **Set** or **Get** node for a property by: + +1. Right-clicking in the graph or dragging a connection from an existing node +2. In the **All Actions** dialog, search for the property of interest, i.e. `Get Position`. +3. Make sure that the selection has an icon similar to and not on the right. +4. Either press the **Add** button or simply hit **Enter**. + +Using **Property** nodes allows an `Orchestration` to read or modify the state of that property. +For example, a character controller would update the `Position` property each frame based on input. + +## Get property + +The property **Get** node accesses the current value of a property. +These nodes do not have execution control flow pins as they're designed to specifically return a single value to be used as *input* values to other nodes. + +
Get Position property
+ +## Set property + +The property **Set** node updates or modifies the value of a property. +These nodes have execution control flow pins as they're designed to be called in a sequence chain. +These nodes also have an *input* pin based on the property's type to set the property value with. + +
Set Position property
\ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/resources.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/resources.md new file mode 100644 index 0000000..a4c11e8 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/resources.md @@ -0,0 +1,66 @@ +--- +toc_max_heading_level: 4 +--- + +# Resources + +Resources are the fundamental foundation to any game engine, and Godot is no different. +Resources represent all things from assets such as images, textures, and sounds, to Godot-specific assets like scenes, scripts, and even `Orchestration`s. +While many of these resources can be set directly on scene nodes using the **Inspector** view, you may need to dynamically load or work with resources at runtime. + +For example, your game may define different themes that have unique styles, icons, textures that can be chosen in the game's settings by the user. +In such cases, it may make sense to load only the preferred theme, and therefore these need to be handled dynamically at runtime. + +In this section, you will learn more about `Resource`s, and how to load and access them using Orchestrator. + +## Resource paths + +A resource path is a special string that begins with `res://` and follows the Godot semantics for providing a universal resource identifier (URI) to the specific resource file. +Orchestrator provides a specialized node, **Get Resource Path**, that specifically makes working with resource paths (URIs) simple. + +To create a **Get Resource Path** node: + +1. Locate the resource in the **FileSystem** view. +2. Select the file and drag the file onto the graph. +3. Upon releasing the mouse, select the **Get Path** option on the context-menu. + +## Resource path properties + +The **Get Resource Path** properties can be modified in the **Inspector** view, after selecting the node. + +| Property | Description | +|:---------|:----------------------------------------------------------------------| +| Path | The complete Godot `res://` path to the resource file in the project. | + +:::info +The **Get Resource Path** node does not load the resource from the **FileSystem**. +Instead, this node simply returns the fully-qualified path to the file in the Godot project. +This can be useful for passing the resource's path to another node that loads the resource, such as a scene or an image. +::: + +## Preload resources + +When you need to load a resource like a texture at runtime, you could use the **Engine Singleton** node to access the `ResoureLoader` singleton. +However, this approach loads the resource at the time the `Call Load` function is called in the execution flow, and if the resource loading blocks too long during the frame, the game may stutter. + +One way to avoid this problem is use a technique called *preloading*, which is where resources are loaded automatically when the owning scene is loaded by the engine. +This guarantees that the rendering of the scene is more stable and less likely to have stutter, while the trade-off is that the loading of the scene may take slightly longer. + +To preload resources with Orchestrator, you need to add a **Preload Resource** node: + +1. Locate the resource in the **FileSystem** view. +2. Select the file and drag the file onto the graph. +3. Upon releasing the mouse, select the **Preload** option in the context-menu. + +:::info +When a **Preload Resource** node exists in an `Orchestration`, Orchestrator will automatically *load* the resource when the node that owns the orchestration enters the scene tree. +Multiple subsequent nodes can accept the *output* pin as an input without incurring any overhead since the resource is loaded once. +::: + +## Preload resource properties + +The **Preload Resource** properties can be modified in the **Inspector** view, after selecting the node. + +| Property | Description | +|:---------|:------------------------------------------| +| Resource | A reference to the resource to be loaded. | diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/scene.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/scene.md new file mode 100644 index 0000000..0d5fc38 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/scene.md @@ -0,0 +1,139 @@ +--- +toc_max_heading_level: 4 +--- + +# Scene + +Sometimes an `Orchestration` simply modifies the behavior of the node that it's attached; however, there are other situations where one node needs to coordinate, manipulate, or interact with other nodes in your scene. +Orchestrator provides several useful ways to interact with other scene nodes and the Godot `SceneTree`. + +## Scene nodes + +Godot provides dozens of scene node types, which provide some basic archetype in the engine. +For example, there are nodes that provide user interface widgets, nodes that provide behaviors for 2D games, and others for 3D games. +Additionally, these nodes have specializations for things such as characters, meshes, triggers, and more. + +When you attach an `Orchestration` to a scene node, the `Orchestration` will inherit the behavior of the base type you assigned when you created the script. +Most users assign the script's base type to match the node type you attach the orchestration to, a common parent type such as `Node3D`, `Node2D`, or `Node`. + +## Accessing scene node behaviors + +Accessing a scene node's behavior (functions and properties) occurs by searching for the function or property in the **All Actions** dialog. +The main question is whether you want to access a function or property for the node that the `Orchestration` is attached, or are you wanting to access a function or property on another node in the scene. + +### Behaviors on orchestration's owner + +By default, the **All Actions** dialog presents a list of behaviors that are relevant to the `Orchestration` owner when you right-click on the graph. +For example, if the base type selected is a `Node3D` and you would like to call the `rotate_y` function: + +1. Right-click on the graph to open the **All Actions** dialog. +2. Search for `rotate_y`. +3. Select the `Call Rotate Y` and either pressed the **Add** button or hit **Enter**. + +:::note +When you drag the mouse from either an input or output pin, the **All Actions** dialog presents a context-specific list of actions based on the type of pin you dragged from. +This context-specific list often will be a subset or not even related to the base type of the `Orchestration`, so make sure to right-click on the graph to access the **All Actions** dialog if you're interested in the attached node's methods or properties. +::: + +### Behaviors on other nodes + +To access behavior on other scene nodes, this requires a reference to that specific scene node. +A reference to that node can be obtained simply by: + +1. Selecting the desired scene node in the **Scene** view. +2. Drag the scene node onto the graph. +3. Releasing the mouse button will spawn a **Get Scene Node** node. + +:::info +A **Get Scene Node** uses a Godot `NodePath` to refer to the scene node. +If you rearrange your scene, the path to the node may change, and the **Get Scene Node** will need to be updated to reflect the new path. +In order to change the path, select the **Get Scene Node** and then modify the `Node Path` property in the **Inspector** view. +::: + +## Scene node properties + +The **Get Scene Node** node is designed to use a `NodePath` to find the node in the current scene and return a reference to the physical node object in the scene. +To modify the **Get Scene Node** properties, use the **Inspector** view. + +| Property | Description | +|:----------|:-------------------------------------------------------| +| Node Path | The relative path to the node that should be returned. | + +The *output* data pin on the node will contain the reference to the node identified by the `Node Path`. +By dragging the mouse away from the *output* pin will open the **All Actions** dialog with access to context-specific actions to the scene node's type. + +## Scene tree + +The `SceneTree` is the top-level concept in a scene, it represents the container that wraps the actual scene. +It is also the place where you can access many common scene helper functions such as `create_timer`, `create_tween`, or calling the `quit()` function to exit the game. + +There are two ways to access the `SceneTree`: + +- Call the `get_tree()` method on the current node +- Use the `Get Scene Tree` visual script node + +Regardless of which approach is used, dragging away from the *output* pin will provide direct access to functions and properties on the godot `SceneTree` object. + +### Using the get_tree method + +The `get_tree()` method is accessible to an `Orchestration` as long as the base type you chose inherits from `Node`. +If you chose a type that inherits from `Control`, `Node2D`, or `Node3D`, then you can safely access `get_tree()`. + +1. Right-click the graph, opening the **All Actions** dialog. +2. Search for `Call Get Tree`, and select the `Call Get Tree` option by either pressing **Add** or hitting **Enter**. + +### Using the get scene tree node + +The **Get Scene Tree** node is another way to access the `SceneTree` from within an `Orchestration`. +This method is preferred and will work regardless of the base type chosen. + +1. Right-click the graph, opening the **All Actions** dialog. +2. Search for `Get Scene Tree` and select the `Call Get Scene Tree` option, either by pressing **Add** or hitting **Enter**. + +## Scene Tree properties + +There are no properties that can be modified in the **Inspector** view. +The **Get Scene Tree** node simply returns a reference to the `SceneTree` godot object as an *output* pin. + +## Instantiating scenes + +You may find you have the need to load a specific scene and attach the scene to the current scene. +This is often done when spawning in creatures, other players, or transitioning between scenes. + +In languages like `GDScript` or `C#`, the process to instantiate a scene first involves loading the scene from disk, and then creating an instance of the scene. +Orchestrator simplifies this in a single step using the **Instantiate Scene** node. + +
+ +To add an **Instantiate Scene** node to the graph: + +1. Right-click the graph and search for **Instantiate Scene**. +2. Select the `Instantiate Scene` option, and press **Add** or simply hit **Enter**. + +### Set what scene to load + +Setting which scene to load can be done by either pressing the **Assign...** button on the node itself or by selecting the `Scene` property in the **Inspector** view. +In both cases: + +1. Navigate through the **Select File** dialog, locating the scene you instantiate. +2. Select the file and press **Open** or simply double-click the scene file to select. + +Once the scene file is selected, the `Scene` property on the node and in the **Inspector** view will include the `res://` based path to the scene. + +## Instantiate scene properties + +To set the properties for the **Instantiate Scene** node, either modify the `Scene` property directly on the node or select the node and use the **Inspector** view to modify the `Scene` property. + +| Property | Description | +|:---------|:------------------------------------------------------------------------------------| +| Scene | Specifies the full `res://` based path to the scene file that will be instantiated. | + +* The `Scene` property can be set dynamically by assigning an connection to the `Scene` input pin that contains the full path to the scene to load. +* The *output* pin will refer to the root `Node` in the scene that was loaded. + +:::info +It is perfectly safe to connect the `Scene Root` *output* pin to other node input pins if necessary. +The same instantiated scene root will be returned rather than instantiating the scene for each node input. + +If used in a loop, a *new* scene will only be created when the *input* control flow pin is called. +::: \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/signals.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/signals.md new file mode 100644 index 0000000..da4ae0d --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/signals.md @@ -0,0 +1,133 @@ +--- +toc_max_heading_level: 4 +--- + +# Signals + +Godot implements the observer pattern using signals. +A signal represents a callback that any Godot `Object`, including an `Orchestration`, can connect to and react when the signal is fired. +In addition, signals can provide contextual information using function arguments. + +## Creating signals + +To create a new signal in an orchestration, follow these steps: + +1. Press the button on the **Signal** component view. +2. Enter a unique name when the new signal entry is added. +This is the name of the signal that parts of the orchestration as well as external Godot objects can connect and be notified when the signal is fired. + +## Renaming signals + +To rename a signal: + +1. Right-click the signal in the component panel, and select **Rename** in the context-menu. +
+2. Enter the new signal name in the text box and press **Enter**. +
+ +:::info +Any node in the current orchestration that refers to the signal will automatically update when the signal is renamed. +Any other external resource, including another Orchestration will not automatically update and will need to be changed after the signal is renamed. +::: + +## Deleting a signal + +To delete a signal: + +1. Select the **Signal** in the **Component** panel. +2. Right-click and select **Remove** in the context-menu. + +:::info +Removing a **Signal** will also remove all signal nodes that refer to that signal from the orchestration. +::: + +## Passing data with signals + +Signals can also pass additional data to their listeners (objects that are connected to the signal), much like how a caller passes arguments to a function call. +Each signal has a signature, much like a function, and when an `Object` connects to the signal, the function that is registered as the `Callable` for the signal must match the signal's argument signature. + +For example, a `CheckBox` emits both a `pressed` and a `toggled` signal. +The `pressed` signal does not pass any arguments, and so the callable will simply have an empty argument list. +An orchestration function that listens to `pressed` signals would look like, taking note that there are no arguments: + +```cpp +void _on_pressed() { +} +``` + +The `toggled` signal is different, it passes the current *toggled* state of the `CheckBox`, notifying the listener of the current checked state of the `CheckBox`. +An orchestration function that listens to `toggled` signals would look like: + +```cpp +void _on_toggled(bool p_new_checkbox_state) { +} +``` + +When you define a signal in Orchestrator, you can add arguments to the signal's signature in the **Inspector** view: + +1. Select the **Signal** in the **Component** panel. +2. Modify the `Argument Count` property, which defaults to `0` for no arguments. +3. Expand each argument added, `Argument 1`, `Argument 2`, and so on. +4. Modify the argument's `type` by selecting a type from the drop-down list. +For example, to pass a 3D object's position, you would select `Vector3`, as positions in 3D space are represented by a Vector with `x`, `y`, and `z` coordinates. +5. Customize the argument's `name` to better describe what the argument represents. +For example, to pass a 3D object's position, you might set the name to `position`. + +## Emit a signal + +When a signal is emitted or fired, this notifies any connected observers that some condition has occurred. +The notification to all observer `Callable` functions happens within the main thread, synchronously. + +### How to emit a signal + +To emit a signal within an Orchestration: + +1. Select the desired **Signal** from the **Component** view. +2. Drag the **Signal** onto the graph. +3. Releasing the mouse button will spawn an **Emit Signal** node. +4. Connect the execution pin with other nodes so that the signal is fired when needed. +5. If the **Signal** defines any arguments, connect any input arguments. + +### Emit signal properties + +You can set all the properties for a signal in the **Inspector** panel. + +| Property | Description | +|:------------------|:----------------------------------------------------------------------------------------------------------------| +| Argument Count | Specifies the number of arguments that the signal includes, defaults to `0`. | +| Argument `n` Type | Specifies the n-th argument's type.
Only connections that match the type can be connected to the input pin. | +| Argument `n` Name | Specifies the n-th argument's name, which can better describe what the argument represents. | + +:::info +Each argument defined in the **Inspector** view will be represented as an input pin on the **Emit Signal** node in the graph. +::: + +:::warning +Reducing the number of signal arguments will automatically disconnect any connections in the graph to that argument pin. +In the event you accidentally reduce the number of arguments and break a connection, be sure to reconnect the pins after adjusting the argument count. +::: + +## Await a signal + +There are situations where you may need to make use of a coroutine, which allows the current execution of the code to temporarily yield until some condition is met before continuing the code continues where it left off. +This technique is quite powerful as it simplifies the logic needed to yield and wait for that condition. +In Godot, coroutines work in conjunction with signals. + +### How to await a signal + +To asynchronously wait for a signal to be fired: + +1. Right-click the graph and search for `Await Signal` in the **All Actions** dialog. +2. Select `Await Signal` and press the **Add** button or simply press **Enter**. +3. Connect the execution pins with other nodes to that the *await* is called when needed. +4. Connect to manually assign the name of the signal to the `Signal Name` input pin. +5. Connect a reference to the object that emits the signal to the `Target` pin, which defaults to the current orchestration. + +### Await signal properties + +There are no properties in the **Inspector** view that can be modified for the **Await Signal** node; however, there are two input pins that can be customized on the node in the graph. + +| Input | Description | +|:------------|:-----------------------------------------------------------------------------------| +| Target | Specifies the object that the orchestration should connect to and wait. | +| Signal Name | Specifies the name of the signal that the target that the orchestration will wait. | diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/singletons.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/singletons.md new file mode 100644 index 0000000..7d142ee --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/singletons.md @@ -0,0 +1,102 @@ + +# Singletons + +A singleton represents a Godot object where there is only a single instance of that object present in your game. +The Godot engine provides dozens of singletons for various purposes. +In addition, user code can also add and register their own singletons that can be accessed globally. +To add a singleton reference to a script, place an **Engine Singleton** node onto the graph. + +## Singleton types + +By default, Godot provides dozens of singletons, each providing access to very specific features. +These singletons are registered by a unique name and can be referenced using that name. +The Godot provided singletons are: + +| Singleton Name | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------| +| AudioServer | Server interface for low-level audio access. | +| CameraServer | Server keeping track of different cameras accessible in Godot. | +| ClassDB | A class information repository. | +| DisplayServer | A server interface for low-level window management. | +| EditorInterface | Godot editor's interface. | +| Engine | Provides access to engine properties. | +| EngineDebugger | Exposes the internal debugger. | +| GDExtensionManager | Provides access to GDExtension functionality. | +| GDScriptLanguageProtocol | - | +| Geometry2D | Provides methods for some common 2D geometric operations. | +| Geometry3D | Provides methods for some common 3D geometric operations. | +| Input | A singleton for handling inputs. | +| InputMap | A singleton that manages all `InputEventAction`s. | +| IP | Internet protocol (IP) support functions such as DNS resolution. | +| JavaClassWrapper | - | +| JavaScriptBridge | Singleton that connects the engine with the browser's JavaScript context in Web export. | +| Marshalls | Data transformation (marshalling) and encoding helpers. | +| NativeMenu | A server interface for OS native menus. | +| NavigationMeshGenerator | Helper class for creating and clearing navigation meshes. | +| NavigationServer2D | A server interface for low-level 2D navigation access. | +| NavigationServer3D | A server interface for low-level 3D navigation access. | +| OS | Provides access to common operating system functionalities. | +| Performance | Exposes performance-related data. | +| PhysicsServer2D | A server interface for low-level 2D physics access. | +| PhysicsServer2DManager | A singleton for managing `PhysicsServer2D` implementations. | +| PhysicsServer3D | A server interface for low-level 3D physics access. | +| PhysicsServer3DManager | A singleton for managing `PhysicsServer3D` implementations. | +| ProjectSettings | Stores globally-accessible variables. | +| RenderingServer | Server for anything visible. | +| ResourceLoader | A singleton for loading resource files. | +| ResourceSaver | A singleton for saving `Resource`s to the filesystem. | +| ResourceUID | A singleton that manages the unique identifiers of all resources within a project. | +| TextServerManager | A singleton for managing `TextServer` implementations. | +| ThemeDB | A singleton that provides access to static information about `Theme` resources used by the engine and by your project. | +| Time | A singleton for working with time data. | +| TranslationServer | A server responsible for language translations. | +| WorkerThreadPool | A singleton that allocates some `Thread`s on startup, used to offload tasks to these threads. | +| XRServer | Server for AR and VR features. | + +## Selecting the singleton + +Once an **Engine Singleton** node has been placed onto the graph canvas, it will default to the `Engine` singleton. +To change which singleton you want to access: + +1. Select the **Singleton** node in the graph. +2. Select the designed choice in the **Inspector** view for the `Singleton` property. +
+ +## Accessing singleton functions + +Godot singletons provide access to commonly used functions, such as `Time.get_unix_time_from_system()`. +To access singleton functions, simply: + +1. Drag the mouse away from the output pin on the **Engine Singleton** node. +2. When releasing the mouse, the **All Actions** dialog will show. +3. Search for the desired function, i.e. `get unix time from system` +4. Select the function and press `Add` or hit `Enter` to place the function onto the graph. + +## Registering a user-defined singleton + +In addition to the singletons that are provided by Godot, users can also add their own singletons. +When a singleton is added, it's expected that you guarantee that the instance remains valid until the singleton is unregistered. +If a registered singleton is deleted before it's removed, the editor or game will likely crash. + +To add a user-defined singleton using Orchestrator: + +1. Place an **Engine Singleton** node that refers to the `Engine` singleton onto the graph. +2. Drag the mouse away from the output pin. +3. In the **All Actions** dialog, search for `register` and select `Call Register Singleton`. +4. Provide a unique name to register the singleton instance with, i.e. `MySingleton`. +5. With a reference to your singleton object, connect the reference to the `instance` input pin. + +:::info +User-defined singletons are registered dynamically at runtime, and therefore are not accessible using the **Engine Singleton** node. +To access a user-defined singleton, use the **Engine Singleton** node calling the `Call Get Singleton` function to obtain a reference at runtime. + +For most cases, it may be simpler to use an **Autoload** node instead, since autoloads are registered in the **Project Settings** and are directly selectable in the **Inspector** view when selecting the **Autoload** node. +You also won't need to worry about unregistering the **Autoload** as Godot will handle this automatically. +::: + +To unregister a user-defined singleton using Orchestrator: + +1. Place an **Engine Singleton** node that refers to the `Engine` singleton onto the graph. +2. Drag the mouse away from the output pin. +3. In the **All Actions** dialog, search for `unregister` and select `Call Unregister Singleton`. +4. Provide the registered singleton's name in the `name` input pin. \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes/variables.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/variables.md new file mode 100644 index 0000000..e017161 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes/variables.md @@ -0,0 +1,181 @@ +--- +toc_max_heading_level: 4 +--- + +# Variables + +**Variables** are properties that hold a value or reference to an Object in your game. +These properties can be accessible internally to the `Orchestration` that contains them, or can accessible externally so that their values can be modified by designers working with instances of the orchestration attached on scene nodes. + +## Variable Types + +Variables can be created using a variety of different types, including data types such as Boolean, Integer, or Float, but can also reference types for holding more complex values like Objects, Nodes, Resources, or other named types. +Arrays, Dictionaries, and specialized Packed-Arrays can be created too. +Each type is specifically color coded for easy identification: + +| Variable Type | Color | Icon | Represents | +|:-------------------|:---------------------------------------------------:|:---------------------------------------:|:---------------------------------------------------------------| +| Boolean | | | True or false value (`bool`). | +| Integer | | | Signed 64-bit value between `-2^63` and `2^63-1`. | +| Float | | | Signed 64-bit double-precision floating-point number. | +| String | | | Group of alphanumeric characters, such as `Hello World`. | +| StringName | | | An immutable string that is faster to compare than `String`. | +| Rect2 | | | 2D axis-aligned bounding box using floating-point coordinates. | +| Rect2i | | | 2D axis-aligned bounding box using integer coordinates. | +| Vector2 | | | 2D vector using floating-point coordinates. | +| Vector2i | | | 2D vector using integer coordinates. | +| Vector3 | | | 3D vector using floating-point coordinates. | +| Vector3i | | | 3D vector using integer coordinates. | +| Vector4 | | | 4D vector using floating-point coordinates. | +| Vector4i | | | 4D vector using integer coordinates. | +| Transform2D | | | 2x3 matrix representing a 2D transformation. | +| Transform3D | | | 3x4 matrix representing a 3D transformation. | +| Plane | | | A plane in Hessian normal form. | +| Quaternion | | | Represents 3D rotations. | +| AABB | | | 3D axis-aligned bounding box. | +| Basis | | | 3x3 matrix for representing 3D rotation and scale. | +| Projection | | | 4x4 matrix for 3D projective transformations. | +| Color | | | RGBA color. | +| NodePath | | | Pre-parsed scene tree path, can be relative or absolute. | +| RID | | | Handle for a `Resource`'s unique identifier. | +| Object | | | Base class for all classes in the Godot engine. | +| Dictionary | | | Container that holds key-value pairs. | +| Array | | | Container that holds a sequence of elements. | +| Callable | | | Represents a method or a standalone function callback. | +| PackedByteArray | | | Packed array of byte values. | +| PackedStringArray | | | Packed array of `String` values. | +| PackedInt32Array | | | Packed array of 32-bit integer values. | +| PackedInt64Array | | | Packed array of 64-bit integer values. | +| PackedFloat32Array | | | Packed array of 32-bit floating-point values. | +| PackedFloat64Array | | | Packed array of 64-bit floating-point values. | +| PackedVector2Array | | | Packed array of `Vector2` values. | +| PackedVector3Array | | | Packed array of `Vector3` values. | +| PackedColorArray | | | Packed array of `Color` values. | + +:::info +We are aware that variables cannot be assigned to all Godot engine values, such as enumerations. +We are also aware that exporting of certain variables as *flags* and *enumerations* also is not available. +There is currently an upcoming fix to introduce a revamped **Variable** UI to allow defining variables of any Godot type more easily. +::: + +:::tip +Connection colors can be adjusted in the `Project > Project Settings > Orchestrator > UI` section. +::: + +## Exported variables + +For a variable to be modified from outside the orchestration, it must be **exported**. + +
+ +Variables in the component panel are private by default, using the . +By clicking the eye icon or selecting the variable and toggling the **Exported** property in the **Inspector** view, the variable can be made accessible from outside the orchestration, using the icon . + +Once a variable has been exported, if the orchestration is attached to any scene nodes, the value of the variable can be initialized for each specific scene node that the orchestration is attached separately. + +
+ +This allows for creating orchestrations with unique behaviors and reusing that behavior on different nodes, but allowing each node to work differently based on unique per-node configurable values. + +## Private variables + +By default, a variable is private, or *not exported*. +Private variables are those that can be modified from within the owning orchestration graphs; however, are not accessible from external actors such as `C#`, `GDScript`, or other orchestrations. +You can determine whether a variable is private if it has the icon next to its name in the **Component** view. + + +
+
+ + +## Variable descriptions + +While Orchestrator allows you to define a variable description, these descriptions are only for informational purposes. +At this time, these descriptions are not exposed in the tooltips for exported variables; however, this is planned for a future patch. + +## Promoting to variable + +Variables can also be created automatically by using the **Promote to Variable** context-menu option. +Right-click any input or output data pin on an orchestration node and select **Promote to Variable**. + +
+ +## Accessing variables + +When working with variables in an orchestration, you will access them in one of two ways: by using the **Get** node (referred to as a Getter or Accessor) to get the value of the variable or by using the **Set** node (referred to as a Setter or Mutator) to set the value of the variable. + + +
Get the value of variable speed
+
Set the value of variable speed
+ + +You can create a **Set** node or a **Get** node for a variable by right-clicking in the graph and typing either **Set (variable name)** or **Get (variable name)**. +Another method is to drag and drop the variable onto the graph canvas, selecting to spawn either a **Set** or **Get** node. + +## Editing variables + +Variable values can be set either as part of the orchestration's node graph or as a default value in the **Inspector** view. +When setting a default value on an *exported* variable, the default value will be overridden if the scene node that the orchestration is attached specifies a custom value in the **Inspector**. +To set variable default values: + +1. Click the variable in the component panel. +2. In the **Inspector** view, modify the value associated with the **Default Value** property. + +:::tip +Not all variable types allow specifying default values. +For example, if the variable represents a `Node` or a Godot `Object` type, then the default value property won't be available. +::: + +## Renaming variables + +To rename a variable: + +1. Right-click the variable in the component panel, and select **Rename** in the context-menu. +
+2. Enter the new variable name in the text box and press **Enter**. +
+ +:::info +Any **Get** or **Set** node already in any graph will automatically update when the variable is renamed. +::: + +## Variable properties + +You can set all the properties for a variable in the **Inspector** panel. +Some variables may have more or less properties than others, depending on the variable's type. + +| Property | Description | +|:--------------|:----------------------------------------------------------------------------------------------------------------------------| +| Name | The name of the variable, can only be changed from the component panel. | +| Category | The logical group the variable belongs. Setting this to an empty string or `Default` implies the variable is uncategorized. | +| Type | Specifies the type the variable represents. | +| Exported | Toggles whether the variable is publically accessible outside the Orchestration when checked. | +| Default Value | For many variable types, sets an initial, default value assigned to the variable when the orchestration is created. | +| Description | Specifies a custom description that describes the variable, its purpose, and usage. | + +## Getting and setting variable values + +Variables can also be edited as part of your orchestration graphs by using the **Get** and **Set** nodes. +The easiest way to create them is by dragging a variable from the component panel onto the graph. +A small context-menu will appear asking if you would like to create a **Get** or **Set** node. + +
+ +### Get nodes + +A variable **Get** node returns the variable's value to in the orchestration. +Once created, these nodes can be plugged into any node that takes the appropriate variable type. + +
+ +### Set nodes + +A variable **Set** node changes the value stored in the variable. +Note that these must be called by an execution pin in order for the node to execute and set the variable's value. + +
+ +## Shortcuts when dragging + +* **Ctrl-drag**: Creates a **Get** node +* **Alt-drag**: Creates a **Set** node