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