Find your way to contribute.

The first public package provides C++17 source, a buildable core and 15 asset-independent contracts. Start with a small logic, test, documentation or portability task.

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. Read the checkout instructions

   Start with AGENTS.md ↗ and CONTRIBUTING.md ↗. Suggested tests cover screen transforms, JSON files, animation and path containment. Check existing contracts before adding another.

2. Find the code that applies the rule

   enemy.cpp ↗ contains enemy behavior; kb_fsm.cpp ↗ is the state machine interpreter. Reference definitions and captures are not included with the public source. Identify the required data before proposing new values.

3. Reproduce with a small input

   Use data created in memory or temporary files. Input bindings contract ↗ is an example; PublicTests.cmake ↗ lists the public selection. The test should demonstrate a real failure or a rule that is not covered yet.

4. Submit a reviewable pull request

   Create a branch in your fork, inspect the diff and submit the change with the test command and result. Human review decides whether to merge. If the case needs missing material, submit the investigation and the exact requirement.

A useful measurement answers a small question: which side the projectile starts from, what event starts an attack, or on which frame the enemy changes state.

1. Define the question and control

   Choose the entry, stage, and a reproducible situation. For shot direction, for example, compare X on the left and right while keeping the same attack situation. A video already helps locate the problem.

2. Identify the reference

   Record the game version, initial state, and commands used. For advanced research, the project uses Mesen and Lua with a compatible local reference. Ask for guidance about the fixture: it is an emulator reference state, not a file interchangeable between arbitrary configurations.

3. Record the first deviation

   Count frames, describe the position, and record the enemy state when possible. Distinguish world, camera, and image coordinates: the same number in different coordinate bases can look like a correction and introduce an error.

4. Deliver reduced data

   A short table with frame, action, position, speed, HP, and event is usually more useful than a huge package. Include the capture recipe and examples that confirm or reject your hypothesis.

./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

You can help recover an incorrect frame, identify a palette, or find out why the character appears to “jump” between poses. The entry indicates when the art has already been verified and the problem lies elsewhere.

1. Choose a frame, not the whole sheet

   Report the character, animation, frame index, and visual reference. Separate an incorrect drawing from a correct frame used at the wrong time.

2. Preserve the anchor point

   Compare the feet, body center, and projectile origin at the same position. Keep the cell dimensions, transparency, frame order, and alignment. Changing the crop can alter the appearance even when the drawing is identical.

3. Check the palette and both directions

   Use the reference colors and also check the damage or shooting frames. Some sheets have a separate flash version. Do not mirror a character just by convention: Axe Max, for example, has its own documented orientation.

4. Deliver a clear comparison

   Include before/after at the same scale, the changed cell, the editable file, and the material source. If the art is correct and the sequence is wrong, the adjustment may belong in the animation definition.

./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

There is work both in listening and implementation: locating an audible restart, measuring the loop, identifying a missing effect, or checking when the sound should play.

1. Identify the track or event

   Report the stage and situation. For an effect, record the action that should produce it. For music, separate the intro, repeat, and any pause caused by another game event.

2. Mark the loop boundary

   Record the sample rate and the start/end positions in audio frames. These are PCM samples per channel, not game frames. The intro should play once and the selected section should repeat without an audible cut.

3. Use the engine's format and map

   Music without a configured loop region may use OGG; effects use WAV. When the track has loop a configured loop, as Flame Mammoth does, the current path requires 16-bit PCM WAV with compatible channels and sample rate. An OGG alone does not prepare this case. bgm.json private materials connects stages to tracks. The loop reference for Flame Mammoth private materials shows the fields start_frame, end_frame, sample_rate and the measurement source.

4. Listen to the transition, then check it in the game

   Play several loops and compare the seam. For SFX, also check the timing of the attack or presentation. Replacing a sample does not fix an event triggered on the wrong frame.

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

You can contribute without writing code. A report that allows the problem to be reproduced saves time and helps verify that the fix really solved the case.

1. Shorten the path to the error

   Record the stage, section, commands, and whether you reached it through the menu, a respawn, or the test map. Say whether there was a dash, charged shot, wall, or change of direction.

2. Show the first strange moment

   A short video is great for animation and audio. For collision, explain where the shot or body should make contact. If it only happens sometimes, report the attempts that worked and those that failed.

3. Identify the tested version

   Include the commit or package you received. If you have access to the build, the log is logs/megaman-x.log in the executable's folder. Send only the relevant excerpt after checking its contents.

4. Check again after the fix

   Repeat the same steps and also a nearby case: the other side of the enemy, a shot at another height, or returning after dying. This distinguishes a robust fix from an adjustment that works in only one situation.

Character / problem:
Stage and section:
Project version or commit:
System / Windows version:
Command, test profile, or menu path:
Fixture, initial position, and seed (if applicable):
Compiler / toolchain (if you compiled):

Steps to reproduce:
1.
2.
3.

What I expected:
What happened:
Does it happen every time or sometimes?
First incorrect moment in the video:
Link to short video / capture / log: