Files
zelda-1-prometeu-port/AGENTS.md
T

227 lines
15 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.
<!-- 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.