add PBS docs
This commit is contained in:
@@ -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) >
|
||||
@@ -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) >
|
||||
@@ -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) >
|
||||
@@ -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) >
|
||||
@@ -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) >
|
||||
@@ -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) >
|
||||
@@ -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) >
|
||||
@@ -0,0 +1,331 @@
|
||||
< [Back](chapter-14.md) | [Summary](table-of-contents.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) >
|
||||
@@ -0,0 +1,456 @@
|
||||
< [Back](chapter-1.md) | [Summary](table-of-contents.md) | [Next](chapter-3.md) >
|
||||
|
||||
# ⚙️ ** PVM (PROMETEU VM) — Instruction Set**
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The **PROMETEU VM** is a mandatory virtual machine always present in the logical hardware:
|
||||
|
||||
* **stack-based**
|
||||
* deterministic
|
||||
* cycle-oriented
|
||||
* designed for teaching and inspection
|
||||
|
||||
It exists to:
|
||||
|
||||
* map high-level language concepts
|
||||
* make computational cost visible
|
||||
* allow execution analysis
|
||||
* serve as the foundation of the PROMETEU cartridge
|
||||
|
||||
> The PROMETEU VM is simple by choice.
|
||||
> Simplicity is a pedagogical tool.
|
||||
|
||||
---
|
||||
|
||||
## 2. Execution Model
|
||||
|
||||
### 2.1 Main Components
|
||||
|
||||
The VM has:
|
||||
|
||||
* **PC (Program Counter)** — next instruction
|
||||
* **Operand Stack** — value stack
|
||||
* **Call Stack** — stores execution frames for function calls
|
||||
* **Scope Stack** — stores frames for blocks within a function
|
||||
* **Heap** — dynamic memory
|
||||
* **Globals** — global variables
|
||||
* **Constant Pool** — literals and references
|
||||
* **ROM** — cartridge bytecode
|
||||
* **RAM** — mutable data
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Execution Cycle
|
||||
|
||||
Each instruction executes:
|
||||
|
||||
```
|
||||
FETCH → DECODE → EXECUTE → ADVANCE PC
|
||||
```
|
||||
|
||||
Properties:
|
||||
|
||||
* every instruction has a fixed cost in cycles
|
||||
* there is no invisible implicit work
|
||||
* execution is fully deterministic
|
||||
|
||||
---
|
||||
|
||||
## 3. Fundamental Types
|
||||
|
||||
| Type | Description |
|
||||
| --------- | ------------------------- |
|
||||
| `int32` | 32-bit signed integer |
|
||||
| `int64` | 64-bit signed integer |
|
||||
| `float` | 64-bit floating point |
|
||||
| `boolean` | true/false |
|
||||
| `string` | immutable UTF-8 |
|
||||
| `null` | absence of value |
|
||||
| `ref` | heap reference |
|
||||
|
||||
### 3.1 Numeric Promotion
|
||||
The VM promotes types automatically during operations:
|
||||
* `int32` + `int32` → `int32`
|
||||
* `int32` + `int64` → `int64`
|
||||
* `int` + `float` → `float`
|
||||
* Bitwise operations promote `int32` to `int64` if any operand is `int64`.
|
||||
|
||||
Do not exist:
|
||||
|
||||
* magic coercions
|
||||
* implicit casts
|
||||
* silent overflows
|
||||
|
||||
---
|
||||
|
||||
## 4. Stack Conventions & Calling ABI
|
||||
|
||||
* Operations use the top of the stack.
|
||||
* Results always return to the stack.
|
||||
* **LIFO Order:** Last pushed = first consumed.
|
||||
* **Mandatory Return:** Every function (`Call`) and `Syscall` MUST leave exactly **one** value on the stack upon completion. If there is no meaningful value to return, `Null` must be pushed.
|
||||
|
||||
### 4.1 Calling Convention (Call / Ret)
|
||||
|
||||
1. **Arguments:** The caller pushes arguments in order (arg0, arg1, ..., argN-1).
|
||||
2. **Execution:** The `Call` instruction specifies `args_count`. These `N` values become the **locals** of the new frame (local 0 = arg0, local 1 = arg1, etc.).
|
||||
3. **Return Value:** Before executing `Ret`, the callee MUST push its return value.
|
||||
4. **Cleanup:** The `Ret` instruction is responsible for:
|
||||
- Popping the return value.
|
||||
- Removing all locals (the arguments) from the operand stack.
|
||||
- Re-pushing the return value.
|
||||
- Restoring the previous frame and PC.
|
||||
|
||||
### 4.2 Syscall Convention
|
||||
|
||||
1. **Arguments:** The caller pushes arguments in order.
|
||||
2. **Execution:** The native implementation pops arguments as needed. Since it's a stack, it will pop them in reverse order (argN-1 first, then argN-2, ..., arg0).
|
||||
3. **Return Value:** The native implementation MUST push exactly one value onto the stack before returning to the VM.
|
||||
4. **Cleanup:** The native implementation is responsible for popping all arguments it expects.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
PUSH_CONST 3
|
||||
PUSH_CONST 4
|
||||
ADD
|
||||
```
|
||||
|
||||
State:
|
||||
|
||||
```
|
||||
[3]
|
||||
[3, 4]
|
||||
[7]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Instruction Categories
|
||||
|
||||
1. Flow control
|
||||
2. Stack
|
||||
3. Arithmetic and logic
|
||||
4. Variables
|
||||
5. Functions
|
||||
6. Heap and structures
|
||||
7. Peripherals (syscalls)
|
||||
8. System
|
||||
|
||||
---
|
||||
|
||||
## 6. Instructions — VM Set 1
|
||||
|
||||
### 6.1 Execution Control
|
||||
|
||||
| Instruction | Cycles | Description |
|
||||
| ------------------- | ------ | ------------------------- |
|
||||
| `NOP` | 1 | Does nothing |
|
||||
| `HALT` | 1 | Terminates execution |
|
||||
| `JMP addr` | 2 | Unconditional jump |
|
||||
| `JMP_IF_FALSE addr` | 3 | Jumps if top is false |
|
||||
| `JMP_IF_TRUE addr` | 3 | Jumps if top is true |
|
||||
|
||||
---
|
||||
|
||||
### 6.2 Stack
|
||||
|
||||
| Instruction | Cycles | Description |
|
||||
| -------------- | ------ | ------------------- |
|
||||
| `PUSH_CONST k` | 2 | Pushes constant |
|
||||
| `POP` | 1 | Removes top |
|
||||
| `DUP` | 1 | Duplicates top |
|
||||
| `SWAP` | 1 | Swaps two tops |
|
||||
| `PUSH_I32 v` | 2 | Pushes 32-bit int |
|
||||
| `PUSH_I64 v` | 2 | Pushes 64-bit int |
|
||||
| `PUSH_F64 v` | 2 | Pushes 64-bit float |
|
||||
| `PUSH_BOOL v` | 2 | Pushes boolean |
|
||||
|
||||
---
|
||||
|
||||
### 6.3 Arithmetic
|
||||
|
||||
| Instruction | Cycles |
|
||||
| ----------- | ------ |
|
||||
| `ADD` | 2 |
|
||||
| `SUB` | 2 |
|
||||
| `MUL` | 4 |
|
||||
| `DIV` | 6 |
|
||||
|
||||
---
|
||||
|
||||
### 6.4 Comparison and Logic
|
||||
|
||||
| Instruction | Cycles |
|
||||
| ----------- | ------ |
|
||||
| `EQ` | 2 |
|
||||
| `NEQ` | 2 |
|
||||
| `LT` | 2 |
|
||||
| `GT` | 2 |
|
||||
| `LTE` | 2 |
|
||||
| `GTE` | 2 |
|
||||
| `AND` | 2 |
|
||||
| `OR` | 2 |
|
||||
| `NOT` | 1 |
|
||||
| `BIT_AND` | 2 |
|
||||
| `BIT_OR` | 2 |
|
||||
| `BIT_XOR` | 2 |
|
||||
| `SHL` | 2 |
|
||||
| `SHR` | 2 |
|
||||
| `NEG` | 1 |
|
||||
|
||||
---
|
||||
|
||||
### 6.5 Variables
|
||||
|
||||
| Instruction | Cycles | Description |
|
||||
| -------------- | ------ | ---------------- |
|
||||
| `GET_GLOBAL i` | 3 | Reads global |
|
||||
| `SET_GLOBAL i` | 3 | Writes global |
|
||||
| `GET_LOCAL i` | 2 | Reads local |
|
||||
| `SET_LOCAL i` | 2 | Writes local |
|
||||
|
||||
---
|
||||
|
||||
### 6.6 Functions
|
||||
|
||||
| Instruction | Cycles | Description |
|
||||
|----------------| ------ |--------------------------------------------|
|
||||
| `CALL addr` | 5 | Saves PC and creates a new call frame |
|
||||
| `RET` | 4 | Returns from function, restoring PC |
|
||||
| `PUSH_SCOPE` | 3 | Creates a scope within the current function |
|
||||
| `POP_SCOPE` | 3 | Removes current scope and its local variables |
|
||||
|
||||
**ABI Rules for Functions:**
|
||||
* **Mandatory Return Value:** Every function MUST leave exactly one value on the stack before `RET`. If the function logic doesn't return a value, it must push `null`.
|
||||
* **Stack Cleanup:** `RET` automatically clears all local variables (based on `stack_base`) and re-pushes the return value.
|
||||
|
||||
---
|
||||
|
||||
### 6.7 Heap
|
||||
|
||||
| Instruction | Cycles | Description |
|
||||
| --------------- | ------ | --------------- |
|
||||
| `ALLOC size` | 10 | Allocates on heap |
|
||||
| `LOAD_REF off` | 3 | Reads field |
|
||||
| `STORE_REF off` | 3 | Writes field |
|
||||
|
||||
Heap is:
|
||||
|
||||
* finite
|
||||
* monitored
|
||||
* accounted for in the CAP
|
||||
|
||||
---
|
||||
|
||||
### 6.8 Peripherals (Syscalls)
|
||||
|
||||
| Instruction | Cycles | Description |
|
||||
|--------------| -------- | --------------------- |
|
||||
| `SYSCALL id` | variable | Call to hardware |
|
||||
|
||||
**ABI Rules for Syscalls:**
|
||||
* **Argument Order:** Arguments must be pushed in the order they appear in the call (LIFO stack behavior).
|
||||
* Example: `gfx.draw_rect(x, y, w, h, color)` means:
|
||||
1. `PUSH x`
|
||||
2. `PUSH y`
|
||||
3. `PUSH w`
|
||||
4. `PUSH h`
|
||||
5. `PUSH color`
|
||||
6. `SYSCALL 0x1002`
|
||||
* **Consumption:** The native function MUST pop all its arguments from the stack.
|
||||
* **Return Value:** If the syscall returns a value, it will be pushed onto the stack by the native implementation. If not, the stack state for the caller remains as it was before pushing arguments.
|
||||
|
||||
#### Implemented Syscalls (v0.1)
|
||||
|
||||
| ID | Name | Arguments (Stack) | Return |
|
||||
| ---------- | ----------------- | ---------------------------- | ------- |
|
||||
| `0x0001` | `system.has_cart` | - | `bool` |
|
||||
| `0x0002` | `system.run_cart` | - | - |
|
||||
| `0x1001` | `gfx.clear` | `color_idx` | - |
|
||||
| `0x1002` | `gfx.draw_rect` | `x, y, w, h, color_idx` | - |
|
||||
| `0x1003` | `gfx.draw_line` | `x1, y1, x2, y2, color_idx` | - |
|
||||
| `0x1004` | `gfx.draw_circle` | `xc, yc, r, color_idx` | - |
|
||||
| `0x1005` | `gfx.draw_disc` | `xc, yc, r, b_col, f_col` | - |
|
||||
| `0x1006` | `gfx.draw_square` | `x, y, w, h, b_col, f_col` | - |
|
||||
| `0x2001` | `input.get_pad` | `button_id` | `bool` |
|
||||
| `0x3001` | `audio.play` | `s_id, v_id, vol, pan, pitch`| - |
|
||||
|
||||
**Button IDs:**
|
||||
- `0`: Up, `1`: Down, `2`: Left, `3`: Right
|
||||
- `4`: A, `5`: B, `6`: X, `7`: Y
|
||||
- `8`: L, `9`: R
|
||||
- `10`: Start, `11`: Select
|
||||
|
||||
---
|
||||
|
||||
## 7. Execution Errors
|
||||
|
||||
Errors are:
|
||||
|
||||
* explicit
|
||||
* fatal
|
||||
* never silent
|
||||
|
||||
Types:
|
||||
|
||||
* stack underflow
|
||||
* invalid type
|
||||
* invalid heap
|
||||
* invalid frame
|
||||
|
||||
Generate:
|
||||
|
||||
* clear message
|
||||
* state dump
|
||||
* stack trace
|
||||
|
||||
---
|
||||
|
||||
## 8. Determinism
|
||||
|
||||
Guarantees:
|
||||
|
||||
* same input → same result
|
||||
* same sequence → same cycles
|
||||
* no speculative execution
|
||||
* no invisible optimizations
|
||||
|
||||
> If you see the instruction, you pay for it.
|
||||
|
||||
---
|
||||
|
||||
## 9. Relationship with Languages
|
||||
|
||||
Java, TypeScript, Lua etc:
|
||||
|
||||
* are source languages
|
||||
* compiled to this bytecode
|
||||
* never executed directly
|
||||
|
||||
All run on the **same VM**.
|
||||
|
||||
---
|
||||
|
||||
## 10. Example
|
||||
|
||||
Source:
|
||||
|
||||
```java
|
||||
x = 3 + 4;
|
||||
```
|
||||
|
||||
Bytecode:
|
||||
|
||||
```
|
||||
PUSH_CONST 3
|
||||
PUSH_CONST 4
|
||||
ADD
|
||||
SET_GLOBAL 0
|
||||
```
|
||||
|
||||
Cost:
|
||||
|
||||
```
|
||||
2 + 2 + 2 + 3 = 9 cycles
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Execution per Tick
|
||||
|
||||
The VM does not run infinitely.
|
||||
|
||||
It executes:
|
||||
|
||||
* until consuming the **logical frame** budget
|
||||
* or until `HALT`
|
||||
|
||||
The budget is defined by the PROMETEU logical hardware (e.g., `CYCLES_PER_FRAME`).
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
vm.step_budget(10_000)
|
||||
```
|
||||
|
||||
This feeds:
|
||||
|
||||
* CAP
|
||||
* profiling
|
||||
* certification
|
||||
|
||||
---
|
||||
|
||||
## 12. Logical Frame and `FRAME_SYNC`
|
||||
|
||||
PROMETEU defines **logical frame** as the minimum unit of consistent game update.
|
||||
|
||||
* **Input is latched per logical frame** (does not change until the logical frame is completed).
|
||||
* The **cycle budget** is applied to the logical frame.
|
||||
* A new logical frame only starts when the current frame ends.
|
||||
|
||||
### 12.1 System Instruction: `FRAME_SYNC`
|
||||
|
||||
The `FRAME_SYNC` instruction marks the **end of the logical frame**.
|
||||
|
||||
| Instruction | Cycles | Description |
|
||||
| ------------ | ------ | ---------------------------------- |
|
||||
| `FRAME_SYNC` | 1 | Finalizes the current logical frame |
|
||||
|
||||
Properties:
|
||||
|
||||
* `FRAME_SYNC` is a **system instruction**.
|
||||
* It should not be exposed as a "manual" API to the user.
|
||||
* Tooling/compiler can **inject** `FRAME_SYNC` automatically at the end of the main loop.
|
||||
|
||||
### 12.2 Semantics (what happens when it executes)
|
||||
|
||||
When executing `FRAME_SYNC`, the core:
|
||||
|
||||
1. **Finalizes** the current logical frame.
|
||||
2. **Presents** the frame (`gfx.present()` or `gfx.compose_and_present()` depending on the GFX model).
|
||||
3. **Releases** the input latch.
|
||||
4. **Resets** the budget for the next logical frame.
|
||||
|
||||
### 12.3 Overbudget (when the frame doesn't finish on time)
|
||||
|
||||
If the logical frame budget runs out **before** the VM reaches `FRAME_SYNC`:
|
||||
|
||||
* the VM **pauses** (PC and stacks remain at the exact point)
|
||||
* there is **no present**
|
||||
* the input latch is **maintained**
|
||||
* on the next host tick, the VM **continues** from where it left off, still in the same logical frame
|
||||
|
||||
Practical effect:
|
||||
|
||||
* if the code needs 2 budgets to reach `FRAME_SYNC`, the game updates at ~30 FPS (logical frame takes 2 ticks)
|
||||
* this is deterministic and reportable in the CAP
|
||||
|
||||
---
|
||||
|
||||
## 15. Extensibility
|
||||
|
||||
The Instruction Set is versioned.
|
||||
|
||||
Future:
|
||||
|
||||
* DMA
|
||||
* streaming
|
||||
* vectors
|
||||
* fictitious coprocessors
|
||||
|
||||
No existing instruction changes its meaning.
|
||||
|
||||
---
|
||||
|
||||
## 16. Summary
|
||||
|
||||
* stack-based VM
|
||||
* explicit cost
|
||||
* deterministic execution
|
||||
* integrated with CAP
|
||||
* foundation of every PROMETEU cartridge
|
||||
|
||||
< [Back](chapter-1.md) | [Summary](table-of-contents.md) | [Next](chapter-3.md) >
|
||||
@@ -0,0 +1,309 @@
|
||||
< [Back](chapter-2.md) | [Summary](table-of-contents.md) | [Next](chapter-4.md) >
|
||||
|
||||
# 🧠 **Memory: Stack, Heap, and Allocation**
|
||||
|
||||
## 1. Overview
|
||||
|
||||
PROMETEU treats **memory as an explicit resource**.
|
||||
|
||||
Nothing is allocated "for convenience".
|
||||
|
||||
Nothing grows "automatically".
|
||||
|
||||
Nothing is invisible.
|
||||
|
||||
This chapter defines:
|
||||
|
||||
- the **memory spaces** of the PROMETEU VM
|
||||
- how **Stack** and **Heap** work
|
||||
- the cost and consequences of **dynamic allocation**
|
||||
- how memory relates to **CAP and certification**
|
||||
|
||||
---
|
||||
|
||||
## 2. PROMETEU VM Memory Spaces
|
||||
|
||||
The PROMETEU VM memory is divided into regions with clear responsibilities:
|
||||
|
||||
```
|
||||
+---------------------------+
|
||||
|Constant Pool |
|
||||
+---------------------------+
|
||||
|Global Space |
|
||||
+---------------------------+
|
||||
|Call Stack |
|
||||
| (Frames + Locals) |
|
||||
+---------------------------+
|
||||
| Operand Stack |
|
||||
+---------------------------+
|
||||
| Heap |
|
||||
+---------------------------+
|
||||
|
||||
```
|
||||
|
||||
Each region:
|
||||
|
||||
- has its own semantics
|
||||
- has defined limits
|
||||
- has a direct impact on execution cost
|
||||
|
||||
---
|
||||
|
||||
## 3. Operand Stack
|
||||
|
||||
### 3.1 Definition
|
||||
|
||||
The **Operand Stack** is used for:
|
||||
|
||||
- passing operands between instructions
|
||||
- intermediate results
|
||||
- expression evaluation
|
||||
|
||||
It is:
|
||||
|
||||
- **LIFO**
|
||||
- automatically growing within the frame
|
||||
- **reset** between frames (except explicitly persisted values)
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Characteristics
|
||||
|
||||
- does not store complex structures
|
||||
- stores primitive values or references
|
||||
- overflow or underflow are **fatal errors**
|
||||
|
||||
> The operand stack is cheap, fast, and temporary.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 4. Call Stack
|
||||
|
||||
### 4.1 Execution Frames
|
||||
|
||||
Each function call creates a **Call Frame**, containing:
|
||||
|
||||
- local variables
|
||||
- parameters
|
||||
- return address
|
||||
- execution context
|
||||
|
||||
Frames are created with:
|
||||
|
||||
```
|
||||
PUSH_FRAME n
|
||||
```
|
||||
|
||||
And destroyed with:
|
||||
|
||||
```
|
||||
POP_FRAME
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Costs and Limits
|
||||
|
||||
- frame creation has an explicit cost
|
||||
- maximum stack depth is limited
|
||||
- deep recursion is discouraged
|
||||
|
||||
PROMETEU favors:
|
||||
|
||||
- iteration
|
||||
- explicit state
|
||||
- conscious depth control
|
||||
|
||||
---
|
||||
|
||||
## 5. Global Space
|
||||
|
||||
### 5.1 Definition
|
||||
|
||||
The **Global Space** stores:
|
||||
|
||||
- global variables
|
||||
- persistent game state
|
||||
- long-term references
|
||||
|
||||
Globals:
|
||||
|
||||
- survive between frames
|
||||
- occupy memory permanently
|
||||
- count towards total memory usage
|
||||
|
||||
---
|
||||
|
||||
### 5.2 Conscious usage
|
||||
|
||||
PROMETEU encourages:
|
||||
|
||||
- few globals
|
||||
- compact structures
|
||||
- explicit initialization
|
||||
|
||||
Globals are equivalent to **static RAM** in microcontrollers.
|
||||
|
||||
---
|
||||
|
||||
## 6. Heap
|
||||
|
||||
### 6.1 Definition
|
||||
|
||||
The **Heap** is the dynamic memory region of the PROMETEU VM.
|
||||
|
||||
It is used for:
|
||||
|
||||
- objects
|
||||
- arrays
|
||||
- tables
|
||||
- composite structures
|
||||
|
||||
Every allocation on the heap is done explicitly with:
|
||||
|
||||
```
|
||||
ALLOC size
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6.2 Allocation Costs
|
||||
|
||||
Allocating memory:
|
||||
|
||||
- consumes **cycles**
|
||||
- consumes **available heap**
|
||||
- increases pressure on the system
|
||||
|
||||
PROMETEU treats allocation as an **expensive operation by definition**.
|
||||
|
||||
> Allocation is an architectural decision, not a detail.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 7. Heap Limits
|
||||
|
||||
### 7.1 Finite Heap
|
||||
|
||||
The heap:
|
||||
|
||||
- has a defined maximum size
|
||||
- can vary according to the active CAP
|
||||
- never grows dynamically
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
Heap Limit:32KB
|
||||
Heap Used:28KB
|
||||
```
|
||||
|
||||
Exceeding the limit:
|
||||
|
||||
- does not crash the game
|
||||
- generates an execution error
|
||||
- appears in the certification report
|
||||
|
||||
---
|
||||
|
||||
### 7.2 Heap and CAP
|
||||
|
||||
During a JAM or evaluation:
|
||||
|
||||
- heap peak is measured
|
||||
- the value is compared to the CAP limit
|
||||
- non-compliances are recorded
|
||||
|
||||
The game **continues running**, but the evidence is recorded.
|
||||
|
||||
---
|
||||
|
||||
## 8. Garbage Collection (GC)
|
||||
|
||||
### 8.1 Existence of GC
|
||||
|
||||
PROMETEU may use **simple Garbage Collection**, with the following properties:
|
||||
|
||||
- non-incremental (v0.1)
|
||||
- explicit cost
|
||||
- observable pauses
|
||||
- documented behavior
|
||||
|
||||
GC **is not invisible**.
|
||||
|
||||
---
|
||||
|
||||
### 8.2 GC Cost
|
||||
|
||||
When GC occurs:
|
||||
|
||||
- cycles are consumed
|
||||
- the frame may be impacted
|
||||
- the event is recorded
|
||||
|
||||
PROMETEU teaches:
|
||||
|
||||
> "Creating garbage has a cost."
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 9. Memory Best Practices
|
||||
|
||||
PROMETEU explicitly encourages:
|
||||
|
||||
- structure reuse
|
||||
- allocation outside the main loop
|
||||
- persistent buffers
|
||||
- pooling manual
|
||||
|
||||
And discourages:
|
||||
|
||||
- per-frame allocation
|
||||
- disposable temporary structures
|
||||
- unplanned growth
|
||||
|
||||
---
|
||||
|
||||
## 10. Relationship with Microcontrollers
|
||||
|
||||
The PROMETEU memory model is intentionally similar to real MCUs:
|
||||
|
||||
| MCU | PROMETEU |
|
||||
| --- | --- |
|
||||
| Static RAM | Global Space |
|
||||
| Stack | Call Stack |
|
||||
| Heap | Heap |
|
||||
| Allocation failure | Explicit error |
|
||||
| Fragmentation | Dev's responsibility |
|
||||
|
||||
This creates a direct transfer of learning.
|
||||
|
||||
---
|
||||
|
||||
## 11. Pedagogical Implications
|
||||
|
||||
This model allows teaching:
|
||||
|
||||
- the difference between stack and heap
|
||||
- allocation cost
|
||||
- data lifetime
|
||||
- architectural impact of simple decisions
|
||||
- the relationship between memory and time
|
||||
|
||||
Everything with **immediate and visible feedback**.
|
||||
|
||||
---
|
||||
|
||||
## 12. Summary
|
||||
|
||||
- PROMETEU has well-defined memory spaces
|
||||
- stack is temporary and cheap
|
||||
- heap is finite and expensive
|
||||
- allocation has an explicit cost
|
||||
- GC is visible and measurable
|
||||
- memory participates in certification
|
||||
|
||||
< [Back](chapter-2.md) | [Summary](table-of-contents.md) | [Next](chapter-4.md) >
|
||||
@@ -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) >
|
||||
@@ -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) >
|
||||
@@ -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) >
|
||||
@@ -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) >
|
||||
@@ -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) >
|
||||
@@ -0,0 +1,289 @@
|
||||
< [Back](chapter-8.md) | [Summary](table-of-contents.md) | [Next](chapter-10.md) >
|
||||
|
||||
# ⚡ **Events and Interrupts**
|
||||
|
||||
## 1. Overview
|
||||
|
||||
PROMETEU clearly distinguishes between **normal execution**, **events**, and **interrupts**.
|
||||
|
||||
Nothing occurs "out of time".
|
||||
|
||||
Nothing interrupts the system without cost.
|
||||
|
||||
Nothing happens without a well-defined point in the execution cycle.
|
||||
|
||||
> Events are signals.
|
||||
> Interrupts are machine decisions.
|
||||
>
|
||||
|
||||
This chapter defines:
|
||||
|
||||
- what PROMETEU considers an event
|
||||
- how interrupts are modeled
|
||||
- when they can occur
|
||||
- how they relate to cycles, CAP, and determinism
|
||||
|
||||
---
|
||||
|
||||
## 2. Event Philosophy in PROMETEU
|
||||
|
||||
PROMETEU **does not use invisible asynchronous callbacks**.
|
||||
|
||||
Every event:
|
||||
|
||||
- is registered
|
||||
- is delivered at a predictable moment
|
||||
- is handled within the main loop
|
||||
|
||||
This model avoids:
|
||||
|
||||
- implicit concurrency
|
||||
- hidden race conditions
|
||||
- non-deterministic side effects
|
||||
|
||||
PROMETEU favors:
|
||||
|
||||
> explicit control over reactivity.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 3. Events
|
||||
|
||||
### 3.1 Definition
|
||||
|
||||
An **event** in PROMETEU is a **logical signal** generated by the system or the program, indicating that something has occurred.
|
||||
|
||||
Examples of events:
|
||||
|
||||
- end of frame
|
||||
- timer expired
|
||||
- system state change
|
||||
- execution error
|
||||
|
||||
Events **do not execute code automatically**.
|
||||
|
||||
They only **inform**.
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Event Queue
|
||||
|
||||
PROMETEU maintains an **event queue**:
|
||||
|
||||
- events are queued
|
||||
- the queue is processed in order
|
||||
- processing occurs at defined points in the frame
|
||||
|
||||
Events:
|
||||
|
||||
- do not interrupt execution arbitrarily
|
||||
- do not execute outside the loop
|
||||
|
||||
---
|
||||
|
||||
## 4. Interrupts
|
||||
|
||||
### 4.1 Definition
|
||||
|
||||
An **interrupt** is a special event, treated by the system as **priority**, which can:
|
||||
|
||||
- change the normal flow of execution
|
||||
- execute specific system code
|
||||
- impact cycles and budget
|
||||
|
||||
Interrupts are **rare and explicit**.
|
||||
|
||||
---
|
||||
|
||||
### 4.2 What is NOT an interrupt
|
||||
|
||||
In PROMETEU, the following are **not interrupts**:
|
||||
|
||||
- button input
|
||||
- collisions
|
||||
- common timers
|
||||
- game logic
|
||||
|
||||
These are treated as **state or normal events**.
|
||||
|
||||
---
|
||||
|
||||
## 5. Types of Interrupts in PROMETEU
|
||||
|
||||
PROMETEU defines a small and well-controlled set of interrupts.
|
||||
|
||||
### 5.1 Frame Interrupt (Conceptual VBlank)
|
||||
|
||||
The end of each frame generates a **logical synchronization interrupt**, responsible for:
|
||||
|
||||
- framebuffer swap
|
||||
- audio commit
|
||||
- state synchronization
|
||||
|
||||
This interrupt:
|
||||
|
||||
- occurs at SYNC
|
||||
- has a fixed cost
|
||||
- does not execute user code
|
||||
|
||||
---
|
||||
|
||||
### 5.2 System Interrupt
|
||||
|
||||
Generated by exceptional conditions:
|
||||
|
||||
- fatal VM error
|
||||
- memory violation
|
||||
- invalid instruction
|
||||
|
||||
Result:
|
||||
|
||||
- execution is halted
|
||||
- VM state is preserved
|
||||
- detailed report is generated
|
||||
|
||||
---
|
||||
|
||||
### 5.3 Timed Interrupts (Timers)
|
||||
|
||||
PROMETEU can offer **system timers**, modeled as:
|
||||
|
||||
- counters based on frames
|
||||
- signals generated upon reaching zero
|
||||
|
||||
Timers:
|
||||
|
||||
- do not trigger code automatically
|
||||
- generate queryable events
|
||||
|
||||
Conceptual example:
|
||||
|
||||
```
|
||||
if (timer.expired(T1)) {
|
||||
// handle event
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Relationship between Events, Interrupts, and the Loop
|
||||
|
||||
The complete flow can be represented as follows:
|
||||
|
||||
```
|
||||
FRAME N
|
||||
──────────────
|
||||
SAMPLEINPUT
|
||||
PROCESS EVENTS
|
||||
UPDATE
|
||||
DRAW
|
||||
AUDIO
|
||||
INTERRUPT: VBLANK
|
||||
SYNC
|
||||
──────────────
|
||||
```
|
||||
|
||||
Important:
|
||||
|
||||
- events are processed before main logic
|
||||
- interrupts occur only at safe points
|
||||
- no interrupt occurs "in the middle" of an instruction
|
||||
|
||||
---
|
||||
|
||||
## 7. Costs and Budget
|
||||
|
||||
Events and interrupts:
|
||||
|
||||
- consume cycles
|
||||
- participate in the CAP
|
||||
- appear in certification
|
||||
|
||||
Example report:
|
||||
|
||||
```
|
||||
Frame 18231:
|
||||
Event processing:120cycles
|
||||
VBlank interrupt:80cycles
|
||||
```
|
||||
|
||||
Nothing is free.
|
||||
|
||||
---
|
||||
|
||||
## 8. Determinism and Reproducibility
|
||||
|
||||
PROMETEU guarantees:
|
||||
|
||||
- same sequence of events → same behavior
|
||||
- interrupts always at the same point in the frame
|
||||
- timers based on frame count, not real time
|
||||
|
||||
This allows:
|
||||
|
||||
- reliable replays
|
||||
- precise debugging
|
||||
- fair certification
|
||||
|
||||
---
|
||||
|
||||
## 9. Best Practices
|
||||
|
||||
PROMETEU encourages:
|
||||
|
||||
- treating events as data
|
||||
- querying events explicitly
|
||||
- avoiding heavy logic in handlers
|
||||
- using timers instead of excessive polling
|
||||
|
||||
PROMETEU discourages:
|
||||
|
||||
- simulating asynchronous callbacks
|
||||
- depending on implicit order
|
||||
- using events as a "shortcut" for complex logic
|
||||
|
||||
---
|
||||
|
||||
## 10. Relationship with Microcontrollers
|
||||
|
||||
The model reflects real MCUs:
|
||||
|
||||
| MCU | PROMETEU |
|
||||
| --- | --- |
|
||||
| ISR | Explicit interrupt |
|
||||
| Main Loop | PROMETEU Loop |
|
||||
| Flags | Events |
|
||||
| Timers | Per-frame timers |
|
||||
|
||||
But without:
|
||||
|
||||
- real concurrency
|
||||
- unpredictable interrupts
|
||||
|
||||
PROMETEU **teaches the concept**, not the chaos.
|
||||
|
||||
---
|
||||
|
||||
## 11. Pedagogical Implications
|
||||
|
||||
This model allows teaching:
|
||||
|
||||
- the difference between event and interrupt
|
||||
- safe synchronization
|
||||
- flow control in reactive systems
|
||||
- the impact of temporal decisions
|
||||
|
||||
Everything with **order, clarity, and measurement**.
|
||||
|
||||
---
|
||||
|
||||
## 12. Summary
|
||||
|
||||
- events inform, they do not execute
|
||||
- interrupts are rare and controlled
|
||||
- no execution occurs outside the loop
|
||||
- costs are explicit
|
||||
- behavior is deterministic
|
||||
|
||||
< [Back](chapter-8.md) | [Summary](table-of-contents.md) | [Next](chapter-10.md) >
|
||||
@@ -0,0 +1,20 @@
|
||||
# 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)
|
||||
|
||||
---
|
||||
[Back to README](../README.md)
|
||||
Reference in New Issue
Block a user