277 lines
15 KiB
Markdown
277 lines
15 KiB
Markdown
# 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.
|