How to Report a Bug in RenoDX: A Complete Guide for DirectX Modders

Report RenoDX bugs by identifying the affected subsystem (Devkit, MCP Bridge, or Shader Pipeline), creating a minimal reproducible test case, enabling debug logging via RENO_DEBUG=1, and submitting a detailed GitHub Issue with logs and crash dumps.

RenoDX is a Reshade‑based modding engine for DirectX games that enables runtime shader modification and resource upgrading. When something breaks, providing the maintainers at clshortfuse/renodx with precise diagnostic information dramatically speeds up resolution. This guide walks you through the exact steps to isolate, document, and report issues using the repository's existing tooling and source structure.

Identify the Affected Subsystem

RenoDX consists of three distinct subsystems, each with separate entry points and logging facilities. Determining which component fails is the first step toward a useful report.

• Devkit Addon – The in‑game inspection layer that injects into the target process. Source code resides in [src/addons/devkit/addon.cpp](https://github.com/clshortfuse/renodx/blob/main/src/addons/devkit/addon.cpp).
• MCP Bridge – The helper process that forwards devkit data to external MCP clients. Implementation is located in [src/apps/mcp_bridge/main.cpp](https://github.com/clshortfuse/renodx/blob/main/src/apps/mcp_bridge/main.cpp).
• Shader / Resource Upgrade Pipeline – The compile‑time and run‑time handling of shaders, resource upgrades, and tonemapping. Architectural details are documented in [docs/DEVKIT_MCP.md](https://github.com/clshortfuse/renodx/blob/main/docs/DEVKIT_MCP.md).

Once you have identified the subsystem, you can focus your reproduction steps on the relevant code path and log sources.

Build a Minimal Reproducible Test Case

A minimal test case isolates the cause and eliminates variables. Use the generic game template located at src/games/generic as your starting point.

1. Copy the generic template to a new directory under src/games/.
2. Modify the addon entry point to trigger the specific behavior that fails.
3. Compile with the standard CMake workflow: cmake --preset clang-x64 && cmake --build --preset clang-x64-release.

Detailed instructions for creating a new mod are in the "Building a mod" section of [docs/CONTRIBUTING.md](https://github.com/clshortfuse/renodx/blob/main/docs/CONTRIBUTING.md#building-a-mod). If the bug appears during addon initialization, use this minimal addon.cpp to confirm the entry point is reached:

// src/games/generic/addon.cpp
#include "reshade.hpp"
#include "src/utils/settings.hpp"

extern "C" __declspec(dllexport) void reshade_register_addon_api(reshade::api::addon_interface *api)
{
    // Register a simple on‑load callback
    api->register_event<reshade::api::event::init_device>([]
    {
        reshade::log::message(reshade::log::level::debug, "Generic test addon loaded – good to go!");
    });

    // Expose a dummy setting so the user can toggle the addon
    const reshade::api::setting_info debug_setting = {
        .key = "debug.generic_test",
        .binding = nullptr,
        .default_value = "0",
        .label = "Enable generic test addon",
        .section = "Debug"
    };
    api->register_setting(debug_setting);
}

Copy the resulting renodx-generic.addon64 into the Reshade addons folder and launch the target game. If the subsystem loads correctly, the debug line above will appear in the log output.

Enable Debug Logging and Capture Diagnostics

RenoDX provides extensive debug instrumentation via the utility headers [src/utils/trace.hpp](https://github.com/clshortfuse/renodx/blob/main/src/utils/trace.hpp) and [src/utils/shader_dump.hpp](https://github.com/clshortfuse/renodx/blob/main/src/utils/shader_dump.hpp).

To enable debug output:

1. Run the setup‑dev‑env script with the -Update flag.
2. Launch the game with the environment variable RENO_DEBUG=1, or edit [src/utils/settings.hpp](https://github.com/clshortfuse/renodx/blob/main/src/utils/settings.hpp) to force debug mode.
3. Reproduce the issue.

After reproduction, collect the following artifacts from the game directory or bin folder:

• Console output and any generated renodx-debug.log files.
• Windows error dump (.dmp) if a crash occurred.
• Exact shader IDs or resource hashes if the bug involves the pipeline.

These logs provide the call stack, shader compilation errors, and subsystem state transitions necessary for triage.

Submit a GitHub Issue

Navigate to the Issues tab and select New Issue → Bug report. Use the following template to ensure all required fields are present:

**Component**: (Devkit / MCP Bridge / Shader Pipeline)  
**Game / Target**: (e.g., "Zelda: Tears of the Kingdom")  
**RenoDX Version**: (output of `git rev-parse HEAD`)  

**Reproduction Steps**  
1. …  
2. …  

**Observed Behavior**  
(copy the exact console/log output here)

**Expected Behavior**  
(what should happen)

**Additional Context**  
- OS / Windows SDK version  
- Toolchain versions (`dxcompiler`, `slangc`, `glslang`) – see `cmake/tool-versions.cmake` for minimums  
- Screenshots or video (optional)  

**Attachments**  
- `renodx-debug.log`  
- Crash dump (`.dmp`) if applicable  

Include the minimum tool versions listed in cmake/tool-versions.cmake to verify your build environment meets requirements. After submission, monitor the issue for follow‑up questions regarding revised test cases or additional logs.

Summary

• Identify the subsystem using the entry points in src/addons/devkit/addon.cpp, src/apps/mcp_bridge/main.cpp, or the shader pipeline documentation.
• Create a minimal test case based on src/games/generic to isolate the failure.
• Enable debug logging via RENO_DEBUG=1 or src/utils/settings.hpp, then collect renodx-debug.log and crash dumps.
• File a structured GitHub Issue with component tags, reproduction steps, observed behavior, and toolchain versions from cmake/tool-versions.cmake.

Frequently Asked Questions

Where do I find the RenoDX debug logs?

RenoDX writes debug output to renodx-debug.log in the game or bin directory when logging is enabled. The logging functions in src/utils/trace.hpp and src/utils/shader_dump.hpp generate these entries. Check this file after reproducing the issue to find the exact call stack and subsystem state.

What information is required for a shader pipeline bug?

Shader pipeline issues require the specific shader hash or resource ID, the .cso or .hlsl source if applicable, and the output of renodx-debug.log showing the compilation error. Reference docs/DEVKIT_MCP.md for details on how the pipeline processes resources, and list the versions of dxcompiler, slangc, and glslang from your environment.

How do I create a minimal test case for the devkit addon?

Start with the template in src/games/generic/addon.cpp and strip away all unrelated functionality. Register a single callback that triggers the bug, compile the addon, and place it in the Reshade addons folder. If the issue involves initialization, verify that reshade::log::message appears in the logs to confirm the entry point in src/addons/devkit/addon.cpp was reached.

Should I attach crash dumps to my bug report?

Yes, always attach .dmp files when the engine crashes. These dumps allow maintainers to inspect the exact memory state and thread context at the point of failure. Pair the dump with the corresponding renodx-debug.log and the commit hash from git rev-parse HEAD so developers can match symbols to the correct source version.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}