238 lines
4.3 KiB
Markdown
238 lines
4.3 KiB
Markdown
< [Back](chapter-7.md) | [Summary](table-of-contents.md) | [Next](chapter-9.md) >
|
|
|
|
# 📀 MEMCARD Peripheral (Save/Load System)
|
|
|
|
## 1. Overview
|
|
|
|
The **MEMCARD** is the peripheral responsible for the **explicit persistence of game data** in PROMETEU.
|
|
|
|
It simulates the behavior of classic *memory cards* (PS1, GameCube), providing:
|
|
|
|
- limited storage
|
|
- explicit I/O cost
|
|
- full game control over when to save
|
|
- portability across platforms
|
|
|
|
The MEMCARD **is not a save state**.
|
|
|
|
It represents **data that the game itself decides to persist**.
|
|
|
|
---
|
|
|
|
## 2. Design Principles
|
|
|
|
The MEMCARD peripheral follows these principles:
|
|
|
|
- ✅ **Explicit persistence** (nothing automatic)
|
|
- ✅ **Limited and known size**
|
|
- ✅ **Mandatory commit**
|
|
- ✅ **Measurable time cost (cycles)**
|
|
- ✅ **Stable and documented format**
|
|
- ✅ **Platform independent**
|
|
- ❌ No complex file system (in v0.1)
|
|
- ❌ No multiple internal files (in v0.1)
|
|
|
|
---
|
|
|
|
## 3. Conceptual Model
|
|
|
|
Each PROMETEU cartridge can access **one or more MEMCARD slots**, the default model being:
|
|
|
|
- **Slot A** — main
|
|
- **Slot B** — optional (future)
|
|
|
|
Each slot corresponds to **a file on the host**:
|
|
|
|
```
|
|
MyGame_A.mem
|
|
MyGame_B.mem
|
|
```
|
|
|
|
The runtime mounts this file as a **persistent storage device**.
|
|
|
|
---
|
|
|
|
## 4. Capacity and CAP
|
|
|
|
The size of the MEMCARD is **fixed**, defined by the execution profile (CAP).
|
|
|
|
### Suggested sizes
|
|
|
|
| Profile | Size |
|
|
| --- | --- |
|
|
| JAM | 8 KB |
|
|
| STANDARD | 32 KB |
|
|
| ADVANCED | 128 KB |
|
|
|
|
The game **cannot exceed** this size.
|
|
|
|
Attempts to write above the limit result in an error.
|
|
|
|
---
|
|
|
|
## 5. Peripheral API (v0.1)
|
|
|
|
### 5.1 Logical Interface
|
|
|
|
The MEMCARD exposes a **simple single-blob API**:
|
|
|
|
```
|
|
mem.read_all() -> byte[]
|
|
mem.write_all(byte[])
|
|
mem.commit()
|
|
mem.clear()
|
|
mem.size() -> int
|
|
```
|
|
|
|
---
|
|
|
|
### 5.2 Operation Semantics
|
|
|
|
### `read_all()`
|
|
|
|
- Returns all persisted content
|
|
- If the card is empty, returns a zeroed buffer
|
|
- Cycle cost proportional to size
|
|
|
|
---
|
|
|
|
### `write_all(bytes)`
|
|
|
|
- Writes the buffer **to temporary memory**
|
|
- Does not persist immediately
|
|
- Fails if `bytes.length > mem.size()`
|
|
|
|
---
|
|
|
|
### `commit()`
|
|
|
|
- Persists data to the device
|
|
- **Mandatory** operation
|
|
- Simulates hardware flush
|
|
- May fail (e.g., I/O, simulated corruption)
|
|
|
|
---
|
|
|
|
### `clear()`
|
|
|
|
- Zeroes the card content
|
|
- Requires `commit()` to persist
|
|
|
|
---
|
|
|
|
### `size()`
|
|
|
|
- Returns total card capacity in bytes
|
|
|
|
---
|
|
|
|
## 6. Explicit Commit (Fundamental Rule)
|
|
|
|
PROMETEU **does not save automatically**.
|
|
|
|
Without `commit()`:
|
|
|
|
- data remains volatile
|
|
- can be lost upon exiting the game
|
|
- simulates abrupt hardware shutdown
|
|
|
|
👉 This teaches:
|
|
|
|
- data flushing
|
|
- atomicity
|
|
- risk of corruption
|
|
- real cost of persistence
|
|
|
|
---
|
|
|
|
## 7. Execution Cost (Cycles)
|
|
|
|
All MEMCARD operations have an explicit cost.
|
|
|
|
### Example (illustrative values)
|
|
|
|
| Operation | Cost |
|
|
| --- | --- |
|
|
| read_all | 1 cycle / 256 bytes |
|
|
| write_all | 1 cycle / 256 bytes |
|
|
| commit | fixed + proportional cost |
|
|
|
|
These costs appear:
|
|
|
|
- in the profiler
|
|
- in the frame timeline
|
|
- in the CAP report
|
|
|
|
---
|
|
|
|
## 8. `.mem` File Format
|
|
|
|
The MEMCARD file has a simple and robust format.
|
|
|
|
### 8.1 Header
|
|
|
|
| Field | Size |
|
|
| --- | --- |
|
|
| Magic (`PMEM`) | 4 bytes |
|
|
| Version | 1 byte |
|
|
| Cart ID | 8 bytes |
|
|
| Payload Size | 4 bytes |
|
|
| CRC32 | 4 bytes |
|
|
|
|
---
|
|
|
|
### 8.2 Payload
|
|
|
|
- Binary buffer defined by the game
|
|
- Fixed size
|
|
- Content interpreted only by the game
|
|
|
|
---
|
|
|
|
## 9. Integrity and Security
|
|
|
|
- CRC validates corruption
|
|
- Cart ID prevents using wrong save
|
|
- Version allows future format evolution
|
|
- Runtime can:
|
|
- warn of corruption
|
|
- allow card reset
|
|
|
|
---
|
|
|
|
## 10. Integration with the Editor / GUI
|
|
|
|
The main tool can provide a **Memory Card Manager**:
|
|
|
|
- create/reset card
|
|
- see size and usage
|
|
- import/export `.mem`
|
|
- visualize last commits
|
|
- associate cards with projects
|
|
|
|
None of these operations change the runtime.
|
|
|
|
---
|
|
|
|
## 11. Planned Evolutions (outside v0.1)
|
|
|
|
- Block API (`read_block`, `write_block`)
|
|
- multiple internal slots
|
|
- wear simulation
|
|
- save versioning
|
|
- optional encryption (educational)
|
|
|
|
---
|
|
|
|
## 12. Summary
|
|
|
|
The MEMCARD peripheral in PROMETEU:
|
|
|
|
- simulates real hardware
|
|
- forces design decisions
|
|
- teaches persistence correctly
|
|
- is simple to use
|
|
- is hard to abuse
|
|
- grows without breaking compatibility
|
|
|
|
< [Back](chapter-7.md) | [Summary](table-of-contents.md) | [Next](chapter-9.md) > |