< [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) >