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

115 lines
6.4 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.
# Stage da caverna inicial
A stage `@zelda1:stages/cave_start` usa `RoomLayoutOWCave0` da ROM local
verificada. Tem cenário e mapa de colisão próprios, conectados à abertura da
sala `$77` do overworld. HUD e viewport 256×240 continuam compartilhados em 1:1.
Para entrar, caminhe para cima na abertura da parede do primeiro mapa. Para
sair, caminhe para baixo pela abertura central do piso da caverna. Link retorna
à mesma porta. Parar nessa posição não provoca reentrada: é preciso sair da
célula e voltar, preservando a regra de `UndergroundExitType`.
## O que foi portado
- Layout e compressão das colunas da caverna, usando as tabelas do overworld.
- Paletas próprias da caverna e atributos de fundo equivalentes à sala `$44`.
- Colisão de terreno com os mesmos IDs e sondas NES do overworld.
- Gatilho alinhado da entrada em `(64,77)`; descida de 16 pixels, um pixel a
cada quatro ticks, com o corpo atrás dos pixels não transparentes do cenário.
- Posicionamento interno em `(112,221)`, olhando para cima, seguido da caminhada
forçada de 48 pixels até `(112,173)`, com a velocidade fracionária original.
- Saída inferior em `Y=221`; retorno a `(64,93)`, olhando para baixo, e subida
automática até `(64,77)` atrás do cenário, também um pixel a cada quatro ticks.
- Troca do scene bank antes da emissão de HUD e personagem, sem misturar os mapas.
A primeira espada agora é coletável e Link começa sem ela. A aquisição atualiza
`Items[0]`, apaga texto e item do piso, ergue a espada e faz o velho desaparecer.
A flag da sala impede respawn na mesma partida. Ver
[inventário e primeira aquisição](../../inventory/README.md).
O fogo permanece estático e o texto inicial aparece inteiro. Não há diálogo
progressivo ou som. As fogueiras agora causam dano; ver
[sistema de vida](../../life/README.md). Os waits de transferência PPU e cópia progressiva da
tela NES não são emulados: o cenário é trocado de uma vez.
## Organização
| Local | Responsabilidade |
| --- | --- |
| `src/stages/cave_start/` | Vínculo do scene bank 1, terreno e condição de saída |
| `src/stages/overworld_start/` | Terreno original e condição da entrada |
| `src/stage/flow.pbs` | Máquina de transição, posições forçadas e proteção contra reentrada |
| `src/stage/player_probe.pbs` | Sonda NES compartilhada, consultando a stage ativa |
| `src/scene/main.pbs` | Rebind da stage e câmera quando muda a tela |
| `src/link/` | Aplica as posições forçadas, mantém animação e desenha o corpo |
| `assets/tilesets/cave_start/` | 44 glyphs 8×8, paleta de sete cores |
| `assets/scenes/cave_start/` | Cena 32×30, fundo na camada 0 |
| `assets/characters/link_door/` | 68 poses 16×16 para prioridade atrás do cenário |
Os slots existentes foram preservados: Link 0, terreno do overworld 1 e HUD 2.
Terreno da caverna ocupa glyph slot 3; poses da porta, slot 4; aquisição, slot 5.
Scenes: overworld 0, caverna antes da coleta 1, com velho pós-coleta 2 e vazia 3. Link e espada continuam na camada 1; o HUD permanece na camada 0.
As poses da porta são derivadas dos sprites existentes: para cada posição e
fase, pixels são tornados transparentes onde o índice original de fundo NES é
diferente de zero. Isso reproduz a prioridade sprite/background nesse local,
sem confundir RGB preto com transparência. Não é uma alteração dos sprites de
caminhada usados durante o jogo normal.
## Proveniência
`room.json` registra hash da ROM, colunas, mapa de IDs antes de qualquer
composição visual, paletas NES, padrões decorativos e posições do texto.
`terrain.png` contém apenas o terreno; `room.png` acrescenta a decoração estática.
`room@3x.png` permite inspeção sem suavização. A colisão usa o primeiro mapa,
portanto os pixels do texto e das fogueiras não se tornam paredes.
`RoomLayoutOWCave0` está no offset PRG `89000`. A paleta vem de
`CaveBgPaletteRowsTransferBuf`, offset `107101`. Os atributos A/B da sala `$44`
selecionam, respectivamente, as linhas 3 e 2. O texto vem da primeira entrada
original de `PersonTextAddrs`, em `PersonText`; os controles de quebra de linha
são decodificados, sem redesenhar a fonte. O velho usa tile `$98` espelhado,
fogueiras `$5C` espelhado, espada `$20/$21`; as posições consideram o Y visível
do OAM. RGBs continuam aproximações digitais explícitas dos códigos NES.
Rotinas de referência consultadas nos fontes locais do disassembly:
[Z_05.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_05.asm)
(`LayoutRoomOrCaveOW`, `CheckWarps`, `HandleWarpOW`, `InitMode_EnterRoom`,
`InitMode_WalkCave`, `CheckCaveEdge`),
[Z_01.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_01.asm)
(`InitModeB_EnterCave_Bank5`, `SetUpCommonCaveObjects`, tabelas de animação e texto),
e [Z_07.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_07.asm)
(`StepOutside`, `GetCollidingTileMoving`, `PlayerScreenEdgeBounds`).
## Regeneração e validação
```sh
python3 tools/prepare_cave.py
python3 tools/validate_cave.py
```
O gerador verifica a ROM, publica os assets preservando suas identidades e
regenera somente `src/stages/cave_start/room.generated.pbs`. As demais fontes
PBS são mantidas manualmente. Reexecutar com as mesmas entradas é idempotente;
edições manuais nos PNGs gerados são substituídas.
O validador executa a rotina 6502 de colisão com as colunas da caverna: 2.573
sondas coincidiram com o modelo do port. Depois compara 20 capturas reais do
Studio com os cenários extraídos e os sprites em posições/fases explícitas:
zero pixels diferentes. Inclui entrada, prioridade atrás do cenário, spawn,
caminhada forçada, paredes, retorno, repouso sem reentrada e segunda visita.
Resultado: `validation/results.json`.
As capturas são uma sequência contínua descrita em `CHECKPOINTS` de
`tools/validate_cave.py`, começando com uma sessão nova. O script compara os PNGs
salvos; não os recaptura. Algumas posições ficam um pixel antes/depois da grade
por carry/borrow do movimento fracionário, como `(65,133)` e `(111,173)`;
curvas usam as regras da grade, sem arredondar artificialmente essas posições.
As 20 capturas desta pasta registram a etapa anterior ao inventário, com
espada já disponível. A validação vigente da aquisição está em
`../../inventory/validation/results.json`.
Na etapa de conexão, build e pack passaram. Os 11 arquivos PBS envolvidos tiveram diagnostics
vazios. Isso não equivale a comparar a execução completa com um emulador NES.