238 lines
4.6 KiB
Markdown
238 lines
4.6 KiB
Markdown
< [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) > |