Volver al Blog
Motores Gráficos10 de noviembre de 202613 min de lectura

Sistemas de guardado: que la partida de la versión 1.0 cargue en la 1.4

Sale un parche, alguien renombra un campo y miles de jugadores pierden una partida de ochenta horas. Qué guardar y qué reconstruir, cómo versionar el formato con migraciones encadenadas, cómo escribir el archivo sin que un apagón lo corrompa y cómo guardar sin tirones, en Unity y Unreal.

IM
Ignacio MelendezDesarrollador Full-Stack y de Videojuegos
Sistemas de guardado: que la partida de la versión 1.0 cargue en la 1.4

Llega un nuevo parche 1.3 con una pequeña mejora. Durante el desarrollo, alguien del equipo se dio cuenta que el campo gold del inventario se llamaba así desde el prototipo. Como el juego ya tenía tres monedas diferentes, lo renombró a coins. Los tests pasaban. QA probó partidas nuevas y todo funcionaba. El parche salió un viernes, y el lunes había cientos de reseñas negativas de jugadores que habían cargado su partida y aparecían sin una sola moneda.

No fue un fallo del serializador. Hizo justo lo que se le había programado hacer: leer el archivo, no encontrar ningún campo coins y por lo tanto, dejar el valor por defecto: cero. No saltó ningún error, ni excepción, ni log. El campo gold seguía en el archivo, con las 48.000 monedas del jugador, pero ya no se leía.

Un sistema de guardado no es una funcionalidad que se hace al final del proyecto, lo que es un fallo para todos los que empiezan. Es un formato de datos que tiene que seguir funcionando durante toda la vida del juego, y que cada parche va a romper sin querer.

1. Decidir qué se guarda y qué se reconstruye

El primer error de muchos sistemas de guardado es intentar guardar el estado del juego tal cual está en memoria.

En Unity, eso suele significar serializar MonoBehaviour. En Unreal, guardar actores enteros. Funciona en el prototipo. Pero el formato del archivo queda atado a la estructura interna de las clases, y se convierte en un problema en cuanto el código cambia.

Para evitarlo, hay que hacerse la pregunta: ¿cuál es el estado mínimo a partir del cual puedo reconstruir todo lo demás? Casi siempre es mucho menos de lo que parece:

  • Se guarda: Lo que el jugador ha decidido o conseguido: inventario, progreso de misiones, estadísticas, posición en el mapa, flags de historia, ajustes...
  • Se reconstruye: Lo que se puede derivar: las stats finales (a partir del nivel y el equipo), el estado visual, la IA de los enemigos, las referencias entre objetos...

Además, es importante tener en cuenta que se debe guardar siempre por identificador, nunca por referencia. Un objeto del inventario se guarda como "sword_iron", no como una referencia a un ScriptableObject o a un asset. El id sobrevive a que el asset cambie de carpeta o de nombre, mientras que la referencia no.

Como consejo, si el archivo de guardado contiene nombres de clases, rutas de assets o GUIDs internos del motor, está guardando la implementación, no el estado del juego.

Pero, separar el modelo de guardado del modelo de juego tiene el coste de que hace falta un paso de conversión en cada sentido. Justo ahí es donde viven las migraciones, y sin él no hay forma limpia de evolucionar el formato.

2. JSON vs binario

La siguiente decisión es el formato. Las dos principales opciones razonables tienen ventajas claras:

  • JSON (o cualquier formato de texto con nombres de campo). Es legible, se puede inspeccionar y editar a mano durante el desarrollo, tolera campos nuevos o ausentes, y facilita mucho las migraciones porque se puede manipular el documento antes de convertirlo a objetos. Como desventaja, suele ocupar más y es más lento de procesar.
  • Binario. Es compacto y rápido. Pero si el formato depende del orden de los campos, cualquier cambio en la estructura desplaza todo lo que viene detrás, y el archivo antiguo ya no sirve.

Para la mayoría de juegos, el tamaño de la partida guardada no es un cuello de botella, y la flexibilidad que da un formato con nombres de campo compensa con creces. En los casos como consolas con cuotas estrictas, guardado en la nube... donde el tamaño de esos archivos si que importa, es posible comprimir el JSON, que reduce mucho el tamaño sin perder sus ventajas.

En Unity, actualmente JsonUtility se queda corto rápidamente: no serializa diccionarios, ni propiedades, entre otros. La alternativa habitual es Newtonsoft Json, disponible como paquete oficial (com.unity.nuget.newtonsoft-json), que además permite trabajar con el documento como árbol (JObject), que es lo que hace falta para migrar.

En Unreal, el camino estándar es una subclase de USaveGame con propiedades UPROPERTY(). La serialización es binaria, pero es tagged: cada propiedad se guarda con su nombre y su tipo, así que añadir propiedades nuevas o eliminar antiguas no rompe la lectura. Renombrar una propiedad o cambiar su tipo sí que lo rompen.

3. Versionar el formato desde el primer día

Todo archivo de guardado debería llevar un número de versión desde la primera build que llega a un jugador. Es una línea de código, y añadirla después es mucho más difícil; hay que distinguir de algún modo los archivos que no la tienen de los que sí, y trabajar con ellos de manera diferente.

La idea es sencilla: cada vez que el formato cambia de forma incompatible, se incrementa la versión y se escribe una migración que transforma un archivo de la versión n a la versión n + 1. Al cargar, se aplican en cadena todas las migraciones desde la versión del archivo hasta la actual.

1using Newtonsoft.Json.Linq;
2
3public interface ISaveMigration
4{
5    int FromVersion { get; }
6    void Apply(JObject save);
7}
8
9public static class SaveMigrator
10{
11    public const int CurrentVersion = 3;
12
13    private static readonly ISaveMigration[] Migrations =
14    {
15        new V1_AddSettings(),        // 1 -> 2
16        new V2_RenameGoldToCoins(),  // 2 -> 3
17    };
18
19    public static JObject Migrate(JObject save)
20    {
21        int version = save.Value<int?>("version") ?? 1;
22
23        if (version > CurrentVersion)
24            throw new SaveTooNewException(version);
25
26        foreach (var migration in Migrations)
27        {
28            if (migration.FromVersion < version) continue;
29            migration.Apply(save);
30            version = migration.FromVersion + 1;
31            save["version"] = version;
32        }
33
34        return save;
35    }
36}

Las migraciones son pequeñas y cada una solo sabe de dos versiones consecutivas. La del ejemplo inicial sería así:

1public class V2_RenameGoldToCoins : ISaveMigration
2{
3    public int FromVersion => 2;
4
5    public void Apply(JObject save)
6    {
7        var inventory = (JObject)save["inventory"];
8        if (inventory?["gold"] is JToken gold)
9        {
10            inventory["coins"] = gold;
11            inventory.Remove("gold");
12        }
13    }
14}

De esta forma, cada nueva actualización, seguirá funcionando con los ficheros anteriores, haciendo un cambio para adaptar al nuevo contenido todo lo viejo.

En Unreal hay un mecanismo nativo más elaborado llamado custom versions (FCustomVersionRegistration y Ar.CustomVer dentro de Serialize), que es el que usa el propio motor para versionar sus formatos. Para un USaveGame sencillo, un campo SaveVersion y una función de migración tras LoadGameFromSlot es más fácil de leer y de testear, y cubre la mayoría de casos.

Hay un caso que ninguna migración puede resolver: un archivo con una versión más nueva que la del juego, que es el SaveTooNewException del ejemplo. Esto suele ocurrir cuando un jugador sincroniza partidas en la nube entre dos dispositivos diferentes con versiones distintas del juego, o cuando prueba una beta o PTS con mejoras futuras y regresa a la versión estable.

En estos casos es necesario negarse a cargar, con un mensaje claro, y sobre todo no sobrescribir el archivo: la versión antigua del juego no sabe qué contiene, y guardar encima destruiría el progreso.

4. Algunas reglas de las migraciones

