Files
zelda-1-prometeu-port/extracted/hud/README.md
T

90 lines
4.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# HUD do overworld
Composição 256×64 extraída da ROM local verificada, exibida em escala 1:1 na
faixa superior da área NES. Usa os padrões e os registros de transferência PPU
originais para mapa, caixas A/B, LIFE, ícones e contadores.
O estado inicial tem sala `$77`, três corações completos, zero rupees, chaves e
bombas e slots A/B vazios. O slot A agora lê `Items[0]`: a espada aparece após
a aquisição na caverna. Ver [inventário](../inventory/README.md). Os corações agora são dinâmicos e leem os slots `$18/$19`;
os outros contadores continuam fixos. Ver [vida](../life/README.md). `hud.png` preserva o visual
com espada e `hud_unarmed.png` registra o visual inicial sem ela.
## Organização
- `src/hud`: serviço público `Hud.draw()`, chamado uma vez por frame pela raiz.
- `assets/ui/hud`: banco independente, 20 imagens 32×32 e paleta com nove cores. Os corações usam
um banco 8×8 separado em `assets/ui/life`.
- `src/scene`: posiciona os tiles na caixa NES; layer 0, abaixo de Link/espada.
- Cada stage continua dona do terreno e das colisões; o HUD é compartilhado.
A divisão em blocos 32×32 é apenas o formato de publicação no Prometeu. Os
padrões originais continuam 8×8 e estão identificados em `provenance.json`.
O preload usa HUD no glyph slot 2, Link no slot 0 e terreno no slot 1.
## Origem e composição
Offsets relativos ao PRG, sem o cabeçalho iNES de 16 bytes:
| Dado | Offset | Uso |
| --- | ---: | --- |
| StatusBarStaticsTransferBuf | 107358 | Atributos, caixas, LIFE e ícones |
| LevelInfoOW: mapa do HUD | 103247 | Quatro linhas de oito tiles `$F5` |
| StatusBarTransferBufTemplate | 25863 | Linhas de corações e contadores `$21,$00,$24` |
| Paletas LevelInfoOW | 103171 | Quatro linhas de fundo e quatro de sprites |
| CommonBackgroundPatterns | 34687 | Fonte e elementos da interface |
| CommonMiscPatterns | 36479 | Corações, mapa e ícones finais |
| CommonSpritePatterns | 32895 | Marcador e espada |
O decodificador interpreta os bits de repetição e incremento vertical dos
registros PPU e resolve a paleta pelas quadrantes da attribute table original.
A fixture preenche três corações `$F2` na linha inferior, conforme a ordem de
`FormatHeartsInTextBuf`. O marcador usa sprite `$3E`, na posição visível `(45,52)`
calculada por `UpdatePositionMarker` para a sala `$77`. A espada usa `$20/$21`,
na posição `(152,32)`: o item estreito acrescenta quatro pixels ao X do slot A,
e a coordenada visível considera o deslocamento de uma linha do OAM.
Referências de leitura: `StatusBarStaticsTransferBuf` em
[Z_06.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_06.asm),
`FormatStatusBarText`, `FormatHeartsInTextBuf`, `UpdatePositionMarker` e
`Anim_WriteSpecificItemSprites` em
[Z_01.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_01.asm),
e `DrawStatusBarSword` em
[Z_07.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_07.asm).
Os bytes e imagens são extraídos da ROM do usuário. Os códigos NES de paleta
são preservados; RGBs são aproximações digitais explícitas, como nos assets
anteriores, sem afirmar equivalência a uma saída de vídeo composto.
## Reproduzir e validar
```sh
python3 tools/prepare_hud.py
python3 tools/validate_hud_captures.py
```
O primeiro comando verifica o hash da ROM, extrai o HUD, gera seus 16 PNGs,
registra o asset preservando identidade e escreve a proveniência. O glyph 16
substitui apenas o glyph 12 quando não há espada. É idempotente
para as mesmas entradas e substitui edições manuais dos PNGs gerados.
`hud.png` e `hud@3x.png` permitem inspecionar a composição isolada.
O segundo compara as capturas salvas, sem executar o Studio. Para renová-las,
usar sessões novas do mesmo build e as sequências abaixo:
| Captura | Sequência |
| --- | --- |
| runtime_initial.png | 1 frame sem entrada |
| runtime_down_wall.png | 1 frame sem entrada, depois 200 para baixo |
| runtime_up_edge.png | 200 frames para cima |
| runtime_up_attack.png | Na sessão anterior, 5 frames com A e sem direção |
As quatro capturas abaixo são históricas, anteriores ao inventário; a validação
atual de A vazio/espada adquirida está em `../inventory/validation/results.json`.
Na etapa inicial de render, build/pack passaram, e os três arquivos PBS envolvidos tiveram diagnostics
vazios. As quatro capturas completas corresponderam pixel a pixel à composição
do HUD extraído com cenário e sprites. O teste de ataque confirma que a espada
continua acima do fundo do HUD ao alcançar sua faixa. Resultado em
`runtime-validation.json`. A validação não executa o jogo completo num emulador
NES. As capturas antigas em `../overworld/start/` são anteriores a este HUD.