ue5coro

UE5Coro

UE5Coro implementa suporte a corrotina C++20 para Unreal Engine 5 com foco na lógica de jogo, conveniência e fornecimento de integração perfeita com o mecanismo.

Observação

O suporte para C++17, compiladores, plataformas e versões de mecanismo mais antigos está disponível na série UE5Coro 1.x legada.

Há suporte integrado para fácil criação de UFUNCTIONs latentes. Altere o tipo de retorno de um UFUNCTION latente para torná-lo uma corrotina e você obterá todo o padrão FPendingLatentAction gratuitamente, com suporte multithreading seguro para BP pronto para uso:

 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);
}

Esta corrotina rastreará automaticamente seu UObject alvo entre threads, portanto, mesmo que seu objeto proprietário seja destruído antes de terminar, ele não travará devido a um this pendurado no thread do jogo.

Até mesmo o tipo de retorno da corrotina fica oculto do BP para não atrapalhar os projetistas:

Não está interessado em FUNÇÕES latentes? Não é um problema. Corrotinas Raw C++ também são suportadas, com exatamente o mesmo conjunto de recursos. A implementação de apoio é selecionada em tempo de compilação; ações latentes só são criadas se você realmente as usar.

Altere seu tipo de retorno para um dos tipos de corrotina fornecidos por este plug-in, e tarefas assíncronas complexas que seriam complicadas de implementar por conta própria tornam-se linhas simples triviais que Just Work™, eliminando a necessidade de retornos de chamada e outros manipuladores.

• Aproveitando a conveniência do LoadSynchronous, mas não as desvantagens?
  UObject* HardPtr = co_await AsyncLoadObject(SoftPtr); permite que você mantenha apenas os benefícios (e seu FPS).
• Que tal espalhar uma computação pesada por vários ticks?
  Adicione uma co_await NextTick(); dentro de um loop e pronto. Há uma classe de orçamento de tempo que permite especificar diretamente o tempo de processamento desejado e permitir que a corrotina se programe dinamicamente.
• Falando em agendamento dinâmico, a otimização pode ser tão simples quanto isto:
  co_await Ticks(bCloseToCamera ? 1 : 2);
• Por que reduzir o tempo no thread do jogo quando você tem vários núcleos de CPU ansiosos para trabalhar?
  Adicione co_await MoveToTask(); à sua função, e tudo após essa linha será executado dentro do sistema UE::Tasks em um thread de trabalho.
  
• Quer voltar? É co_await MoveToGameThread(); .
  Você está livre para mover-se arbitrariamente entre threads, e as corrotinas UFUNCTION latentes voltam automaticamente para o thread do jogo quando terminam de retomar o BP.
• Ainda não está convencido? Veja como executar uma linha do tempo inteira:
  co_await Timeline(this, From, To, Duration, YourUpdateLambdaGoesHere);
• Difícil de agradar? Veja como você pode esperar de forma assíncrona por um delegado DYNAMIC sem escrever um UFUNCTION apenas para AddDynamic/BindDynamic, ou estar em um UCLASS, ou qualquer classe:
  co_await YourDynamicDelegate; (esse é o código inteiro)
• Ah, você queria parâmetros com aquele delegado?
  auto [Your, Parameters] = co_await YourDynamicDelegate;

Isso deve dar uma ideia da redução significativa de código e esforço que é possível com este plugin. Código menor e mais simples de escrever geralmente se traduz em menos bugs, e o código assíncrono sendo fácil de escrever significa que não há atrito quando se trata de fazer as coisas da maneira certa, imediatamente.

Diga adeus ao LoadSynchronous, bom o suficiente por enquanto, que ainda está em envio, duas atualizações depois. Com a tarefa em questão reduzida de "escrever todo o padrão do StreamableManager e mover uma parte da função de chamada para um retorno de chamada" para apenas "colocar co_await na frente dele", você terminará mais rápido do que seria necessário para chegar com uma justificativa de por que a versão de bloqueio síncrono é de alguma forma aceitável.

Existem muitos recursos adicionais no plugin, como geradores que permitem evitar a alocação de um TArray inteiro apenas para retornar um número variável de valores. Mais fácil para você escrever, mais fácil para o compilador otimizar, você só precisa de armazenamento O(1) em vez de O(N) para N itens, o que há para não gostar?

Lista de recursos

Os links a seguir levarão você às páginas relevantes da documentação. Marque esta seção se preferir ler a documentação mais recente em seu navegador ou diretamente em seu IDE. Cada função da API está documentada nos cabeçalhos C++, e as versões contêm a fonte Markdown da documentação que você está lendo agora.

Autoria de corrotina

Esses recursos se concentram na exposição de corrotinas ao restante do mecanismo.

