299 lines
5.9 KiB
Markdown
299 lines
5.9 KiB
Markdown
# 📜 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) > |