## 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 `. 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. # 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/`, 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.