Play and record, or work with an AI.

A recording is not a video. The Mesen emulator saves only the buttons you press, frame by frame, in a small file (.mmo). The project then replays that file and the game happens again, identically. That lets us compare our game with the original on the same play.

1. Choose what to record

   Start with the requested recordings list here on the site, in order: it goes from what helps most to what helps least. The pack has the same requests as text. If you like, write to David first to agree on what is most missing and avoid repeating what already exists.

2. Set up the pack

   Unzip the pack into a folder. Unzip Mesen 2.1.1 so that Mesen.exe sits inside the pack's Mesen folder, without deleting settings.json. Put your ROM in 1-PUT-YOUR-ROM-HERE and run 2-CHECK-THE-ROM.bat: it must show OK in green. Open Mesen with 3-PLAY-AND-RECORD.bat, set up your controller in Settings > Input and open the ROM with File > Open.

3. Reach the starting point without recording

   Go to the boss door, or just before the enemy, and save a save state there. Before you start recording, loading a save state is fine, as often as you like.

4. Record your attempt

   Menu Tools > Movies > Record. Save the file in the pack's recordings folder, with the name the list gives. Under Record from, choose Current state. Use Power on only when the list asks for it.

5. Stop and check

   Menu Tools > Movies > Stop. Check that the .mmo file is in the folder. Did it not go as planned? Load the save state and record again with the same name plus -b at the end (then -c, -d). Do not delete the earlier ones: a failed attempt is useful too.

6. Send the recordings

   Zip the recordings folder and email it to davidluky@davidluky.com, the website's contact. You can send them a little at a time, after each session. Do not send the ROM.

Inside the project, AI work runs like this:

1. One card per session

   Each AI session gets one card: a complete request with the files, the commands and the number that proves it worked, set before the work starts.

2. Coordinator and executor

   A coordinator writes and orders the cards and checks every delivery against the repository. An executor runs one card at a time, exactly as written.

3. The proof is the original game

   A behaviour is accepted when our game's state is equal to the original's on the same recordings. The checklist only goes up with verified parts. Players' recordings are the material for that comparison.

4. Stopping is a result too

   A card that cannot finish is parked with the numbers seen and the command to resume. That counts as a good outcome.

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. Find the module your change belongs to

   Start with README.md ↗, follow CONTRIBUTING.md ↗ and consult the architecture map ↗. The guides explain who owns input, state and each frame update. 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: