Caso práctico: migrar Action RPG de Epic (4.27 a 5.8)

Action RPG es el juego de ejemplo gratuito de Epic en C++, construido sobre el Gameplay Ability System. Es una buena prueba: módulos C++, Gameplay Abilities, muchos efectos Cascade, ajustes móviles y un módulo de pantalla de carga. Esta página sigue una migración completa y desatendida de 4.27 a 5.8 con UEAPM y muestra los números reales de su informe.

1. Conseguir el ejemplo

1. En el Epic Games Launcher, abre Unreal Engine > Samples y descarga Action RPG para el motor 4.27.
2. Crea un proyecto a partir de él (por ejemplo ActionRPGSampleUE427).
3. Haz una copia de la carpeta del proyecto. Deja fuera Binaries, Intermediate, Saved y DerivedDataCache. Todos los pasos siguientes trabajan sobre la copia.

2. Pasos de archivos desde un proyecto 5.8

El proyecto todavía no se abre en 5.8: su C++ no compila. Ejecuta los pasos project y cpp desde cualquier proyecto 5.8 que tenga UEAPM, apuntando a la copia:

powershell -File Tools\migrate_headless.ps1 -Project D:\Host\UeapmHost.uproject `
    -Target D:\Work\ActionRPG58\ActionRPGSampleUE427.uproject -Steps project,cpp

Resultado de esta pasada (se conserva en Saved/UEAPM/History/):

Paso	Cambios	Pendientes
project	30	1 (Manual)
cpp	8	0

• Proyecto: asociación de motor de 4.27 a 5.8; WindowsNoEditor / MacNoEditor renombradas; 11 entradas de plugin eliminadas (entre ellas plugins de PhysX, VR, Magic Leap y LPV); 13 ajustes de Android e iOS actualizados para 5.8; 3 claves de denylist de empaquetado renombradas (IniKeyBlacklist a IniKeyDenylist y lo mismo para la sección y su propia autorreferencia). Un elemento Manual: la muestra tenía habilitado el plugin SlateRemote (eliminado) pero no lo usa, así que no hay nada que hacer.
• C++: 46 archivos de código analizados, 7 correcciones más los archivos de proyecto regenerados:
  • build settings de V2 a V7 con el orden de includes de 5.8, en los dos targets;
  • se añade un include de AbilitySystemLog.h;
  • dos comprobaciones en una ability task actualizadas para el weak pointer del componente;
  • un acceso a EventData.Target actualizado para object pointers;
  • GetReferencerName añadido al FGCObject de la pantalla de carga.

3. Build

Ejecuta el comando de build que aparece en las Notes de la sección C++ del informe:

& "C:\Program Files\Epic Games\UE_5.8\Engine\Build\BatchFiles\Build.bat" ActionRPGEditor Win64 Development `
    -Project="D:\Work\ActionRPG58\ActionRPGSampleUE427.uproject" -WaitMutex

El proyecto compila en 5.8 sin más cambios en el código.

4. Instalar UEAPM en el proyecto

Copia el plugin en ActionRPGSampleUE427/Plugins/UnrealEngineAbsoluteProjectMigrator/ y compila de nuevo.

5. Ejecutar la migración

Abre el proyecto y ejecuta los pasos por defecto desde Window > Absolute Project Migrator, o de forma desatendida:

powershell -File Tools\migrate_headless.ps1 -Project D:\Work\ActionRPG58\ActionRPGSampleUE427.uproject -Editor

Tabla de resumen de esta ejecución:

Paso	Estado	Cambios	Pendientes (error/manual)	Warnings	Tiempo (s)
Proyecto y configuración	ejecutado	0	0	0	0.2
Reguardado de assets	ejecutado	873	0	0	15.2
Enhanced Input (opcional)	no seleccionado	0	0	0	0.0
Cascade a Niagara	ejecutado	75	0	11	61.4
Código C++	ejecutado	1	0	0	5.5
Renderizado y móvil	ejecutado	6	0	0	0.1
Física (PhysX a Chaos)	ejecutado	10	0	0	0.0
Blueprints	ejecutado	0	1	0	7.2

Observa el orden de ejecución: los Blueprints ahora se ejecutan al final, después de la física, para que cualquier Blueprint que solo compile una vez convertidas sus dependencias tenga una oportunidad justa.

En cifras:

• 873 paquetes vueltos a guardar en el formato de 5.8, sin errores de carga.
• 26 sistemas Cascade convertidos a Niagara y 49 referencias sustituidas: 33 anim notifies, 9 emisores colocados en mapas, 4 componentes de Blueprint y 3 nodos de spawn.
• 11 warnings por referencias que no pudo sustituir (9 notifies Trail personalizados, 1 llamada SpawnEmitterAttached en BP_WeaponSpider, 1 Level Sequence). Siguen reproduciendo Cascade, que aún funciona en 5.8.
• 1 cambio de C++: los archivos de proyecto se regeneran otra vez después de que los pasos de assets y Cascade tocan el árbol de código.
• 16 cambios de configuración en esta pasada: 6 ajustes de renderizado (incluidos los valores móviles que mantienen desactivados Lumen y Virtual Shadow Maps) y 10 ajustes de física de la época de PhysX eliminados. Las 3 renombraciones de claves de denylist de empaquetado ahora aparecen en la primera pasada (ver arriba).
• La nota sobre SlateRemote se mantiene en el informe de la primera pasada, guardado en Saved/UEAPM/History/: la muestra no usa ese plugin, así que no hay nada que hacer al respecto.
• 179 Blueprints compilados, 1 pendiente: el único pendiente.

6. Leer el informe

El único pendiente en Left to do:

Severidad	Categoría	Ubicación	Corrección (resumen)
Error	Compile error	GA_GoblinRange01	Las Gameplay Abilities de UE5 exigen que el Gameplay Effect de cooldown conceda etiquetas. Establece CooldownGameplayEffectClass en None o da al efecto un componente Grant Tags con una etiqueta Cooldown.*.

Siguiendo el informe, abre GA_GoblinRange01 y establece CooldownGameplayEffectClass en None. Compila y guarda.

Resultado verificado

• El proyecto C++ compila con Build.bat en 5.8.
• 179 Blueprints compilan con 0 errores después de la corrección manual.
• Los 4 mapas cargan.
• Play In Editor desde el menú principal hasta el nivel funciona: la intro se reproduce, el personaje del jugador aparece, se mueve unos 15 m y activa ataques cuerpo a cuerpo; hay 7 componentes de partículas activos (los efectos Niagara convertidos).
• Tiempos en la máquina de prueba: la primera pasada (pasos de archivo desde el proyecto host) tarda menos de medio minuto; la segunda pasada (la ejecución desatendida en el editor) tarda unos 2 minutos, la mayor parte de eso la conversión de Cascade a Niagara; cada build tarda alrededor de un minuto, aunque un build puede tardar más si otro build tiene retenido el lock de build.