--- name: setup-game-mod-dev description: "RenoDX workflow for setting up or resuming game mod development with Clang debug builds, DevKit, MCP bridge, ReShade game-folder links, live shader paths, per-game addon scaffolds, metadata, shader dump/decompile baselines, and verification. Use when starting a new src/games/{game} mod, continuing game-specific addon work, configuring DevKit for a game, or turning DevKit findings into a real mod." argument-hint: "game title/folder, install path, graphics API, and fresh vs continuing" ---

# Setup Game Mod Development

Set up **RenoDX mod development for a specific game**. Cover the local toolchain, DevKit/MCP inspection, game-folder ReShade/addon links, and the initial or continued `src/games/{game}` workflow.

Focus on the **development environment and mod scaffold**. For swapchain/resource tracing, HDR source proof, resource upgrades, or rejecting final-SDR inverse-tonemap approaches, use `swapchain-resource-analysis`. For shader-side tonemap/LUT math after the target pass is known, use `handle-sdr-tonemap-lut`.

## Related skills and scope

| Need | Use | |---|---| | Create/resume a game folder, build targets, link ReShade/addons, configure DevKit paths | This skill | | Trace final output, resource formats, swapchain proxy, `SwapChainPass`, SDR/HDR output toggle, or HDR source proof | `swapchain-resource-analysis` | | Edit the proven game shader for RenoDRT/PsychoV/LUT bridge math | `handle-sdr-tonemap-lut` |

Keep this skill focused on getting the mod development environment and baseline workflow ready. Record enough facts for handoff, but do not duplicate the specialized swapchain/resource or shader-math workflows.

## Boundaries

- Keep changes local to one `src/games/{game}` folder unless cross-mod work is explicitly requested. - Do not change global CMake presets, CI workflows, vendored dependencies, or external submodules. - New mods start from `src/games/generic`. - Use the CMake target named after the mod folder; the output artifact is `renodx-{mod}.addon64` or `.addon32`. - Use the `devkit` and `mcp_bridge` targets for local inspection; their debug outputs are `renodx-devkit.addon64` and `renodx-mcp-bridge.exe`. - Prefer Clang CMake presets for real development builds. Use VS Code CMake build integration when available, but select the `clang-*` configure/build presets. Treat `ninja-*` and `vs-*` presets as workflow testing paths only, not normal mod development paths. - Do not build a game addon while that game is running with the addon loaded; the DLL can be locked. - Do not put dumped `.cso` files in `src/games/{game}`. They can shadow editable HLSL during live shader loading.

## Required setup facts

Collect or infer these before editing files or changing a game folder:

| Fact | Notes | |---|---| | Work mode | `continue` if `src/games/{game}` exists or the user says resume; `fresh` otherwise. | | Mod folder id | Lowercase folder name under `src/games`, usually no spaces. | | Game title | Human-readable metadata title. | | Game binary folder | The folder where ReShade and `.addon64`/`.addon32` files must load from. Infer from metadata when possible, but verify because it may be a subfolder such as `...\Binaries\Win64`. | | Executable/process | `game_exe` or `process_name` for metadata and runtime checks. | | Graphics API | Usually `d3d11`, `d3d12`, or `vulkan`; affects loader DLL naming and shader targets. | | Architecture | Usually `x64`; use `.addon32` only for 32-bit games. | | Swapchain/output state | Optional early fact: known swapchain format/color space, especially RGBA8U/UNORM bottlenecks or existing HDR/scRGB/PQ paths. | | Proxy/resource need | Optional early fact: whether evidence suggests a RGBA16F proxy, resource upgrade, `SwapChainPass` output shader, or output preset cbuffer is needed before shader-side tonemap work. | | Store ids | Steam/GOG/Microsoft/Nexus ids if known. | | Loader name | Default is often `dxgi.dll`; honor `deploy.reshade_preferred_name` or game-specific requirements. | | ReShade state | Whether the game folder already has a ReShade loader DLL, `ReShade.ini`, and `ReShade.log`. |

Before asking for missing facts, read `src/games/{mod}/metadata.json` when it exists. Use `deploy.steam_appid`, `deploy.game_exe`, `deploy.process_name`, `deploy.api`, `deploy.architecture`, `deploy.reshade_preferred_name`, and `deploy.detection.default_install_paths` to reduce guessing. If `steam_appid` is present, resolve the local Steam install by reading Steam `libraryfolders.vdf` and `appmanifest_{appid}.acf`, then use `game_exe`/`process_name` to locate the binary folder. Steam metadata alone usually resolves only the install root; still ask when executable metadata is missing, the game is not locally installed, or multiple executable matches make the injection folder ambiguous.

## Expected agent output

When invoked, produce or maintain these sections in the response or working notes:

1. **Setup facts** - game folder, install/binary folder, API, arch, and mode. 2. **Existing state** - mod folder files, metadata, registered shaders, current build artifacts, and relevant scratch/verification notes. 3. **Build plan** - exact Clang debug CMake targets (`devkit`, `mcp_bridge`, `{mod}`) and any game-shutdown requirement. 4. **Game-folder link plan** - ReShade bootstrap state, loader DLL, DevKit addon, and game addon symlink/copy targets; list conflicts instead of deleting unknown files. 5. **DevKit plan** - MCP connection, tools path, live shader path, snapshot, draw/resource/shader inspection steps, and any handoff needed for swapchain/resource proof. 6. **Baseline plan** - original capture, dump/decompile location, editable HLSL location, 1:1 live baseline validation. 7. **Verification checklist** - target built, files generated, addon loaded, shader replacement active, runtime output validated.

## Continue an existing mod

Use this path when `src/games/{mod}` already exists.

