110 lines
1.9 KiB
Markdown
110 lines
1.9 KiB
Markdown
< [Back](chapter-12.md) | [Summary](table-of-contents.md) | [Next](chapter-14.md) >
|
|
|
|
# Cartridges
|
|
|
|
**Version:** 1.0 (stable baseline)
|
|
**Status:** Proposal
|
|
|
|
---
|
|
|
|
## 1. Objective
|
|
|
|
Define a minimum and stable contract for Prometeu cartridges, allowing:
|
|
|
|
* App identification
|
|
* Mode selection (Game/System)
|
|
* Entrypoint resolution
|
|
* Predictable loading by the runtime
|
|
|
|
---
|
|
|
|
## 2. Concept
|
|
|
|
A cartridge is the distributable unit of Prometeu. It can exist as:
|
|
|
|
* **Directory (dev)** — ideal for development and hot-reload
|
|
* **Packaged file (.pmc)** — ideal for distribution
|
|
|
|
Both share the same logical layout.
|
|
|
|
---
|
|
|
|
## 3. Logical Layout
|
|
|
|
```
|
|
<cartridge>/
|
|
├── manifest.json
|
|
├── program.pbc
|
|
└── assets/
|
|
└── ...
|
|
```
|
|
|
|
Required fields:
|
|
|
|
* `manifest.json`
|
|
* `program.pbc` (Prometeu bytecode)
|
|
|
|
---
|
|
|
|
## 4. manifest.json (Contract v1)
|
|
|
|
```json
|
|
{
|
|
"magic": "PMTU",
|
|
"cartridge_version": 1,
|
|
"app_id": 1234,
|
|
"title": "My Game",
|
|
"app_version": "1.0.0",
|
|
"app_mode": "Game",
|
|
"entrypoint": "main"
|
|
}
|
|
```
|
|
|
|
### Fields
|
|
|
|
* `magic`: fixed string `PMTU`
|
|
* `cartridge_version`: format version
|
|
* `app_id`: unique numerical identifier
|
|
* `title`: name of the app
|
|
* `app_version`: app version
|
|
* `app_mode`: `Game` or `System`
|
|
* `entrypoint`: symbol or index recognized by the VM
|
|
|
|
---
|
|
|
|
## 5. Runtime Rules
|
|
|
|
* Validate `magic` and `cartridge_version`
|
|
* Read `app_mode` to decide execution flow
|
|
* Resolve `entrypoint` in `program.pbc`
|
|
* Ignore `assets/` if not supported yet
|
|
|
|
---
|
|
|
|
## 6. Usage Modes
|
|
|
|
### Directory (development)
|
|
|
|
```
|
|
prometeu --run ./mycart/
|
|
```
|
|
|
|
### Packaged file
|
|
|
|
```
|
|
prometeu --run mygame.pmc
|
|
```
|
|
|
|
Both must behave identically in the runtime.
|
|
|
|
---
|
|
|
|
## 7. Contract Stability
|
|
|
|
From v1 onwards:
|
|
|
|
* `manifest.json` is the source of truth
|
|
* Fields can only be added in a backward-compatible manner
|
|
* Incompatible changes require a new `cartridge_version`
|
|
|
|
< [Back](chapter-12.md) | [Summary](table-of-contents.md) | [Next](chapter-14.md) > |