improve v0.1, and add docs

crates/core/src/color.rs

@@ -18,6 +18,10 @@ impl Color {
         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 {
         Self(raw)
     }

crates/core/src/machine.rs

@@ -1,8 +1,8 @@
-use crate::peripherals::{Gfx, InputSignals, Pad, Touch};
+use crate::peripherals::{BlendMode, Gfx, InputSignals, Pad, Touch};
 use crate::Color;
 
 /// 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 gfx: Gfx,
     pub pad: Pad,
@@ -54,7 +54,10 @@ impl Machine {
             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.
@@ -63,8 +66,8 @@ impl Machine {
     }
 
     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)
     }
 }

crates/core/src/peripherals/mod.rs

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

crates/host_desktop/src/main.rs

@@ -29,7 +29,7 @@ struct PrometeuApp {
 
     input_signals: InputSignals,
     
-    frame_dt: Duration,
+    frame_target_dt: Duration,
     next_frame: Instant,
 }
 
@@ -38,10 +38,12 @@ impl PrometeuApp {
         Self {
             window: None,
             pixels: None,
-            input_signals: InputSignals::default(),
+            
             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(),
         }
     }
@@ -181,7 +183,7 @@ impl ApplicationHandler for PrometeuApp {
         let now = Instant::now();
 
         if now >= self.next_frame {
-            self.next_frame += self.frame_dt;
+            self.next_frame += self.frame_target_dt;
 
             // executa 1 frame do PROMETEU
             self.machine.step_frame(&self.input_signals);

docs/README.md

@@ -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) >

docs/topics/chapter-1.md

@@ -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) >

docs/topics/chapter-10.md

@@ -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) >

docs/topics/chapter-11.md

@@ -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) >

docs/topics/chapter-2.md

@@ -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) >

docs/topics/chapter-3.md

@@ -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) >

docs/topics/chapter-4.md

@@ -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) >

docs/topics/chapter-5.md

@@ -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) >

docs/topics/chapter-6.md

@@ -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) >

docs/topics/chapter-7.md

@@ -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) >

docs/topics/chapter-8.md

@@ -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) >

docs/topics/chapter-9.md

@@ -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) >

docs/topics/table-of-contens.md

@@ -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)