ue5coro

UE5Коро

UE5Coro реализует поддержку сопрограмм C++20 для Unreal Engine 5 с упором на логику игрового процесса, удобство и обеспечение плавной интеграции с движком.

Примечание

Поддержка C++17, более старых компиляторов, платформ и версий движка доступна в устаревшей серии UE5Coro 1.x.

Имеется встроенная поддержка для удобного создания скрытых UFUNCTION. Измените тип возвращаемого значения скрытой функции UFUNCTION, чтобы сделать ее сопрограммой, и вы бесплатно получите весь шаблон FPendingLatentAction с поддержкой многопоточности, безопасной для BP:

 UFUNCTION (BlueprintCallable, meta = (Latent, LatentInfo = LatentInfo))
FVoidCoroutine Example(FLatentActionInfo LatentInfo)
{
    UE_LOGFMT (LogTemp, Display, " Started " );
    co_await UE5Coro::Latent::Seconds ( 1 ); // Does not block the game thread!
    UE_LOGFMT (LogTemp, Display, " Done " );
    co_await UE5Coro::Async::MoveToThread (ENamedThreads::AnyThread);
    auto Value = HeavyComputation ();
    co_await UE5Coro::Async::MoveToGameThread ();
    UseComputedValue (Value);
}

Эта сопрограмма будет автоматически отслеживать свой целевой UObject в разных потоках, поэтому даже если объект-владелец будет уничтожен до завершения, он не выйдет из строя из-за того, this висит в игровом потоке.

Даже тип возвращаемого значения сопрограммы скрыт от BP, чтобы не беспокоить дизайнеров:

Вас не интересуют скрытые ФУНКЦИИ? Это не проблема. Также поддерживаются сопрограммы Raw C++ с тем же набором функций. Реализация поддержки выбирается во время компиляции; скрытые действия создаются только в том случае, если вы их действительно используете.

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

• Нравится удобство LoadSynchronous, но нет недостатков?
  UObject* HardPtr = co_await AsyncLoadObject(SoftPtr); позволяет вам сохранить только преимущества (и ваш FPS).
• А как насчет распределения тяжелых вычислений на несколько тиков?
  Добавьте co_await NextTick(); внутри цикла, и все готово. Существует класс бюджета времени, который позволяет вам напрямую указать желаемое время обработки и позволить сопрограмме динамически планировать себя.
• Говоря о динамическом планировании, регулирование может быть таким простым:
  co_await Ticks(bCloseToCamera ? 1 : 2);
• Зачем распределять время в игровом потоке, если у вас есть несколько ядер процессора, готовых работать?
  Добавьте co_await MoveToTask(); в вашу функцию, и все, что после этой строки, будет выполняться в системе UE::Tasks в рабочем потоке.
  
• Хотите вернуться? Это co_await MoveToGameThread(); .
  Вы можете произвольно перемещаться между потоками, а скрытые сопрограммы UFUNCTION автоматически возвращаются в игровой поток, когда они завершают работу, чтобы возобновить BP.
• Все еще не убеждены? Вот как запустить всю временную шкалу:
  co_await Timeline(this, From, To, Duration, YourUpdateLambdaGoesHere);
• Трудно угодить? Вот как вы можете асинхронно ожидать делегата DYNAMIC, не записывая UFUNCTION только для AddDynamic/BindDynamic, не находясь в UCLASS или вообще в любом классе:
  co_await YourDynamicDelegate; (это весь код)
• О, вам нужны параметры с этим делегатом?
  auto [Your, Parameters] = co_await YourDynamicDelegate;

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

Попрощайтесь с достаточно хорошим на данный момент™ LoadSynchronous, который все еще находится в продаже, двумя обновлениями позже. Поскольку задача уменьшена с «написать весь шаблон StreamableManager и переместить часть вызывающей функции в обратный вызов» до просто «поставить перед ней co_await», вы закончите быстрее, чем потребовалось бы, чтобы начать работу. с обоснованием того, почему версия с синхронной блокировкой почему-то приемлема.

В плагине есть множество дополнительных функций, таких как генераторы, которые позволяют вам не выделять весь TArray только для возврата переменного количества значений. Вам проще писать, проще оптимизировать компилятору, вам нужна только память O(1) вместо O(N) для N элементов, что вам не нравится?

Список функций

Следующие ссылки приведут вас на соответствующие страницы документации. Добавьте этот раздел в закладки, если предпочитаете читать новейшую документацию в браузере или прямо из IDE. Каждая функция API документирована в заголовках C++, а выпуски содержат исходный код документации Markdown, которую вы сейчас читаете.

Создание сопрограмм

