adjustments on docs
This commit is contained in:
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user