< [Voltar](chapter-12.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-14.md) >

# Cartuchos

**Versão:** 1.0 (baseline estável)
**Status:** Proposta

---

## 1. Objetivo

Definir um contrato mínimo e estável para cartuchos Prometeu, permitindo:

* Identificação do app
* Seleção de modo (Game/System)
* Resolução de entrypoint
* Carregamento previsível pelo runtime

---

## 2. Conceito

Um cartucho é a unidade distribuível do Prometeu. Ele pode existir como:

* **Diretório (dev)** — ideal para desenvolvimento e hot-reload
* **Arquivo empacotado (.pmc)** — ideal para distribuição

Ambos compartilham o mesmo layout lógico.

---

## 3. Layout Lógico

```
<cartridge>/
 ├── manifest.json
 ├── program.pbc
 └── assets/
     └── ...
```

Campos obrigatórios:

* `manifest.json`
* `program.pbc` (bytecode Prometeu)

---

## 4. manifest.json (Contrato v1)

```json
{
  "magic": "PMTU",
  "cartridge_version": 1,
  "app_id": 1234,
  "title": "Meu Jogo",
  "app_version": "1.0.0",
  "app_mode": "Game",        // Game | System
  "entrypoint": "main"
}
```

### Campos

* `magic`: string fixa `PMTU`
* `cartridge_version`: versão do formato
* `app_id`: identificador numérico único
* `title`: nome do app
* `app_version`: versão do app
* `app_mode`: `Game` ou `System`
* `entrypoint`: símbolo ou índice reconhecido pela VM

---

## 5. Regras do Runtime

* Validar `magic` e `cartridge_version`
* Ler `app_mode` para decidir fluxo de execução
* Resolver `entrypoint` no `program.pbc`
* Ignorar `assets/` se não suportado ainda

---

## 6. Modos de Uso

### Diretório (desenvolvimento)

```
prometeu --run ./mycart/
```

### Arquivo empacotado

```
prometeu --run mygame.pmc
```

Ambos devem se comportar de forma idêntica no runtime.

---

## 7. Estabilidade do Contrato

A partir do v1:

* `manifest.json` é a fonte de verdade
* Campos só podem ser adicionados de forma backward-compatible
* Mudanças incompatíveis exigem `cartridge_version` novo

< [Voltar](chapter-12.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-14.md) >