Эти функции направлены на предоставление доступа к сопрограммам остальной части движка.

• Сопрограммы (очевидно)
  • Служба поддержки отмены имеет собственную страницу.
• Генераторы
• Интеграция системы способностей игрового процесса работает немного по-другому.

Нереальная интеграция

Эти оболочки предоставляют удобные способы использования функций движка из ваших сопрограмм.

• Интеграция искусственного интеллекта (MoveTo, поиск пути...)
• Анимация-ожидающие (монтажи, уведомления...)
• Асинхронные ожидания (многопоточность, синхронизация...)
• HTTP (асинхронные HTTP-запросы)
• Неявные ожидания (некоторые типы движков напрямую co_awaitable, без оберток)
• Скрытые ожидающие (взаимодействие с игровым потоком, задержка...)
  • Загрузка ресурсов (асинхронная загрузка мягких указателей, пакетов...)
  • Асинхронные запросы на столкновение (трассировка линий, проверка перекрытия...)
  • Латентная цепочка (универсальная обертка скрытого действия)
  • Тиковый временной бюджет (выполняется в течение x мс на кадр)
• Скрытые обратные вызовы (взаимодействие с менеджером скрытых действий)

Примечание

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

Чаще всего это не проблема: например, безымянный временный объект в co_await Something() не появляется в исходном коде. Если необходимо сохранить возвращаемое значение Private , используйте auto (или ограниченное TAwaitable auto ), чтобы не писать имя типа.

Непосредственный вызов общедоступных ожидаемых функций C++ await_ready , await_suspend и await_resume не поддерживается ни в одном awaiter.

Дополнительные возможности

• Совокупные ожидающие (WhenAny, WhenAll, Race...)
• Скрытые временные рамки (плавная интерполяция по такту)
• Потоковые примитивы (семафоры, события...)

Установка

Поддерживаются только пронумерованные выпуски. Не используйте ветки Git напрямую.

Загрузите выбранную вами версию и распакуйте ее в папку «Плагины» вашего проекта. Переименуйте папку просто в UE5Coro без номера версии. Если все сделано правильно, у вас должен получиться YourProjectPluginsUE5CoroUE5Coro.uplugin .

Примечание

Пожалуйста, обратитесь к собственному README релиза, если вы используете 1.x. У него был другой метод установки с использованием нескольких плагинов.

Настройка проекта

В вашем проекте могут использоваться некоторые устаревшие настройки, которые необходимо удалить, чтобы разблокировать поддержку C++20, которая в противном случае входит в стандартную комплектацию новых проектов, созданных на Unreal Engine 5.3 или более поздней версии.

Убедитесь, что в ваших файлах Target.cs (всех) используются последние настройки и указана версия заказа:

 DefaultBuildSettings = BuildSettingsVersion . Latest ;
IncludeOrderVersion = EngineIncludeOrderVersion . Latest ;

Если вы используете устаревший флаг bEnableCppCoroutinesForEvaluation , он больше не нужен, и его больше не следует включать явно; это может вызвать проблемы. Рекомендуется удалить все ссылки на него из файлов сборки.

Если вы устанавливаете для CppStandard значение CppStandardVersion.Cpp17 в файле Build.cs... не делайте этого :)

Использование

Ссылайтесь на модуль "UE5Coro" из вашего Build.cs, как и на любой другой модуль C++, и используйте #include "UE5Coro.h" . Сам плагин включать не нужно.

Некоторые функциональные возможности находятся в дополнительных модулях, на которые необходимо ссылаться отдельно. Например, для поддержки системы игровых возможностей требуется "UE5CoroGAS" в Build.cs и #include "UE5CoroGAS.h" . Базовый модуль UE5Coro зависит только от модулей ядра, которые включены по умолчанию.

Важный

Не #включайте напрямую какой-либо другой заголовок, а только тот, который соответствует имени модуля. Известно, что основные IDE, используемые с Unreal Engine, неправильно отображают предложения заголовков. Если вы добавите UE5Coro.h в свой PCH, вы сможете сделать его доступным повсюду.

Обновления

Для обновления удалите UE5Coro из папки «Плагины» вашего проекта и установите новую версию, следуя инструкциям выше.

Упаковка

Упаковка UE5Coro отдельно (из окна «Плагины») не требуется и не поддерживается.

Удаление

Чтобы удалить плагин из проекта, переопределите все сопрограммы без его функциональности, удалите все ссылки на плагин и его модули и добавьте основное перенаправление из /Script/UE5CoroK2.K2Node_UE5CoroCallCoroutine в /Script/BlueprintGraph.K2Node_CallFunction .