Introducción

Actualizar el motor de juego a mitad de un proyecto es una de las decisiones rutinarias que más miedo dan en el desarrollo de videojuegos. Una nueva versión de Godot podría corregir el bug que te está bloqueando — o podría romper silenciosamente una escena en la que invertiste seis meses de trabajo. Por eso los desarrolladores experimentados de la comunidad de Godot tratan una actualización de versión como una decisión de riesgo, no como una tarea rutinaria.

Esta guía no es una defensa del «actualiza siempre». Es una checklist de gestión de riesgos para la migración entre versiones 4.x de Godot: cómo decidir si actualizar siquiera, cómo prepararte para poder dar marcha atrás con seguridad, qué se sabe que se rompe entre versiones y — lo más importante — cómo verificar de verdad que nada se rompió.

¿Deberías actualizar siquiera?

Antes de tocar nada, responde con honestidad a esta pregunta. Actualizar tiene un coste real (trabajo de migración + volver a probar), así que el beneficio debe ser igual de real.

Actualiza si…

  • Un bug ya corregido en el motor te está bloqueando. Si tu problema ya está resuelto en una versión más reciente, actualizar suele salir más barato que convivir con la solución provisional para siempre.
  • Una nueva funcionalidad beneficia materialmente a tu juego. No un «suena bien» — algo que te ahorra tiempo real de desarrollo o desbloquea un diseño que necesitas.
  • Tu calendario de desarrollo es largo. Si tu proyecto va a durar años, los saltos pequeños y frecuentes (una versión menor cada vez) son mucho más seguros que un salto gigante al final. La brecha solo crece.

No actualices si…

  • Estás cerca del lanzamiento. Las semanas previas al lanzamiento son el peor momento posible para introducir cambios a nivel de motor. Primero publica, actualiza después.
  • Necesitas C# + exportación a Web. La exportación a Web para proyectos en C# sigue sin estar disponible en Godot 4.x (seguimiento en godot#70796). Si dependes de ella en 3.x, pasar a 4.x te la quita.
  • Tu objetivo es hardware antiguo. Godot 3.x funciona en GPU de clase OpenGL 2; el renderizador Compatibility de Godot 4 requiere OpenGL 3.3 / WebGL 2. Si tu audiencia usa máquinas antiguas, 3.x puede ser genuinamente el motor correcto.
  • Los addons críticos aún no se han actualizado. Si un plugin del que depende tu proyecto no soporta la nueva versión, heredas su problema de migración además del tuyo.

Regla general: actualiza cuando un beneficio concreto supere un coste concreto que hayas estimado — no porque exista una versión nueva.

Antes de actualizar — Checklist de preparación

Cada paso de esta lista existe para que, si la actualización sale mal, pierdas una tarde y no un proyecto.

  1. Haz commit de todo y crea una rama de actualización. Nunca actualices la única copia de tu proyecto. Una rama dedicada (o una copia completa de la carpeta si no usas git) significa que revertir es un solo comando, no una misión de rescate.
  2. Anota tu versión exacta actual (por ejemplo, qué build 4.x.y, estándar o .NET). La necesitarás si tienes que volver atrás o abrir un informe de bug.
  3. Conserva el binario del editor antiguo. Las versiones de Godot se instalan en paralelo — el editor es un único ejecutable, así que conservar ambos no cuesta nada y te permite abrir la rama antigua con el editor antiguo en cualquier momento.
  4. Lista tus addons y comprueba las versiones que soporta cada uno. Revisa addons/, anota de dónde salió cada uno y confirma en su repositorio o en su página de la Asset Library que soporta la versión de destino.
  5. Lee las notas oficiales de actualización de cada versión que atravieses. Las guías oficiales de migración están escritas por versión — si pasas de 4.2 a 4.4, lee las notas de 4.3 y de 4.4.
  6. Captura evidencia del «estado bueno conocido». Haz capturas de pantalla de tus escenas clave, graba un clip corto de gameplay o — lo mejor de todo — escribe escenarios de prueba automatizados (más sobre esto en la sección de pruebas de abajo). Después de la actualización, «¿se ve y se comporta igual?» solo tiene respuesta si antes registraste qué significa «igual».

