Guarda el contrato, no la escena

874. Identidad de la lección

Módulo

2.13 — Guardado y carga

Lección

Guarda el contrato, no la escena

Tipo académico

Concepto

Tipo de esquema

texto

Orden

1

Tiempo estimado

30–40 minutos, incluida la práctica

Esta lección establece cómo decidir qué debe entrar en un archivo de guardado, qué debe descartarse, qué debe reconstruirse como presentación, qué debe recalcularse y qué sistema es responsable de cada campo duradero.

875. Objetivo de aprendizaje

Al terminar esta lección, podrás crear un inventario del estado de guardado para un fragmento de juego con varios sistemas, clasificando el estado duradero, transitorio, de presentación y derivado, asignando propietarios a los campos duraderos e identificando el procedimiento de reconstrucción del estado no duradero.

876. Por qué importa

Un archivo de guardado no es una fotografía de la escena en ejecución. Es una representación duradera del estado necesario para continuar una partida válida. Guardar convierte cada sistema participante en un contrato: los campos necesitan un significado estable, un propietario claro y un procedimiento de reconstrucción definido. Si una implementación generada por IA serializa objetos de la escena sin criterio, puede conservar detalles visuales y perder las reglas que mantienen coherente el juego.

877. Conocimientos previos

Debes poder identificar límites y contratos entre sistemas de Stage 2. En particular, esta lección parte del módulo 2.12 — La llegada es un contrato, no una suposición de distancia. Debes distinguir una condición de juego autoritativa de un detalle de presentación y de un valor calculado a partir de otro estado.

878. Concepto central

El concepto central es el límite de serialización.

Persiste solamente el estado duradero necesario para restaurar el contrato del juego. El estado transitorio es temporal y puede descartarse o resolverse antes de guardar. El estado de presentación es la expresión visual o de interfaz de otro estado. El estado derivado se calcula a partir de hechos autoritativos o de las reglas actuales. Cada categoría requiere un tratamiento distinto:

Serializar no significa «guardar todas las variables». Significa seleccionar deliberadamente la representación estable más pequeña capaz de restaurar el estado previsto. Una transacción aún no confirmada, un bloqueo temporal de interacción o un objetivo almacenado en caché pueden ser importantes durante la ejecución sin formar parte del contrato duradero.

879. Propiedad del esquema

Cada campo persistido debe tener un único sistema propietario. Ese propietario define:

1. El significado del campo.
2. Su rango válido o sus valores permitidos.
3. Cuándo puede cambiar.
4. Cómo se valida al cargar.
5. Cómo se usa para reconstruir el estado de ejecución.

Por ejemplo, el sistema de inventario puede ser propietario de credits e items. Un controlador de escena puede mostrar esos valores, pero no debería convertirse en su propietario de guardado solo porque tiene acceso a la UI o a los nodos de la escena. Una transacción de inventario pendiente puede pertenecer al sistema de transacciones mientras está activa, pero es transitoria salvo que el juego prometa explícitamente reanudar esa operación inconclusa.

880. Modelo mental

Usa el modelo contrato, ejecución, reconstrucción, derivación:

CONTRATO DURADERO
    ↓ serializar
DATOS DE GUARDADO
    ↓ cargar y validar
ESTADO DE EJECUCIÓN
    ├── operaciones transitorias: resolver o descartar
    ├── presentación: reconstruir o volver a enlazar
    └── valores derivados: recalcular desde hechos duraderos

Para cada posible campo, responde cuatro preguntas:

Para cada campo duradero, pregunta además qué sistema define su significado y sus cambios válidos. Ese sistema es su propietario.

Este modelo evita dos errores opuestos. Guardar demasiado poco provoca pérdida de progreso o reglas inconsistentes. Guardar demasiado crea autoridades duplicadas, valores obsoletos y un acoplamiento frágil con la estructura actual de la escena.

881. Ejemplo concreto

Considera un fragmento pequeño con un jugador, un inventario y una puerta que se abre cuando el jugador obtiene un pase.

El archivo de guardado no necesita contener un objeto puerta serializado, una pista de animación, un nodo de UI ni una operación de compra sin terminar. Necesita los hechos duraderos que determinan si la puerta debe estar abierta y desde dónde debe continuar el jugador. El controlador de la puerta y la UI reconstruyen después su presentación a partir de esos hechos.

