15 KiB
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.mdatualizado 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/linke a cena emsrc/scene, com as APIs públicas declaradas nos respectivos barrels. O identificador técnico do projeto ézelda1; a pasta continua se chamandozelda-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/scenecuida da apresentação esrc/linkconsulta a stage sem conhecer o mapa concreto. -
O HUD compartilhado fica em
src/hud, com assets emassets/ui/hud. O slot A refleteItems[0]; os corações refletemItems[$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 emsrc/stage/flow.pbs, sem mover controle do personagem ou apresentação para as stages. A primeira espada é coletável;CavePickupcoordena 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
Itemsde 40 slots e tabelas de item/slot/descritor emsrc/inventory; flags OW independentes emsrc/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 emsrc/link/vitals.pbs. Atacantes devem chamarLink.hurt, respeitando imunidade e morte. Não converter a fração$FFem uma escala genérica de HP sem preservar as regras da ROM. -
tools/generate_life_fixture.pygera uma entrada isolada de testes. Nunca deixar essa entrada instalada emsrc/main.pbsao devolver o projeto. Regenerar vida comtools/prepare_life.pydepois dos bancos de Link/caverna. -
O ciclo externo fica em
src/game: abertura, unfurl, partida, morte e menu.src/main.pbssomente liga os hooks.src/screenscontém telas sem colisão; não misturar essa máquina com as transições de salas emsrc/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 emsrc/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.pyapó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.pyexecuta a rotina 6502 de descritores; a regressão gráfica deve mostrar os oito frames e uma pedra visível. -
src/worldpreserva bits de itens ao escrever mortes nos três bits baixos; histórico é anel de seis inserções únicas, não LRU.$07guarda sala limpa. Salvar contagem na saída, não na morte de Link. Menu pós-morte limpa histórico. -
src/lootcuida 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_graphicsusa 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 emsrc/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.kinddistingue $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_TESTem overworld_start/main.pbs eENABLE_TEMPORARY_BOMBem 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.BombableWallem 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 ememcard_slots: 1. Preservarapp_id=2137977836em 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.pytermina comprepare_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.