prometeu-runtime/docs/specs

📜 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 >