chore: version Zelda 1 port and engineering records
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user