Files

15 KiB
Raw Permalink Blame History

Link NES no Studio

No painel Assets, selecione o banco Link NES (characters/link). O banco tem especialização sprites, frames 16×16 com transparência e paleta 0. São 16 frames de corpo e quatro imagens direcionais da espada de madeira. Na área de animações, selecione o animator link e um dos clipes:

Ação Clipes Reprodução
Parado idle_down, idle_up, idle_left, idle_right Um frame
Caminhada walk_down, walk_up, walk_left, walk_right Dois frames, 6 ticks por frame, loop
Pose de ataque attack_down, attack_up, attack_left, attack_right Dois frames, 6 ticks por frame, uma vez

Os 20 PNGs e a definição persistida animations.studio.json estão em assets/characters/link/. Os clipes idle reutilizam os frames de caminhada. Os dois frames de ataque horizontal têm a mesma imagem porque a tabela original repete o descritor. Os clipes de ataque são uma apresentação das poses do corpo, não uma reconstrução completa da sequência de combate; a espada é outro objeto. A duração de 6 ticks reproduz a cadência da caminhada; sua aplicação às poses de ataque serve ao preview e ainda não especifica a lógica final de combate.

Montagem

tools/assemble_link.py lê a ROM verificada e monta as duas colunas NES 8×16. Usa os descritores originais de animação, aplica os espelhamentos de direção e reproduz a substituição do escudo básico nos frames voltados para baixo, incluindo a correção de espelhamento da coluna do escudo. Não há redesenho de pixels.

Os códigos de paleta são extraídos do registro do mundo externo: $0F, $29, $27, $17. O índice zero fica transparente. Os valores RGB são uma aproximação explícita para visualização digital; os códigos NES são a referência. Como explica a documentação de paletas do NES, a conversão para RGB depende da representação escolhida.

provenance.json registra offsets e transformações por frame. preview.png mostra os 16 frames ampliados. animation-proposal.json contém a proposta usada para salvar os clipes pela API do Studio. A definição oficial é assets/characters/link/animations.studio.json.

Esta primeira montagem cobre a túnica verde, o escudo básico e a espada de madeira. Ainda não cobre o escudo mágico, outras túnicas, poses de levantar itens, morte ou outras armas. O jogo agora desenha e controla Link pelos direcionais; veja a seção de movimento abaixo.

Reproduzir e validar

python3 tools/assemble_link.py

O script regenera os PNGs e o manifesto do banco, preserva seu UUID e registra o banco no índice de assets se necessário. Não sobrescreve a definição de animações salva pelo Studio: ele gera apenas a proposta fora de assets. Depois de edições manuais dos PNGs ou do manifesto, regenerar substitui esses arquivos gerados e pode exigir rebind explícito das animações no Studio.

Validação realizada: reconhecimento dos 16 bindings pelo Studio; save da definição sem diagnósticos; preview dos 12 clipes; caminhada no segundo frame no tick 6; ataque encerrado no tick 12; diagnostics PBS vazios; build e pack concluídos sem diagnósticos.

Referência das rotinas: DrawObjectWithAnim, ObjAnimFrameHeap e Anim_WriteHorizontallyFlippableSpritePair em Z_01.asm, e SetUpWalkingSprites / Link_EndMoveAndAnimate em Z_07.asm.

Movimento no jogo

Dê Play e use os direcionais configurados no Studio. Link anda em quatro direções, muda a orientação do sprite e para mantendo o frame e a direção atuais. Não há movimento diagonal. O cenário atual é a primeira tela do overworld, com colisões de terreno, bordas externas fechadas e entrada da caverna conectada. Ver stage inicial.

Regras portadas das rotinas do NES:

  • Coordenadas lógicas 256×240, exibidas em escala 1:1 no centro da saída 480×270 do Prometeu. O topo de 64 pixels exibe o HUD estático compartilhado.
  • QSpeed=$60, quatro aplicações por tick e acumulador de posição de 8 bits, compartilhado entre os eixos. Inclui o comportamento diferente de carry e borrow e a limitação por célula, em vez de arredondar a velocidade.
  • Grade de 8 pixels e regras do overworld para selecionar direções: curva em ponto da grade, inversão imediata, retorno ao ponto mais próximo quando aplicável e prioridade dos bits nas combinações de entrada.
  • Animação com contador de entrada de 4 ticks, depois alternância a cada 6 ticks com entrada direcional. A fase persiste ao soltar o controle e virar.
  • Deslocamento vertical do overworld de 2 pixels e convenção OAM de mais uma linha ao converter a coordenada NES para o topo do PNG.

Fontes: InitLinkSpeed, Link_ModifyDirAtGridPoint e Link_ModifyDirOnGridLine em Z_05.asm; MoveObject, PlayerScreenEdgeBounds, Walker_Move, AnimateLinkBase e RollOverAnimCounter em Z_07.asm; acumuladores de fração em Z_01.asm.

