From 78e12a065e22f3d0f76a006c2d74b89075581f15 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Mon, 12 Jan 2026 18:37:53 +0000 Subject: [PATCH] improve v0.1, and add docs --- crates/core/src/color.rs | 4 + crates/core/src/machine.rs | 15 +- crates/core/src/peripherals/mod.rs | 1 + crates/host_desktop/src/main.rs | 12 +- docs/README.md | 299 ++++++++++++++++++++ docs/topics/chapter-1.md | 254 +++++++++++++++++ docs/topics/chapter-10.md | 350 +++++++++++++++++++++++ docs/topics/chapter-11.md | 258 +++++++++++++++++ docs/topics/chapter-2.md | 306 ++++++++++++++++++++ docs/topics/chapter-3.md | 309 ++++++++++++++++++++ docs/topics/chapter-4.md | 434 +++++++++++++++++++++++++++++ docs/topics/chapter-5.md | 294 +++++++++++++++++++ docs/topics/chapter-6.md | 260 +++++++++++++++++ docs/topics/chapter-7.md | 262 +++++++++++++++++ docs/topics/chapter-8.md | 238 ++++++++++++++++ docs/topics/chapter-9.md | 289 +++++++++++++++++++ docs/topics/table-of-contens.md | 16 ++ 17 files changed, 3590 insertions(+), 11 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/topics/chapter-1.md create mode 100644 docs/topics/chapter-10.md create mode 100644 docs/topics/chapter-11.md create mode 100644 docs/topics/chapter-2.md create mode 100644 docs/topics/chapter-3.md create mode 100644 docs/topics/chapter-4.md create mode 100644 docs/topics/chapter-5.md create mode 100644 docs/topics/chapter-6.md create mode 100644 docs/topics/chapter-7.md create mode 100644 docs/topics/chapter-8.md create mode 100644 docs/topics/chapter-9.md create mode 100644 docs/topics/table-of-contens.md diff --git a/crates/core/src/color.rs b/crates/core/src/color.rs index 53166fe6..c09a526a 100644 --- a/crates/core/src/color.rs +++ b/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) } diff --git a/crates/core/src/machine.rs b/crates/core/src/machine.rs index e07659c1..ef7a9026 100644 --- a/crates/core/src/machine.rs +++ b/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 z = (self.pad.a.hold_frames % 140) as i32; - (20 + t, z) + let x = (self.frame_index % 300) as i32; + let y = (self.pad.a.hold_frames % 160) as i32; + (x, y) } } diff --git a/crates/core/src/peripherals/mod.rs b/crates/core/src/peripherals/mod.rs index d319df4a..988ea52c 100644 --- a/crates/core/src/peripherals/mod.rs +++ b/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; diff --git a/crates/host_desktop/src/main.rs b/crates/host_desktop/src/main.rs index 77c72f47..080d5814 100644 --- a/crates/host_desktop/src/main.rs +++ b/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(), } } @@ -67,7 +69,7 @@ impl PrometeuApp { } } -impl ApplicationHandler for PrometeuApp { +impl ApplicationHandler for PrometeuApp { fn resumed(&mut self, event_loop: &ActiveEventLoop) { let attrs = WindowAttributes::default() .with_title("PROMETEU - host_desktop") @@ -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); diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..208f48f4 --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/chapter-1.md b/docs/topics/chapter-1.md new file mode 100644 index 00000000..49416e31 --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/chapter-10.md b/docs/topics/chapter-10.md new file mode 100644 index 00000000..6659e48c --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/chapter-11.md b/docs/topics/chapter-11.md new file mode 100644 index 00000000..fe62541f --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/chapter-2.md b/docs/topics/chapter-2.md new file mode 100644 index 00000000..1f3c3c09 --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/chapter-3.md b/docs/topics/chapter-3.md new file mode 100644 index 00000000..b0374d6b --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/chapter-4.md b/docs/topics/chapter-4.md new file mode 100644 index 00000000..0d81d176 --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/chapter-5.md b/docs/topics/chapter-5.md new file mode 100644 index 00000000..ade86335 --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/chapter-6.md b/docs/topics/chapter-6.md new file mode 100644 index 00000000..6e0348e9 --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/chapter-7.md b/docs/topics/chapter-7.md new file mode 100644 index 00000000..bf760b2d --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/chapter-8.md b/docs/topics/chapter-8.md new file mode 100644 index 00000000..23f72aca --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/chapter-9.md b/docs/topics/chapter-9.md new file mode 100644 index 00000000..b0537dc7 --- /dev/null +++ b/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) > \ No newline at end of file diff --git a/docs/topics/table-of-contens.md b/docs/topics/table-of-contens.md new file mode 100644 index 00000000..6d467dbb --- /dev/null +++ b/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) \ No newline at end of file