Contribute, as a person or an AI agent

Send a device report

The device report form is the most useful contribution for untested devices. Include:

• Device, CPU, GPU and RAM
• The full graphics driver version (on Intel, like 32.0.101.9175; on Linux, the Mesa version) and the OS
• Plugged in or on battery, and the power mode or wattage
• The emulator build, every setting you changed and every EDEN_NX2_* switch you set (or "none")
• The game and the exact spot, docked or handheld mode, and a screenshot of the scene
• Average fps and, if you can, p50 and p99 frame times, measured after the scene settled

Never attach keys, firmware, game files, saves, shader caches, or logs that show your user name or folder paths.

A report of something that doesn't work is as useful as a good result.

Agent-ready issues

Issues labeled agent-ready carry the goal, the files, an acceptance test and how to measure the result, so an AI agent, or a person, can pick one up without a long back-and-forth. For a first contribution by hand, look at good first issue.

Free CI builds on every pull request

Every pull request is built by GitHub Actions on Windows (clang-cl) and Linux (GCC), with warnings as errors, and the tests run, at no cost to you. The Windows build is uploaded as a test build, kept for 14 days and linked in a comment on the pull request, so a tester with the game can try your change without building anything. Pull requests that only touch documentation skip the build.

Branches and releases are described in docs/LANES.md: pull requests go to main, experiments live behind default-off EDEN_NX2_* switches.

For AI agents

Start with AGENTS.md

AGENTS.md at the repository root is the brief for coding agents: check upstream before writing a fix, try a live experiment through the debug server before asking for a new build, keep experiments behind switches that are off by default, and use the debugging tools it lists before guessing.

Drive the emulator through the debug MCP server

Start the emulator with EDEN_NX2_DEBUG_SERVER=127.0.0.1:6545 set in its environment. It then listens on loopback only, and is off when the variable is not set. tools/nx2/debug_mcp.py (Python, standard library only) is a stdio MCP server that forwards to it, so an agent can ask a running game questions without a relaunch or a rebuild:

• status, frame_times and screenshot: what is on screen and how evenly frames arrive
• log_tail and log_filter: read new log lines and change the filter live
• capture_frame and reject_shaders: dump a frame and A/B shaders live
• input and input_sequence: press buttons and replay timed inputs to reach a spot

Add it to an MCP client from the repository root. With Claude Code:

claude mcp add guarana-debug -- python -I tools/nx2/debug_mcp.py --server 127.0.0.1:6545

Or in any client's JSON configuration:

{
  "mcpServers": {
    "emulator-debug": {
      "command": "python",
      "args": [
        "-I",
        "tools/nx2/debug_mcp.py",
        "--server",
        "127.0.0.1:6545"
      ]
    }
  }
}

Keep it light while someone is playing: one request at a time, and agents never start or stop the emulator themselves.

The design, the full tool list and its safety rules are in docs/nx2/debug-mcp.md. Game files, keys and firmware stay on the machine running the game; the server gives no way to read them.

Measure with the bench harness

tools/bench/bench.py runs one scene the same way on any machine through the same debug server, checks the scene against a reference screenshot and writes one JSON row per run. Agents and people use the same harness, so results compare.

python -I tools/bench/bench.py run --exe <emulator> --game <your game> \
    --scene tools/bench/scenes/oot-hyrule-field.json \
    --save-backup <folder with the scene's save> --reference <your screenshot>

The quality bar

1. Ship only changes with a measured gain on a verified scene.
2. Drop switches that didn't help in a paired run, or keep them off and say so.
3. Claim only numbers you have, next to their baseline.
4. A driver-bug fix needs a before and after screenshot or log, even without an fps gain.
5. Correctness first: a speed-up that changes what a game draws needs a scene comparison and a known-issues entry.

One topic per pull request, and the description states the measured effect. Changes that aren't specific to integrated GPUs belong in upstream Lichii first.