As bordas originais (X=0..240, ObjY=61..221) disparam transições na ROM. As bordas do overworld continuam fechadas. Há colisão de terreno e conexão com a caverna inicial, cuja abertura inferior permite retornar ao overworld. Combate, escadas lentas e portas de dungeons ainda não estão implementados. Não houve uma comparação de toda a execução contra um emulador NES; a referência combina análise das rotinas, sondas 6502 e capturas do port.

A cena vazia de teste em assets/scenes/movement foi preservada, mas excluída do build. O jogo agora usa assets/scenes/overworld_start, cujo terreno é extraído da sala inicial da ROM. Veja a documentação da sala. O compositor limpa o fundo antes de desenhar terreno e sprites, sem rastros.

Definições editadas no Studio

O arquivo src/link/graphics.generated.pbs deriva os glyph IDs dos clipes salvos no Studio e os offsets de arma da ROM:

python3 tools/sync_link_animation.py

Execute após alterar/reordenar os frames no Studio. O script verifica UUID, glyph IDs, fingerprints e a cadência de dois frames de 6 ticks, rejeitando drift. O relógio original do NES controla a fase compartilhada; não é reiniciado ao selecionar outra direção. Não existe alocação de Animator por frame. O gerador substitui somente esse arquivo gerado; não edita o ciclo do jogo nem os demais arquivos PBS. Executá-lo novamente com as mesmas entradas é idempotente.

Organização do código

Os módulos têm seus próprios mod.barrel:

  • Raiz: ciclo do jogo e entrada do controle; exporta somente init e frame.
  • @zelda1:link: personagem, movimento, ataque e desenho; exporta o serviço Link.
  • @zelda1:scene: apresentação, viewport e emissão de sprites; exporta Scene.
  • @zelda1:hud: interface extraída da ROM, com slot A ligado ao inventário; exporta Hud.
  • @zelda1:stage: API da stage ativa e sonda de colisão NES; exporta Stage.
  • @zelda1:stages/overworld_start: cenário e mapa de colisão da primeira tela; exporta OverworldStart.
  • @zelda1:stages/cave_start: cenário e colisão da caverna; exporta CaveStart.

O código interno de Link permanece com visibilidade mod. O módulo raiz não conhece LinkState, LinkMovement, renderizador ou contadores da espada.

Arquivo em src/ Responsabilidade
main.pbs Leitura dos botões e ciclo do jogo
link/main.pbs API Link.reset(), Link.prepare_stage(...), Link.update(...) e Link.draw(), composição dos sistemas internos
link/state.pbs Estado de referência do personagem, animação e arma
link/controller.pbs Reset, início do ataque e temporização do corpo
link/movement.pbs Prioridade dos direcionais, curvas e movimento fracionário
link/render.pbs Seleção das imagens de corpo e espada, coordenadas NES e prioridades
link/sword.pbs Transições e contadores da espada, depois do desenho do corpo
link/graphics.generated.pbs Glyph IDs e offsets extraídos, regeneráveis
stage/main.pbs e stage/player_probe.pbs Acesso à stage ativa e consulta do terreno pelas regras NES
stages/overworld_start/ Vínculo do cenário, IDs de tiles e classificação de colisão da sala
scene/main.pbs API Scene.reset(), Scene.ensure_ready(), Scene.emit_sprite(...) e Scene.draw_frame(); preparação da apresentação, câmera, viewport e moldura

O módulo Link cria uma única instância de cada sistema e de LinkState na inicialização. Os sistemas recebem explicitamente a mesma referência ao estado, sem copiar seus contadores ou alocar objetos a cada frame. A ordem continua sendo entrada, atualização de Link, desenho do corpo e atualização/desenho da espada.

A primeira divisão reduziu main.pbs de 292 para 27 linhas, registrada em refactor-validation.json. A divisão em módulos deixou a raiz com 16 linhas; a chamada da moldura acrescentou uma linha. Build/pack e os diagnósticos dos nove arquivos passaram. Os 15 casos de movimento e 43 de ataque foram reexecutados; as 58 capturas ficaram idênticas pixel a pixel às anteriores. modules-validation.json registra essa nova comparação. Essa é uma validação de preservação do port atual, não uma nova comparação com um emulador NES.

O identificador técnico no manifesto foi ajustado para zelda1, permitindo imports PBS como @zelda1:link: a gramática de módulo atual não aceita o hífen do identificador anterior zelda-1. A pasta e o app_id permanecem iguais. O módulo Link depende somente da API pública de cena; cena não depende de Link.

Caixa de apresentação em escala original

A imagem lógica NES permanece em 256×240, escala 1:1, com origem (112, 15) na saída 480×270. A caixa externa mede 272×256, com origem (104, 7) e margem de 8 pixels. Tanto a imagem quanto a caixa ficam centralizadas nos dois eixos. O espaço superior de 64 pixels do NES continua reservado ao futuro HUD.

Scene.draw_frame() desenha o fundo externo e a moldura com Gfx, fora da área NES. Como essas primitivas são aplicadas depois do Composer, também encobrem partes de sprites que ultrapassem os limites de 256×240. Não se usa clear sobre a área do jogo, escala de coordenadas, redimensionamento dos PNGs ou suavização.

Essa é uma composição feita pelo projeto, não uma nova API de viewport do runtime. viewport-preview.png mostra a captura real. Os seis casos em viewport-validation/results.json verificam o quadro inicial, as quatro bordas e a espada ultrapassando a borda inferior. A imagem interna foi comparada com os pixels originais; a moldura e o fundo externo também foram conferidos.

Validação do movimento

Build/pack e diagnostics PBS concluíram sem erros. As capturas reais do runtime em movement-validation/ foram comparadas com composições de pixels esperadas, incluindo fundo preto integral para detectar rastros. results.json registra os 15 casos aprovados: orientação inicial, alternância, quatro direções, parada nas duas fases, prioridade de entrada simultânea, limites e reversão entre pontos da grade. Os deslocamentos negativos respeitam o borrow original; não se pressupõe simetria de arredondamento com os deslocamentos positivos.

Ataque com A

No modo Play, pressione o botão A configurado no Studio. A espada já está disponível nesta sala de teste. Segurar A não repete o ataque; entradas durante o período ocupado não ficam enfileiradas.

O controle porta WieldSword, UpdateSwordOrRod, AnimateLinkObjState e a ordem original de atualização: primeiro entrada/movimento/corpo, depois arma. Os contadores da arma sobrescrevem o contador de animação de Link depois de seu corpo ser desenhado, o que determina os instantes de recuperação.

Tick desde o início Corpo sem entrada direcional Espada
1–4 Pose de ataque, fase 0 Oculta, preparação
5–12 Pose de ataque, fase 0 Estado 2, extensão completa
13 Pose normal, fase 0 Estado 3, primeiro recolhimento
14 Pose normal, fase 1 Estado 4, segundo recolhimento
15 Mantém a fase normal Estado 5, oculta
16 Mantém a fase normal Desativada ao atualizar a arma
17 em diante Controle normal Pode iniciar outro golpe com uma nova borda de A

O deslocamento fica bloqueado até o tick 13; pode voltar no tick 14, mesmo com a espada ainda recolhendo. A orientação continua obedecendo à rotina original de direcionais durante o golpe. Não é um travamento de direção.

As quatro imagens da espada são sprites separados; usam a paleta original da espada de madeira (a mesma linha de cores de Link), transparência e a prioridade do corpo de Link à frente da arma. Os offsets por estado/direção são extraídos diretamente da ROM e registrados em attack-data.json.

O animator sword no Studio contém os clipes point_up, point_down, point_left e point_right. Os clipes attack_* do animator link são catálogos das poses do corpo; a sequência completa acima é controlada pelo estado do jogo em PBS e não pela duração desses clipes de preview.

Extração reproduzível das imagens da espada:

python3 tools/assemble_sword.py
python3 tools/sync_link_animation.py

O primeiro script preserva os 16 artefatos de corpo e acrescenta as quatro armas. A definição oficial de animações foi atualizada pela API do Studio com revisão esperada, preservando os clipes existentes. Se regenerar o banco base inteiro com assemble_link.py, regenere também a espada e valide/revincule os bindings no Studio antes de sincronizar o código.

O padrão vertical usa os tiles $20/$21, centralizados como objeto de largura 8; o horizontal usa $82..$85, com os espelhamentos originais. Esses padrões horizontais vêm da área carregada na abertura que permanece em CHR-RAM quando os gráficos de nível são carregados. Não são gráficos redesenhados.

Validação: build/pack e diagnostics sem erros; 43 capturas reais comparadas pixel a pixel em attack-validation/results.json. Cobrem quatro direções, fronteiras de estado, entrada mantida, nova pressão após soltura, mudança de orientação durante a extensão e retorno do deslocamento no tick 14. attack-preview.png reúne as capturas ampliadas sem suavização.

Escopo atual: animação da espada de madeira, sem som. Não inclui colisão de golpe, dano, inventário nem o projétil disparado com vida cheia no original.

A conexão com a segunda stage está documentada em caverna inicial. Link.prepare_stage() aplica posições forçadas antes do vínculo do cenário; entradas normais são suspensas durante os percursos de entrada e saída.

Link agora inicia sem espada e só ataca quando Items[0]>0. A primeira aquisição, pose e persistência na sessão estão documentadas em inventário. Link.update() e Link.draw() separam a mudança de estado da composição visual; as capturas antigas de ataque são anteriores a essa aquisição e pressupõem espada disponível.

O sistema de vida agora mantém dano, cura, invulnerabilidade, recuo e morte. Link.hurt(...) é a entrada para futuros atacantes e os corações do HUD são gerados a partir dos mesmos bytes de vida de Items.