Система компонентов C#

Система компонентов позволяет реализовать логику приложения с помощью набора строительных блоков — компонентов — и назначать эти блоки нодам, предоставляя им дополнительную функциональность. Комбинируя эти маленькие и простые блоки, вы можете создать очень сложную логическую систему.

Логический компонент объединяет ноду и класс C#, содержащий логическую реализацию (действия, которые необходимо выполнить), определяющий набор дополнительных параметров, которые будут использоваться.

Компоненты, назначенные на ноду

Компоненты дают вам больше гибкости в реализации вашей логики, позволяя:

• управлять тем, какие части кода (реализованные как методы компонентов) должны выполняться, а какие нет;
• контролировать порядок выполнения этих частей кода;
• неоднократно использовать части кода, написанные один раз, для любого количества объектов без каких-либо изменений. Если вы хотите изменить свой код, вы меняете его в одном-единственном источнике (как в случае с NodeReference, если сравнивать с контентом);
• объединять определенные части кода, которые будут выполняться для определенных нод. Можно создать очень сложную систему из множества маленьких и простых блоков (это как использовать NodeReference для построения большой сложной структуры из множества простых нод).

Перед тем как начать писать код, нужно установить необходимое программное обеспечение .

Дополнительная информация#

Для организации рабочего процесса программирования и создания проектов на основе .NET необходимо следующее:

• .NET SDK (для Windows и Linux)

• IDE или текстовый редактор. Проверяется совместимость различных IDE со следующими версиями .NET:

  IDE	Поддерживаемая версия .NET
  MS Visual Studio Code	8.0.x
  MS Visual Studio 2022	8.0.x

  Примечание

  Visual Studio Code — рекомендуемый вариант.

Если вы работаете с MS Visual Studio Code, установите расширение C# для Visual Studio Code от OmniSharp при первом открытии компонента.

В случае возникновения каких-либо проблем с .NET, обратитесь к разделу "Устранение неполадок" в статье Проблемы с .NET.

Компоненты создаются в Редакторе. В Asset Browser нажмите правую кнопку мыши и выберите Create Code -> C# Component.

Укажите имя компонента в диалоговом окне, после чего в текущем каталоге браузера ассетов будет создан скриптовый файл C# с соответствующим именем.

Дважды щелкните на новом скриптовом файле, чтобы открыть его для редактирования логики компонента в IDE по умолчанию.

Внимание

Не создавайте компоненты в подключаемых папках.

Переименование компонентов#

По сути, компоненты — это классы C#, унаследованные от базового класса Component.

Работа системы компонентов C# основана на свойствах . Когда вы создаете новый компонент, он автоматически регистрируется в Системе компонентов и создается внутреннее runtime-свойство и связывается с компонентом через GUID. Для правильной работы компонента необходим следующий атрибут класса Component.

[Component(PropertyGuid = "2ae011355ed7f110a202912faa000cc22276e539")]

Внимание

Значение атрибута Component нельзя изменять.

Компоненты C# перечислены в иерархии Properties, изначально они унаследованы от базового свойства C# Components.

Примечание

Общее автоматическое наследование компонентов не поддерживается, вы можете получить логическую реализацию из произвольного компонента вручную, унаследовав его класс от класса родительского компонента.

Простое наследование#

Логика#

Логика компонентов реализована с помощью набора методов, которые вызываются соответствующими функциями скрипта world:

• Init() — создаются и инициализируются все необходимые ресурсы.

• UpdateAsyncThread() — указываются все логические функции, которые вы хотите вызывать в каждом кадре независимо от потока рендеринга.

  Примечание

  Этот метод не имеет защитных блокировок, поэтому не рекомендуется изменять другие компоненты внутри этого метода, если вы не уверены, что эти компоненты не будут изменены или удалены где-либо еще.

• UpdateSyncThread() — указываются все параллельные функции логики, которые вы хотите выполнить перед Update (). Этот метод можно использовать для выполнения некоторых ресурсоемких вычислений, таких как поиск пути, генерация процедурных текстур и т.д.

  Примечание

  Этот метод следует использовать для вызова только тех методов API, которые относятся к текущей ноде: самой ноде, ее материалам и свойствам.
• Update() — указываются все логические функции, которые должны вызываться в каждом кадре.
• PostUpdate() — корректируется поведение в соответствии с обновленными состояниями нод в том же кадре.
• UpdatePhysics() — выполняется симуляция физики: выполнение непрерывных операций (продвижение машины вперед в зависимости от оборотов двигателя, имитация постоянного ветра, выполнение немедленных реакций на столкновение и т. д.).

• Swap() — работа с результатами метода updateAsyncThread() — все остальные методы (потоки) уже выполнены и ждут. После этой функции происходит только два действия:

  • все объекты, поставленные в очередь на удаление, удаляются;
  • выполняется обновление Профайлера.
• Shutdown() — выполняется очистка при выключении компонента.

Примечание

Вы можете создать несколько методов для каждого этапа (например, несколько методов Update() или только один Init () ).

Внимание

Методы UpdateAsyncThread(), UpdateSyncThread() и UpdatePhysics() позволяют вызывать только потокобезопасные функции движка.

Параметры#

public int public_field;

private int private_field;

[ShowInEditor]
private float private_editable_field;

[HideInEditor]
public float public_hidden_field;

Логическая реализация, описанная в компоненте, активна во время выполнения, только если компонент назначен на ноду, и обе ноды и компонент включены.

Есть несколько способов применения компонента к ноде:

• Выберите ноду, щелкните Add New Property и введите имя ассета *.cs в разделе Node Properties вкладки Node. Вы можете сделать это, перетащив туда ассет *.cs из окна Asset Browser.

  

  Также поддерживается перетаскивание на ноду в окне просмотра редактора.

  

• Добавьте компонент к ноде с помощью кода, используя функции ноды AddComponent<T>(Node node) и AddComponent<T>().

NewComponent component = AddComponent<NewComponent>(node);

NewComponent component = node.AddComponent<NewComponent>();

Логика определенного компонента применяется только тогда, когда компонент и соответствующая нода включены. Таким образом, при необходимости вы можете включать/отключать логику каждого конкретного компонента во время выполнения.

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

Компоненты могут взаимодействовать с другими компонентами и нодами.

Чтобы запустить проект, нажмите кнопку Play на панели инструментов. Это запустит экземпляр приложения в отдельном окне.

Примечание

Вы увидите зеленое уведомление об успешной компиляции, а красное сигнализирует об обнаружении ошибок. При нажатии на красное сообщение в консоли отображаются сведения. Все ошибки компиляции и выполнения C#-кода отображаются в консоли.
Чтобы в Windows сообщения об ошибках отображались корректно, язык для программ, не поддерживающих Юникод, должен быть таким же, как текущий языковой стандарт системы.

В списке доступны пресеты пользовательских параметров запуска. По умолчанию выставлен пресет Default (Debug) со стандартными параметрами запуска. Нажмите на значок шестеренки, чтобы настроить текущий выбранный пресет пользовательских параметров запуска.

В открывшемся окне доступны следующие варианты запуска:

Конфигурация	Используемая сборка UNIGINE Engine
Video API	Графический API, используемый для рендеринга: DirectX Vulkan
Resolution	Размер экрана
Fullscreen	Настройка полноэкранного режима, запуск экземпляра в одном из следующих режимов: Disable — отключен, приложение запускается в оконном режиме Enable — включен, приложение запускается в полноэкранном режиме Borderless Window — приложение запускается в режиме без границ — полнооконном режиме, когда окно приложения отображается без дополнительных элементов
VR Mode	Включить совместимость с одной из поддерживаемых гарнитур VR: Disable — отключить Vive Oculus
Video Debug	Включает контекст отладки Vulkan или DirectX: Disable — отключить Messages Asserts
Materials Loading Mode	Выбор режима загрузки материалов: Fastest Start — минимальное потребление памяти и максимальная скорость загрузки двигателя. Рекомендуется для быстрых итераций на этапе разработки приложения. Full Materials — немного медленнее загружается при запуске движка и используется больше памяти, чем в первом режиме, но меньше скачков. Может использоваться для небольшого проекта с небольшим количеством материалов (в случае удовлетворительной производительности и достаточного объема памяти). Full Materials + Compile Shaders + Load Shaders — этот режим обеспечивает стабильную работу и значительное уменьшение скачков, но требует много памяти и увеличивает время загрузки при запуске. Рекомендуется для фазы производства (когда вы передаете свое приложение конечному пользователю).
Run Current World	Запуск текущего мира, открытого в редакторе, независимо от того, какой мир по умолчанию установлен логикой.
Arguments	Набор параметров командной строки запуска .

При изменении любого пользовательского параметра запуска и закрытии окна в зависимости от выбранной предустановки будут выполнены следующие действия:

• Если в списке выбрана предустановка Default (Debug), в текущей папке браузера ассетов будет создан новый файл ассетов *.launch , содержащий настраиваемые параметры запуска. Соответствующий пресет будет доступен в списке пресетов.
• Если выбран другой пресет, к нему будут применены изменения.

Примечание

Вы можете переименовывать и удалять предустановки пользовательских параметров запуска, переименовывая и удаляя соответствующие ассеты *.launch.

UnigineEditor автоматически перекомпилирует компоненты C# по мере того как вы вносите изменения в код, сохраняете их и возвращаетесь в редактор. Вы увидите зеленое уведомление об успешной компиляции, а красное сигнализирует об обнаружении ошибок. При нажатии на красное сообщение в консоли отображаются подробные сведения.

Вы можете проверить исходный код компонентов C# во время работы вашего приложения, независимо от того, запущено ли приложение с помощью кнопки Play прямо в UnigineEditor или создано и запущено из IDE.

Подробности см. в статье Отладка компонентов C# .

Чтобы создать отладочную или финальную сборку вашего приложения C#, используйте опцию File -> Create Build, доступную в UnigineEditor.

Подробности см. в статье Финальная сборка проекта для публикации .

В качестве примера, можно использовать компоненты для реализации логики преследования врагами в вашей игре: независимо от их размера, формы, скорости, все они будут проверять позицию игрока и пытаться найти путь, по которому можно максимально быстро дойти до игрока. Код будет по большей части одинаковым, могут различаться лишь параметры (скорость, меш и, возможно, звуки), поэтому можно добавить все эти параметры в компонент (чтобы можно было изменять их в любое время) и в код соответствующего класса компонента (например, добавление врагов в мире в методе Init() и преследование игрока в методе Update()).

Затем нужно просто назначить компонент всем объектам врагов и настроить параметры (определить меши, звуки и т. д.). Система компонентов сделает все остальное: выполнит ваш код на соответствующих этапах основного цикла Engine для всех объектов врагов, используя их конкретные параметры. Если вы впоследствии захотите изменить код, это можно сделать в одном единственном месте — классе компонента.

Интеграция с инструментом Microprofile позволяет контролировать общую производительность системы компонентов, а также добавлять необходимую информацию по компонентам.