# 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](https://www.nesdev.org/wiki/PPU_palettes), 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 ```sh 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](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/Z_01.asm), e `SetUpWalkingSprites` / `Link_EndMoveAndAnimate` em [Z_07.asm](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/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](../overworld/start/README.md). 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](https://github.com/aldonunez/zelda1-disassembly/blob/master/src/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](../overworld/start/README.md). 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: ```sh 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: ```sh 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](../cave/start/README.md). `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](../inventory/README.md). `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](../life/README.md) 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.