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
+114
View File
@@ -0,0 +1,114 @@
# 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.
Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

@@ -0,0 +1,42 @@
[
{
"name": "initial",
"frame": 1
},
{
"name": "menu-initial",
"frame": 2
},
{
"name": "outside-contact",
"frame": 3
},
{
"name": "collected-person",
"frame": 4
},
{
"name": "blink-hidden",
"frame": 5
},
{
"name": "blink-person",
"frame": 6
},
{
"name": "menu-collected",
"frame": 7
},
{
"name": "expired",
"frame": 8
},
{
"name": "revisit",
"frame": 9
},
{
"name": "new-game",
"frame": 10
}
]
Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 39 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 71 KiB

@@ -0,0 +1,55 @@
{
"pixel_checks": [
{
"name": "initial",
"different_pixels": 0
},
{
"name": "outside-contact",
"different_pixels": 0
},
{
"name": "collected-person",
"different_pixels": 0
},
{
"name": "blink-hidden",
"different_pixels": 0
},
{
"name": "blink-person",
"different_pixels": 0
},
{
"name": "expired",
"different_pixels": 0
},
{
"name": "revisit",
"different_pixels": 0
},
{
"name": "new-game",
"different_pixels": 0
},
{
"name": "menu-initial",
"different_pixels": 0
},
{
"name": "menu-collected",
"different_pixels": 0
}
],
"native_collision_probes": 2573,
"gameplay_assertions": [
"contact",
"sword ownership",
"room pickup bit",
"64-frame disappearance",
"menu pause",
"revisit",
"constant scene revision",
"constant inventory variant"
]
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

@@ -0,0 +1,18 @@
{
"production_build": "5e713d48-8d9c-480d-9d35-a9aa112751a8",
"native_pixel_checks": 10,
"native_collision_probes": 2573,
"legacy_glyphs_preserved": 44,
"scene_revision": 1,
"inventory_variant": 1,
"regeneration_unchanged_files": 1176,
"production_smoke": [
"new game",
"cave entry",
"sword pickup/lift",
"person disappears",
"inventory opens"
],
"temporary_bombs_enabled": false,
"user_memcard_written": false
}
+286
View File
@@ -0,0 +1,286 @@
{
"bank": 3,
"terrain_scene": 1,
"parts": [
{
"kind": 1,
"x": 120,
"y": 129,
"glyph": 44
},
{
"kind": 1,
"x": 128,
"y": 129,
"glyph": 45
},
{
"kind": 1,
"x": 120,
"y": 137,
"glyph": 46
},
{
"kind": 1,
"x": 128,
"y": 137,
"glyph": 47
},
{
"kind": 0,
"x": 72,
"y": 129,
"glyph": 48
},
{
"kind": 0,
"x": 80,
"y": 129,
"glyph": 49
},
{
"kind": 0,
"x": 72,
"y": 137,
"glyph": 50
},
{
"kind": 0,
"x": 80,
"y": 137,
"glyph": 51
},
{
"kind": 0,
"x": 168,
"y": 129,
"glyph": 48
},
{
"kind": 0,
"x": 176,
"y": 129,
"glyph": 49
},
{
"kind": 0,
"x": 168,
"y": 137,
"glyph": 50
},
{
"kind": 0,
"x": 176,
"y": 137,
"glyph": 51
},
{
"kind": 2,
"x": 124,
"y": 153,
"glyph": 52
},
{
"kind": 2,
"x": 124,
"y": 161,
"glyph": 53
},
{
"kind": 2,
"x": 48,
"y": 104,
"glyph": 54
},
{
"kind": 2,
"x": 56,
"y": 104,
"glyph": 55
},
{
"kind": 2,
"x": 64,
"y": 104,
"glyph": 56
},
{
"kind": 2,
"x": 72,
"y": 104,
"glyph": 57
},
{
"kind": 2,
"x": 88,
"y": 104,
"glyph": 58
},
{
"kind": 2,
"x": 96,
"y": 104,
"glyph": 59
},
{
"kind": 2,
"x": 104,
"y": 104,
"glyph": 60
},
{
"kind": 2,
"x": 112,
"y": 104,
"glyph": 61
},
{
"kind": 2,
"x": 120,
"y": 104,
"glyph": 62
},
{
"kind": 2,
"x": 128,
"y": 104,
"glyph": 63
},
{
"kind": 2,
"x": 136,
"y": 104,
"glyph": 64
},
{
"kind": 2,
"x": 144,
"y": 104,
"glyph": 65
},
{
"kind": 2,
"x": 152,
"y": 104,
"glyph": 57
},
{
"kind": 2,
"x": 168,
"y": 104,
"glyph": 55
},
{
"kind": 2,
"x": 176,
"y": 104,
"glyph": 64
},
{
"kind": 2,
"x": 192,
"y": 104,
"glyph": 61
},
{
"kind": 2,
"x": 200,
"y": 104,
"glyph": 64
},
{
"kind": 2,
"x": 64,
"y": 112,
"glyph": 59
},
{
"kind": 2,
"x": 72,
"y": 112,
"glyph": 66
},
{
"kind": 2,
"x": 80,
"y": 112,
"glyph": 64
},
{
"kind": 2,
"x": 88,
"y": 112,
"glyph": 60
},
{
"kind": 2,
"x": 96,
"y": 112,
"glyph": 62
},
{
"kind": 2,
"x": 104,
"y": 112,
"glyph": 67
},
{
"kind": 2,
"x": 120,
"y": 112,
"glyph": 55
},
{
"kind": 2,
"x": 128,
"y": 112,
"glyph": 59
},
{
"kind": 2,
"x": 136,
"y": 112,
"glyph": 68
},
{
"kind": 2,
"x": 144,
"y": 112,
"glyph": 62
},
{
"kind": 2,
"x": 160,
"y": 112,
"glyph": 55
},
{
"kind": 2,
"x": 168,
"y": 112,
"glyph": 69
},
{
"kind": 2,
"x": 176,
"y": 112,
"glyph": 54
},
{
"kind": 2,
"x": 184,
"y": 112,
"glyph": 57
},
{
"kind": 2,
"x": 192,
"y": 112,
"glyph": 70
}
],
"legacy_scenes_reserved": [
2,
3
]
}
File diff suppressed because it is too large Load Diff
Binary file not shown.

After

Width:  |  Height:  |  Size: 2.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 8.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.0 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

@@ -0,0 +1,267 @@
{
"rom_sha256": "89232edf4f9b52e3cb872094bc78973de080befca2ddea893b6e936066514d4e",
"cave_probes_compared": 2573,
"probe_mismatches": 0,
"runtime_frames_compared": 20,
"checkpoints": [
{
"checkpoint": "initial",
"frames": 1,
"input": {},
"stage": 0,
"x": 120,
"y": 133,
"direction": "down",
"animation_phase": 0,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "approach_left",
"frames": 40,
"input": {
"left": true
},
"stage": 0,
"x": 65,
"y": 133,
"direction": "left",
"animation_phase": 1,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "door_ready",
"frames": 43,
"input": {
"up": true
},
"stage": 0,
"x": 64,
"y": 77,
"direction": "up",
"animation_phase": 0,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "door_start",
"frames": 1,
"input": {},
"stage": 0,
"x": 64,
"y": 77,
"direction": "up",
"animation_phase": 0,
"door_step": 0,
"different_pixels": 0
},
{
"checkpoint": "door_middle",
"frames": 32,
"input": {},
"stage": 0,
"x": 64,
"y": 85,
"direction": "up",
"animation_phase": 1,
"door_step": 8,
"different_pixels": 0
},
{
"checkpoint": "cave_spawn",
"frames": 31,
"input": {},
"stage": 1,
"x": 112,
"y": 221,
"direction": "up",
"animation_phase": 0,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "cave_walk_done",
"frames": 32,
"input": {},
"stage": 1,
"x": 112,
"y": 173,
"direction": "up",
"animation_phase": 1,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "cave_idle",
"frames": 12,
"input": {},
"stage": 1,
"x": 112,
"y": 173,
"direction": "up",
"animation_phase": 1,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "cave_left_wall",
"frames": 200,
"input": {
"left": true
},
"stage": 1,
"x": 32,
"y": 173,
"direction": "left",
"animation_phase": 1,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "cave_right_wall",
"frames": 200,
"input": {
"right": true
},
"stage": 1,
"x": 208,
"y": 173,
"direction": "right",
"animation_phase": 0,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "cave_center",
"frames": 72,
"input": {
"left": true
},
"stage": 1,
"x": 111,
"y": 173,
"direction": "left",
"animation_phase": 0,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "cave_exit_ready",
"frames": 36,
"input": {
"down": true
},
"stage": 1,
"x": 112,
"y": 221,
"direction": "down",
"animation_phase": 0,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "exit_start",
"frames": 1,
"input": {
"down": true
},
"stage": 0,
"x": 64,
"y": 93,
"direction": "down",
"animation_phase": 0,
"door_step": 16,
"different_pixels": 0
},
{
"checkpoint": "exit_middle",
"frames": 32,
"input": {},
"stage": 0,
"x": 64,
"y": 85,
"direction": "down",
"animation_phase": 1,
"door_step": 8,
"different_pixels": 0
},
{
"checkpoint": "exit_done",
"frames": 32,
"input": {},
"stage": 0,
"x": 64,
"y": 77,
"direction": "down",
"animation_phase": 1,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "exit_idle",
"frames": 24,
"input": {},
"stage": 0,
"x": 64,
"y": 77,
"direction": "down",
"animation_phase": 1,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "walk_away",
"frames": 6,
"input": {
"down": true
},
"stage": 0,
"x": 64,
"y": 85,
"direction": "down",
"animation_phase": 0,
"door_step": -1,
"different_pixels": 0
},
{
"checkpoint": "return_to_door",
"frames": 6,
"input": {
"up": true
},
"stage": 0,
"x": 64,
"y": 77,
"direction": "up",
"animation_phase": 0,
"door_step": 0,
"different_pixels": 0
},
{
"checkpoint": "reenter_start",
"frames": 1,
"input": {},
"stage": 0,
"x": 64,
"y": 77,
"direction": "up",
"animation_phase": 0,
"door_step": 0,
"different_pixels": 0
},
{
"checkpoint": "cave_again",
"frames": 96,
"input": {},
"stage": 1,
"x": 112,
"y": 173,
"direction": "up",
"animation_phase": 1,
"door_step": -1,
"different_pixels": 0
}
],
"scope": "Original collision leaf routine with cave column RAM; full-frame checkpoints of entry, cave walls, exit, idle without reentry and a second visit. Excludes full-game NES execution, video-copy waits and cave object interactions."
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB