Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests Activity

improve v0.1, and add docs

Browse Source
This commit is contained in:
Nilton Constantino 2026-01-12 18:37:53 +00:00
parent 41c93fa0a3
commit 552fa4e187
No known key found for this signature in database
17 changed files with 3590 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
crates/core/src/color.rs
View File

@ -18,6 +18,10 @@ impl Color {
Self((r5 << 11) | (g6 << 5) | b5) Self((r5 << 11) | (g6 << 5) | b5)
} }
pub const fn gray_scale(c: u8) -> Self {
Self::rgb(c, c, c)
}
pub const fn from_raw(raw: u16) -> Self { pub const fn from_raw(raw: u16) -> Self {
Self(raw) Self(raw)
} }

15
crates/core/src/machine.rs
View File

@ -1,8 +1,8 @@
use crate::peripherals::{Gfx, InputSignals, Pad, Touch}; use crate::peripherals::{BlendMode, Gfx, InputSignals, Pad, Touch};
use crate::Color; use crate::Color;
/// PROMETEU "hardware lógico" (v0). /// PROMETEU "hardware lógico" (v0).
/// O Host alimenta INPUT/TOUCH e chama `step_frame()` em 60Hz. /// O Host alimenta INPUT SIGNALS e chama `step_frame()` em 60Hz.
pub struct Machine { pub struct Machine {
pub gfx: Gfx, pub gfx: Gfx,
pub pad: Pad, pub pad: Pad,
@ -54,7 +54,10 @@ impl Machine {
Color::rgb(0xFF, 0x40, 0x40) Color::rgb(0xFF, 0x40, 0x40)
}; };
self.gfx.fill_rect(x, y, 24, 24, color); // game
self.gfx.fill_rect(x, y, 20, 20, color);
// smoke
self.gfx.fill_rect_blend(140, 0, 40, 180, Color::gray_scale(0x88), BlendMode::Half)
} }
/// Final do frame: troca buffers. /// Final do frame: troca buffers.
@ -63,8 +66,8 @@ impl Machine {
} }
fn demo_pos(&self) -> (i32, i32) { fn demo_pos(&self) -> (i32, i32) {
let t = (self.frame_index % 280) as i32; let x = (self.frame_index % 300) as i32;
let z = (self.pad.a.hold_frames % 140) as i32; let y = (self.pad.a.hold_frames % 160) as i32;
(20 + t, z) (x, y)
} }
} }

1
crates/core/src/peripherals/mod.rs
View File

@ -4,6 +4,7 @@ mod touch;
mod input_signal; mod input_signal;
pub use gfx::Gfx; pub use gfx::Gfx;
pub use gfx::BlendMode;
pub use input_signal::InputSignals; pub use input_signal::InputSignals;
pub use pad::Pad; pub use pad::Pad;
pub use touch::Touch; pub use touch::Touch;

12
crates/host_desktop/src/main.rs
View File

@ -29,7 +29,7 @@ struct PrometeuApp {
input_signals: InputSignals, input_signals: InputSignals,
frame_dt: Duration, frame_target_dt: Duration,
next_frame: Instant, next_frame: Instant,
} }
@ -38,10 +38,12 @@ impl PrometeuApp {
Self { Self {
window: None, window: None,
pixels: None, pixels: None,
input_signals: InputSignals::default(),
machine: Machine::new(), machine: Machine::new(),
frame_dt: Duration::from_nanos(1_000_000_000 / 60), input_signals: InputSignals::default(),
frame_target_dt: Duration::from_nanos(1_000_000_000 / 60),
next_frame: Instant::now(), next_frame: Instant::now(),
} }
} }
@ -67,7 +69,7 @@ impl PrometeuApp {
} }
} }
impl ApplicationHandler for PrometeuApp { impl ApplicationHandler for PrometeuApp {
fn resumed(&mut self, event_loop: &ActiveEventLoop) { fn resumed(&mut self, event_loop: &ActiveEventLoop) {
let attrs = WindowAttributes::default() let attrs = WindowAttributes::default()
.with_title("PROMETEU - host_desktop") .with_title("PROMETEU - host_desktop")
@ -181,7 +183,7 @@ impl ApplicationHandler for PrometeuApp {
let now = Instant::now(); let now = Instant::now();
if now >= self.next_frame { if now >= self.next_frame {
self.next_frame += self.frame_dt; self.next_frame += self.frame_target_dt;
// executa 1 frame do PROMETEU // executa 1 frame do PROMETEU
self.machine.step_frame(&self.input_signals); self.machine.step_frame(&self.input_signals);

299
docs/README.md Normal file
View File

@ -0,0 +1,299 @@
# 📜 Prometeu — O Fogo e a Promessa
**PROMETEU** é um console imaginário.
Mas não no sentido fraco de “imaginar”.
PROMETEU foi **deliberadamente projetado** para existir como um **modelo computacional completo**: simples o bastante para ser entendido, e poderoso o suficiente para criar jogos reais.
O nome PROMETEU carrega dois significados intencionais:
- **Prometeu, o titã**, que roubou o fogo dos deuses e entregou aos humanos
- **“Prometeu” como verbo**, uma promessa feita
Neste projeto:
- o *fogo* é o conhecimento de como computadores realmente funcionam
- a *promessa* é que nada é mágico, nada é escondido, e tudo pode ser compreendido
Este manual é essa promessa escrita.
---
## 🎯 O que é o PROMETEU
PROMETEU é um **Virtual Microconsole** — um computador fictício, com regras claras, recursos limitados e comportamento determinístico.
Ele foi projetado para:
- ensinar fundamentos reais de computação
- expor tempo, memória e execução
- permitir jogos 2D completos (plataformers, metroidvanias, arcade)
- servir como ponte entre:
- microcontroladores
- consoles clássicos
- máquinas virtuais
- engines modernas
PROMETEU **não é**:
- uma engine genérica
- um substituto de Unity ou Godot
- um console comercial real
PROMETEU **é**:
- um laboratório
- um instrumento didático
- um brinquedo sério
---
## 🧠 Modelo Mental Fundamental
> PROMETEU é um microcontrolador que desenha pixels, toca som e lida com inputs do jogador.
>
Tudo no sistema deriva disso.
### Equivalência conceitual
| Microcontrolador real | PROMETEU |
| --- | --- |
| Clock | Tick da VM |
| Flash | Cartucho PROMETEU |
| RAM | Heap + Stack |
| GPIO | Input |
| DMA | Transferência gráfica |
| ISR | Eventos do sistema |
| Periféricos | GFX, AUDIO, INPUT, FS |
Se você entende um MCU, você entende PROMETEU.
---
## 🧩 Filosofia de Design
### 1. Simplicidade visível
- Cada operação tem custo
- Cada frame tem orçamento
- Cada erro tem causa observável
Nada acontece “porque sim”.
### 2. Determinismo
- Mesmo cartucho
- Mesma entrada
- Mesmo resultado
Independente da plataforma.
### 3. Limitação como ferramenta pedagógica
PROMETEU impõe limites **intencionais**:
- memória finita
- tempo por frame
- recursos gráficos limitados
Limites ensinam design.
### 4. Profundidade progressiva
PROMETEU pode ser explorado em camadas:
1. **Camada Jogo** — `update()` e `draw()`
2. **Camada Sistema** — bytecode, stack, heap
3. **Camada Máquina** — ciclos, eventos, periféricos
O aluno decide até onde descer.
## 🏗️ Arquitetura Geral
```
+---------------------------+
| CARTUCHO |
| (bytecodeX + assets) |
+-------------+-------------+
|
+-------------v-------------+
| PROMETEU VM |
| (stack-based, |
| determinística) |
+-------------+-------------+
|
+-------------v-------------+
| PERIFÉRICOS VIRTUAIS |
| GFX | AUDIO |INPUT | FS| |
+-------------+-------------+
|
+-------------v-------------+
| CAMADA DE PLATAFORMA |
| PC | SteamOS | Android |
| iOS | Consoles (futuro) |
+---------------------------+
```
Este manual descreve **a máquina PROMETEU**, não ferramentas externas.
---
## 📦 O Cartucho PROMETEU
Um **cartucho PROMETEU** é um pacote imutável, equivalente a firmware.
Conteúdo típico:
- `program.pbx` — bytecode PROMETEU (bytecodeX)
- `assets/` — gráficos, áudio, mapas
- `manifest.json` — metadados e configuração
O cartucho:
- sempre pode ser executado
- sempre pode ser distribuído
- nunca é bloqueado pelo sistema
---
## 🧪 Linguagens de Programação
PROMETEU **não executa linguagens de alto nível diretamente**.
As linguagens são **fontes**, compiladas para bytecode PROMETEU.
### Linguagens planejadas
- **Java (subset)** — arquitetura, ensino profundo
- **TypeScript (subset)** — acessibilidade e mercado
- **Lua (subset)** — scripting clássico e leve
Todas convergem para:
> O mesmo bytecode. A mesma VM. O mesmo comportamento.
>
---
## 🔄 Modelo de Execução
PROMETEU executa em um loop fixo:
```
BOOT
↓
LOAD CARTUCHO
↓
INIT
↓
LOOP (60 Hz):
├─INPUT
├─UPDATE
├─ DRAW
├─ AUDIO
└─ SYNC
```
- Frequência padrão: **60 Hz**
- Cada iteração corresponde a **um frame**
- O tempo de execução é **mensurável**
---
## ⏱️ CAP — Execution Cap (Orçamento de Execução)
### Definição
O **CAP** define um orçamento de execução (tempo, memória e recursos) **em um contexto específico**, como uma Game Jam ou avaliação.
> CAP nunca bloqueia execução.
CAP nunca bloqueia empacotamento.
CAP nunca impede o jogo de ser jogado.
>
---
### Quando o CAP é usado
- Game Jams PROMETEU
- Avaliações acadêmicas
- Desafios técnicos
- Comparações entre soluções
Fora desses contextos, PROMETEU opera em **modo livre**.
---
### O papel do CAP
O CAP serve para:
- orientar decisões técnicas
- fornecer feedback mensurável
- gerar **certificações técnicas**
- criar critérios objetivos de avaliação
PROMETEU **ajuda durante o desenvolvimento**:
- indicadores visuais
- alertas de custo
- profiling por frame
---
## 📄 Certificação PROMETEU
### O que é
A **Certificação PROMETEU** é um relatório técnico gerado a partir da execução do jogo sob um CAP definido.
Ela:
- **não impede** o jogo
- **não invalida** a entrega
- **registra evidências técnicas**
---
### Exemplo de relatório
```
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
```
O relatório **acompanha o jogo**.
---
## 🎓 Uso Educacional
A avaliação pode considerar:
- Qualidade do jogo (criatividade, design)
- Qualidade técnica (certificação)
- Decisões arquiteturais justificadas
- Evolução entre versões
PROMETEU avalia **processo**, não apenas resultado.
< [Sumário](topics/table-of-contens.md) >

254
docs/topics/chapter-1.md Normal file
View File

@ -0,0 +1,254 @@
[Sumário](../table-of-contens.md) | [Adiante](chapter-2.md) >
# ⏱️ **Modelo de Tempo e Ciclos**
# 1. Visão Geral
PROMETEU é um sistema **orientado a tempo**.
Nada acontece “instantaneamente”.
Toda ação consome **tempo mensurável**, expresso em **ciclos de execução**.
Este capítulo define:
- o **clock base** do sistema
- o conceito de **ciclo PROMETEU**
- como o tempo é distribuído ao longo dos frames
- como o **CAP (Execution Cap)** se relaciona com esse modelo
---
## 2. Clock Base do Sistema
PROMETEU opera com um **clock fixo de 60 Hz**.
Isso significa:
- 60 iterações do loop principal por segundo
- cada iteração corresponde a **um frame**
- o clock é **determinístico e estável**, independente da plataforma
> O clock define o ritmo da máquina,
não a quantidade de trabalho obrigatório por frame.
>
---
## 3. O Frame PROMETEU
Um **frame PROMETEU** representa uma unidade completa de execução.
Cada frame executa, conceitualmente, as seguintes etapas:
```
FRAME N
──────────────
INPUT
UPDATE
DRAW
AUDIO
SYNC
──────────────
```
O sistema garante:
- ordem fixa
- repetição previsível
- ausência de frames “fantasmas”
---
## 4. Ciclos PROMETEU
### 4.1 Definição
Um **ciclo PROMETEU** é a menor unidade abstrata de tempo do sistema.
- cada instrução da VM consome um número fixo de ciclos
- chamadas de periféricos também possuem custo
- o custo é **documentado e estável**
Ciclos são:
- **contáveis**
- **comparáveis**
- **independentes de hardware real**
---
### 4.2 Por que ciclos, e não milissegundos?
PROMETEU não mede tempo em milissegundos porque:
- milissegundos variam entre plataformas
- clocks reais diferem
- jitter e latência escondem custo real
Ciclos permitem afirmar:
> “Este programa é mais caro que aquele,
>
>
> independentemente de onde ele rode.”
>
---
## 5. Orçamento por Frame
Cada frame possui um **orçamento máximo de ciclos**.
Esse orçamento:
- é resetado a cada frame
- não acumula ciclos não utilizados
- representa a capacidade da “CPU virtual”
### Exemplo conceitual
```
Frame Budget:10,000cycles
Used:
-Update logic:4,200
-Draw calls:3,100
-Audio:900
Remaining:
1,800cycles
```
---
## 6. Separação entre Clock e Trabalho
PROMETEU **não exige** que toda lógica rode a cada frame.
O programador é **explicitamente encorajado** a distribuir trabalho no tempo.
### Exemplos comuns
- lógica de inimigos a cada 2 frames (30 Hz)
- pathfinding a cada 4 frames (15 Hz)
- animações independentes da AI
- timers baseados em contagem de frames
Isso reflete práticas reais de:
- consoles clássicos
- sistemas embarcados
- firmware de microcontroladores
> Nem tudo precisa acontecer agora.
>
---
## 7. Distribuição Temporal como Arquitetura
PROMETEU trata **distribuição de trabalho no tempo** como uma decisão arquitetural.
Isso significa que:
- código que roda todo frame é mais caro
- código distribuído é mais eficiente
- otimização é, antes de tudo, **organização temporal**
PROMETEU ensina:
> desempenho não vem só de “menos código”,
>
>
> mas de **quando** o código roda.
>
---
## 8. Execution CAP (Orçamento Contextual)
### 8.1 O que é o CAP
O **CAP** define um conjunto de limites técnicos associados a um **contexto específico**, como:
- Game Jams
- avaliações acadêmicas
- desafios técnicos
O CAP pode definir:
- orçamento máximo de ciclos por frame
- limite de memória
- limites de chamadas de periféricos
---
### 8.2 CAP não bloqueia execução
Regras fundamentais:
- o jogo **sempre roda**
- o jogo **sempre pode ser empacotado**
- o jogo **sempre pode ser jogado**
O CAP **nunca impede** execução.
---
### 8.3 CAP gera evidência, não punição
Quando um CAP está ativo, PROMETEU:
- mede execução
- registra picos
- identifica gargalos
- gera **relatório de certificação**
Esse relatório:
- não bloqueia o jogo
- não invalida a entrega
- **documenta conformidade ou não conformidade**
---
## 9. Certificação Baseada em Tempo
A certificação PROMETEU analisa:
- uso médio de ciclos por frame
- picos máximos
- frames problemáticos
- distribuição de custo
Exemplo:
```
Target CAP:PROMETEU-LITE
Frame Budget:5,000cycles
Frame 18231:
Used:5,612cycles❌
Primary cause:
enemy.updateAI():1,012cycles
```
Essa certificação acompanha o jogo como **artefato técnico**.
---
## 10. Implicações Pedagógicas
O modelo de tempo e ciclos permite ensinar:
- planejamento de execução
- arquitetura orientada a tempo
- trade-offs técnicos
- leitura de perfis reais
[Sumário](../table-of-contens.md) | Próximo: [Next](chapter-2.md) >

350
docs/topics/chapter-10.md Normal file
View File

@ -0,0 +1,350 @@
< [Voltar](chapter-9.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-11.md) >
# 🛠️ **Debug, Inspeção e Profiling**
## 1. Visão Geral
PROMETEU foi projetado para **ser observado**.
Debug, inspeção e profiling **não são ferramentas externas opcionais** —
eles são **partes integrantes da máquina**.
Nada acontece sem deixar rastros.
Nada consome recursos sem ser medido.
Nada falha sem explicação.
> PROMETEU não esconde estado.
PROMETEU expõe comportamento.
>
---
## 2. Filosofia de Debug em PROMETEU
PROMETEU segue três princípios fundamentais de debug:
1. **Estado antes de abstração**
O programador vê a máquina antes de ver “features”.
2. **Tempo como primeira classe**
Cada ação é analisada no contexto do frame e dos ciclos.
3. **Observação não altera execução**
Debug nunca muda o comportamento do sistema.
---
## 3. Modos de Execução
PROMETEU opera em três modos principais:
### 3.1 Modo Normal
- execução contínua
- sem inspeção detalhada
- foco em jogo e experiência
---
### 3.2 Modo Debug
- execução controlada
- acesso a estado interno
- pausas e stepping
Este modo é usado para:
- aprendizado
- investigação
- correção de erros
---
### 3.3 Modo Certificação
- execução determinística
- métricas coletadas
- geração de relatório
Nenhum modo altera o resultado lógico do programa.
---
## 4. Debug de Execução
### 4.1 Pausa e Continuação
O sistema pode ser pausado em pontos seguros:
- início do frame
- antes de UPDATE
- após DRAW
- antes do SYNC
Durante pausa:
- estado é congelado
- buffers não são trocados
- tempo lógico não avança
---
### 4.2 Step-by-Step
PROMETEU permite stepping em diferentes níveis:
- **por frame**
- **por função**
- **por instrução da VM**
Stepping por instrução revela:
- Program Counter (PC)
- instrução atual
- pilha de operandos
- call stack
---
## 5. Inspeção de Estado
### 5.1 Pilhas
PROMETEU permite inspecionar:
- **Operand Stack**
- **Call Stack**
Para cada frame:
- conteúdo
- profundidade
- crescimento e limpeza
Stack overflow e underflow são imediatamente visíveis.
---
### 5.2 Heap
O heap pode ser inspecionado em tempo real:
- tamanho total
- uso atual
- pico de uso
- objetos vivos
O programador pode observar:
- padrões de alocação
- fragmentação
- pressão de GC
---
### 5.3 Espaço Global
Variáveis globais:
- valores atuais
- referências
- inicialização
Globais são visíveis como **RAM estática**.
---
## 6. Debug Gráfico
PROMETEU permite inspecionar o sistema gráfico:
- front buffer
- back buffer
- estado da paleta
- sprites ativos
É possível:
- congelar a imagem
- observar buffers separadamente
- identificar redraw excessivo
---
## 7. Profiling de Tempo (Ciclos)
### 7.1 Medição por Frame
Para cada frame, PROMETEU registra:
- ciclos totais usados
- ciclos por subsistema
- picos de execução
Exemplo conceitual:
```
Frame 18231:
Total:9,842/10,000cycles
UPDATE:4,210
DRAW:3,180
AUDIO:920
SYSTEM:612
```
---
### 7.2 Profiling por Função
PROMETEU pode associar ciclos a:
- funções
- métodos
- blocos lógicos
Isso permite responder:
> “onde o tempo está sendo gasto?”
>
---
### 7.3 Profiling por Instrução
No nível mais baixo, o sistema pode exibir:
- instruções executadas
- custo individual
- frequência
Esse nível é especialmente útil para:
- ensino de VM
- otimização profunda
- análise de bytecode
---
## 8. Profiling de Memória
PROMETEU registra:
- uso médio de heap
- pico de heap
- alocações por frame
- frequência de GC
Exemplo:
```
Heap:
Avg:24KB
Peak:34KB❌
Limit:32KB
```
Esses dados alimentam diretamente a certificação.
---
## 9. Breakpoints e Watchpoints
### 9.1 Breakpoints
PROMETEU suporta breakpoints em:
- frames específicos
- funções
- instruções da VM
Breakpoints:
- pausam execução
- preservam estado
- não alteram comportamento
---
### 9.2 Watchpoints
Watchpoints monitoram:
- variáveis
- endereços de heap
- valores específicos
A execução pode pausar quando:
- um valor muda
- um limite é ultrapassado
---
## 10. Debug de Eventos e Interrupções
PROMETEU permite observar:
- fila de eventos
- timers ativos
- interrupções ocorridas
Cada evento possui:
- origem
- frame
- custo
- consequência
Nada acontece “em silêncio”.
---
## 11. Integração com CAP e Certificação
Todos os dados de debug e profiling:
- alimentam o relatório de certificação
- são coletados de forma determinística
- não dependem de ferramentas externas
O relatório final é:
- reproduzível
- auditável
- explicável
---
## 12. Uso Pedagógico
Este sistema permite ensinar:
- como debugar sistemas reais
- como ler métricas
- como correlacionar tempo e memória
- como justificar decisões técnicas
O aluno aprende:
> debug não é tentativa e erro,
é observação informada.
>
---
## 13. Resumo
- debug é parte do sistema
- inspeção é completa
- profiling é determinístico
- tempo e memória são visíveis
- certificação é baseada em evidência
< [Voltar](chapter-9.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-11.md) >

258
docs/topics/chapter-11.md Normal file
View File

@ -0,0 +1,258 @@
< [Voltar](chapter-10.md) | [Sumário](table-of-contens.md) >
# 🌍 **Garantias de Portabilidade e Execução Multiplataforma**
## 1. Visão Geral
PROMETEU foi projetado desde o início para ser **portável por construção**, não por adaptação posterior.
Um cartucho PROMETEU:
- executa da mesma forma em qualquer plataforma suportada
- produz os mesmos resultados para as mesmas entradas
- mantém comportamento técnico previsível
> PROMETEU não depende da plataforma.
A plataforma depende do PROMETEU.
>
Este capítulo define **o contrato de portabilidade** do sistema.
---
## 2. Princípio Fundamental da Portabilidade
A portabilidade em PROMETEU se baseia em uma regra simples:
> Somente a PROMETEU VM define o comportamento do programa.
>
Isso significa:
- linguagens-fonte não importam após compilação
- hardware real não influencia lógica
- sistema operacional não altera semântica
Tudo que não pertence à VM é **adaptação**, não execução.
---
## 3. Separação de Responsabilidades
PROMETEU separa rigorosamente três camadas:
```
+----------------------------+
| CARTUCHO |
| (bytecode + assets) |
+-------------+--------------+
|
+-------------v--------------+
| PROMETEU VM |
| (lógica, tempo, memória) |
+-------------+--------------+
|
+-------------v--------------+
| CAMADA DE PLATAFORMA |
| janela, áudio,input, FS |
+----------------------------+
```
### O que a VM controla
- execução de bytecode
- tempo lógico (frames, ciclos)
- memória (stack, heap)
- determinismo
- custos e métricas
### O que a plataforma fornece
- exibição de pixels
- saída de áudio
- coleta de input físico
- acesso ao sistema de arquivos sandbox
A plataforma **nunca decide comportamento**.
---
## 4. Determinismo como Base da Portabilidade
PROMETEU garante determinismo por meio de:
- clock lógico fixo (60 Hz)
- ciclos abstratos, não tempo real
- input amostrado por frame
- ausência de concorrência implícita
- ausência de operações dependentes de sistema
Isso permite afirmar:
> “Se o cartucho é o mesmo, o jogo é o mesmo.”
>
---
## 5. Independência de Hardware Real
PROMETEU **não utiliza**:
- timers do sistema operacional
- clocks de alta resolução
- instruções específicas de CPU
- aceleração gráfica não controlada
Todo desempenho é medido em **ciclos PROMETEU**, não em milissegundos.
O hardware real:
- apenas executa a VM
- nunca interfere na semântica
---
## 6. Precisão de Ponto Flutuante
Para garantir consistência numérica:
- PROMETEU define operações matemáticas explícitas
- evita dependência de FPU específica
- padroniza comportamento de `number`
Isso evita:
- divergências entre arquiteturas
- erros acumulativos imprevisíveis
- diferenças sutis entre plataformas
---
## 7. Input Multiplataforma
PROMETEU abstrai input físico em **estado lógico**.
- teclado, gamepad e toque são mapeados externamente
- o cartucho só enxerga botões e eixos lógicos
- o momento da leitura é fixo por frame
O mesmo cartucho:
- reage da mesma forma em PC, mobile ou console
- não contém lógica dependente de dispositivo
---
## 8. Áudio Multiplataforma
O sistema de áudio:
- define canais e mixagem logicamente
- usa APIs nativas apenas como saída
- mantém sincronização por frame
Diferenças de hardware:
- não alteram timing lógico
- não alteram sequência sonora
- não afetam certificação
---
## 9. Gráficos Multiplataforma
O sistema gráfico:
- opera sobre framebuffer lógico
- usa paleta indexada
- não depende de GPU específica
A camada de plataforma:
- apenas exibe o framebuffer
- não reinterpreta comandos gráficos
PROMETEU **não delega decisões gráficas ao hardware**.
---
## 10. Sistema de Arquivos e Persistência
PROMETEU define um **filesystem lógico sandbox**:
- caminhos virtuais
- limites de tamanho
- comportamento determinístico
A plataforma mapeia esse filesystem para:
- disco
- storage móvel
- memória persistente
Sem alterar semântica.
---
## 11. Certificação e Portabilidade
A **Certificação PROMETEU** é válida para todas as plataformas.
Se um cartucho:
- passa em uma plataforma
- com as mesmas entradas
Ele:
- passará em todas
- produzirá os mesmos relatórios
Isso é possível porque:
> a certificação valida a VM, não o ambiente.
>
---
## 12. O que PROMETEU NÃO garante
PROMETEU **não promete**:
- desempenho absoluto igual (FPS real)
- latência física idêntica
- consumo energético equivalente
PROMETEU promete:
- **comportamento lógico idêntico**
- **decisões técnicas reproduzíveis**
---
## 13. Implicações Pedagógicas
Este modelo permite ensinar:
- diferença entre lógica e apresentação
- por que engines modernas quebram determinismo
- como isolar sistemas
- como projetar software portável
O aluno aprende:
> portabilidade não é sorte — é arquitetura.
>
---
## 14. Resumo
- PROMETEU define comportamento na VM
- plataformas apenas executam
- tempo é lógico, não físico
- input, áudio e gráficos são abstraídos
- certificação é universal
- portabilidade é garantida por design
< [Voltar](chapter-10.md) | [Sumário](table-of-contens.md) >

306
docs/topics/chapter-2.md Normal file
View File

@ -0,0 +1,306 @@
< [Voltar](chapter-1.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-3.md) >
# ⚙️ **PROMETEU VM Instruction Set**
## 1. Visão Geral
A **PROMETEU VM** é uma **máquina virtual stack-based**, determinística e orientada a ciclos.
Seu Instruction Set foi projetado para:
- ser **facilmente compreendido**
- mapear diretamente conceitos de linguagens de alto nível
- expor claramente custo de execução
- permitir inspeção completa da pilha e da memória
> A PROMETEU VM é intencionalmente simples.
Simplicidade é uma característica pedagógica, não uma limitação.
>
---
## 2. Modelo de Execução da VM
### 2.1 Componentes principais
A PROMETEU VM possui:
- **Program Counter (PC)** — endereço da próxima instrução
- **Operand Stack** — pilha de valores
- **Call Stack** — pilha de chamadas (frames)
- **Heap** — memória dinâmica
- **Global Space** — variáveis globais
- **Constant Pool** — literais e referências
---
### 2.2 Ciclo de execução da VM
Cada instrução segue o ciclo:
```
FETCH → DECODE →EXECUTE → ADVANCE PC
```
Cada instrução:
- consome um número fixo de **ciclos**
- tem efeitos observáveis na pilha/memória
- nunca executa trabalho implícito oculto
---
## 3. Tipos Fundamentais da VM
A PROMETEU VM suporta um conjunto **mínimo e explícito** de tipos:
| Tipo | Descrição |
| --- | --- |
| `number` | ponto flutuante (64-bit) |
| `boolean` | verdadeiro / falso |
| `string` | UTF-8 imutável |
| `null` | ausência de valor |
| `ref` | referência para heap |
> Não existem tipos implícitos, coerções mágicas ou overflows silenciosos.
>
---
## 4. Convenções da Pilha
- Operações consomem operandos **do topo da pilha**
- Resultados são empilhados
- A pilha cresce para cima
- Ordem: **último empilhado = primeiro consumido**
Exemplo:
```
PUSH3
PUSH4
ADD
```
Stack:
```
[3]
[3, 4]
[7]
```
---
## 5. Categorias de Instruções
O Instruction Set é organizado por função:
1. Controle de fluxo
2. Pilha
3. Aritmética e lógica
4. Variáveis
5. Funções
6. Heap e estruturas
7. Interação com periféricos
8. Sistema
---
## 6. Instruções da VM (v0.1)
### 6.1 Controle de Execução
| Instrução | Ciclos | Descrição |
| --- | --- | --- |
| `NOP` | 1 | Não faz nada |
| `HALT` | 1 | Encerra execução |
| `JMP addr` | 2 | Salta para endereço |
| `JMP_IF_FALSE addr` | 3 | Salta se topo da pilha for falso |
---
### 6.2 Operações de Pilha
| Instrução | Ciclos | Descrição |
| --- | --- | --- |
| `PUSH_CONST k` | 2 | Empilha constante |
| `POP` | 1 | Remove topo da pilha |
| `DUP` | 1 | Duplica topo |
| `SWAP` | 1 | Troca dois topos |
---
### 6.3 Aritmética
| Instrução | Ciclos | Descrição |
| --- | --- | --- |
| `ADD` | 2 | Soma |
| `SUB` | 2 | Subtração |
| `MUL` | 4 | Multiplicação |
| `DIV` | 6 | Divisão |
> Custos refletem complexidade relativa, não tempo real.
>
---
### 6.4 Comparações e Lógica
| Instrução | Ciclos |
| --- | --- |
| `EQ` | 2 |
| `NEQ` | 2 |
| `LT` | 2 |
| `GT` | 2 |
| `AND` | 2 |
| `OR` | 2 |
| `NOT` | 1 |
---
### 6.5 Variáveis e Escopos
| Instrução | Ciclos | Descrição |
| --- | --- | --- |
| `GET_GLOBAL idx` | 3 | Lê global |
| `SET_GLOBAL idx` | 3 | Escreve global |
| `GET_LOCAL idx` | 2 | Lê local |
| `SET_LOCAL idx` | 2 | Escreve local |
---
### 6.6 Funções e Chamadas
| Instrução | Ciclos | Descrição |
| --- | --- | --- |
| `CALL addr` | 5 | Chamada de função |
| `RET` | 4 | Retorno |
| `PUSH_FRAME n` | 3 | Cria frame local |
| `POP_FRAME` | 3 | Remove frame |
---
### 6.7 Heap e Estruturas
| Instrução | Ciclos | Descrição |
| --- | --- | --- |
| `ALLOC size` | 10 | Aloca no heap |
| `LOAD_REF off` | 3 | Lê campo |
| `STORE_REF off` | 3 | Escreve campo |
> Toda alocação tem custo explícito.
>
>
> O heap é finito e monitorado.
>
---
### 6.8 Periféricos (Chamadas Nativas)
| Instrução | Ciclos | Descrição |
| --- | --- | --- |
| `CALL_NATIVE id` | variável | Chamada ao sistema |
Exemplos:
- `gfx.sprite`
- `input.btn`
- `audio.play`
O custo depende do periférico e é **documentado separadamente**.
---
## 7. Erros de Execução
Erros são **explícitos e fatais**, nunca silenciosos:
- stack underflow
- acesso inválido ao heap
- tipo incompatível
- frame inválido
Todos geram:
- mensagem clara
- estado da VM
- stack trace
---
## 8. Determinismo e Garantias
A PROMETEU VM garante:
- mesma sequência de instruções → mesmo resultado
- mesmos ciclos → mesma certificação
- nenhuma otimização invisível
- nenhuma execução especulativa
> Se você vê a instrução, você paga por ela.
>
---
## 9. Relação com Linguagens de Alto Nível
Java, TypeScript e Lua são:
- **linguagens-fonte**
- compiladas para este Instruction Set
- nunca executadas diretamente
Diferentes linguagens:
- geram bytecode diferente
- mas executam na **mesma máquina**
---
## 10. Exemplo Completo
### Código fonte (conceitual)
```java
x =3 +4;
```
### Bytecode PROMETEU
```
PUSH_CONST3
PUSH_CONST4
ADD
SET_GLOBAL0
```
### Custo total
```
2 + 2 + 2 + 3 = 9 cycles
```
---
## 11. Extensibilidade
O Instruction Set é **versionado**.
Novas versões podem adicionar:
- instruções vetoriais
- instruções de DMA
- instruções de streaming
- coprocessadores fictícios
Nenhuma instrução existente muda de significado.
< [Voltar](chapter-1.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-3.md) >

309
docs/topics/chapter-3.md Normal file
View File

@ -0,0 +1,309 @@
< [Voltar](chapter-2.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-4.md) >
# 🧠 **Memória: Stack, Heap e Alocação**
## 1. Visão Geral
PROMETEU trata **memória como um recurso explícito**.
Nada é alocado “por conveniência”.
Nada cresce “automaticamente”.
Nada é invisível.
Este capítulo define:
- os **espaços de memória** da PROMETEU VM
- como **Stack** e **Heap** funcionam
- o custo e as consequências da **alocação dinâmica**
- como a memória se relaciona com **CAP e certificação**
---
## 2. Espaços de Memória da PROMETEU VM
A memória da PROMETEU VM é dividida em regiões com responsabilidades claras:
```
+---------------------------+
|Constant Pool |
+---------------------------+
|Global Space |
+---------------------------+
|Call Stack |
| (Frames + Locals) |
+---------------------------+
| Operand Stack |
+---------------------------+
| Heap |
+---------------------------+
```
Cada região:
- tem semântica própria
- tem limites definidos
- tem impacto direto no custo de execução
---
## 3. Operand Stack
### 3.1 Definição
A **Operand Stack** é usada para:
- passagem de operandos entre instruções
- resultados intermediários
- avaliação de expressões
Ela é:
- **LIFO**
- de crescimento automático dentro do frame
- **resetada** entre frames (exceto valores persistidos explicitamente)
---
### 3.2 Características
- não armazena estruturas complexas
- armazena valores primitivos ou referências
- overflow ou underflow são **erros fatais**
> A pilha de operandos é barata, rápida e temporária.
>
---
## 4. Call Stack (Stack de Chamadas)
### 4.1 Frames de Execução
Cada chamada de função cria um **Call Frame**, contendo:
- variáveis locais
- parâmetros
- endereço de retorno
- contexto de execução
Frames são criados com:
```
PUSH_FRAME n
```
E destruídos com:
```
POP_FRAME
```
---
### 4.2 Custos e Limites
- criação de frame tem custo explícito
- profundidade máxima de stack é limitada
- recursão profunda é desencorajada
PROMETEU favorece:
- iteração
- estado explícito
- controle consciente de profundidade
---
## 5. Global Space
### 5.1 Definição
O **Global Space** armazena:
- variáveis globais
- estado persistente do jogo
- referências de longo prazo
Globais:
- sobrevivem entre frames
- ocupam memória permanentemente
- contam para o uso total de memória
---
### 5.2 Uso consciente
PROMETEU incentiva:
- poucas globais
- estruturas compactas
- inicialização explícita
Globais são equivalentes a **RAM estática** em microcontroladores.
---
## 6. Heap
### 6.1 Definição
O **Heap** é a região de memória dinâmica da PROMETEU VM.
É usado para:
- objetos
- arrays
- tabelas
- estruturas compostas
Toda alocação no heap é feita explicitamente com:
```
ALLOC size
```
---
### 6.2 Custos da Alocação
Alocar memória:
- consome **ciclos**
- consome **heap disponível**
- aumenta pressão sobre o sistema
PROMETEU trata alocação como uma operação **cara por definição**.
> Alocar é uma decisão arquitetural, não um detalhe.
>
---
## 7. Limites de Heap
### 7.1 Heap Finito
O heap:
- tem tamanho máximo definido
- pode variar conforme o CAP ativo
- nunca cresce dinamicamente
Exemplo:
```
Heap Limit:32KB
Heap Used:28KB
```
Ultrapassar o limite:
- não trava o jogo
- gera erro de execução
- aparece no relatório de certificação
---
### 7.2 Heap e CAP
Durante uma JAM ou avaliação:
- o pico de heap é medido
- o valor é comparado ao limite do CAP
- não conformidades são registradas
O jogo **continua rodando**, mas a evidência fica registrada.
---
## 8. Garbage Collection (GC)
### 8.1 Existência do GC
PROMETEU pode utilizar **Garbage Collection simples**, com as seguintes propriedades:
- não incremental (v0.1)
- custo explícito
- pausas observáveis
- comportamento documentado
GC **não é invisível**.
---
### 8.2 Custo do GC
Quando o GC ocorre:
- ciclos são consumidos
- o frame pode sofrer impacto
- o evento é registrado
PROMETEU ensina:
> “Criar lixo tem custo.”
>
---
## 9. Boas Práticas de Memória
PROMETEU encoraja explicitamente:
- reutilização de estruturas
- alocação fora do loop principal
- buffers persistentes
- pooling manual
E desencoraja:
- alocação por frame
- estruturas temporárias descartáveis
- crescimento não planejado
---
## 10. Relação com Microcontroladores
O modelo de memória PROMETEU é intencionalmente similar a MCUs reais:
| MCU | PROMETEU |
| --- | --- |
| RAM estática | Global Space |
| Stack | Call Stack |
| Heap | Heap |
| Falha de alocação | Erro explícito |
| Fragmentação | Responsabilidade do dev |
Isso cria transferência direta de aprendizado.
---
## 11. Implicações Pedagógicas
Este modelo permite ensinar:
- diferença entre stack e heap
- custo de alocação
- lifetime de dados
- impacto arquitetural de decisões simples
- relação entre memória e tempo
Tudo com **feedback imediato e visível**.
---
## 12. Resumo
- PROMETEU possui espaços de memória bem definidos
- stack é temporária e barata
- heap é finita e cara
- alocação tem custo explícito
- GC é visível e mensurável
- memória participa da certificação
< [Voltar](chapter-2.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-4.md) >

434
docs/topics/chapter-4.md Normal file
View File

@ -0,0 +1,434 @@
< [Voltar](chapter-3.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-5.md) >
# 🎨 **Periférico GFX (Sistema Gráfico)**
## 1. Visão Geral
O periférico **GFX** é responsável pela geração de imagem no PROMETEU.
Ele modela um **hardware gráfico simples**, inspirado em consoles clássicos
(SNES, CPS-2, Neo-Geo), priorizando:
- determinismo
- baixo custo computacional
- didática
- portabilidade
O GFX **não é uma GPU moderna**.
Ele é um dispositivo explícito, baseado em:
- framebuffer
- tilemaps
- banks de tiles
- sprites por prioridade
- composição por ordem de desenho
---
## 2. Resolução e Framebuffer
### Resolução base
- **320 × 180 pixels**
- proporção próxima de 16:9
- escalável pelo host (nearest-neighbor)
### Formato de pixel
- **RGB565**
- 5 bits Red
- 6 bits Green
- 5 bits Blue
- sem canal alpha
Transparência é feita por **color key**.
---
## 3. Double Buffering
O GFX mantém dois buffers:
- **Back Buffer** — onde o frame é construído
- **Front Buffer** — onde o frame é exibido
Fluxo por frame:
1. O sistema desenha no back buffer
2. Chama `present()`
3. Buffers são trocados
4. O host exibe o front buffer
Isso garante:
- ausência de tearing
- sincronização clara por frame
- comportamento determinístico
---
## 4. Estrutura Gráfica do PROMETEU
O mundo gráfico é composto por:
- Até **16 Tile Banks**
- **4 Game Layers** (scrolláveis)
- **1 HUD Layer** (fixa, sempre por cima)
- Sprites com prioridade entre layers
### 4.1 Tile Banks
- Existem até **16 banks**
- Cada bank tem tamanho fixo de tile:
- 8×8, 16×16 ou 32×32
- Um bank é uma biblioteca de gráficos:
- ambiente
- personagens
- UI
- efeitos
### 4.2 Layers
- Existem:
- 4 Game Layers
- 1 HUD Layer
- Cada layer aponta para **um único bank**
- Sprites podem usar **qualquer bank**
- HUD:
- não scrolla
- prioridade máxima
- geralmente usa tiles 8×8
---
## 5. Modelo Interno de uma Game Layer
Uma Game Layer **não é um bitmap de pixels**.
Ela é composta por:
- Um **Tilemap lógico** (índices de tiles)
- Um **Cache de Borda** (janela de tiles visíveis)
- Um **Offset de Scroll**
### Estrutura:
- `bank_id`
- `tile_size`
- `tilemap` (matriz grande)
- `scroll_x`, `scroll_y`
- `cache_origin_x`, `cache_origin_y`
- `cache_tiles[w][h]`
---
## 6. Tilemap Lógico
O tilemap representa o mundo:
Cada célula contém:
- `tile_id`
- `flip_x`
- `flip_y`
- `priority` (opcional)
- `palette_id` (opcional)
O tilemap pode ser muito maior que a tela.
---
## 7. Cache de Borda (Tile Cache)
O cache é uma janela de tiles ao redor da câmera.
Exemplo:
- Tela: 320×180
- Tiles 16×16 → 20×12 visíveis
- Cache: 22×14 (margem de 1 tile)
Ele guarda os tiles já resolvidos a partir do tilemap.
---
## 8. Atualização do Cache
A cada frame:
1. Calcular:
- `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. Se `tile_x` mudou:
- Avança `cache_origin_x`
- Recarrega apenas a nova coluna
3. Se `tile_y` mudou:
- Avança `cache_origin_y`
- Recarrega apenas a nova linha
Somente **uma linha e/ou coluna** é atualizada por frame.
---
## 9. Cache como Ring Buffer
O cache é circular:
- Não move dados fisicamente
- Apenas move índices lógicos
Acesso:
- `real_x = (cache_origin_x + logical_x) % cache_width`
- `real_y = (cache_origin_y + logical_y) % cache_height`
---
## 10. Projeção para o Back Buffer
Para cada frame:
1. Para cada Game Layer, em ordem:
- Rasterizar tiles visíveis do cache
- Aplicar scroll, flip e transparência
- Escrever no back buffer
2. Desenhar sprites:
- Com prioridade entre layers
- Ordem de desenho define profundidade
3. Desenhar HUD layer por último
---
## 11. Ordem de Desenho e Prioridade
- Não existe Z-buffer
- Não existe sorting automático
- Quem desenha depois fica na frente
Ordem base:
1. Game Layer 0
2. Game Layer 1
3. Game Layer 2
4. Game Layer 3
5. Sprites (por prioridade entre layers)
6. HUD Layer
---
## 12. Transparência (Color Key)
- Um valor RGB565 é reservado como TRANSPARENT_KEY
- Pixels com essa cor não são desenhados
```
if src == TRANSPARENT_KEY:
skip
else:
draw
```
---
## 13. Color Math (Blending Discreto)
Inspirado no SNES.
Modos oficiais:
- `BLEND_NONE`
- `BLEND_HALF`
- `BLEND_HALF_PLUS`
- `BLEND_HALF_MINUS`
- `BLEND_FULL`
Sem alpha contínuo.
Sem blending arbitrário.
Tudo é:
- inteiro
- barato
- determinístico
---
## 14. Onde o Blend é Aplicado
- O blend ocorre durante o desenho
- O resultado vai direto para o back buffer
- Não existe composição posterior automática
---
## 15. O que o GFX NÃO suporta
Por design:
- Alpha contínuo
- RGBA framebuffer
- Shader
- Pipeline moderno de GPU
- HDR
- Gamma correction
---
## 16. Regra de Performance
- Layers:
- só atualizam borda ao cruzar tile
- nunca redesenham mundo inteiro
- Rasterização:
- sempre por frame, só área visível
- Sprites:
- sempre redesenhados por frame
---
## 17. PostFX Especial — Fade (Scene e HUD)
O PROMETEU suporta **fade gradual** como um PostFX especial, com dois controles
independentes:
- **Scene Fade**: afeta toda a cena (Game Layers 0–3 + Sprites)
- **HUD Fade**: afeta apenas o HUD Layer (sempre composto por último)
O fade é implementado sem alpha contínuo por pixel e sem floats.
Ele usa um **nível inteiro discreto** (0..31), que na prática produz um resultado
visual “quase contínuo” em 320×180 pixel art.
---
### 17.1 Representação do Fade
Cada fade é representado por:
- `fade_level: u8` no intervalo **[0..31]**
- `0` → totalmente substituído pela cor de fade
- `31` → totalmente visível (sem fade)
- `fade_color: RGB565`
- cor para a qual a imagem será misturada
Registradores:
- `SCENE_FADE_LEVEL` (0..31)
- `SCENE_FADE_COLOR` (RGB565)
- `HUD_FADE_LEVEL` (0..31)
- `HUD_FADE_COLOR` (RGB565)
Casos comuns:
- Fade-out: `fade_color = BLACK`
- Flash/teleporte: `fade_color = WHITE`
- Efeitos especiais: qualquer cor RGB565
---
### 17.2 Operação de Fade (Mistura com Cor Arbitrária)
Para cada pixel RGB565 `src` e cor de fade `fc`, o pixel final `dst` é calculado por canal.
1) Extrair componentes:
- `src_r5`, `src_g6`, `src_b5`
- `fc_r5`, `fc_g6`, `fc_b5`
2) Aplicar mistura inteira:
```
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`
2) Aplicar mistura inteira:
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
3) Reempacotar:
```
dst = pack_rgb565(r5, g6, b5)
```
Observações:
- Operação determinística
- Somente inteiros
- Pode ser otimizada via LUT
---
### 17.3 Ordem de Aplicação no Frame
A composição do frame segue esta ordem:
1. Rasterizar **Game Layers 0–3** → Back Buffer
2. Rasterizar **Sprites** conforme prioridade
3. (Opcional) Pipeline extra (Emission/Light/Glow etc.)
4. Aplicar **Scene Fade** usando:
- `SCENE_FADE_LEVEL`
- `SCENE_FADE_COLOR`
5. Rasterizar **HUD Layer**
6. Aplicar **HUD Fade** usando:
- `HUD_FADE_LEVEL`
- `HUD_FADE_COLOR`
7. `present()`
Regras:
- Scene Fade nunca afeta HUD
- HUD Fade nunca afeta a cena
---
### 17.4 Casos de Uso
- Troca de HUD:
- diminuir `HUD_FADE_LEVEL` até 0
- trocar HUD/tilemap
- aumentar `HUD_FADE_LEVEL` até 31
- Troca de área:
- diminuir `SCENE_FADE_LEVEL` até 0
- trocar cenário
- aumentar `SCENE_FADE_LEVEL` até 31
- Flash / dano / teleporte:
- usar `fade_color = WHITE` ou outra cor temática
---
## 18. Resumo
O GFX do PROMETEU é simples **por escolha**, não por limitação.
- Framebuffer RGB565 com double buffer
- Color key para transparência
- Blending discreto estilo SNES
- Até 16 tile banks
- 4 game layers + 1 HUD
- Layer = tilemap + cache + scroll
- Projeção rasterizada por frame
- Profundidade definida por ordem de desenho
< [Voltar](chapter-3.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-5.md) >

294
docs/topics/chapter-5.md Normal file
View File

@ -0,0 +1,294 @@
< [Voltar](chapter-4.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-6.md) >
# 🔊 Periférico AUDIO (Sistema de Som)
## 1. Visão Geral
O **Periférico AUDIO** é responsável pela **geração e mistura de som** no PROMETEU.
Assim como os demais subsistemas, o áudio:
- **não é automático**
- **não é gratuito**
- **não é mágico**
Cada som ouvido é resultado de **comandos explícitos**, executados sob **orçamento de tempo e recursos**.
> Som também consome tempo.
Som também consome memória.
>
---
## 2. Filosofia do Sistema de Áudio
PROMETEU trata áudio como:
- um **periférico ativo**
- com **canais limitados, previsíveis**
- e **comportamento determinístico**
O objetivo não é realismo absoluto, mas **clareza arquitetural**.
---
## 3. Componentes do Periférico AUDIO
O sistema de áudio é composto por:
- **Canais de áudio** — fontes independentes de som
- **Samples** — dados sonoros curtos
- **Music streams** — trilhas contínuas
- **Mixer** — combinação final dos canais
Cada componente tem custo explícito.
---
## 4. Canais de Áudio
### 4.1 Definição
Um **canal de áudio** representa uma fonte sonora independente.
Características:
- número máximo de canais é limitado
- cada canal toca **um som por vez**
- canais são misturados no output final
Exemplo conceitual:
```
Max Channels:8
```
---
### 4.2 Uso dos Canais
Quando um som é tocado:
```
audio.play(sampleId, channel)
```
Se o canal estiver ocupado:
- o som anterior pode ser interrompido
- ou a chamada pode ser ignorada
(dependendo da política definida)
PROMETEU **não gerencia prioridades automaticamente**.
---
## 5. Samples (Efeitos Sonoros)
### 5.1 Definição
Um **sample** é um trecho curto de áudio pré-carregado.
Usado para:
- efeitos (tiros, passos, colisões)
- feedback imediato
- sons repetitivos
Samples:
- ocupam memória
- são imutáveis durante execução
- devem ser carregados conscientemente
---
### 5.2 Custo dos Samples
Cada sample tem custo associado a:
- tamanho em memória
- taxa de reprodução
- duração
Reproduzir muitos samples simultaneamente:
- consome mais ciclos
- aumenta pressão no mixer
---
## 6. Music Streams (Trilha Sonora)
### 6.1 Definição
**Music streams** são sons contínuos, geralmente mais longos.
Características:
- tocados em loop ou sequência
- geralmente ocupam um canal dedicado
- podem ser streamados para reduzir uso de memória
---
### 6.2 Controle de Música
Operações típicas:
```
audio.musicPlay(trackId)
audio.musicStop()
audio.musicSetVolume(v)
```
Essas operações:
- têm custo explícito
- afetam o mixer global
PROMETEU não faz crossfade automático sem instrução explícita.
---
## 7. Mixer de Áudio
### 7.1 Função do Mixer
O **mixer** combina os canais ativos em um único sinal de saída.
O custo do mixer depende de:
- número de canais ativos
- complexidade do som
- efeitos aplicados (se houver)
Mais canais ativos → mais custo por frame.
---
### 7.2 Efeitos Simples
PROMETEU pode suportar efeitos básicos:
- volume por canal
- pan (esquerda/direita)
- mute
Efeitos:
- são explícitos
- têm custo mensurável
- não são aplicados automaticamente
---
## 8. Sincronização Temporal do Áudio
### 8.1 Relação com o Clock do Sistema
O áudio em PROMETEU é sincronizado com o **clock base de 60 Hz**.
Isso significa:
- atualizações de áudio ocorrem por frame
- eventos sonoros são disparados em ticks definidos
- latência é previsível e estável
---
### 8.2 Áudio como Evento
PROMETEU incentiva tratar áudio como **evento**, não como estado contínuo:
- tocar som ao ocorrer uma ação
- evitar chamadas repetidas por frame
- desacoplar áudio da lógica pesada
Isso reduz custo e melhora clareza.
---
## 9. Áudio e CAP
O sistema de áudio participa do **Execution CAP**:
- reprodução de sons consome ciclos
- mixagem entra no orçamento por frame
- picos de áudio são registrados
Exemplo de relatório:
```
Frame 24510:
audio.play():120cycles
audio.mixer():380cycles
```
Excessos:
- não bloqueiam o jogo
- aparecem na certificação
---
## 10. Boas Práticas de Áudio
PROMETEU incentiva:
- reutilizar samples
- limitar canais simultâneos
- tratar áudio como evento
- separar música de efeitos
E desencoraja:
- tocar sons repetidamente por frame
- usar muitos canais sem necessidade
- samples grandes para efeitos simples
---
## 11. Relação com Consoles Clássicos
O modelo de áudio PROMETEU é inspirado em:
- canais dedicados do NES
- mixagem simples do SNES
- hardware de áudio previsível
Mas abstraído para:
- clareza
- simplicidade
- ensino
O objetivo é entender **como o som é produzido**, não emular chips específicos.
---
## 12. Implicações Pedagógicas
O Periférico AUDIO permite ensinar:
- concorrência limitada
- eventos temporais
- impacto de recursos em tempo real
- separação entre lógica e apresentação sonora
Tudo isso com **feedback auditivo e mensurável**.
---
## 13. Resumo
- áudio é um periférico explícito
- canais são limitados
- samples ocupam memória
- mixagem consome ciclos
- áudio participa do CAP
- som é consequência de decisões técnicas
< [Voltar](chapter-4.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-6.md) >

260
docs/topics/chapter-6.md Normal file
View File

@ -0,0 +1,260 @@
< [Voltar](chapter-5.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-7.md) >
# 🎮 **Periférico INPUT (Sistema de Entrada)**
## 1. Visão Geral
O **Periférico INPUT** é responsável por **coletar e disponibilizar o estado dos controles** ao programa PROMETEU.
Em PROMETEU:
- input é **estado**, não evento implícito
- input é **amostrado no tempo**, não entregue assíncronamente
- input tem **ordem, custo e momento definidos**
> Botões não “disparam eventos”.
Eles mudam de estado.
>
---
## 2. Filosofia do Sistema de Entrada
PROMETEU modela input como hardware clássico:
- o estado dos controles é lido **uma vez por frame**
- o programa consulta esse estado durante `UPDATE`
- não existem callbacks assíncronos de input
Esse modelo:
- é determinístico
- é simples de entender
- reflete microcontroladores e consoles clássicos
---
## 3. Dispositivos de Entrada
PROMETEU abstrai diferentes dispositivos em uma interface comum.
Dispositivos típicos:
- controle digital (D-Pad + botões)
- teclado (mapeado para botões)
- gamepad
- toque (mobile, mapeado)
Independentemente da origem, PROMETEU expõe **o mesmo modelo lógico**.
---
## 4. Modelo de Estado
### 4.1 Estado por Frame
Para cada frame, o sistema mantém:
- estado atual dos botões
- estado do frame anterior
Isso permite consultar:
- botão pressionado
- botão liberado
- botão mantido pressionado
---
### 4.2 Tipos de Consulta
Operações típicas:
```
input.btn(id)// botão está pressionado
input.btnp(id)// botão foi pressionado neste frame
input.btnr(id)// botão foi liberado neste frame
```
Essas funções:
- são puramente consultivas
- não alteram estado
- têm custo explícito
---
## 5. Momento da Amostragem
O estado do input é capturado **no início de cada frame**, antes da fase `UPDATE`.
Fluxo conceitual:
```
FRAME N:
SAMPLEINPUT
UPDATE
DRAW
AUDIO
SYNC
```
Durante todo o frame:
- o estado de input é imutável
- chamadas repetidas retornam o mesmo valor
> Input não muda no meio do frame.
>
---
## 6. Determinismo e Reprodutibilidade
O modelo de input PROMETEU garante:
- mesma sequência de inputs
- mesmos frames
- mesmos resultados
Isso permite:
- reprodução de execuções
- replays determinísticos
- certificação confiável
Input pode ser:
- gravado
- reproduzido
- injetado artificialmente
---
## 7. Input e CAP
Operações de input:
- consomem poucos ciclos
- participam do orçamento por frame
- aparecem em relatórios de certificação
Exemplo:
```
Frame 18231:
input.btn():12cycles
```
Embora barato, input **não é gratuito**.
---
## 8. Mapeamento de Botões
### 8.1 Identificadores Lógicos
PROMETEU define identificadores lógicos de botões:
- `UP`, `DOWN`, `LEFT`, `RIGHT`
- `A`, `B`, `X`, `Y`
- `START`, `SELECT`
O mapeamento físico:
- depende da plataforma
- é resolvido fora da VM
- é transparente ao programa
---
### 8.2 Portabilidade
O mesmo cartucho PROMETEU:
- roda em teclado
- roda em gamepad
- roda em touch
Sem alteração de código.
---
## 9. Input Analógico (Opcional)
PROMETEU pode expor eixos analógicos de forma explícita:
```
input.axis(id)
```
Características:
- valor normalizado (ex.: -1.0 a 1.0)
- custo explícito
- atualização por frame
Input analógico:
- não é obrigatório
- não substitui input digital
- deve ser usado conscientemente
---
## 10. Boas Práticas de Input
PROMETEU incentiva:
- tratar input como estado
- consultar input apenas em `UPDATE`
- separar input de lógica pesada
- mapear ações, não teclas
E desencoraja:
- lógica dependente de polling excessivo
- leitura de input em DRAW
- acoplamento direto a hardware físico
---
## 11. Relação com Consoles Clássicos
O modelo PROMETEU reflete:
- leitura de registradores de input
- polling por frame
- ausência de eventos assíncronos
Esse modelo:
- simplifica raciocínio
- aumenta previsibilidade
- facilita debugging
---
## 12. Implicações Pedagógicas
O Periférico INPUT permite ensinar:
- diferença entre evento e estado
- amostragem temporal
- determinismo em sistemas interativos
- sincronização entre input e lógica
Com feedback claro e reproduzível.
---
## 13. Resumo
- input é estado, não evento
- amostrado uma vez por frame
- imutável durante o frame
- consultas têm custo explícito
- input participa do CAP
- modelo é determinístico
< [Voltar](chapter-5.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-7.md) >

262
docs/topics/chapter-7.md Normal file
View File

@ -0,0 +1,262 @@
< [Voltar](chapter-6.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-8.md) >
# 🖐️ Periférico TOUCH (Sistema de Entrada via ponteiro absoluto)
## 1. Visão Geral
O periférico **TOUCH** fornece ao PROMETEU um **ponteiro absoluto**, baseado em coordenadas de tela, destinado a:
- interação com UI
- seleção direta de elementos
- ações contextuais no cenário
- mecânicas baseadas em arrasto (drag, slash, trail)
O TOUCH é um **periférico de primeira classe**, tão válido quanto D-Pad e botões.
---
## 2. Princípios de Design
O TOUCH no PROMETEU segue princípios rígidos:
- ✅ **Single-touch universal**
- ✅ **Determinístico**
- ✅ **Estado por frame**
- ✅ **Sem gestos**
- ✅ **Sem aceleração**
- ✅ **Sem heurística**
- ✅ **Mesmo comportamento em todas as plataformas**
> Se um comportamento não pode ser garantido em todas as plataformas, ele não existe no PROMETEU.
>
---
## 3. Modelo Conceitual
O PROMETEU expõe **apenas um ponteiro ativo por vez**, independentemente de quantos toques físicos o hardware reconheça.
- Hardware pode detectar multitouch
- Runtime seleciona **apenas um toque ativo**
- A API **nunca expõe multitouch**
Esse modelo garante:
- portabilidade total
- previsibilidade
- ausência de ambiguidades
---
## 4. Espaço de Coordenadas
- As coordenadas do TOUCH usam **o mesmo espaço do framebuffer**
- Resolução: **320×180**
- Origem: canto superior esquerdo `(0,0)`
- Intervalos:
- `x ∈ [0, 319]`
- `y ∈ [0, 179]`
O TOUCH é **absoluto**:
> (x, y) representa a posição exata do contato, sem transformação dinâmica.
>
---
## 5. API do Periférico TOUCH
### 5.1 Estrutura Exposta
```
TOUCH:
present : bool
down : bool
pressed : bool
released : bool
x : int
y : int
```
---
### 5.2 Semântica dos Campos
- **present**
- `true` se o periférico TOUCH está disponível
- `false` se não houver touch físico (desktop, hardware sem touch)
- **down**
- `true` enquanto o ponteiro ativo está pressionado
- **pressed**
- `true` apenas no frame em que o ponteiro ativo foi capturado
- **released**
- `true` apenas no frame em que o ponteiro ativo foi liberado
- **x, y**
- posição atual do ponteiro ativo
- válidas apenas quando `down == true`
---
## 6. Política de Seleção do Ponteiro
### *Single Pointer Capture Policy*
Quando múltiplos toques físicos ocorrem, o PROMETEU aplica a seguinte política:
---
### 6.1 Captura Inicial
1. Se **nenhum ponteiro está ativo**
2. E ocorre um **novo toque físico**
3. O **primeiro toque detectado** é capturado
4. Esse toque se torna o **ponteiro ativo**
Esse frame gera:
- `pressed = true`
- `down = true`
---
### 6.2 Manutenção da Captura
Enquanto o ponteiro ativo estiver pressionado:
- Apenas ele é rastreado
- Todos os outros toques físicos são ignorados
- `x, y` seguem apenas o ponteiro ativo
---
### 6.3 Liberação
Quando o ponteiro ativo é solto:
- `released = true`
- `down = false`
- O sistema entra em estado **sem ponteiro ativo**
---
### 6.4 Recaptura (Regra Importante)
Após a liberação:
- Toques que **já estavam presentes** são ignorados
- Um novo ponteiro só é capturado com um **novo evento de toque**
> Isso evita saltos inesperados do ponteiro e ações acidentais.
>
---
## 7. Comportamentos Deliberadamente NÃO Suportados
O periférico TOUCH **não implementa**:
❌ Multitouch
❌ Gestos (swipe, pinch, rotate, long-press)
❌ Aceleração ou suavização
❌ Sensibilidade dinâmica
❌ Histórico implícito
❌ Interpretação de intenção
Se um jogo quiser qualquer um desses comportamentos, ele deve:
- implementar explicitamente
- usando apenas estado por frame
- sem suporte implícito do hardware
---
## 8. “Sem Gesto” — Definição Formal
O PROMETEU **não interpreta padrões temporais**.
O periférico TOUCH **não classifica ações** como:
- swipe
- drag
- long press
- double tap
Ele apenas informa:
- posição atual
- estado do contato
Toda semântica é responsabilidade do jogo.
---
## 9. “Sem Aceleração” — Definição Formal
O PROMETEU **não modifica** o input do TOUCH.
- Nenhuma curva de sensibilidade
- Nenhuma amplificação por velocidade
- Nenhuma suavização
A relação entre o toque físico e `(x, y)` é **1:1** após normalização.
---
## 10. Integração com Outras Formas de Input
- Desktop:
- mouse pode emular TOUCH
- Mobile:
- touch físico direto
- Steam Deck:
- touchscreen físico
- Hardware PROMETEU:
- touch opcional, mas suportado
Do ponto de vista do PROMETEU:
> TOUCH é sempre TOUCH.
>
---
## 11. Usos Esperados
O periférico TOUCH é adequado para:
- UI (menus, inventário, mapas)
- drag-and-drop
- seleção direta
- “clicar para investigar”
- puzzles baseados em apontamento
- mecânicas de rastro (ex.: Fruit Ninja-like)
---
## 12. Garantias de Portabilidade
Todo jogo PROMETEU que utiliza TOUCH:
- comporta-se de forma idêntica em todas as plataformas
- não depende de capacidades específicas do host
- não sofre variação semântica entre desktop, mobile e hardware dedicado
---
## 13. Resumo
O TOUCH no PROMETEU é:
- simples
- explícito
- previsível
- universal
- determinístico
< [Voltar](chapter-6.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-8.md) >

238
docs/topics/chapter-8.md Normal file
View File

@ -0,0 +1,238 @@
< [Voltar](chapter-7.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-9.md) >
# 📀 Periférico MEMCARD (Sistema de save/load)
## 1. Visão Geral
O **MEMCARD** é o periférico responsável pela **persistência explícita de dados do jogo** no PROMETEU.
Ele simula o comportamento de *memory cards* clássicos (PS1, GameCube), fornecendo:
- armazenamento limitado
- custo explícito de I/O
- controle total do jogo sobre quando salvar
- portabilidade entre plataformas
O MEMCARD **não é um save state**.
Ele representa **dados que o próprio jogo decide persistir**.
---
## 2. Princípios de Design
O periférico MEMCARD segue os seguintes princípios:
- ✅ **Persistência explícita** (nada automático)
- ✅ **Tamanho limitado e conhecido**
- ✅ **Commit obrigatório**
- ✅ **Custo de tempo (ciclos) mensurável**
- ✅ **Formato estável e documentado**
- ✅ **Independente de plataforma**
- ❌ Sem sistema de arquivos complexo (no v0.1)
- ❌ Sem múltiplos arquivos internos (no v0.1)
---
## 3. Modelo Conceitual
Cada cartucho PROMETEU pode acessar **um ou mais slots de MEMCARD**, sendo o modelo padrão:
- **Slot A** — principal
- **Slot B** — opcional (futuro)
Cada slot corresponde a **um arquivo no host**:
```
MyGame_A.mem
MyGame_B.mem
```
O runtime monta esse arquivo como um **dispositivo de armazenamento persistente**.
---
## 4. Capacidade e CAP
O tamanho do MEMCARD é **fixo**, definido pelo perfil de execução (CAP).
### Tamanhos sugeridos
| Perfil | Tamanho |
| --- | --- |
| JAM | 8 KB |
| STANDARD | 32 KB |
| ADVANCED | 128 KB |
O jogo **não pode exceder** esse tamanho.
Tentativas de escrita acima do limite resultam em erro.
---
## 5. API do Periférico (v0.1)
### 5.1 Interface Lógica
O MEMCARD expõe uma API **simples de blob único**:
```
mem.read_all() -> byte[]
mem.write_all(byte[])
mem.commit()
mem.clear()
mem.size() -> int
```
---
### 5.2 Semântica das Operações
### `read_all()`
- Retorna todo o conteúdo persistido
- Se o cartão estiver vazio, retorna um buffer zerado
- Custo em ciclos proporcional ao tamanho
---
### `write_all(bytes)`
- Escreve o buffer **em memória temporária**
- Não persiste imediatamente
- Falha se `bytes.length > mem.size()`
---
### `commit()`
- Persiste os dados no dispositivo
- Operação **obrigatória**
- Simula flush de hardware
- Pode falhar (ex.: I/O, corrupção simulada)
---
### `clear()`
- Zera o conteúdo do cartão
- Requer `commit()` para persistir
---
### `size()`
- Retorna a capacidade total do cartão em bytes
---
## 6. Commit Explícito (Regra Fundamental)
O PROMETEU **não salva automaticamente**.
Sem `commit()`:
- dados permanecem voláteis
- podem ser perdidos ao encerrar o jogo
- simulam desligamento abrupto de hardware
👉 Isso ensina:
- flush de dados
- atomicidade
- risco de corrupção
- custo real de persistência
---
## 7. Custo de Execução (Ciclos)
Todas as operações de MEMCARD têm custo explícito.
### Exemplo (valores ilustrativos)
| Operação | Custo |
| --- | --- |
| read_all | 1 ciclo / 256 bytes |
| write_all | 1 ciclo / 256 bytes |
| commit | custo fixo + proporcional |
Esses custos aparecem:
- no profiler
- na timeline de frame
- no relatório de CAP
---
## 8. Formato do Arquivo `.mem`
O arquivo de MEMCARD possui um formato simples e robusto.
### 8.1 Header
| Campo | Tamanho |
| --- | --- |
| Magic (`PMEM`) | 4 bytes |
| Version | 1 byte |
| Cart ID | 8 bytes |
| Payload Size | 4 bytes |
| CRC32 | 4 bytes |
---
### 8.2 Payload
- Buffer binário definido pelo jogo
- Tamanho fixo
- Conteúdo interpretado apenas pelo jogo
---
## 9. Integridade e Segurança
- CRC valida corrupção
- Cart ID impede uso de save errado
- Versão permite evolução futura do formato
- Runtime pode:
- avisar corrupção
- permitir reset do cartão
---
## 10. Integração com o Editor / GUI
A ferramenta principal pode fornecer um **Memory Card Manager**:
- criar/resetar cartão
- ver tamanho e uso
- importar/exportar `.mem`
- visualizar últimos commits
- associar cartões a projetos
Nenhuma dessas operações altera o runtime.
---
## 11. Evoluções Planejadas (fora do v0.1)
- API de blocos (`read_block`, `write_block`)
- múltiplos slots internos
- wear simulation
- versionamento de saves
- criptografia opcional (educacional)
---
## 12. Resumo
O periférico MEMCARD no PROMETEU:
- simula hardware real
- força decisões de design
- ensina persistência corretamente
- é simples de usar
- é difícil de abusar
- cresce sem quebrar compatibilidade
< [Voltar](chapter-7.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-9.md) >

289
docs/topics/chapter-9.md Normal file
View File

@ -0,0 +1,289 @@
< [Voltar](chapter-8.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-10.md) >
# ⚡ **Eventos e Interrupções**
## 1. Visão Geral
PROMETEU distingue claramente **execução normal**, **eventos** e **interrupções**.
Nada ocorre “fora do tempo”.
Nada interrompe o sistema sem custo.
Nada acontece sem um ponto bem definido no ciclo de execução.
> Eventos são sinais.
Interrupções são decisões da máquina.
>
Este capítulo define:
- o que PROMETEU considera um evento
- como interrupções são modeladas
- quando elas podem ocorrer
- como se relacionam com ciclos, CAP e determinismo
---
## 2. Filosofia de Eventos em PROMETEU
PROMETEU **não utiliza callbacks assíncronos invisíveis**.
Todo evento:
- é registrado
- é entregue em momento previsível
- é tratado dentro do loop principal
Esse modelo evita:
- concorrência implícita
- race conditions ocultas
- efeitos colaterais não determinísticos
PROMETEU favorece:
> controle explícito sobre reatividade.
>
---
## 3. Eventos
### 3.1 Definição
Um **evento** em PROMETEU é um **sinal lógico** gerado pelo sistema ou pelo programa, que indica que algo ocorreu.
Exemplos de eventos:
- fim de frame
- timer expirado
- troca de estado do sistema
- erro de execução
Eventos **não executam código automaticamente**.
Eles apenas **informam**.
---
### 3.2 Fila de Eventos
PROMETEU mantém uma **fila de eventos**:
- eventos são enfileirados
- a fila é processada em ordem
- o processamento ocorre em pontos definidos do frame
Eventos:
- não interrompem execução arbitrariamente
- não executam fora do loop
---
## 4. Interrupções
### 4.1 Definição
Uma **interrupção** é um evento especial, tratado pelo sistema como **prioritário**, que pode:
- alterar o fluxo normal de execução
- executar código específico do sistema
- impactar ciclos e orçamento
Interrupções são **raras e explícitas**.
---
### 4.2 O que NÃO é uma interrupção
Em PROMETEU, **não são interrupções**:
- input de botão
- colisões
- timers comuns
- lógica de jogo
Esses são tratados como **estado ou eventos normais**.
---
## 5. Tipos de Interrupções em PROMETEU
PROMETEU define um conjunto pequeno e bem controlado de interrupções.
### 5.1 Interrupção de Frame (VBlank Conceitual)
O final de cada frame gera uma **interrupção lógica de sincronização**, responsável por:
- swap de framebuffer
- commit de áudio
- sincronização de estado
Essa interrupção:
- ocorre no SYNC
- tem custo fixo
- não executa código do usuário
---
### 5.2 Interrupção de Sistema
Gerada por condições excepcionais:
- erro fatal de VM
- violação de memória
- instrução inválida
Resultado:
- execução é interrompida
- estado da VM é preservado
- relatório detalhado é gerado
---
### 5.3 Interrupções Temporizadas (Timers)
PROMETEU pode oferecer **timers do sistema**, modelados como:
- contadores baseados em frames
- sinais gerados ao atingir zero
Timers:
- não disparam código automaticamente
- geram eventos consultáveis
Exemplo conceitual:
```
if (timer.expired(T1)) {
// tratar evento
}
```
---
## 6. Relação entre Eventos, Interrupções e o Loop
O fluxo completo pode ser representado assim:
```
FRAME N
──────────────
SAMPLEINPUT
PROCESS EVENTS
UPDATE
DRAW
AUDIO
INTERRUPT: VBLANK
SYNC
──────────────
```
Importante:
- eventos são processados antes da lógica principal
- interrupções ocorrem apenas em pontos seguros
- nenhuma interrupção ocorre “no meio” de uma instrução
---
## 7. Custos e Orçamento
Eventos e interrupções:
- consomem ciclos
- participam do CAP
- aparecem na certificação
Exemplo de relatório:
```
Frame 18231:
Event processing:120cycles
VBlank interrupt:80cycles
```
Nada é gratuito.
---
## 8. Determinismo e Reprodutibilidade
PROMETEU garante:
- mesma sequência de eventos → mesmo comportamento
- interrupções sempre no mesmo ponto do frame
- timers baseados em frame count, não em tempo real
Isso permite:
- replays confiáveis
- debugging preciso
- certificação justa
---
## 9. Boas Práticas
PROMETEU incentiva:
- tratar eventos como dados
- consultar eventos explicitamente
- evitar lógica pesada em handlers
- usar timers em vez de polling excessivo
PROMETEU desencoraja:
- simular callbacks assíncronos
- depender de ordem implícita
- usar eventos como “atalho” para lógica complexa
---
## 10. Relação com Microcontroladores
O modelo reflete MCUs reais:
| MCU | PROMETEU |
| --- | --- |
| ISR | Interrupção explícita |
| Loop principal | Loop PROMETEU |
| Flags | Eventos |
| Timers | Timers por frame |
Mas sem:
- concorrência real
- interrupções imprevisíveis
PROMETEU **ensina o conceito**, não o caos.
---
## 11. Implicações Pedagógicas
Este modelo permite ensinar:
- diferença entre evento e interrupção
- sincronização segura
- controle de fluxo em sistemas reativos
- impacto de decisões temporais
Tudo com **ordem, clareza e mensuração**.
---
## 12. Resumo
- eventos informam, não executam
- interrupções são raras e controladas
- nenhuma execução ocorre fora do loop
- custos são explícitos
- comportamento é determinístico
< [Voltar](chapter-8.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-10.md) >

16
docs/topics/table-of-contens.md Normal file
View File

@ -0,0 +1,16 @@
# Table of Contents
- [Capitulo 1: Modelo de Tempo e Ciclos](chapter-1.md)
- [Capitulo 2: PROMETEU VM Instruction Set](chapter-2.md)
- [Capitulo 3: Memória: Stack, Heap e Alocação](chapter-3.md)
- [Capitulo 4: Periférico GFX (Sistema Gráfico)](chapter-4.md)
- [Capitulo 5: Periférico AUDIO (Sistema de Áudio)](chapter-5.md)
- [Capitulo 6: Periférico INPUT (Sistema de Entrada)](chapter-6.md)
- [Capitulo 7: Periférico TOUCH (Sistema de Entrada via ponteiro absoluto)](chapter-7.md)
- [Capitulo 8: Periférico MEMCARD (Sistema de save/load)](chapter-8.md)
- [Capitulo 9: Eventos e Interrupções](chapter-9.md)
- [Capitulo 10: Debug, Inspeção e Profiling](chapter-10.md)
- [Capitulo 11: Garantias de Portabilidade e Execução Multiplataforma](chapter-11.md)
---
[Voltar para o README](../README.md)