1. Inspect the existing folder: - `metadata.json` - `addon.cpp` - `shared.h` - existing shader replacements and includes - committed `README.md`, verification/dev notes, or repo memory if present 2. Treat the folder name as the build target unless CMake target listing proves otherwise. 3. Preserve existing shader registrations and settings unless the user asks to replace them. 4. Rebuild only the smallest relevant targets: - `devkit` and `mcp_bridge` if inspection tooling changed or is missing - `{mod}` for the game addon 5. Re-link only the game folder artifacts needed for this session: - ReShade loader DLL if missing or known-good symlink target changed - `renodx-devkit.addon64` or `.addon32` - `renodx-{mod}.addon64` or `.addon32` 6. Point DevKit live shaders at the existing mod folder only if it is clean of dumped binaries and unrelated scratch files. 7. Keep concise build/runtime checks in the agent response or existing committed mod docs when setup knowledge changes.

## Start a fresh mod

1. Create `src/games/{mod}` by copying the relevant files from `src/games/generic`. 2. Keep the first scaffold minimal: - `addon.cpp` - `shared.h` - `metadata.json` - shader files only after a real target shader is proven 3. Update exported addon text in `addon.cpp`: - `NAME` should identify RenoDX for the game. - `DESCRIPTION` should identify the game-specific module. 4. Create `metadata.json` with the schema, `id`, `title`, `status`, optional `summary`/`tags`, and `deploy` fields such as `game_exe`, `api`, `steam_appid`, and `architecture`. 5. Let the top-level CMake auto-discover the mod through `addon.cpp`; do not edit global CMake just to add a game folder. 6. Build the new mod target before adding shader complexity. 7. Add shader registrations only after DevKit identifies stable target shader hashes.

## Local toolchain and build setup

Clang debug is the default path for mod development builds.

| Architecture | Configure preset | Development build preset | |---|---|---| | x64 | `clang-x64` | `clang-x64-debug` | | x86 | `clang-x86` | `clang-x86-debug` |

When working on mods, assume debug build artifacts. Use release presets only for explicit packaging/deploy requests, not normal development or DevKit iteration. Do not use `ninja-*`, `vs-*`, or ad-hoc build folders for real mod development; reserve them for workflow testing or explicit user requests.

1. Ensure repo-local shader tools exist in `bin` when DevKit decompilation or DXC isolation is needed: - `dxc.exe` - `dxcompiler.dll` - `cmd_Decompiler.exe` - optional SPIR-V tools 2. If tools are missing, run the repo setup script from the repo root with install/update intent. 3. Build these targets for live inspection: - `devkit` - `mcp_bridge` 4. Build the game target named `{mod}`. 5. If a build fails because the output `.addon64`/`.addon32` is locked, stop the game and rebuild; do not work around it by renaming random artifacts.

## Game-folder ReShade and addon links

Use symlinks for local development when possible; copy only when symlinks are unavailable or the user asks for deploy-like behavior.

1. Resolve the **game binary folder** from metadata when possible. Prefer `deploy.detection.default_install_paths`, then Steam `deploy.steam_appid` via local `appmanifest_{appid}.acf`, then locate `deploy.game_exe`/`process_name` under that root. Do not assume the Steam install root is the injection folder. 2. Check for existing loader/addon files: - ReShade loader DLL, usually `dxgi.dll` - `ReShade.ini` - `renodx-devkit.addon64`/`.addon32` - `renodx-{mod}.addon64`/`.addon32` 3. If a target exists and is not a symlink or known build artifact, report it as a conflict or backup candidate instead of deleting it. 4. Use `scripts/setup-reshade.ps1` against the game binary folder when ReShade search paths or baseline `ReShade.ini` need setup. 5. Link the DevKit addon from the active build output. 6. Link the game addon from the active build output. 7. Launch the game and confirm `ReShade.log` shows both addons loaded.

### If the game folder has no ReShade yet

First use `scripts/setup-dev-env.ps1 -Update` or `-Install` to populate repo-local `bin` with `ReShade32.dll` and `ReShade64.dll` when they are available from the machine's ReShade install. Then use `scripts/setup-reshade.ps1` against the resolved game binary folder before linking addons. If a mod folder already has metadata, prefer `scripts/setup-reshade.ps1 -Mod {mod}` so the script can infer the Steam install and loader defaults from `metadata.json`.

The script currently does useful development setup tasks:

- creates the loader DLL, default `dxgi.dll`, as a symlink to repo-local `bin\ReShade64.dll`/`bin\ReShade32.dll` when available, falling back to `%ProgramData%\ReShade`; - copies `%ProgramData%\ReShade\ReShade.ini` into the game folder when `ReShade.ini` is missing; - updates `EffectSearchPaths` and `TextureSearchPaths` in `ReShade.ini` for the game folder and common ReShade shader folders. - writes `[renodx-dev] ToolsPath` to the repo `bin` folder and `[renodx-dev] LivePath` to `src/games/{mod}` when `-Mod` resolves an existing mod folder, otherwise to the game folder's `renodx-dev\live` path. This avoids starting DevKit with no tools directory configured.

If setup reports that ReShade DLLs or `%ProgramData%\ReShade\ReShade.ini` are missing, install/configure ReShade first, rerun `scripts/setup-dev-env.ps1 -Update`, then rerun the game-folder setup. Do not fabricate a loader path.

Treat these as script limitations unless the user asks to change it:

- it defaults to `-Arch x64` and `-LoaderName dxgi.dll`; - it leaves an existing non-symlink `dxgi.dll` untouched and reports the conflict.

For a 32-bit game, call the script with `-Arch x86`. For a non-`dxgi.dll` loader or a game that needs `deploy.reshade_preferred_name`, pass `-LoaderName` explicitly and still report any existing non-symlink conflict.

Pass `-LivePath <path>` when the DevKit l

