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
+116
View File
@@ -0,0 +1,116 @@
# Inventário NES — primeira aquisição de espada
Link começa sem espada. Entre na caverna inicial e caminhe até a espada:
a coleta ocorre por contato, sem apertar A. Link ergue o item, o slot A do HUD
é preenchido e o ataque fica disponível depois da pose. Sair e voltar mantém
a aquisição durante a partida; uma nova execução começa novamente sem espada.
## Estrutura da ROM preservada
`src/inventory` mantém o bloco `Items` com os **40 slots originais**, em vez de
um booleano separado para esta espada. `items.generated.pbs` contém as tabelas
`ItemIdToSlot` e `ItemIdToDescriptor`, com os 36 IDs originais. No descritor,
o nibble alto define a classe e o baixo define valor, quantidade ou grau.
A aquisição implementada nesta iteração é a de espada, classe 2:
| Item ID | Slot | Descritor | Valor em Items[0] |
| --- | --- | --- | --- |
| 1 | 0 | `$21` | 1, espada de madeira |
| 2 | 0 | `$22` | 2, espada branca |
| 3 | 0 | `$23` | 3, espada mágica |
Zero significa ausência da espada. `HandleClass2` só grava se o grau recebido
for maior ou igual ao atual. Uma espada inferior ainda é consumida pela
coleta, mas não rebaixa o inventário. Somente a espada de madeira está colocada
no mundo; visuais e efeitos dos demais equipamentos não foram implementados.
As tabelas completas estão preservadas como base para os próximos itens, sem
simular os efeitos especiais das classes 0 e 1 antes de portá-los.
O reset segue o código de nova partida da ROM: zera os 40 bytes e inicializa
`Items[$18]=$22` (três corações/recipientes), `Items[$19]=$FF` (fração de vida)
e `Items[$25]=8` (capacidade de bombas). Dano, cura e HUD de corações agora usam esses bytes; ver
[sistema de vida](../life/README.md). Os objetos de cura ainda não estão
colocados no mundo.
`src/world` mantém os 128 bytes de flags de salas do overworld. A aquisição usa
o bit `$10` da sala `$77`, separado de `Items`. Assim, o estado de um item de
sala não é inferido apenas do nível atual da espada. Outros bits do byte são
preservados ao marcar a aquisição. Não há gravação em disco/memcard ainda.
## Comportamento da primeira caverna
A condição de coleta vem de `UpdateCavePersonState_TalkOrShopOrDoorCharge`:
`ObjX=120` e `abs(ObjY-152)<6`. A borda `Y=158` ainda não coleta;
`Y=157` já coleta. O X visual da espada é 124 devido ao alinhamento de um
sprite estreito, mas a coordenada de contato usa 120, como na ROM.
A aquisição marca a sala e atualiza `Items[0]` no mesmo frame. O item no piso
e o texto desaparecem. O velho pisca durante o contador de 64 frames e então
some; nas visitas seguintes, não há velho, texto ou espada, mas as fogueiras
continuam presentes. O texto inicial continua aparecendo inteiro, sem a
progressão de diálogo da ROM, e o fogo permanece estático. Não há som.
`TakeItem` arma um contador de 128 frames. `CheckLiftItem` decrementa antes
do desenho: a pose aparece nos ticks 1–127, e o estado normal retorna no tick
128. A movimentação e o ataque ficam suspensos durante esse período. Segurar
A durante a pose não sintetiza um novo pressionamento ao terminá-la.
O desenho usa os tiles originais `$78/$79` à esquerda e `$08/$09` à direita,
com espelhamento horizontal na metade direita e a espada `$20/$21` erguida
com uma mão. A troca do tile direito em `DrawLinkLiftingItem` preserva o
atributo OAM `$40` definido por `Anim_WriteMirroredSpritePair`. O tile `$78` vem do bloco de demo
residente em CHR `$0700..$08DF`, preservado quando o overworld carrega a partir
de `$08E0`. A reconstrução `extracted/graphics/ppu/overworld_sprites.png` foi
corrigida para incluir esse resíduo. O desenho da pose usa o deslocamento OAM
de uma linha, sem os dois pixels adicionais da caminhada do overworld.
## Organização e APIs
- `Inventory.reset/read_slot/sword_level/take_sword`: acesso ao bloco Items e
aquisição de espada pelos descritores da ROM.
- `WorldFlags.reset/room_item_taken/mark_room_item_taken`: flags da sala.
- `CavePickup`: contato com o item, flag de aquisição e contador do velho.
- `Link.update`: controle, aquisição e duração da pose; `Link.draw`: corpo/arma.
- `Hud.draw`: escolhe o tile com ou sem espada a partir de `Items[0]`.
- `Stage.render_revision`: atualiza o visual da caverna sem confundir a revisão
visual com a identidade da stage usada por colisões e transições.
Os bancos existentes mantiveram seus IDs e slots. A pose de aquisição usa
`assets/characters/link_pickup`, glyph slot 5. Os glyphs 0–15 do HUD continuam
iguais; o glyph 16 substitui apenas a região do slot A quando não há espada.
As variantes de caverna usam scene slots 1 (antes), 2 (velho sem texto/item)
e 3 (após o velho sumir), compartilhando o mesmo banco de 44 glyphs.
## Evidências e reprodução
```sh
python3 tools/prepare_inventory.py
python3 tools/prepare_hud.py
python3 tools/prepare_cave.py
python3 tools/validate_inventory.py
```
Os geradores verificam o hash da ROM e são idempotentes para as mesmas entradas.
Preservam identidades dos assets; substituem os PNGs e fontes marcados como
gerados. `rom-data.json` registra tabelas, defaults, offsets e condições da coleta.
`validation/sequence.json` registra as entradas e o build de duas sessões reais
do Studio. O validador compara as capturas salvas, sem recapturá-las: 28 frames
completos coincidiram pixel a pixel. Inclui A sem espada, a borda de coleta,
a pose em 1/127/128, bloqueio dos comandos, A mantido, ataque adquirido,
retorno ao overworld, segunda visita sem respawn e nova partida restaurando o item.
O validador também confere as tabelas contra os bytes da ROM e executa uma
porção limitada da rotina 6502 `HandleClass2` em 12 combinações de grau anterior
e recebido. Isso verifica a regra de não rebaixamento na ROM; o percurso do
guest exercita a aquisição 0→1. Não equivale à execução completa num emulador NES.
Build/pack passaram e os 15 arquivos PBS envolvidos tiveram diagnostics vazios.
Referências locais consultadas: `ItemIdToSlot`, `ItemIdToDescriptor`, `TakeItem`,
`HandleClass2`, coleta da caverna e suas flags em
[Z_01.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_01.asm);
reset do bloco Items em
[Z_02.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_02.asm);
`CheckLiftItem` e `DrawLinkLiftingItem` em
[Z_07.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_07.asm).
Binary file not shown.

