adjustments on docs

This commit is contained in:
2026-03-24 13:40:47 +00:00
parent f6751a03a4
commit a6ad14fcb2
33 changed files with 831 additions and 1330 deletions
+39
View File
@@ -0,0 +1,39 @@
# PROMETEU Learn
Esta área reúne material didático sobre a máquina PROMETEU.
Ela existe para explicar o modelo mental da fantasy handheld, suas influências, tradeoffs e implicações de design sem contaminar as specs normativas com framing pedagógico.
## Authority
- `docs/runtime/learn/` não é fonte canônica de contrato técnico.
- As superfícies normativas da máquina vivem em [`../specs/`](../specs/README.md).
- As invariantes internas da VM/runtime vivem em [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md).
## Current Guides
- [`gfx-mental-model.md`](gfx-mental-model.md)
- [`audio-mental-model.md`](audio-mental-model.md)
- [`input-mental-model.md`](input-mental-model.md)
- [`touch-mental-model.md`](touch-mental-model.md)
- [`save-memory-and-memcard.md`](save-memory-and-memcard.md)
- [`observability-and-debugging.md`](observability-and-debugging.md)
- [`portability-and-cross-platform.md`](portability-and-cross-platform.md)
- [`time-model-and-cycles.md`](time-model-and-cycles.md)
## Rules
- material em `learn` pode explicar, comparar, ensinar e contextualizar;
- material em `learn` não deve redefinir o contrato normativo dos specs;
- quando um tema tiver spec e guia didático, o guia deve apontar para o spec correspondente.
## When To Create A Pair
Criar um par `spec` + `learn` quando o tema:
- precisa de contrato técnico estável e também de modelo mental;
- tem forte carga histórica, pedagógica ou de design rationale;
- corre risco de virar manifesto dentro do spec normativo;
- exige exemplos, comparações ou intuição que não pertencem ao contrato.
Se o tema for pequeno e estritamente contratual, o capítulo pode nascer só em `specs`.
+55
View File
@@ -0,0 +1,55 @@
# Audio Mental Model
Status: pedagogical
Companion spec: [`../specs/05-audio-peripheral.md`](../specs/05-audio-peripheral.md)
O modelo mental correto para áudio em PROMETEU é o de um periférico ativo com orçamento, não o de “som automático”.
## Philosophy
Som:
- consome tempo;
- consome memória;
- usa canais finitos;
- depende de comandos explícitos.
Isso aproxima PROMETEU de consoles e arcades clássicos em que o jogo “conversa” com um bloco de áudio com regras próprias.
## Audio CPU Metaphor
Uma metáfora útil é pensar em:
```text
[Game CPU] -> envia comandos em 60 Hz -> [AUDIO Peripheral]
|
v
Voices + Mixer
|
v
PCM Output
```
Essa metáfora não exige um thread dedicado. Ela só separa responsabilidades:
- a máquina define o modelo lógico;
- o host decide como entregar buffers contínuos;
- o jogo fala em comandos, não em manipulação direta do backend.
## Good Habits
- reutilizar samples;
- limitar vozes simultâneas;
- tratar som como evento intencional;
- separar música e efeitos;
- evitar disparar o mesmo som todo frame.
## Historical Direction
As influências principais aqui são:
- NES, pela clareza de canais limitados;
- SNES, por playback de sample e mistura;
- CPS-2 e Neo Geo, pela sensação de folga e presença de sample playback.
PROMETEU abstrai essas referências. Ele não tenta reproduzir nenhum desses sistemas literalmente.
+65
View File
@@ -0,0 +1,65 @@
# GFX Mental Model
Status: pedagogical
Companion spec: [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
PROMETEU trata gráficos como um periférico explícito, não como uma GPU moderna.
O modelo mental correto é o de uma máquina 2D retro com:
- framebuffer;
- tile banks;
- tile layers;
- sprites por ordem de desenho;
- composição determinística por frame.
## Why This Exists
O objetivo não é imitar hardware histórico byte a byte. O objetivo é capturar a família de restrições e de linguagem visual de consoles como SNES, CPS-2 e Neo Geo, mas em um contrato pequeno, portátil e implementável em desktop e hardware DIY.
Isso produz algumas consequências importantes:
- desenho por ordem importa mais do que “efeitos”;
- paletas importam como parte do asset design;
- o programador pensa em rasterização, não em shaders;
- o custo visual fica mais observável.
## What The GFX Is Not
PROMETEU GFX não é:
- pipeline moderno de GPU;
- framebuffer RGBA com alpha arbitrário;
- sistema de shaders;
- composição automática pós-processada.
Essas ausências são deliberadas. Elas forçam uma linguagem visual mais próxima de console clássico e mantêm o contrato executável em ambientes modestos.
## Practical Intuition
- Tile layers existem para mundo e cenário.
- HUD existe para informação fixa e deve permanecer desacoplado da câmera.
- Sprites existem para entidades móveis e sua profundidade depende da ordem e da prioridade.
- Paletas existem para variar estado visual sem duplicar tile art.
- Fade existe como efeito especial discreto, não como alpha genérico.
## Palette Thinking
Uma boa maneira de pensar PROMETEU é: arte e cor não são a mesma coisa.
O tile é a forma. A paleta é o estado visual.
Isso habilita:
- variação de inimigos;
- mudança de bioma;
- dano, gelo, veneno, power-up;
- temas de HUD;
- ciclos de dia e noite.
## Use Cases
- troca de área com `Scene Fade`;
- troca de HUD com `HUD Fade`;
- flash de dano ou teleporte;
- swap global de paleta para clima ou estado de mundo.
+43
View File
@@ -0,0 +1,43 @@
# Input Mental Model
Status: pedagogical
Companion spec: [`../specs/06-input-peripheral.md`](../specs/06-input-peripheral.md)
PROMETEU trata input como estado amostrado, não como evento assíncrono.
## State Versus Event
O modelo mais importante para entender é:
- botão não “dispara” uma ação sozinho;
- botão muda de estado;
- o jogo consulta esse estado durante o frame.
Isso se parece muito mais com polling de registrador em console clássico do que com callbacks de UI moderna.
## Why This Matters
Esse modelo:
- melhora determinismo;
- simplifica replay;
- facilita depuração;
- torna o frame loop mais legível.
Também encaixa melhor na identidade de PROMETEU como máquina com forte inspiração em hardware retro e em construção DIY.
## Good Habits
- ler input em `UPDATE`;
- mapear ações, não teclas físicas;
- separar leitura de input de lógica pesada;
- tratar polling como parte do frame budget.
## Teaching Value
O periférico de input ajuda a ensinar:
- diferença entre estado e evento;
- amostragem temporal;
- sincronização entre input e lógica;
- determinismo em sistemas interativos.
@@ -0,0 +1,33 @@
# Observability and Debugging
Status: pedagogical
Companion spec: [`../specs/10-debug-inspection-and-profiling.md`](../specs/10-debug-inspection-and-profiling.md)
PROMETEU foi desenhado para ser observável.
## Debug Philosophy
Há três ideias centrais aqui:
1. estado vem antes de abstração;
2. tempo é cidadão de primeira classe;
3. observar não deve alterar o resultado lógico.
Isso puxa o projeto para um estilo de depuração mais próximo de máquina e menos próximo de “tentativa e erro”.
## Why This Matters
Quando a máquina expõe pilhas, heap, ciclos, buffers e faults de forma consistente, o programador consegue:
- localizar custo real;
- correlacionar tempo e memória;
- justificar decisão técnica;
- depurar sem inventar explicações mágicas.
## Teaching Value
Essa superfície didática existe porque PROMETEU quer ensinar também como sistemas são analisados:
- debugging como observação informada;
- profiling como leitura de evidência;
- certification como relatório técnico reproduzível.
@@ -0,0 +1,52 @@
# Portability and Cross-Platform Execution
Status: pedagogical
Companion spec: [`../specs/11-portability-and-cross-platform-execution.md`](../specs/11-portability-and-cross-platform-execution.md)
PROMETEU trata portabilidade como propriedade arquitetural da máquina, não como adaptação posterior.
## Core Idea
O ponto principal é simples:
- a máquina define a semântica;
- o host realiza apresentação e integração física;
- o cartridge não negocia comportamento com o sistema operacional.
Isso evita a noção comum de que cada plataforma “tem sua versão” da lógica do jogo.
## Why This Matters
Quando tempo, memória, input, áudio e gráficos são definidos pela máquina, ficam mais fáceis:
- replay determinístico;
- certification reproduzível;
- execução em desktop, mobile e hardware DIY;
- separação limpa entre semântica e adaptação.
## Practical Separation
Uma forma útil de pensar é:
- cartridge carrega programa e assets;
- a VM/runtime executa a lógica;
- o host mostra pixels, entrega áudio e coleta input físico;
- o host não redefine as regras do jogo.
## What Portability Does Not Mean
PROMETEU não promete:
- a mesma latência física;
- o mesmo consumo energético;
- o mesmo throughput bruto do host.
Ele promete consistência lógica. Isso é o que importa para a identidade da máquina.
## Teaching Value
Esse modelo ajuda a ensinar:
- diferença entre lógica e apresentação;
- por que engines modernas frequentemente perdem determinismo;
- como projetar software portátil sem depender de sorte.
@@ -0,0 +1,43 @@
# Save Memory and MEMCARD
Status: pedagogical
Companion spec: [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
PROMETEU trata persistência como hardware explícito, não como save invisível.
## Mental Model
O MEMCARD não é save state. Ele é um dispositivo de persistência controlado pelo jogo.
Isso implica:
- tamanho conhecido;
- custo observável;
- necessidade de `commit()`;
- possibilidade de falha;
- formato de dados sob controle do jogo.
## Why Explicit Commit Matters
O `commit()` existe para tornar persistência uma decisão técnica visível.
Sem ele, não há ilusão de que “salvar simplesmente aconteceu”. O jogo precisa assumir quando quer:
- materializar escrita;
- aceitar custo;
- lidar com risco de perda ou corrupção.
## Tooling Surface
Ferramentas externas podem expor utilidades como:
- criar ou resetar MEMCARD;
- importar e exportar `.mem`;
- inspecionar tamanho e uso;
- associar cartões a projetos.
Essas superfícies são auxiliares. Elas não mudam o contrato da máquina.
## Why This Fits PROMETEU
Esse modelo conversa bem com a herança de console e com o foco DIY do projeto: persistência é parte do design da máquina, não conveniência escondida do host.
@@ -0,0 +1,50 @@
# Time Model and Cycles
Status: pedagogical
Companion spec: [`../specs/01-time-model-and-cycles.md`](../specs/01-time-model-and-cycles.md)
PROMETEU trata tempo como parte explícita da máquina.
## Core Idea
Nada acontece “de graça” ou “instantaneamente”. O programador deve pensar em:
- ritmo da máquina;
- custo por frame;
- distribuição de trabalho ao longo do tempo;
- impacto arquitetural de quando cada sistema roda.
## Why Cycles Instead of Milliseconds
Milissegundos variam com plataforma, jitter e hardware real. Cycles dão uma métrica de custo que pertence à máquina PROMETEU, não ao host.
Isso torna mais fácil comparar soluções, ensinar custo e raciocinar sobre performance sem esconder a conta atrás do sistema operacional.
## Temporal Distribution As Design
Uma das intuições mais importantes em PROMETEU é: otimização não é só “fazer menos”, é decidir **quando** fazer.
Exemplos úteis:
- IA em 30 Hz;
- pathfinding em 15 Hz;
- timers dirigidos por frame count;
- separação entre atualização pesada e apresentação.
## Why CAP Fits Here
O CAP reforça essa leitura de tempo como evidência técnica. Ele não existe para bloquear execução, e sim para tornar visíveis:
- picos;
- gargalos;
- distribuição de custo;
- decisões de arquitetura temporal.
## Teaching Value
Esse modelo ajuda a ensinar:
- planejamento de execução;
- trade-offs técnicos;
- leitura de perfil real;
- organização temporal como ferramenta arquitetural.
+40
View File
@@ -0,0 +1,40 @@
# Touch Mental Model
Status: pedagogical
Companion spec: [`../specs/07-touch-peripheral.md`](../specs/07-touch-peripheral.md)
PROMETEU usa TOUCH como um ponteiro absoluto e determinístico, não como uma superfície rica em gestos.
## Design Intuition
O princípio central é simples:
- um único ponteiro ativo;
- sem gestos implícitos;
- sem aceleração;
- sem heurística;
- mesmo comportamento em desktop, mobile e hardware dedicado.
Se o comportamento não puder ser garantido de forma portátil, ele não entra na máquina.
## Why Single Pointer
Multitouch físico pode existir no host, mas a máquina escolhe um único ponteiro lógico para evitar:
- ambiguidades de captura;
- diferenças entre plataformas;
- mudanças semânticas entre mouse, touch real e touchscreen embutido.
## Good Uses
TOUCH funciona bem para:
- UI;
- seleção direta;
- drag-and-drop;
- puzzles de apontamento;
- trilhas, cortes e mecânicas baseadas em contato.
## What Games Must Do Themselves
Se um jogo quiser gesto, swipe, long-press ou smoothing, ele deve construir isso por cima do estado bruto por frame. O periférico não interpreta intenção.