Files
zelda-1-prometeu-port/extracted/link/README.md
T

277 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.