Algunas de las recomendaciones que puedo ofrecer después de mantener un formato de guardado durante varios parches serían:

  1. Las migraciones nunca se borran. Un jugador puede volver al juego después de dos años con una partida de la versión 1. La cadena entera tiene que seguir funcionando. Esta suele ser la que más fácil se olvida, ya que, un desarrollador que lleva 10 años actualizando un juego, no piensa nunca que haya jugadores que vuelvan después de 5 años de innactividad.
  2. Una migración no usa las clases actuales del juego. Trabaja sobre el documento (el JObject, o los campos crudos), no sobre los tipos del código. Si la migración 2 usa la clase Inventory y en la versión 7 esa clase cambia, la migración 2 deja de compilar o, peor, cambia de comportamiento.
  3. Los identificadores eliminados necesitan un destino. Si un objeto desaparece del juego, el archivo antiguo seguirá teniéndolo. La migración debe decidir qué hacer: sustituirlo por otro, convertirlo en moneda o eliminarlo. Lo que no puede pasar es que el juego crashee al cargar un identificador que ya no existe, o vuelva a hacer referencias a objetos que llevan tiempo sin funcionar dentro del juego.
  4. Cada versión publicada deja un archivo de prueba. Antes de publicar, se guarda una partida real de esa versión en el repositorio. Los tests de carga cogen todos esos archivos, los migran a la versión actual y comprueban que cargan sin errores y con los valores esperados.
1[TestCase("saves/v1_early_game.json")]
2[TestCase("saves/v2_mid_game.json")]
3[TestCase("saves/v3_endgame_100h.json")]
4public void OldSavesLoadIntoCurrentVersion(string path)
5{
6    var json = JObject.Parse(File.ReadAllText(path));
7    var migrated = SaveMigrator.Migrate(json);
8
9    Assert.AreEqual(SaveMigrator.CurrentVersion, migrated.Value<int>("version"));
10    Assert.DoesNotThrow(() => SaveData.FromJson(migrated));
11}

Cada partida guardada es un contrato con un jugador. El código puede cambiar todo lo que quiera, siempre que el contrato se siga cumpliendo.

5. Cada sistema guarda su parte

Cuando el juego crece, un único SaveData con todo dentro acaba siendo un cuello de botella. Inventario, misiones, ajustes y logros tocan la misma clase, y cualquier cambio en uno de ellos obliga a subir la versión de todo el archivo y a escribir una migración que recorre datos que no le importan. Además que para el desarrollador, cambiar un valor consiste en analizar el árbol completo de datos y otras estructuras que no le interesa.

Lo que escala mejor es que cada sistema sea dueño de su propia sección del archivo, identificada por una clave fija y con su propia versión. El gestor de guardado no sabe qué hay dentro de cada sección: recorre los sistemas registrados, les pide sus datos y los guarda bajo su clave. Al cargar, hace lo contrario, y cada sistema migra su sección a partir de la versión con la que se guardó.

1public interface ISaveable
2{
3    string SaveKey { get; }   // "inventory", "quests"... no cambia nunca
4    int SaveVersion { get; }
5    JObject Capture();
6    void Restore(JObject data, int fromVersion);
7}
8
9public class SaveManager
10{
11    private readonly List<ISaveable> saveables = new();
12
13    public void Register(ISaveable saveable) => saveables.Add(saveable);
14
15    public JObject CaptureAll()
16    {
17        var sections = new JObject();
18        foreach (var s in saveables)
19        {
20            sections[s.SaveKey] = new JObject
21            {
22                ["version"] = s.SaveVersion,
23                ["data"] = s.Capture(),
24            };
25        }
26
27        return new JObject
28        {
29            ["version"] = SaveMigrator.CurrentVersion,
30            ["sections"] = sections,
31        };
32    }
33
34    public void RestoreAll(JObject save)
35    {
36        var sections = (JObject)save["sections"];
37        foreach (var s in saveables)
38        {
39            // Un sistema nuevo no tiene sección en partidas antiguas: se queda con sus valores por defecto.
40            if (sections?[s.SaveKey] is not JObject section) continue;
41            s.Restore((JObject)section["data"], section.Value<int>("version"));
42        }
43    }
44}

En Unreal el sistema habitual es marcar las propiedades con UPROPERTY(SaveGame) y serializar el objeto con ArIsSaveGame. Usa la misma serialización con etiquetas que USaveGame, así que tolera igual de bien las propiedades nuevas o eliminadas.

La versión global del archivo no desaparece: sigue sirviendo para los cambios en la estructura del propio archivo, como pasar de un único bloque a secciones. Pero el día a día de cada sistema ya no la toca.

La clave de cada sección forma parte del formato. Renombrar "inventory" a "bag" es exactamente el mismo error que renombrar gold a coins: la sección antigua sigue en el archivo, pero nadie la lee.

6. Escribir sin corromper

