Jogue e grave, ou trabalhe com uma IA.

A gravação não é um vídeo. O emulador Mesen guarda só os botões que você aperta, quadro a quadro, num arquivo pequeno (.mmo). Depois o projeto reproduz esse arquivo e o jogo acontece de novo, idêntico. Assim dá para comparar o nosso jogo com o original nas mesmas jogadas.

1. Escolha o que gravar

   Comece pela lista de gravações pedidas, aqui no site, na ordem: ela vai do que mais ajuda para o que menos ajuda. O pacote traz os mesmos pedidos em texto. Se quiser, escreva antes para o David para combinar o que mais falta e não repetir o que já existe.

2. Prepare o pacote

   Descompacte o pacote numa pasta. Descompacte o Mesen 2.1.1 de modo que o Mesen.exe fique dentro da pasta Mesen do pacote, sem apagar o settings.json. Coloque a sua ROM em 1-COLOQUE-A-ROM-AQUI e rode 2-CONFERIR-A-ROM.bat: tem que aparecer OK em verde. Abra o Mesen com 3-JOGAR-E-GRAVAR.bat, configure o controle em Settings > Input e abra a ROM em File > Open.

3. Chegue ao ponto de partida sem gravar

   Vá até a porta do chefe, ou até antes do inimigo, e salve um save state ali. Antes de começar a gravar, carregar save state pode, quantas vezes quiser.

4. Grave a tentativa

   Menu Tools > Movies > Record. Salve o arquivo na pasta gravacoes do pacote, com o nome que a lista indica. Em Record from, escolha Current state. Power on só quando a lista pedir.

5. Pare e confira

   Menu Tools > Movies > Stop. Confira se o arquivo .mmo apareceu na pasta. Não saiu como queria? Carregue o save state e grave de novo com o mesmo nome e -b no final (depois -c, -d). Não apague as anteriores: tentativa errada também serve.

6. Envie as gravações

   Compacte a pasta gravacoes num arquivo zip e envie por e-mail para davidluky@davidluky.com, o contato do site. Pode enviar aos poucos, a cada sessão. Não envie a ROM.

Dentro do projeto, o trabalho com IA funciona assim:

1. Um cartão por sessão

   Cada sessão de IA recebe um cartão: um pedido completo, com os arquivos, os comandos e o número que prova que deu certo, definido antes do trabalho.

2. Coordenador e executor

   Um coordenador escreve e ordena os cartões e confere cada entrega no repositório. Um executor faz um cartão por vez, exatamente como está escrito.

3. A prova é o jogo original

   Um comportamento é aceito quando o estado do nosso jogo fica igual ao do original nas mesmas gravações. O checklist só sobe com partes verificadas. As gravações dos jogadores são o material dessa comparação.

4. Parar também é resultado

   Um cartão que não termina é estacionado com os números vistos e o comando para retomar. Isso conta como um bom resultado.

O primeiro pacote público oferece código C++17, um núcleo compilável e 15 contratos independentes de assets. Use uma tarefa pequena de lógica, teste, documentação ou portabilidade para começar.

pacman -S --needed mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-raylib mingw-w64-x86_64-nlohmann-json

git clone https://github.com/davidluky/megaman-x-engine.git
cd megaman-x-engine
$env:PATH = "C:\msys64\mingw64\bin;C:\msys64\usr\bin;" + $env:PATH
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build -j 8
ctest --test-dir build --output-on-failure

1. Encontre o módulo da sua mudança

   Comece pelo README.md ↗, siga CONTRIBUTING.md ↗ e consulte o mapa de arquitetura ↗. Os guias mostram os responsáveis por entrada, estado e atualização de cada quadro. Confira os contratos existentes antes de adicionar outro.

2. Encontre quem executa a regra

   enemy.cpp ↗ contém o comportamento dos inimigos; kb_fsm.cpp ↗ é o interpretador de máquinas de estados. As definições e capturas de referência não acompanham o código público. Identifique o dado necessário antes de propor valores novos.

3. Reproduza com uma entrada pequena

   Use dados criados em memória ou arquivos temporários. Contrato de controles ↗ é um exemplo; PublicTests.cmake ↗ registra a seleção pública. O teste deve mostrar uma falha real ou uma regra ainda sem cobertura.

4. Envie um pull request revisável

   Crie uma branch no seu fork, confira o diff e envie a mudança com o comando de teste e o resultado. A revisão humana decide a integração. Se o caso precisar de material ausente, entregue a investigação e o requisito exato.

Uma medição útil responde uma pergunta pequena: de que lado o projétil nasce, qual evento inicia um ataque ou em que quadro o inimigo muda de estado.

1. Defina a pergunta e o controle

   Escolha a ficha, a fase e uma situação reproduzível. Para direção do tiro, por exemplo, compare X à esquerda e à direita, mantendo a mesma situação de ataque. Um vídeo já ajuda a localizar o problema.

2. Identifique a referência

   Anote a versão do jogo, o estado inicial e os comandos usados. Para pesquisa avançada, o projeto usa Mesen e Lua com uma referência local compatível. Peça orientação sobre a fixture: ela é um estado de referência do emulador, não um arquivo intercambiável entre qualquer configuração.