--- name: setup-game-mod-dev description: "RenoDX workflow for setting up or resuming game mod development with Clang debug builds, DevKit, MCP bridge, ReShade game-folder links, live shader paths, per-game addon scaffolds, metadata, shader dump/decompile baselines, and verification. Use when starting a new src/games/{game} mod, continuing game-specific addon work, configuring DevKit for a game, or turning DevKit findings into a real mod." argument-hint: "game title/folder, install path, graphics API, and fresh vs continuing" ---

# Setup Game Mod Development

Set up **RenoDX mod development for a specific game**. Cover the local toolchain, DevKit/MCP inspection, game-folder ReShade/addon links, and the initial or continued `src/games/{game}` workflow.

Focus on the **development environment and mod scaffold**. For swapchain/resource tracing, HDR source proof, resource upgrades, or rejecting final-SDR inverse-tonemap approaches, use `swapchain-resource-analysis`. For shader-side tonemap/LUT math after the target pass is known, use `handle-sdr-tonemap-lut`.

## Related skills and scope

| Need | Use | |---|---| | Create/resume a game folder, build targets, link ReShade/addons, configure DevKit paths | This skill | | Trace final output, resource formats, swapchain proxy, `SwapChainPass`, SDR/HDR output toggle, or HDR source proof | `swapchain-resource-analysis` | | Edit the proven game shader for RenoDRT/PsychoV/LUT bridge math | `handle-sdr-tonemap-lut` |

Keep this skill focused on getting the mod development environment and baseline workflow ready. Record enough facts for handoff, but do not duplicate the specialized swapchain/resource or shader-math workflows.

## Boundaries

- Keep changes local to one `src/games/{game}` folder unless cross-mod work is explicitly requested. - Do not change global CMake presets, CI workflows, vendored dependencies, or external submodules. - New mods start from `src/games/generic`. - Use the CMake target named after the mod folder; the output artifact is `renodx-{mod}.addon64` or `.addon32`. - Use the `devkit` and `mcp_bridge` targets for local inspection; their debug outputs are `renodx-devkit.addon64` and `renodx-mcp-bridge.exe`. - Prefer Clang CMake presets for real development builds. Use VS Code CMake build integration when available, but select the `clang-*` configure/build presets. Treat `ninja-*` and `vs-*` presets as workflow testing paths only, not normal mod development paths. - Do not build a game addon while that game is running with the addon loaded; the DLL can be locked. - Do not put dumped `.cso` files in `src/games/{game}`. They can shadow editable HLSL during live shader loading.

## Required setup facts

Collect or infer these before editing files or changing a game folder:

| Fact | Notes | |---|---| | Work mode | `continue` if `src/games/{game}` exists or the user says resume; `fresh` otherwise. | | Mod folder id | Lowercase folder name under `src/games`, usually no spaces. | | Game title | Human-readable metadata title. | | Game binary folder | The folder where ReShade and `.addon64`/`.addon32` files must load from. Infer from metadata when possible, but verify because it may be a subfolder such as `...\Binaries\Win64`. | | Executable/process | `game_exe` or `process_name` for metadata and runtime checks. | | Graphics API | Usually `d3d11`, `d3d12`, or `vulkan`; affects loader DLL naming and shader targets. | | Architecture | Usually `x64`; use `.addon32` only for 32-bit games. | | Swapchain/output state | Optional early fact: known swapchain format/color space, especially RGBA8U/UNORM bottlenecks or existing HDR/scRGB/PQ paths. | | Proxy/resource need | Optional early fact: whether evidence suggests a RGBA16F proxy, resource upgrade, `SwapChainPass` output shader, or output preset cbuffer is needed before shader-side tonemap work. | | Store ids | Steam/GOG/Microsoft/Nexus ids if known. | | Loader name | Default is often `dxgi.dll`; honor `deploy.reshade_preferred_name` or game-specific requirements. | | ReShade state | Whether the game folder already has a ReShade loader DLL, `ReShade.ini`, and `ReShade.log`. |

Before asking for missing facts, read `src/games/{mod}/metadata.json` when it exists. Use `deploy.steam_appid`, `deploy.game_exe`, `deploy.process_name`, `deploy.api`, `deploy.architecture`, `deploy.reshade_preferred_name`, and `deploy.detection.default_install_paths` to reduce guessing. If `steam_appid` is present, resolve the local Steam install by reading Steam `libraryfolders.vdf` and `appmanifest_{appid}.acf`, then use `game_exe`/`process_name` to locate the binary folder. Steam metadata alone usually resolves only the install root; still ask when executable metadata is missing, the game is not locally installed, or multiple executable matches make the injection folder ambiguous.

## Expected agent output

When invoked, produce or maintain these sections in the response or working notes:

1. **Setup facts** - game folder, install/binary folder, API, arch, and mode. 2. **Existing state** - mod folder files, metadata, registered shaders, current build artifacts, and relevant scratch/verification notes. 3. **Build plan** - exact Clang debug CMake targets (`devkit`, `mcp_bridge`, `{mod}`) and any game-shutdown requirement. 4. **Game-folder link plan** - ReShade bootstrap state, loader DLL, DevKit addon, and game addon symlink/copy targets; list conflicts instead of deleting unknown files. 5. **DevKit plan** - MCP connection, tools path, live shader path, snapshot, draw/resource/shader inspection steps, and any handoff needed for swapchain/resource proof. 6. **Baseline plan** - original capture, dump/decompile location, editable HLSL location, 1:1 live baseline validation. 7. **Verification checklist** - target built, files generated, addon loaded, shader replacement active, runtime output validated.

## Continue an existing mod

Use this path when `src/games/{mod}` already exists.

1. Inspect the existing folder: - `metadata.json` - `addon.cpp` - `shared.h` - existing shader replacements and includes - committed `README.md`, verification/dev notes, or repo memory if present 2. Treat the folder name as the build target unless CMake target listing proves otherwise. 3. Preserve existing shader registrations and settings unless the user asks to replace them. 4. Rebuild only the smallest relevant targets: - `devkit` and `mcp_bridge` if inspection tooling changed or is missing - `{mod}` for the game addon 5. Re-link only the game folder artifacts needed for this session: - ReShade loader DLL if missing or known-good symlink target changed - `renodx-devkit.addon64` or `.addon32` - `renodx-{mod}.addon64` or `.addon32` 6. Point DevKit live shaders at the existing mod folder only if it is clean of dumped binaries and unrelated scratch files. 7. Keep concise build/runtime checks in the agent response or existing committed mod docs when setup knowledge changes.

## Start a fresh mod

1. Create `src/games/{mod}` by copying the relevant files from `src/games/generic`. 2. Keep the first scaffold minimal: - `addon.cpp` - `shared.h` - `metadata.json` - shader files only after a real target shader is proven 3. Update exported addon text in `addon.cpp`: - `NAME` should identify RenoDX for the game. - `DESCRIPTION` should identify the game-specific module. 4. Create `metadata.json` with the schema, `id`, `title`, `status`, optional `summary`/`tags`, and `deploy` fields such as `game_exe`, `api`, `steam_appid`, and `architecture`. 5. Let the top-level CMake auto-discover the mod through `addon.cpp`; do not edit global CMake just to add a game folder. 6. Build the new mod target before adding shader complexity. 7. Add shader registrations only after DevKit identifies stable target shader hashes.

## Local toolchain and build setup

Clang debug is the default path for mod development builds.

| Architecture | Configure preset | Development build preset | |---|---|---| | x64 | `clang-x64` | `clang-x64-debug` | | x86 | `clang-x86` | `clang-x86-debug` |

When working on mods, assume debug build artifacts. Use release presets only for explicit packaging/deploy requests, not normal development or DevKit iteration. Do not use `ninja-*`, `vs-*`, or ad-hoc build folders for real mod development; reserve them for workflow testing or explicit user requests.

1. Ensure repo-local shader tools exist in `bin` when DevKit decompilation or DXC isolation is needed: - `dxc.exe` - `dxcompiler.dll` - `cmd_Decompiler.exe` - optional SPIR-V tools 2. If tools are missing, run the repo setup script from the repo root with install/update intent. 3. Build these targets for live inspection: - `devkit` - `mcp_bridge` 4. Build the game target named `{mod}`. 5. If a build fails because the output `.addon64`/`.addon32` is locked, stop the game and rebuild; do not work around it by renaming random artifacts.

## Game-folder ReShade and addon links

Use symlinks for local development when possible; copy only when symlinks are unavailable or the user asks for deploy-like behavior.

1. Resolve the **game binary folder** from metadata when possible. Prefer `deploy.detection.default_install_paths`, then Steam `deploy.steam_appid` via local `appmanifest_{appid}.acf`, then locate `deploy.game_exe`/`process_name` under that root. Do not assume the Steam install root is the injection folder. 2. Check for existing loader/addon files: - ReShade loader DLL, usually `dxgi.dll` - `ReShade.ini` - `renodx-devkit.addon64`/`.addon32` - `renodx-{mod}.addon64`/`.addon32` 3. If a target exists and is not a symlink or known build artifact, report it as a conflict or backup candidate instead of deleting it. 4. Use `scripts/setup-reshade.ps1` against the game binary folder when ReShade search paths or baseline `ReShade.ini` need setup. 5. Link the DevKit addon from the active build output. 6. Link the game addon from the active build output. 7. Launch the game and confirm `ReShade.log` shows both addons loaded.

### If the game folder has no ReShade yet

First use `scripts/setup-dev-env.ps1 -Update` or `-Install` to populate repo-local `bin` with `ReShade32.dll` and `ReShade64.dll` when they are available from the machine's ReShade install. Then use `scripts/setup-reshade.ps1` against the resolved game binary folder before linking addons. If a mod folder already has metadata, prefer `scripts/setup-reshade.ps1 -Mod {mod}` so the script can infer the Steam install and loader defaults from `metadata.json`.

The script currently does useful development setup tasks:

- creates the loader DLL, default `dxgi.dll`, as a symlink to repo-local `bin\ReShade64.dll`/`bin\ReShade32.dll` when available, falling back to `%ProgramData%\ReShade`; - copies `%ProgramData%\ReShade\ReShade.ini` into the game folder when `ReShade.ini` is missing; - updates `EffectSearchPaths` and `TextureSearchPaths` in `ReShade.ini` for the game folder and common ReShade shader folders. - writes `[renodx-dev] ToolsPath` to the repo `bin` folder and `[renodx-dev] LivePath` to `src/games/{mod}` when `-Mod` resolves an existing mod folder, otherwise to the game folder's `renodx-dev\live` path. This avoids starting DevKit with no tools directory configured.

If setup reports that ReShade DLLs or `%ProgramData%\ReShade\ReShade.ini` are missing, install/configure ReShade first, rerun `scripts/setup-dev-env.ps1 -Update`, then rerun the game-folder setup. Do not fabricate a loader path.

Treat these as script limitations unless the user asks to change it:

- it defaults to `-Arch x64` and `-LoaderName dxgi.dll`; - it leaves an existing non-symlink `dxgi.dll` untouched and reports the conflict.

For a 32-bit game, call the script with `-Arch x86`. For a non-`dxgi.dll` loader or a game that needs `deploy.reshade_preferred_name`, pass `-LoaderName` explicitly and still report any existing non-symlink conflict.

Pass `-LivePath <path>` when the DevKit l

