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

126 lines
6.5 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.
# Primeira stage do overworld
Sala `$77` da primeira campanha, extraída da ROM local verificada. O layout
usado é `$72`. A entrega cobre somente o terreno: pedras, chão, caminhos e
entrada da caverna. `room.png` preserva a faixa superior preta como fonte de
terreno; o jogo desenha nessa faixa o [HUD compartilhado](../../hud/README.md).
Há colisão de terreno e conexão de ida e volta com a
[caverna inicial](../../cave/start/README.md). Inimigos e outras salas ainda
não estão implementados.
O controle e o ataque de Link continuam disponíveis para inspecionar o render.
A posição de teste anterior de Link foi mantida; esta etapa não implementa a
sequência de entrada do jogo nem o inventário inicial da ROM.
## Dados extraídos
- `room.png`: composição 256×240 com a área do HUD reservada.
- `room@3x.png`: ampliação sem suavização para inspeção.
- `tiles/`: os 21 padrões 8×8 com a paleta usada nesta sala.
- `room.json`: mapa de tiles, paletas NES, descritores e bytes comprimidos
de cada coluna, offsets PRG e hash da ROM.
- `runtime_initial.png`: captura real do cenário no Prometeu, dentro da caixa.
- `runtime_no_collision_left.png`: registro histórico anterior às colisões.
- `runtime_attack_over_terrain.png`: corpo e espada acima do cenário.
- `runtime-validation.json`: resultado das três comparações pixel a pixel.
## Decodificação
A identificação da sala vem de `LevelInfoOW`, no offset PRG `103215`.
O atributo D da sala seleciona o layout `$72` na tabela `RoomLayoutsOW`.
Cada um dos 16 descritores de coluna seleciona um grupo e uma coluna comprimida.
Os bytes de cada coluna produzem 11 blocos de 16×16; o bit `$40` repete um bloco.
Os blocos selecionam quatro padrões 8×8 pelas tabelas Primary/SecondarySquaresOW.
Os padrões de fundo são reconstruídos com os blocos CommonBackgroundPatterns,
PatternBlockOWBG e CommonMiscPatterns. As paletas externa e interna desta sala
selecionam a mesma linha NES 2: `$0F, $1A, $37, $12`. Os códigos são originais;
os RGBs são aproximações digitais explícitas, seguindo o critério usado nos
assets de Link. Não há uma captura de PPU/emulador NES usada como referência
de saída RGB neste teste.
Referências de formato e algoritmo:
[Z_05.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_05.asm)
(LayoutRoomOW, WriteSquareOW, FillPlayAreaAttrs) e
[Z_06.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_06.asm)
(dados do overworld e diretório de colunas). Os bytes gráficos e de mapa são
lidos da ROM do usuário, não baixados dessas referências.
## Assets e composição
`assets/tilesets/overworld` contém o banco de terreno, com 21 glyphs 8×8.
`assets/scenes/overworld_start` contém a cena 32×30, com o terreno na camada 0.
Link e a espada são emitidos na camada 1 para ficarem acima do cenário.
A cena vazia anterior em `assets/scenes/movement` foi preservada e excluída
do build. O preload confirmado é Link no glyph slot 0, terreno no glyph slot 1
e sala inicial no scene slot 0.
A câmera recebe `(-112, -15)`, posicionando o cenário no mesmo retângulo
256×240 usado pelos sprites. A moldura e a máscara externas continuam sob
responsabilidade de `Scene.draw_frame()`. Os PNGs do jogo não são ampliados.
## Reproduzir
Na raiz, com Python 3 e Pillow:
```sh
python3 tools/extract_start_room.py
python3 tools/prepare_start_room.py
```
O primeiro comando apenas extrai e documenta os dados. O segundo também
regenera o banco e a requisição de publicação da cena e atualiza a participação
dos assets no build, preservando suas identidades. Esses arquivos são gerados;
regenerar substitui eventuais edições manuais dos tiles e do mapa desta sala.
O build e os diagnostics PBS passaram. Três capturas reais foram comparadas
com a composição dos pixels extraídos mais os sprites já existentes. Os testes
confirmaram alinhamento, ordem de desenho, ausência de rastros, movimento sem
colisão de terreno e permanência da sala ao chegar à borda. Não foi feita uma
comparação contra execução em um emulador NES.
## Stage e colisões
`src/stages/overworld_start` possui o vínculo do cenário e os dados brutos de
colisão da sala `$77`. Cada próxima tela terá sua própria stage.
`src/stage` concentra o acesso à stage ativa e a sonda do jogador; `src/scene`
continua responsável pela câmera, viewport e moldura. Link depende somente
da API `Stage`, sem conhecer `OverworldStart` ou seus tiles.
A colisão usa os IDs NES originais, preservados antes da compactação dos glyphs.
A rotina `GetCollidingTileMoving` / `GetCollidableTile` em Z_07 usa o ponto
`ObjY + $0B`, offsets por direção e duas amostras horizontais ao andar para
cima/baixo. Escolhe o maior ID bruto antes de normalizar as nove exceções
transitáveis para `$26`; IDs a partir de `$89` bloqueiam. A consulta acontece
na grade de 8 pixels. Direcionais simultâneos consideram os caminhos livres,
mantendo a ordem do overworld; um único direcional bloqueado ainda anima Link.
As bordas externas continuam fechadas nos limites anteriores. A entrada da
caverna agora dispara em `(64,77)`, com retorno à mesma abertura. Ver a
documentação da stage da caverna para os percursos automáticos. As capturas
desta pasta são anteriores a essa conexão. O caso especial de parede falsa da sala
`$1F` não se aplica a esta stage. Não há colisão de espada com inimigos.
`tools/sync_start_stage.py`, também executado por `prepare_start_room.py`,
regenera `room.generated.pbs` e `collision-data.json`, conferindo o hash e as
tabelas da ROM. Para reproduzir a verificação independente:
```sh
python3 tools/sync_start_stage.py
python3 tools/validate_collision_rom.py
python3 tools/validate_stage_captures.py
```
A primeira validação executa uma porção limitada de instruções 6502 diretamente
dos bytes da ROM, na entrada `$EDFA`: 2.573 sondas da grade coincidiram com o
modelo do port. Exclui a sonda superior fora da área de terreno, transições e
execução completa do jogo. Resultado em `collision-rom-validation.json`.
A segunda compara as capturas reais obtidas pelo Studio em
`collision-validation/` com o cenário extraído e os sprites nas posições do
modelo: 14 casos, zero pixels diferentes. Cobre paredes, limites, canto com
duas direções bloqueadas, seleção de direção livre, repouso, reversão e caverna.
O script compara as capturas salvas; novas capturas exigem executar as sequências
em `CASES` pelo runtime do Studio, com uma sessão nova por caso.
Build/pack passaram e os sete arquivos PBS envolvidos tiveram diagnostics vazios.