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