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

117 lines
6.3 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.
# 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).