El segundo gran motivo de partidas perdidas no son los parches, es la escritura. Si el juego está escribiendo el archivo y en ese momento se va la luz, la consola entra en reposo, el jugador cierra el proceso o el sistema mata la app en el móvil, el archivo queda a medias. Medio JSON no se puede parsear, y la partida entera desaparece.

La solución es no escribir nunca directamente sobre el archivo bueno. Se escribe primero a un archivo temporal, se asegura que los datos han llegado al disco y solo entonces se sustituye el archivo original por el nuevo, en una operación que el sistema de archivos hace de forma atómica:

1public static void WriteAtomic(string path, string contents)
2{
3    string temp = path + ".tmp";
4    string backup = path + ".bak";
5
6    using (var stream = new FileStream(temp, FileMode.Create, FileAccess.Write))
7    using (var writer = new StreamWriter(stream))
8    {
9        writer.Write(contents);
10        writer.Flush();
11        stream.Flush(flushToDisk: true);
12    }
13
14    if (File.Exists(path))
15        File.Replace(temp, path, backup); // sustituye y conserva la versión anterior
16    else
17        File.Move(temp, path);
18}

El archivo .bak es la red de seguridad. Al cargar, si el archivo principal no se puede leer (o no pasa una validación), se intenta con la copia anterior. El jugador pierde unos minutos de progreso en vez de ochenta horas.

En consolas y en algunas plataformas móviles, el acceso al disco pasa por las APIs de guardado de la plataforma, que tienen sus propias reglas (tamaños máximos, operaciones transaccionales, avisos obligatorios de "no apagues la consola"). En Unreal, UGameplayStatics::SaveGameToSlot ya se apoya en el sistema de guardado de cada plataforma. El patrón de temporal más copia de seguridad sigue siendo válido en PC, pero en consola hay que seguir lo que pida la plataforma.

Pero para saber cuándo hay que tirar de la copia, primero hay que detectar que el archivo principal está mal.

7. Validar lo que se carga

Un archivo a medias no siempre falla cuando se parsea. Si el JSON se corta justo en un punto concreto, puede quedar sintácticamente válido pero incompleto, y el binario puede leerse sin errores, aunque contenga valores basura. La forma fiable de detectarlo es utilizar un hash del contenido que se escribe junto a los datos. Al cargar se vuelve a calcular, y si no coincide, el archivo no se usa y se pasa a la última copia de seguridad guardada.

1// Formato en disco: primera línea, el hash; el resto, el JSON.
2public static string WithChecksum(string json) => Hash(json) + "\n" + json;
3
4public static JObject Load(string path)
5{
6    // Primero el principal; si está dañado, la copia del último guardado bueno.
7    return TryRead(path) ?? TryRead(path + ".bak")
8        ?? throw new SaveCorruptedException(path);
9}
10
11private static JObject TryRead(string path)
12{
13    if (!File.Exists(path)) return null;
14
15    string[] parts = File.ReadAllText(path).Split('\n', 2);
16    if (parts.Length < 2 || parts[0] != Hash(parts[1]))
17        return null;
18
19    return JObject.Parse(parts[1]);
20}
21
22private static string Hash(string text)
23{
24    using var sha = SHA256.Create();
25    byte[] bytes = sha.ComputeHash(Encoding.UTF8.GetBytes(text));
26    return BitConverter.ToString(bytes).Replace("-", "");
27}

Para detectar corrupción accidental basta con un CRC32 (un código de comprobación de 32 bits, muy rápido de calcular, pensado para detectar errores accidentales y no manipulaciones). Contra un jugador que intenta editar el archivo, ningún hash guardado junto a los datos sirve de mucho, ya que al editarlo, se puede recalcular también. En los casos donde estos es importante (rankings, partidas competitivas, datos multijugador...), la validación debe realizarse en un servidor, para garantizar esa seguridad.

El checksum dice que el archivo es el que se escribió, no que su contenido tenga sentido. Un bug de hace tres parches pudo guardar monedas negativas, un nivel por encima del máximo o un objeto que ya no existe. Por esta razón, siempre que se haga una migración y antes de pasar los datos al juego, es conveniente realizar un último saneamiento que se encargue de corregir lo imposible y deje constancia de ello:

1public static void Sanitize(SaveData save, ItemDatabase items)
2{
3    save.Coins = Mathf.Max(0, save.Coins);
4    save.Level = Mathf.Clamp(save.Level, 1, MaxLevel);
5
6    int removed = save.Inventory.RemoveAll(id => !items.Exists(id));
7    if (removed > 0)
8        Debug.LogWarning($"Eliminados {removed} objetos desconocidos del guardado");
9}

Es mejor que el jugador cargue una partida con un objeto de menos que una corrupta que no le permita jugar.

El log permite encontrar después de dónde venía el dato roto.

8. Guardar sin tirones

El último problema es de rendimiento. Serializar una partida grande y escribirla a disco puede tardar decenas de milisegundos (parece poco pero se nota al jugar), y si ocurre en el hilo principal durante un autoguardado, el jugador lo nota como un tirón. Como comenté en el artículo de profiling en Unity, estos picos puntuales son de los más molestos, porque no aparecen en la media de FPS y son difíciles de cazar.

La solución tiene dos partes.

  1. En el hilo principal solo se hace lo imprescindible: copiar el estado del juego al modelo de guardado. Es lo que se conoce como un snapshot: una copia de datos planos y rápida, tanto de hacer como de leer.
  2. En segundo plano, se realizan la serialización a texto y la escritura a disco, sobre ese snapshot, que ya no cambia aunque el juego siga corriendo.
1public async Task SaveAsync()
2{
3    // Hilo principal: copiar el estado, nada más.
4    SaveData snapshot = SaveData.CaptureFrom(gameState);
5
6    // Segundo plano: serializar y escribir.
7    await Task.Run(() =>
8    {
9        string json = JsonConvert.SerializeObject(snapshot);
10        WriteAtomic(savePath, json);
11    });
12}

En Unreal, UGameplayStatics::AsyncSaveGameToSlot hace la escritura en segundo plano y avisa con un delegado al terminar. La parte de copiar el estado al USaveGame sigue siendo responsabilidad del juego y del desarrollador, y conviene que también sea una copia de datos y no un recorrido costoso por el mundo.

Siempre que se pueda, hay que evitar que dos guardados se solapen. Si el autoguardado salta mientras el anterior todavía está escribiendo, los dos compiten por el mismo archivo temporal. Una cola de un solo elemento (si hay un guardado en curso, el siguiente espera y solo se conserva el más reciente) puede ser una buena solución.

9. Lo que dejaría montado antes de la primera build pública

Un sistema de guardado no tiene que ser complejo, pero sí tiene que estar pensado antes de que el primer jugador guarde su primera partida. Este es el mínimo que dejaría preparado:

  • Un modelo de guardado separado del modelo de juego, con identificadores en vez de referencias.
  • Un campo de versión en el archivo desde el día uno, y un migrador vacío listo para recibir la primera migración.
  • Una sección por sistema, con clave fija y versión propia.
  • Escritura atómica con copia de seguridad, y carga que intenta la copia si el principal falla.
  • Checksum al guardar y saneado al cargar, para no dar por buenos datos corruptos o imposibles.
  • Guardado en dos fases: snapshot en el hilo principal, serialización y escritura en segundo plano.
  • Un archivo de prueba por versión publicada en el repositorio, cargado por los tests en cada build.

Ninguna de estas piezas lleva más de una tarde. Lo caro es descubrir que hacían falta después de que un parche haya borrado el progreso de los jugadores, porque esas partidas ya no se pueden recuperar.

Artículos Relacionados

Ver todos los artículos
Profiling en Unity: encontrar el cuello de botella real

Profiling en Unity: encontrar el cuello de botella real

Subir los FPS a ciegas es perder el tiempo. Cómo usar el Unity Profiler para encontrar el cuello de botella real (CPU, GPU, draw calls o GC) antes de tocar una línea de código.

Strangler Fig: migrar un sistema sin apagarlo

Strangler Fig: migrar un sistema sin apagarlo

La higuera estranguladora crece alrededor de su árbol huésped hasta reemplazarlo por completo. El mismo truco sirve para migrar un sistema legacy: funcionalidad a funcionalidad, sin un big bang y sin apagar nada.

El viaje de un error: de un 500 del backend al mensaje que ve el usuario

El viaje de un error: de un 500 del backend al mensaje que ve el usuario

Un error atraviesa cuatro capas antes de llegar al usuario: el interceptor HTTP, el mapeo a errores de dominio, la política de comportamiento y la red de seguridad de render. Tres implementaciones (TypeScript, Kotlin y Swift) del mismo patrón.