Estudo de caso: migrando o Action RPG da Epic (4.27 para 5.8)
O Action RPG é o jogo de exemplo gratuito da Epic em C++, construído sobre o Gameplay Ability System. É um bom teste: módulos C++, Gameplay Abilities, muitos efeitos Cascade, configurações mobile e um módulo de tela de carregamento. Esta página acompanha uma migração completa sem supervisão do 4.27 para o 5.8 com o UEAPM e mostra os números reais do relatório.
1. Obter o exemplo
- No Epic Games Launcher, abra Unreal Engine > Samples e baixe o Action RPG para a engine 4.27.
- Crie um projeto a partir dele (por exemplo
ActionRPGSampleUE427). - Faça uma cópia da pasta do projeto. Deixe de fora
Binaries,Intermediate,SavedeDerivedDataCache. Todos os passos seguintes trabalham na cópia.
2. Etapas de arquivos a partir de um projeto 5.8
O projeto ainda não abre no 5.8: o C++ não compila. Execute as etapas project e cpp a partir de qualquer projeto
5.8 que tenha o UEAPM, apontando para a cópia:
powershell -File Tools\migrate_headless.ps1 -Project D:\Host\UeapmHost.uproject `
-Target D:\Work\ActionRPG58\ActionRPGSampleUE427.uproject -Steps project,cpp
Resultado desta passada (guardado em Saved/UEAPM/History/):
| Etapa | Alterações | Pendências |
|---|---|---|
project | 30 | 1 (Manual) |
cpp | 8 | 0 |
- Projeto: associação de engine de 4.27 para 5.8;
WindowsNoEditor/MacNoEditorrenomeadas; 11 entradas de plugin removidas (entre elas plugins de PhysX, VR, Magic Leap e LPV); 13 configurações de Android e iOS atualizadas para o 5.8; 3 chaves de denylist de empacotamento renomeadas (IniKeyBlacklistparaIniKeyDenyliste o mesmo para a seção e sua própria autorreferência). Um item Manual: o exemplo tinha o plugin SlateRemote (removido) habilitado, mas não o usa, então não há nada a fazer. - C++: 46 arquivos de código analisados, 7 correções mais os arquivos de projeto regenerados:
- build settings de
V2paraV7com a ordem de includes do 5.8, nos dois targets; - um include de
AbilitySystemLog.hadicionado; - duas verificações em uma ability task atualizadas para o weak pointer do componente;
- um acesso a
EventData.Targetatualizado para object pointers; GetReferencerNameadicionado aoFGCObjectda tela de carregamento.
- build settings de
3. Build
Execute o comando de build impresso nas Notes da seção C++ do relatório:
& "C:\Program Files\Epic Games\UE_5.8\Engine\Build\BatchFiles\Build.bat" ActionRPGEditor Win64 Development `
-Project="D:\Work\ActionRPG58\ActionRPGSampleUE427.uproject" -WaitMutex
O projeto compila no 5.8 sem nenhuma outra alteração no código.
4. Instalar o UEAPM no projeto
Copie o plugin para ActionRPGSampleUE427/Plugins/UnrealEngineAbsoluteProjectMigrator/ e compile de novo.
5. Executar a migração
Abra o projeto e execute as etapas padrão em Window > Absolute Project Migrator, ou sem supervisão:
powershell -File Tools\migrate_headless.ps1 -Project D:\Work\ActionRPG58\ActionRPGSampleUE427.uproject -Editor
Tabela de resumo desta execução:
| Etapa | Status | Alterações | Pendências (erro/manual) | Warnings | Tempo (s) |
|---|---|---|---|---|---|
| Projeto e configuração | executada | 0 | 0 | 0 | 0.2 |
| Regravação de assets | executada | 873 | 0 | 0 | 15.2 |
| Enhanced Input (opcional) | não selecionada | 0 | 0 | 0 | 0.0 |
| Cascade para Niagara | executada | 75 | 0 | 11 | 61.4 |
| Código C++ | executada | 1 | 0 | 0 | 5.5 |
| Renderização e mobile | executada | 6 | 0 | 0 | 0.1 |
| Física (PhysX para Chaos) | executada | 10 | 0 | 0 | 0.0 |
| Blueprints | executada | 0 | 1 | 0 | 7.2 |
Observe a ordem de execução: os Blueprints agora rodam por último, depois da física, para que qualquer Blueprint que só compile depois que suas dependências forem convertidas tenha uma chance justa.
Em números:
- 873 pacotes regravados no formato do 5.8, sem erros de carregamento.
- 26 sistemas Cascade convertidos para Niagara e 49 referências substituídas: 33 anim notifies, 9 emissores colocados em mapas, 4 componentes de Blueprint e 3 nós de spawn.
- 11 warnings para referências que não pôde substituir (9 notifies Trail personalizados, 1 chamada
SpawnEmitterAttachedemBP_WeaponSpider, 1 Level Sequence). Elas continuam tocando Cascade, que ainda funciona no 5.8. - 1 alteração de C++: os arquivos de projeto são regenerados de novo depois que as etapas de assets e Cascade tocam a árvore de código.
- 16 alterações de configuração nesta passada: 6 configurações de renderização (incluindo os valores mobile que mantêm Lumen e Virtual Shadow Maps desligados) e 10 configurações de física da era PhysX removidas. As 3 renomeações de chaves de denylist de empacotamento agora aparecem na primeira passada (ver acima).
- A observação sobre o SlateRemote permanece no relatório da primeira passada, guardado em
Saved/UEAPM/History/: o exemplo não usa esse plugin, então não há nada a fazer a respeito. - 179 Blueprints compilados, 1 pendente: a única pendência.
6. Ler o relatório
A única pendência em Left to do:
| Severidade | Categoria | Local | Correção (resumo) |
|---|---|---|---|
| Error | Compile error | GA_GoblinRange01 | Gameplay Abilities do UE5 exigem que o Gameplay Effect de cooldown conceda tags. Defina CooldownGameplayEffectClass como None ou dê ao efeito um componente Grant Tags com uma tag Cooldown.*. |
Seguindo o relatório, abra GA_GoblinRange01 e defina CooldownGameplayEffectClass como None. Compile e salve.
Resultado verificado
- O projeto C++ compila com o
Build.batno 5.8. - 179 Blueprints compilam com 0 erros depois da correção manual.
- Os 4 mapas carregam.
- Play In Editor do menu principal até a fase funciona: a intro toca, o personagem do jogador aparece, se move cerca de 15 m e ativa ataques corpo a corpo; 7 componentes de partícula ficam ativos (os efeitos Niagara convertidos).
- Tempo na máquina de teste: a primeira passada (etapas de arquivo a partir do projeto host) leva menos de meio minuto; a segunda passada (a execução sem supervisão no editor) leva cerca de 2 minutos, a maior parte disso a conversão de Cascade para Niagara; cada build leva cerca de um minuto, embora um build possa levar mais tempo se outro build estiver retendo o lock de build.