4.3 KiB
📀 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