# 📜 Prometeu — The Fire and the Promise

**PROMETEU** is an imaginary console.

But not in the weak sense of "imagining".

PROMETEU was **deliberately designed** to exist as a **complete computational model**: simple enough to be understood, and powerful enough to create real games.

The name PROMETEU carries two intentional meanings:

- **Prometheus, the titan**, who stole fire from the gods and gave it to humans
- **“Prometeu” as a verb**, a promise made (in Portuguese)

In this project:

- the *fire* is the knowledge of how computers really work
- the *promise* is that nothing is magic, nothing is hidden, and everything can be understood

This manual is that written promise.

---

## 🎯 What is PROMETEU

PROMETEU is a **Virtual Microconsole** — a fictitious computer, with clear rules, limited resources, and deterministic behavior.

It was designed to:

- teach real computing fundamentals
- expose time, memory, and execution
- allow full 2D games (platformers, metroidvanias, arcade)
- serve as a bridge between:
    - microcontrollers
    - classic consoles
    - virtual machines
    - modern engines

PROMETEU **is not**:

- a generic engine
- a substitute for Unity or Godot
- a real commercial console

PROMETEU **is**:

- a laboratory
- a didactic instrument
- a serious toy

---

## 🧠 Fundamental Mental Model

> PROMETEU is a microcontroller that draws pixels, plays sound, and handles player input.
>

Everything in the system derives from this.

### Conceptual equivalence

| Real microcontroller | PROMETEU |
| --- | --- |
| Clock | VM Tick |
| Flash | PROMETEU Cartridge |
| RAM | Heap + Stack |
| GPIO | Input |
| DMA | Graphics transfer |
| ISR | System events |
| Peripherals | GFX, AUDIO, INPUT, FS |

If you understand an MCU, you understand PROMETEU.

---

## 🧩 Design Philosophy

### 1. Visible Simplicity

- Every operation has a cost
- Every frame has a budget
- Every error has an observable cause

Nothing happens "just because".

### 2. Determinism

- Same cartridge
- Same input
- Same result

Regardless of the platform.

### 3. Limitation as a pedagogical tool

PROMETEU imposes **intentional** limits:

- finite memory
- time per frame
- limited graphics resources

Limits teach design.

### 4. Progressive depth

PROMETEU can be explored in layers:

1. **Game Layer** — `update()` and `draw()`
2. **System Layer** — bytecode, stack, heap
3. **Machine Layer** — cycles, events, peripherals

The student decides how deep to go.

## 🏗️ General Architecture

```
+---------------------------+
|        CARTRIDGE          |
|  (bytecodeX + assets)     |
+-------------+-------------+
              |
+-------------v-------------+
|        PROMETEU VM        |
|   (stack-based,           |
|    deterministic)         |
+-------------+-------------+
              |
+-------------v-------------+
|    VIRTUAL PERIPHERALS    |
|  GFX | AUDIO |INPUT | FS| | 
+-------------+-------------+
              |
+-------------v-------------+
|      PLATFORM LAYER       |
| PC | SteamOS | Android    |
| iOS | Consoles (future)   |
+---------------------------+
```

This manual describes **the PROMETEU machine**, not external tools.

---

## 📦 The PROMETEU Cartridge

A **PROMETEU cartridge** is an immutable package, equivalent to firmware.

Typical content:

- `program.pbx` — PROMETEU bytecode (bytecodeX)
- `assets/` — graphics, audio, maps
- `manifest.json` — metadata and configuration

The cartridge:

- can always be executed
- can always be distributed
- is never blocked by the system

---

## 🧪 Programming Languages

PROMETEU **does not execute high-level languages directly**.

The languages are **sources**, compiled to PROMETEU bytecode.

### Planned languages

- **Java (subset)** — architecture, deep teaching
- **TypeScript (subset)** — accessibility and market
- **Lua (subset)** — classic and lightweight scripting

All converge to:

> The same bytecode. The same VM. The same behavior.
>

---

## 🔄 Execution Model

PROMETEU executes in a fixed loop:

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

```

- Default frequency: **60 Hz**
- Each iteration corresponds to **one frame**
- Execution time is **measurable**

---

## ⏱️ CAP — Execution Cap

### Definition

The **CAP** defines an execution budget (time, memory, and resources) **in a specific context**, such as a Game Jam or evaluation.

> CAP never blocks execution.
> CAP never blocks packaging.
> CAP never prevents the game from being played.
>

---

### When the CAP is used

- PROMETEU Game Jams
- Academic evaluations
- Technical challenges
- Comparisons between solutions

Outside of these contexts, PROMETEU operates in **free mode**.

---

### The role of the CAP

The CAP serves to:

- guide technical decisions
- provide measurable feedback
- generate **technical certifications**
- create objective evaluation criteria

PROMETEU **helps during development**:

- visual indicators
- cost alerts
- per-frame profiling

---

## 📄 PROMETEU Certification

### What it is

The **PROMETEU Certification** is a technical report generated from the execution of the game under a defined CAP.

It:

- **does not prevent** the game from running
- **does not invalidate** the delivery
- **records technical evidence**

---

### Report Example

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

The report **accompanies the game**.

---

## 🎓 Educational Use

Evaluation may consider:

- Game quality (creativity, design)
- Technical quality (certification)
- Justified architectural decisions
- Evolution between versions

PROMETEU evaluates **process**, not just result.

< [Summary](topics/table-of-contents.md) >