After

Width:  |  Height:  |  Size: 687 B

+146
View File
@@ -0,0 +1,146 @@
{
"rom_sha256": "89232edf4f9b52e3cb872094bc78973de080befca2ddea893b6e936066514d4e",
"items_length": 40,
"item_slots": [
1,
0,
0,
0,
6,
5,
4,
4,
2,
2,
3,
13,
9,
12,
27,
28,
8,
10,
11,
11,
14,
15,
16,
17,
22,
23,
24,
26,
31,
29,
30,
7,
7,
21,
25,
20
],
"item_descriptors": [
20,
33,
34,
35,
1,
1,
33,
34,
33,
34,
1,
1,
1,
1,
1,
21,
1,
1,
33,
34,
1,
1,
1,
1,
17,
17,
16,
1,
1,
1,
1,
17,
34,
1,
16,
18
],
"new_game_items": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
34,
255,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
8,
0,
0
],
"prg_offsets": {
"item_slots": 27412,
"item_descriptors": 27448,
"new_game": 44915
},
"lift": {
"body_left_tile": 120,
"body_right_tile": 8,
"body_left_flip_x": false,
"body_right_flip_x": true,
"item_tile": 32,
"timer": 128,
"residual_chr_source": "demo_sprites",
"left_tile_prg_offset": 20020
},
"cave_pickup": {
"room_id": 119,
"room_item_mask": 16,
"x": 120,
"item_y": 152,
"vertical_distance_exclusive": 6,
"person_disappear_timer": 64
},
"scope": "NES Items layout/tables, sword grades 0..3, OW room flags and wooden sword acquisition. Other item effects and disk persistence are not implemented."
}
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: 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: 48 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: 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: 45 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 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: 45 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: 45 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: 46 KiB

