From 484e0895c1a754d88901e2c7f536dd3741acd97a Mon Sep 17 00:00:00 2001
From: Nilton Constantino <nilton.constantino@visma.com>
Date: Wed, 14 Jan 2026 07:42:32 +0000
Subject: [PATCH] update palleta spec

---
 docs/topics/chapter-4.md | 179 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 178 insertions(+), 1 deletion(-)

diff --git a/docs/topics/chapter-4.md b/docs/topics/chapter-4.md
index 3fb1a2d3..378f1da0 100644
--- a/docs/topics/chapter-4.md
+++ b/docs/topics/chapter-4.md
@@ -407,7 +407,184 @@ Regras:
 
 ---
 
-## 18. Resumo
+## 18. Sistema de Paletas
+
+### 18.1. Visão Geral
+
+O PROMETEU utiliza **exclusivamente** gráficos indexados por paleta.
+
+Não existe modo RGB direto por pixel.  
+Todo pixel gráfico é um **índice** que aponta para uma cor real em uma paleta.
+
+Objetivos:
+
+- reduzir uso de RAM e storage
+- permitir troca de cores sem shader
+- manter identidade retrô
+- facilitar efeitos como variação, dano, dia/noite
+
+---
+
+### 18.2. Formato de Pixel
+
+Cada pixel de um tile ou sprite é:
+
+- **4 bits por pixel (4bpp)**
+- valores: `0..15`
+
+Regra fixa:
+
+- Índice `0` = TRANSPARENTE
+- Índices `1..15` = cores válidas da paleta
+
+---
+
+### 18.3. Estrutura de Paletas
+
+Cada **Tile Bank** contém:
+
+- Até **256 paletas**
+- Cada paleta tem:
+  - **16 cores**
+  - cada cor em **RGB565 (u16)**
+
+Tamanho:
+
+- 1 paleta = 16 × 2 bytes = **32 bytes**
+- 256 paletas = **8 KB por bank**
+- 16 banks = **128 KB máximo de paletas**
+
+---
+
+### 18.4. Associação de Paleta
+
+#### Regra Fundamental
+
+- Cada **tile** usa **uma única paleta**
+- Cada **sprite** usa **uma única paleta**
+- A paleta deve ser informada **explicitamente** em todo draw
+
+Não existe troca de paleta dentro do mesmo tile ou sprite.
+
+---
+
+### 18.5. Onde a Paleta é Definida
+
+#### Tilemap
+
+Cada célula do tilemap contém:
+
+- `tile_id`
+- `palette_id (u8)`
+- `flip_x`
+- `flip_y`
+
+#### Sprite
+
+Cada sprite draw contém:
+
+- `bank_id`
+- `tile_id`
+- `palette_id (u8)`
+- `x`, `y`
+- `flip_x`, `flip_y`
+- `priority`
+
+---
+
+### 18.6. Resolução de Cor
+
+O pipeline funciona assim:
+
+1. Ler pixel indexado do tile (valor 0..15)
+2. Se índice == 0 → pixel transparente
+3. Caso contrário:
+  - cor_real = paleta[palette_id][indice]
+4. Aplicar:
+  - flip
+  - blend discreto
+  - escrita no back buffer
+
+Ou seja:
+```
+pixel_index = tile_pixel(x,y)
+if pixel_index == 0:
+    skip
+else:
+    color = bank.palettes[palette_id][pixel_index]
+    draw(color)
+```
+
+---
+
+### 18.7. Organização dos Tile Banks
+
+Os Tile Banks são “assets fortes”:
+
+- Tiles e paletas vivem juntos
+- Exportação/importação sempre leva:
+  - tiles + paletas
+- O hardware não impõe organização semântica:
+  - o agrupamento é decisão do criador
+- Tooling e scripts podem criar convenções:
+  - ex.: paletas 0..15 = inimigos
+  - 16..31 = cenário
+  - etc.
+
+--- 
+
+### 18.8. Efeitos Possíveis com Paletas
+
+Sem shader, é possível:
+
+- Palette swap:
+  - inimigos com variação de cor
+- Estados:
+  - dano, gelo, veneno, power-up
+- Dia / noite:
+  - trocar paletas globalmente
+- Biomas:
+  - mesma arte, clima diferente
+ - UI themes
+
+Tudo isso sem mudar os tiles.
+
+--- 
+
+### 18.9. Limitações Artísticas
+
+- Cada tile/sprite:
+ 
+  - máximo de 16 cores
+
+- Gradientes suaves exigem:
+
+  - dithering
+  - blend discreto
+  - glow/emission
+
+Essa limitação é intencional e faz parte da identidade do PROMETEU.
+
+---
+
+### 18.10. Métricas para Certificação (CAP)
+
+O sistema pode medir:
+
+- `palettes_loaded_total`
+- `palettes_referenced_this_frame`
+- `tiles_drawn_by_palette_id`
+- `sprites_drawn_by_palette_id`
+
+Isso permite:
+
+- analisar custo artístico
+- ensinar impacto de variedade excessiva
+- sugerir boas práticas de coesão visual
+
+---
+
+## 19. Resumo
 
 O GFX do PROMETEU é simples **por escolha**, não por limitação.