chore: version Zelda 1 port and engineering records

This commit is contained in:
Nilton Constantino
2026-11-16 15:22:13 +00:00
commit 6f2fa420c2
4282 changed files with 822198 additions and 0 deletions
+93
View File
@@ -0,0 +1,93 @@
# Expansão do overworld
O catálogo `tools/overworld_manifest.json` liga os IDs internos às salas NES.
Cada tela mantém stage, dados de colisão e render em `src/stages`; o módulo
`src/overworld` fornece metadados e conexões, e `src/stage` coordena a rolagem.
| Stage | Sala NES | Tela |
|---|---|---|
| 0 | $77 | Inicial |
| 2 | $67 | Norte |
| 3 | $66 | Noroeste |
| 4 | $65 | Noroeste 2 |
| 5 | $64 | Campo de bombas |
| 6 | $57 | Norte superior oeste |
| 7 | $58 | Norte superior leste |
| 8 | $68 | Leste da sala norte |
| 9 | $78 | Leste da sala inicial |
| 12 | $56 | Oeste 1 |
| 13 | $55 | Oeste 2 |
| 14 | $54 | Oeste 3 |
| 15 | $44 | Loja oeste |
A stage 1 continua sendo a caverna da espada. A stage 10 é a caverna secreta
da $67 (Moblin/30 rupias), acessível após bombardear a parede superior;
ver [real-secret.md](real-secret.md). O percurso novo permite
$77 → $78 → $68 → $58 → $57; $68 também liga a $67. Não há ligação direta
$67 → $57: a borda é sólida na ROM. As conexões são extraídas por adjacência
nativa e aberturas compartilhadas, sem criar portas em paredes.
As quatro salas novas usam listas nativas de Octoroks vermelhos $07/$08.
A flag de entrada pelas bordas vem do atributo F, bit 3. A busca percorre o
perímetro no sentido anti-horário, mantém o cursor entre visitas, rejeita
areia >= $84 e tenta novamente quando Link está a menos de $22 nos dois eixos.
Atores nascem em ordem descendente, sem nuvem; o atraso usa o timer longo
nativo e não repõe inimigos mortos durante a visita. O histórico de seis salas
e as flags persistentes continuam em `src/world`, com os IDs nativos.
Scenes 13, 14 e 15 continuam sendo, respectivamente, atlas de salas,
rolagens e inventário. O atlas de terreno usa quatro paletas e 35 glyphs;
o inventário possui 16 faixas. Nenhum novo slot de scene foi criado.
HUD e fundo congelado do inventário seguem a sala ativa. A área NES permanece
256×240 em escala 1:1. O save v1 e app_id permanecem os mesmos: já incluem as
128 flags do overworld. Nenhum perfil de teste deve ser escrito no cartão padrão.
## Regeneração
Executar `python3 tools/prepare_overworld.py` após regenerar assets de HUD,
salas ou inventário. Esse comando extrai as 13 salas da ROM local verificada,
recria stages gerenciadas, metadados, atlas, marcadores e inventário.
A stage inicial é mantida manualmente, incluindo os testes temporários
explicitamente desativados. Os entrypoints antigos prepare_north e
prepare_bomb_route terminam com a recomposição deste catálogo.
## Validação
`python3 tools/validate_overworld.py` executa sondas de colisão da ROM
para as 13 salas e a rotina 6502 FindNextEdgeSpawnCell para as quatro novas.
O oráculo é limitado às rotinas alcançadas, não é um emulador NES completo.
`tools/generate_overworld_fixture.py install` instala uma entrada temporária,
com cópias em `.tmp/overworld-fixture`. Compilar pelo Studio e avançar conforme
`cases.json`; capturar em `extracted/overworld/expansion/validation`.
A fixture confere as 30 transições direcionadas, nascimento dos inimigos,
limpeza/histórico e marcadores de asserção. Depois executar
`python3 tools/generate_overworld_fixture.py restore`, recompilar o jogo e
validar diagnostics. Nunca devolver a fixture instalada.
`python3 tools/validate_overworld_captures.py` compara terreno, inventário,
HUD e destinos das transições com os PNGs extraídos.
## Limites deste recorte
As cavernas, NPCs e segredos das quatro salas novas ainda não têm interação.
A paisagem e suas colisões são nativas; não substituir essas entradas por
uma cópia da caverna inicial. Outras bordas externas permanecem sem destino
até portar suas salas e tipos de inimigos.
A sala $65 possui flag de Zora, agora atendida pelo módulo
`src/enemies/zora`; detalhes em [zora.md](zora.md). As quatro
salas adicionadas não possuem essa flag. Som continua fora desta wave.
## Loja da sala $66
Entrada aberta (112,77) ligada à stage 11 `cave_shop` ($78), com retorno à $66.
Escudo mágico 160, chave 100, vela azul 60; ver [shop.md](shop.md). Continuam
nove salas OW; agora três interiores, sem novos slots de scene.
## Percurso oeste até a loja $44
Expansão $57↔$56↔$55↔$54↔$44, mais $55↔$65 e $54↔$64. Total atual:
13 salas, 15 ligações reversíveis e quatro interiores. Zora também nas salas
$56/$55/$54; $44 não possui a flag. A loja $77 é a stage 16, vinculada à 15,
com entrada aberta (64,77), bombas 20, escudo 130 e flechas 80. Nenhum slot
adicional de scene. Detalhes/limites/evidência em [west-route.md](west-route.md).