prometeu-runtime/docs/specs

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