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

> Report RenoDX bugs effectively. Learn to identify issues, create test cases, enable debug logging, and submit detailed GitHub issues for faster resolution. A must-read for DirectX modders.

- Repository: [Carlos Lopez/renodx](https://github.com/clshortfuse/renodx)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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)](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)](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)](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)](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`](https://github.com/clshortfuse/renodx/blob/main/addon.cpp) to confirm the entry point is reached:

```cpp
// 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)](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)](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)](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](https://github.com/clshortfuse/renodx/issues) tab and select **New Issue → Bug report**. Use the following template to ensure all required fields are present:

```markdown
**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`](https://github.com/clshortfuse/renodx/blob/main/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`](https://github.com/clshortfuse/renodx/blob/main/src/addons/devkit/addon.cpp), [`src/apps/mcp_bridge/main.cpp`](https://github.com/clshortfuse/renodx/blob/main/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`](https://github.com/clshortfuse/renodx/blob/main/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`](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) 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`](https://github.com/clshortfuse/renodx/blob/main/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`](https://github.com/clshortfuse/renodx/blob/main/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`](https://github.com/clshortfuse/renodx/blob/main/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.