Wiki
Plugin de Unreal Engine
Plugin uVersion para Unreal Engine: control de versiones nativo en el editor, diff de Blueprint, auditoría Project Health y las dos reglas que más a menudo bloquean un envío.
Requisitos previos
.uversion/ subiendo desde el proyecto; si no encuentra ninguna, y si no se ha
guardado antes ningún token de autenticación, no se activa en absoluto y Unreal se queda sin control de versiones.
No es una avería: es lo que le impide imponerse en tus proyectos que no están versionados con
uVersion. Abre el proyecto desde la carpeta clonada por el cliente desktop, no desde una copia colocada
en otro sitio.
Instalación
El plugin uVersion se distribuye como binario precompilado, gestionado por el cliente desktop. Sin compilación de tu parte, sin archivos fuente que manipular. Nunca se versiona: no llega con el repositorio, y no debe enviarse dentro de él. Cada equipo instala el binario que corresponde a SU versión de Unreal y a SU sistema.
Versiones de Unreal admitidas: 5.6 y superiores.
1. Abrir el workspace en el cliente desktop
Instala el cliente desktop de uVersion, inicia sesión y abre luego el workspace que contiene el proyecto de Unreal. Todo ocurre desde el cliente: no hay ningún archivo comprimido que descargar, ni que descomprimir a mano en el proyecto.
2. Dejar que el cliente detecte el proyecto
El cliente busca tu .uproject (el archivo que describe un proyecto de Unreal) bajo la raíz del
workspace, siempre que no esté enterrado a más de tres niveles. En cuanto lo encuentra, aparece una barra
Unreal en la parte superior de la pestaña del workspace, y coloca el plugin correspondiente a tu versión
de Unreal en Plugins/uVersion/. La insignia de la izquierda lleva el estado del plugin y su número
de versión: ahí es también donde se leen las actualizaciones.
3. Abrir el proyecto en Unreal
El plugin queda activo de inmediato. No hay nada que marcar en la ventana Plugins del editor, nada que reiniciar: si faltaba, es que el cliente aún no lo ha colocado, no que quede por activar.
Más adelante: las actualizaciones
El cliente desktop comprueba si hay versiones nuevas al abrir el proyecto y periódicamente después. Atención, la comprobación automática no hace lo mismo en los dos casos:
- Plugin ausente: se instala sin preguntarte nada. Es lo que hace transparente el primer arranque.
-
Plugin ya presente pero desfasado (versión nueva, o cambio de versión de Unreal): el cliente
se limita a avisarte. Nunca reemplaza por sí solo un plugin instalado. La insignia
del panel de Unreal pasa entonces a
Update ready.
Para aplicar la actualización: cierra el editor de Unreal y haz clic en la insignia. Un plugin
cargado no puede reemplazarse en el disco; si el editor sigue abierto, la insignia muestra
Restart UE.
Primera conexión
En el caso normal, no hay nada que conectar. El plugin se selecciona a sí mismo como proveedor de control de versiones en cuanto detecta un workspace uVersion alrededor del proyecto, o un token ya guardado. Tus credenciales se toman del cliente desktop, sin volver a escribirlas. Basta con abrir el proyecto.
Los tres pasos siguientes solo sirven si esa selección automática no se ha producido.
1. Abrir el menú Revision Control
Se encuentra abajo a la derecha de la barra de estado del editor, no en los menús de arriba. Se
abre hacia arriba y lleva las acciones de Unreal, entre ellas Submit Content, más una sección
uVersion con nuestra entrada Audit Project (Project Health). Toma
Connect to Revision Control.
2. Elegir uVersion en la lista Provider
Se abre la ventana Revision Control Login. Despliega Provider y toma uVersion. Cuando el workspace es reconocido, la ventana lo anuncia ella misma en verde (Automatically configured from workspace) y los campos Workspace, Server URL y Username ya están rellenos: no hay nada que escribir.
3. Validar con Accept Settings
El botón Accept Settings, en la parte inferior de la ventana, aplica la elección y cierra la ventana. La barra de estado muestra entonces Connected to seguido del nombre del repositorio y de tu nombre de usuario. La elección se memoriza: las siguientes aperturas del proyecto no volverán a pasar por aquí.
Reservar un asset y luego enviarlo
El recorrido completo desde el editor, sobre un archivo de contenido. El código, en cambio, nunca parte de aquí: consulta El código pasa por el cliente desktop.
1. Mirar el estado del asset antes de empezar
Cada miniatura del Content Browser lleva una insignia que dice en qué punto está el asset: reservado por ti, reservado por otra persona, o desfasado respecto al servidor. La información sobre herramientas da la frase completa, por ejemplo File is out of date, sync to get the latest version. En ese caso, sincroniza primero (clic derecho, Revision Control, Sync): empezar a trabajar sobre una versión desfasada es preparar un conflicto.
2. Reservar el asset
Clic derecho sobre el asset, submenú Revision Control, luego Check Out. Todo está ahí: Sync, Check Out, Check In, History, Diff Against Depot, Revert, como con cualquier otro proveedor de Unreal. Los artistas no tienen nada nuevo que aprender.
En la práctica a menudo no tendrás que hacer nada: en cuanto modificas un asset, el plugin coloca el lock del lado del servidor por sí solo, sin checkout manual.
3. Comparar antes de enviar
Diff Against Depot abre la herramienta de comparación visual estándar del editor, incluso sobre un Blueprint: las dos revisiones se muestran una junto a otra, y los nodos añadidos, eliminados o modificados quedan rodeados. Funciona sobre cualquier commit del historial, desde History.
4. Enviar
Clic derecho, Revision Control, Check In sobre la selección, o Submit Content en el menú de la barra de estado para enviarlo todo de una vez. La ventana lista los archivos afectados, incluidas las eliminaciones, y reclama una descripción. En el momento del envío, el plugin limpia los redirectors que dejaron tus renombrados y ejecuta las reglas de validación activas: una regla en error detiene el envío y nombra los archivos culpables.
Qué hace el plugin en Unreal
Project Health: auditar el proyecto
El menú Revision Control de la barra de estado contiene una entrada
Audit Project (Project Health). Recorre el registro de assets del proyecto
sin cargar un solo asset, y produce un informe de salud: nombres, estructura de carpetas,
dependencias, contenido huérfano, costes. Funciona sin conexión (el informe se escribe bajo
Saved/uVersionAudit) y lo envía al servidor cuando estás conectado, donde alimenta la
pestaña Project Health del cliente desktop.
Limpieza de redirectors
Cuando renombras o mueves un asset, Unreal deja tras de sí un redirector: un pequeño archivo de reenvío que apunta la ruta antigua a la nueva, para que los assets que referenciaban el nombre antiguo sigan funcionando. Se acumulan rápido y acaban volviendo el árbol ilegible. El plugin los detecta y los limpia en el momento del checkin, actualizando las referencias en todos los assets afectados.
Validación previa al checkin
El plugin sabe ejecutar una serie de comprobaciones sobre los archivos enviados: compilación de Blueprints, convención de nombres, tamaño de las texturas, ajustes de importación, dependencias faltantes, dependencias circulares, assets huérfanos, duplicados, complejidad de los materiales. Nueve reglas en total. Una regla en error bloquea el envío, una regla en warning lo autoriza tras confirmación.
Reconciliación al arranque
Al abrir el proyecto, el plugin compara el estado de tus assets con el servidor. Recorre Content/
y los Content/ de los plugins del proyecto, y reserva automáticamente todo asset encontrado
modificable en el disco que no lo estuviera ya. La intención es protegerte: un archivo que habías empezado a modificar
no puede ser atrapado por un compañero entre dos sesiones.
El código pasa por el cliente desktop, no por Unreal
El plugin rechaza el envío de los archivos de código: .cpp, .h,
.hpp, .c y .cs. El intento se detiene en una ventana bloqueante que
nombra los archivos culpables. No es un defecto: el cliente desktop compila antes de enviar y publica los
binarios de editor que tus compañeros recuperan en el sync. Un commit de código que saliera desde el editor pasaría por
alto ambos, y suspendería la distribución de binarios para todo el equipo.
Así que envía tu código desde el cliente desktop. Los archivos de contenido, en cambio, siguen siendo perfectamente libres de salir desde Unreal.
.uasset puro. El mensaje te dice que envíes tu código desde el
cliente desktop primero.
Es el bloqueo más común, y cae de buen grado sobre alguien que no escribe código: basta con que un archivo fuente se haya vuelto modificable en el disco para que la reconciliación al arranque lo haya reservado por sí sola. La razón es real: un asset guardado contra código no enviado rompe a todos los que lo sincronizan, ya que sus binarios no tienen el código del que depende.
El desbloqueo: abre la pestaña Pending del cliente desktop, la lista My Pending Changes, localiza los archivos de código, y haz un Checkin Selected si los has modificado, o un Revert si no los has tocado. Tu envío de contenido vuelve a salir después con normalidad. Puede tardar unos segundos, el tiempo de que el editor refresque su vista de los locks.
Problemas frecuentes
Ningún menú uVersion: el editor ignora el control de versiones
Probablemente el proyecto no está en un workspace uVersion. Comprueba que existe una carpeta .uversion/
en la raíz de la carpeta clonada, y que abres el proyecto desde esa carpeta y no desde una copia colocada
en otro sitio.
« Failed to connect to source control »
Comprueba que el cliente desktop está en marcha y que has iniciado sesión en él: es quien guarda tus credenciales y sabe dialogar con un servidor autofirmado. Si la cuenta propietaria del workspace no ha iniciado sesión en el cliente, el plugin se niega a trabajar bajo otra identidad, y es intencionado.
Un envío es rechazado aunque no he tocado ningún código
Tienes la reserva de un archivo de código. Consulta El código pasa por el cliente desktop.
Quiero un asset que otra persona ha bloqueado
Esto no se pide desde Unreal: el plugin no tiene función de solicitud de liberación. Pasa por el cliente desktop, pestaña Pending, sección Other Users' Locks, botón Request Release en la línea del archivo. El titular recibe una solicitud en forma de tarjeta en el board Production.
El plugin no se actualiza
Es el comportamiento esperado: la comprobación automática instala un plugin ausente, pero se limita a
señalar una actualización. Cierra el editor de Unreal (un plugin cargado no puede reemplazarse), y haz clic luego en la
insignia Update ready de la barra Unreal del cliente desktop para aplicarla.
Una regla de validación no se dispara nunca
Las nueve reglas se entregan desactivadas. Un administrador debe activarlas por proyecto desde la pestaña Rules del panel Admin.