Migração de esquema de save games e gravações recuperáveis

Um save é uma interface de longa duração

Um arquivo de save pode durar mais que o código que o gerou. Renomear um campo, mudar unidades ou dividir uma estrutura de inventário altera essa interface, mesmo que o parsing continue funcionando. Projete a persistência em torno de um modelo de dados documentado, de uma versão de esquema e de um caminho de recuperação, em vez de serializar objetos vivos arbitrários.

Formato não é compatibilidade

O guia de salvamento do Godot ilustra a serialização explícita do estado do jogo e as limitações dos tipos JSON. [1] O Protocol Buffers documenta regras de compatibilidade, incluindo preservar a identidade dos números de campo e reservar os números removidos. [2] Um formato de serialização ajuda a representar dados; o significado específico do jogo, os valores padrão, as migrações e as faixas de versão suportadas continuam sendo responsabilidade do projeto.

Exemplo prático

Um save ilustrativo da versão 1 contém coins: 125. A versão 2 substitui esse campo por wallet: {gold: 125}. A versão 3 adiciona difficulty, usando normal somente ao migrar um save mais antigo que não tem o campo.

Implemente as transformações 1 → 2 e 2 → 3 sobre os dados já decodificados. Depois do primeiro passo, verifique se a moeda continua 125; depois do segundo, verifique o valor padrão e se todo o progresso não relacionado foi preservado. Avance a versão registrada somente depois que cada transformação for bem-sucedida. Um save da versão 3 não deve receber uma concessão extra só por ser carregado novamente.

Se um save da versão 5 for mais novo do que este loader suporta, preserve-o e informe a incompatibilidade. Tentar adivinhar seu significado e sobrescrevê-lo com a versão 3 transformaria um problema temporário de compatibilidade em perda de dados.

Fluxo de migração e restauração

Mantenha fixtures imutáveis para cada esquema histórico suportado, incluindo campos opcionais ausentes e valores-limite. Valide tipos de dados, intervalos, identificadores estáveis de objetos, assets obrigatórios e referências cruzadas antes de substituir o mundo ativo. Sempre que possível, construa o estado restaurado de forma isolada e então o ative depois da validação.

Separe a migração de esquema do remapeamento de conteúdo: um item removido do jogo exige uma política documentada de substituição ou compensação, e não apenas a renomeação de um campo. Faça com que os erros indiquem o que fazer e mantenha o save utilizável anterior até que o substituto seja verificado.

Limites de commit e de falha

Em saves baseados em SQLite, faça o commit dos dados e da versão do esquema em uma única transação; a documentação de atomic commit do SQLite explica tanto o mecanismo quanto as premissas sobre o armazenamento. [3] Em saves em arquivo, prepare uma substituição completa e use as operações de substituição atômica e de durabilidade suportadas pela plataforma. Um rename, sozinho, não é uma garantia universal contra perda de energia.

Teste gravações interrompidas, armazenamento cheio, entrada corrompida e falha de migração. Um checksum pode detectar corrupção acidental, mas não comprova que a semântica do jogo seja válida. Defina de forma explícita a escolha do backup e a recuperação, e nunca informe sucesso antes de a operação de persistência escolhida ter sido concluída com êxito.

Fontes

[1] Saving games — documentação do Godot Engine.

[2] Proto3 language guide — documentação do Protocol Buffers.

[3] Atomic commit — desenvolvedores do SQLite.