PROMETEU

PROMETEU is an educational and experimental fantasy handheld / fantasy console ecosystem inspired by classic consoles, focusing on teaching programming, system architecture, and hardware concepts through software.

PROMETEU is a fantasy console with a simple, explicit, and educational VM/runtime inside it.

---

🎯 Project Goals

• Simulate simple "logical hardware": Create a low entry barrier for understanding how computers work.
• Deterministic Loop: Ensure the same code produces the same result on any platform.
• Total Portability: The core does not depend on an operating system, allowing it to run from modern computers to dedicated hardware.
• First-Class Tools: Offer deep debugging and inspection as a central part of the experience.
• DIY hardware affinity: Keep the machine model close enough to handheld/console-era hardware that it can inform real embedded and homebrew-style implementations.

---

🧠 Design Philosophy

• No magic: everything is explicit.
• No implicit heuristics: the system doesn't "guess intentions".
• Deterministic: same input → same result.
• Hardware-first: APIs model peripherals, not modern frameworks.
• Portable by definition: if it doesn't work on all platforms, it doesn't exist.
• Console-era sensibility: PROMETEU carries intentional influence from NES, SNES, Mega Drive, Game Boy, GBA, CPS-2, and adjacent DIY-friendly hardware thinking.

🧭 Canonical Architecture

PROMETEU is the machine. The VM/runtime is one subsystem inside that machine.

Authoritative documents:

• docs/runtime/virtual-machine/ARCHITECTURE.md is normative for VM/runtime invariants.
• docs/runtime/specs/README.md describes the broader PROMETEU machine, hardware model, and fantasy console context.
• Supporting material under docs/ may expand, explain, or propose changes, but it must not silently collapse the whole machine into the VM layer.

---

📦 Monorepo Structure

This repository is organized as a Rust workspace and contains several components:

• crates/: Software implementation in Rust.
  • prometeu: Unified command-line interface (CLI).
  • prometeu-drivers: The virtual hardware (GPU, SPU, Input).
  • prometeu-host-desktop-winit: Host for execution on Desktop systems.
• docs/: Technical documentation and system specifications.
• devtools-protocol/: Definition of the communication protocol for development tools.
• test-cartridges/: Cartridge examples and test suites.

---

🛠️ Requirements

• Rust: Version defined in rust-toolchain.toml.
• Installation: Use rustup to install the required toolchain.

---

▶️ Quick Start

To compile the full project:

cargo build

To run an example cartridge:

./target/debug/prometeu run test-cartridges/color-square-ts

For more details on how to use the CLI, see the prometeu README.

---

🚧 Project Status

⚠️ Early stage (bootstrap)

Currently, the focus is on stabilizing the core architecture and debugging protocol. Nothing here should be considered a stable API yet.

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

✨ Final Note

PROMETEU is both a technical and pedagogical project. The idea is not to hide complexity, but to expose the right complexity, at the right level, so it can be understood, studied, and explored.