--- name: setup-game-mod-dev description: "RenoDX workflow for setting up or resuming game mod development with Clang debug builds, DevKit, MCP bridge, ReShade game-folder links, live shader paths, per-game addon scaffolds, metadata, shader dump/decompile baselines, and verification. Use when starting a new src/games/{game} mod, continuing game-specific addon work, configuring DevKit for a game, or turning DevKit findings into a real mod." argument-hint: "game title/folder, install path, graphics API, and fresh vs continuing" ---

# Setup Game Mod Development

Set up **RenoDX mod development for a specific game**. Cover the local toolchain, DevKit/MCP inspection, game-folder ReShade/addon links, and the initial or continued `src/games/{game}` workflow.

Focus on the **development environment and mod scaffold**. For swapchain/resource tracing, HDR source proof, resource upgrades, or rejecting final-SDR inverse-tonemap approaches, use `swapchain-resource-analysis`. For shader-side tonemap/LUT math after the target pass is known, use `handle-sdr-tonemap-lut`.

## Related skills and scope

| Need | Use | |---|---| | Create/resume a game folder, build targets, link ReShade/addons, configure DevKit paths | This skill | | Trace final output, resource formats, swapchain proxy, `SwapChainPass`, SDR/HDR output toggle, or HDR source proof | `swapchain-resource-analysis` | | Edit the proven game shader for RenoDRT/PsychoV/LUT bridge math | `handle-sdr-tonemap-lut` |

Keep this skill focused on getting the mod development environment and baseline workflow ready. Record enough facts for handoff, but do not duplicate the specialized swapchain/resource or shader-math workflows.

## Boundaries

- Keep changes local to one `src/games/{game}` folder unless cross-mod work is explicitly requested. - Do not change global CMake presets, CI workflows, vendored dependencies, or external submodules. - New mods start from `src/games/generic`. - Use the CMake target named after the mod folder; the output artifact is `renodx-{mod}.addon64` or `.addon32`. - Use the `devkit` and `mcp_bridge` targets for local inspection; their debug outputs are `renodx-devkit.addon64` and `renodx-mcp-bridge.exe`. - Prefer Clang CMake presets for real development builds. Use VS Code CMake build integration when available, but select the `clang-*` configure/build presets. Treat `ninja-*` and `vs-*` presets as workflow testing paths only, not normal mod development paths. - Do not build a game addon while that game is running with the addon loaded; the DLL can be locked. - Do not put dumped `.cso` files in `src/games/{game}`. They can shadow editable HLSL during live shader loading.

## Required setup facts

Collect or infer these before editing files or changing a game folder:

| Fact | Notes | |---|---| | Work mode | `continue` if `src/games/{game}` exists or the user says resume; `fresh` otherwise. | | Mod folder id | Lowercase folder name under `src/games`, usually no spaces. | | Game title | Human-readable metadata title. | | Game binary folder | The folder where ReShade and `.addon64`/`.addon32` files must load from. Infer from metadata when possible, but verify because it may be a subfolder such as `...\Binaries\Win64`. | | Executable/process | `game_exe` or `process_name` for metadata and runtime checks. | | Graphics API | Usually `d3d11`, `d3d12`, or `vulkan`; affects loader DLL naming and shader targets. | | Architecture | Usually `x64`; use `.addon32` only for 32-bit games. | | Swapchain/output state | Optional early fact: known swapchain format/color space, especially RGBA8U/UNORM bottlenecks or existing HDR/scRGB/PQ paths. | | Proxy/resource need | Optional early fact: whether evidence suggests a RGBA16F proxy, resource upgrade, `SwapChainPass` output shader, or output preset cbuffer is needed before shader-side tonemap work. | | Store ids | Steam/GOG/Microsoft/Nexus ids if known. | | Loader name | Default is often `dxgi.dll`; honor `deploy.reshade_preferred_name` or game-specific requirements. | | ReShade state | Whether the game folder already has a ReShade loader DLL, `ReShade.ini`, and `ReShade.log`. |

Before asking for missing facts, read `src/games/{mod}/metadata.json` when it exists. Use `deploy.steam_appid`, `deploy.game_exe`, `deploy.process_name`, `deploy.api`, `deploy.architecture`, `deploy.reshade_preferred_name`, and `deploy.detection.default_install_paths` to reduce guessing. If `steam_appid` is present, resolve the local Steam install by reading Steam `libraryfolders.vdf` and `appmanifest_{appid}.acf`, then use `game_exe`/`process_name` to locate the binary folder. Steam metadata alone usually resolves only the install root; still ask when executable metadata is missing, the game is not locally installed, or multiple executable matches make the injection folder ambiguous.

## Expected agent output

When invoked, produce or maintain these sections in the response or working notes:

1. **Setup facts** - game folder, install/binary folder, API, arch, and mode. 2. **Existing state** - mod folder files, metadata, registered shaders, current build artifacts, and relevant scratch/verification notes. 3. **Build plan** - exact Clang debug CMake targets (`devkit`, `mcp_bridge`, `{mod}`) and any game-shutdown requirement. 4. **Game-folder link plan** - ReShade bootstrap state, loader DLL, DevKit addon, and game addon symlink/copy targets; list conflicts instead of deleting unknown files. 5. **DevKit plan** - MCP connection, tools path, live shader path, snapshot, draw/resource/shader inspection steps, and any handoff needed for swapchain/resource proof. 6. **Baseline plan** - original capture, dump/decompile location, editable HLSL location, 1:1 live baseline validation. 7. **Verification checklist** - target built, files generated, addon loaded, shader replacement active, runtime output validated.

## Continue an existing mod

Use this path when `src/games/{mod}` already exists.

1. Inspect the existing folder: - `metadata.json` - `addon.cpp` - `shared.h` - existing shader replacements and includes - committed `README.md`, verification/dev notes, or repo memory if present 2. Treat the folder name as the build target unless CMake target listing proves otherwise. 3. Preserve existing shader registrations and settings unless the user asks to replace them. 4. Rebuild only the smallest relevant targets: - `devkit` and `mcp_bridge` if inspection tooling changed or is missing - `{mod}` for the game addon 5. Re-link only the game folder artifacts needed for this session: - ReShade loader DLL if missing or known-good symlink target changed - `renodx-devkit.addon64` or `.addon32` - `renodx-{mod}.addon64` or `.addon32` 6. Point DevKit live shaders at the existing mod folder only if it is clean of dumped binaries and unrelated scratch files. 7. Keep concise build/runtime checks in the agent response or existing committed mod docs when setup knowledge changes.

## Start a fresh mod

1. Create `src/games/{mod}` by copying the relevant files from `src/games/generic`. 2. Keep the first scaffold minimal: - `addon.cpp` - `shared.h` - `metadata.json` - shader files only after a real target shader is proven 3. Update exported addon text in `addon.cpp`: - `NAME` should identify RenoDX for the game. - `DESCRIPTION` should identify the game-specific module. 4. Create `metadata.json` with the schema, `id`, `title`, `status`, optional `summary`/`tags`, and `deploy` fields such as `game_exe`, `api`, `steam_appid`, and `architecture`. 5. Let the top-level CMake auto-discover the mod through `addon.cpp`; do not edit global CMake just to add a game folder. 6. Build the new mod target before adding shader complexity. 7. Add shader registrations only after DevKit identifies stable target shader hashes.

## Local toolchain and build setup

Clang debug is the default path for mod development builds.

| Architecture | Configure preset | Development build preset | |---|---|---| | x64 | `clang-x64` | `clang-x64-debug` | | x86 | `clang-x86` | `clang-x86-debug` |

When working on mods, assume debug build artifacts. Use release presets only for explicit packaging/deploy requests, not normal development or DevKit iteration. Do not use `ninja-*`, `vs-*`, or ad-hoc build folders for real mod development; reserve them for workflow testing or explicit user requests.

1. Ensure repo-local shader tools exist in `bin` when DevKit decompilation or DXC isolation is needed: - `dxc.exe` - `dxcompiler.dll` - `cmd_Decompiler.exe` - optional SPIR-V tools 2. If tools are missing, run the repo setup script from the repo root with install/update intent. 3. Build these targets for live inspection: - `devkit` - `mcp_bridge` 4. Build the game target named `{mod}`. 5. If a build fails because the output `.addon64`/`.addon32` is locked, stop the game and rebuild; do not work around it by renaming random artifacts.

## Game-folder ReShade and addon links

Use symlinks for local development when possible; copy only when symlinks are unavailable or the user asks for deploy-like behavior.

1. Resolve the **game binary folder** from metadata when possible. Prefer `deploy.detection.default_install_paths`, then Steam `deploy.steam_appid` via local `appmanifest_{appid}.acf`, then locate `deploy.game_exe`/`process_name` under that root. Do not assume the Steam install root is the injection folder. 2. Check for existing loader/addon files: - ReShade loader DLL, usually `dxgi.dll` - `ReShade.ini` - `renodx-devkit.addon64`/`.addon32` - `renodx-{mod}.addon64`/`.addon32` 3. If a target exists and is not a symlink or known build artifact, report it as a conflict or backup candidate instead of deleting it. 4. Use `scripts/setup-reshade.ps1` against the game binary folder when ReShade search paths or baseline `ReShade.ini` need setup. 5. Link the DevKit addon from the active build output. 6. Link the game addon from the active build output. 7. Launch the game and confirm `ReShade.log` shows both addons loaded.

### If the game folder has no ReShade yet

First use `scripts/setup-dev-env.ps1 -Update` or `-Install` to populate repo-local `bin` with `ReShade32.dll` and `ReShade64.dll` when they are available from the machine's ReShade install. Then use `scripts/setup-reshade.ps1` against the resolved game binary folder before linking addons. If a mod folder already has metadata, prefer `scripts/setup-reshade.ps1 -Mod {mod}` so the script can infer the Steam install and loader defaults from `metadata.json`.

The script currently does useful development setup tasks:

- creates the loader DLL, default `dxgi.dll`, as a symlink to repo-local `bin\ReShade64.dll`/`bin\ReShade32.dll` when available, falling back to `%ProgramData%\ReShade`; - copies `%ProgramData%\ReShade\ReShade.ini` into the game folder when `ReShade.ini` is missing; - updates `EffectSearchPaths` and `TextureSearchPaths` in `ReShade.ini` for the game folder and common ReShade shader folders. - writes `[renodx-dev] ToolsPath` to the repo `bin` folder and `[renodx-dev] LivePath` to `src/games/{mod}` when `-Mod` resolves an existing mod folder, otherwise to the game folder's `renodx-dev\live` path. This avoids starting DevKit with no tools directory configured.

If setup reports that ReShade DLLs or `%ProgramData%\ReShade\ReShade.ini` are missing, install/configure ReShade first, rerun `scripts/setup-dev-env.ps1 -Update`, then rerun the game-folder setup. Do not fabricate a loader path.

Treat these as script limitations unless the user asks to change it:

- it defaults to `-Arch x64` and `-LoaderName dxgi.dll`; - it leaves an existing non-symlink `dxgi.dll` untouched and reports the conflict.

For a 32-bit game, call the script with `-Arch x86`. For a non-`dxgi.dll` loader or a game that needs `deploy.reshade_preferred_name`, pass `-LoaderName` explicitly and still report any existing non-symlink conflict.

Pass `-LivePath <path>` when the DevKit l

