# 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`](docs/vm-arch/ARCHITECTURE.md) is normative for VM/runtime invariants.
- [`docs/runtime/specs/README.md`](docs/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/](./crates)**: Software implementation in Rust.
  - **[prometeu](crates/tools/prometeu)**: Unified command-line interface (CLI).
  - **[prometeu-drivers](crates/console/prometeu-drivers)**: The virtual hardware (GPU, SPU, Input).
  - **[prometeu-host-desktop-winit](crates/host/prometeu-host-desktop-winit)**: Host for execution on Desktop systems.
- **[docs/](./docs)**: Technical documentation and system specifications.
- **[devtools-protocol/](devtools)**: Definition of the communication protocol for development tools.
- **[test-cartridges/](./test-cartridges)**: Cartridge examples and test suites.

---

## 🛠️ Requirements

- **Rust**: Version defined in `rust-toolchain.toml`.
- **Installation**: Use [rustup](https://rustup.rs/) to install the required toolchain.

---

## ▶️ Quick Start

To compile the full project:

```bash
cargo build
```

To run an example cartridge:

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

For more details on how to use the CLI, see the **[prometeu](crates/tools/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](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.