adjustments on docs

This commit is contained in:
2026-03-24 13:40:47 +00:00
parent f77b9f762f
commit 1b0e290e1d
42 changed files with 72 additions and 1655 deletions
+299
View File
@@ -0,0 +1,299 @@
# 📜 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) >
+254
View File
@@ -0,0 +1,254 @@
< [Summary](table-of-contents.md) | [Next](chapter-2.md) >
# ⏱️ **Time Model and Cycles**
# 1. Overview
PROMETEU is a **time-oriented** system.
Nothing happens "instantly".
Every action consumes **measurable time**, expressed in **execution cycles**.
This chapter defines:
- the system's **base clock**
- the concept of a **PROMETEU cycle**
- how time is distributed across frames
- how the **CAP (Execution Cap)** relates to this model
---
## 2. System Base Clock
PROMETEU operates with a **fixed clock of 60 Hz**.
This means:
- 60 iterations of the main loop per second
- each iteration corresponds to **one frame**
- the clock is **deterministic and stable**, regardless of the platform
> The clock defines the machine's rhythm,
not the amount of mandatory work per frame.
>
---
## 3. The PROMETEU Frame
A **PROMETEU frame** represents a complete unit of execution.
Each frame conceptually executes the following stages:
```
FRAME N
──────────────
INPUT
UPDATE
DRAW
AUDIO
SYNC
──────────────
```
The system guarantees:
- fixed order
- predictable repetition
- absence of "ghost" frames
---
## 4. PROMETEU Cycles
### 4.1 Definition
A **PROMETEU cycle** is the smallest abstract unit of time in the system.
- each VM instruction consumes a fixed number of cycles
- peripheral calls also have a cost
- the cost is **documented and stable**
Cycles are:
- **countable**
- **comparable**
- **independent of real hardware**
---
### 4.2 Why cycles, and not milliseconds?
PROMETEU does not measure time in milliseconds because:
- milliseconds vary between platforms
- real clocks differ
- jitter and latency hide the real cost
Cycles allow stating:
> "This program is more expensive than that one,
>
>
> regardless of where it runs."
>
---
## 5. Per-Frame Budget
Each frame has a **maximum cycle budget**.
This budget:
- is reset every frame
- does not accumulate unused cycles
- represents the capacity of the "virtual CPU"
### Conceptual example
```
Frame Budget:10,000cycles
Used:
-Update logic:4,200
-Draw calls:3,100
-Audio:900
Remaining:
1,800cycles
```
---
## 6. Separation between Clock and Work
PROMETEU **does not require** all logic to run every frame.
The programmer is **explicitly encouraged** to distribute work over time.
### Common examples
- enemy logic every 2 frames (30 Hz)
- pathfinding every 4 frames (15 Hz)
- animations independent of AI
- timers based on frame count
This reflects real-world practices from:
- classic consoles
- embedded systems
- microcontroller firmware
> Not everything needs to happen now.
>
---
## 7. Temporal Distribution as Architecture
PROMETEU treats **work distribution over time** as an architectural decision.
This means that:
- code that runs every frame is more expensive
- distributed code is more efficient
- optimization is, first and foremost, **temporal organization**
PROMETEU teaches:
> performance doesn't just come from "less code",
>
>
> but from **when** the code runs.
>
---
## 8. Execution CAP (Contextual Budget)
### 8.1 What is the CAP
The **CAP** defines a set of technical limits associated with a **specific context**, such as:
- Game Jams
- academic evaluations
- technical challenges
The CAP can define:
- maximum cycle budget per frame
- memory limit
- peripheral call limits
---
### 8.2 CAP does not block execution
Fundamental rules:
- the game **always runs**
- the game **can always be packaged**
- the game **can always be played**
The CAP **never prevents** execution.
---
### 8.3 CAP generates evidence, not punishment
When a CAP is active, PROMETEU:
- measures execution
- records peaks
- identifies bottlenecks
- generates a **certification report**
This report:
- does not block the game
- does not invalidate the delivery
- **documents compliance or non-compliance**
---
## 9. Time-Based Certification
PROMETEU certification analyzes:
- average cycle usage per frame
- maximum peaks
- problematic frames
- cost distribution
Example:
```
Target CAP:PROMETEU-LITE
Frame Budget:5,000cycles
Frame 18231:
Used:5,612cycles❌
Primary cause:
enemy.updateAI():1,012cycles
```
This certification accompanies the game as a **technical artifact**.
---
## 10. Pedagogical Implications
The time and cycles model allows teaching:
- execution planning
- time-oriented architecture
- technical trade-offs
- reading real profiles
< [Summary](table-of-contents.md) | [Next](chapter-2.md) >
+350
View File
@@ -0,0 +1,350 @@
< [Back](chapter-9.md) | [Summary](table-of-contents.md) | [Next](chapter-11.md) >
# 🛠️ **Debug, Inspection, and Profiling**
## 1. Overview
PROMETEU was designed to **be observed**.
Debug, inspection, and profiling **are not optional external tools** —
they are **integral parts of the machine**.
Nothing happens without leaving traces.
Nothing consumes resources without being measured.
Nothing fails without explanation.
> PROMETEU does not hide state.
> PROMETEU exposes behavior.
>
---
## 2. Debug Philosophy in PROMETEU
PROMETEU follows three fundamental debug principles:
1. **State before abstraction**
The programmer sees the machine before seeing “features”.
2. **Time as first class**
Every action is analyzed in the context of the frame and cycles.
3. **Observation does not alter execution**
Debug never changes the behavior of the system.
---
## 3. Execution Modes
PROMETEU operates in three main modes:
### 3.1 Normal Mode
- continuous execution
- no detailed inspection
- focus on game and experience
---
### 3.2 Debug Mode
- controlled execution
- access to internal state
- pauses and stepping
This mode is used for:
- learning
- investigation
- error correction
---
### 3.3 Certification Mode
- deterministic execution
- collected metrics
- report generation
No mode alters the logical result of the program.
---
## 4. Execution Debug
### 4.1 Pause and Resume
The system can be paused at safe points:
- frame start
- before UPDATE
- after DRAW
- before SYNC
During pause:
- state is frozen
- buffers are not swapped
- logical time does not advance
---
### 4.2 Step-by-Step
PROMETEU allows stepping at different levels:
- **by frame**
- **by function**
- **by VM instruction**
Stepping by instruction reveals:
- Program Counter (PC)
- current instruction
- operand stack
- call stack
---
## 5. State Inspection
### 5.1 Stacks
PROMETEU allows inspecting:
- **Operand Stack**
- **Call Stack**
For each frame:
- content
- depth
- growth and cleanup
Stack overflow and underflow are immediately visible.
---
### 5.2 Heap
The heap can be inspected in real time:
- total size
- current usage
- peak usage
- live objects
The programmer can observe:
- allocation patterns
- fragmentation
- GC pressure
---
### 5.3 Global Space
Global variables:
- current values
- references
- initialization
Globals are visible as **static RAM**.
---
## 6. Graphics Debug
PROMETEU allows inspecting the graphics system:
- front buffer
- back buffer
- palette state
- active sprites
It is possible to:
- freeze the image
- observe buffers separately
- identify excessive redraw
---
## 7. Time Profiling (Cycles)
### 7.1 Per-Frame Measurement
For each frame, PROMETEU records:
- total cycles used
- cycles per subsystem
- execution peaks
Conceptual example:
```
Frame 18231:
Total:9,842/10,000cycles
UPDATE:4,210
DRAW:3,180
AUDIO:920
SYSTEM:612
```
---
### 7.2 Per-Function Profiling
PROMETEU can associate cycles with:
- functions
- methods
- logical blocks
This allows answering:
> “where is the time being spent?”
>
---
### 7.3 Per-Instruction Profiling
At the lowest level, the system can display:
- executed instructions
- individual cost
- frequency
This level is especially useful for:
- VM teaching
- deep optimization
- bytecode analysis
---
## 8. Memory Profiling
PROMETEU records:
- average heap usage
- heap peak
- allocations per frame
- GC frequency
Example:
```
Heap:
Avg:24KB
Peak:34KB❌
Limit:32KB
```
These data directly feed the certification.
---
## 9. Breakpoints and Watchpoints
### 9.1 Breakpoints
PROMETEU supports breakpoints in:
- specific frames
- functions
- VM instructions
Breakpoints:
- pause execution
- preserve state
- do not change behavior
---
### 9.2 Watchpoints
Watchpoints monitor:
- variables
- heap addresses
- specific values
Execution can pause when:
- a value changes
- a limit is exceeded
---
## 10. Event and Interrupt Debugging
PROMETEU allows observing:
- event queue
- active timers
- occurred interrupts
Each event has:
- origin
- frame
- cost
- consequence
Nothing happens “silently”.
---
## 11. Integration with CAP and Certification
All debug and profiling data:
- feed the certification report
- are collected deterministically
- do not depend on external tools
The final report is:
- reproducible
- auditable
- explainable
---
## 12. Pedagogical Use
This system allows teaching:
- how to debug real systems
- how to read metrics
- how to correlate time and memory
- how to justify technical decisions
The student learns:
> debug is not trial and error,
> it is informed observation.
>
---
## 13. Summary
- debug is part of the system
- inspection is complete
- profiling is deterministic
- time and memory are visible
- certification is evidence-based
< [Back](chapter-9.md) | [Summary](table-of-contents.md) | [Next](chapter-11.md) >
+258
View File
@@ -0,0 +1,258 @@
< [Back](chapter-10.md) | [Summary](table-of-contents.md) | [Next](chapter-12.md) >
# 🌍 **Portability Guarantees and Cross-Platform Execution**
## 1. Overview
PROMETEU was designed from the beginning to be **portable by construction**, not by later adaptation.
A PROMETEU cartridge:
- executes the same way on any supported platform
- produces the same results for the same inputs
- maintains predictable technical behavior
> PROMETEU does not depend on the platform.
> The platform depends on PROMETEU.
>
This chapter defines the system's **portability contract**.
---
## 2. Fundamental Principle of Portability
Portability in PROMETEU is based on a simple rule:
> Only the PROMETEU VM defines the program's behavior.
>
This means:
- source languages do not matter after compilation
- real hardware does not influence logic
- the operating system does not change semantics
Everything that does not belong to the VM is **adaptation**, not execution.
---
## 3. Separation of Responsibilities
PROMETEU strictly separates three layers:
```
+----------------------------+
| CARTRIDGE |
| (bytecode + assets) |
+-------------+--------------+
|
+-------------v--------------+
| PROMETEU VM |
| (logic, time, memory) |
+-------------+--------------+
|
+-------------v--------------+
| PLATFORM LAYER |
| window, audio, input, FS |
+----------------------------+
```
### What the VM controls
- bytecode execution
- logical time (frames, cycles)
- memory (stack, heap)
- determinism
- costs and metrics
### What the platform provides
- pixel display
- audio output
- physical input collection
- access to the sandbox file system
The platform **never decides behavior**.
---
## 4. Determinism as the Basis of Portability
PROMETEU guarantees determinism through:
- fixed logical clock (60 Hz)
- abstract cycles, not real time
- input sampled per frame
- absence of implicit concurrency
- absence of system-dependent operations
This allows stating:
> “If the cartridge is the same, the game is the same.”
>
---
## 5. Independence from Real Hardware
PROMETEU **does not use**:
- operating system timers
- high-resolution clocks
- CPU-specific instructions
- uncontrolled graphics acceleration
All performance is measured in **PROMETEU cycles**, not in milliseconds.
The real hardware:
- only executes the VM
- never interferes with semantics
---
## 6. Floating Point Precision
To guarantee numerical consistency:
- PROMETEU defines explicit mathematical operations
- avoids dependence on specific FPUs
- standardizes `number` behavior
This avoids:
- divergences between architectures
- unpredictable cumulative errors
- subtle differences between platforms
---
## 7. Cross-Platform Input
PROMETEU abstracts physical input into **logical state**.
- keyboard, gamepad, and touch are mapped externally
- the cartridge only sees logical buttons and axes
- the reading moment is fixed per frame
The same cartridge:
- reacts the same way on PC, mobile, or console
- does not contain device-dependent logic
---
## 8. Cross-Platform Audio
The audio system:
- defines channels and mixing logically
- uses native APIs only as output
- maintains per-frame synchronization
Hardware differences:
- do not change logical timing
- do not change sound sequence
- do not affect certification
---
## 9. Cross-Platform Graphics
The graphics system:
- operates on a logical framebuffer
- uses an indexed palette
- does not depend on a specific GPU
The platform layer:
- only displays the framebuffer
- does not reinterpret graphics commands
PROMETEU **does not delegate graphics decisions to the hardware**.
---
## 10. File System and Persistence
PROMETEU defines a **sandbox logical filesystem**:
- virtual paths
- size limits
- deterministic behavior
The platform maps this filesystem to:
- disk
- mobile storage
- persistent memory
Without changing semantics.
---
## 11. Certification and Portability
The **PROMETEU Certification** is valid for all platforms.
If a cartridge:
- passes on one platform
- with the same inputs
It:
- will pass on all
- will produce the same reports
This is possible because:
> the certification validates the VM, not the environment.
>
---
## 12. What PROMETEU DOES NOT guarantee
PROMETEU **does not promise**:
- identical absolute performance (real FPS)
- identical physical latency
- equivalent energy consumption
PROMETEU promises:
- **identical logical behavior**
- **reproducible technical decisions**
---
## 13. Pedagogical Implications
This model allows teaching:
- the difference between logic and presentation
- why modern engines break determinism
- how to isolate systems
- how to design portable software
The student learns:
> portability is not luck — it is architecture.
>
---
## 14. Summary
- PROMETEU defines behavior in the VM
- platforms only execute
- time is logical, not physical
- input, audio, and graphics are abstracted
- certification is universal
- portability is guaranteed by design
< [Back](chapter-10.md) | [Summary](table-of-contents.md) | [Next](chapter-12.md) >
+236
View File
@@ -0,0 +1,236 @@
< [Back](chapter-11.md) | [Summary](table-of-contents.md) | [Next](chapter-13.md) >
# 🧠 Firmware — PrometeuOS (POS) + PrometeuHub
## 1. Overview
The **PROMETEU Firmware** is composed of two layers:
- **PrometeuOS (POS)**: the system firmware/base. It is the maximum authority for boot, peripherals, PVM execution, and fault handling.
- **PrometeuHub**: the system launcher and UI environment, embedded in the firmware, executed **over** the POS and using the **PROMETEU Window System**.
> **Every cartridge is an App**.
> The difference is the **App mode** (Game or System), specified in the cartridge header.
---
## 2. Terms and Definitions
- **Host**: real platform (desktop, mobile, DIY console, etc.) that calls the core at 60Hz and displays the framebuffer.
- **POS (PrometeuOS)**: firmware (system core). Controls boot, PVM, budget, input latch, peripherals, and crash.
- **PrometeuHub**: system UI / launcher running over POS.
- **PVM (PROMETEU Virtual Machine)**: VM that executes the App's bytecode.
- **App / Cartridge**: PROMETEU executable package (e.g., `.pbc`).
- **AppMode**: App mode in the cartridge header:
- `GAME`: assumes full screen, own UI
- `SYSTEM`: app integrated into the system, should run "in a window" in the Hub
- **Logical frame**: App update unit, terminated by `FRAME_SYNC`.
- **Host tick**: call from the host (real 60Hz).
---
## 3. Responsibilities of the POS (PrometeuOS)
The POS must guarantee:
### 3.1 Boot and System States
- Deterministic RESET (known state)
- Optional SPLASH (short)
- initialization of the PrometeuHub and the Window System
- return to the Hub after app exit/crash
### 3.2 PVM Control
- load cartridge into the PVM
- reset PC/stack/heap upon app start
- execute budget per logical frame
- respect `FRAME_SYNC` as logical frame boundary
- maintain input latched per logical frame
### 3.3 Peripheral Control
- initialization and reset of:
- GFX / buffers
- AUDIO (channels, command queue)
- INPUT / TOUCH
- "safe mode" policy (ignore Hub/config if requested)
### 3.4 Failures and Recovery
- capture fatal PVM faults
- present **POS_CRASH_SCREEN** (outside the PVM)
- allow:
- app restart
- return to Hub
- system reset
---
## 4. Responsibilities of the PrometeuHub
The PrometeuHub must:
- list available Apps in storage
- read metadata from the cartridge header (including `AppMode`)
- allow selection and launch
- apply system theme/UI via Window System
- decide the "execution behavior" based on the `AppMode`
### 4.1 Decision by `AppMode`
When selecting an App:
- If `AppMode = GAME`:
- the Hub delegates to the POS: **execute as a game** (full screen)
- If `AppMode = SYSTEM`:
- the Hub delegates to the POS: **load the App**
- and the Hub **opens a window** and runs the App "integrated into the system"
> Note: the Hub does not execute bytecode directly; it always delegates to the POS.
---
## 5. PROMETEU Window System (System UI)
The Window System is part of the firmware (POS + Hub) and offers:
- global theme (palette, fonts, UI sounds)
- window system (at least: one active window + dialog stack)
- input routing:
- focus, navigation, confirmation/cancellation
- touch as "tap" (single pointer)
### 5.1 System App Integration
System Apps are executed in "window" mode and must:
- respect the viewport area provided by the window
- cooperate with the Window System's focus/inputs
- accept being suspended/closed by the Hub
The Hub can offer window "chrome":
- title
- back/close button
- overlays (toast, dialogs)
---
## 6. Cartridge Header (minimum requirement for the firmware)
The firmware requires every cartridge to provide at least the following in the header:
- `magic` / `version`
- `app_id` (short string or hash)
- `title` (string)
- `entrypoint` (PC address)
- `app_mode`: `GAME` or `SYSTEM`
- (optional) `icon_id` / `cover_id`
- (optional) `requested_cap` / VM version
The POS/HUB must use `app_mode` to decide on execution.
---
## 7. Official Boot States (Firmware)
### 7.1 POS_RESET
- initializes peripherals
- prepares PVM
- loads config
- detects safe mode
Transition: `POS_SPLASH` or `POS_LAUNCH_HUB`
### 7.2 POS_SPLASH (optional)
- displays logo/version
- fixed time or "skip"
Transition: `POS_LAUNCH_HUB`
### 7.3 POS_LAUNCH_HUB
- starts Window System
- enters the Hub loop
Transition: `HUB_HOME`
### 7.4 HUB_HOME
- lists Apps
- allows selection:
- `GAME` → `POS_RUN_GAME(app)`
- `SYSTEM` → `HUB_OPEN_WINDOW(app)` (which delegates `POS_RUN_SYSTEM(app)`)
### 7.5 POS_RUN_GAME(app)
- loads cartridge into the PVM
- executes logical frame (budget + `FRAME_SYNC`)
- presents frames
- maintains latch per logical frame
Exits:
- `APP_EXIT` → `POS_LAUNCH_HUB`
- `APP_FAULT` → `POS_CRASH_SCREEN`
### 7.6 POS_RUN_SYSTEM(app)
- loads cartridge into the PVM (or separate instance, if supported in the future)
- executes under the Hub/Window System cycle
- presents in the window area (viewport)
Exits:
- `APP_EXIT` → returns to the Hub
- `APP_FAULT` → `POS_CRASH_SCREEN` (or crash window + fallback)
### 7.7 POS_CRASH_SCREEN
- displays error (type, PC, stack trace)
- actions: restart app / hub / reset
Transition: as chosen.
---
## 8. Execution Model (Budget, Latch, and `FRAME_SYNC`)
The POS is responsible for guaranteeing:
- **Input latched per logical frame**
- execution in slices (host ticks) until the app reaches `FRAME_SYNC`
- only at `FRAME_SYNC`:
- `present()` (or compose+present)
- advances `logical_frame_index`
- releases input latch
- resets the budget for the next logical frame
If the budget runs out before `FRAME_SYNC`:
- does not present
- maintains latch
- execution continues in the next host tick within the same logical frame
---
## 9. Rules for Returning to the Hub
The firmware must offer a "return to system" mechanism:
- button shortcut (e.g., START+SELECT for X ticks)
- or controlled syscall (System Apps only)
Upon returning to the Hub:
- the POS terminates or suspends the current App
- returns to the Window System with a consistent state
---
## 10. Pedagogical Objectives
This firmware allows teaching:
- boot stages and firmware as an authority
- separation between system and application
- deterministic execution with budget and logical frame
- difference between apps (Game vs System)
- fault tolerance and realistic crash handling
---
## 11. Summary
- POS is the base layer and controls the PVM, budget, latch, peripherals, and crash.
- PrometeuHub is the embedded firmware launcher/UI over the POS.
- Every cartridge is an App; the header defines the `app_mode` (GAME/SYSTEM).
- `GAME` runs in full screen; `SYSTEM` runs integrated into the Hub in a window.
- `FRAME_SYNC` is the logical frame boundary.
< [Back](chapter-11.md) | [Summary](table-of-contents.md) | [Next](chapter-13.md) >
+110
View File
@@ -0,0 +1,110 @@
< [Back](chapter-12.md) | [Summary](table-of-contents.md) | [Next](chapter-14.md) >
# Cartridges
**Version:** 1.0 (stable baseline)
**Status:** Proposal
---
## 1. Objective
Define a minimum and stable contract for Prometeu cartridges, allowing:
* App identification
* Mode selection (Game/System)
* Entrypoint resolution
* Predictable loading by the runtime
---
## 2. Concept
A cartridge is the distributable unit of Prometeu. It can exist as:
* **Directory (dev)** — ideal for development and hot-reload
* **Packaged file (.pmc)** — ideal for distribution
Both share the same logical layout.
---
## 3. Logical Layout
```
<cartridge>/
├── manifest.json
├── program.pbc
└── assets/
└── ...
```
Required fields:
* `manifest.json`
* `program.pbc` (Prometeu bytecode)
---
## 4. manifest.json (Contract v1)
```json
{
"magic": "PMTU",
"cartridge_version": 1,
"app_id": 1234,
"title": "My Game",
"app_version": "1.0.0",
"app_mode": "Game",
"entrypoint": "main"
}
```
### Fields
* `magic`: fixed string `PMTU`
* `cartridge_version`: format version
* `app_id`: unique numerical identifier
* `title`: name of the app
* `app_version`: app version
* `app_mode`: `Game` or `System`
* `entrypoint`: symbol or index recognized by the VM
---
## 5. Runtime Rules
* Validate `magic` and `cartridge_version`
* Read `app_mode` to decide execution flow
* Resolve `entrypoint` in `program.pbc`
* Ignore `assets/` if not supported yet
---
## 6. Usage Modes
### Directory (development)
```
prometeu --run ./mycart/
```
### Packaged file
```
prometeu --run mygame.pmc
```
Both must behave identically in the runtime.
---
## 7. Contract Stability
From v1 onwards:
* `manifest.json` is the source of truth
* Fields can only be added in a backward-compatible manner
* Incompatible changes require a new `cartridge_version`
< [Back](chapter-12.md) | [Summary](table-of-contents.md) | [Next](chapter-14.md) >
+135
View File
@@ -0,0 +1,135 @@
< [Back](chapter-13.md) | [Summary](table-of-contents.md) | [Next](chapter-15.md) >
# Boot Profiles
**Version:** 1.0
**Status:** Proposal
---
## 1. Objective
Define how Prometeu decides what to execute at startup:
* Hub
* Automatic cartridge
* Debug mode
---
## 2. BootTarget Concept
At the beginning of boot, the POS resolves a target:
```rust
enum BootTarget {
Hub,
Cartridge { path: String, debug: bool },
}
```
---
## 3. General Rules
### If BootTarget == Hub
* Firmware enters `HubHome`
* No cartridge is automatically loaded
### If BootTarget == Cartridge
1. Load cartridge
2. Read `app_mode` in the manifest
3. Apply rules:
* `Game`:
* Enter `RunningGame`
* `System`:
* Stay in `HubHome`
* Open the app as a window/system tool
---
## 4. Host CLI
### Default boot
```
prometeu
```
Result: enters the Hub
### Run cartridge
```
prometeu run <cartridge>
```
Result:
* Game → enters directly into the game
* System → opens as a tool in the Hub
### Run with debugger
```
prometeu debug <cartridge>
```
Result:
* Same flow as `run`
* Runtime starts in debug mode
* Waits for connection from the Java Debugger
---
## 5. Firmware States
Firmware maintains only:
* `Boot`
* `HubHome`
* `RunningGame`
* `AppCrashed`
System apps never change the firmware state.
---
## 6. Behavior on Real Hardware (future)
* If miniSD/physical cartridge is present at boot:
* POS can:
* always go to the Hub, or
* auto-execute according to user configuration
---
## 7. Integration with Debugger
When `debug == true`:
* Runtime:
* Initializes
* Opens DevTools socket
* Waits for `start` command
* Only after that does it start cartridge execution
---
## 8. Stability
* BootTarget is an internal POS contract
* Host CLI must respect these rules
* New boot modes must be compatible extensions
< [Back](chapter-13.md) | [Summary](table-of-contents.md) | [Next](chapter-15.md) >
+331
View File
@@ -0,0 +1,331 @@
< [Back](chapter-14.md) | [Summary](table-of-contents.md) | [Next](chapter-16.md) >
# Asset Management
## Bank-Centric Hardware Asset Model
**Scope:** Runtime / Hardware Asset Management (SDK-agnostic)
---
## 1. Fundamental Principles
1. **Every asset in Prometeu resides in a Bank**
2. **A Bank is a hardware memory management system**
3. **Assets are cold binaries stored in the cartridge**
4. **Asset memory belongs to the console, not to the VM**
5. **Loading, residency, and eviction are explicit**
6. **Hardware does not interpret gameplay semantics**
7. **The SDK orchestrates policies; hardware executes contracts**
> In Prometeu, you do not load “data”. You load **residency**.
---
## 2. Asset Origin (Cold Storage)
* All assets initially reside in **cold storage** inside the cartridge.
* Typically, each asset corresponds to a binary file.
* The runtime **never scans the cartridge directly**.
* All access goes through the **Asset Table**.
---
## 3. Asset Table
The Asset Table is an index loaded at cartridge boot.
It describes **content**, not residency.
### Location
* The Asset Table **must be embedded as JSON inside `manifest.json`**.
* Tooling may compile this JSON into a binary table for runtime use, but the source of truth is the manifest.
### Required Fields (conceptual)
* `asset_id` (integer, internal identifier)
* `asset_name` (string, user-facing identifier)
* `asset_type` (TILEBANK, SOUNDBANK, BLOB, TILEMAP, ...)
* `bank_kind` (mandatory, single)
* `offset` (byte offset in cartridge)
* `size` (cold size)
* `decoded_size` (resident size)
* `codec` (RAW, LZ4, ZSTD, ...)
* `asset_metadata` (type-specific)
> `bank_kind` defines **where** an asset may reside in hardware.
---
## 4. Bank — Definition
> **A Bank is the residency and swapping mechanism of the Prometeu hardware.**
A Bank:
* owns **numbered slots**
* enforces **resident memory budgets**
* enforces **staging / inflight budgets**
* accepts only compatible assets
* supports **atomic swap via commit**
* exposes memory and residency metrics
Banks are hardware infrastructure, not assets.
---
## 5. BankKind
Each Bank belongs to a **BankKind**, defining its pipeline and constraints.
### Example BankKinds
* `GFX_TILEBANK`
* `AUDIO_SOUNDBANK`
* `DATA_BLOBBANK`
* `MAP_TILEMAPBANK`
Each BankKind defines:
* slot count
* maximum resident memory
* inflight / staging memory budget
* decode and validation pipeline
* hardware consumer subsystem (renderer, audio mixer, etc.)
---
## 6. Slots and Slot References
* Each BankKind owns a fixed set of **slots**.
* A slot:
* references a resident asset (or is empty)
* never stores data directly
* may expose a **generation counter** (debug)
### Slot Reference
Slots are always referenced with explicit BankKind context:
* `gfxSlot(3)`
* `audioSlot(1)`
* `blobSlot(7)`
This prevents cross-bank ambiguity.
---
## 7. Bank Memory Model
* Bank memory is **console-owned memory**.
* It does not belong to the VM heap.
* It does not participate in GC.
* It can be fully released when the cartridge shuts down.
Each Bank manages:
* total memory
* used memory
* free memory
* inflight (staging) memory
Conceptually, each Bank is a **specialized allocator**.
---
## 8. Unified Loader
### Conceptual API
```text
handle = asset.load(asset_name, slotRef, flags)
```
Load flow:
1. Resolve `asset_name` via Asset Table to get its `asset_id`
2. Read `bank_kind` from asset entry
3. Validate compatibility with `slotRef`
4. Enqueue load request
5. Perform IO + decode on worker
6. Produce materialized asset in staging
### Handle States
* `PENDING` — enqueued
* `LOADING` — IO/decode in progress
* `READY` — staging completed
* `COMMITTED` — installed into slot
* `CANCELED`
* `ERROR`
---
## 9. Commit
```text
asset.commit(handle)
```
* Commit is **explicit** and **atomic**
* Executed at a safe frame boundary
* Performs **pointer swap** in the target slot
* Previous asset is released if no longer referenced
The hardware **never swaps slots automatically**.
---
## 10. Asset Deduplication
* A decoded asset exists **at most once per BankKind**.
* Multiple slots may reference the same resident asset.
* Redundant loads become **install-only** operations.
Memory duplication is forbidden by contract.
---
## 11. Bank Specializations
### 11.1 GFX_TILEBANK
* AssetType: TILEBANK
* Immutable graphical tile + palette structure
* Consumed by the graphics subsystem
### 11.2 AUDIO_SOUNDBANK
* AssetType: SOUNDBANK
* Resident audio samples or streams
* Consumed by the audio mixer
### 11.3 DATA_BLOBBANK
* AssetType: BLOB
* Read-only byte buffers
* Hardware does not interpret contents
Used by the SDK via:
* **Views** (zero-copy, read-only)
* **Decode** (materialization into VM heap)
---
## 12. Views and Decode (SDK Contract)
* **View**
* read-only
* zero-copy
* valid only while the blob remains resident
* **Decode**
* allocates VM-owned entities
* independent from the Bank after creation
Hardware is unaware of Views and Decode semantics.
---
## 13. Manifest and Initial Load
* The cartridge may include a `manifest.json`.
* The manifest may declare:
* assets to preload
* target slot references
These loads occur **before the first frame**.
---
## 14. Shutdown and Eviction
* On cartridge shutdown:
* all Banks are cleared
* all resident memory is released
No implicit persistence exists.
---
## 15. Debugger and Telemetry
Each Bank must expose:
* total memory
* used memory
* free memory
* inflight memory
* occupied slots
* `asset_id` per slot
* `asset_name` per slot
* generation per slot
This enables debuggers to visualize:
* memory stacks per Bank
* memory pressure
* streaming strategies
---
## 16. Minimal Syscall API (Derived)
The following syscalls form the minimal hardware contract for asset management:
```text
asset.load(asset_name, slotRef, flags) -> handle
asset.status(handle) -> LoadStatus
asset.commit(handle)
asset.cancel(handle)
bank.info(bank_kind) -> BankStats
bank.slot_info(slotRef) -> SlotStats
```
Where:
* `LoadStatus` ∈ { PENDING, LOADING, READY, COMMITTED, CANCELED, ERROR }
* `BankStats` exposes memory usage and limits
* `SlotStats` exposes current asset_id, asset_name and generation
---
## 17. Separation of Responsibilities
### Hardware (Prometeu)
* manages memory
* loads bytes
* decodes assets
* swaps pointers
* reports usage
### SDK
* defines packs, scenes, and policies
* interprets blobs
* creates VM entities
### VM
* executes logic
* manages its own heap
* never owns hardware assets
---
## 18. Golden Rule
> **Banks are the foundation of the hardware.**
> **Asset Types describe content.**
> **The SDK orchestrates; the hardware executes.**
< [Back](chapter-14.md) | [Summary](table-of-contents.md) | [Next](chapter-16.md) >
+384
View File
@@ -0,0 +1,384 @@
< [Back](chapter-15.md) | [Summary](table-of-contents.md) >
# **Host ABI and Syscalls**
This chapter defines the Application Binary Interface (ABI) between the Prometeu Virtual Machine (PVM) and the host environment. It specifies how syscalls are identified, resolved, invoked, verified, and accounted for.
Syscalls provide controlled access to host-managed subsystems such as graphics, audio, input, asset banks, and persistent storage.
This chapter defines the **contract**. Individual subsystems (GFX, AUDIO, MEMCARD, ASSETS, etc.) define their own syscall tables that conform to this ABI.
---
## 1 Design Principles
The syscall system follows these rules:
1. **Deterministic**: Syscalls must behave deterministically for the same inputs and frame state.
2. **Synchronous**: Syscalls execute to completion within the current VM slice.
3. **Non-blocking**: Long operations must be modeled as request + status polling.
4. **Capability-gated**: Each syscall requires a declared capability.
5. **Stack-based ABI**: Arguments and return values are passed via VM slots.
6. **Not first-class**: Syscalls are callable but cannot be stored as values.
7. **Language-agnostic identity**: Syscalls are identified by canonical names, not language syntax.
---
## 2 Canonical Syscall Identity
Syscalls are identified by a **canonical triple**:
```
(module, name, version)
```
Example:
```
("gfx", "present", 1)
("input", "state", 1)
("audio", "play", 2)
```
This identity is:
* Independent of language syntax.
* Stable across languages and toolchains.
* Used for capability checks and linking.
### Language independence
Different languages may reference the same syscall using different syntax:
| Language style | Reference form |
| -------------- | --------------- |
| Dot-based | `gfx.present` |
| Namespace | `gfx::present` |
| Object-style | `Gfx.present()` |
| Functional | `present(gfx)` |
All of these map to the same canonical identity:
```
("gfx", "present", 1)
```
The compiler is responsible for this mapping.
---
## 3 Syscall Resolution
The host maintains a **Syscall Registry**:
```
(module, name, version) -> syscall_id
```
Example:
```
("gfx", "present", 1) -> 0x0101
("gfx", "submit", 1) -> 0x0102
("audio", "play", 1) -> 0x0201
```
### Resolution process
At cartridge load time:
1. The cartridge declares required syscalls using canonical identities.
2. The cartridge bytecode encodes host-backed call sites as `HOSTCALL <sysc_index>` into that declaration table.
3. The host verifies capabilities from the cartridge manifest before execution begins.
4. The host resolves each canonical identity to a numeric `syscall_id`.
5. The loader rewrites every `HOSTCALL <sysc_index>` into `SYSCALL <id>`.
6. The VM stores the patched executable image for fast execution.
At runtime, the VM executes:
```
SYSCALL <id>
```
Only numeric IDs are used during execution.
Raw `SYSCALL <id>` is not valid in a PBX pre-load artifact and must be rejected by the loader.
---
## 4 Syscall Instruction Semantics
The VM provides two relevant instruction forms across the load pipeline:
Pre-load PBX artifact:
```
HOSTCALL <sysc_index>
```
Final executable image:
```
SYSCALL <id>
```
Where:
* `<sysc_index>` is an index into the program-declared syscall table.
* `<id>` is a 32-bit integer identifying the syscall.
Execution steps:
1. The VM looks up syscall metadata using `<id>`.
2. The VM verifies that enough arguments exist on the stack.
3. The VM checks capability requirements defensively.
4. The syscall executes in the host environment.
5. The syscall leaves exactly `ret_slots` values on the stack.
If any contract rule is violated, the VM traps.
---
## 5 Syscall Metadata Table
Each syscall is defined by a metadata entry.
### SyscallMeta structure
```
SyscallMeta {
id: u32
module: string
name: string
version: u16
arg_slots: u8
ret_slots: u8
capability: CapabilityId
may_allocate: bool
cost_hint: u32
}
```
Fields:
| Field | Description |
| -------------- | ------------------------------------------------ |
| `id` | Unique numeric syscall identifier |
| `module` | Canonical module name |
| `name` | Canonical syscall name |
| `version` | ABI version of the syscall |
| `arg_slots` | Number of input stack slots |
| `ret_slots` | Number of return stack slots |
| `capability` | Required capability |
| `may_allocate` | Whether the syscall may allocate VM heap objects |
| `cost_hint` | Expected cycle cost |
The loader uses this table to resolve canonical identities, validate declared ABI shape, and enforce capability gating. The verifier uses the final numeric metadata to validate stack effects after patching.
---
## 6 Arguments and Return Values
Syscalls use the same slot-based ABI as functions.
### Argument passing
Arguments are pushed onto the stack before the syscall.
Example:
```
push a
push b
SYSCALL X // expects 2 arguments
```
### Return values
After execution, the syscall leaves exactly `ret_slots` values on the stack.
Example:
```
// before: []
SYSCALL input_state
// after: [held, pressed, released]
```
Composite return values are represented as multiple slots (stack tuples).
---
## 7 Syscalls as Callable Entities (Not First-Class)
Syscalls behave like functions in terms of arguments and return values, but they are **not first-class values**.
This means:
* Syscalls can be invoked.
* Syscalls cannot be stored in variables.
* Syscalls cannot be passed as arguments.
* Syscalls cannot be returned from functions.
Only user-defined functions and closures are first-class.
### Conceptual declaration
```
host fn input_state() -> (int, int, int)
```
This represents a syscall with three return values, but it cannot be treated as a function value.
---
## 8 Error Model: Traps vs Status Codes
Syscalls use a hybrid error model.
### Trap conditions (contract violations)
The VM traps when:
* The syscall id is invalid.
* The canonical identity cannot be resolved.
* The required capability is missing.
* The stack does not contain enough arguments.
* A handle is invalid or dead.
These are fatal contract violations.
### Status returns (domain conditions)
Normal operational states are returned as values.
Examples:
* asset not yet loaded
* audio voice unavailable
* memcard full
These are represented by status codes in return slots.
---
## 9 Capability System
Each syscall requires a capability.
Capabilities are declared by the cartridge manifest.
Example capability groups:
* `gfx`
* `audio`
* `input`
* `asset`
* `memcard`
If a syscall is invoked without the required capability:
* The VM traps.
---
## 10 Interaction with the Garbage Collector
The VM heap is managed by the GC. Host-managed memory is separate.
### Heap vs host memory
| Memory | Managed by | GC scanned |
| --------------- | ---------- | ---------- |
| VM heap objects | VM GC | Yes |
| Asset banks | Host | No |
| Audio buffers | Host | No |
| Framebuffers | Host | No |
Assets are addressed by identifiers, not VM heap handles.
### Host root rule
If a syscall stores a handle to a VM heap object beyond the duration of the call, it must register that handle as a **host root**.
This prevents the GC from collecting objects still in use by the host.
This rule applies only to VM heap objects (such as closures or user objects), not to asset identifiers or primitive values.
---
## 11 Determinism Rules
Syscalls must obey deterministic execution rules.
Forbidden behaviors:
* reading real-time clocks
* accessing non-deterministic OS APIs
* performing blocking I/O
Allowed patterns:
* frame-based timers
* request + poll status models
* event delivery at frame boundaries
---
## 12 Cost Model and Budgeting
Each syscall contributes to frame cost.
The VM tracks:
* cycles spent in syscalls
* syscall counts
* allocation cost (if any)
Example telemetry:
```
Frame 10231:
Syscalls: 12
Cycles (syscalls): 380
Allocations via syscalls: 2
```
Nothing is free.
---
## 13 Blocking and Long Operations
Syscalls must not block.
Long operations must use a two-phase model:
1. Request
2. Status polling or event notification
Example pattern:
```
asset.load(id)
...
status, progress = asset.status(id)
```
---
## 14 Summary
* Syscalls are deterministic, synchronous, and non-blocking.
* They use the same slot-based ABI as functions.
* They are callable but not first-class.
* They are identified canonically by `(module, name, version)`.
* Language syntax does not affect the ABI.
* The host resolves canonical identities to numeric syscall IDs.
* Capabilities control access to host subsystems.
* GC only manages VM heap objects.
* Host-held heap objects must be registered as roots.
* All syscall costs are tracked per frame.
< [Back](chapter-15.md) | [Summary](table-of-contents.md) >
+427
View File
@@ -0,0 +1,427 @@
< [Back](chapter-1.md) | [Summary](table-of-contents.md) | [Next](chapter-3.md) >
# **Prometeu Virtual Machine (PVM)**
This chapter defines the execution model, value system, calling convention, memory model, and host interface of the Prometeu Virtual Machine.
The PVM is a **deterministic, stack-based VM** designed for a 2D fantasy console environment. Its primary goal is to provide predictable performance, safe memory access, and a stable execution contract suitable for real-time games running at a fixed frame rate. fileciteturn2file0
---
## 1 Core Design Principles
The PVM is designed around the following constraints:
1. **Deterministic execution**: no hidden threads or asynchronous callbacks.
2. **Frame-based timing**: execution is bounded by frame time.
3. **Safe memory model**: all heap objects are accessed through handles.
4. **Simple compilation target**: stack-based bytecode with verified control flow.
5. **Stable ABI**: multi-value returns with fixed slot semantics.
6. **First-class functions**: functions can be passed, stored, and returned.
---
## 2 Execution Model
The PVM executes bytecode in a **frame loop**. Each frame:
1. The firmware enters the VM.
2. The VM runs until:
* the frame budget is consumed, or
* a `FRAME_SYNC` instruction is reached.
3. At `FRAME_SYNC`:
* events are delivered
* input is sampled
* optional GC may run
4. Control returns to the firmware.
`FRAME_SYNC` is the **primary safepoint** in the system.
---
## 3 Value Types
All runtime values are stored in VM slots as a `Value`.
### Primitive value types (stack values)
| Type | Description |
| ------- | --------------------- |
| `int` | 64-bit signed integer |
| `bool` | Boolean value |
| `float` | 64-bit floating point |
### Built-in vector and graphics types (stack values)
These are treated as VM primitives with dedicated opcodes:
| Type | Description |
| ------- | --------------------------------- |
| `vec2` | 2D vector (x, y) |
| `color` | Packed color value |
| `pixel` | Combination of position and color |
These types:
* live entirely on the stack
* are copied by value
* never allocate on the heap
### Heap values
All user-defined objects live on the heap and are accessed via **handles**.
| Type | Description |
| -------- | -------------------------- |
| `handle` | Reference to a heap object |
| `null` | Null handle |
Handles may refer to:
* user objects
* arrays
* strings
* closures
---
## 4 Handles and Gate Table
Heap objects are accessed through **handles**. A handle is a pair:
```
handle = { index, generation }
```
The VM maintains a **gate table**:
```
GateEntry {
alive: bool
generation: u32
base: usize
slots: u32
type_id: u32
}
```
When an object is freed:
* its gate entry is marked dead
* its generation is incremented
If a handle’s generation does not match the gate entry, the VM traps.
This prevents use-after-free bugs.
---
## 5 Heap Model
* All user objects live in the heap.
* Objects are fixed-layout blocks of slots.
* No inheritance at the memory level.
* Traits/interfaces are resolved by the compiler or via vtables.
Built-in types remain stack-only.
Heap objects include:
* user structs/classes
* strings
* arrays
* closures
---
## 6 Tuples and Multi-Return ABI
The PVM supports **multi-value returns**.
### Tuple rules
* Tuples are **stack-only**.
* Maximum tuple arity is **N = 6**.
* Tuples are not heap objects by default.
* To persist a tuple, it must be explicitly boxed.
### Call convention
Each function declares a fixed `ret_slots` value.
At call time:
1. Caller prepares arguments.
2. `CALL` transfers control.
3. Callee executes.
4. `RET` leaves exactly `ret_slots` values on the stack.
The verifier ensures that:
* all control paths produce the same `ret_slots`
* stack depth is consistent.
---
## 7 Call Stack and Frames
The VM uses a **call stack**.
Each frame contains:
```
Frame {
return_pc
base_pointer
ret_slots
}
```
Execution uses only the following call instructions:
| Opcode | Description |
| ------ | ---------------------- |
| `CALL` | Calls a function by id |
| `RET` | Returns from function |
There is no separate `PUSH_FRAME` or `POP_FRAME` instruction in the public ISA.
---
## 8 Closures and First-Class Functions
Closures are heap objects and represent **function values**.
The PVM treats functions as **first-class values**. This means:
* Functions can be stored in variables.
* Functions can be passed as arguments.
* Functions can be returned from other functions.
* All function values are represented as closures.
Even functions without captures are represented as closures with an empty capture set.
### Closure layout
```
Closure {
func_id
captures[]
}
```
Captures are stored as handles or value copies.
All closure environments are part of the GC root set.
### Direct and indirect calls
The PVM supports two forms of function invocation:
| Opcode | Description |
| -------------- | -------------------------------------- |
| `CALL` | Direct call by function id |
| `CALL_CLOSURE` | Indirect call through a closure handle |
For `CALL_CLOSURE`:
1. The closure handle is read from the stack.
2. The VM extracts the `func_id` from the closure.
3. The function is invoked using the closure’s captures as its environment.
The verifier ensures that:
* The closure handle is valid.
* The target function’s arity matches the call site.
* The `ret_slots` contract is respected.
---
## 9 Coroutines (Deterministic)
The PVM supports **cooperative coroutines**.
Characteristics:
* Coroutines are scheduled deterministically.
* No preemption.
* No parallel execution.
* All scheduling happens at safepoints.
Each coroutine contains:
```
Coroutine {
call_stack
operand_stack
state
}
```
### Coroutine instructions
| Opcode | Description |
| ------- | -------------------------- |
| `SPAWN` | Creates a coroutine |
| `YIELD` | Suspends current coroutine |
| `SLEEP` | Suspends for N frames |
Scheduling is:
* round-robin
* deterministic
* bounded by frame budget
Coroutine stacks are part of the GC root set.
---
## 10 Garbage Collection
The PVM uses a **mark-sweep collector**.
### GC rules
* GC runs only at **safepoints**.
* The primary safepoint is `FRAME_SYNC`.
* GC is triggered by:
* heap thresholds, or
* allocation pressure.
### Root set
The GC marks from:
* operand stack
* call stack frames
* global variables
* coroutine stacks
* closure environments
* host-held handles
The collector:
* does not compact memory (v1)
* uses free lists for reuse
---
## 11 Event and Interrupt Model
The PVM does not allow asynchronous callbacks.
All events are:
* queued by the firmware
* delivered at `FRAME_SYNC`
This ensures:
* deterministic execution
* predictable frame timing
Coroutines are the only supported concurrency mechanism.
---
## 12 Host Interface (Syscalls)
All hardware access occurs through syscalls.
Syscalls are:
* synchronous
* deterministic
* capability-checked
They operate on the following subsystems:
### Graphics
* tilebanks
* layers
* sprites
* palette control
* fade registers
* frame present
### Audio
* voice allocation
* play/stop
* volume/pan/pitch
* steal policy
### Input
* sampled once per frame
* exposed as frame state
### Assets
Asset banks are **host-owned memory**.
The VM interacts through handles:
| Syscall | Description |
| -------------- | ---------------------------- |
| `asset.load` | Request asset load into slot |
| `asset.status` | Query load state |
| `asset.commit` | Activate loaded asset |
Asset memory:
* is not part of the VM heap
* is not scanned by GC
### Save Memory (MEMCARD)
| Syscall | Description |
| --------------- | --------------- |
| `mem.read_all` | Read save data |
| `mem.write_all` | Write save data |
| `mem.commit` | Persist save |
| `mem.size` | Query capacity |
---
## 13 Verifier Requirements
Before execution, bytecode must pass the verifier.
The verifier ensures:
1. Valid jump targets
2. Stack depth consistency
3. Correct `ret_slots` across all paths
4. Handle safety rules
5. Closure call safety
6. No invalid opcode sequences
Invalid bytecode is rejected.
---
## 14 Summary
The Prometeu VM is:
* stack-based
* deterministic
* frame-synchronized
* handle-based for heap access
* multi-return capable
* first-class function capable
* coroutine-driven for concurrency
This design balances:
* ease of compilation
* predictable performance
* safety and debuggability
* suitability for real-time 2D games.
< [Back](chapter-1.md) | [Summary](table-of-contents.md) | [Next](chapter-3.md) >
+353
View File
@@ -0,0 +1,353 @@
< [Back](chapter-2.md) | [Summary](table-of-contents.md) | [Next](chapter-4.md) >
# 🧠 **Memory Model**
This chapter defines the memory architecture of the Prometeu Virtual Machine (PVM). It describes the stack, heap, handles, object layout, garbage collection, and interaction with host-owned memory such as asset banks.
The memory model is designed to be:
* deterministic
* safe
* simple to verify
* suitable for real-time 2D games
---
## 1 Overview
The PVM uses a **split memory model**:
1. **Stack memory**
* used for temporary values
* function arguments
* multi-return tuples
2. **Heap memory**
* used for all user-defined objects
* accessed only through handles
3. **Host-owned memory**
* asset banks
* audio buffers
* framebuffers
* not part of the VM heap
---
## 2 Stack Memory
The stack is used for:
* primitive values
* built-in value types
* temporary results
* function arguments
* tuple returns
### Stack value types
| Type | Description |
| -------- | ------------------------ |
| `int` | 64-bit integer |
| `bool` | Boolean |
| `float` | 64-bit float |
| `vec2` | 2D vector |
| `color` | Packed color |
| `pixel` | Position + color |
| `handle` | Reference to heap object |
All stack values are:
* fixed-size
* copied by value
* never directly reference raw memory
### Stack properties
* Stack is bounded and verified.
* Stack depth must be consistent across all control paths.
* Stack never stores raw pointers.
---
## 3 Tuples (Stack-Only Aggregates)
Tuples are used for multi-value returns.
### Tuple rules
* Tuples exist only on the stack.
* Maximum tuple arity: **6 slots**.
* Tuples are not heap objects by default.
* To persist a tuple, it must be explicitly boxed into a heap object.
### Example
Function returning two values:
```
fn position(): (int, int)
```
At runtime:
```
stack top → [x, y]
```
---
## 4 Heap Memory
All user-defined objects live in the heap.
### Heap characteristics
* Linear slot-based storage.
* Objects are fixed-layout blocks.
* No raw pointer access.
* No inheritance at memory level.
Heap objects include:
* user structs/classes
* arrays
* strings
* closures
* boxed tuples (optional)
---
## 5 Handles and Gate Table
All heap objects are accessed via **handles**.
A handle is defined as:
```
handle = { index, generation }
```
The VM maintains a **gate table**:
```
GateEntry {
alive: bool
generation: u32
base: usize
slots: u32
type_id: u32
}
```
### Handle safety
When an object is freed:
* `alive` becomes false
* `generation` is incremented
When a handle is used:
* index must exist
* generation must match
Otherwise, the VM traps.
This prevents:
* use-after-free
* stale references
---
## 6 Object Layout
Heap objects have a simple, fixed layout:
```
Object {
type_id
field_0
field_1
...
}
```
Properties:
* Fields are stored in slot order.
* No hidden base classes.
* No pointer arithmetic.
Traits and method dispatch are resolved:
* statically by the compiler, or
* via vtable handles (if dynamic dispatch is used).
---
## 7 Closures
Closures are heap objects.
Layout:
```
Closure {
func_id
capture_count
captures[]
}
```
Captures may be:
* copied values
* handles to heap objects
Closure environments are part of the GC root set.
---
## 8 Coroutine Memory
Each coroutine owns its own stacks:
```
Coroutine {
call_stack
operand_stack
state
}
```
All coroutine stacks are included in the GC root set.
Coroutines do not share stacks or frames.
---
## 9 Garbage Collection
The PVM uses a **mark-sweep collector**.
### GC properties
* Non-moving (no compaction in v1).
* Runs only at **safepoints**.
* Primary safepoint: `FRAME_SYNC`.
### GC triggers
GC may run when:
* heap usage exceeds threshold
* allocation pressure is high
### Root set
The collector marks from:
* operand stack
* call stack frames
* global variables
* coroutine stacks
* closure environments
* host-held handles
---
## 10 Allocation and Deallocation
### Allocation
Heap allocation:
1. VM reserves a slot block.
2. A gate entry is created.
3. A handle is returned.
If allocation fails:
* VM may trigger GC.
* If still failing, a trap occurs.
### Deallocation
Objects are freed only by the GC.
When freed:
* gate is marked dead
* generation is incremented
* memory becomes available via free list
---
## 11 Host-Owned Memory (Asset Banks)
Asset memory is **not part of the VM heap**.
It is managed by the firmware.
Examples:
* tilebanks
* audio sample banks
* sprite sheets
### Properties
* VM cannot access asset memory directly.
* Access occurs only through syscalls.
* Asset memory is not scanned by GC.
---
## 12 Save Memory (MEMCARD)
Save memory is a host-managed persistent storage area.
Properties:
* fixed size
* accessed only via syscalls
* not part of the VM heap
* not scanned by GC
---
## 13 Memory Safety Rules
The VM enforces:
1. All heap access via handles.
2. Generation checks on every handle use.
3. Bounds checking on object fields.
4. No raw pointer arithmetic.
5. Verified stack discipline.
Any violation results in a trap.
---
## 14 Summary
The PVM memory model is based on:
* stack-only primitive and tuple values
* heap-only user objects
* generation-based handles
* deterministic GC at frame safepoints
* strict separation between VM heap and host memory
This design ensures:
* predictable performance
* memory safety
* simple verification
* suitability for real-time game workloads.
< [Back](chapter-2.md) | [Summary](table-of-contents.md) | [Next](chapter-4.md) >
+600
View File
@@ -0,0 +1,600 @@
< [Back](chapter-3.md) | [Summary](table-of-contents.md) | [Next](chapter-5.md) >
# 🎨 **GFX Peripheral (Graphics System)**
## 1. Overview
The **GFX** peripheral is responsible for generating images in PROMETEU.
It models **simple graphics hardware**, inspired by classic consoles
(SNES, CPS-2, Neo-Geo), prioritizing:
- determinism
- low computational cost
- didactics
- portability
The GFX **is not a modern GPU**.
It is an explicit device, based on:
- framebuffer
- tilemaps
- tile banks
- priority-based sprites
- composition by drawing order
---
## 2. Resolution and Framebuffer
### Base resolution
- **320 × 180 pixels**
- aspect ratio close to 16:9
- scalable by the host (nearest-neighbor)
### Pixel format
- **RGB565**
- 5 bits Red
- 6 bits Green
- 5 bits Blue
- no alpha channel
Transparency is handled via **color key**.
---
## 3. Double Buffering
The GFX maintains two buffers:
- **Back Buffer** — where the frame is built
- **Front Buffer** — where the frame is displayed
Per-frame flow:
1. The system draws to the back buffer
2. Calls `present()`
3. Buffers are swapped
4. The host displays the front buffer
This guarantees:
- no tearing
- clear per-frame synchronization
- deterministic behavior
---
## 4. PROMETEU Graphical Structure
The graphical world is composed of:
- Up to **16 Tile Banks**
- **4 Tile Layers** (scrollable)
- **1 HUD Layer** (fixed, always on top)
- Sprites with priority between layers
### 4.1 Tile Banks
- There are up to **16 banks**
- Each bank has a fixed tile size:
- 8×8, 16×16, or 32×32
- A bank is a graphics library:
- environment
- characters
- UI
- effects
### 4.2 Layers
- There are:
- 4 Tile Layers
- 1 HUD Layer
- Each layer points to **a single bank**
- Sprites can use **any bank**
- HUD:
- does not scroll
- maximum priority
- generally uses 8×8 tiles
---
## 5. Internal Model of a Tile Layer
A Tile Layer **is not a bitmap of pixels**.
It is composed of:
- A **logical Tilemap** (tile indices)
- A **Border Cache** (window of visible tiles)
- A **Scroll Offset**
### Structure:
- `bank_id`
- `tile_size`
- `tilemap` (large matrix)
- `scroll_x`, `scroll_y`
- `cache_origin_x`, `cache_origin_y`
- `cache_tiles[w][h]`
---
## 6. Logical Tilemap
The tilemap represents the world:
Each cell contains:
- `tile_id`
- `flip_x`
- `flip_y`
- `priority` (optional)
- `palette_id` (optional)
The tilemap can be much larger than the screen.
---
## 7. Border Cache (Tile Cache)
The cache is a window of tiles around the camera.
Example:
- Screen: 320×180
- 16×16 tiles → 20×12 visible
- Cache: 22×14 (1-tile margin)
It stores tiles already resolved from the tilemap.
---
## 8. Cache Update
Every frame:
1. Calculate:
- `tile_x = scroll_x / tile_size`
- `tile_y = scroll_y / tile_size`
- `offset_x = scroll_x % tile_size`
- `offset_y = scroll_y % tile_size`
2. If `tile_x` changed:
- Advance `cache_origin_x`
- Reload only the new column
3. If `tile_y` changed:
- Advance `cache_origin_y`
- Reload only the new line
Only **one row and/or column** is updated per frame.
---
## 9. Cache as Ring Buffer
The cache is circular:
- Does not physically move data
- Only moves logical indices
Access:
- `real_x = (cache_origin_x + logical_x) % cache_width`
- `real_y = (cache_origin_y + logical_y) % cache_height`
---
## 10. Projection to the Back Buffer
For each frame:
1. For each Tile Layer, in order:
- Rasterize visible tiles from the cache
- Apply scroll, flip, and transparency
- Write to the back buffer
2. Draw sprites:
- With priority between layers
- Drawing order defines depth
3. Draw HUD layer last
---
## 11. Drawing Order and Priority
- There is no Z-buffer
- There is no automatic sorting
- Whoever draws later is in front
Base order:
1. Tile Layer 0
2. Tile Layer 1
3. Tile Layer 2
4. Tile Layer 3
5. Sprites (by priority between layers)
6. HUD Layer
---
## 12. Transparency (Color Key)
- One RGB565 value is reserved as TRANSPARENT_KEY
- Pixels with this color are not drawn
```
if src == TRANSPARENT_KEY:
skip
else:
draw
```
---
## 13. Color Math (Discrete Blending)
Inspired by the SNES.
Official modes:
- `BLEND_NONE`
- `BLEND_HALF`
- `BLEND_HALF_PLUS`
- `BLEND_HALF_MINUS`
- `BLEND_FULL`
No continuous alpha.
No arbitrary blending.
Everything is:
- integer
- cheap
- deterministic
---
## 14. Where Blend is Applied
- Blending occurs during drawing
- The result goes directly to the back buffer
- There is no automatic post-composition
---
## 15. What the GFX DOES NOT support
By design:
- Continuous alpha
- RGBA framebuffer
- Shaders
- Modern GPU pipeline
- HDR
- Gamma correction
---
## 16. Performance Rule
- Layers:
- only update the border when crossing a tile
- never redraw the entire world
- Rasterization:
- always per frame, only the visible area
- Sprites:
- always redrawn per frame
---
## 17. Special PostFX — Fade (Scene and HUD)
PROMETEU supports **gradual fade** as a special PostFX, with two independent
controls:
- **Scene Fade**: affects the entire scene (Tile Layers 0–3 + Sprites)
- **HUD Fade**: affects only the HUD Layer (always composed last)
The fade is implemented without continuous per-pixel alpha and without floats.
It uses a **discrete integer level** (0..31), which in practice produces an
"almost continuous" visual result in 320×180 pixel art.
---
### 17.1 Fade Representation
Each fade is represented by:
- `fade_level: u8` in the range **[0..31]**
- `0` → fully replaced by the fade color
- `31` → fully visible (no fade)
- `fade_color: RGB565`
- color the image will be blended into
Registers:
- `SCENE_FADE_LEVEL` (0..31)
- `SCENE_FADE_COLOR` (RGB565)
- `HUD_FADE_LEVEL` (0..31)
- `HUD_FADE_COLOR` (RGB565)
Common cases:
- Fade-out: `fade_color = BLACK`
- Flash/teleport: `fade_color = WHITE`
- Special effects: any RGB565 color
---
### 17.2 Fade Operation (Blending with Arbitrary Color)
For each RGB565 pixel `src` and fade color `fc`, the final pixel `dst` is calculated per channel.
1) Extract components:
- `src_r5`, `src_g6`, `src_b5`
- `fc_r5`, `fc_g6`, `fc_b5`
2) Apply integer blending:
```
src_weight = fade_level // 0..31
fc_weight = 31 - fade_level
r5 = (src_r5 * src_weight + fc_r5 * fc_weight) / 31
g6 = (src_g6 * src_weight + fc_g6 * fc_weight) / 31
b5 = (src_b5 * src_weight + fc_b5 * fc_weight) / 31
```
- `src_r5`, `src_g6`, `src_b5`
- `fc_r5`, `fc_g6`, `fc_b5`
3) Repack:
```
dst = pack_rgb565(r5, g6, b5)
```
Notes:
- Deterministic operation
- Integers only
- Can be optimized via LUT
---
### 17.3 Order of Application in the Frame
The frame composition follows this order:
1. Rasterize **Tile Layers 0–3** → Back Buffer
2. Rasterize **Sprites** according to priority
3. (Optional) Extra pipeline (Emission/Light/Glow etc.)
4. Apply **Scene Fade** using:
- `SCENE_FADE_LEVEL`
- `SCENE_FADE_COLOR`
5. Rasterize **HUD Layer**
6. Apply **HUD Fade** using:
- `HUD_FADE_LEVEL`
- `HUD_FADE_COLOR`
7. `present()`
Rules:
- Scene Fade never affects the HUD
- HUD Fade never affects the scene
---
### 17.4 Use Cases
- HUD Switch:
- decrease `HUD_FADE_LEVEL` to 0
- switch HUD/tilemap
- increase `HUD_FADE_LEVEL` to 31
- Area Switch:
- decrease `SCENE_FADE_LEVEL` to 0
- switch scenery
- increase `SCENE_FADE_LEVEL` to 31
- Flash / damage / teleport:
- use `fade_color = WHITE` or another thematic color
---
## 18. Palette System
### 18.1. Overview
PROMETEU uses **exclusively** palette-indexed graphics.
There is no direct RGB-per-pixel mode.
Every graphical pixel is an **index** pointing to a real color in a palette.
Objectives:
- reduce RAM and storage usage
- allow color swapping without shaders
- maintain retro identity
- facilitate effects like variation, damage, day/night
---
### 18.2. Pixel Format
Each pixel of a tile or sprite is:
- **4 bits per pixel (4bpp)**
- values: `0..15`
Fixed rule:
- Index `0` = TRANSPARENT
- Indices `1..15` = valid palette colors
---
### 18.3. Palette Structure
Each **Tile Bank** contains:
- Up to **256 palettes**
- Each palette has:
- **16 colors**
- each color in **RGB565 (u16)**
Size:
- 1 palette = 16 × 2 bytes = **32 bytes**
- 256 palettes = **8 KB per bank**
- 16 banks = **128 KB maximum palettes**
---
### 18.4. Palette Association
#### Fundamental Rule
- Each **tile** uses **a single palette**
- Each **sprite** uses **a single palette**
- The palette must be provided **explicitly** in every draw
There is no palette swap within the same tile or sprite.
---
### 18.5. Where the Palette is Defined
#### Tilemap
Each tilemap cell contains:
- `tile_id`
- `palette_id (u8)`
- `flip_x`
- `flip_y`
#### Sprite
Each sprite draw contains:
- `bank_id`
- `tile_id`
- `palette_id (u8)`
- `x`, `y`
- `flip_x`, `flip_y`
- `priority`
---
### 18.6. Color Resolution
The pipeline works like this:
1. Read indexed pixel from tile (value 0..15)
2. If index == 0 → transparent pixel
3. Otherwise:
- real_color = palette[palette_id][index]
4. Apply:
- flip
- discrete blend
- writing to back buffer
In other words:
```
pixel_index = tile_pixel(x,y)
if pixel_index == 0:
skip
else:
color = bank.palettes[palette_id][pixel_index]
draw(color)
```
---
### 18.7. Organization of Tile Banks
Tile Banks are "strong assets":
- Tiles and palettes live together
- Export/import always carries:
- tiles + palettes
- The hardware does not impose semantic organization:
- grouping is the creator's decision
- Tooling and scripts can create conventions:
- e.g.: palettes 0..15 = enemies
- 16..31 = scenery
- etc.
---
### 18.8. Possible Effects with Palettes
Without shaders, it is possible to:
- Palette swap:
- enemies with color variation
- States:
- damage, ice, poison, power-up
- Day / night:
- swap palettes globally
- Biomes:
- same art, different climate
- UI themes
All this without changing tiles.
---
### 18.9. Artistic Limitations
- Each tile/sprite:
- maximum of 16 colors
- Smooth gradients require:
- dithering
- discrete blend
- glow/emission
This limitation is intentional and part of the PROMETEU identity.
---
### 18.10. Metrics for Certification (CAP)
The system can measure:
- `palettes_loaded_total`
- `palettes_referenced_this_frame`
- `tiles_drawn_by_palette_id`
- `sprites_drawn_by_palette_id`
This allows:
- analyzing artistic cost
- teaching the impact of excessive variety
- suggesting best practices for visual cohesion
---
## 19. Summary
PROMETEU's GFX is simple **by choice**, not by limitation.
- RGB565 Framebuffer with double buffer
- Color key for transparency
- SNES-style discrete blending
- Up to 16 tile banks
- 4 Tile Layers + 1 HUD
- Layer = tilemap + cache + scroll
- Rasterized projection per frame
- Depth defined by drawing order
< [Back](chapter-3.md) | [Summary](table-of-contents.md) | [Next](chapter-5.md) >
+331
View File
@@ -0,0 +1,331 @@
< [Back](chapter-4.md) | [Summary](table-of-contents.md) | [Next](chapter-6.md) >
# 🔊 AUDIO Peripheral (Audio System)
## 1. Overview
The **AUDIO Peripheral** is responsible for **sound generation and mixing** in PROMETEU.
Just like the other subsystems:
- it is not automatic
- it is not free
- it is not magic
Each sound is the result of **explicit commands**, executed under a **time and resource budget**.
> Sound consumes time.
> Sound consumes memory.
---
## 2. Philosophy
PROMETEU treats audio as:
- an **active peripheral**
- with **limited channels**
- **deterministic** behavior
- **explicit** control
Objective: architectural and didactic clarity, not absolute realism.
---
## 3. General Architecture
The audio system is composed of:
- **Voices (channels)** — independent players
- **Samples** — PCM data
- **Mixer** — summation of voices
- **Output** — PCM stereo buffer
Conceptual separation:
- Game sends **commands at 60Hz**
- Audio is **generated continuously** at 48kHz
---
## 4. Output Format
- Sample rate: **48,000 Hz**
- Format: **PCM16 stereo (signed i16)**
- Clipping: saturation/clamp
This format is compatible with:
- common I2S DACs
- HDMI audio
- USB audio
- DIY SBCs (Raspberry Pi, Orange Pi, etc.)
---
## 5. Voices (Channels)
### 5.1 Quantity
```
MAX_VOICES = 16
```
Each voice:
- plays **1 sample at a time**
- is independent
- is mixed into the final output
---
### 5.2 Voice State
Each voice maintains:
- `sample_id`
- `pos` (fractional position in the sample)
- `rate` (pitch)
- `volume` (0..255)
- `pan` (0..255, left→right)
- `loop_mode` (off / on)
- `loop_start`, `loop_end`
- `priority` (optional)
---
### 5.3 Voice Conflict
If all voices are occupied:
- an explicit policy is applied:
- `STEAL_OLDEST`
- `STEAL_QUIETEST`
- `STEAL_LOWEST_PRIORITY`
PROMETEU does not resolve this automatically without a defined rule.
---
## 6. Conceptual Model: “Audio CPU”
The PROMETEU AUDIO is conceived as an **independent peripheral**, just as classic consoles had:
- Main game CPU
- Dedicated sound CPU
In PROMETEU:
- The **logical core** assumes this conceptual separation
- The **host decides** how to implement it:
- same thread
- separate thread
- separate core
### 6.1 Hardware Metaphor
Conceptually:
```
[Game CPU] → sends 60Hz commands → [AUDIO Peripheral]
|
v
Voices + Mixer
|
v
PCM Output
```
### 6.2 Implementation is the Host's Role
The core:
- defines the **model**
- defines the **commands**
- defines the **limits**
The host:
- chooses:
- threads
- CPU affinity
- audio backend
- guarantees continuous delivery of buffers
Thus:
> PROMETEU models the hardware.
> The host decides how to physically realize it.
---
## 7. Samples
### 7.1 Format
PROMETEU samples:
- **PCM16 mono**
- own sample_rate (e.g., 22050, 44100, 48000)
- immutable data at runtime
Fields:
- `sample_rate`
- `frames_len`
- `loop_start`, `loop_end` (optional)
---
### 7.2 Usage
Example:
```
audio.play(sample_id, voice_id, volume, pan, pitch, priority)
```
Or:
```
audio.playAuto(sample_id, volume, pan, pitch, priority)
```
(uses stealing policy)
---
## 8. Pitch and Interpolation
- `rate = 1.0` → normal speed
- `rate > 1.0` → higher pitch
- `rate < 1.0` → lower pitch
As position becomes fractional:
- **linear interpolation** is used between two neighboring samples
---
## 9. Mixer
For each output frame (48kHz):
1. For each active voice:
- read sample at current position
- apply pitch
- apply volume
- apply pan → generates L/R
2. Sum all voices
3. Apply clamp
4. Write to the stereo buffer
Cost depends on:
- number of active voices
- use of interpolation
---
## 10. Synchronization with the Game
- Game runs at **60Hz**
- Audio generates data at **48kHz**
Every frame (60Hz):
- game sends commands:
- play
- stop
- set_volume
- set_pan
- set_pitch
The audio applies these commands and continues playing.
---
## 11. Basic Commands
Conceptual examples:
```
audio.play(sample, voice, volume, pan, pitch, priority)
audio.stop(voice)
audio.setVolume(voice, v)
audio.setPan(voice, p)
audio.setPitch(voice, p)
audio.isPlaying(voice)
```
---
## 12. Audio and CAP
Audio participates in the Execution CAP:
- mixing cost per frame
- cost per active voice
- command cost
Example:
```
Frame 1024:
voices_active: 9
mix_cycles: 410
audio_commands: 6
```
---
## 13. Best Practices
Recommended:
- reuse samples
- limit simultaneous voices
- treat sound as an event
- separate music and effects
Avoid:
- playing sound every frame
- abusing voices
- giant samples for simple effects
---
## 14. Historical Inspiration
The PROMETEU model is inspired by:
- NES: fixed channels
- SNES: sample playback + mixing
- CPS2: comfortable polyphony
- Neo Geo: heavy samples (not fully copied)
But abstracted for:
- clarity
- simplicity
- teaching
---
## 15. Summary
- Output: stereo PCM16 @ 48kHz
- 16 voices
- mono PCM16 samples
- Volume, pan, pitch
- Linear interpolation
- Explicit mixer
- "Audio CPU" concept
- Implementation is the host's role
< [Back](chapter-4.md) | [Summary](table-of-contents.md) | [Next](chapter-6.md) >
+260
View File
@@ -0,0 +1,260 @@
< [Back](chapter-5.md) | [Summary](table-of-contents.md) | [Next](chapter-7.md) >
# 🎮 **INPUT Peripheral (Input System)**
## 1. Overview
The **INPUT Peripheral** is responsible for **collecting and providing the state of controls** to the PROMETEU program.
In PROMETEU:
- input is **state**, not an implicit event
- input is **sampled over time**, not delivered asynchronously
- input has a **defined order, cost, and moment**
> Buttons do not “trigger events”.
> They change state.
>
---
## 2. Philosophy of the Input System
PROMETEU models input like classic hardware:
- the state of controls is read **once per frame**
- the program queries this state during `UPDATE`
- there are no asynchronous input callbacks
This model:
- is deterministic
- is simple to understand
- reflects microcontrollers and classic consoles
---
## 3. Input Devices
PROMETEU abstracts different devices into a common interface.
Typical devices:
- digital control (D-Pad + botões)
- keyboard (mapped to buttons)
- gamepad
- touch (mobile, mapped)
Regardless of the origin, PROMETEU exposes **the same logical model**.
---
## 4. State Model
### 4.1 Per-Frame State
For each frame, the system maintains:
- current state of buttons
- state from the previous frame
This allows querying:
- button pressed
- button released
- button held down
---
### 4.2 Query Types
Typical operations:
```
input.btn(id)// button is pressed
input.btnp(id)// button was pressed this frame
input.btnr(id)// button was released this frame
```
These functions:
- are purely advisory
- do not change state
- have an explicit cost
---
## 5. Sampling Moment
The input state is captured **at the beginning of each frame**, before the `UPDATE` phase.
Conceptual flow:
```
FRAME N:
SAMPLEINPUT
UPDATE
DRAW
AUDIO
SYNC
```
Throughout the entire frame:
- the input state is immutable
- repeated calls return the same value
> Input does not change in the middle of the frame.
>
---
## 6. Determinism and Reproducibility
The PROMETEU input model guarantees:
- same sequence of inputs
- same frames
- same results
This allows:
- execution playback
- deterministic replays
- reliable certification
Input can be:
- recorded
- played back
- artificially injected
---
## 7. Input and CAP
Input operations:
- consume few cycles
- participate in the per-frame budget
- appear in certification reports
Example:
```
Frame 18231:
input.btn():12cycles
```
Although cheap, input **is not free**.
---
## 8. Button Mapping
### 8.1 Logical Identifiers
PROMETEU defines logical button identifiers:
- `UP`, `DOWN`, `LEFT`, `RIGHT`
- `A`, `B`, `X`, `Y`
- `START`, `SELECT`
The physical mapping:
- depends on the platform
- is resolved outside the VM
- is transparent to the program
---
### 8.2 Portability
The same PROMETEU cartridge:
- runs on a keyboard
- runs on a gamepad
- runs on touch
Without any code changes.
---
## 9. Analog Input (Optional)
PROMETEU can expose analog axes explicitly:
```
input.axis(id)
```
Characteristics:
- normalized value (e.g.: -1.0 to 1.0)
- explicit cost
- per-frame update
Analog input:
- is not mandatory
- does not replace digital input
- must be used consciously
---
## 10. Input Best Practices
PROMETEU encourages:
- treating input as state
- querying input only in `UPDATE`
- separating input from heavy logic
- mapping actions, not keys
And discourages:
- logic dependent on excessive polling
- reading input in DRAW
- direct coupling to physical hardware
---
## 11. Relationship with Classic Consoles
The PROMETEU model reflects:
- reading input registers
- per-frame polling
- absence of asynchronous events
This model:
- simplifies reasoning
- increases predictability
- facilitates debugging
---
## 12. Pedagogical Implications
The INPUT Peripheral allows teaching:
- the difference between event and state
- temporal sampling
- determinism in interactive systems
- synchronization between input and logic
With clear and reproducible feedback.
---
## 13. Summary
- input is state, not an event
- sampled once per frame
- immutable during the frame
- queries have an explicit cost
- input participates in the CAP
- model is deterministic
< [Back](chapter-5.md) | [Summary](table-of-contents.md) | [Next](chapter-7.md) >
+262
View File
@@ -0,0 +1,262 @@
< [Back](chapter-6.md) | [Summary](table-of-contents.md) | [Next](chapter-8.md) >
# 🖐️ TOUCH Peripheral (Absolute Pointer Input System)
## 1. Overview
The **TOUCH** peripheral provides PROMETEU with an **absolute pointer**, based on screen coordinates, intended for:
- UI interaction
- direct element selection
- contextual actions in the scenery
- drag-based mechanics (drag, slash, trail)
The TOUCH is a **first-class peripheral**, as valid as D-Pad and buttons.
---
## 2. Design Principles
TOUCH in PROMETEU follows strict principles:
- ✅ **Universal single-touch**
- ✅ **Deterministic**
- ✅ **Per-frame state**
- ✅ **No gestures**
- ✅ **No acceleration**
- ✅ **No heuristics**
- ✅ **Same behavior on all platforms**
> If a behavior cannot be guaranteed on all platforms, it does not exist in PROMETEU.
>
---
## 3. Conceptual Model
PROMETEU exposes **only one active pointer at a time**, regardless of how many physical touches the hardware recognizes.
- Hardware may detect multitouch
- Runtime selects **only one active touch**
- The API **never exposes multitouch**
This model guarantees:
- total portability
- predictability
- absence of ambiguities
---
## 4. Coordinate Space
- TOUCH coordinates use **the same space as the framebuffer**
- Resolution: **320×180**
- Origin: top-left corner `(0,0)`
- Ranges:
- `x ∈ [0, 319]`
- `y ∈ [0, 179]`
TOUCH is **absolute**:
> (x, y) represents the exact position of contact, without dynamic transformation.
>
---
## 5. TOUCH Peripheral API
### 5.1 Exposed Structure
```
TOUCH:
present : bool
down : bool
pressed : bool
released : bool
x : int
y : int
```
---
### 5.2 Field Semantics
- **present**
- `true` if the TOUCH peripheral is available
- `false` if there is no physical touch (desktop, hardware without touch)
- **down**
- `true` while the active pointer is pressed
- **pressed**
- `true` only in the frame where the active pointer was captured
- **released**
- `true` only in the frame where the active pointer was released
- **x, y**
- current position of the active pointer
- valid only when `down == true`
---
## 6. Pointer Selection Policy
### *Single Pointer Capture Policy*
When multiple physical touches occur, PROMETEU applies the following policy:
---
### 6.1 Initial Capture
1. If **no pointer is active**
2. And a **new physical touch** occurs
3. The **first detected touch** is captured
4. This touch becomes the **active pointer**
This frame generates:
- `pressed = true`
- `down = true`
---
### 6.2 Capture Maintenance
While the active pointer is pressed:
- Only it is tracked
- All other physical touches are ignored
- `x, y` follow only the active pointer
---
### 6.3 Release
When the active pointer is released:
- `released = true`
- `down = false`
- The system enters a **no active pointer** state
---
### 6.4 Recapture (Important Rule)
After release:
- Touches that **were already present** are ignored
- A new pointer is only captured with a **new touch event**
> This avoids unexpected pointer jumps and accidental actions.
>
---
## 7. Deliberately NOT Supported Behaviors
The TOUCH peripheral **does not implement**:
❌ Multitouch
❌ Gestures (swipe, pinch, rotate, long-press)
❌ Acceleration or smoothing
❌ Dynamic sensitivity
❌ Implicit history
❌ Intent interpretation
If a game wants any of these behaviors, it must:
- implement them explicitly
- using only per-frame state
- without implicit hardware support
---
## 8. “No Gesture” — Formal Definition
PROMETEU **does not interpret temporal patterns**.
The TOUCH peripheral **does not classify actions** as:
- swipe
- drag
- long press
- double tap
It only reports:
- current position
- contact state
All semantics are the game's responsibility.
---
## 9. “No Acceleration” — Formal Definition
PROMETEU **does not modify** the TOUCH input.
- No sensitivity curves
- No speed-based amplification
- No smoothing
The relationship between the physical touch and `(x, y)` is **1:1** after normalization.
---
## 10. Integration with Other Input Forms
- Desktop:
- mouse can emulate TOUCH
- Mobile:
- direct physical touch
- Steam Deck:
- physical touchscreen
- PROMETEU Hardware:
- optional touch, but supported
From PROMETEU's point of view:
> TOUCH is always TOUCH.
>
---
## 11. Expected Uses
The TOUCH peripheral is suitable for:
- UI (menus, inventory, maps)
- drag-and-drop
- direct selection
- “click to investigate”
- pointing-based puzzles
- trail mechanics (e.g.: Fruit Ninja-like)
---
## 12. Portability Guarantees
Every PROMETEU game that uses TOUCH:
- behaves identically on all platforms
- does not depend on host-specific capabilities
- does not suffer semantic variation between desktop, mobile, and dedicated hardware
---
## 13. Summary
The TOUCH in PROMETEU is:
- simple
- explicit
- predictable
- universal
- deterministic
< [Back](chapter-6.md) | [Summary](table-of-contents.md) | [Next](chapter-8.md) >
+238
View File
@@ -0,0 +1,238 @@
< [Back](chapter-7.md) | [Summary](table-of-contents.md) | [Next](chapter-9.md) >
# 📀 MEMCARD Peripheral (Save/Load System)
## 1. Overview
The **MEMCARD** is the peripheral responsible for the **explicit persistence of game data** in PROMETEU.
It simulates the behavior of classic *memory cards* (PS1, GameCube), providing:
- limited storage
- explicit I/O cost
- full game control over when to save
- portability across platforms
The MEMCARD **is not a save state**.
It represents **data that the game itself decides to persist**.
---
## 2. Design Principles
The MEMCARD peripheral follows these principles:
- ✅ **Explicit persistence** (nothing automatic)
- ✅ **Limited and known size**
- ✅ **Mandatory commit**
- ✅ **Measurable time cost (cycles)**
- ✅ **Stable and documented format**
- ✅ **Platform independent**
- ❌ No complex file system (in v0.1)
- ❌ No multiple internal files (in v0.1)
---
## 3. Conceptual Model
Each PROMETEU cartridge can access **one or more MEMCARD slots**, the default model being:
- **Slot A** — main
- **Slot B** — optional (future)
Each slot corresponds to **a file on the host**:
```
MyGame_A.mem
MyGame_B.mem
```
The runtime mounts this file as a **persistent storage device**.
---
## 4. Capacity and CAP
The size of the MEMCARD is **fixed**, defined by the execution profile (CAP).
### Suggested sizes
| Profile | Size |
| --- | --- |
| JAM | 8 KB |
| STANDARD | 32 KB |
| ADVANCED | 128 KB |
The game **cannot exceed** this size.
Attempts to write above the limit result in an error.
---
## 5. Peripheral API (v0.1)
### 5.1 Logical Interface
The MEMCARD exposes a **simple single-blob API**:
```
mem.read_all() -> byte[]
mem.write_all(byte[])
mem.commit()
mem.clear()
mem.size() -> int
```
---
### 5.2 Operation Semantics
### `read_all()`
- Returns all persisted content
- If the card is empty, returns a zeroed buffer
- Cycle cost proportional to size
---
### `write_all(bytes)`
- Writes the buffer **to temporary memory**
- Does not persist immediately
- Fails if `bytes.length > mem.size()`
---
### `commit()`
- Persists data to the device
- **Mandatory** operation
- Simulates hardware flush
- May fail (e.g., I/O, simulated corruption)
---
### `clear()`
- Zeroes the card content
- Requires `commit()` to persist
---
### `size()`
- Returns total card capacity in bytes
---
## 6. Explicit Commit (Fundamental Rule)
PROMETEU **does not save automatically**.
Without `commit()`:
- data remains volatile
- can be lost upon exiting the game
- simulates abrupt hardware shutdown
👉 This teaches:
- data flushing
- atomicity
- risk of corruption
- real cost of persistence
---
## 7. Execution Cost (Cycles)
All MEMCARD operations have an explicit cost.
### Example (illustrative values)
| Operation | Cost |
| --- | --- |
| read_all | 1 cycle / 256 bytes |
| write_all | 1 cycle / 256 bytes |
| commit | fixed + proportional cost |
These costs appear:
- in the profiler
- in the frame timeline
- in the CAP report
---
## 8. `.mem` File Format
The MEMCARD file has a simple and robust format.
### 8.1 Header
| Field | Size |
| --- | --- |
| Magic (`PMEM`) | 4 bytes |
| Version | 1 byte |
| Cart ID | 8 bytes |
| Payload Size | 4 bytes |
| CRC32 | 4 bytes |
---
### 8.2 Payload
- Binary buffer defined by the game
- Fixed size
- Content interpreted only by the game
---
## 9. Integrity and Security
- CRC validates corruption
- Cart ID prevents using wrong save
- Version allows future format evolution
- Runtime can:
- warn of corruption
- allow card reset
---
## 10. Integration with the Editor / GUI
The main tool can provide a **Memory Card Manager**:
- create/reset card
- see size and usage
- import/export `.mem`
- visualize last commits
- associate cards with projects
None of these operations change the runtime.
---
## 11. Planned Evolutions (outside v0.1)
- Block API (`read_block`, `write_block`)
- multiple internal slots
- wear simulation
- save versioning
- optional encryption (educational)
---
## 12. Summary
The MEMCARD peripheral in PROMETEU:
- simulates real hardware
- forces design decisions
- teaches persistence correctly
- is simple to use
- is hard to abuse
- grows without breaking compatibility
< [Back](chapter-7.md) | [Summary](table-of-contents.md) | [Next](chapter-9.md) >
+308
View File
@@ -0,0 +1,308 @@
< [Back](chapter-8.md) | [Summary](table-of-contents.md) | [Next](chapter-10.md) >
# ⚡ **Events and Scheduling**
This chapter defines how the Prometeu Virtual Machine (PVM) handles events, frame synchronization, and cooperative concurrency. It replaces the older interrupt-oriented terminology with a simpler and more accurate model based on **frame boundaries**, **event queues**, and **coroutines**.
The goal is to preserve determinism while still allowing responsive and structured game logic.
---
## 1 Core Philosophy
Prometeu does **not use asynchronous callbacks** or preemptive interrupts for user code.
All external signals are:
* queued by the firmware
* delivered at deterministic points
* processed inside the main execution loop
Nothing executes “out of time”.
Nothing interrupts the program in the middle of an instruction.
Nothing occurs without a known cost.
This guarantees:
* deterministic behavior
* reproducible runs
* stable frame timing
---
## 2 Events
### 2.1 Definition
An **event** is a logical signal generated by the system or by internal runtime mechanisms.
Events:
* represent something that has occurred
* do not execute code automatically
* are processed explicitly during the frame
Examples:
* end of frame
* timer expiration
* asset load completion
* system state change
* execution error
---
### 2.2 Event Queue
The firmware maintains an **event queue**.
Properties:
* events are queued in order
* events are processed at frame boundaries
* event processing is deterministic
Events never:
* execute user code automatically
* interrupt instructions
* run outside the main loop
---
## 3 Frame Boundary (Sync Phase)
The primary synchronization point in Prometeu is the **frame boundary**, reached by the `FRAME_SYNC` instruction.
At this point:
1. Input state is sampled.
2. Events are delivered.
3. Coroutine scheduling occurs.
4. Optional garbage collection may run.
5. Control returns to the firmware.
This replaces the older notion of a "VBlank interrupt".
The frame boundary:
* has a fixed, measurable cost
* does not execute arbitrary user code
* is fully deterministic
---
## 4 System Events vs System Faults
Prometeu distinguishes between normal events and system faults.
### 4.1 Normal events
Examples:
* timer expired
* asset loaded
* frame boundary
These are delivered through the event queue.
### 4.2 System faults
Generated by exceptional conditions:
* invalid instruction
* memory violation
* handle misuse
* verifier failure
Result:
* VM execution stops
* state is preserved
* a diagnostic report is generated
System faults are not recoverable events.
---
## 5 Timers
Timers are modeled as **frame-based counters**.
Properties:
* measured in frames, not real time
* deterministic across runs
* generate events when they expire
Timers:
* do not execute code automatically
* produce queryable or queued events
Example:
```
if timer.expired(t1) {
// handle event
}
```
---
## 6 Coroutines and Cooperative Scheduling
Prometeu provides **coroutines** as the only form of concurrency.
Coroutines are:
* cooperative
* deterministic
* scheduled only at safe points
There is:
* no preemption
* no parallel execution
* no hidden threads
### 6.1 Coroutine lifecycle
Each coroutine can be in one of the following states:
* `Ready`
* `Running`
* `Sleeping`
* `Finished`
### 6.2 Scheduling
At each frame boundary:
1. The scheduler selects the next coroutine.
2. Coroutines run in a deterministic order.
3. Each coroutine executes within the frame budget.
The default scheduling policy is:
* round-robin
* deterministic
---
### 6.3 Coroutine operations
Typical coroutine instructions:
| Operation | Description |
| --------- | ----------------------------- |
| `spawn` | Create a coroutine |
| `yield` | Voluntarily suspend execution |
| `sleep` | Suspend for N frames |
`yield` and `sleep` only take effect at safe points.
---
## 7 Relationship Between Events, Coroutines, and the Frame Loop
The high-level frame structure is:
```
FRAME N
------------------------
Sample Input
Deliver Events
Schedule Coroutines
Run VM until:
- budget exhausted, or
- FRAME_SYNC reached
Sync Phase
------------------------
```
Important properties:
* events are processed at known points
* coroutine scheduling is deterministic
* no execution occurs outside the frame loop
---
## 8 Costs and Budget
All event processing and scheduling:
* consumes cycles
* contributes to the CAP (certification and analysis profile)
* appears in profiling reports
Example:
```
Frame 18231:
Event processing: 120 cycles
Coroutine scheduling: 40 cycles
Frame sync: 80 cycles
```
Nothing is free.
---
## 9 Determinism and Reproducibility
Prometeu guarantees:
* same sequence of inputs and events → same behavior
* frame-based timers
* deterministic coroutine scheduling
This allows:
* reliable replays
* precise debugging
* fair certification
---
## 10 Best Practices
Prometeu encourages:
* treating events as data
* querying events explicitly
* structuring logic around frame steps
* using coroutines for asynchronous flows
Prometeu discourages:
* simulating asynchronous callbacks
* relying on hidden timing
* using events as implicit control flow
---
## 11 Conceptual Comparison
| Traditional System | Prometeu |
| ------------------ | ----------------------- |
| Hardware interrupt | Frame boundary event |
| ISR | System sync phase |
| Main loop | VM frame loop |
| Timer interrupt | Frame-based timer event |
| Threads | Coroutines |
Prometeu teaches reactive system concepts without the unpredictability of real interrupts.
---
## 12 Summary
* Events inform; they do not execute code.
* The frame boundary is the only global synchronization point.
* System faults stop execution.
* Coroutines provide cooperative concurrency.
* All behavior is deterministic and measurable.
< [Back](chapter-8.md) | [Summary](table-of-contents.md) | [Next](chapter-10.md) >
@@ -0,0 +1,21 @@
# Table of Contents
- [Chapter 1: Time Model and Cycles](chapter-1.md)
- [Chapter 2: PROMETEU VM Instruction Set](chapter-2.md)
- [Chapter 3: Memory: Stack, Heap, and Allocation](chapter-3.md)
- [Chapter 4: GFX Peripheral (Graphics System)](chapter-4.md)
- [Chapter 5: AUDIO Peripheral (Audio System)](chapter-5.md)
- [Chapter 6: INPUT Peripheral (Input System)](chapter-6.md)
- [Chapter 7: TOUCH Peripheral (Absolute Pointer Input System)](chapter-7.md)
- [Chapter 8: MEMCARD Peripheral (Save/Load System)](chapter-8.md)
- [Chapter 9: Events and Interrupts](chapter-9.md)
- [Chapter 10: Debug, Inspection, and Profiling](chapter-10.md)
- [Chapter 11: Portability Guarantees and Cross-Platform Execution](chapter-11.md)
- [Chapter 12: Firmware — PrometeuOS (POS) + PrometeuHub](chapter-12.md)
- [Chapter 13: Cartridge](chapter-13.md)
- [Chapter 14: Boot Profiles](chapter-14.md)
- [Chapter 15: Asset Management](chapter-15.md)
- [Chapter 16: Host ABI and Syscalls](chapter-16.md)
---
[Back to README](../README.md)