Queda una decisión importante: ¿la posición exacta del jugador es duradera? Si el juego promete continuar desde el lugar exacto, guárdala. Si promete reiniciar desde un punto de control o una sala segura, guarda el identificador del punto de control. La respuesta proviene del contrato del juego, no de la variable que resulte más fácil de serializar.

882. Error común

El error común es tratar todo valor no duradero como si perteneciera a la misma categoría, o tratar el árbol de la escena actual como si fuera el esquema de guardado.

Una transacción pendiente no es lo mismo que una etiqueta del HUD. La transacción es estado de proceso transitorio; la etiqueta es presentación. Ninguno debe convertirse automáticamente en datos guardados. Una escena también contiene objetos temporales, referencias del motor, valores en caché y estado visual. Es una organización de implementación, no necesariamente el contrato duradero.

Otro error frecuente es guardar tanto un valor autoritativo como su derivado—por ejemplo, guardar hasPass y openGateCount—sin definir cuál prevalece si no coinciden. Al cargar, las autoridades duplicadas pueden producir un juego que parece correcto pero contradice sus propias reglas.

883. Práctica guiada

Crea un inventario del estado de guardado para este fragmento con varios sistemas:

• El jugador puede llevar créditos y objetos.
• Un contrato está activo o inactivo.
• El destino actual es una de tres regiones.
• La presentación de una puerta cambia cuando se completa el contrato.
• El HUD muestra los créditos, el contrato activo y el nombre de la región actual.
• La animación de apertura de la puerta y las etiquetas del HUD se crean durante la ejecución.
• Una transacción de inventario puede permanecer pendiente brevemente antes de confirmar los créditos y los objetos.

Construye una tabla con estas columnas:

Campo posible | Duradero / Transitorio / Presentación / Derivado | Sistema propietario | ¿Guardar, resolver, descartar o reconstruir? | Motivo

Clasifica al menos estos elementos:

• credits
• items
• contractCompleted
• currentRegionId
• pendingInventoryTransaction
• referencia al objeto puerta
• progreso de la animación de la puerta
• texto de créditos del HUD
• etiqueta de región del HUD
• número de contratos completados

Para pendingInventoryTransaction, toma una decisión explícita: indica si la transacción debe confirmarse o cancelarse antes de guardar y explica por qué la operación inconclusa no es automáticamente un estado duradero. Conserva en el contrato duradero el resultado confirmado—como los créditos o los objetos actualizados—si el juego promete que ese resultado sobrevivirá.

Después toma una decisión explícita sobre la ubicación del jugador: elige playerPosition o checkpointId como representación duradera. Explica qué promesa de continuidad justifica tu elección.

No empieces enumerando variables de una escena. Empieza por los hechos que el jugador espera conservar después de cerrar y volver a abrir el juego. Si un valor puede calcularse a partir de otro valor guardado, márcalo como derivado e identifica su fuente.

884. Validación / evidencia

885. Puntos clave

• Un archivo de guardado representa hechos duraderos del juego, no un árbol de escena capturado.
• Las operaciones transitorias deben resolverse, cancelarse o descartarse salvo que el juego prometa explícitamente reanudarlas.
• Los objetos de ejecución y la presentación deben reconstruirse a partir del contrato guardado.
• Los valores derivados deben recalcularse a partir del estado autoritativo, no guardarse como autoridades competidoras.
• Cada campo persistido necesita un sistema propietario y un significado definido.

886. Siguiente lección

Continúa con 2.13 L2 — Restaura los sistemas en un orden deliberado.

887. Persistencia (fix-save-roundtrip)

Abre academy-fixtures/labs/save-roundtrip. Ejecuta node run.mjs. Inspecciona qué campos son duraderos. La presentación y lastFeedback no son una segunda autoridad de guardado.

888. Contratos de handoff (fix-handoff-contracts)

Abre academy-fixtures/labs/handoff-contracts. Ejecuta node run.mjs. Registra entradas, salidas, owner, invariantes, fallo (escritura ilegal) y validación. Luego fix-save-roundtrip: academy-fixtures/labs/save-roundtrip → node run.mjs.

889. Comprobación