El procedimiento de actualización

  1. Abre la copia de la rama con el editor nuevo. La rama de actualización, no main. El editor nuevo ofrecerá convertir/reimportar — acepta.
  2. Deja que reimporte. La carpeta .godot se regenera desde cero. La primera importación puede tardar en proyectos grandes, y las advertencias que imprime durante esa primera pasada suelen ser inofensivas.
  3. Revisa los paneles Output y Debugger en busca de errores nuevos. Compara con los errores que ya tenías antes (los anotaste, ¿verdad?). Los errores nuevos son la lista de tareas de la migración.
  4. Juega las rutas críticas. Inicia una partida nueva, carga una partida guardada, ejecuta el bucle de juego principal, abre los menús principales. Los errores en el editor son los fáciles — las regresiones se esconden en el comportamiento en tiempo de ejecución.
  5. Ejecuta tus escenarios de prueba (los que preparaste antes de actualizar) y compara con la línea base.
  6. Revisa el diff del árbol de trabajo en git antes de hacer commit. El editor reescribe archivos durante la migración: project.godot recibe nuevos valores de configuración, los archivos .tscn se vuelven a guardar y pueden aparecer nuevos archivos .uid. Revisa el diff para saber exactamente qué cambió — y luego haz commit de todo como un único commit de migración claramente etiquetado.

Puntos de ruptura conocidos entre versiones 4.x

Las versiones menores de Godot 4 son mayormente compatibles, pero ese «mayormente» carga con bastante peso en la frase. Estos son los cambios con más probabilidades de morder, según las notas oficiales y los reportes de la comunidad.

4.2 → 4.3: TileMap queda obsoleto en favor de TileMapLayer

Godot 4.3 marcó como obsoleto el nodo TileMap en favor de TileMapLayer — un nodo por capa en lugar de capas dentro de un solo nodo. Los TileMap existentes siguen funcionando, pero el código nuevo y los proyectos nuevos deberían usar TileMapLayer. El editor incluye una herramienta de extracción: selecciona tu TileMap, abre el panel inferior de TileMap, haz clic en el icono de caja de herramientas de la esquina superior derecha y elige «Extract TileMap layers as individual TileMapLayer nodes».

Trampa reportada por la comunidad: existen reportes de bits de colisión de las capas de física del TileSet que se restablecen a los valores por defecto tras la migración a TileMapLayer. No le pasa a todo el mundo, pero el modo de fallo es desagradable (las cosas dejan de colisionar, en silencio). Verifica explícitamente las colisiones de tus tiles después de convertir.

4.3 → 4.4: archivos .uid y ampliaciones de GDScript

  • Godot 4.4 añadió archivos acompañantes .uid junto a scripts y shaders. Súbelos al control de versiones — borrarlos puede romper las referencias uid:// allí donde se usen (las notas oficiales de actualización de 4.4 cubren cambios relacionados, como que las rutas de @export_file pasan a ser uid://). Parecen basura; no lo son.
  • Los Dictionary tipados y otras ampliaciones de GDScript son retrocompatibles — tu código antiguo sigue funcionando. Pero los addons que adoptan las nuevas funciones dejan de funcionar en versiones anteriores, así que el comportamiento de los addons puede diferir a un lado y otro del salto.

General: cambios sutiles entre cualquier par de versiones menores

Los ajustes de renderizado entre versiones menores pueden cambiar sutilmente el aspecto de tu juego — iluminación, anti-aliasing, snapping 2D. Las discusiones de la comunidad también incluyen regresiones específicas de una escena que no se reproducen en proyectos nuevos: una escena se comporta mal tras la actualización, pero reconstruir esa misma escena en un proyecto limpio funciona bien. Si algo se rompe de forma inexplicable, prueba esta secuencia de aislamiento: cierra el editor, borra la carpeta .godot, vuelve a abrir y deja que todo se reimporte; si el problema persiste, reproduce la escena en un proyecto limpio para determinar si el culpable es el estado acumulado de tu proyecto o un cambio real del motor.

3.x → 4.x es otra historia

Todo lo anterior trata de saltos entre versiones 4.x. Migrar de Godot 3 a Godot 4 es una categoría completamente distinta: la sintaxis de GDScript cambió, muchos nodos fueron renombrados, y TileMap, la física y el renderizado se rehicieron desde cero — y la mayoría de los addons necesitan versiones dedicadas para 4.x. En proyectos 3.x grandes, el coste de la migración puede acercarse al coste de rehacer el juego, y si merece la pena es una decisión genuinamente propia de cada proyecto. Esa migración merece (y tiene) su propia documentación; este artículo no fingirá cubrirla.

Probar después de la actualización — el verdadero cuello de botella

Aquí viene la parte honesta: la razón número uno por la que los desarrolladores evitan actualizar no es la migración en sí — es que verificar a mano que «nada se rompió» sale caro. Una pasada completa de regresión manual en un juego mediano puede comerse un fin de semana. Y un bug en tiempo de ejecución que tus jugadores encuentren después del lanzamiento es mucho peor que cualquier error del editor, porque entonces es un problema de reputación, no un elemento de la lista de tareas.

Smoke test manual mínimo

  • Iniciar una partida nueva desde la pantalla de título
  • Cargar un archivo de guardado existente
  • Jugar el bucle de juego principal durante unos minutos
  • Comprobar la interfaz en cada resolución y modo de ventana que soportes

Automatiza la comparación antes/después

La pasada manual no escala, y no puede decirte que un sprite se desplazó dos píxeles. Exactamente para esto se creó Godot QA — un ejecutor de pruebas para Godot gratuito, de código abierto y con licencia MIT. Su flujo de trabajo encaja a la perfección con las actualizaciones de versión:

  1. Antes de actualizar, escribe (o graba) archivos JSON de escenario que cubran tus rutas críticas, y captura capturas de pantalla de línea base en la versión antigua.
  2. Después de actualizar, ejecuta exactamente los mismos escenarios más un diff de píxeles contra las líneas base en la versión nueva.
  3. Los fallos localizan las regresiones en minutos en lugar de un fin de semana de repetición manual.

Un escenario no es más que una lista JSON de pasos — entradas, esperas, aserciones, capturas de pantalla:

{
  "name": "core_loop_smoke",
  "steps": [
    {"type": "wait", "seconds": 1.0},
    {"type": "input", "action": "ui_accept", "pressed": true},
    {"type": "wait", "seconds": 0.5},
    {"type": "assert", "node_path": "/root/Main/Player",
     "property": "health", "expected": 100, "operator": "eq"},
    {"type": "input", "action": "move_right", "pressed": true},
    {"type": "wait", "seconds": 2.0},
    {"type": "input", "action": "move_right", "pressed": false},
    {"type": "assert", "node_path": "/root/Main/Player",
     "property": "position:x", "expected": 100.0, "operator": "gt"},
    {"type": "screenshot", "name": "after_move"}
  ]
}

Este mismo formato de escenario es el que usa la herramienta run_test_scenario de Godot MCP Pro, así que un asistente de IA conectado a tu editor puede escribir estos escenarios por ti.

Si algo se rompe

  1. Haz bisección por versión. Si saltaste varias versiones menores de golpe, reintenta la actualización una versión menor cada vez para encontrar exactamente dónde se rompió. Eso reduce la búsqueda de «todo» a un solo changelog.
  2. Borra la carpeta .godot y deja que el proyecto reimporte. Las cachés de importación obsoletas causan una proporción sorprendente de las rarezas posteriores a la actualización.
  3. Busca tu mensaje de error exacto en los issues de GitHub del motor. Si es una regresión real, a menudo alguien ya la ha reportado — a veces con una solución provisional.
  4. Comprueba si el culpable es un addon. Desactiva tus addons en la configuración del proyecto y vuelve a probar. Si el problema desaparece, es el addon — comprueba si hay una versión actualizada antes de culpar al motor.
  5. Acepta que quedarse en la versión antigua es un resultado válido. Si el coste de arreglarlo supera el beneficio de la actualización, revierte la rama, quédate donde estás y ponte un recordatorio para reintentarlo cuando salga la próxima versión. Eso no es un fracaso — es la gestión de riesgos funcionando.

Cuándo quedarse quieto es la decisión correcta

Algunos proyectos simplemente no deberían actualizar, y eso merece decirse sin rodeos: juegos publicados o a punto de publicarse, proyectos en C# que necesitan exportación web, juegos dirigidos a hardware antiguo y proyectos sobre builds de motor personalizadas muy modificadas. En todos estos casos, la versión que usas está haciendo su trabajo. Actualizar es una herramienta, no una virtud — la meta es un juego terminado, no un motor recién estrenado.

Preguntas frecuentes

¿Puedo volver a una versión anterior después de actualizar?

No de forma fiable. Una vez que el editor nuevo vuelve a guardar tus escenas y recursos, dejan de ser retrocompatibles con editores más antiguos. La única vía de vuelta segura es restaurar desde el control de versiones — que es exactamente la razón de ser de la rama de actualización.

¿Debería saltarme varias versiones de golpe?

Los saltos pequeños son más seguros. Las notas oficiales de actualización están escritas por versión, así que cada salto tiene una checklist conocida — un salto de varias versiones las apila todas a la vez y hace más difícil saber qué cambio rompió qué.

¿De verdad las versiones menores rompen cosas?

Raramente, pero sí. La mayoría de los proyectos saltan versiones menores sin problemas, pero existen casos límite reportados por la comunidad — bits de colisión que se restablecen, regresiones de renderizado específicas de una escena. Precisamente por eso importan las pruebas de línea base antes de la actualización: convierten «¿se rompió algo?» de una sensación en una medición.

¿Esta checklist sirve para 3.x → 4.x?

La checklist en sí, sí — crear una rama, conservar el binario antiguo, capturar líneas base, probar después. La lista de puntos de ruptura, no: la migración de 3 a 4 es mucho más grande (sintaxis de GDScript, nodos renombrados, sistemas rehechos) y tiene su propia documentación oficial dedicada.