@@ -0,0 +1,12 @@
{
"build_id": "d0b60714-84e7-40da-b7f8-1f306f5bdb27",
"correction": "Preserve right OAM horizontal-flip attribute when replacing the lifting sprite with tile $08.",
"recaptured": [
"pickup_first",
"lift_input_lock",
"lift_tick127",
"lift_tick128"
],
"right_half_verified_against_original_chr": true,
"full_frame_different_pixels": 0
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

+380
View File
@@ -0,0 +1,380 @@
{
"rom_sha256": "89232edf4f9b52e3cb872094bc78973de080befca2ddea893b6e936066514d4e",
"rom_tables_verified": true,
"items_slots": 40,
"room_item_mask": 16,
"captures_compared": 28,
"equipment_grade_rom_cases": [
{
"before": 0,
"taken_grade": 1,
"after": 1
},
{
"before": 0,
"taken_grade": 2,
"after": 2
},
{
"before": 0,
"taken_grade": 3,
"after": 3
},
{
"before": 1,
"taken_grade": 1,
"after": 1
},
{
"before": 1,
"taken_grade": 2,
"after": 2
},
{
"before": 1,
"taken_grade": 3,
"after": 3
},
{
"before": 2,
"taken_grade": 1,
"after": 2
},
{
"before": 2,
"taken_grade": 2,
"after": 2
},
{
"before": 2,
"taken_grade": 3,
"after": 3
},
{
"before": 3,
"taken_grade": 1,
"after": 3
},
{
"before": 3,
"taken_grade": 2,
"after": 3
},
{
"before": 3,
"taken_grade": 3,
"after": 3
}
],
"checkpoints": [
{
"checkpoint": "initial",
"room_variant": 0,
"x": 120,
"y": 133,
"direction": "down",
"phase": 0,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "unarmed_a",
"room_variant": 0,
"x": 120,
"y": 133,
"direction": "down",
"phase": 0,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "release_initial",
"room_variant": 0,
"x": 120,
"y": 133,
"direction": "down",
"phase": 0,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "approach_left",
"room_variant": 0,
"x": 65,
"y": 133,
"direction": "left",
"phase": 1,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "door_ready",
"room_variant": 0,
"x": 64,
"y": 77,
"direction": "up",
"phase": 0,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "cave_ready",
"room_variant": 1,
"x": 112,
"y": 173,
"direction": "up",
"phase": 1,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "cave_unarmed_a",
"room_variant": 1,
"x": 112,
"y": 173,
"direction": "up",
"phase": 1,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "cave_release",
"room_variant": 1,
"x": 112,
"y": 173,
"direction": "up",
"phase": 1,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "align_sword",
"room_variant": 1,
"x": 120,
"y": 173,
"direction": "right",
"phase": 0,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "outside_pickup",
"room_variant": 1,
"x": 120,
"y": 158,
"direction": "up",
"phase": 0,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "pickup_first",
"room_variant": 2,
"x": 120,
"y": 157,
"direction": "up",
"phase": 0,
"sword_level": 1,
"action": "lift",
"different_pixels": 0
},
{
"checkpoint": "lift_input_lock",
"room_variant": 2,
"x": 120,
"y": 157,
"direction": "up",
"phase": 0,
"sword_level": 1,
"action": "lift",
"different_pixels": 0
},
{
"checkpoint": "lift_tick127",
"room_variant": 3,
"x": 120,
"y": 157,
"direction": "up",
"phase": 0,
"sword_level": 1,
"action": "lift",
"different_pixels": 0
},
{
"checkpoint": "lift_tick128",
"room_variant": 3,
"x": 120,
"y": 157,
"direction": "up",
"phase": 0,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "held_a_after_lift",
"room_variant": 3,
"x": 120,
"y": 157,
"direction": "up",
"phase": 0,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "release_lift",
"room_variant": 3,
"x": 120,
"y": 157,
"direction": "up",
"phase": 0,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "armed_attack",
"room_variant": 3,
"x": 120,
"y": 157,
"direction": "up",
"phase": 0,
"sword_level": 1,
"action": "attack",
"different_pixels": 0
},
{
"checkpoint": "attack_recovered",
"room_variant": 3,
"x": 120,
"y": 157,
"direction": "up",
"phase": 1,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "exit_ready",
"room_variant": 0,
"x": 64,
"y": 93,
"direction": "down",
"phase": 0,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "exit_start",
"room_variant": 0,
"x": 64,
"y": 92,
"direction": "down",
"phase": 0,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "overworld_owned",
"room_variant": 0,
"x": 64,
"y": 77,
"direction": "down",
"phase": 0,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "walk_away",
"room_variant": 0,
"x": 64,
"y": 85,
"direction": "down",
"phase": 1,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "return_door",
"room_variant": 0,
"x": 64,
"y": 77,
"direction": "up",
"phase": 0,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "cave_revisited",
"room_variant": 3,
"x": 112,
"y": 173,
"direction": "up",
"phase": 1,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "realign",
"room_variant": 3,
"x": 120,
"y": 173,
"direction": "right",
"phase": 0,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "no_second_pickup",
"room_variant": 3,
"x": 120,
"y": 157,
"direction": "up",
"phase": 0,
"sword_level": 1,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "new_game",
"room_variant": 0,
"x": 120,
"y": 133,
"direction": "down",
"phase": 0,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
},
{
"checkpoint": "new_game_cave",
"room_variant": 1,
"x": 112,
"y": 173,
"direction": "up",
"phase": 1,
"sword_level": 0,
"action": "walk",
"different_pixels": 0
}
],
"scope": "Live guest path: unarmed inputs, exact pickup threshold, lift at ticks 1/127/128, input lock, held-A edge, armed attack, room-flag persistence on reentry. Inventory tables/defaults checked against ROM; other item effects and full NES execution excluded."
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

@@ -0,0 +1,200 @@
{
"build_id": "23c0cf76-bc74-4e33-b8aa-ce59836da0de",
"session_1": [
[
"initial",
1,
{}
],
[
"unarmed_a",
5,
{
"a": true
}
],
[
"release_initial",
1,
{}
],
[
"approach_left",
40,
{
"left": true
}
],
[
"door_ready",
43,
{
"up": true
}
],
[
"cave_ready",
96,
{}
],
[
"cave_unarmed_a",
5,
{
"a": true
}
],
[
"cave_release",
1,
{}
],
[
"align_sword",
6,
{
"right": true
}
],
[
"outside_pickup",
10,
{
"up": true
}
],
[
"pickup_first",
1,
{
"up": true
}
],
[
"lift_input_lock",
5,
{
"down": true,
"a": true
}
],
[
"lift_tick127",
121,
{
"down": true,
"a": true
}
],
[
"lift_tick128",
1,
{
"down": true,
"a": true
}
],
[
"held_a_after_lift",
1,
{
"a": true
}
],
[
"release_lift",
1,
{}
],
[
"armed_attack",
5,
{
"a": true
}
],
[
"attack_recovered",
20,
{}
],
[
"exit_ready",
48,
{
"down": true
}
],
[
"exit_start",
1,
{
"down": true
}
],
[
"overworld_owned",
64,
{}
],
[
"walk_away",
6,
{
"down": true
}
],
[
"return_door",
6,
{
"up": true
}
],
[
"cave_revisited",
96,
{}
],
[
"realign",
6,
{
"right": true
}
],
[
"no_second_pickup",
11,
{
"up": true
}
]
],
"session_2": [
[
"new_game",
1,
{}
],
[
"left",
40,
{
"left": true
}
],
[
"up",
43,
{
"up": true
}
],
[
"new_game_cave",
96,
{}
]
]
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB