Un cambio de guardado es una decisión de compatibilidad

1424. Identidad de la lección

Módulo

3.17 — Migraciones de guardado

Lección

1 — Un cambio de guardado es una decisión de compatibilidad

Tipo académico

Concepto

Tipo de esquema

texto

Orden

1 del módulo

Tiempo estimado

30–45 minutos, incluida la práctica

Esta lección establece cómo identificar la obligación de migración creada por un cambio en un campo de datos guardados. También distingue la identidad del build del juego de la identidad del esquema de los datos guardados. Todavía no diseña el procedimiento completo de migración.

1425. Objetivo de aprendizaje

Al terminar esta lección, podrás identificar la obligación de migración creada por un cambio en un esquema de datos guardados, distinguir la identidad del build que lee de la identidad del esquema guardado y declarar qué significado del jugador debe conservarse.

1426. Por qué importa

Una partida guardada es un contrato entre una versión del juego y las versiones posteriores. Cambiar un campo puede volver ilegible una partida antigua o alterar el progreso del jugador sin aviso. Antes de escribir código de migración, debes identificar la obligación de compatibilidad que crea el cambio. También debes saber qué identidad describe al programa que lee y cuál describe el formato de datos leído. Así, la lección siguiente recibe un problema preciso en lugar de un valor predeterminado supuesto.

1427. Conocimientos previos

Debes poder:

• distinguir el estado persistente del estado temporal de ejecución;
• describir los campos de un pequeño payload de guardado;
• aplicar el método de reproducir, acotar y validar de 3.16 L2 — Reproducir, acotar, validar;
• distinguir un valor de datos de la regla que lo interpreta.

No se requiere una API de migración específica de un motor.

1428. Concepto central

Un cambio en un campo de datos guardados crea una obligación de evaluar la compatibilidad cuando una partida escrita con el esquema antiguo puede ser leída con el esquema nuevo. Esa evaluación puede concluir que no hace falta código de migración si el lector nuevo puede interpretar de forma segura la representación antigua y conservar su significado. El trabajo de migración solo es necesario cuando la evaluación identifica una transformación, un valor predeterminado, un rechazo u otro tratamiento que el esquema nuevo no puede evitar.

Mantén separadas estas dos identidades:

• Identidad del build: identifica el programa o build del juego que intenta cargar la partida.
• Identidad del esquema: identifica la estructura y las reglas de los datos guardados, normalmente mediante una versión del esquema.

Un build puede leer varias identidades de esquema, y una misma identidad de esquema puede ser leída por más de un build. El número del build no indica automáticamente qué campos contiene una partida. Del mismo modo, schemaVersion no identifica el ejecutable que la está leyendo. El análisis de compatibilidad necesita ambos datos cuando sean relevantes: qué build carga y qué esquema utiliza la partida.

Para identificar esa obligación, establece tres hechos sobre el cambio de datos:

1. Representación de origen: ¿Qué contenía la partida antigua y qué versión del esquema la produjo?
2. Significado que se conserva: ¿Qué estado válido del jugador representa ese dato y debe mantenerse?
3. Cambio de destino: ¿Qué campo, tipo, nombre, unidad o estructura nueva debe representar ese significado?

Renombrar un campo, cambiar su tipo, cambiar sus unidades, eliminarlo o cambiar su significado puede requerir trabajo de migración cuando la representación antigua no puede interpretarse directamente conservando el significado válido del jugador. Añadir un campo no exige automáticamente trabajo de migración: si el campo nuevo tiene un valor predeterminado válido que conserva el significado para todas las partidas antiguas, la decisión de compatibilidad puede resolverse en el lector sin reescribir la partida. Sí crea una obligación de migración cuando las partidas antiguas no tienen un valor válido o cuando conservar el significado del campo requiere una transformación explícita u otro tratamiento.

Conviene separar tres ideas:

• Representación: cómo se almacena el valor.
• Significado: qué representa el valor en el juego.
• Invariante: qué debe cumplirse para que el valor sea válido.

En esta lección usarás esas distinciones para identificar la obligación. Elegir una política para null, definir el comportamiento ante fallos y especificar el procedimiento completo de transformación y validación corresponde a 3.17 L2 — Diseñar una migración segura.

1429. Modelo mental

Usa el modelo IDENTIDAD DEL BUILD → IDENTIDAD DEL ESQUEMA → CAMBIO → SIGNIFICADO para identificar una obligación de migración:

