< [Voltar](chapter-7.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-9.md) > # 📀 Periférico MEMCARD (Sistema de save/load) ## 1. Visão Geral O **MEMCARD** é o periférico responsável pela **persistência explícita de dados do jogo** no PROMETEU. Ele simula o comportamento de *memory cards* clássicos (PS1, GameCube), fornecendo: - armazenamento limitado - custo explícito de I/O - controle total do jogo sobre quando salvar - portabilidade entre plataformas O MEMCARD **não é um save state**. Ele representa **dados que o próprio jogo decide persistir**. --- ## 2. Princípios de Design O periférico MEMCARD segue os seguintes princípios: - ✅ **Persistência explícita** (nada automático) - ✅ **Tamanho limitado e conhecido** - ✅ **Commit obrigatório** - ✅ **Custo de tempo (ciclos) mensurável** - ✅ **Formato estável e documentado** - ✅ **Independente de plataforma** - ❌ Sem sistema de arquivos complexo (no v0.1) - ❌ Sem múltiplos arquivos internos (no v0.1) --- ## 3. Modelo Conceitual Cada cartucho PROMETEU pode acessar **um ou mais slots de MEMCARD**, sendo o modelo padrão: - **Slot A** — principal - **Slot B** — opcional (futuro) Cada slot corresponde a **um arquivo no host**: ``` MyGame_A.mem MyGame_B.mem ``` O runtime monta esse arquivo como um **dispositivo de armazenamento persistente**. --- ## 4. Capacidade e CAP O tamanho do MEMCARD é **fixo**, definido pelo perfil de execução (CAP). ### Tamanhos sugeridos | Perfil | Tamanho | | --- | --- | | JAM | 8 KB | | STANDARD | 32 KB | | ADVANCED | 128 KB | O jogo **não pode exceder** esse tamanho. Tentativas de escrita acima do limite resultam em erro. --- ## 5. API do Periférico (v0.1) ### 5.1 Interface Lógica O MEMCARD expõe uma API **simples de blob único**: ``` mem.read_all() -> byte[] mem.write_all(byte[]) mem.commit() mem.clear() mem.size() -> int ``` --- ### 5.2 Semântica das Operações ### `read_all()` - Retorna todo o conteúdo persistido - Se o cartão estiver vazio, retorna um buffer zerado - Custo em ciclos proporcional ao tamanho --- ### `write_all(bytes)` - Escreve o buffer **em memória temporária** - Não persiste imediatamente - Falha se `bytes.length > mem.size()` --- ### `commit()` - Persiste os dados no dispositivo - Operação **obrigatória** - Simula flush de hardware - Pode falhar (ex.: I/O, corrupção simulada) --- ### `clear()` - Zera o conteúdo do cartão - Requer `commit()` para persistir --- ### `size()` - Retorna a capacidade total do cartão em bytes --- ## 6. Commit Explícito (Regra Fundamental) O PROMETEU **não salva automaticamente**. Sem `commit()`: - dados permanecem voláteis - podem ser perdidos ao encerrar o jogo - simulam desligamento abrupto de hardware 👉 Isso ensina: - flush de dados - atomicidade - risco de corrupção - custo real de persistência --- ## 7. Custo de Execução (Ciclos) Todas as operações de MEMCARD têm custo explícito. ### Exemplo (valores ilustrativos) | Operação | Custo | | --- | --- | | read_all | 1 ciclo / 256 bytes | | write_all | 1 ciclo / 256 bytes | | commit | custo fixo + proporcional | Esses custos aparecem: - no profiler - na timeline de frame - no relatório de CAP --- ## 8. Formato do Arquivo `.mem` O arquivo de MEMCARD possui um formato simples e robusto. ### 8.1 Header | Campo | Tamanho | | --- | --- | | Magic (`PMEM`) | 4 bytes | | Version | 1 byte | | Cart ID | 8 bytes | | Payload Size | 4 bytes | | CRC32 | 4 bytes | --- ### 8.2 Payload - Buffer binário definido pelo jogo - Tamanho fixo - Conteúdo interpretado apenas pelo jogo --- ## 9. Integridade e Segurança - CRC valida corrupção - Cart ID impede uso de save errado - Versão permite evolução futura do formato - Runtime pode: - avisar corrupção - permitir reset do cartão --- ## 10. Integração com o Editor / GUI A ferramenta principal pode fornecer um **Memory Card Manager**: - criar/resetar cartão - ver tamanho e uso - importar/exportar `.mem` - visualizar últimos commits - associar cartões a projetos Nenhuma dessas operações altera o runtime. --- ## 11. Evoluções Planejadas (fora do v0.1) - API de blocos (`read_block`, `write_block`) - múltiplos slots internos - wear simulation - versionamento de saves - criptografia opcional (educacional) --- ## 12. Resumo O periférico MEMCARD no PROMETEU: - simula hardware real - força decisões de design - ensina persistência corretamente - é simples de usar - é difícil de abusar - cresce sem quebrar compatibilidade < [Voltar](chapter-7.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-9.md) >