# Migre formas salvas antigas deliberadamente

> Defina como ler dados salvos por versões anteriores do jogo e migre os formatos conhecidos antes de usá-los.

- URL: https://oneshotgems.ai/pt-BR/topics/local-storage-game-versioning
- Categoria: Para desenvolvedores de jogos
- Tipo: Guia
- Atualizado: 5 de outubro de 2026

O teste de salvamento pergunta se os valores pretendidos persistem. O controle de versão responde a uma pergunta diferente: o que deve acontecer quando uma versão posterior do jogo lê dados escritos por uma versão mais antiga? Se a versão um armazenasse a melhor pontuação como um número e a versão dois armazenasse um objeto de perfil, ler a forma antiga como se fosse nova pode quebrar o menu ou descartar silenciosamente o progresso. Coloque uma versão ao lado dos dados salvos e escreva uma migração explícita para formas anteriores conhecidas.

## Mantenha os valores em um objeto pequeno e versionado

Em vez de salvar uma pontuação simples como 240, armazene um objeto JSON como { version: 2, bestScore: 240, settings: { sound: true } }. Ao carregar, analise o texto, verifique se é um objeto e inspecione sua versão antes de usar os campos. JSON.parse pode lançar um SyntaxError para JSON inválido, portanto, lide com texto malformado com um substituto definido em vez de permitir que a inicialização pare antes que o player possa começar.

Mantenha o objeto enxuto e documente o significado de cada versão. Não considere o número da versão uma validação suficiente: um valor marcado como versão 2 ainda pode estar incompleto ou ter o tipo errado. Verifique os campos dos quais a versão atual realmente depende, como bestScore, que deve ser um número finito e não negativo, e a preferência de som, que deve ser booleana.

## Escreva uma migração para cada formato antigo compatível

Uma migração da versão 1 pode converter o número antigo no novo objeto, preencher uma preferência padrão e salvar o formato da versão 2. Execute as migrações em sequência quando houver suporte a várias versões históricas: da versão 1 para a 2 e depois da 2 para a 3. Teste cada caso de teste separadamente, incluindo uma chave ausente, JSON malformado, uma versão futura desconhecida e um valor parcialmente gravado. Decida se os dados desconhecidos serão preservados, ignorados ou redefinidos e, quando necessário, exiba uma mensagem de recuperação.

## Considere os limites do armazenamento do navegador

A MDN descreve localStorage como dados associados a uma origem que podem persistir entre sessões do navegador, mas sua disponibilidade e seu conteúdo não devem ser tratados como um backup de conta garantido. Não armazene ali segredos nem decisões que precisem ser confiáveis. Se o jogo não conseguir ler um salvamento, permita um novo começo definido e evite tentar novamente a mesma migração interrompida em todo início.

## Perguntas

**Devo limpar todos os salvamentos quando o formato mudar?** Somente quando essa for uma decisão explícita do produto. Se valores importantes puderem ser mapeados com segurança, uma pequena migração testada poderá preservá-los; caso contrário, defina um substituto claro e explique a redefinição.

**Um campo de versão torna os dados do localStorage confiáveis?** Não. Ele identifica a forma esperada para que o jogo possa migrá-la ou rejeitá-la. Os dados ainda podem estar ausentes, malformados, desatualizados ou indisponíveis, portanto, valide antes de usá-los.

## Siga sua curiosidade

- [Teste o estado de salvamento em um jogo de navegador](https://oneshotgems.ai/pt-BR/topics/testing-game-save-state): Verifique o que um jogo de navegador salva, o que é redefinido e como ele se comporta quando os dados armazenados estão ausentes, obsoletos ou alterados entre as sessões.
- [Um loop de teste de regressão para jogos pequenos](https://oneshotgems.ai/pt-BR/topics/game-regression-testing): Proteja um loop de jogo funcional após as revisões com uma pequena lista de verificação de regressão focada em mecânica, pontuação, reinicialização e casos extremos próximos.

## Leitura complementar

- [Armazenamento local MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
- [MDN JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse)

---
Página canônica: https://oneshotgems.ai/pt-BR/topics/local-storage-game-versioning