Los dos primeros pasos no deben fusionarse. El build identifica al lector; el esquema identifica los datos. Los dos últimos evitan un atajo frecuente: comenzar por el campo nuevo e inventar un valor. Primero analiza los datos antiguos y su significado; después expresa la obligación de compatibilidad creada por el esquema de destino.

Puedes resumir el resultado así:

build lector + representación del esquema antiguo + significado conocido → obligación de compatibilidad para la representación nueva

La siguiente lección convertirá esa obligación en un procedimiento ordenado y decidirá cómo validar el resultado transformado.

1430. Ejemplo concreto

Supón que un build identificado como build-5 lee una partida escrita con la versión de esquema 4:

{
  "schemaVersion": 4,
  "credits": 1200,
  "inventory": ["medkit"]
}

La versión 5 sustituye el campo escalar credits por un objeto de economía:

{
  "schemaVersion": 5,
  "wallet": {
    "credits": 1200,
    "debt": 0
  },
  "inventory": ["medkit"]
}

build-5 es la identidad del programa que lee. schemaVersion: 4 es la identidad del formato de datos guardados. Responden preguntas distintas; ninguna de las dos demuestra por sí sola la compatibilidad.

La obligación de migración no consiste simplemente en «añadir una clave wallet». Es la siguiente:

• Cambio: credits pasa a wallet.credits y aparece wallet.debt.
• Esquema de origen: las partidas con versión de esquema 4 usan la representación antigua.
• Significado: el saldo existente del jugador debe seguir siendo 1200 y el inventario debe permanecer sin cambios.
• Contexto del lector: el build actual debe decidir cómo tratar el esquema 4 mientras espera el esquema 5.

La estructura de destino es la versión 5, pero el procedimiento detallado para crearla, validarla y tratar valores excepcionales queda aplazado a L2.

1431. Error común

El error común es tratar un cambio de esquema como un problema del constructor: añadir el campo que falta, asignarle un valor conveniente y continuar. Esto evita preguntar qué significan los datos antiguos y puede cambiar el estado del jugador sin declarar una obligación de compatibilidad.

Un error relacionado es tratar el número del build y la versión del esquema como si fueran intercambiables. El número del build identifica el software; la versión del esquema identifica los datos guardados. Confundirlos puede hacer que el cargador aplique una interpretación equivocada o suponga, sin evidencia, que un build puede leer un formato concreto.

Otro error consiste en suponer que un número de versión vuelve compatible una partida automáticamente. La versión identifica el formato de origen; no identifica por sí sola el significado que debe conservarse ni completa la migración.

1432. Práctica guiada

Analiza este cambio propuesto sin escribir código. Supón que el lector actual es el build build-3.

La versión 2 almacena el mejor tiempo en milisegundos:

{
  "schemaVersion": 2,
  "bestTimeMs": 90500,
  "level": 6
}

La versión 3 almacena el mismo resultado en segundos decimales y renombra el campo:

{
  "schemaVersion": 3,
  "bestTimeSeconds": 90.5,
  "level": 6
}

Escribe una identificación en cuatro partes de la obligación de migración:

1. IDENTIDAD DEL BUILD: identifica el programa que intenta leer la partida: build-3.
2. IDENTIDAD DEL ESQUEMA: identifica la versión de datos que contiene la forma antigua: versión de esquema 2.
3. CAMBIO: nombra el campo, la representación y las unidades que cambiaron.
4. SIGNIFICADO: indica qué resultado del jugador debe seguir siendo equivalente, incluido el hecho de que 90500 milisegundos representa 90.5 segundos, y que level debe permanecer sin cambios.

Explica explícitamente por qué build-3 y la versión de esquema 2 no son la misma identidad. No diseñes el procedimiento de transformación, no elijas una política para null ni especifiques el comportamiento ante fallos. Esas decisiones quedan aplazadas a 3.17 L2 — Diseñar una migración segura.

1433. Validación / evidencia

1434. Puntos clave

• Un cambio en datos guardados crea una obligación cuando una partida antigua puede ser leída por código nuevo.
• La identidad del build identifica al lector; la identidad del esquema identifica el formato de los datos guardados.
• Las versiones de esquema identifican la representación de origen; no ejecutan la migración ni demuestran la compatibilidad.
• Primero identifica la representación que cambió y después decide qué significado del jugador debe conservarse.
• La transformación detallada, la validación y las políticas para null y fallos corresponden al procedimiento de migración segura de L2.

1435. Siguiente lección

Siguiente: Diseñar una migración segura, donde convertirás la obligación de compatibilidad identificada en un procedimiento ordenado con decisiones explícitas de transformación y validación.

1436. Comprobación