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
initeframe. @zelda1:link: personagem, movimento, ataque e desenho; exporta o serviçoLink.@zelda1:scene: apresentação, viewport e emissão de sprites; exportaScene.@zelda1:hud: interface extraída da ROM, com slot A ligado ao inventário; exportaHud.@zelda1:stage: API da stage ativa e sonda de colisão NES; exportaStage.@zelda1:stages/overworld_start: cenário e mapa de colisão da primeira tela; exportaOverworldStart.@zelda1:stages/cave_start: cenário e colisão da caverna; exportaCaveStart.
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.