967 lines
59 KiB
Markdown
967 lines
59 KiB
Markdown
# 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.
|