--- name: setup-game-mod-dev description: "RenoDX workflow for setting up or resuming game mod development with Clang debug builds, DevKit, MCP bridge, ReShade game-folder links, live shader paths, per-game addon scaffolds, metadata, shader dump/decompile baselines, and verification. Use when starting a new src/games/{game} mod, continuing game-specific addon work, configuring DevKit for a game, or turning DevKit findings into a real mod." argument-hint: "game title/folder, install path, graphics API, and fresh vs continuing" ---

# Setup Game Mod Development

Set up **RenoDX mod development for a specific game**. Cover the local toolchain, DevKit/MCP inspection, game-folder ReShade/addon links, and the initial or continued `src/games/{game}` workflow.

Focus on the **development environment and mod scaffold**. For swapchain/resource tracing, HDR source proof, resource upgrades, or rejecting final-SDR inverse-tonemap approaches, use `swapchain-resource-analysis`. For shader-side tonemap/LUT math after the target pass is known, use `handle-sdr-tonemap-lut`.

## Related skills and scope

| Need | Use | |---|---| | Create/resume a game folder, build targets, link ReShade/addons, configure DevKit paths | This skill | | Trace final output, resource formats, swapchain proxy, `SwapChainPass`, SDR/HDR output toggle, or HDR source proof | `swapchain-resource-analysis` | | Edit the proven game shader for RenoDRT/PsychoV/LUT bridge math | `handle-sdr-tonemap-lut` |

Keep this skill focused on getting the mod development environment and baseline workflow ready. Record enough facts for handoff, but do not duplicate the specialized swapchain/resource or shader-math workflows.

## Boundaries

- Keep changes local to one `src/games/{game}` folder unless cross-mod work is explicitly requested. - Do not change global CMake presets, CI workflows, vendored dependencies, or external submodules. - New mods start from `src/games/generic`. - Use the CMake target named after the mod folder; the output artifact is `renodx-{mod}.addon64` or `.addon32`. - Use the `devkit` and `mcp_bridge` targets for local inspection; their debug outputs are `renodx-devkit.addon64` and `renodx-mcp-bridge.exe`. - Prefer Clang CMake presets for real development builds. Use VS Code CMake build integration when available, but select the `clang-*` configure/build presets. Treat `ninja-*` and `vs-*` presets as workflow testing paths only, not normal mod development paths. - Do not build a game addon while that game is running with the addon loaded; the DLL can be locked. - Do not put dumped `.cso` files in `src/games/{game}`. They can shadow editable HLSL during live shader loading.

## Required setup facts

Collect or infer these before editing files or changing a game folder:

| Fact | Notes | |---|---| | Work mode | `continue` if `src/games/{game}` exists or the user says resume; `fresh` otherwise. | | Mod folder id | Lowercase folder name under `src/games`, usually no spaces. | | Game title | Human-readable metadata title. | | Game binary folder | The folder where ReShade and `.addon64`/`.addon32` files must load from. Infer from metadata when possible, but verify because it may be a subfolder such as `...\Binaries\Win64`. | | Executable/process | `game_exe` or `process_name` for metadata and runtime checks. | | Graphics API | Usually `d3d11`, `d3d12`, or `vulkan`; affects loader DLL naming and shader targets. | | Architecture | Usually `x64`; use `.addon32` only for 32-bit games. | | Swapchain/output state | Optional early fact: known swapchain format/color space, especially RGBA8U/UNORM bottlenecks or existing HDR/scRGB/PQ paths. | | Proxy/resource need | Optional early fact: whether evidence suggests a RGBA16F proxy, resource upgrade, `SwapChainPass` output shader, or output preset cbuffer is needed before shader-side tonemap work. | | Store ids | Steam/GOG/Microsoft/Nexus ids if known. | | Loader name | Default is often `dxgi.dll`; honor `deploy.reshade_preferred_name` or game-specific requirements. | | ReShade state | Whether the game folder already has a ReShade loader DLL, `ReShade.ini`, and `ReShade.log`. |

Before asking for missing facts, read `src/games/{mod}/metadata.json` when it exists. Use `deploy.steam_appid`, `deploy.game_exe`, `deploy.process_name`, `deploy.api`, `deploy.architecture`, `deploy.reshade_preferred_name`, and `deploy.detection.default_install_paths` to reduce guessing. If `steam_appid` is present, resolve the local Steam install by reading Steam `libraryfolders.vdf` and `appmanifest_{appid}.acf`, then use `game_exe`/`process_name` to locate the binary folder. Steam metadata alone usually resolves only the install root; still ask when executable metadata is missing, the game is not locally installed, or multiple executable matches make the injection folder ambiguous.

## Expected agent output

When invoked, produce or maintain these sections in the response or working notes:

1. **Setup facts** - game folder, install/binary folder, API, arch, and mode. 2. **Existing state** - mod folder files, metadata, registered shaders, current build artifacts, and relevant scratch/verification notes. 3. **Build plan** - exact Clang debug CMake targets (`devkit`, `mcp_bridge`, `{mod}`) and any game-shutdown requirement. 4. **Game-folder link plan** - ReShade bootstrap state, loader DLL, DevKit addon, and game addon symlink/copy targets; list conflicts instead of deleting unknown files. 5. **DevKit plan** - MCP connection, tools path, live shader path, snapshot, draw/resource/shader inspection steps, and any handoff needed for swapchain/resource proof. 6. **Baseline plan** - original capture, dump/decompile location, editable HLSL location, 1:1 live baseline validation. 7. **Verification checklist** - target built, files generated, addon loaded, shader replacement active, runtime output validated.

## Continue an existing mod

Use this path when `src/games/{mod}` already exists.

1. Inspect the existing folder: - `metadata.json` - `addon.cpp` - `shared.h` - existing shader replacements and includes - committed `README.md`, verification/dev notes, or repo memory if present 2. Treat the folder name as the build target unless CMake target listing proves otherwise. 3. Preserve existing shader registrations and settings unless the user asks to replace them. 4. Rebuild only the smallest relevant targets: - `devkit` and `mcp_bridge` if inspection tooling changed or is missing - `{mod}` for the game addon 5. Re-link only the game folder artifacts needed for this session: - ReShade loader DLL if missing or known-good symlink target changed - `renodx-devkit.addon64` or `.addon32` - `renodx-{mod}.addon64` or `.addon32` 6. Point DevKit live shaders at the existing mod folder only if it is clean of dumped binaries and unrelated scratch files. 7. Keep concise build/runtime checks in the agent response or existing committed mod docs when setup knowledge changes.

## Start a fresh mod

1. Create `src/games/{mod}` by copying the relevant files from `src/games/generic`. 2. Keep the first scaffold minimal: - `addon.cpp` - `shared.h` - `metadata.json` - shader files only after a real target shader is proven 3. Update exported addon text in `addon.cpp`: - `NAME` should identify RenoDX for the game. - `DESCRIPTION` should identify the game-specific module. 4. Create `metadata.json` with the schema, `id`, `title`, `status`, optional `summary`/`tags`, and `deploy` fields such as `game_exe`, `api`, `steam_appid`, and `architecture`. 5. Let the top-level CMake auto-discover the mod through `addon.cpp`; do not edit global CMake just to add a game folder. 6. Build the new mod target before adding shader complexity. 7. Add shader registrations only after DevKit identifies stable target shader hashes.

## Local toolchain and build setup

Clang debug is the default path for mod development builds.

| Architecture | Configure preset | Development build preset | |---|---|---| | x64 | `clang-x64` | `clang-x64-debug` | | x86 | `clang-x86` | `clang-x86-debug` |

When working on mods, assume debug build artifacts. Use release presets only for explicit packaging/deploy requests, not normal development or DevKit iteration. Do not use `ninja-*`, `vs-*`, or ad-hoc build folders for real mod development; reserve them for workflow testing or explicit user requests.

1. Ensure repo-local shader tools exist in `bin` when DevKit decompilation or DXC isolation is needed: - `dxc.exe` - `dxcompiler.dll` - `cmd_Decompiler.exe` - optional SPIR-V tools 2. If tools are missing, run the repo setup script from the repo root with install/update intent. 3. Build these targets for live inspection: - `devkit` - `mcp_bridge` 4. Build the game target named `{mod}`. 5. If a build fails because the output `.addon64`/`.addon32` is locked, stop the game and rebuild; do not work around it by renaming random artifacts.

## Game-folder ReShade and addon links

Use symlinks for local development when possible; copy only when symlinks are unavailable or the user asks for deploy-like behavior.

1. Resolve the **game binary folder** from metadata when possible. Prefer `deploy.detection.default_install_paths`, then Steam `deploy.steam_appid` via local `appmanifest_{appid}.acf`, then locate `deploy.game_exe`/`process_name` under that root. Do not assume the Steam install root is the injection folder. 2. Check for existing loader/addon files: - ReShade loader DLL, usually `dxgi.dll` - `ReShade.ini` - `renodx-devkit.addon64`/`.addon32` - `renodx-{mod}.addon64`/`.addon32` 3. If a target exists and is not a symlink or known build artifact, report it as a conflict or backup candidate instead of deleting it. 4. Use `scripts/setup-reshade.ps1` against the game binary folder when ReShade search paths or baseline `ReShade.ini` need setup. 5. Link the DevKit addon from the active build output. 6. Link the game addon from the active build output. 7. Launch the game and confirm `ReShade.log` shows both addons loaded.

### If the game folder has no ReShade yet

First use `scripts/setup-dev-env.ps1 -Update` or `-Install` to populate repo-local `bin` with `ReShade32.dll` and `ReShade64.dll` when they are available from the machine's ReShade install. Then use `scripts/setup-reshade.ps1` against the resolved game binary folder before linking addons. If a mod folder already has metadata, prefer `scripts/setup-reshade.ps1 -Mod {mod}` so the script can infer the Steam install and loader defaults from `metadata.json`.

The script currently does useful development setup tasks:

- creates the loader DLL, default `dxgi.dll`, as a symlink to repo-local `bin\ReShade64.dll`/`bin\ReShade32.dll` when available, falling back to `%ProgramData%\ReShade`; - copies `%ProgramData%\ReShade\ReShade.ini` into the game folder when `ReShade.ini` is missing; - updates `EffectSearchPaths` and `TextureSearchPaths` in `ReShade.ini` for the game folder and common ReShade shader folders. - writes `[renodx-dev] ToolsPath` to the repo `bin` folder and `[renodx-dev] LivePath` to `src/games/{mod}` when `-Mod` resolves an existing mod folder, otherwise to the game folder's `renodx-dev\live` path. This avoids starting DevKit with no tools directory configured.

If setup reports that ReShade DLLs or `%ProgramData%\ReShade\ReShade.ini` are missing, install/configure ReShade first, rerun `scripts/setup-dev-env.ps1 -Update`, then rerun the game-folder setup. Do not fabricate a loader path.

Treat these as script limitations unless the user asks to change it:

- it defaults to `-Arch x64` and `-LoaderName dxgi.dll`; - it leaves an existing non-symlink `dxgi.dll` untouched and reports the conflict.

For a 32-bit game, call the script with `-Arch x86`. For a non-`dxgi.dll` loader or a game that needs `deploy.reshade_preferred_name`, pass `-LoaderName` explicitly and still report any existing non-symlink conflict.

Pass `-LivePath <path>` when the DevKit l