Files

15 KiB
Raw Permalink Blame History

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.

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.