3. Registre o primeiro desvio

   Conte os quadros, descreva a posição e registre o estado do inimigo quando possível. Diferencie coordenadas do mundo, da câmera e da imagem: o mesmo número em bases diferentes pode parecer uma correção e introduzir um erro.

4. Entregue os dados reduzidos

   Uma tabela curta com quadro, ação, posição, velocidade, HP e evento costuma ser mais útil que um pacote enorme. Inclua a receita de captura e exemplos que confirmam ou rejeitam sua hipótese.

./build/venv/Scripts/python.exe tools/oracle/check_recordings.py --brief
./build/venv/Scripts/python.exe tools/oracle/validate_fixture.py tools/oracle/fixtures/stage_select_thispc.mss

$traceDir = Join-Path 'build/contributor' ('intro-enemy-trace-' + [guid]::NewGuid().ToString('N'))
./build/venv/Scripts/python.exe tools/oracle/run_mesen.py --game mmx1 --script tools/oracle/lua/enemy_behavior_trace.lua --savestate tools/oracle/fixtures/stage_select_thispc.mss --out $traceDir --timeout 120

Você pode ajudar a recuperar um quadro incorreto, identificar uma paleta ou descobrir por que o personagem parece “pular” de posição entre poses. A ficha indica quando a arte já está verificada e o problema está em outra parte.

1. Escolha um quadro, não a folha inteira

   Informe o personagem, a animação, o índice do quadro e a referência visual. Separe desenho errado de quadro correto usado no momento errado.

2. Preserve o ponto de apoio

   Compare os pés, o centro do corpo e a origem do projétil na mesma posição. Mantenha dimensões da célula, transparência, ordem dos quadros e alinhamento. Alterar o recorte pode mexer na aparência mesmo que o desenho seja igual.

3. Confira a paleta e as duas direções

   Use as cores da referência e confira também os quadros de dano ou tiro. Algumas folhas possuem uma versão de flash separada. Não espelhe um personagem só por convenção: o Axe Max, por exemplo, tem orientação própria documentada.

4. Entregue uma comparação clara

   Inclua antes/depois na mesma escala, a célula alterada, o arquivo editável e a origem do material. Se a arte estiver correta e a sequência errada, o ajuste pode ser na definição da animação.

./build/venv/Scripts/python.exe tools/pack_enemy_sprite.py --src content/x1/sprites/enemies/mmm-mmxmetoll.gif --dst build/met-candidate.png --cell-width 32 --cell-height 32

Há trabalho tanto na escuta quanto na implementação: localizar um reinício audível, medir o loop, identificar um efeito ausente ou conferir quando o som deve tocar.

1. Identifique a faixa ou o evento

   Informe a fase e a situação. Para um efeito, registre a ação que deveria produzi-lo. Para música, separe introdução, repetição e eventual pausa causada por outro evento do jogo.

2. Marque a fronteira do loop

   Registre a taxa de amostragem e as posições inicial/final em frames de áudio. Elas são amostras PCM por canal, não quadros do jogo. A introdução deve tocar uma vez e o trecho escolhido deve repetir sem corte perceptível.

3. Use o formato e o mapa do motor

   Música sem região de loop configurada pode usar OGG; efeitos usam WAV. Quando a faixa tem loop configurado, como Flame Mammoth, o caminho atual exige WAV PCM de 16 bits, com canais e taxa de amostragem compatíveis. Um OGG sozinho não prepara esse caso. bgm.json acervo privado conecta as fases às faixas. A referência de loop do Flame Mammoth acervo privado mostra os campos start_frame, end_frame, sample_rate e a origem da medição.

4. Ouça a transição, depois confira no jogo

   Reproduza várias voltas e compare a emenda. Para SFX, confira também o momento do ataque ou da apresentação. Trocar uma amostra não corrige um evento disparado no quadro errado.

ctest --test-dir build -R audio-loop --output-on-failure

Você pode contribuir sem escrever código. Um relato que permite repetir o problema economiza tempo e ajuda a conferir se a correção realmente resolveu o caso.

1. Reduza o caminho até o erro

   Anote a fase, o trecho, os comandos e se chegou pelo menu, por respawn ou pelo mapa de teste. Diga se houve dash, tiro carregado, parede ou mudança de direção.

2. Mostre o primeiro instante estranho

   Um vídeo curto é ótimo para animação e áudio. Para colisão, explique onde o tiro ou o corpo deveria tocar. Se só acontece às vezes, informe as tentativas que funcionaram e as que falharam.

3. Identifique a versão testada

   Inclua o commit ou o pacote recebido. Se tiver acesso ao build, o log é logs/megaman-x.log na pasta do executável. Envie apenas o trecho relevante, depois de conferir o conteúdo.

4. Confira novamente depois da correção

   Repita os mesmos passos e também um caso vizinho: outro lado do inimigo, um tiro em outra altura ou retorno após morrer. Isso separa uma correção robusta de um ajuste que só funciona em uma situação.

Personagem / problema:
Fase e trecho:
Versão ou commit do projeto:
Sistema / versão do Windows:
Comando, perfil de teste ou caminho pelo menu:
Fixture, posição inicial e seed (se houver):
Compilador / toolchain (se você compilou):

Passos para reproduzir:
1.
2.
3.

O que eu esperava:
O que aconteceu:
Ocorre sempre ou às vezes?
Primeiro instante incorreto no vídeo:
Link para vídeo curto / captura / log: