chore: version Zelda 1 port and engineering records

This commit is contained in:
Nilton Constantino
2026-11-16 15:22:13 +00:00
commit 6f2fa420c2
4282 changed files with 822198 additions and 0 deletions
+93
View File
@@ -0,0 +1,93 @@
# Expansão do overworld
O catálogo `tools/overworld_manifest.json` liga os IDs internos às salas NES.
Cada tela mantém stage, dados de colisão e render em `src/stages`; o módulo
`src/overworld` fornece metadados e conexões, e `src/stage` coordena a rolagem.
| Stage | Sala NES | Tela |
|---|---|---|
| 0 | $77 | Inicial |
| 2 | $67 | Norte |
| 3 | $66 | Noroeste |
| 4 | $65 | Noroeste 2 |
| 5 | $64 | Campo de bombas |
| 6 | $57 | Norte superior oeste |
| 7 | $58 | Norte superior leste |
| 8 | $68 | Leste da sala norte |
| 9 | $78 | Leste da sala inicial |
| 12 | $56 | Oeste 1 |
| 13 | $55 | Oeste 2 |
| 14 | $54 | Oeste 3 |
| 15 | $44 | Loja oeste |
A stage 1 continua sendo a caverna da espada. A stage 10 é a caverna secreta
da $67 (Moblin/30 rupias), acessível após bombardear a parede superior;
ver [real-secret.md](real-secret.md). O percurso novo permite
$77 → $78 → $68 → $58 → $57; $68 também liga a $67. Não há ligação direta
$67 → $57: a borda é sólida na ROM. As conexões são extraídas por adjacência
nativa e aberturas compartilhadas, sem criar portas em paredes.
As quatro salas novas usam listas nativas de Octoroks vermelhos $07/$08.
A flag de entrada pelas bordas vem do atributo F, bit 3. A busca percorre o
perímetro no sentido anti-horário, mantém o cursor entre visitas, rejeita
areia >= $84 e tenta novamente quando Link está a menos de $22 nos dois eixos.
Atores nascem em ordem descendente, sem nuvem; o atraso usa o timer longo
nativo e não repõe inimigos mortos durante a visita. O histórico de seis salas
e as flags persistentes continuam em `src/world`, com os IDs nativos.
Scenes 13, 14 e 15 continuam sendo, respectivamente, atlas de salas,
rolagens e inventário. O atlas de terreno usa quatro paletas e 35 glyphs;
o inventário possui 16 faixas. Nenhum novo slot de scene foi criado.
HUD e fundo congelado do inventário seguem a sala ativa. A área NES permanece
256×240 em escala 1:1. O save v1 e app_id permanecem os mesmos: já incluem as
128 flags do overworld. Nenhum perfil de teste deve ser escrito no cartão padrão.
## Regeneração
Executar `python3 tools/prepare_overworld.py` após regenerar assets de HUD,
salas ou inventário. Esse comando extrai as 13 salas da ROM local verificada,
recria stages gerenciadas, metadados, atlas, marcadores e inventário.
A stage inicial é mantida manualmente, incluindo os testes temporários
explicitamente desativados. Os entrypoints antigos prepare_north e
prepare_bomb_route terminam com a recomposição deste catálogo.
## Validação
`python3 tools/validate_overworld.py` executa sondas de colisão da ROM
para as 13 salas e a rotina 6502 FindNextEdgeSpawnCell para as quatro novas.
O oráculo é limitado às rotinas alcançadas, não é um emulador NES completo.
`tools/generate_overworld_fixture.py install` instala uma entrada temporária,
com cópias em `.tmp/overworld-fixture`. Compilar pelo Studio e avançar conforme
`cases.json`; capturar em `extracted/overworld/expansion/validation`.
A fixture confere as 30 transições direcionadas, nascimento dos inimigos,
limpeza/histórico e marcadores de asserção. Depois executar
`python3 tools/generate_overworld_fixture.py restore`, recompilar o jogo e
validar diagnostics. Nunca devolver a fixture instalada.
`python3 tools/validate_overworld_captures.py` compara terreno, inventário,
HUD e destinos das transições com os PNGs extraídos.
## Limites deste recorte
As cavernas, NPCs e segredos das quatro salas novas ainda não têm interação.
A paisagem e suas colisões são nativas; não substituir essas entradas por
uma cópia da caverna inicial. Outras bordas externas permanecem sem destino
até portar suas salas e tipos de inimigos.
A sala $65 possui flag de Zora, agora atendida pelo módulo
`src/enemies/zora`; detalhes em [zora.md](zora.md). As quatro
salas adicionadas não possuem essa flag. Som continua fora desta wave.
## Loja da sala $66
Entrada aberta (112,77) ligada à stage 11 `cave_shop` ($78), com retorno à $66.
Escudo mágico 160, chave 100, vela azul 60; ver [shop.md](shop.md). Continuam
nove salas OW; agora três interiores, sem novos slots de scene.
## Percurso oeste até a loja $44
Expansão $57↔$56↔$55↔$54↔$44, mais $55↔$65 e $54↔$64. Total atual:
13 salas, 15 ligações reversíveis e quatro interiores. Zora também nas salas
$56/$55/$54; $44 não possui a flag. A loja $77 é a stage 16, vinculada à 15,
com entrada aberta (64,77), bombas 20, escudo 130 e flechas 80. Nenhum slot
adicional de scene. Detalhes/limites/evidência em [west-route.md](west-route.md).
+326
View File
@@ -0,0 +1,326 @@
# Inventário do port e ponto de retomada
**Pausado por pedido do usuário em 09/11/2026, após concluir o percurso oeste até a loja de bombas da $44.**
Este documento registra o estado do port de Zelda 1 NES para Prometeu.
O inventário original da pausa foi feito nos fontes e relatórios salvos.
Na retomada, o Zora foi implementado e validado em novos builds e sessões
headless; as evidências desse recorte estão em `extracted/zora`.
O recorte atual permite iniciar uma partida sem espada, entrar na caverna,
coletar a espada, explorar 13 telas do overworld e quatro cavernas, comprar
nas lojas da $66 e $44, enfrentar Octoroks/Zora, obter
drops, usar bombas, abrir o inventário, morrer/continuar e salvar/carregar
um perfil no memcard. Ainda não permite completar o jogo.
## Ponto de pausa atual — 09/11/2026
O usuário pediu para parar por enquanto. Não há implementação em andamento.
Última entrega: percurso oeste e loja da $44, descritos em
[west-route.md](west-route.md). Estado jogável: **13 telas do overworld e
quatro interiores**, duas lojas, combate com Octoroks/Zora, bombas, inventário
e save/load. A lista aceita de quatro recortes foi concluída.
- Último build/pack aprovado: `9a71c3be-7b87-4533-bfc0-cbfd36e30108`.
- Fixtures removidas; `src/main.pbs` e Game restaurados. Studio em modo manual,
sem sessão headless mantida pelo agente. Cartão do usuário preservado.
- Smoke final: New Game, coleta/pose da espada, Continue com cartão descartável
em leitura somente, quitação de débito, bomba 8→7 e inventário aberto/fechado.
- Build e testes runtime passaram. LSP teve falhas intermitentes em três fontes;
não registrar essas consultas como diagnostics vazios. Evidência e demais
atritos em [prometeu-feedback.md](prometeu-feedback.md).
- **Próximo recorte sugerido, ainda não iniciado nem escolhido pelo usuário:**
uso da vela e um segredo queimável real, conferindo primeiro as regras e o
local na ROM. Depois, considerar percurso rumo à primeira dungeon.
- Vela azul já pode ser comprada, mas não produz fogo. Flechas já podem ser
compradas, mas o uso de arco/flechas está pendente. Dungeons ainda pendentes.
Ao retomar, ler este bloco, AGENTS.md e os documentos do recorte; conferir
mudanças locais e obter o controle do Studio antes de editar/testar pelo agente.
Não reutilizar taskId da sessão encerrada nem reativar bombas de teste no início.
## Como interpretar o inventário
- **Portado no recorte:** implementado para as telas e os atores existentes;
não significa que todo o sistema original esteja coberto.
- **Parcial:** existe estrutura ou comportamento, mas falta conteúdo,
integração ou parte das regras para representar o sistema completo.
- **Pendente:** não há implementação jogável identificada no estado atual.
- Assets extraídos, tabelas e ícones disponíveis não equivalem a gameplay portado.
## O que já foi portado
| Área | Estado e comportamento disponível | Fontes principais |
|---|---|---|
| Assets NES | Extração de patterns, paletas, mapas e descritores utilizados no recorte; PNGs e dados rastreáveis à ROM local verificada. Não é certificação de extração de todo o conteúdo do jogo. | `tools/extract_graphics.py`, `tools/extract_start_room.py`, `tools/nes_object_graphics.py`, `assets/`, `extracted/` |
| Apresentação | Área NES de 256×240, escala 1:1, centralizada numa caixa; terreno, atores e HUD compostos separadamente. HUD na camada 2, atores na 1. | `src/scene`, `src/hud` |
| Link: movimento | Quatro direções, animação, alinhamento à grade e movimento fracionário orientados pela ROM; escolha de direção conforme posição na grade, não uma prioridade vertical global inventada. | `src/link/movement.pbs`, `src/link/controller.pbs` |
| Link: espada | Ataque direcional, animação e alcance; começa sem espada; coleta da primeira espada com pose de erguer o item. Graus de espada tratados nos dados/dano, sem todos os locais de aquisição. | `src/link/sword.pbs`, `src/link/render.pbs`, `src/inventory` |
| Projétil de espada | Disparo condicionado à vida cheia, slot único e dispersão; colisão com os inimigos existentes. | `src/link/beam.pbs` |
| Defesa e dano | Bloqueio frontal das pedras com escudo, ricochete, contato com inimigos/fogo, imunidade temporária e recuo. | `src/enemies/octorok/rock.pbs`, `src/link/vitals.pbs` |
| Vida | Corações e fração nativa, capacidade, dano, cura, itens de vida e continuação com três corações; efeitos dos graus de anel nos cálculos/paleta. Aquisição de todos esses equipamentos pelo mapa ainda pendente. | `src/inventory/life.pbs`, `src/link/vitals.pbs` |
| Bombas | Seleção no slot B, consumo, colocação, fusível, explosão e efeitos, limites de slots e dano aos inimigos existentes. Não acrescentar dano ao próprio Link por suposição. | `src/link/bomb.pbs`, `src/link/main.pbs` |
| Paredes bombáveis | Mecanismo reutilizável: detonação, limiar nativo, flag persistente, cobertura visual, colisão e entrada coordenadas. Integrado ao segredo real da $67; outros locais continuam pendentes. | `src/world/bombable_wall.pbs`, `src/stages/overworld_start` |
| Stages e colisões | Uma stage por tela, dados nativos e sondas compartilhadas de jogador/monstros. Transições horizontais/verticais e entrada/saída da caverna. | `src/stages`, `src/stage` |
| Zora | Ator $11, bola de fogo $55, surgimento em água, estados nativos, vulnerabilidade, morte/drop e regra do escudo mágico; integrado à $65. | `src/enemies/zora`, [zora.md](zora.md) |
| Octoroks | Tipos $07/$08/$09: vermelho lento, vermelho rápido e azul lento; animações, movimento, pedras, HP, reação a golpes, morte e drops. Pool de cinco atores atende às salas atuais. | `src/enemies/octorok` |
| Nascimento de inimigos | Nuvens nas salas correspondentes e entrada pelas bordas nas quatro salas novas; cursor, timer, distância de segurança e ordem de slots orientados pela ROM. | `src/enemies/octorok/edge.pbs`, `src/overworld` |
| Persistência entre visitas | Flags nativas do overworld, contagem de mortes registrada na saída e histórico de seis salas; respawn depende dessas regras, não é simplesmente proibido ao trocar de tela. | `src/world` |
| Drops | Tabelas/grupos nativos, contadores de ajuda, bombas, rupias, corações e fada; tempo de vida, coleta por contato/espada e voo da fada. | `src/loot`, `src/combat_graphics` |
| Inventário: dados | Bloco Items de 40 slots, classes/graus, contadores, fila de rupias e seleção B separada; flags de coletas não se confundem com posse. | `src/inventory`, `src/world` |
| Inventário: tela | Abre/fecha com rolagem, pausa gameplay, mostra conteúdo e seleciona item B; HUD e fundo acompanham a sala ativa. | `src/screens/inventory` |
| Caverna da espada | Entrada/saída, primeira aquisição, texto, velho, fogo e desaparecimento após a coleta. Objetos e letras agora são sprites sobre terreno fixo, inclusive durante a rolagem do inventário. | `src/stages/cave_start` |
| Abertura e fluxo | Tela de título com brilho/cachoeira, New Game/Continue, abertura da área de jogo, morte, Game Over, Continue/Save/Retry e retorno ao título. | `src/game`, `src/screens/title`, `src/screens/continue_menu` |
| Save/load | Um perfil no memcard, commit assíncrono, validação de payload, mensagens de erro/modo memória, restauração de Items e flags OW. Validado também manualmente pelo usuário. | `src/save`, `src/screens/save`, [save.md](save.md) |
## Conteúdo de mapa disponível
São **13 telas do overworld e quatro cavernas jogáveis**.
Os IDs internos não são os IDs nativos: preservar o mapeamento do catálogo.
| Stage | Sala NES | Módulo em `src/stages` | Observação |
|---|---|---|---|
| 0 | $77 | `overworld_start` | Tela inicial; entrada da espada aberta; testes temporários desativados. |
| 1 | Caverna ligada a $77 | `cave_start` | Espada coletável, velho/texto/fogo; terreno único com objetos separados. |
| 2 | $67 | `overworld_north` | Octoroks e parede bombável que leva ao prêmio de 30 rupias. |
| 3 | $66 | `overworld_northwest` | Rota oeste e entrada aberta da loja. |
| 4 | $65 | `overworld_northwest_2` | Octoroks e Zora da flag nativa. |
| 5 | $64 | `overworld_bomb_field` | Rota de obtenção de bombas por drops; não há garantia por morte. |
| 6 | $57 | `overworld_north_upper` | Terreno, colisão e Octoroks pelas bordas; interiores/segredos pendentes. |
| 7 | $58 | `overworld_northeast_upper` | Terreno, colisão e Octoroks pelas bordas; interiores/segredos pendentes. |
| 8 | $68 | `overworld_east` | Terreno, colisão e Octoroks pelas bordas; interiores/segredos pendentes. |
| 9 | $78 | `overworld_start_east` | Terreno, colisão e Octoroks pelas bordas; interiores/segredos pendentes. |
| 10 | Caverna ligada a $67 | `cave_secret` | Moblin $7B, prêmio único de 30 rupias; retorno à sala norte. |
| 11 | Caverna ligada a $66 | `cave_shop` | Loja $78: escudo mágico, chave e vela azul. |
| 12 | $56 | `overworld_west_1` | Octoroks e Zora; segredo secundário pendente. |
| 13 | $55 | `overworld_west_2` | Um Octorok e Zora. |
| 14 | $54 | `overworld_west_3` | Octoroks, Zora e ligação ao campo de bombas. |
| 15 | $44 | `overworld_shop_west` | Octoroks e entrada aberta da loja. |
| 16 | Caverna ligada a $44 | `cave_supply_shop` | Loja $77: escudo mágico, quatro bombas e flechas. |
Conexões implementadas, todas reversíveis:
```text
$44
│
$54 ── $55 ── $56 ── $57 ── $58
│ │ │
$64 ── $65 ── $66 ── $67 ── $68
│ │
$77 ── $78
│
caverna da espada
```
No diagrama, a ligação caverna/$77 representa entrada/saída, não adjacência
geográfica ao sul. Não há conexão direta $67→$57: a borda é sólida.
As 15 conexões de overworld correspondem a 30 transições direcionadas.
Catálogo: `tools/overworld_manifest.json`; detalhes em [overworld.md](overworld.md).
## O que está parcial ou ainda falta
| Área | Pendência |
|---|---|
| Overworld completo | Restante das 128 posições de tela do mapa, conectividade, atributos, encontros e conteúdo específico; não abrir bordas sem portar o destino. |
| Zora | Primeiro encontro da $65 implementado; ampliar regressões ao adicionar salas, armas e interações futuras. Ver [zora.md](zora.md).
| Outros inimigos | Demais famílias do overworld e dungeons, com descritores, comportamento, dano, drops e regras de spawn próprios. |
| Cavernas e NPCs | Outras cavernas/lojas além das quatro atuais; demais pagamentos, jogos e diálogos específicos. Entradas/segredos secundários das salas de expansão ainda estão pendentes. |
| Texto e abertura | Revelação progressiva de diálogos e lógica de texto mais completa; história/demo automáticas do título ainda pendentes. A mensagem da espada aparece inteira. |
| Segredos reais | Primeira parede/caverna da $67 integrada; ampliar aos outros locais da ROM; implementar árvores queimáveis, pedras/blocos movíveis e demais gatilhos nativos. Os demais locais e tipos de segredo ainda não estão integrados. |
| Uso dos itens B | Bombas funcionam; há caminho de consumo/cura de poção no código, sem aquisição normal integrada neste recorte. Bumerangue, arco/flechas, vela, apito, comida, vara e demais usos ainda precisam de gameplay. Seleção/ícones/dados não bastam. |
| Equipamentos e travessia | Locais e requisitos de espadas superiores, anéis, escudos/upgrades, escada, jangada e demais equipamentos; completar seus efeitos específicos e acesso ao mapa. |
| Progressão | Aquisições e economia além do circuito atual, recipientes de coração no mapa, progressão de chaves, itens únicos e requisitos de acesso. |
| Dungeons | Entradas, salas, portas/chaves, bloqueios, empurrar blocos, escadas/passagens, mapas/bússolas, itens e persistência de estado própria. Nenhuma dungeon jogável identificada. |
| Chefes e Triforce | Chefes, fragmentos, progressão de dungeons, Ganon, resgate e encerramento. |
| Perfis e segunda quest | Nome/seleção de três perfis, contador de mortes, segunda quest e suas diferenças de conteúdo. Save atual tem um perfil. |
| Save futuro | Evoluir o schema quando existirem flags de dungeons, novos metadados e segunda quest; prever migração. Não mudar app_id para isso. |
| Áudio | Música e efeitos ainda fora da primeira wave, conforme escopo combinado. |
| Fidelidade integral | Expandir regressões por sistema/sala. Os oráculos atuais executam rotinas 6502 delimitadas; não existe validação lockstep do jogo inteiro. |
## Limites e decisões a preservar
1. **Fidelidade de comportamento e imagem à ROM**, com organização adequada ao
Prometeu. Não é necessário reproduzir a organização gráfica interna do NES.
2. **Terreno fixo + elementos mutáveis separados.** NPCs, texto, itens e
coberturas de paredes bombáveis devem ser sprites/glyphs independentes.
Render, colisão e entrada de um segredo usam a mesma flag persistente.
Referência: [scene-composition.md](scene-composition.md).
3. **Sem retorno dos testes temporários:** `ENABLE_TEMPORARY_BOMB` e
`ENABLE_BOMBABLE_SWORD_TEST` estão false. Não recolocar pacote de bombas
na tela inicial nem fechar a entrada da espada sem pedido explícito.
4. **Viewport 1:1 e módulos por responsabilidade:** Link em `src/link`, stage
por tela, apresentação em `src/scene`, inventário/vida em `src/inventory`.
5. **Limite atual de 16 slots de scene:** slots 2/3 da caverna estão reservados
para compatibilidade de IDs; gameplay usa scene 1 fixa. Atlas de salas,
transições e inventário ficam em 13/14/15. Não adicionar slot 16 sem rever
a organização/capacidade. O inventário mantém 16 faixas de composição.
6. **Save v1:** 180 bytes, header 12 + Items 40 + flags OW 128;
`app_id=2137977836`, um slot/perfil. Histórico de visitas, posição, inimigos,
projéteis, drops e timers não são salvos. Carregar retorna ao início com
três corações e capacidade preservada; limpa Items[$15].
7. **Proteger o cartão do usuário:** `.studio/memcard.pmc`; testes em imagens
separadas ou memória. New Game não apaga imediatamente o save; Save explícito
substitui o único perfil. Não tratar MEMORY ONLY como GAME SAVED.
8. **Fontes e documentação PBS:** consultar referências do Studio antes de
recorrer a Java. Manter [prometeu-feedback.md](prometeu-feedback.md) com
evidência concreta; escolhas do port não devem virar defeitos do runtime.
## Validação já registrada
| Recorte | Evidência preservada |
|---|---|
| Expansão do overworld | 16.524 sondas de colisão nativas, 192 buscas de entrada pelas bordas, 18 transições direcionadas e 45 comparações visuais exatas. Relatórios em `extracted/overworld/expansion/`. |
| Caverna com objetos separados | Dez comparações visuais exatas, 2.573 sondas nativas; coleta, flag, posse, piscadas, timer, pausa e revisita. `extracted/cave/start/composition-validation/`. |
| Save | Payloads, checksum, reopen, leitura somente, modo memória, dados inválidos e fluxo de UI; evidências em `extracted/save/`, com detalhes em [save.md](save.md). Teste manual aprovado pelo usuário. |
| Demais sistemas | Fixtures e validadores de Link, vida, inventário, combate, drops, bombas, paredes, gráficos, HUD e fluxo em `tools/`; relatórios/capturas em `extracted/`. Não assumir que todos os scripts antigos foram reexecutados após cada mudança. |
Build de produção anterior à retomada: `5e713d48-8d9c-480d-9d35-a9aa112751a8`,
após a refatoração da caverna. Diagnostics vazios nas cinco fontes consultadas
naquela entrega. Teste por input normal: New Game → caverna → coleta/pose da
espada → desaparecimento do velho → inventário.
A entrada atual `src/main.pbs` chama Game.boot/Game.frame e MemcardBoot;
não contém a fixture. O Studio foi devolvido ao modo manual na última entrega.
Na pausa não houve alteração de gameplay; na retomada foi acrescentado o Zora.
## Retomada sugerida
1. Ler este inventário e `AGENTS.md`; conferir mudanças feitas durante a pausa.
2. Obter controle pelo Studio quando autorizado, compilar fontes salvas e
conferir diagnostics. O build histórico acima não substitui essa checagem.
3. Ao retomar um novo recorte, fazer um smoke com cartão de teste: iniciar sem espada, coletar na caverna,
abrir/fechar inventário, sair, combater um Octorok, salvar e carregar.
4. **Lista aceita na retomada:** Zora da $65 → segredo bombável real → loja
→ expansão de um percurso com objetivo. O Zora é o primeiro recorte; os
seguintes são concluídos por recorte, com evidências abaixo.
5. Ao adicionar conteúdo, extrair da ROM mapa, atributos, lista de inimigos,
entradas e flags; atualizar o catálogo e reutilizar os atlas existentes.
6. Regenerar caverna com `tools/prepare_cave.py` quando necessário e finalizar
a recomposição compartilhada com `tools/prepare_overworld.py`. Consultar
os documentos específicos antes de regenerar outros bancos.
7. Executar verificações apropriadas ao recorte; usar fixtures isoladas e
restaurar main/barrels/fontes auxiliares antes do build final de produção.
8. Atualizar este inventário e o feedback com o que mudou e os limites restantes.
A pausa anterior foi encerrada pelo usuário e a lista aceita foi executada.
O ponto de pausa atual está no início deste documento.
## Retomada: primeiro recorte concluído — Zora
A lacuna da $65 foi fechada: ciclo e disparo, arte, vulnerabilidade,
dano/morte/drop, bloqueio por escudo mágico e reinício por visita. Duas sequências
foram comparadas no guest com 388 ticks de UpdateZora da ROM; o cálculo angular
teve 1.369 pares conferidos. Sete comparações de assets e doze de composição
runtime foram exatas. Asserts de integração cobrem água, lotação, submersão,
bomba, morte sem reaparição na visita, nova visita, relógio e escudos.
O encontro com Octoroks, abertura/fechamento do inventário e saída para a sala
vizinha foi exercitado com Game.frame e uma entrada de teste isolada.
As nove salas mantiveram as 16.524 sondas nativas de colisão aprovadas.
A entrada de produção foi restaurada. Não foram reativados os testes temporários
de bombas, adicionados slots de scene ou alterados app_id/schema do save.
Lista restante: **segredo bombável real → loja → expansão de percurso com objetivo**.
Build final do recorte Zora: `dee2921c-11fd-4b45-9287-f24a3f87e9f0`.
Compilação/pack aprovados e diagnostics vazios nas seis fontes centrais
consultadas. Boot e New Game revalidados sem fixtures, em memory_fresh.
## Segundo recorte concluído — segredo bombável real
Sala $67: parede nativa em (112,80), entrada (112,77), caverna Moblin $7B
com prêmio único de 30 rupias. Stage própria cave_secret (10); terrain scene
compartilhada com objetos mutáveis separados. Abertura, colisão, entrada,
retorno, crédito e persistência implementados. Sem bomba de teste no início.
Ver [real-secret.md](real-secret.md). Foram conferidos 121 contatos nativos,
4.352 pixels de suporte da máscara de porta, oito recortes visuais exatos,
o ciclo de bomba/consumo/entrada/saída/revisita e gravação/reabertura de um
cartão descartável. Payload v1 contém flags $91 na sala $67, 30 rupias e
3 bombas, com checksum válido. O cartão do usuário não foi alterado.
Regressão no build normal: caverna da espada com coleta e saída; Continue de
save de teste e caminhada da tela inicial até a caverna secreta já coletada.
Build final do recorte: `dc681b23-7485-4a72-bcfc-7a29f3ac376b`.
Lista restante: **loja → expansão de percurso com objetivo**.
Regressão adicional do segundo recorte: 18 transições do overworld, 45
comparações visuais e seis capturas intermediárias da cobertura da parede
reexecutadas e aprovadas, além das 16.524 sondas e 192 buscas de borda.
Build/pack final aprovados; diagnostics vazios nas sete fontes consultadas.
Entrada de produção restaurada; nenhum helper de fixture ficou em src.
## Terceiro recorte concluído — loja da $66
Stage 11 `cave_shop`, tipo nativo $78: escudo mágico por 160, chave por 100
e vela azul por 60 rupias. Entrada aberta (112,77), compra por contato,
pose de aquisição de 128 ticks e saída para a própria $66. Uma compra por
visita; estoque reposto na próxima entrada, inclusive após load, apesar do
bit de item coletado persistente. Débito passa por Items[$27], sem alterar
schema/app_id do memcard. Ver [shop.md](shop.md).
Nove salas OW e **três interiores**: espada (1), segredo (10), loja (11).
A loja compartilha a scene de terreno 1; vendedor, texto, preços e produtos
são sprites. Nenhum slot de scene adicionado. Preços continuam visíveis após
comprar; os demais objetos seguem o desaparecimento nativo por visita.
Validação: 150 casos de aquisição/débito com rotinas da ROM, 13 comparações
exatas de composição/poses e asserts de entrada, saldo insuficiente, compra
única, saída, revisita e menu. Save durável em cartão descartável reaberto:
Items preservados e débito pendente de 60 liquidado após load. Cartão do
usuário não alterado. As 16.524 sondas de colisão e 192 casos de borda passaram.
**Limites:** compra/posse/seleção da vela implementadas; fogo da vela e árvores
queimáveis pendentes. Chaves acumulam, mas portas de dungeon ainda pendentes.
Texto aparece inteiro, como nas cavernas anteriores. Demais lojas pendentes.
Próximo recorte da lista aceita: **expansão de um percurso com objetivo**.
Integração adicional via Game.frame com inicialização isolada na entrada da
$66 confirmou a loja e abertura do submenu. O smoke de produção confirmou
New Game, coleta da espada, saída e transição até a $66; o trajeto longo
terminou em morte antes da loja. Ver limites e evidência em docs/shop.md.
Todas as entradas/helpers temporários foram restaurados antes do build final.
Build/pack final da loja: `ee40b41e-bd92-4648-bd2b-386e62c9bc00`.
Diagnostics vazios nas oito fontes consultadas; build final sem diagnósticos.
Boot/New Game revalidados após restauração, em memory_fresh.
## Quarto recorte concluído — percurso oeste com loja de bombas
Quatro salas ($56/$55/$54/$44), seis novas ligações reversíveis e interior
próprio da loja $77. O percurso $58→$57→$56→$55→$54→$44 tem aquisição concreta:
quatro bombas por 20 rupias; a loja também vende escudo por 130 e flechas por 80.
Atalhos nativos ligam $55↔$65 e $54↔$64. Ver [west-route.md](west-route.md).
Agora são 13 salas OW e quatro interiores, sem novos slots de scene. Zora nas
três salas novas que possuem a flag; encontros preservam listas e quantidades.
Compra/visita compartilhada em src/shop; arte, dados e render por stage.
Inventário recomposto em 16 faixas. IDs antigos do HUD/caverna preservados.
Validação: 23.868 sondas e 384 buscas nativas, 30 transições, 116 checkpoints
verdes, 69 comparações visuais do overworld e 12 da loja. Foram executados
400 casos nativos da loja nova e 150 da anterior, com Game.frame para entrada,
menu, compra, saída e reposição. Save durável e reabertura confirmaram oito
bombas, flechas, escudo e quitação do débito pendente. Cartão do usuário intacto.
Os limites de infraestrutura e da fixture estão descritos no documento do recorte.
A lista aceita na retomada foi concluída por estes quatro recortes. Próximas
opções úteis: uso da vela e um segredo queimável real; depois ampliar um trajeto
rumo à primeira dungeon com as famílias de inimigos correspondentes. Flechas
já podem ser compradas, mas o uso de arco/flechas continua pendente.
Build/pack final: `9a71c3be-7b87-4533-bfc0-cbfd36e30108`, sem diagnósticos.
Fixtures removidas; main e máquina Game restaurados. Smoke normal: New Game,
coleta/pose da espada e Continue pelo menu com cartão descartável em leitura
somente; quitação do débito, uso de bomba (8→7) e inventário aberto/fechado.
Diagnostics vazios em ShopVisit, StageFlow e Stage; três outras consultas de
fontes retornaram INFRASTRUCTURE_FAILURE do LSP, registradas no feedback.
O build e as verificações runtime passaram; não contar falha de LSP como vazio.
+966
View File
@@ -0,0 +1,966 @@
# Feedback de interface e produção do Prometeu
Registro contínuo das facilidades e dificuldades encontradas ao portar Zelda 1.
O objetivo é orientar melhorias no Prometeu com casos concretos de produção.
Atualizar durante o desenvolvimento, incluindo o que vale preservar.
Iniciado em 2026-11-06. As observações iniciais vêm desta sessão de trabalho.
Os previews de sprites e frames do runtime foram inspecionados; a disposição
visual dos painéis do Studio ainda não foi avaliada diretamente.
## Como registrar
- Identificar a tarefa, o comportamento observado e seu impacto na produção.
- Distinguir fato observado, hipótese de causa e sugestão de melhoria.
- Incluir erro, arquivo, captura ou passos úteis para uma reprodução mínima.
- Registrar também facilidades que devem ser preservadas.
- Acrescentar novas ocorrências ao item existente quando for o mesmo problema.
- Marcar correções e revalidar; não apagar o histórico da dificuldade.
- Usar P1 para bloqueio ou desvio relevante no trabalho, P2 para atrito recorrente
e P3 para acabamento. Prioridades são propostas iniciais, não decisões de produto.
## O que está funcionando bem
| ID | Observação | Evidência e valor para produção |
| --- | --- | --- |
| BOM-01 | Banco de glyphs e animações têm identidade verificável | Os 16 frames de corpo foram preservados ao acrescentar quatro imagens da espada. UUID, artifact ID, glyph ID e fingerprint permitem conferir os vínculos. Evita depender apenas de nomes e posições de arquivos. |
| BOM-02 | Preview de animação recebe ticks explícitos | Foi possível consultar a segunda pose da caminhada no tick 6 e verificar o término dos clipes Once. Ajuda a depurar tempos sem depender de observação em tempo real. |
| BOM-03 | Build, pack e runtime podem ser usados no mesmo fluxo | A integração de sprites e o controle foram compilados, empacotados e executados pelas ferramentas do Studio. O runtime aceita entradas controladas e avanço limitado de frames. |
| BOM-04 | Capturas do runtime permitem validar regressões visuais | A divisão do código passou por 58 comparações de imagens anteriores e posteriores, todas idênticas. Ver [resultado da comparação](../extracted/link/refactor-validation.json). |
| BOM-05 | Diagnósticos trazem código e posição no fonte | Erros de sintaxe e resolução de símbolos incluem intervalo e arquivo. Depois da divisão, os oito arquivos retornaram diagnostics vazios. |
| BOM-06 | Revisão esperada na gravação de animações e concessão de controle são explícitas | As definições foram salvas com revisão esperada. O agente só adquiriu controle após a liberação em DEV e devolveu o projeto ao estado MANUAL nas entregas finais. Preservar essas garantias ao melhorar a ergonomia. |
| BOM-07 | Estruturas com estado por referência permitem organizar o jogo | A implementação atual passa um único LinkState entre movimento, atualização e desenho, mantendo a ordem do NES. Os objetos são criados uma vez; não há criação desses sistemas a cada frame. |
| BOM-08 | Bancos de cena, camadas e câmera alinham cenário e sprites sem redimensionar assets | A sala inicial usa 21 glyphs 8×8 no fundo e Link/espada na camada seguinte. A câmera posiciona a área NES na caixa 1:1; três capturas corresponderam à composição dos pixels extraídos. Ver [validação da sala](../extracted/overworld/start/runtime-validation.json). |
| BOM-09 | Stage com dados privados e services compõe cenário e colisão sem alterar a apresentação | A sala inicial exporta sua API, o Link consulta `Stage` e sete arquivos tiveram diagnostics vazios. Quatorze capturas de caminhos e bloqueios corresponderam pixel a pixel ao modelo. |
| BOM-10 | Banco independente com tiles 32×32 e paleta de nove cores preservou o HUD NES | O HUD foi publicado com 16 blocos sem redimensionar os padrões 8×8 originais. `Hud.draw()` compartilha o render entre stages; quatro capturas completas corresponderam pixel a pixel, inclusive espada acima do fundo do HUD. Formato e limite de paleta foram conferidos na especificação pública do packer; não foi necessário consultar Java. |
| BOM-11 | Troca de scene bank e reaplicação da câmera suportaram uma segunda stage | Caverna e overworld mantiveram bancos e colisões próprios, HUD compartilhado e atores alinhados. Build na primeira tentativa; 11 fontes sem diagnostics e 20 capturas de ida/volta sem diferenças. Não foi necessário consultar Java. |
| BOM-12 | Arrays tipados e módulos privados comportaram o estado original do inventário | O bloco de 40 slots Items e os 128 bytes de flags OW são arrays fixos por referência, com mutações encapsuladas. As tabelas de 36 itens foram preservadas. Quinze fontes sem diagnostics e 28 capturas da aquisição/revisita/reinício coincidiram pixel a pixel. A especificação pública de arrays foi suficiente, sem consulta a Java. |
Nota de validação visual: a pose de aquisição inicialmente omitiu o flip OAM
`$40` da metade direita. As comparações anteriores usavam o próprio PNG extraído
como referência e, por isso, não detectaram o erro de composição. A correção
conferiu a metade direita diretamente com os padrões `$08/$09` espelhados e
recapturou aquisição, bloqueio e término da pose. Isso é um limite da validação
do port, não evidência de defeito do Studio. Preservar inspeção visual e uma
referência independente dos atributos de montagem dos sprites.
| BOM-13 | Arrays compartilhados permitiram portar vida sem duplicar o estado do inventário | Items `$18/$19` são usados pela aritmética e pelo HUD. Um cartucho de teste executou 79 casos e 21 capturas sem diferenças; o jogo normal confirmou seis contatos de fogo, morte e continuação. Vinte e oito imagens de aquisição permaneceram iguais. As rotinas 6502 foram referência independente para 8.064 casos numéricos. |
## Dificuldades observadas
### ATR-01 Nomes de projeto aceitos não são todos endereçáveis em imports
**P1 · Observado; causa sugerida pela gramática consultada.**
O manifesto aceita `zelda-1`, mas `@zelda-1:generated/animations/...` gerou
`E_PARSE_EXPECTED_TOKEN`, encontrando `MINUS` onde era esperado `:`.
A gramática de referência de módulo consome um identificador simples para o projeto.
Impacto: não foi possível consumir diretamente a factory virtual de animação
com o nome atual do projeto. Foi necessário gerar uma consulta local de glyphs.
Melhoria: alinhar validação dos nomes e sintaxe de import; suportar nomes aceitos
pelo manifesto ou fornecer uma referência estável ao próprio projeto.
`@app` no exemplo não é uma solução demonstrada: o projeto do exemplo chama-se
`app`; tratá-lo como alias universal foi uma suposição incorreta do agente.
Contorno adotado na divisão em módulos: ajustar o identificador técnico do
manifesto para `zelda1`, preservando pasta e `app_id`. Os imports reais e o build
passaram. O problema do Prometeu continua aberto para nomes com hífen.
### ATR-02 Divisão em arquivos tem diagnósticos difíceis de interpretar
**P1 · Observado; reprodução mínima e causa ainda pendentes.**
Ao extrair funções para arquivos do mesmo módulo e declará-las com `mod fn`
no barrel, surgiram `E_SEM_APPLY_NON_CALLABLE_TARGET` em chamadas internas.
A tentativa com globais compartilhados também apresentou
`E_SEM_ASSIGN_TARGET_UNRESOLVED` nas atribuições de outro arquivo.
Uma tentativa com services alcançou a etapa seguinte e falhou com
`E_SEM_EXEC_LOWERING_UNRESOLVED_CALLEE` em chamadas qualificadas.
Impacto: uma divisão de aproximadamente 300 linhas exigiu sucessivas adaptações
de organização. A versão com structs, métodos e estado passado explicitamente
compilou e preservou as 58 capturas.
Melhoria: criar casos mínimos de funções, globais e services internos entre
arquivos; confrontar com a regra documentada de visibilidade `mod`.
Explicar no diagnóstico se falta visibilidade, assinatura ou suporte de lowering.
Não considerar a solução atual prova da causa dos erros anteriores.
Ocorrência na introdução das stages: `this.colliding_tile(...)` em service
falhou com `E_SEM_EXEC_LOWERING_UNRESOLVED_CALLEE`. Após extrair a sonda para
um struct privado, a expressão `probe.colliding_tile(...) <
OverworldStart.first_unwalkable()` também falhou, agora com intervalo localizado.
Atribuir os dois resultados a variáveis locais antes da comparação compilou e
passou nos testes visuais. Esse contorno foi encontrado sem consultar Java;
a causa do lowering permanece pendente de reprodução mínima no compilador.
### ATR-03 Erro de lowering expõe identificadores internos sem localizar a causa
**P1 · Observado; reprodução mínima pendente.**
Durante uma tentativa de consumir Animator por uma factory local, o build falhou
com `MARSHAL_VERIFY_PRECHECK_BAD_RET_STACK_HEIGHT`,
`expected=0 actual=1 [fn=52] [pc=392]`.
Impacto: o diagnóstico não permitiu identificar a expressão PBS responsável.
A consulta direta aos frames foi a alternativa que compilou.
Melhoria: anexar nome da função, arquivo, intervalo de fonte e caminho de chamada.
Investigar o caso antes de atribuir o defeito ao tipo result ou ao Animator.
### ATR-04 Misturar Gfx e Composer pode ocultar sprites
**P2 · Observado em capturas e confirmado pela leitura do pipeline.**
Uma área desenhada com `Gfx.clear` e `Gfx.fill_rect` cobriu Link, embora a emissão
do sprite tivesse sido aceita. Nesse pipeline, as primitivas Gfx são aplicadas
como overlay depois da composição canônica.
Impacto: a cena pareceu não desenhar o personagem, sem erro de execução.
Melhoria: documentar a ordem de desenho perto das APIs e do exemplo inicial;
fornecer um exemplo de fundo de cena com sprite, distinguindo-o de overlays.
O comportamento observado é compatível com a ordem implementada; não foi
demonstrado um defeito do rasterizador.
### ATR-05 Sprites sem cena deixaram rastros entre frames
**P2 · Observado em capturas e confirmado pela leitura do caminho sem cena.**
Depois de remover o overlay, desenhar apenas sprites sem vincular uma cena
manteve pixels de frames anteriores. Vincular uma cena vazia resolveu os rastros.
Impacto: até um teste simples de movimento precisou de um banco de cena adicional.
Melhoria: tornar explícita a política de limpeza de frames sem cena e oferecer
um caminho mínimo de produção para fundo vazio com sprites, sem configuração
manual inesperada.
### ATR-06 Estado de devolução de controle ficou ambíguo
**P2 · Uma ocorrência observada.**
Uma chamada de release retornou `CLEANUP_FAILED: Project control: BUSY`.
A chamada seguinte retornou `WAITING_FOR_ACCESS`. Em entregas posteriores,
shutdown do runtime seguido de release retornou `MANUAL` normalmente.
Impacto: ficou incerto se o controle já havia sido devolvido e se a interface
precisaria de atualização. A causa do primeiro episódio não foi identificada.
Melhoria: retornar o estado final de autoridade mesmo quando o cleanup falha,
separar pendências de limpeza de concessão de controle e indicar recuperação.
### ATR-07 Mensagens de sucesso intermediário coexistem com falha do build
**P2 · Observado no erro inicial do projeto.**
O log mostrou `builder pipeline completed successfully` após
`E_LINK_UNRESOLVED_BARREL_ENTRY` e terminou com
`issues found on pipeline stage: analyze`.
Impacto: o usuário precisa interpretar linhas aparentemente contraditórias
para entender se o jogo compilou.
Melhoria: distinguir etapa executada de resultado válido e destacar um único
resultado final. Para o barrel exportando `init` inexistente, oferecer navegação
ao símbolo e explicar as opções de declarar a função ou ajustar a exportação.
### ATR-08 Importação de bancos pelo agente exige edição de manifestos
**P2 · Lacuna nas ferramentas disponíveis nesta sessão.**
Havia ferramentas para animações, linguagem, build e runtime. Não havia uma
operação anunciada de importação/criação/registro de banco de PNGs. Foi necessário
escrever `asset.json`, seleção de artefatos e o índice de registro pelo filesystem.
Impacto: o fluxo de produção precisou conhecer formatos de persistência e IDs.
Isso não demonstra ausência dessas operações na interface manual do Studio.
Melhoria: expor importação em lote, criação e registro de banco, composição e
consulta de layout com as mesmas validações e proteção de revisão do editor.
Nova ocorrência ao montar a sala inicial: foi preciso registrar um banco de
21 tiles, gerar a requisição de cena 32×30 e excluir o banco vazio do build
editando os formatos de persistência. O fluxo compilou, mas uma operação de
importação de tilemap pelo conector reduziria o conhecimento de formatos exigido.
### ATR-09 Boot com escolha explícita de memória falhou
**P2 · Uma ocorrência observada; causa ainda pendente.**
`studio_headless_boot` com `memcardChoice=memory_fresh` retornou
`MEMCARD_ERROR`, `boot: invalid_state`. A consulta seguinte informou ausência
de sessão ativa. Boot sem esse parâmetro funcionou.
Impacto: uma escolha explícita anunciada pela ferramenta interrompeu o teste.
Melhoria: reproduzir a sequência em uma sessão nova e documentar/validar as
precondições da escolha antes de iniciar o boot. Não há evidência de perda de dados.
### ATR-10 Uso normal do PBS depende de consultar a implementação Java
**P1 · Atrito observado repetidamente pelo agente e apontado pelo usuário.**
Para dividir arquivos, interpretar visibilidade, resolver imports e compreender
falhas de lowering, o agente consultou parser, serviços semânticos e testes Java
do compilador. Esse caminho exige acesso e familiaridade com o código interno
do Prometeu para realizar tarefas comuns de autoria de um jogo.
Impacto: aumenta o tempo de produção e dificulta o uso por quem conhece apenas
PBS e o Studio. A consulta ao Java também pode refletir uma investigação de bug,
não necessariamente uma regra ausente da linguagem; registrar essa distinção.
Melhoria: oferecer um guia de produção com exemplos completos e compiláveis de
módulos, barrels, estado mutável, construtores, imports e consumo de animações.
Vincular cada diagnóstico à regra e ao exemplo correspondente. Manter exemplos
validados contra o SDK instalado e explicitar limitações conhecidas.
Conduta neste port: consultar primeiro as referências e exemplos expostos pelo
Studio; recorrer à implementação somente quando houver lacuna, contradição ou
um defeito a investigar. As referências `pbs:spec:3` e `pbs:spec:5` do Studio
foram consultadas para a divisão atual em módulos.
Exemplo concreto de desatualização: `pbs:spec:5`, seção 5.2, apresenta
`import { Gfx, color } from @sdk:gfx` e `Gfx.draw_pixel(...)`. A referência
instalada `pbs:sdk:game:1:sdk/gfx/main.pbs` usa `Color` de `@core:color` e não
declara `draw_pixel`. Isso reforça a necessidade de validar exemplos contra
o SDK distribuído.
### ATR-11 Tipo de cena importado falhou no build sem diagnóstico de fonte
**P1 · Observado na divisão em módulos; causa e reprodução mínima pendentes.**
Uma versão com `pub struct Scene`, `new Scene.make()` na raiz e uma referência
Scene recebida pelo módulo Link falhou no build com
`Unsupported PBS runtime type: Scene`. Quatro consultas de diagnostics retornaram
`INFRASTRUCTURE_FAILURE: LSP query failed`, sem apontar um intervalo PBS.
Impacto: a tentativa de encapsular objetos entre módulos não forneceu informação
suficiente para distinguir uma limitação de autoria de um defeito do compilador.
Isso não demonstra que todos os structs importados sejam incompatíveis.
Alternativa validada: APIs públicas `Link` e `Scene` como services, com structs
internos no módulo Link. Build e diagnostics passaram, e as 58 capturas de
regressão continuaram idênticas. A documentação de services foi consultada pela
API de referências, sem uma nova consulta às fontes Java para essa alternativa.
Melhoria: reduzir o caso com tipos e construtores importados, produzir um erro
com localização no fonte e manter o LSP funcional mesmo quando o lowering falha.
### ATR-12 Apresentação de uma área de jogo menor exige composição manual
**P2 · Lacuna na superfície de autoria consultada; solução local validada.**
O port mantém a área NES de 256×240 dentro do framebuffer 480×270. A referência
`@sdk:composer` consultada expõe câmera, vínculo de cena e emissão de sprites,
sem parâmetros de retângulo de viewport, clipping ou escala de apresentação.
A especificação GFX documenta resolução base fixa e escala pelo host.
O usuário preferiu manter 1:1 e colocar a imagem numa caixa. A implementação
local calcula centralização, desenha uma moldura externa e encobre as regiões
fora da área NES com overlays. Os seis testes visuais passaram, preservando os
pixels internos e limitando a espada na borda inferior.
Impacto: um encaixe comum de jogo com outra resolução lógica exige conhecer a
ordem Composer/Gfx e implementar manualmente máscara e moldura. Não foi provada
a ausência de todo suporte interno a viewport no runtime; a lacuna constatada
é a configuração disponível ao autor do projeto nas referências consultadas.
Melhoria: oferecer uma configuração documentada para área lógica, encaixe 1:1,
clipping e, futuramente, escala inteira no host. Preservar a imagem canônica
do runtime e tornar explícita a diferença entre área de jogo e apresentação.
### ATR-13 Reset headless retornou sucesso, mas a sessão ficou terminada
**P2 · Uma ocorrência observada; causa pendente.**
Após boot e um frame correto, `studio_headless_reset` retornou sem erro.
O avanço seguinte pediu 200 frames e devolveu `TERMINATED`, com zero frames
executados. `studio_headless_state` mostrou appId 0, pc 0, logicalFrameIndex 0.
Encerrar e iniciar outra sessão com o mesmo build permitiu executar os 200
frames. As 14 verificações usaram sessões novas, evitando depender do reset.
Melhoria: investigar o reset e retornar explicitamente um estado que permita
saber se o aplicativo continua executável; cobrir reset seguido de avanço.
Não foi constatada uma falha do código PBS nesse episódio.
### ATR-14 Prioridade do sprite em relação aos pixels do fundo não tem contrato explícito na referência consultada
**P2 · Lacuna de documentação observada; não demonstra ausência de suporte interno.**
A entrada e saída da caverna NES usam o bit de prioridade do sprite para esconder
partes de Link atrás dos pixels de fundo cujo índice não é zero. A referência
pública `@sdk:composer` documenta `layer` e `priority`, mas não descreve um modo
com essa semântica por pixel em relação ao tilemap.
O port optou por gerar 68 variantes locais do corpo, mascaradas conforme os
índices originais do terreno em cada posição da porta. As capturas de entrada
e saída corresponderam à composição esperada. Essa solução adiciona assets e
acopla as máscaras à abertura específica. Nenhum defeito do parâmetro `priority`
foi demonstrado; sua equivalência à regra NES não foi assumida.
Melhoria: documentar a relação entre prioridade de sprites, camadas e fundo,
com um exemplo de oclusão de atores por tiles e índice transparente. Avaliar
uma configuração de oclusão no cenário para dispensar variantes por posição.
### ATR-15 Compor elementos mutáveis sobre o terreno fixo
**Aprendizado de composição do port · escolha estática corrigida. Não é defeito do runtime.**
A primeira implementação incorporou texto, velho e espada ao tilemap e usou
três scenes para coleta e desaparecimento. Essa escolha nossa gerou rebinds
ao piscar o velho; não era uma necessidade do Prometeu nem uma restrição de
sprites. Não atribuir esse custo ao runtime.
A refatoração mantém o terreno numa única scene ativa e emite velho, espada,
fogo e letras como sprites/glyphs independentes, com visibilidade comandada
pelos estados existentes. O fundo do inventário contém só terreno e recebe
os mesmos objetos deslocados durante sua rolagem. A identidade visual da
stage permanece constante durante coleta e piscadas. IDs de assets e glyphs
anteriores são preservados; scenes 2/3 ficam reservadas para não deslocar
os IDs das demais telas.
Aplicar o mesmo padrão às paredes bombáveis: passagem no terreno base,
cobertura mutável desenhada à parte, e uma flag persistente compartilhada
por render, colisão e entrada. Não multiplicar scenes por combinações de
objetos/segredos. Referência prática: `docs/scene-composition.md`.
Revalidação: dez capturas de terreno + sprites foram idênticas aos compostos
NES anteriores, incluindo velho visível/oculto, espada/texto removidos e duas
rolagens parciais do inventário. 2.573 sondas da caverna continuaram iguais à
rotina nativa. Asserções conferiram coleta, flag, posse, timer, pausa e revisita,
com chave de scene e variante do inventário constantes. No build normal,
inputs percorreram a entrada e a coleta com Link erguendo a espada; o submenu
abriu depois da coleta. Nenhum perfil foi escrito no cartão do usuário.
Regeneração idempotente em 1.176 arquivos; os 44 glyphs legados mantiveram seus
bytes e IDs. Evidências em `extracted/cave/start/composition-validation`.
Build final 5e713d48 aprovado, diagnostics vazios nas cinco fontes consultadas.
### ATR-16 Ensaiar serviços de gameplay exigiu trocar temporariamente a entrada do projeto
**P2 · Custo observado na superfície de testes utilizada.**
Para testar cura, limites e morte sem adicionar teclas de debug ao jogo,
foi gerado um `main.pbs` de ensaio e compilado temporariamente no mesmo projeto.
A entrada normal foi copiada de volta antes do build jogável. A ferramenta
`studio_build_start` consultada recebe a raiz do projeto e não uma entrada ou
target de teste separado.
Impacto: aumenta o cuidado com restauração e rastreamento do build testado.
Não foi demonstrado que todo mecanismo interno de testes tenha essa limitação.
Melhoria: oferecer um target de testes com entrada própria, assertions e estado
consultável, preservando o source de produção e o fluxo de Play normal.
O ensaio usou apenas referências públicas e PBS, sem acesso às fontes Java.
## Primeiras prioridades propostas
1. Resolver endereçamento de projetos e reprodução mínima da divisão em arquivos
(ATR-01 e ATR-02), pois afetam a organização normal de um jogo.
2. Tornar erros de lowering localizáveis no PBS (ATR-03).
3. Entregar um exemplo mínimo de sprites com fundo e limpeza corretos
(ATR-04 e ATR-05).
4. Melhorar resultado final do build, importação de assets e estados de controle
(ATR-06 a ATR-09).
## Avaliação de interface ainda a fazer
Observar diretamente os fluxos do editor: importar PNGs, encontrar um banco,
montar/reordenar frames, escolher paleta, dar Play e retornar ao código.
Anotar ações necessárias, passos repetidos, retorno visual e recuperação de
erro. Ainda não atribuir problemas de layout, descoberta ou usabilidade visual
a painéis que não foram inspecionados.
## Abertura e ciclo principal — 2026-11-06
### BOM-14 — Composição fiel com bancos indexados e sprites
Título extraído da ROM usa atributos, paletas, flips e prioridade de sprites.
Trinta e sete comparações de capturas do Studio passaram sem diferença de pixels,
abrangendo também menu e transições. A composição reutiliza Scene e o viewport
existentes; onze consultas de diagnostics ficaram vazias. Evidência e protocolo:
`extracted/game_flow/validation`. Referências públicas foram consultadas antes
originalmente; nenhuma consulta Java foi necessária nesta etapa.
### ATR-17 — Limite de bancos aparece como falha genérica no boot
Uma versão inicial pré-carregava 17 cenas, incluindo slot 16. O build aceitou,
mas o boot headless falhou com BackendError, sem identificar o asset/slot.
Após consultar as referências disponíveis, a investigação em
`runtime/crates/console/prometeu-drivers/src/memory_banks.rs` confirmou arrays
com 16 posições; `asset.rs` reduz falhas de preload a BackendError. Esta é
investigação do runtime Rust, não consulta Java para aprender PBS.
Impacto: um build aprovado não garantia cartucho inicializável e o diagnóstico
não apontava a configuração responsável. Sugestão: validar limites no pack/build
e propagar asset, tipo de banco e slot no erro de boot. Contorno aplicado:
compartilhar quatro cenas entre as oito fases de brilho; total atual 13 cenas.
Boot e ciclo completo revalidados. A validação antecipada do produto continua
pendente; o contorno no jogo não representa correção do runtime.
Lição do port: offsets de tabelas em disassembly de referência divergiam da ROM
fornecida. A extração passou a seguir os ponteiros reais do cartucho. Isso não
é defeito do Prometeu e não deve ser contabilizado como problema de interface.
## Sala norte e Octoroks — 2026-11-06
### BOM-15 — Composição e testes determinísticos sustentam o port
Cenário norte e encontro extraídos da ROM, publicados em bancos separados e
observados no Studio. Três capturas completas coincidiram pixel a pixel com
composição dos patterns/paletas originais; 32 asserções executadas no guest
passaram. As 3.672 sondas confrontadas com a rotina 6502 verificam o modelo de
colisão fora do Studio. Referências SDK foram lidas pelo conector; nenhuma
consulta Java foi necessária. Evidências em `extracted/overworld/north/validation`.
### ATR-02 / ATR-03 — Reincidência em expressões com chamadas
O build falhou em lowering com `MARSHAL_VERIFY_PRECHECK_BAD_RET_STACK_HEIGHT`,
`expected=1 actual=2 [fn=72] [pc=363]`; após contornar expressões, outro ponto
surgiu como `[fn=235] [pc=78]`. A fixture também expôs retorno `expected=0
actual=5 [fn=70]`. Guardar resultados de chamadas em locais antes de comparações,
expressões e argumentos resolveu o conjunto. Não foi isolada a causa de cada
caso: esses IDs não mapeiam diretamente a arquivos PBS no diagnóstico. Manter
como reincidência do problema já registrado, não nova causa confirmada.
Chamadas entre serviços de arquivos do mesmo módulo na fixture também precisaram
import explícito do serviço; o compilador retornou erro localizado de overload.
### ATR-04 — HUD durante rolagem exige camada acima do cenário
Primeira captura da câmera vertical mostrou o mapa cobrindo o HUD que era emitido
na camada 0. Passar o HUD para a camada 2, preservando personagens na 1, resolveu
e foi verificado nas capturas. A referência de Composer documenta câmera/camada,
mas não explica suficientemente a interação de tilemap ativo com sprites na
mesma camada. Sugestão: exemplo de HUD fixo com cenário em rolagem e ordem de
composição explícita. O sintoma foi observado no runtime; não é avaliação visual
de painel do editor. A camada atual está anotada no código e nas orientações.
Lição de extração: nuvens usam CHR herdada da abertura, fora do bloco de sprites
OW. A conferência visual encontrou a omissão e a ordem de carga foi corrigida.
Isso é particularidade do cartucho, não defeito do Prometeu.
## Correção dos gráficos do Octorok — 2026-11-06
Erro do port, não do Prometeu: o extrator omitia o incremento de tipo no caminho
DrawObjectWithType e ignorava flip vertical dos frames para cima. Octoroks usavam
frames de outra animação e a pedra selecionava tile $98 em vez de $9E.
O validador copiava a hipótese de índice incorreta; suas três capturas não
incluíam pedra visível. Assim, a evidência pixel a pixel de BOM-15 não provava
fidelidade da interpretação dos descritores. Os testes de colisão e dano eram
separados e não detectariam esse erro de composição.
Correção de produção: descritores obtidos por execução limitada do código 6502
original, sem consultar Java. Uma fixture no Studio desenha os oito frames e
uma pedra visível simultaneamente; as nove imagens e o framebuffer completo
coincidiram com os descritores da ROM. A fixture foi removida antes do build
jogável. Evidência: `extracted/overworld/north/validation/graphics_fix`.
Lição: validar todos os estados visuais relevantes e usar um oráculo que não
repita a mesma suposição do extrator. Não atribuir a falha ao renderer ou à UI.
## Ciclo de combate, drops e projéteis — 2026-11-06
### BOM-16 — Produção modular e validação de estados visíveis
Histórico, inventário, loot, personagem e apresentação permaneceram separados.
Um banco de 30 patterns 8×8 atende itens, projétil, dispersão e dígitos, incluindo
sprite NES ímpar que seleciona a tabela de background. Comparações das folhas
visuais no Studio passaram sem diferença de pixels; o HUD inicial permaneceu
idêntico após trocar os contadores fixos por valores de Items. Dados e imagens
em `extracted/combat`. Os testes no guest verificaram 2.214 condições, além das
verificações internas de projétil e ricochete, e foram seguidos por sessão real
com coleta e histórico de mortes. Dezenove fontes tiveram diagnostics vazios.
Referências SDK e código 6502 foram suficientes; nenhuma consulta Java.
### ATR-18 — Inicialização global limita uso de factories encapsuladas
**Restrição observada; não classificada como defeito do compilador.**
Declarações globais `loot0: DroppedItem = Loot.new_item()` foram rejeitadas com
`E_SEM_GLOBAL_UNSUPPORTED_INITIALIZER`, com nome do global e localização. A
construção direta com `new DroppedItem(new FairyFlight(...),...)` compilou, mas
exigiu expor o tipo auxiliar FairyFlight no barrel para o módulo consumidor.
Impacto: composição de estado de módulos precisa expor mais detalhes ou criar
uma estratégia adicional de inicialização. Sugestão: documentar o padrão
recomendado de factory/Init e considerar factory pura suportada em globals.
O diagnóstico foi localizado; não foi necessário consultar a implementação.
### Procedimento de teste — watchdog e lotes por frame
Executar toda a fixture grande no Init atingiu o watchdog headless de 100.000
ticks de firmware, com resultado tipado `INFRASTRUCTURE_FAILURE` e
`watchdog_expired`. Distribuir casos em 93 frames resolveu sem alterar runtime
ou orçamento do jogo. Guardar esse padrão nos exemplos de testes guest; não
tratar o limite acionado pelo teste como falha de gameplay ou defeito de UI.
Lição de validação mantida da correção anterior: conferir os estados visíveis
por descritores executados da ROM, não apenas por tabelas reinterpretadas pelo
mesmo extrator. As folhas desta etapa incluem todos os drops relevantes, as
quatro direções do projétil e o ricochete em fases diferentes.
## Tela de inventário — validação no Studio
**Bom:** APIs de input, composição, camadas, câmera e sprites indexados foram
suficientes para portar o submenu sem consultar fontes Java. O HUD conserva
layer 2 e acompanha a rolagem; seleção e posse ficaram separadas de Link e da
stage. Os quatro bancos nativos de paleta de sprites atendem todos os ícones.
**Evidência:** build de produção aprovado, quinze documentos PBS com diagnostics
vazios, 1.104 comparações da busca de seleção contra execução 6502 da ROM e três
veredictos de integração no guest: bombas, pausa/retomada e poções/seleção. Todos
passaram. A comparação visual independente encontrou igualdade nas 1.125 amostras
opacas dos ícones (retângulo sobreposto pelo cursor excluído). Gerador de assets
reexecutado sem mudança em 245 arquivos. Fixtures ficaram fora de src após o teste.
Resultados e capturas em `extracted/inventory_screen/validation`.
**Restrição de produção:** há 16 slots de scene. O submenu ocupa o último,
compartilhando os cinco fundos congelados em faixas de uma única scene longa.
Isso compilou e executou no Studio. Ajuda futura: mostrar orçamento de scenes
no editor e documentar padrões de carregamento/reutilização para jogos maiores.
**Limite de fidelidade ainda aberto:** a API Gfx/Assets consultada não documenta
um controle de grayscale global equivalente ao PPUMASK do NES. A bomba mantém
fusível, nuvens, dano e consumo, mas falta esse flash global. Não foi necessário
alterar o runtime para concluir o menu; avaliar filtro de tela/paleta no SDK.
**Diagnóstico do compilador em fixture:** uma versão de teste recebeu
`MARSHAL_VERIFY_PRECHECK_BAD_RET_STACK_HEIGHT`, identificando função por número
(`fn=201`, `pc`) sem arquivo PBS. Foi possível concluir os mesmos objetivos em
rotinas menores com resultados intermediários explícitos. Causa não isolada;
não atribuir genericamente a chamadas aninhadas. Sugestão: mapear o verificador
para nome de função/arquivo/span, preservando o detalhe técnico para investigação.
## Percurso de bombas — salas OW $66/$65/$64
**Bom:** reaproveitar as scenes 13/14/15 como atlas permitiu acrescentar três
stages independentes, três transições horizontais reversíveis, HUD e inventário
por sala sem ultrapassar 16 scenes. Câmera X/Y e glyphs com paletas alternativas
atenderam cenários de cores diferentes. Nenhuma consulta Java nem alteração do
runtime. O pool de inimigos/drops foi ampliado para cinco.
**Validação:** build final aprovado, quinze fontes com diagnostics vazios,
2.560 execuções nativas do drop de azul sem divergências. Fixture guest passou
ida/volta nas três salas, HP de dois golpes, imunidade, geração nativa do drop,
coleta de quatro bombas e consumo de uma pelo B. Capturas e resultados em
`extracted/overworld/northwest`; fontes de teste removidas de src antes do build
final. Não há alegação de equivalência completa por frame com o jogo emulado.
**Produção:** a regeneração de assets ainda exige ordem explícita: north,
bomb_route, inventory_screen. Como o último banco de cena já foi ocupado,
novas stages dependem de layout e orçamento dos atlas compartilhados. Sugestão:
manifesto de geração com dependências e visualização do orçamento no Studio.
**Diagnóstico:** o verificador backend voltou a informar erro de altura de
stack somente com número de função e PC em uma fixture. Resultados locais
explícitos permitiram concluir o teste. Consolidar com o registro anterior;
a ausência de nome/arquivo continua sendo a dificuldade observada.
**Lição do port:** a pesquisa na internet identificou duas fontes legítimas de
bombas (loja e Octoroks azuis). A ROM foi necessária para escolher o menor
percurso atual: atributo D bit 7 integra o ID de lista. O valor C=$69 nas salas
intermediárias resolve para uma lista mista vermelha, não para tipo $09. Dados
publicados incluem ponteiro e bytes completos das listas; não basear spawns
apenas nos seis bits baixos de C.
## Bomba temporária para teste solicitado pelo usuário
Exceção explícita à fidelidade dos itens iniciais: um pacote nativo de quatro
bombas foi colocado em ($98,$8D), à direita de Link. A posse continua passando
por Inventory.take_drop; o objeto de teste pertence à stage inicial e não muda
as tabelas da ROM nem o inventário inicial. Um único const em
`src/stages/overworld_start/test_bomb.pbs` permite desativá-lo. O registro de
coleta dura até partida nova; Continue e retorno à sala não recriam o pacote.
Respawn foi conferido novamente em ModifyObjCountByHistoryOW: sala limpa e
presente no histórico de seis entradas permanece limpa. O código atual mantém
essa regra; não trocar por respawn imediato para facilitar o teste de bombas.
Durante a verificação por input headless, capturas não corresponderam à
sequência esperada de botões (por exemplo, um comando right foi seguido por
menu aberto). Causa não isolada; não atribuir a defeito do teclado do Studio.
O teste de coleta/consumo foi executado também diretamente na máquina GameFlow,
sem depender dessa automação de botões. Capturas ficam separadas por nome.
Resultado: os seis checkpoints guest passaram (zero inicial, coleta +4, B -1,
menu sem consumo, retorno sem recriar, partida nova recria). HUD capturado
mostrou 4 após coleta e 3 após uso; a explosão foi renderizada. Fixture removida
de src antes do build final. Nenhum novo asset ou slot de scene foi necessário.
## Parede bombável — mecanismo OW e montagem temporária
**Bom:** os glyphs de terreno existentes e composição de sprites foram
suficientes para cobrir a abertura, inclusive no fundo congelado do inventário
e durante ambas as rolagens verticais. Não foi necessário mais um asset, slot
de scene ou alteração de runtime. A caverna, a espada e as transições existentes
foram reutilizadas. Nenhuma consulta a fontes Java.
**Evidência:** 121 casos de colisão executados no leaf 6502 real foram conferidos
no guest. Passaram também flags independentes, fusível sem revelar, detonação,
prioridade de bomba, entrada bloqueada/aberta, coleta da espada, saída da
caverna, Continue e reset de partida. Cinco recortes 16×16 de terreno (fechado,
inventário, duas rolagens e abertura restaurada) coincidiram exatamente com os
PNGs nativos. Fontes de fixture restauradas antes do build de produção; dados
em `extracted/bomb_wall`.
**Dificuldade de PBS:** após acrescentar dependências à stage inicial, chamadas
para RoomData.tile_at/normalize_tile/first_unwalkable/contains_player passaram a
receber `E_SEM_EXEC_LOWERING_UNRESOLVED_CALLEE`, sem mudança nesses métodos.
Renomear apenas a variável global não resolveu; dar ao tipo o nome específico
StartRoomData resolveu as quatro chamadas. Outras stages têm tipos locais
chamados RoomData. Causa interna não isolada; registrar como suspeita de
resolução de identidades com nomes repetidos/ciclos, não como diagnóstico
confirmado. Sugestão: incluir módulo/identidade do receiver no diagnóstico e
cobrir essa composição nos testes do compilador.
## Encerramento dos testes temporários de bomba
Após aprovação do usuário, os dois toggles de teste foram desativados: pacote
inicial e parede na entrada da espada. A abertura e o inventário inicial voltam
ao comportamento original; drops dos Octoroks, bombas, flags e mecanismo de
paredes permanecem. Os toggles permitiram encerrar a montagem sem tocar em
assets nem na lógica de produção validada. Capturas anteriores são históricas.
Verificação do encerramento: build de produção aprovado e diagnostics vazios
nas duas fontes alteradas; ambos os toggles conferidos como false.
## Save no memcard — perfil único
**Bom:** referências instaladas MEMCARD.md, exemplo e @sdk:mem foram suficientes
para implementar bootstrap, metadados/ícone, RAM do slot, commit, query e
release sem consultar Java. O resultado tipado separa aceitação de pedido,
durabilidade e memória apenas. O jogo só mostra GAME SAVED após state 1;
state 4 recebe MEMORY ONLY / NOT SAVED TO CARD. O runtime continua responsável
por montagem, publicação, recuperação e descarte de sessão.
**Evidência:** gravação durável confirmada, processo encerrado e mesmo cartão
reaberto em novo processo; os 180 bytes coincidiram com payload independente
Python/Adler-32, incluindo 00/7f/80/ff. Progresso, três corações com capacidade
preservada, relógio temporário e história reconstruída foram conferidos no
guest. App version 1.0.0→1.0.1 manteve acesso com app_id estável. Cartão RO em
memory_existing bloqueou Save e permaneceu idêntico byte a byte; memory_fresh
terminou sem alegar gravação. Magic inválida, schema não suportado e slot
truncado foram rejeitados sem alterar seus payloads. Dois recortes de UI
coincidiram pixel a pixel com composição independente de patterns NES.
Dados, capturas, limites e testes em `extracted/save`.
**Proteção útil do host:** PERSISTENT com mídia RO foi recusado antes de admitir
o jogo, com reason read_only; memory_existing permitiu carregar essa mídia.
Após teste em memory_fresh, shutdown/build recusou RAM suja com unsaved_changes.
Só a RAM da fixture descartável foi descartada explicitamente para continuar.
Não transformar essas recusas em sucesso nem descartar progresso do usuário.
**Produção:** fonte NES e ícone de Link foram gerados a partir dos assets/ROM,
reutilizando o banco de glyphs e a scene do menu. Nenhum slot de scene adicional.
Regeneração idempotente em 49 arquivos; prepare_game_screens encadeia a etapa
save_ui para não restaurar inadvertidamente o antigo menu sem SAVE.
**PBS:** imports de services privados do próprio módulo foram recusados com
E_LINK_IMPORT_SYMBOL_NOT_PUBLIC; convertê-los em structs auxiliares privados,
como os demais módulos, manteve o codec/ícone encapsulados e compilou. Registrar
esse padrão nos exemplos de composição de módulos; não foi necessário expor
helpers de serialização ao jogo nem recorrer às fontes Java.
**Lição de fidelidade:** copiar os bytes completos de WorldFlags segue o save
original; não mascarar todos os kills por suposição. O histórico de seis salas
não é salvo. Conferir offsets absolutos também importa: InvClock=$066C menos
Items=$0657 é slot $15, não $14. A fixture distingue e preserva o slot vizinho.
Nenhuma alegação de teste de corte de energia durante IO ou emulação lockstep.
**Verificação final pela interface do jogo:** em build sem fixtures, inputs
headless com dois frames de pressão/liberação percorreram título, New Game,
menu vivo, seleção de Save, confirmação, GAME SAVED, encerramento do processo
e Continue no boot seguinte. O cartão padrão `.studio/memcard.pmc` foi criado
pelo host sem receber perfis de teste; todos os testes de payload ficaram em
imagens separadas de .tmp. A captura inicial SAVING permaneceu correta até o
Frame observar o commit já retornado pelo runtime: não confundir fim do avanço
de frames com espera de IO. Não foi necessário alterar o input do jogo.
Esse procedimento também evita atribuir ao teclado um possível erro de
sequenciamento das capturas headless mencionado no teste temporário anterior.
Build final aprovado e diagnostics vazios em 12 fontes PBS; nenhuma fixture
permaneceu em src. O boot de produção com o cartão padrão foi revalidado.
## Expansão do overworld — nove salas
**Produção positiva:** atlas compartilhados permitiram adicionar quatro salas,
18 conexões direcionadas e 12 faixas de inventário mantendo os 16 slots de
scene existentes. Cada stage continua dona da colisão e do render, com catálogo
ROM compartilhado para identidade, inimigos e apresentação. Não foi necessário
consultar fontes Java. Build/pack e headless permitiram conferir dados e pixels.
**PBS observado:** `return data.edges(stage)!=0` produziu
E_SEM_EXEC_LOWERING_UNRESOLVED_CALLEE na chamada, apesar do método existir.
Separar em `let value=data.edges(stage); return value!=0` compilou. Causa interna
não investigada; sugerir cobertura/documentação desse formato de expressão e
um diagnóstico mais específico. A consulta LSP localizou o mesmo intervalo.
**Limite de fixture:** uma função de Frame com 1.814 condicionais sequenciais
foi recusada com MARSHAL_VERIFY_REGISTRY_INVALID / verification scratch limit.
Agrupar ações repetidas por intervalo resolveu o build. O jogo normal já
compilava. Melhorar a mensagem com a função/limite relevante; isso foi um
limite de produção de teste, não um defeito visual da interface.
**Evidência de fidelidade:** 16.524 sondas contra a rotina de colisão nativa e
192 buscas de entrada contra FindNextEdgeSpawnCell 6502 passaram. A fixture
executou 1.814 frames, conferiu as 18 transições, os quatro encontros com
entrada pelas bordas e a expulsão do histórico de seis salas preservando item.
45 comparações de terreno/HUD/inventário/destinos foram exatas. A primeira
fixture esqueceu de zerar o offset de HUD como GameFlow faz; foi corrigida na
fixture, sem atribuir esse erro ao runtime. Evidências em
extracted/overworld/expansion. O save mantém seu formato e os IDs nativos.
**Limites explícitos:** as quatro novas salas não têm Zora; o catálogo revelou
que a antiga $65 tem essa flag e o port desse inimigo continua pendente.
Entradas de cavernas e segredos das novas salas ainda não têm interação.
Build final e5d139e4 aprovado; diagnostics vazios nas seis fontes centrais
consultadas. Regeneração idempotente em 1.148 arquivos. No build normal, inputs
percorreram título, New Game e a ligação $77→$78; Octorok entrou pela borda e
o inventário abriu na sala nova. Testes usaram memory_fresh; o cartão do usuário
não recebeu gravações. Fixtures restauradas e controle do Studio devolvido.
## Retomada — Zora da sala $65 (09/11/2026)
**Lacuna de conteúdo encerrada:** o encontro extra do atributo A&$08 está em
src/enemies/zora, separado dos Octoroks e da contagem de mortes da sala.
Submersão natural permite novo surgimento; morte bloqueia o ator nessa visita.
Bola de fogo usa mira/tabela angular nativas e exige escudo mágico para bloqueio.
**Produção positiva:** referências PBS e exemplos do projeto bastaram; não
foram consultadas fontes Java. Sete glyphs foram acrescentados ao banco 11,
preservando os anteriores e sem nova scene. O ciclo foi comparado no guest a
388 ticks da rotina 6502; 1.369 pares de distâncias conferiram o cálculo de
ângulo. Sete comparações de assets e doze de composição foram exatas.
Headless permitiu também observar Zora, tiro, Octoroks, inventário e saída da
sala usando Game.frame, com posicionamento inicial isolado para teste.
**Erro de port detectado pelo runtime:** a rotina NES lê Random+$0D, byte
adjacente ao array de 13 bytes. Uma tradução que usou random[13] produziu trap
Bounds em Zora.update, com função e span identificados. O fallback `else 0`
não torna esse índice válido. O byte adjacente foi modelado explicitamente,
sem ampliar indevidamente o array de random nem enfraquecer a checagem.
Esse foi um erro nosso de acesso, não um defeito do runtime. A fixture passou
após a correção. `spawn` e `step` também foram identificados como palavras
reservadas e os nomes da implementação foram corrigidos.
**Limites explícitos:** não se alega equivalência integral de todo o alocador
NES; seis instâncias de Fireball atendem ao encontro atual e respeitam o teto
contabilizado de onze slots com os atores/tiros/drops existentes. Armas ainda
não portadas permanecem fora da validação. Evidência: extracted/zora e docs/zora.md.
Regeneração idempotente em 1.188 arquivos; fixtures restauradas. Nenhuma gravação
no cartão do usuário; testes em memory_fresh. O próximo recorte da lista aceita
é um segredo bombável real, seguido de loja e expansão com objetivo.
Build final dee2921c aprovado; diagnostics vazios em seis fontes consultadas.
Boot e New Game conferidos novamente com entrada de produção restaurada.
## Segredo bombável real da sala $67 (09/11/2026)
**Conteúdo nativo integrado:** tile object $E6 em (112,80), entrada (112,77),
caverna $7B com Moblin e prêmio de 30 rupias. Tipo, preços, texto e quest
foram conferidos nos bytes da ROM. Estado de abertura ($80), coleta ($10) e
mortes baixas permanecem separados no mesmo byte OW103. O NPC/texto/prêmio
permanecem na visita da coleta; na seguinte ficam somente os fogos.
**Composição adequada ao Prometeu:** passagem no terreno e cobertura opaca de
quatro glyphs enquanto fechada; sprites independentes no interior. A parede
segue os offsets das quatro direções de scroll e do submenu. Nenhuma scene
por estado e nenhum slot adicional. A stage interna 10 reutiliza o terreno 1,
mas mantém módulo e colisão próprios. A API is_cave evita registrar visitas
fictícias no histórico de inimigos. Retorno guarda origem/X da entrada.
**Fidelidade:** a abertura imediata usa quatro tiles $24; a reconstrução de
sala usa secundário $0C ($F3/$24 por coluna). Ambos os patterns são pretos,
mas os IDs diferem; wall_fresh mantém a distinção por visita. A máscara de
porta inicial só foi reutilizada após comparar seus 4.352 pixels de suporte
com a geometria da entrada real. O descritor de Moblin precisa do ObjAttr=$81
que SetUpCommonCaveObjects aplica; ler a tabela genérica produz meia figura.
Essas eram decisões/regras do port, não falhas do compositor.
**Verificação:** 121 contatos contra a rotina 6502, oito recortes visuais
exatos, sequência com bomba/fusível/consumo/entrada/crédito/saída/revisita e
commit em cartão descartável. Payload reaberto com checksum válido, bombas=3,
rupias=30 e flags=$91; o cartão padrão do usuário não foi usado. No build normal,
foram testadas a caverna da espada com coleta/saída e a caminhada após Continue
até a caverna secreta já coletada, usando o cartão de teste somente para leitura.
**Lição de fixture:** consultar disponibilidade do save no Init ainda retornava
false nesse ensaio; a leitura foi movida para o primeiro Frame, após MemcardBoot.
As primeiras asserções verdes cobriam o ramo de partida nova e não provavam
reload. A comparação visual detectou a parede fechada e impediu o falso sucesso;
após corrigir a fixture, imagens e checks de flags/moeda/carga passaram.
Não foi necessário alterar o fluxo de produção nem atribuir isso ao runtime.
A regressão de overworld foi reexecutada com draw_objects na fixture: 18
transições, 45 recortes exatos e seis capturas intermediárias exatas da parede
nas ligações da sala norte. As 16.524 sondas nativas e 192 buscas de borda
continuam aprovadas. O instalador da fixture agora usa marcador de instalação
para aceitar novos backups de produção e impedir restauração indevida.
Regeneração idempotente em 1.226 arquivos. Evidências em extracted/real_secret.
Próximo recorte da lista: loja; depois expansão de percurso com objetivo.
Build final dc681b23-7485-4a72-bcfc-7a29f3ac376b aprovado; diagnostics vazios em sete fontes consultadas.
Fixtures removidas/restauradas antes da compilação final; controle devolvido.
### ATR-19 Validação visual nativa e serviço local de automação do Studio
**P2 · Custo recorrente de produção observado; proposta do usuário em 09/11/2026. Não demonstra defeito do runtime.**
**Evidência:** o headless já fornece avanço por frames, captura, identidade da
sessão/build/frame e operações consultáveis. Essas capacidades permitiram
regressões precisas e devem ser preservadas. Entretanto, no fluxo utilizado,
a imagem chega como conteúdo base64 da ferramenta; o agente monta uma chamada
Python para decodificá-la e gravar um PNG, depois executa outros scripts para
recortar regiões, aplicar exclusões e comparar pixels com referências.
Exemplos: `tools/validate_real_secret_captures.py`,
`tools/validate_real_secret_scroll.py` e `tools/validate_overworld_captures.py`.
O último recorte usou oito comparações do segredo, seis de scroll e 45 do
regressor de overworld, com essa infraestrutura externa de imagens.
**Impacto:** repetição de código de transporte, gerenciamento de caminhos,
sequenciamento de captura e comparação; passagem de blobs grandes por chamadas
do agente; mais pontos de falha entre o frame observado e a evidência salva.
O custo aqui é automatizar o ensaio e manipular suas imagens. Isso não significa
que os testes em Python sejam desnecessários ou que o Studio tenha falhado ao
renderizar. Também não foi demonstrado que inexista uma API interna equivalente;
o que faltou no fluxo exposto/utilizado foi uma operação pronta para esse trabalho.
**Direção sugerida:** tratar a automação do Studio como um serviço de backend
local, com contrato público, acessível por HTTP sobre socket local e, se útil,
WebSocket para eventos de progresso/conclusão. HTTP atende comandos, consulta
de jobs e download de artefatos; WebSocket pode reduzir polling, mas não precisa
ser requisito inicial. As ferramentas do agente e a interface do Studio podem
ser clientes desse mesmo serviço. O protocolo sozinho não resolve o atrito:
a capacidade de capturar, comparar e publicar evidências precisa existir nele.
Um primeiro recorte útil seria:
- Avançar até um checkpoint e capturar o frame na mesma operação, vinculando
explicitamente projeto, task, sessão, build e índice lógico do frame.
- Gravar a captura no armazenamento de artefatos do Studio e devolver um
identificador, hash e referência para leitura/download. Servir PNG binário
por HTTP, ou um handle equivalente na ferramenta, evitando obrigar o agente
a transportar e decodificar base64. Base64 pode continuar como alternativa.
- Comparar captura e referência por identificador de artefato ou referência
de arquivo autorizada, com recorte/ROI, máscaras de exclusão e política
explícita para cores/alpha e tolerância. Comparação exata deve estar disponível.
- Retornar resultado estruturado: aprovado/reprovado, dimensões, pixels
comparados/diferentes, erro máximo e caixa das diferenças; publicar imagens
atual, esperada e diff/overlay como artefatos inspecionáveis.
- Executar uma sequência de inputs/checkpoints e gerar relatório por lote,
preservando o transcript para reprodução. Não aprovar baselines novas
automaticamente: atualizá-las deve ser uma ação explícita e revisável.
**Contrato a preservar:** IDs de requisição para recuperar respostas sem repetir
avanços, status consultável, término real do worker em cancelamentos, validade
ou obsolescência da captura e associação exata do resultado ao build/frame.
Reutilizar o controle por projeto/task e a autorização do Studio existentes;
o serviço não deve contornar esses limites nem usar o cartão do usuário como
mídia implícita de teste. As URLs/handles de artefato precisam ter escopo de
acesso e ciclo de vida definidos. Esta é uma proposta de arquitetura, não uma
API que já existe nem uma conclusão de que HTTP seja obrigatório.
**Separação importante:** o Studio pode assumir execução, captura, comparação
genérica e apresentação de resultados. Os oráculos específicos deste port —
extração de assets, interpretação das tabelas e execução delimitada de rotinas
6502 da ROM — continuam externos ou fornecem referências ao serviço. Não embutir
conhecimento de Zelda no runtime nem substituir uma referência independente
pelo mesmo algoritmo que está sendo testado.
**Critério de sucesso proposto:** reproduzir uma comparação de tela, uma ROI de
HUD e um checkpoint no meio do scroll usando somente operações do serviço,
sem script de decodificação base64 ou montagem de diff. O agente receberia um
resumo pequeno e abriria as imagens apenas quando necessário. Um comando de
lote deveria produzir as mesmas evidências verificáveis atualmente mantidas em
`extracted/real_secret`, incluindo falhas e diferenças, com menos infraestrutura
específica no projeto.
## Evidência adicional — loja $66 (09/11/2026)
**Positivo observado:** terreno fixo compartilhado e objetos/texto em sprites
permitiram vendedor piscante, remoção individual de produto, preços persistentes
e rolagem do inventário sem variantes de scene nem novos slots. Foram aprovadas
13 comparações exatas de composição/poses. O save existente preservou uma compra
com débito ainda pendente; reabertura do cartão de teste liquidou a fila sem
alteração de formato. Referências do Studio bastaram para PBS; não foi necessário
consultar Java neste recorte.
**Custo observado:** as capturas e comparações ainda exigiram decodificação local
de base64 e script específico para ROI/exclusões. Consolida a evidência da
proposta ATR-19 acima: comparação estruturada de artefatos no Studio reduziria
essa infraestrutura. Não é defeito visual observado nem confirmação de causa
no runtime. O oráculo das regras e descritores nativos continua externo.
## Evidências do percurso oeste e segunda loja — 09/11/2026
**Positivo / ATR-11:** um struct público `ShopVisit`, importado com construtor
explícito, compartilhou as regras das duas lojas. A loja anterior passou
novamente nos 150 casos; a nova passou em 400 casos, com compra/saída/revisita
via Game.frame. Isso reforça que o erro histórico com Scene não demonstra
inviabilidade geral de structs entre módulos. Sem consulta a Java neste recorte.
**Positivo / ATR-15:** quatro mapas e mais um interior foram integrados sem
novos slots de scene. Inventário passou de 12 para 16 faixas no mesmo banco.
69 comparações do overworld e 12 da loja foram exatas. Terreno fixo, produtos,
texto e vendedor separados dispensaram variantes de scene durante compra.
A regeneração completa preservou os hashes dos fontes/assets conferidos.
**Produção / ATR-08:** o gerador do port deixou buracos 28/29 no HUD ao derivar
índices de IDs de stages que incluem interiores. Pack recusou corretamente
com `Tile bank artifacts must form a contiguous index range starting at 0.`
O gerador foi corrigido, mantendo os índices antigos. Não é defeito do runtime.
No resultado consultado, o texto identificava a classe de asset, sem caminho
explícito do banco; incluir caminho e índices ausentes reduziria a busca manual.
**Produção / ATR-02–03:** a fixture usou `tick<150 && !verify_old(tick)` e
alcançou OldShopOracle.get fora da tabela no tick 150. O runtime forneceu
Bounds, função e span; a guarda foi substituída por if aninhado e toda a
sequência passou. A referência dinâmica consultada descreve avaliação estrita
da esquerda para a direita e ramo de if não selecionado sem execução, mas não
foi localizada nela uma garantia de curto-circuito para &&. Não atribuir causa
a lowering/runtime sem reprodução mínima e contrato explícito. Exemplo de
guarda com chamada e documentação da avaliação booleana evitaria a suposição.
A falha era do harness temporário, não de gameplay nem da interface visual.
**ATR-19:** as 81 comparações exatas deste recorte ainda exigiram captura em
base64, decodificação e comparação local. Mantém-se a proposta de artefatos,
ROI/máscaras e relatório estruturado no Studio; oráculos 6502 continuam externos.
### ATR-20 Watchdog no primeiro advance após reabrir cartão, sem guest fault
**P2 · Uma ocorrência observada; causa e reprodução mínima não confirmadas.**
No build de fixture `49b8a4a0-fe91-4ded-8d64-131420672e2a`, abrir cartão existente
retornou sucesso. O primeiro advance de um frame terminou em
`INFRASTRUCTURE_FAILURE`, `watchdog_expired`, limite 100000 host ticks e zero
frames concluídos. get_state mostrou lógico0, tick3, PC233, paused; get_fault
retornou null e memcard estava resident/running, sem ação requerida.
Após consultar os estados, um novo advance com ID distinto completou exatamente
um frame; os 299 seguintes passaram, com load e débito corretos. Não houve
reexecução cega de um lote já avançado, alteração do payload ou guest trap.
Evidência em `extracted/supply_shop/save-validation.json`. Não concluir que o
save do jogo esteja defeituoso nem que seja o mesmo caso histórico de reset.
Impacto: foi necessário reconciliar manualmente progresso e estado de boot.
Sugestão: incluir fase/bloqueio atual do firmware no diagnóstico do watchdog e
indicar se a sessão pode continuar. Investigar primeiro um caso mínimo de boot
com mídia existente; manter zero frames concluídos explicitamente no resultado.
**ATR-11 / LSP no fechamento deste recorte:** diagnostics retornou
INFRASTRUCTURE_FAILURE em fontes novas e existentes, embora o build final
passasse. ShopVisit falhou na primeira consulta e respondeu vazio na seguinte;
CaveSupplyShop falhou duas vezes; Link e Overworld também falharam. StageFlow
e Stage responderam vazios. Não há evidência suficiente para atribuir a causa
a criação de arquivos novos. Impacto: verificação LSP parcial, mantida como
limitação explícita. O build/pack e os testes runtime forneceram a validação
executável; seria útil preservar o erro interno no resultado da consulta.
+95
View File
@@ -0,0 +1,95 @@
# Segredo bombável real da sala $67
A sala imediatamente ao norte do início contém o tile object $E6 em
**X=$70 (112), Y=$50 (80)**. Atributos B/F da ROM apontam para a caverna
**$7B**, índice 17: Moblin, mensagem “IT'S A SECRET TO EVERYBODY.” e prêmio
central de **30 rupias**. O segredo aplica-se à primeira quest.
## Como usar no jogo
1. Obter bombas pelos drops já disponíveis; não há pacote de teste no início.
2. Na sala norte $67, colocar a bomba junto à parede central superior.
3. Após a explosão, caminhar pela passagem em X=112, Y=77.
4. Dentro da caverna, tocar a rupia em X=120, Y=152 para receber 30 rupias.
5. Sair pela abertura inferior. Link volta à passagem da sala norte.
O Moblin, a mensagem e a rupia continuam visíveis após o prêmio durante aquela
visita, com o número 30 exibido; o estado seguinte não concede novamente.
Na visita seguinte, o interior mostra somente os fogos. A abertura e a coleta
são persistentes, inclusive ao salvar/carregar. A mensagem é exibida inteira,
como na caverna inicial; revelação progressiva de diálogo continua pendente.
## Organização
- `src/stages/overworld_north`: dono da parede, cobertura, colisão e entrada.
- `src/stages/cave_secret`: stage interna 10, terreno/colisão próprios e
composição do Moblin, texto, prêmio e recibo. Reutiliza a scene de terreno 1.
- `src/stage/flow.pbs`: transições e retorno; `cave_origin/cave_x` preservam
a procedência, mantendo o comportamento anterior da caverna da espada.
- `src/inventory`: crédito de 30 na fila nativa RupeesToAdd/Items[$26].
- `src/world`: abertura no bit $80 e prêmio no bit $10 do byte da sala $67;
os três bits de mortes permanecem independentes.
A scene base e os atlas de rolagem/inventário contêm a passagem revelada.
Enquanto a flag estiver fechada, quatro glyphs opacos de pedra cobrem essa
área. Render, sondas e entrada consultam o mesmo estado. A cobertura acompanha
os offsets das quatro direções de scroll e do inventário. Não há troca de
scene para detonar ou coletar.
O contato da bomba é estritamente menor que $10 nos dois eixos. O objeto está
em Y=80; a entrada de Link é Y=77. Não confundir essas coordenadas nem usar
o raio de dano $18 para abrir a parede. O primeiro slot de bomba detonando
continua sendo escolhido pelo fluxo existente de Link.
Ao revelar, a ROM escreve quatro tiles $24. Ao reconstruir a sala com a flag
persistente, usa o metatile secundário $0C: $F3/$24 em cada coluna. Os dois
patterns são visualmente pretos, mas os IDs de colisão diferem. `wall_fresh`
preserva essa diferença transitória; é limpo ao sair/resetar a visita.
As máscaras de prioridade da porta inicial foram reutilizadas somente após
conferir os 4.352 pixels de suporte das 17 posições de entrada/saída contra
o cenário real da passagem: nenhum pixel difere. Não reutilizar essa máscara
em outras entradas por mera semelhança visual.
A caverna interna usa a identidade nativa da sala $67 para HUD e save, sem
inserir um falso registro no histórico de inimigos. Stages 1 e 10 são interiores
para a API is_cave. Não foram acrescentados slots de scene; mantêm-se 0..15.
## Assets e regeneração
`tools/prepare_real_secret.py` extrai atributos, tipo de caverna, wares,
preços, seletor/bytes de texto e descritor do Moblin. Ele acrescenta sprites
no banco de caverna 3, preservando os glyphs anteriores. O Moblin usa a
sobrescrita nativa de ObjAttr=$81 feita por SetUpCommonCaveObjects; usar uma
entrada arbitrária da tabela de monstros pode produzir apenas metade do NPC.
`tools/prepare_cave.py` termina com prepare_real_secret. Depois executar
`tools/prepare_overworld.py` para recompor terreno, cobertura e inventário.
O catálogo continua com nove salas OW; a nova stage 10 é um interior.
Os testes temporários da bomba e da parede sobre a espada permanecem false.
## Verificações
- `tools/validate_real_secret_rom.py [caminho-do-cartao-de-teste]`: metadados,
máscara, 121 contatos de bomba contra a rotina 6502 e, opcionalmente,
payload/checksum do cartão descartável.
- `tools/generate_real_secret_fixture.py install/restore`: teste isolado de
bomba real, fusível, consumo, abertura, descida, caminhada, menu, coleta,
crédito, saída, bloqueio de reentrada imediata, revisita e save.
- `tools/validate_real_secret_captures.py`: oito recortes comparados a pixels
nativos, commit durável e releitura. Regiões de Link/efeitos vivos são
explicitamente excluídas das comparações de terreno.
Foi usado somente um cartão descartável em `.tmp`; nunca o cartão do usuário.
O payload reaberto preservou 3 bombas, 30 rupias e byte $91 da sala $67
(abertura + prêmio + uma morte registrada). Formato v1/app_id inalterados.
No build normal também foram percorridas a caverna da espada (entrada,
coleta/pose e saída) e, após carregar o cartão de teste em modo somente leitura,
a passagem da sala norte até a caverna já coletada, usando inputs normais.
Relatórios e capturas ficam em `extracted/real_secret`.
Também foram reexecutadas as 18 transições do overworld, 45 comparações de
mapa/HUD/inventário e seis comparações adicionais no meio das rolagens
conectadas à sala norte. Todas exatas; as sondas nativas das nove salas
continuam aprovadas. A fixture de overworld emite draw_objects, como o jogo.
+58
View File
@@ -0,0 +1,58 @@
# Save no memcard
Implementação inicial: **um perfil**, preservando inventário e progresso das
salas do overworld. O menu foi ampliado para Continue / Save / Retry.
## Como usar
1. No Studio/runtime, escolha um memcard em modo **persistente**, com escrita.
A imagem padrão do projeto é `.studio/memcard.pmc`, fora de `build/`.
2. Na abertura, Z (Start) leva a Continue / New Game. Shift (Select) muda a
opção; Z confirma. Sem save válido, escolha New Game.
3. Durante a partida, Shift abre o menu Continue / Save / Retry. Shift muda a
opção e Z confirma. Continue retoma a mesma posição e vida.
4. Escolha Save e aguarde **GAME SAVED**. Z volta à abertura. Ao abrir o jogo
novamente com o mesmo cartão, escolha Continue.
No menu após a morte, Continue mantém seu comportamento anterior: retorno ao
início com três corações. Save também está disponível ali. Z continua abrindo
normalmente o inventário durante a partida; D usa o item B.
Sem armazenamento persistente, o jogo pode funcionar no modo de memória do
runtime, mas mostra **MEMORY ONLY / NOT SAVED TO CARD** ao tentar salvar. Não
confundir essa mensagem com GAME SAVED. Cartão apenas para leitura é gerido
pelo host: carregar em memória pode ser permitido, mas gravar é bloqueado.
New Game reinicia a sessão sem apagar imediatamente o save existente. Somente
escolher Save substitui o único perfil. Dados inválidos ou de versão não
suportada são mantidos no cartão e não são aplicados ao jogo.
## Progresso preservado
O slot guarda os 40 bytes de Items e os 128 bytes de flags OW já modelados.
Espada, equipamentos, bombas, rupias, chaves, capacidade de vida, coletas e
segredos são restaurados. As contagens de mortes já registradas nas flags
seguem a ROM; o histórico de seis salas é reconstruído, sem persistência.
Carregar começa no ponto inicial com três corações preenchidos, limitado pela
capacidade. O relógio temporário é limpo (Items[$15]); posição de Link,
inimigos, projéteis, drops, animações e timers não são salvos.
Perfil com nome, contador de mortes, segunda quest e bancos de flags de
dungeons serão acrescentados quando esses sistemas forem portados. O formato
v1 já tem identificação, tamanho, versão e checksum; detalhes e evidências em
[FORMAT](../extracted/save/FORMAT.md) e `extracted/save/validation`.
## Organização e regeneração
- `src/save`: codec, cache validado, metadados do memcard e commit assíncrono.
- `src/screens/save`: seleção do perfil e mensagens de gravação.
- `src/game`: decisões de abrir menu, salvar, carregar e retomar a partida.
- `tools/prepare_save_ui.py`: fonte NES e ícone de Link; usa o banco existente.
Também é executado após `prepare_game_screens.py` para preservar o menu
dinâmico. Não foram acrescentados slots de scene.
O `app_id` 2137977836 é a identidade persistente e não deve mudar em upgrades.
A versão do projeto e a versão do payload são independentes. O host/runtime
controla criação, montagem, recuperação e decisões sobre alterações pendentes;
o jogo não escreve arquivos diretamente nem salva implicitamente ao sair.
+74
View File
@@ -0,0 +1,74 @@
# Composição de stages e objetos mutáveis
O port preserva os pixels, as coordenadas, o tempo e as regras de gameplay da
ROM. A organização gráfica deve aproveitar o Prometeu: uma scene com terreno
fixo e sprites/glyphs independentes para elementos com estado.
- Terreno: chão, paredes permanentes e decoração que nunca muda.
- Objetos: NPCs, itens coletáveis, fogo e efeitos desenhados pela stage.
- Texto: glyphs separados, com conteúdo/visibilidade próprios.
- Estado: inventário, flags do mundo e timers de gameplay; nunca a scene ativa.
A caverna inicial exemplifica o padrão em `src/stages/cave_start`: `CaveData`
fornece colisão; `CavePickup` controla coleta e desaparecimento; `CaveArt`
desenha os elementos sobre a scene 1. Piscar o velho não altera a chave visual
da stage nem chama bind_scene. A aparência continua sendo a extraída da ROM.
Os glyphs anteriores e os IDs dos assets foram preservados. Slots legados de
scene 2/3 ficam reservados para manter os IDs das demais scenes; não são
selecionados para representar os estados da caverna.
A stage desenha os objetos em coordenadas NES, camada 1, abaixo de Link e do
HUD (camada 2). O inventário aplica o mesmo deslocamento vertical aos objetos
e ao terreno congelado. Timers permanecem pausados durante o submenu.
As faixas de inventário carregam somente terreno; não embutir NPCs ou itens.
## Paredes bombáveis
Desenhar no terreno base a passagem revelada. Enquanto a flag indicar parede
fechada, desenhar uma cobertura de glyphs opacos nos tiles mutáveis. Uma
cobertura pode usar sprites opacos: transparência só é necessária onde deve
aparecer o que está atrás. Não produzir uma scene inteira por parede/estado.
`BombableWall` mantém o estado em WorldFlags (bit $80). A mesma flag controla:
- emissão ou remoção da cobertura;
- substituição dos tiles de colisão;
- disponibilidade da entrada.
A detonação muda essa flag; o próximo frame recompõe a área. O save já persiste
a flag. Distância nativa da abertura continua estritamente menor que $10 nos
dois eixos, distinta do raio de dano $18. A stage é responsável por aplicar
os offsets corretos durante rolagens e inventário; sprites não acompanham a
câmera de terreno automaticamente.
A cobertura existente em `overworld_start` já segue esse padrão. Os testes
temporários da bomba e da parede na entrada da espada continuam desativados.
Usar esse exemplo ao adicionar paredes reais nas próximas salas.
## Regressão da caverna
`tools/generate_cave_composition_fixture.py install` instala a entrada
isolada; executar os dez frames de cases.json pelo headless e capturar cada
checkpoint. `tools/validate_cave_composition.py` compara os estados e o
inventário aos compostos de referência e executa as sondas nativas.
Restaurar com `tools/generate_cave_composition_fixture.py restore` e recompilar
antes de devolver o projeto. Evidências ficam em
`extracted/cave/start/composition-validation`; a entrada final usa Game.frame.
O segredo real da sala $67 aplica esse padrão, incluindo a cobertura durante
rolagens e submenu, interior com NPC/texto/rupia separados e save das flags.
Detalhes e verificações em [real-secret.md](real-secret.md).
## Aplicação na loja $66
`cave_shop` compartilha terreno da scene 1 e emite vendedor, texto, produtos e
preços como sprites. A compra muda visibilidade por visita sem rebind de scene;
os preços permanecem. Todos recebem offset de inventário. Glyphs anteriores
preservados, nenhum slot adicional. Ver [shop.md](shop.md).
## Segunda loja e percurso oeste
A loja da $44 também usa a scene 1, com arte mutável própria e ShopVisit
compartilhado. Nenhuma variante de scene foi criada para comprar ou piscar.
O inventário passou a 16 faixas dentro do slot 15. Stage ID 16 é um ID de
conteúdo e não um slot de scene. Ver [west-route.md](west-route.md).
+70
View File
@@ -0,0 +1,70 @@
# Loja nativa da $66
A entrada aberta da sala $66 (stage 3) leva à stage 11 `cave_shop` e retorna
à mesma sala. Tipo de caverna $78, índice 14. Coordenadas da entrada: (112,77).
Dados rastreáveis em `extracted/shop/rom-data.json`; gerador `tools/prepare_shop.py`.
| Produto | ID | Slot Items | Preço | Regra de aquisição |
|---|---|---|---|---|
| Escudo mágico | 28 | $1F | 160 | Classe 0: atribui 1, inclusive se já possuído. |
| Chave | 25 | $17 | 100 | Classe 1: soma até 255. No limite, a compra ainda custa rupias. |
| Vela azul | 6 | $04 | 60 | Classe 2: máximo entre grau atual e 1; não rebaixa vela vermelha. |
Contato com x=88/120/152 e distância vertical estrita menor que 6 em relação
a y=152. Saldo atual deve cobrir o preço; créditos futuros não contam. Um
débito pendente em Items[$27] impede outra compra. O débito é enfileirado,
não subtraído instantaneamente. Inventário concentra a transação; a stage
cuida de contato, estoque e composição. Link recebe o ID adquirido e ergue
o produto por 128 ticks, alinhado à esquerda como os itens estreitos nativos.
O bit $10 de OW[$66] é gravado preservando mortes, mas não esgota estoque
em visitas futuras. Uma compra por visita. Produto escolhido e mensagem somem;
vendedor e produtos restantes piscam por 64 ticks e desaparecem. Preços ficam.
A nova entrada reinicia a composição independentemente da flag persistente.
Terreno fixo compartilhado na scene 1; objetos/texto em sprites. Glyphs
103–137 acrescentados ao banco da caverna, mantendo IDs anteriores. Entrada,
colisão e dados ficam no módulo próprio; transições ficam em `src/stage`.
`prepare_cave.py` chama `prepare_real_secret.py`, que chama `prepare_shop.py`;
terminar regeneração com `prepare_overworld.py` para recompor o inventário.
## Evidências e limites
`validate_shop_rom.py`: 150 combinações de produto, posse prévia, saldo e débito.
Executa TakeItem/PostDebit da ROM; guardas de contato/saldo são comparadas às
regras extraídas, sem alegar emulação integral da loja. Resultado em
`extracted/shop/native-cases.json`.
`generate_shop_fixture.py install/restore`: entrada/saída real via Link/Stage,
compra, revisita, menu, três poses e save durável. Restaurar antes de entregar.
`validate_shop_captures.py`: 13 comparações exatas com CHR/descritores nativos,
incluindo poses dos três itens; exclui fogo animado, Link nas comparações do
cenário e rupia de preço piscante. A pose é comparada separadamente.
Cartão de teste isolado `.tmp/shop-fixture-21c39996.pmc`: salva os três produtos
e uma compra de vela com saldo 60/débito 60; após reabrir, asserta esse estado
e liquidação para 0/0. Sem mudar formato v1 nem cartão do usuário.
Uso da vela para fogo/árvores e portas de dungeon para chaves continuam
pendentes. Escudo mágico já participa da defesa contra Zora. Texto progressivo,
outras lojas e variantes de diálogos continuam pendentes.
A tentativa de caminhada longa do smoke de produção terminou em morte antes
da entrada: a instrumentação temporária confirmou stage 3 / modo 17. A tela
preta observada era a apresentação de morte, não falha confirmada de bind.
A fixture de compra e save não altera o cartão de uso normal.
Integração adicional: inicialização isolada na porta da $66, seguida por
`Game.frame` completo, confirmou entrada e render da loja (102 frames),
sem simular o desenho diretamente. O submenu foi aberto pelo input Start.
A fixture principal cobre fechamento com offset parcial, compra e saída;
a tentativa adicional de fechar antes do fim da abertura foi ignorada, como
previsto pela fase do submenu. Esses testes não concedem itens na produção.
## Reuso no percurso oeste
A lógica de visita/transação foi extraída para `src/shop/ShopVisit`; os 150
casos da loja $66 foram reexecutados no guest. A stage continua responsável por
seus próprios dados, produtos e composição. A loja nova da $44 tem preços
próprios; não globalizar o preço do escudo. Ver [west-route.md](west-route.md).
O gerador agora acrescenta ambas as lojas preservando os glyphs antigos.
+79
View File
@@ -0,0 +1,79 @@
# Percurso oeste e loja de bombas
Recorte concluído em 09/11/2026: quatro telas nativas e uma loja. O caminho
$58 → $57 → $56 → $55 → $54 → $44 termina numa fonte de bombas compráveis,
sem sorteio de drops. Há atalhos nativos $65 ↔ $55 e $64 ↔ $54.
| Stage | Sala NES | Módulo | Encontro |
|---|---|---|---|
| 12 | $56 | `overworld_west_1` | Quatro Octoroks $07 + Zora |
| 13 | $55 | `overworld_west_2` | Um Octorok $07 + Zora |
| 14 | $54 | `overworld_west_3` | Quatro Octoroks $08/$07 + Zora |
| 15 | $44 | `overworld_shop_west` | Quatro Octoroks $07; entrada aberta (64,77) |
| 16 | Interior ligado a $44 | `cave_supply_shop` | Loja $77, índice 13 |
IDs de stage são independentes dos slots de scene. A stage 16 usa a scene 1;
não foi criado um slot de scene 16. O catálogo passou a 13 salas OW, 15 ligações
reversíveis e quatro interiores. HUD, colisões, listas, flags de Zora e câmera
continuam derivados dos atributos da ROM. As salas novas não usam edge spawn.
## Compras e progressão
| Produto | ID | Slot Items | Preço |
|---|---|---|---|
| Escudo mágico | 28 | $1F | 130 |
| Pacote de quatro bombas | 0 | $01 | 20 |
| Flechas | 8 | $02 | 80 |
Comprar bombas soma quatro e limita em MaxBombs, inclusive com mochila cheia:
a ROM ainda cobra o preço. Comprar flechas preserva um grau superior já possuído.
Comprar escudo atribui 1 ao slot. Há uma compra por visita; sair e entrar repõe
os produtos. OW[$44] recebe o bit $10 sem apagar mortes; esse bit não esgota loja.
Saldo atual e pendência em Items[$27] seguem o contrato da loja anterior.
`src/shop/ShopVisit` compartilha transação, escolha e desaparecimento; cada
interior mantém seu módulo, terreno/collision data e produtos/preços próprios.
`tools/prepare_shop.py` lê os dois estoques, textos e paletas de item da ROM.
Os glyphs antigos permanecem 0–137; a loja nova acrescenta 138–171.
Item 0 tem uma particularidade: TakeItem escreve ItemTypeToLift=0 e
CheckLiftItem retorna sem erguer. Portanto comprar bombas mantém a pose normal.
Escudo e flechas usam a pose estreita de uma mão e 128 ticks. Isso foi conferido
com descritores/CHR e capturas. As flechas são propriedade do inventário;
o uso de arco/flechas ainda está pendente e a seleção B exige o arco.
Scenes de terreno/transição/inventário continuam 13/14/15. O inventário cresceu
para 16 faixas de 416 pixels, com a caverna compartilhada na variante 1.
Marcadores novos foram acrescentados de forma contígua, preservando IDs anteriores.
## Evidências
- `extracted/overworld/expansion`: 23.868 sondas nativas, 384 buscas de borda,
116 checkpoints verdes, 30 transições direcionadas e 69 comparações exatas
de cenário, marcador, inventário e destinos.
- `extracted/supply_shop`: 400 combinações nativas de compra, 150 casos da loja
anterior executados novamente, 12 comparações exatas de composição/poses,
entrada/saída real via Game.frame, menu aberto e fechado, compra única,
débito pendente, reposição e duas compras de bombas (4 → 8).
- Save durável em `.tmp/supply-shop-97ae4684.pmc`: bombas 8, flechas 1, escudo 1,
flag OW[$44]=$11 e saldo/débito 130/130 no payload v1 de 180 bytes, checksum
válido. Reabertura de 300 frames confirmou posse, reposição e liquidação 0/0.
O cartão do usuário não foi alterado.
- `regeneration.json`: prepare_cave + prepare_overworld não alteraram os hashes
dos arquivos conferidos. Fixtures são restauradas antes do build de produção.
O primeiro advance após reabrir o cartão retornou watchdog de infraestrutura
com zero frames concluídos e sem guest fault. Estado consultado; um novo advance
completou o primeiro frame e os 299 seguintes passaram. A causa permanece não
confirmada; isso não é contado como um primeiro advance aprovado.
Uma guarda com chamada no RHS de `&&` na fixture alcançou OldShopOracle.get
fora da tabela no tick 150. Foi substituída por if aninhado e toda a sequência
reexecutada. Não é falha observada de gameplay do port.
## Limites
Segredo/árvore da $56, demais entradas secundárias, uso de vela, arco/flechas e
novas famílias de inimigos ficam para outros recortes. Nenhum conteúdo nativo
foi substituído por item inicial gratuito. Testes temporários da bomba inicial
e da parede da espada continuam desligados. Save v1 e app_id preservados.
+61
View File
@@ -0,0 +1,61 @@
# Primeiro encontro com Zora
`src/enemies/zora` contém o ator $11 e a bola de fogo $55. A presença vem do
atributo A, bit $08, no catálogo `src/overworld`; a sala $65 é a única tela
atualmente portada com essa flag. Não acrescentar Zora à lista de Octoroks.
## Regras implementadas
- Candidatos de posição vêm dos bytes nativos de random: X alinhado a $10,
Y no formato $xD e tile bruto de água no intervalo $8D..$98. O byte $25
adjacente ao array Random, lido pela rotina original, é tratado explicitamente
como zero; não acessar índice 13 no array de 13 elementos.
- Estados 1..5 usam timers $20/$0F/$FF/$10/$60. Em estado 3, o tiro sai em $FD
e o timer passa a $20. Estados 1 e 5 são montículos invulneráveis; 2/3/4
expõem o ator. Frente/costas são decididas pela posição vertical de Link.
- HP equivalente a dois golpes da espada de madeira; espada, beam e bomba
consultam as APIs existentes de Link. Dano fatal produz efeito e drop
pelo grupo nativo, sem incrementar as mortes persistentes da sala.
- Submergir naturalmente permite outro surgimento. Morrer bloqueia novo Zora
nessa visita; sair e voltar reinicia o encontro. Não salvar estado transitório
do ator ou de suas bolas de fogo no memcard.
- Relógio mágico interrompe a rotina do ator; o timer geral continua a cair.
O menu pausa gameplay pela máquina GameFlow existente.
- Bola de fogo mira na posição de Link ao inicializar, usa a tabela nativa de
nove ângulos, atraso de $10 e movimento fracionário; atravessa terreno e
termina nos limites de objetos OW ($11/$E0/$4E/$CD). O dano base é meio coração.
- Escudo comum não bloqueia o tipo $55; escudo mágico em Items[$1F], com Link
idle e direção oposta, bloqueia. Tipos de tiro futuros não devem assumir
automaticamente essa mesma regra.
O encontro usa o fluxo `Enemies.update/draw`, preservando os cinco atores
existentes. Contagem de ocupação inclui atores, drops e pedras; Zora e bolas
respeitam o teto nativo de onze slots. Há seis instâncias de Fireball, suficientes
para o encontro atual; não é ainda um alocador genérico de todos os objetos NES.
## Assets e regeneração
`tools/prepare_zora.py` executa os descritores originais de Zora/fireball,
aplica os flips e acrescenta glyphs 12..18 ao banco de atores 11. Não cria
scene nem altera índices anteriores. O entrypoint de prepare_north recompõe
esse banco ao terminar. Após mudanças nas salas, usar prepare_overworld.py.
As letras, NPCs, itens e terreno continuam seguindo
[scene-composition.md](scene-composition.md). Zora é um ator sobre a scene.
## Evidências e limites
- `tools/validate_zora_rom.py`: execução 6502 delimitada de UpdateZora e
_CalcDiagonalSpeedIndex. Dois ciclos, 388 ticks, e 1.369 pares de distâncias.
Colisão/desenho/tiro externos são substituídos explicitamente por observadores;
não se trata de emulação integral do NES.
- `tools/generate_zora_fixture.py install/restore`: fixture temporária com
comparações no guest dos ciclos e verificações de água, lotação, dano,
submersão, morte/revisita, relógio e escudos. Restaurar antes da entrega.
- `tools/validate_zora_captures.py`: sete comparações de assets e doze de
composição runtime com pixels dos descritores nativos.
- Dados, capturas e resultados em `extracted/zora`.
A equivalência integral do alocador de slots, de toda ordem de atualização e
interações com armas ainda não portadas não é alegada. Não ampliar a implementação
com regras presumidas para outras famílias de inimigos.