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
+226
View File
@@ -0,0 +1,226 @@
<!-- ai-engineering:start -->
## Engineering protocol
This project uses AI Engineering. Read `.ai-engineering/README.md` and
`.ai-engineering/protocol.json` before engineering work. Run `aie status` and
`aie next-actions`, then load the selected Work with `aie work context <WRK>`.
Use `ai-engineering` if the `aie` alias is unavailable; without a CLI, read the
portable files directly. Preserve the project rules outside this block.
Never infer human approval; record it explicitly before significant commitments.
<!-- ai-engineering:end -->
# Orientações deste projeto
- Para usar ou ajustar o AI Engineering, consultar somente a CLI e sua
documentação pública. Não ler os fontes Java do projeto AI Engineering.
Expor lacunas de informação com evidência, impacto e sugestão para melhoria
posterior, sem preenchê-las por investigação da implementação interna.
- Durante o port de Zelda 1, manter `docs/prometeu-feedback.md` atualizado com
facilidades e dificuldades concretas de interface e produção do Prometeu,
conforme solicitado pelo usuário.
- Registrar evidência, impacto e sugestão; distinguir sintomas observados de
causas ainda não confirmadas. Preservar também os aspectos positivos.
- Consolidar ocorrências do mesmo problema e marcar correções revalidadas.
- Não tratar uma dificuldade do agente como defeito visual de uma interface
que não foi inspecionada. Este registro não substitui o trabalho do jogo.
- Para dúvidas de PBS, consultar primeiro referências e exemplos pelo Studio.
Recorrer às fontes Java apenas para lacunas, contradições ou investigação de
defeitos, registrando o motivo quando isso dificultar a produção.
- Manter o personagem em `src/link` e a cena em `src/scene`, com as APIs públicas
declaradas nos respectivos barrels. O identificador técnico do projeto é
`zelda1`; a pasta continua se chamando `zelda-1`.
- Preservar a área NES de 256×240 em escala 1:1, centralizada na caixa de
apresentação do módulo scene, conforme a preferência atual do usuário.
- Cada tela deve ter sua própria stage em `src/stages/<tela>`, responsável pelo
cenário e pelos dados de colisão. `src/stage` é a fronteira da stage ativa e
das sondas NES compartilhadas; `src/scene` cuida da apresentação e `src/link`
consulta a stage sem conhecer o mapa concreto.
- O HUD compartilhado fica em `src/hud`, com assets em `assets/ui/hud`. O slot A
reflete `Items[0]`; os corações refletem `Items[$18/$19]`. Rupias, chaves e
bombas também refletem seus slots reais; rupias passam pela fila $26.
- A stage da caverna inicial fica em `src/stages/cave_start`. Manter transições
em `src/stage/flow.pbs`, sem mover controle do personagem ou apresentação
para as stages. A primeira espada é coletável; `CavePickup` coordena contato
e desaparecimento do velho. CaveArt emite velho, espada, fogo e letras
como sprites sobre o terreno fixo; piscar/coletar não troca a scene.
- Inventário é portado na direção da ROM: bloco `Items` de 40 slots e tabelas
de item/slot/descritor em `src/inventory`; flags OW independentes em `src/world`.
Não substituir isso por booleanos de posse em Link ou nas stages. A primeira
aquisição persiste entre visitas e no save explícito do memcard; manter o
bit de coleta separado da posse do equipamento.
- A aritmética de vida fica em `src/inventory/life.pbs`, compartilhando o array
Items; reações de Link ficam em `src/link/vitals.pbs`. Atacantes devem chamar
`Link.hurt`, respeitando imunidade e morte. Não converter a fração `$FF` em
uma escala genérica de HP sem preservar as regras da ROM.
- `tools/generate_life_fixture.py` gera uma entrada isolada de testes. Nunca
deixar essa entrada instalada em `src/main.pbs` ao devolver o projeto.
Regenerar vida com `tools/prepare_life.py` depois dos bancos de Link/caverna.
- O ciclo externo fica em `src/game`: abertura, unfurl, partida, morte e menu.
`src/main.pbs` somente liga os hooks. `src/screens` contém telas sem colisão;
não misturar essa máquina com as transições de salas em `src/stage`.
- Start na abertura leva a Continue / New Game do perfil único. Shift abre
Continue / Save / Retry durante a partida; Continue vivo retoma posição/vida,
enquanto Continue após morte retorna ao início com três corações. Retry
retorna à abertura. História automática e seleção de três perfis pendentes.
- A sala norte $67 fica em `src/stages/overworld_north`; Octoroks e pedras em
`src/enemies/octorok`. Sondas verticais de monstros também usam dois tiles;
apenas o offset negativo difere do jogador (-16 em vez de -8).
- O HUD fixo usa camada 2, acima dos personagens (1), para permanecer visível
durante a rolagem vertical. Preservar a escala 1:1 e o marcador por sala.
- Regenerar o marcador norte com `tools/prepare_north.py` após regenerar o HUD.
O nascimento usa patterns de demo retidos em $0700–$08DF. Nunca devolver a
fixture de inimigos instalada no main ou exposta pelo barrel.
- Sprites de objetos usam DrawObjectWithType: índice de animação = tipo + 1.
Interpretar atributos de cada frame, incluindo flip vertical. Para Octoroks
e pedras, `tools/nes_object_graphics.py` executa a rotina 6502 de descritores;
a regressão gráfica deve mostrar os oito frames e uma pedra visível.
- `src/world` preserva bits de itens ao escrever mortes nos três bits baixos;
histórico é anel de seis inserções únicas, não LRU. `$07` guarda sala limpa.
Salvar contagem na saída, não na morte de Link. Menu pós-morte limpa histórico.
- `src/loot` cuida dos drops e do voo da fada. Golpe fatal e fim do efeito de
morte avançam contadores distintos. Não substituir as tabelas por sorteio
uniforme. `src/combat_graphics` usa glyph 12 para itens, efeitos e contadores.
- O projétil único fica em `src/link/beam.pbs`, nasce ao passar da espada 2→3 e
usa a condição nativa de HUD cheio (fração >= $80). Sua dispersão também ocupa
o slot. Itens coletados e contadores pertencem ao inventário, não ao HUD.
- Fixtures de combate são geradas fora de src. Quando instaladas para teste,
restaurar main, barrels e mains auxiliares antes de devolver o jogo. A fixture
grande é executada em lotes por frame para respeitar o watchdog do headless.
- O submenu fica em `src/screens/inventory`, aberto/fechado por Start (Z no
desktop); seleção B e busca nativa ficam em `src/inventory/selection.pbs`,
separadas do bloco Items. Esquerda/direita escolhem; D é Button.B. Não conceder
itens para demonstrar o menu. Os testes temporários do pacote inicial e
da parede na entrada da espada foram concluídos e estão desativados; não
reativar sem pedido explícito. Bombas pertencem a Link;
pausa/retomada pertence à máquina GameFlow. Preservar a seleção no HUD layer 2.
- A scene de inventário usa o último slot (15), com 16 faixas de 416 pixels.
Novas scenes precisam considerar o limite de 16; não adicionar slot 16.
- O percurso de bombas usa as salas OW $66/$65/$64 em stages separadas
`overworld_northwest`, `overworld_northwest_2`, `overworld_bomb_field`.
IDs internos 3/4/5. Reutilizar atlas scenes 13 (salas), 14 (transições) e 15
(inventário), sem adicionar slots. Usar prepare_overworld.py como recomposição final dos atlas e
inventory_screen. Atributo D bit 7 também faz parte do ID de lista de inimigos:
C=$69 não significa Octorok azul; as listas completas são nativas.
- `Octorok.kind` distingue $07/$08/$09; cinco atores e drops atendem a sala $64.
HP, reação não fatal e atributos pertencem ao ator; a escolha do drop recebe
o tipo efetivo, preservando os grupos da ROM. Não garantir bombas por morte.
- Testes temporários concluídos e desativados: `ENABLE_BOMBABLE_SWORD_TEST`
em overworld_start/main.pbs e `ENABLE_TEMPORARY_BOMB` em test_bomb.pbs estão
false por pedido do usuário. A entrada da espada voltou a ficar aberta e
não há pacote inicial de teste. `BombableWall` em world é reutilizável:
segredo no bit $80, separado da espada ($10) e mortes (bits 0..2). Somente
detonação, limiar $10 estrito nos dois eixos; não reutilizar o raio de dano
$18. Render, colisão e entrada compartilham essa flag. Desativar os dois
toggles remove a montagem temporária sem remover o mecanismo.
- O tipo auxiliar da sala inicial é StartRoomData; preservar esse nome em
sync_start_stage. prepare_north converte o nome ao copiar o template.
- Save fica em `src/save`, com `[MemcardBoot]` no root e `memcard_slots: 1`.
Preservar `app_id=2137977836` em upgrades. Nunca aguardar commit no hook:
enviar no Frame, consultar status antes de payload, poll entre frames e
liberar resultado terminal. Somente state 1 é GAME SAVED; state 4 é apenas
memória. Mídia, recuperação e descarte de RAM pertencem ao runtime.
- Formato v1: 180 bytes (header 12 + Items 40 + flags OW 128), magic ZL1S,
checksum Adler-32, validação antes de aplicar. Flags OW são copiadas inteiras
como na ROM; não apagar kills arbitrariamente. História de seis salas não
persiste. Ao carregar, limpar relógio em Items[$15] (não $14) e normalizar
vida para três corações, preservando capacidade. Dados ruins não são apagados.
- `prepare_game_screens.py` termina com `prepare_save_ui.py`, que recompõe a
fonte NES no banco existente e o menu dinâmico. Não reintroduzir o menu
antigo sem SAVE. Testes de memcard usam imagens isoladas em .tmp; não gravar
perfis de teste na imagem do usuário `.studio/memcard.pmc`. Restaurar todas
as fixtures antes do build final. Consultar docs/save.md e extracted/save.
- Catálogo de expansão: tools/overworld_manifest.json; gerador final
tools/prepare_overworld.py. Stages 6/7/8/9 são $57/$58/$68/$78, com módulos
próprios e metadados em src/overworld. Não inventar conexão $67→$57.
Enemy count/kinds/edge spawns, HUD, inventário e rolagens usam esse catálogo.
- EdgeSpawn preserva cursor/timer entre visitas; limiar raw $84 e distância
$22, slots descendentes e ausência de nuvem seguem a ROM. Não repor mortos
durante a visita. Cinco atores continuam suficientes para este recorte.
- Zora da sala $65 está em src/enemies/zora; novas salas atuais não têm essa flag.
Cavernas/segredos das salas novas ficam para outro recorte. Consultar
docs/overworld.md e extracted/overworld/expansion. Restaurar a fixture
com generate_overworld_fixture.py restore antes do build de produção.
- Padrão de composição: docs/scene-composition.md. Usar scenes para terreno
fixo e sprites/glyphs para NPCs, itens, texto e partes mutáveis. Preservar
aparência/regras da ROM sem reproduzir sua organização gráfica interna.
Não criar variantes de scene para visibilidade de objetos ou paredes.
- Paredes bombáveis: passagem no terreno base + cobertura desenhada enquanto
fechada; render, colisão e entrada consultam a mesma flag persistente.
Propagar offsets de scroll/inventário à cobertura e aos objetos. Manter
os testes temporários da espada e do pacote de bombas desativados.
- prepare_cave.py gera terreno e CaveArt separadamente; recompor inventário
com prepare_overworld.py depois. Scenes legadas 2/3 ficam reservadas por
compatibilidade de IDs, mas gameplay e inventário usam a caverna fixa 1.
- Inventário e ponto de retomada da pausa de 09/11/2026: docs/port-status.md.
Ler ao retomar; manter o documento atualizado ao concluir novos recortes,
distinguindo gameplay portado de dados/assets ou estruturas ainda parciais.
- Zora é um encontro extra da flag A&$08, separado da lista de Octoroks e da
contagem de mortes da sala. Submersão natural permite novo surgimento;
morte bloqueia até nova visita. Bola de fogo $55 requer escudo mágico
Items[$1F] para bloqueio; não reutilizar a regra das pedras. Ver docs/zora.md.
- Regenerar glyphs Zora com tools/prepare_zora.py após prepare_north; manter
índices anteriores do banco 11. O byte adjacente Random+$0D é explícito,
nunca ler fora do array PBS. Restaurar generate_zora_fixture antes do build.
- Segredo real: parede $E6 na sala $67 em (112,80), entrada (112,77), leva à
stage 10 cave_secret, Moblin $7B com 30 rupias. Ver docs/real-secret.md.
Abertura $80 e prêmio $10 compartilham o byte OW103, preservando kills.
Moblin/texto/prêmio ficam na visita da coleta e somem na seguinte.
- Stages 1, 10, 11 e 16 são interiores (Overworld/Stage.is_cave). Não registrar uma
visita fictícia de inimigos dentro de cavernas. StageFlow guarda cave_origin
e cave_x; retorno da caverna da espada continua em $77, do segredo em $67.
- prepare_cave termina com prepare_real_secret; depois recompor com
prepare_overworld. Terreno revelado + cobertura acompanha scroll/inventário.
wall_fresh distingue tiles $24 imediatos do metatile $0C na revisita; limpar
ao sair/resetar. Máscaras da porta inicial foram equivalentes nesta entrada,
mas precisam de nova verificação em outras geometrias.
- Loja $66: stage 11 cave_shop, tipo $78; escudo 160, chave 100, vela azul 60.
Stage/Overworld.is_cave inclui 11; retorno à origem 3. Ver docs/shop.md.
Compra por contato usa Inventory.purchase e fila Items[$27]; pendência bloqueia
compra. Escudo classe 0 atribui 1; chave soma até255; vela preserva grau maior.
Flag OW102 $10 não impede reposição por visita. Uma compra por visita.
Link.lift_item define arte erguida; espada mantém a pose anterior.
prepare_real_secret termina com prepare_shop; terminar com prepare_overworld.
generate_shop_fixture.py restore antes do build final. Uso de fogo da vela
e portas de dungeon ainda pendentes; não confundir posse com gameplay completo.
- Percurso oeste: stages 12/13/14/15 = $56/$55/$54/$44; loja interior 16 em
cave_supply_shop, entrada aberta (64,77), retorno à origem 15. Stage 16 não
significa slot de scene 16: usa terreno scene1 e inventário variante1.
Ler docs/west-route.md. Catálogo atual: 13 salas, 15 ligações reversíveis.
- Loja $44/$77: escudo130, quatro bombas20, flechas80. src/shop/ShopVisit
compartilha compra e estoque por visita com a loja $66, sem preços globais.
Comprar bombas não ergue: ItemTypeToLift=0 é sentinela nativa. Flechas sem
arco não habilitam seleção B; uso de arco/flechas ainda pendente.
- HUD novo ocupa índices contíguos28–31; não derivar índice apenas do ID de
stage, pois há interiores entre salas. Prefixo supply-shop- segue os glyphs
existentes no gerador; prepare_real_secret remove/recompõe ambos os estoques.
- generate_supply_shop_fixture.py restore antes do build final. Os testes
usam .tmp/supply-shop-97ae4684.pmc, nunca .studio/memcard.pmc. Guards de
chamadas com acesso a tabelas na fixture usam if aninhado; não depender de
&& para impedir a chamada quando o índice estiver fora da tabela.
- Pausa atual por pedido do usuário em 09/11/2026: percurso oeste e loja $44
concluídos, sem trabalho em andamento; ler o bloco "Ponto de pausa atual"
no início de docs/port-status.md. Último build 9a71c3be-7b87-4533-bfc0-cbfd36e30108;
fontes de produção restauradas, Studio manual e headless encerrado.
Próxima sugestão (ainda não iniciada/decidida): uso da vela + segredo
queimável real. Não assumir que flechas compráveis já tenham uso implementado.