4.1 KiB
Save Memory and MEMCARD
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