Encontre seu jeito de contribuir.

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. Leia as instruções do checkout

   Comece por AGENTS.md ↗ e CONTRIBUTING.md ↗. Há propostas de testes para transformação de tela, arquivos JSON, animação e contenção de caminhos. 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: