Filoppi/Luma-Framework
GitHub: Filoppi/Luma-Framework
Luma-Framework 是一个基于 ReShade 插件系统的 DirectX 11 游戏画质模组框架，解决了为老旧 PC 游戏添加 HDR、DLSS 等高级渲染功能的可扩展性问题。
Stars: 350 | Forks: 21
Luma 是一个用于改善 DirectX 11 游戏画质的模组框架。
它利用 ReShade 插件系统，通过 DirectX 钩子添加或修改渲染通道（并替换着色器，例如后处理）。
虽然大部分通用着色器代码专注于 HDR 输出支持，但已经包含更多功能（比如 DLSS 支持），并且其功能没有上限。
许多游戏已内置在代码中，包括一个模板项目，添加新游戏相对容易。
Luma 还可以作为图形分析器，具备深度调试能力（捕获所有绘制/调度命令和状态变更，例如 SRVs/RTVs/UAVs/DSV/CBs 等），下载图形分析器即可在任何 DX11 游戏中使用。
# 开发要求
- Windows 11（Windows 10 应该也能正常运行）
- Visual Studio 2026（2022 可用，旧版本也可能支持）
- Windows 11 SDK 10.0.26100.0（旧版本可用，但对 HDR 支持不佳）
# 使用说明
- （仅限 Prey，其他情况可选）如果尚未设置，请将 “VCPKG_ROOT” 环境变量指向你的 vcpkg 安装文件夹（可从 “https://github.com/microsoft/vcpkg” 下载，与 Visual Studio 集成的版本似乎不够稳定）。
- 在运行代码前安装最新的 VC++ 可再发行组件（https://aka.ms/vs/17/release/vc_redist.x64.exe），我们强制用户更新到最新版本，但可以定义 “_DISABLE_CONSTEXPR_MUTEX_CONSTRUCTOR” 来避免。
- 打开 “Luma.sln” 并构建。注意不要使用 “编辑并继续”（/ZI）构建设置，因为它们会破坏代码补丁生成（尤其是使用 DKUtil 的项目，如 Prey）。
- 代码热点位于 core.hpp 和每个游戏的 main.cpp 文件中。
- Luma 使用游戏项目进行开发和发布。仅需在 DEVELOPMENT、TEST 和 PUBLISHING 配置之间切换即可启用相应功能。它们会在下次加载/编译时自动应用到着色器。Debug、Development-Release 和 Development-Debug 构建都应包含调试符号（因此支持断点），但 “Debug” 构建会禁用优化并输出更多日志，因此速度极慢，仅在调试时需要使用（Visual Studio 可能默认选择此模式，请手动更改）。
# 添加新的游戏模组
- 将 “.\Templates\VisualStudio” 文件夹中的模板文件复制到（例如）"%USERPROFILE%\Documents\Visual Studio 18\Templates\ProjectTemplates\Visual C++"（或 VS 2022 对应的 “Visual Studio 2022”）。
- 在解决方案中添加新项目，并选择 Luma 模板项目，将其放置在 “.\Source\Games” 下。可以使用完整的游戏名称（包括空格等）命名项目。你可以手动查看 Luma 解决方案中已有的模板项目以获取更多信息。
- 检查新创建的 main.cpp 文件并按需替换内容，所有说明都在其中。参考其他游戏的模组获取更多灵感。
- 每个模组的版本存储在 “Globals::VERSION” 中，可以在此处递增。
- 32 位（Win32/x86）游戏也兼容，例如 “BioShock 2”，请确保选择正确的平台。
- 添加一个名为 “LUMA_GAME_NAME_BIN_PATH” 的环境变量（例如 “LUMA_BIOSHOCK_2_BIN_PATH”），并将其指向游戏可执行文件所在文件夹（即 ReShade 放置的位置）。在项目设置的生成后事件页面中设置，将二进制文件复制到该文件夹（模板中已包含 “LUMA_TEMPLATE_BIN_PATH”）。
- 在项目设置的调试页面中，将 “Command” 设置为游戏可执行文件路径（例如 “$(LUMA_PREY_BIN_PATH)\Prey.exe”，不含引号），以便调试时自动启动并附加（注意：部分有 DRM 的游戏可能无法正常工作）。
- 在游戏目录中安装 ReShade 6.6.0+（或通常的最新版本）。
- 构建项目并运行调试模式，它应会自动启动游戏并加载模组。
# 着色器开发
- 模组会在开发构建中自动转储游戏的着色器。
- Luma 着色器位于 “.\Shaders\GameName”（从仓库根目录开始）。开发构建中转储的着色器会保存在此处，手绘着色器也应放在此文件夹（通用着色器除外，应放在通用文件夹）。
- 着色器通过（cso/二进制）哈希值保存和替换。
- 建议使用 VSCode 编辑着色器。
- 在发布和测试构建中，着色器将从 “.\Luma\GameName” 文件夹加载（相对于游戏可执行文件所在位置，即插件所在目录）。
# 发布
GitHub Actions 会自动构建所有游戏项目，并将其与各自的着色器（Luma 文件夹）一起打包。
模组准备完成后，请向原始仓库提交 PR。
在最终打包前，请务必在 “Publishing” 模式下测试模组，因为着色器和 C++ 代码可能会根据配置发生变化。
# 与 RenoDX 的比较
Luma 与 RenoDX（https://github.com/clshortfuse/renodx）类似，灵感部分来源于此，但 Luma 更专注于深度模组游戏，例如添加和替换完整的渲染技术、添加 DLSS 或宽屏支持等。两者之间的简单模组移植相对容易。
# 与 Starfield 和 Kingdom Come Deliverance Luma 模组的关系
Luma 框架源自我最初为 Prey（Luma）编写的模组代码。随后我意识到可以将其通用化，并在其他游戏中复用许多功能。
Starfield 和 Kingdom Come Deliverance 的 Luma 模组并非基于 Luma（通用）框架，因此不应将其混淆。它们确实共享部分作者和代码特性（例如 HDR 相关功能），但它们是独立的实体。
# 为何选择 ReShade？
如果不使用 ReShade 和游戏特定代码钩子，仅通过通用 DirectX 钩子实现相同功能会更加复杂（即使性能更高）（某些引擎会复用渲染目标纹理用于不同目的，因此难以判断哪些需要升级，而 ReShade 提供了设置序列化和许多其他功能）。
# 开发要求
- Windows 11（Windows 10 应该也能正常运行）
- Visual Studio 2026（2022 可用，旧版本也可能支持）
- Windows 11 SDK 10.0.26100.0（旧版本可用，但对 HDR 支持不佳）
# 使用说明
- （仅限 Prey，其他情况可选）如果尚未设置，请将 “VCPKG_ROOT” 环境变量指向你的 vcpkg 安装文件夹（可从 “https://github.com/microsoft/vcpkg” 下载，与 Visual Studio 集成的版本似乎不够稳定）。
- 在运行代码前安装最新的 VC++ 可再发行组件（https://aka.ms/vs/17/release/vc_redist.x64.exe），我们强制用户更新到最新版本，但可以定义 “_DISABLE_CONSTEXPR_MUTEX_CONSTRUCTOR” 来避免。
- 打开 “Luma.sln” 并构建。注意不要使用 “编辑并继续”（/ZI）构建设置，因为它们会破坏代码补丁生成（尤其是使用 DKUtil 的项目，如 Prey）。
- 代码热点位于 core.hpp 和每个游戏的 main.cpp 文件中。
- Luma 使用游戏项目进行开发和发布。仅需在 DEVELOPMENT、TEST 和 PUBLISHING 配置之间切换即可启用相应功能。它们会在下次加载/编译时自动应用到着色器。Debug、Development-Release 和 Development-Debug 构建都应包含调试符号（因此支持断点），但 “Debug” 构建会禁用优化并输出更多日志，因此速度极慢，仅在调试时需要使用（Visual Studio 可能默认选择此模式，请手动更改）。
# 添加新的游戏模组
- 将 “.\Templates\VisualStudio” 文件夹中的模板文件复制到（例如）"%USERPROFILE%\Documents\Visual Studio 18\Templates\ProjectTemplates\Visual C++"（或 VS 2022 对应的 “Visual Studio 2022”）。
- 在解决方案中添加新项目，并选择 Luma 模板项目，将其放置在 “.\Source\Games” 下。可以使用完整的游戏名称（包括空格等）命名项目。你可以手动查看 Luma 解决方案中已有的模板项目以获取更多信息。
- 检查新创建的 main.cpp 文件并按需替换内容，所有说明都在其中。参考其他游戏的模组获取更多灵感。
- 每个模组的版本存储在 “Globals::VERSION” 中，可以在此处递增。
- 32 位（Win32/x86）游戏也兼容，例如 “BioShock 2”，请确保选择正确的平台。
- 添加一个名为 “LUMA_GAME_NAME_BIN_PATH” 的环境变量（例如 “LUMA_BIOSHOCK_2_BIN_PATH”），并将其指向游戏可执行文件所在文件夹（即 ReShade 放置的位置）。在项目设置的生成后事件页面中设置，将二进制文件复制到该文件夹（模板中已包含 “LUMA_TEMPLATE_BIN_PATH”）。
- 在项目设置的调试页面中，将 “Command” 设置为游戏可执行文件路径（例如 “$(LUMA_PREY_BIN_PATH)\Prey.exe”，不含引号），以便调试时自动启动并附加（注意：部分有 DRM 的游戏可能无法正常工作）。
- 在游戏目录中安装 ReShade 6.6.0+（或通常的最新版本）。
- 构建项目并运行调试模式，它应会自动启动游戏并加载模组。
# 着色器开发
- 模组会在开发构建中自动转储游戏的着色器。
- Luma 着色器位于 “.\Shaders\GameName”（从仓库根目录开始）。开发构建中转储的着色器会保存在此处，手绘着色器也应放在此文件夹（通用着色器除外，应放在通用文件夹）。
- 着色器通过（cso/二进制）哈希值保存和替换。
- 建议使用 VSCode 编辑着色器。
- 在发布和测试构建中，着色器将从 “.\Luma\GameName” 文件夹加载（相对于游戏可执行文件所在位置，即插件所在目录）。
# 发布
GitHub Actions 会自动构建所有游戏项目，并将其与各自的着色器（Luma 文件夹）一起打包。
模组准备完成后，请向原始仓库提交 PR。
在最终打包前，请务必在 “Publishing” 模式下测试模组，因为着色器和 C++ 代码可能会根据配置发生变化。
# 与 RenoDX 的比较
Luma 与 RenoDX（https://github.com/clshortfuse/renodx）类似，灵感部分来源于此，但 Luma 更专注于深度模组游戏，例如添加和替换完整的渲染技术、添加 DLSS 或宽屏支持等。两者之间的简单模组移植相对容易。
# 与 Starfield 和 Kingdom Come Deliverance Luma 模组的关系
Luma 框架源自我最初为 Prey（Luma）编写的模组代码。随后我意识到可以将其通用化，并在其他游戏中复用许多功能。
Starfield 和 Kingdom Come Deliverance 的 Luma 模组并非基于 Luma（通用）框架，因此不应将其混淆。它们确实共享部分作者和代码特性（例如 HDR 相关功能），但它们是独立的实体。
# 为何选择 ReShade？
如果不使用 ReShade 和游戏特定代码钩子，仅通过通用 DirectX 钩子实现相同功能会更加复杂（即使性能更高）（某些引擎会复用渲染目标纹理用于不同目的，因此难以判断哪些需要升级，而 ReShade 提供了设置序列化和许多其他功能）。标签：DirectX 11, DirectX 钩子, DLSS, Draw/Dispatch 捕获, DX11, HDR, Luma Framework, Mod 框架, Prey 2017, ReShade Addon, SRV RTV UAV DSV CB, VCPKG, Visual Studio 2022, Windows 11, 后处理渲染, 图形分析, 图形分析器, 客户端加密, 开源模改, 显卡增强, 渲染管线修改, 游戏图形增强, 游戏开发, 游戏性能优化, 游戏模组, 游戏模组框架, 游戏渲染优化, 着色器修改