# 📜 Prometeu — O Fogo e a Promessa

**PROMETEU** é um console imaginário.

Mas não no sentido fraco de “imaginar”.

PROMETEU foi **deliberadamente projetado** para existir como um **modelo computacional completo**: simples o bastante para ser entendido, e poderoso o suficiente para criar jogos reais.

O nome PROMETEU carrega dois significados intencionais:

- **Prometeu, o titã**, que roubou o fogo dos deuses e entregou aos humanos
- **“Prometeu” como verbo**, uma promessa feita

Neste projeto:

- o *fogo* é o conhecimento de como computadores realmente funcionam
- a *promessa* é que nada é mágico, nada é escondido, e tudo pode ser compreendido

Este manual é essa promessa escrita.

---

## 🎯 O que é o PROMETEU

PROMETEU é um **Virtual Microconsole** — um computador fictício, com regras claras, recursos limitados e comportamento determinístico.

Ele foi projetado para:

- ensinar fundamentos reais de computação
- expor tempo, memória e execução
- permitir jogos 2D completos (plataformers, metroidvanias, arcade)
- servir como ponte entre:
    - microcontroladores
    - consoles clássicos
    - máquinas virtuais
    - engines modernas

PROMETEU **não é**:

- uma engine genérica
- um substituto de Unity ou Godot
- um console comercial real

PROMETEU **é**:

- um laboratório
- um instrumento didático
- um brinquedo sério

---

## 🧠 Modelo Mental Fundamental

> PROMETEU é um microcontrolador que desenha pixels, toca som e lida com inputs do jogador.
>

Tudo no sistema deriva disso.

### Equivalência conceitual

| Microcontrolador real | PROMETEU |
| --- | --- |
| Clock | Tick da VM |
| Flash | Cartucho PROMETEU |
| RAM | Heap + Stack |
| GPIO | Input |
| DMA | Transferência gráfica |
| ISR | Eventos do sistema |
| Periféricos | GFX, AUDIO, INPUT, FS |

Se você entende um MCU, você entende PROMETEU.

---

## 🧩 Filosofia de Design

### 1. Simplicidade visível

- Cada operação tem custo
- Cada frame tem orçamento
- Cada erro tem causa observável

Nada acontece “porque sim”.

### 2. Determinismo

- Mesmo cartucho
- Mesma entrada
- Mesmo resultado

Independente da plataforma.

### 3. Limitação como ferramenta pedagógica

PROMETEU impõe limites **intencionais**:

- memória finita
- tempo por frame
- recursos gráficos limitados

Limites ensinam design.

### 4. Profundidade progressiva

PROMETEU pode ser explorado em camadas:

1. **Camada Jogo** — `update()` e `draw()`
2. **Camada Sistema** — bytecode, stack, heap
3. **Camada Máquina** — ciclos, eventos, periféricos

O aluno decide até onde descer.

## 🏗️ Arquitetura Geral

```
+---------------------------+
|        CARTUCHO           |
|  (bytecodeX + assets)     |
+-------------+-------------+
              |
+-------------v-------------+
|        PROMETEU VM        |
|   (stack-based,           |
|    determinística)        |
+-------------+-------------+
              |
+-------------v-------------+
|   PERIFÉRICOS VIRTUAIS    |
|  GFX | AUDIO |INPUT | FS| | 
+-------------+-------------+
              |
+-------------v-------------+
|   CAMADA DE PLATAFORMA    |
| PC | SteamOS | Android    |
| iOS | Consoles (futuro)   |
+---------------------------+
```

Este manual descreve **a máquina PROMETEU**, não ferramentas externas.

---

## 📦 O Cartucho PROMETEU

Um **cartucho PROMETEU** é um pacote imutável, equivalente a firmware.

Conteúdo típico:

- `program.pbx` — bytecode PROMETEU (bytecodeX)
- `assets/` — gráficos, áudio, mapas
- `manifest.json` — metadados e configuração

O cartucho:

- sempre pode ser executado
- sempre pode ser distribuído
- nunca é bloqueado pelo sistema

---

## 🧪 Linguagens de Programação

PROMETEU **não executa linguagens de alto nível diretamente**.

As linguagens são **fontes**, compiladas para bytecode PROMETEU.

### Linguagens planejadas

- **Java (subset)** — arquitetura, ensino profundo
- **TypeScript (subset)** — acessibilidade e mercado
- **Lua (subset)** — scripting clássico e leve

Todas convergem para:

> O mesmo bytecode. A mesma VM. O mesmo comportamento.
>

---

## 🔄 Modelo de Execução

PROMETEU executa em um loop fixo:

```
BOOT
↓
LOAD CARTUCHO
↓
INIT
↓
LOOP (60 Hz):
  ├─INPUT
  ├─UPDATE
  ├─ DRAW
  ├─ AUDIO
  └─ SYNC

```

- Frequência padrão: **60 Hz**
- Cada iteração corresponde a **um frame**
- O tempo de execução é **mensurável**

---

## ⏱️ CAP — Execution Cap (Orçamento de Execução)

### Definição

O **CAP** define um orçamento de execução (tempo, memória e recursos) **em um contexto específico**, como uma Game Jam ou avaliação.

> CAP nunca bloqueia execução.
CAP nunca bloqueia empacotamento.
CAP nunca impede o jogo de ser jogado.
>

---

### Quando o CAP é usado

- Game Jams PROMETEU
- Avaliações acadêmicas
- Desafios técnicos
- Comparações entre soluções

Fora desses contextos, PROMETEU opera em **modo livre**.

---

### O papel do CAP

O CAP serve para:

- orientar decisões técnicas
- fornecer feedback mensurável
- gerar **certificações técnicas**
- criar critérios objetivos de avaliação

PROMETEU **ajuda durante o desenvolvimento**:

- indicadores visuais
- alertas de custo
- profiling por frame

---

## 📄 Certificação PROMETEU

### O que é

A **Certificação PROMETEU** é um relatório técnico gerado a partir da execução do jogo sob um CAP definido.

Ela:

- **não impede** o jogo
- **não invalida** a entrega
- **registra evidências técnicas**

---

### Exemplo de relatório

```
PROMETEUCERTIFICATIONREPORT
-----------------------------
Context:PROMETEUJAM#03
Target Profile:PROMETEU-LITE

Execution:
Avg cycles/frame:4,820
Peak cycles/frame:5,612❌

Memory:
Heap peak:34KB❌(limit:32KB)

Status:
❌NOTCOMPLIANT

Notes:
-OverruncausedbyenemyAIupdateloop
-Heappressurecausedbyper-frameallocations
```

O relatório **acompanha o jogo**.

---

## 🎓 Uso Educacional

A avaliação pode considerar:

- Qualidade do jogo (criatividade, design)
- Qualidade técnica (certificação)
- Decisões arquiteturais justificadas
- Evolução entre versões

PROMETEU avalia **processo**, não apenas resultado.

< [Sumário](topics/table-of-contents.md) >