Headless e CI
A migração pode rodar sem o painel: pelo console do editor, por um commandlet ou por um script.
Comando de console
Ueapm.Migrate [-dry] [-steps=a,b | -steps=a+b] [-target=<caminho do .uproject>]
| Argumento | Significado |
|---|---|
-dry | dry run: só Analisar e Verificar, nada é modificado |
-steps= | as etapas a executar, por id: project, assets, input, cascade, cpp, rendering, physics, blueprints. Separe com , ou + |
-target= | executa as etapas de arquivos (project, cpp) em outro projeto |
Sem -steps, roda a seleção padrão (todas as etapas exceto a opcional input). As etapas sempre rodam na ordem
fixa, seja qual for a ordem em que você as listar.
O + existe porque o -ExecCmds divide o argumento nas vírgulas: dentro de -ExecCmds, escreva
-steps=project+cpp.
Commandlet
& "C:\Program Files\Epic Games\UE_5.8\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" `
"D:\MeuJogo\MeuJogo.uproject" -run=UeapmMigrate [-dry] [-steps=a,b] [-target=...]
| Código de saída | Significado |
|---|---|
0 | concluído, sem pendências |
1 | concluído, com pendências no relatório |
2 | reinício necessário: execute de novo |
3 | erro fatal (por exemplo uma tabela de regras que não carregou) |
:::warning O Cascade precisa da interface do editor
O conversor de Cascade da engine usa views de editor do Niagara, que o commandlet não tem. Todas as outras etapas
rodam no commandlet; para a etapa cascade, execute o editor completo sem supervisão:
& "C:\Program Files\Epic Games\UE_5.8\Engine\Binaries\Win64\UnrealEditor.exe" "D:\MeuJogo\MeuJogo.uproject" `
-ExecCmds="Ueapm.Migrate,QUIT_EDITOR" -unattended -nosplash
:::
Tools/migrate_headless.ps1
O plugin inclui um wrapper em PowerShell que executa qualquer uma das formas, imprime as linhas de resultado do UEAPM e devolve o código de saída.
| Parâmetro | Significado |
|---|---|
-Project | o projeto a abrir (obrigatório) |
-Target | outro projeto onde executar as etapas de arquivos |
-Steps | ids das etapas separados por vírgula (convertidos para + no editor) |
-Dry | dry run |
-Editor | usa o editor completo com -ExecCmds em vez do commandlet (inclui Cascade) |
-EngineRoot | pasta da engine, padrão C:\Program Files\Epic Games\UE_5.8 |
-Log | arquivo de log, padrão %TEMP%\ueapm_headless.log |
# Etapas de arquivos em um projeto C++ que ainda não compila no 5.8, a partir de qualquer projeto 5.8 com o plugin
powershell -File Tools\migrate_headless.ps1 -Project D:\Host\Host.uproject -Target D:\MeuJogo\MeuJogo.uproject -Steps project,cpp
# Todas as etapas padrão dentro do projeto, editor completo (inclui a conversão de Cascade)
powershell -File Tools\migrate_headless.ps1 -Project D:\MeuJogo\MeuJogo.uproject -Editor
# Dry run no commandlet
powershell -File Tools\migrate_headless.ps1 -Project D:\MeuJogo\MeuJogo.uproject -Dry
No modo commandlet o script termina com exit code N (0 done, 1 open items, 2 restart and run again, 3 fatal) e
sai com o mesmo código, então um job de CI pode falhar quando há pendências.
Uma migração C++ completa sem supervisão
- Etapas de arquivos a partir de um projeto host:
migrate_headless.ps1 -Project <Host> -Target <Jogo> -Steps project,cpp. - Build com o comando impresso no relatório.
- Copie o plugin para
<Jogo>/Plugins/e compile de novo. - Todas as etapas no editor:
migrate_headless.ps1 -Project <Jogo> -Editor. - Build final.
O estudo de caso do Action RPG segue exatamente esta sequência.