• Corrotinas (obviamente)
  • O suporte ao cancelamento tem sua própria página.
• Geradores
• A integração do sistema de habilidade de jogabilidade funciona de maneira um pouco diferente.

Integração irreal

Esses wrappers fornecem maneiras convenientes de consumir recursos do mecanismo de suas corrotinas.

• Integração de IA (MoveTo, pathfinding...)
• Aguardadores de animação (montagens, notifica...)
• Aguardadores assíncronos (multithreading, sincronização...)
• HTTP (solicitações HTTP assíncronas)
• Aguardadores implícitos (certos tipos de mecanismo são diretamente co_awaitable, sem wrappers)
• Aguardadores latentes (interação do thread do jogo, atraso...)
  • Carregamento de ativos (ponteiros flexíveis de carregamento assíncrono, pacotes...)
  • Consultas de colisão assíncronas (rastreamentos de linha, verificações de sobreposição...)
  • Cadeia latente (invólucro universal de ação latente)
  • Marque o orçamento de tempo (executado por x ms por quadro)
• Retornos de chamada latentes (interação com o gerenciador de ações latentes)

Observação

A maioria dessas funções retorna tipos internos não documentados do namespace UE5Coro::Private . O código do cliente não deve se referir diretamente a nada deste namespace, pois tudo dentro dele está sujeito a alterações em versões futuras, sem depreciação prévia.

Na maioria das vezes, isso não é um problema: por exemplo, o objeto temporário sem nome em co_await Something() não aparece no código-fonte. Se um valor de retorno Private precisar ser armazenado, use auto (ou um TAwaitable auto restrito) para evitar escrever o nome do tipo.

Chamar diretamente as funções aguardáveis ​​C++ públicas por necessidade await_ready , await_suspend e await_resume não é compatível com nenhum aguardador.

Recursos adicionais

• Aguardadores agregados (WhenAny, WhenAll, Race...)
• Cronogramas latentes (interpolação suave no tick)
• Threading primitivos (semáforos, eventos...)

Instalação

Somente versões numeradas são suportadas. Não use as ramificações do Git diretamente.

Baixe a versão escolhida e extraia-a na pasta Plugins do seu projeto. Renomeie a pasta apenas para UE5Coro, sem número de versão. Feito corretamente, você deve terminar com YourProjectPluginsUE5CoroUE5Coro.uplugin .

Observação

Consulte o README da versão se estiver usando 1.x. Tinha um método diferente de instalação envolvendo vários plugins.

Configuração do projeto

Seu projeto pode usar algumas configurações herdadas que precisam ser removidas para desbloquear o suporte ao C++20, que de outra forma vem como padrão em novos projetos feitos no Unreal Engine 5.3 ou posterior.

Em seus arquivos Target.cs (todos eles), certifique-se de estar usando as configurações mais recentes e inclua a versão do pedido:

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

Se você estiver usando o sinalizador bEnableCppCoroutinesForEvaluation herdado, ele não será mais necessário e não deverá mais ser explicitamente ativado; fazer isso pode causar problemas. É recomendado remover todas as referências a ele dos seus arquivos de construção.

Se você estiver configurando CppStandard como CppStandardVersion.Cpp17 em um arquivo Build.cs... não faça isso :)

Uso

Faça referência ao módulo "UE5Coro" do Build.cs como faria com qualquer outro módulo C++ e use #include "UE5Coro.h" . O plugin em si não precisa ser habilitado.

Algumas funcionalidades estão em módulos opcionais que precisam ser referenciados separadamente. Por exemplo, o suporte do Gameplay Ability System precisa de "UE5CoroGAS" em Build.cs e #include "UE5CoroGAS.h" . O módulo UE5Coro principal depende apenas dos módulos do mecanismo habilitados por padrão.

Importante

Não #inclua diretamente nenhum outro cabeçalho, apenas aquele que corresponde ao nome do módulo. Os principais IDEs usados ​​com o Unreal Engine são conhecidos por apresentarem sugestões de cabeçalho erradas. Se você adicionar UE5Coro.h ao seu PCH, poderá disponibilizá-lo em qualquer lugar.

Atualizações

Para atualizar, exclua o UE5Coro da pasta Plugins do seu projeto e instale a nova versão seguindo as instruções acima.

Embalagem

Empacotar o UE5Coro separadamente (da janela Plugins) não é necessário e não é suportado.

Remoção

Para remover o plug-in do seu projeto, reimplemente todas as suas corrotinas sem sua funcionalidade, remova todas as referências ao plug-in e seus módulos e adicione um redirecionamento principal de /Script/UE5CoroK2.K2Node_UE5CoroCallCoroutine para /Script/BlueprintGraph.K2Node_CallFunction .