96 lines
3.7 KiB
Markdown
96 lines
3.7 KiB
Markdown
# 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/runtime/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.
|