{"url":"https://levimc.org/mods/github.com/honeymirror/RenderDragonShaderLoader/","id":"github.com/honeymirror/RenderDragonShaderLoader","name":"RenderDragonShaderLoader","description":"Shader pack manager & custom shader settings UI for Minecraft Bedrock (RenderDragon) on LeviLamina","owner":"honeymirror","logo":"https://levimc.org/mods/icons/7e37170416540efa-288.webp","repository":"https://github.com/honeymirror/RenderDragonShaderLoader","issues":"https://github.com/honeymirror/RenderDragonShaderLoader/issues","releases":"https://github.com/honeymirror/RenderDragonShaderLoader/releases","stars":8,"downloads":497,"updated":"2026-10-21T08:53:55Z","published":"2026-10-20T07:29:02Z","created":"2026-10-20T07:24:55Z","license":"LGPL-3.0","side":["client"],"platform":["win-x64"],"gameVersions":["1.26.51","1.26.40"],"tags":["platform:levilamina","type:mod"],"latest":{"variant":"client","version":"0.2.1","install":"lip install github.com/honeymirror/RenderDragonShaderLoader#client@0.2.1"},"readmes":[{"file":"README.md","lang":"zh-Hans","text":"# RenderDragonShaderLoader\n\n[English](README_EN.md) | 简体中文\n\n在 Minecraft Bedrock（RenderDragon 渲染管线）里**管理第三方光影包**、**热重载**、\n并用 Iris 风格的界面调整光影自定义参数的 **LeviLamina 客户端模组**。\n\n> 目标版本：**Minecraft Bedrock 1.26.51**（客户端）+ **LeviLamina 26.51.7**（Windows x64）\n> （材质格式：原版 v26，编译产物也写 v26；读取时兼容 v25 的旧包/旧缓存）\n>\n> 运行依赖：**Python 3.10 或更高版本**（推荐 Python 3.12+）\n>\n> 当前发布：**0.2.1**（兼容报告与加载分离；修复无灵动视效设备上的 Forward 光影加载）\n>\n> 导入格式：`shaderpacks/` 目录里按 `.zip` 读取；把 `.mcpack` 拖进游戏窗口时会\n> **自动改名成 `.zip`** 再导入（`.mcpack` 本身就是一个 zip 容器）。\n\n## Python 运行环境\n\n当前版本会使用随模组分发的 Python 脚本进行光影编译和 Native IO 兼容性校验，因此运行前\n必须安装 **Python 3.10+**：\n\n1. 从 [python.org](https://www.python.org/downloads/windows/) 安装 Python 3。\n2. 安装时勾选 **Python Launcher** 和 **Add Python to PATH**。\n3. 完全退出游戏后，在 PowerShell 或命令提示符中运行：\n\n   ```powershell\n   py -3 --version\n   py -3 -m pip install -r toolchain/requirements.txt\n   ```\n\n   第一条命令应正常显示 Python 版本；第二条会安装兼容校验和编译所需的\n   `pyjson5`、`pycryptodome` 等依赖。\n\n4. 两条命令都成功后再启动游戏。\n\n如果系统只有 `python.exe`、没有 `py.exe`，可以编辑模组目录下的\n`config/config.json`，把以下两个命令改成 `python.exe` 的完整路径：\n\n```json\n\"lazuriteCommand\": \"\\\"C:\\\\Python路径\\\\python.exe\\\" toolchain/lazurite_albite.py\",\n\"lazuriteAlbiteCommand\": \"\\\"C:\\\\Python路径\\\\python.exe\\\" toolchain/lazurite_albite.py\",\n```\n\n路径必须替换为本机实际的 `python.exe` 位置，并使用双引号包裹。修改后需要完全重启游戏。\n\n## 现在能做什么\n\n### 面板与操作\n\n- 默认按 `G` 打开或关闭光影管理面板。\n- 在聊天栏、告示牌、铁砧改名、书、命令方块这些**要打字的界面里，面板热键会让路**：\n  敲到绑定的键只会打进输入框，不会弹出面板、也不会被吞掉。\n- 面板内可用鼠标浏览光影列表、拖动滚动条，也可把 `.zip` / `.mcpack` 光影包直接拖进游戏窗口完成导入。\n- 点击「应用 / 完成」后才会真正启用光影；点击「取消」或按 `Esc` 会丢弃本次未应用的改动。\n- 底栏左侧的「设置」按钮打开模组设置页：**改面板热键**（按一个键直接录制）、强制开启灵动视效、\n  启动时自动加载上次用的光影、手动覆盖图形模式。\n- 方向键可以在内容区、底栏两排按钮、右上角「导入 / 导出 / 重置」与右下角「全透明」之间移动，\n  回车等于鼠标左键。\n\n### 光影包识别与导入\n\n- 光影包目录是模组目录下的 `data/shaderpacks/`。\n- 通过窗口拖放或导入功能同时接受 `.zip` 和 `.mcpack`；`.mcpack` 会先改名为 `.zip` 再读取。\n- `.zip` 会被自动解压到 `data/generated/<包名>/src/` 作为工作副本。\n- 已解压的光影目录也可以手工放进 `data/shaderpacks/`，但目录内必须包含 `project.json` 或\n  `shaders.properties` 才会计入光影列表。\n- 光影包可以自带 `.material.bin` 直接加载，也可以包含源码由模组编译；缺少产物且有可编译源码时会进入编译流程。\n\n### 光影列表与参数界面\n\n- 列表会显示完整包名，滚轮只负责滚动，不会因为滚动而改变当前选中项。\n- 启用光影时会根据产物类型自动切换图形模式：延迟产物使用「灵动视效」，前向产物使用「花式」。\n  （判定方式是产物文件名里有没有 `Deferred*`，属于启发式；设置页里的「图形模式覆盖」可以手动纠正。）\n- 关掉面板 / 退出游戏前用的光影会被记住，下次启动自动挂回去（可在设置页里关掉）。\n- 兼容性预检与光影加载相互独立：点击左上角「i」可对当前选中的光影做 Native IO\n  预检；即使结果显示“不兼容（仍可加载）”，应用光影也不会被阻止。\n- 自定义参数界面采用 Iris 风格：分类页和参数页两层结构，支持两列并排和整行两种版式。\n- 参数控件包含滑块、复选框、枚举和颜色；滑块悬停后会展开，滑标可以拖动。\n- 参数来自光影包自己的 `options.json` 或 `shaders.properties`；光影包没有可识别声明时会显示空状态。\n- 参数声明、源码接入、分类、中文名称和运行时 uniform 的完整写法见\n  [`CUSTOM-PARAMETERS.md`](CUSTOM-PARAMETERS.md)。\n- 顶栏提供「导入 / 导出 / 重置」，状态提示会在 3 秒后淡出，并带有 Iris 同款点击音效。\n\n### `/shader` 指令\n\n| 指令 | 作用 |\n| --- | --- |\n| `/shader scan` | 重新扫描 `data/shaderpacks/`，刷新光影包列表。 |\n| `/shader ui` | 直接打开或关闭光影管理面板，不依赖快捷键。 |\n| `/shader key` | 查看当前打开面板所使用的快捷键。 |\n| `/shader key <键名>` | 修改打开面板的快捷键。支持 `A-Z`、`0-9`、`F1-F12`、`SPACE`、`TAB`、`UP` 等名称；`NONE` 表示关闭快捷键。 |\n| `/shader vibrant` | 查看「强制开启灵动视效」的状态。 |\n| `/shader vibrant <on\\|off>` | 打开/关闭强制开启灵动视效（有些服务器会把图形模式锁死，这个开关会绕过判定）。 |\n| `/shader list` | 在聊天栏列出已识别的光影包，以及每个包解析到的参数数量。 |\n| `/shader rollback` | 关闭材质重定向并回退到原版材质。只有可用的热重载环境才会执行成功。 |\n\n## 编译与产物\n\n- 编译默认开启：调用 `lazurite build` + 随模组分发的 `toolchain/shaderc.exe`，串行任务队列，\n  支持取消、超时和日志。\n- 参数改动触发材质级增量编译；缓存命中时不启动编译器进程。\n- 产物先写到 `compiled.new/`，校验 magic / 目标格式版本 26 / 数量与 `meta.json` 一致后，\n  再原子切换到 `compiled/`；旧产物保存到 `compiled/.backup/`。\n- 包可以只带预编译 `.material.bin`，也可以带源码让模组编译。编译后由材质热重载挂回游戏。\n- 支持 `rdloader.pack.json` / `options.json` / `variants.json` / 包内 `lang/*.lang`，\n  并保留普通 `.zip`、`.mcpack` 和 `shaders.properties` 兼容通道。\n\n## 构建\n\n需要：Windows x64 + Python 3.10+ + xmake + Visual Studio（MSVC）+ LLVM（clang-cl）+\nLeviLamina 26.51.7 SDK。\n\n```bash\nxmake f -y -p windows -a x64 -m release --target_type=client --mods_dir=<游戏 mods 目录>\nxmake -y\n```\n\n产物是可直接安装的模组包：把 `bin/RenderDragonShaderLoader/` 整个拷进游戏的 `mods/` 目录即可\n；如果配置了 `--mods_dir`，构建结束会自动同步到 `mods/RenderDragonShaderLoader/`\n（快照保留在 `_backup/`，可用 `tools/sync_mod.ps1 -List/-Rollback` 管理）。\n\n## 目录结构\n\n```\nsrc/            模组源码（不依赖游戏类型，可离线编译/测试）\n  mod/          模组类、配置、注册（`/shader` 指令）\n  core/         光影包扫描与解析、参数模型、图形模式切换\n  hook/         材质热重载（readFile 重定向 + reloadMaterial）、窗口拖放导入\n  ui/           界面（UiScreen / UiSettings / UiLayout / UiCanvas）+ 游戏适配层\nlang/           文案（zh_CN / en_US）\nconfig/         首次安装的默认配置\nsamples/        示例光影包（ExamplePack）\n```\n\n## 第三方\n\n### 设计与兼容性参考\n\n- [Iris](https://github.com/IrisShaders/Iris)：参考其光影参数界面、参数分类方式、滑块交互和点击音效表现。\n- [OptiFine](https://optifine.net/)：参考其 `shaders.properties` 参数表达方式和 `shaderpacks` 目录约定。\n- [BetterRenderDragon](https://github.com/QYCottage/BetterRenderDragon)：参考材质热重载思路。\n- [Lamium](https://github.com/amatouhake/Lamium)：**本模组 UI 参考了该项目**，包括自绘屏幕和输入接管实现。\n\n以上项目未随本仓库分发第三方二进制或资源文件，仅作为设计与实现参考。\n\n### 编译工具链与随包分发\n\n- [Lazurite](https://github.com/veka0/lazurite)：LGPL-3.0，作为光影工程编译入口。\n- [lazurite-albite-compat](https://github.com/bambosan/lazurite-albite-compat)：LGPL-3.0，\n  兼容 albite 后端的 Lazurite 源码树，位于 `toolchain/lazurite-albite-compat/`。\n- [Albite](https://github.com/bambosan/albite)：MIT License，作为可选的材质编译后端。\n\n- 许可：本项目使用 LGPL-3.0，见 [`LICENSE`](LICENSE)。\n- 第三方项目、依赖与分发说明见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。\n"},{"file":"README_EN.md","lang":"en","text":"# RenderDragonShaderLoader\n\nEnglish | [简体中文](README.md)\n\nA **LeviLamina client mod** for Minecraft Bedrock (RenderDragon) that **manages third-party\nshader packs**, supports **hot reload**, and provides an Iris-style interface for adjusting\ncustom shader parameters.\n\n> Target versions: **Minecraft Bedrock 1.26.51** (client) + **LeviLamina 26.51.7** (Windows x64)\n>\n> Runtime dependency: **Python 3.10 or newer** (Python 3.12+ recommended)\n>\n> Current release: **0.2.1** (separates compatibility reports from loading and fixes Forward\n> shader loading on devices without Vibrant Visuals)\n>\n> Import format: `shaderpacks/` is read as `.zip`. Dropping a `.mcpack` onto the game window is\n> also supported: it is **renamed to `.zip` automatically** before importing (a `.mcpack` is a zip\n> container).\n\n## Python Runtime\n\nThe current release uses bundled Python scripts for shader compilation and Native IO compatibility\nvalidation. Install **Python 3.10+** before running the mod:\n\n1. Install Python 3 from [python.org](https://www.python.org/downloads/windows/).\n2. Enable **Python Launcher** and **Add Python to PATH** during installation.\n3. Fully exit the game, then run this command in PowerShell or Command Prompt:\n\n   ```powershell\n   py -3 --version\n   py -3 -m pip install -r toolchain/requirements.txt\n   ```\n\n   The first command must print a Python version. The second installs the\n   `pyjson5`, `pycryptodome`, and other runtime dependencies used by shader\n   compilation and Native IO validation.\n\n4. Start the game only after both commands succeed.\n\nIf the system only provides `python.exe` and does not have `py.exe`, edit\n`config/config.json` in the mod directory and replace both commands with the absolute path to\n`python.exe`:\n\n```json\n\"lazuriteCommand\": \"\\\"C:\\\\Python-Path\\\\python.exe\\\" toolchain/lazurite_albite.py\",\n\"lazuriteAlbiteCommand\": \"\\\"C:\\\\Python-Path\\\\python.exe\\\" toolchain/lazurite_albite.py\",\n```\n\nReplace the example path with the actual local `python.exe` path and keep the escaped quotes.\nFully restart the game after changing the file.\n\n## Current Features\n\n### Panel and Controls\n\n- Press `G` by default to open or close the shader management panel.\n- While typing in chat, a sign, an anvil, a book or a command block, the panel hotkey **steps\n  aside**: the key goes into the text box instead of opening the panel (and is not swallowed).\n- Browse the shader list with the mouse and drag the scrollbar. You can also drag a `.zip` shader\n  or `.mcpack` shader pack directly into the Minecraft window to import it.\n- Shader changes are applied only after clicking Apply / Done. Clicking Cancel or pressing `Esc`\n  discards the unapplied changes.\n- The Settings button at the bottom left opens the mod settings page: **rebind the panel hotkey**\n  (press a key to record it), force-enable Vibrant Visuals, auto-load the last used shader pack on\n  startup, and override the graphics mode manually.\n- The arrow keys move between the content area, the two rows of bottom buttons, the top bar\n  buttons (Import / Export / Reset) and the bottom-right transparency button; Enter acts as a left\n  click.\n\n### Shader Pack Recognition and Import\n\n- The shader pack directory is `data/shaderpacks/` under the mod directory.\n- When importing through drag and drop, `.zip` and `.mcpack` files are accepted. A dragged\n  `.mcpack` is stored as `<name>.zip`; a `.mcpack` placed in `data/shaderpacks/` manually is\n  renamed the same way when the directory is scanned.\n- `.zip` files are automatically extracted to `data/generated/<pack-name>/src/` as working copies.\n- An already extracted shader directory can also be placed manually in `data/shaderpacks/`, but it\n  must contain `project.json` or `shaders.properties` to be recognized.\n- Packs can load prebuilt `.material.bin` files directly or include source for the mod to compile.\n  A source pack without output enters the compilation pipeline automatically.\n\n### Shader List and Parameter Interface\n\n- The list shows full pack names. The mouse wheel only scrolls the list and does not change the\n  current selection.\n- The graphics mode is switched automatically based on the output type: deferred output uses\n  Vibrant Visuals, and forward output uses Fancy.\n  (The detection looks for `Deferred*` in the output file names, so it is a heuristic; the\n  \"Graphics mode override\" entry in the settings page lets the player correct it.)\n- The shader pack that was enabled when the panel was closed / the game exited is remembered and\n  loaded again on the next startup (can be turned off in the settings page).\n- Native IO compatibility is an independent diagnostic. Click the top-left `i` button to inspect\n  the selected pack; an \"Incompatible (load allowed)\" result does not block applying the shader.\n- The custom parameter interface follows Iris conventions: it has category and parameter pages,\n  with both two-column and full-width layouts.\n- Supported parameter controls include sliders, checkboxes, enums, and colors. Sliders expand on\n  hover, and their handles can be dragged.\n- Parameters come from the pack's own `options.json` or `shaders.properties`. If no supported\n  declarations are present, the interface shows an empty state.\n- See [`CUSTOM-PARAMETERS.md`](CUSTOM-PARAMETERS.md) for the complete parameter schema, source\n  integration rules, groups, localization, and runtime uniform setup. The guide is in Simplified\n  Chinese.\n- The top bar provides Import, Export, and Reset. Status messages fade out after 3 seconds, and the\n  interface uses Iris-style click sounds.\n\n### `/shader` Commands\n\n| Command | Description |\n| --- | --- |\n| `/shader scan` | Rescan `data/shaderpacks/` and refresh the shader pack list. |\n| `/shader ui` | Open or close the shader management panel directly, without using the hotkey. |\n| `/shader key` | Show the current hotkey used to open the panel. |\n| `/shader key <key>` | Change the panel hotkey. Supports `A-Z`, `0-9`, `F1-F12`, `SPACE`, `TAB`, `UP`, and similar names. Use `NONE` to disable the hotkey. |\n| `/shader vibrant` | Show the state of \"force enable Vibrant Visuals\". |\n| `/shader vibrant <on\\|off>` | Toggle force-enabling Vibrant Visuals (some servers lock the graphics mode; this bypasses the check). |\n| `/shader list` | List recognized shader packs in chat, including the number of parsed parameters for each pack. |\n| `/shader rollback` | Disable material redirection and restore vanilla materials. This succeeds only when hot reload support is available. |\n\n## Compilation And Outputs\n\n- Compilation is enabled by default: `lazurite build` runs with the bundled\n  `toolchain/shaderc.exe` through a serialized job queue with cancellation, timeout, and logs.\n- Parameter edits trigger material-level incremental compilation. Cache hits start no compiler\n  process at all.\n- Outputs are written to `compiled.new/`, validated for magic, target material format version 26, count,\n  and `meta.json`, then atomically switched into `compiled/`. Old output stays under\n  `compiled/.backup/`.\n- Packs may ship prebuilt `.material.bin` files, source for compilation, or both. Successful\n  compilation is followed by material hot reload.\n- `rdloader.pack.json`, `options.json`, `variants.json`, and pack-local `lang/*.lang` are supported\n  while keeping plain `.zip`, `.mcpack`, and `shaders.properties` compatibility.\n\n## Build\n\nRequirements: Windows x64 + Python 3.10+ + xmake + Visual Studio (MSVC) + LLVM (clang-cl) + the\nLeviLamina 26.51.7 SDK.\n\n```bash\nxmake f -y -p windows -a x64 -m release --target_type=client --mods_dir=<game mods directory>\nxmake -y\n```\n\nThe built mod package is `bin/RenderDragonShaderLoader/`. When `--mods_dir` is configured, the\nbuild also syncs it to `mods/RenderDragonShaderLoader/`; snapshots are kept in `_backup/` and can\nbe managed with `tools/sync_mod.ps1 -List` / `-Rollback`.\n\nThe output is a directly installable mod package. Copy the entire `bin/RenderDragonShaderLoader/`\ndirectory into the game's `mods/` directory. `xmake.lua` includes `lang/` and `config/config.json`\nin the output, and the build process does not modify any game directory.\n\n## Directory Structure\n\n```\nsrc/            Mod source code, independent from the game runtime and buildable/testable offline\n  mod/          Mod class, configuration, and `/shader` command registration\n  core/         Shader pack scanning/parsing, parameter models, and graphics mode switching\n  hook/         Material hot reload (readFile redirection + reloadMaterial), window drag-and-drop import\n  ui/           UI (UiScreen / UiSettings / UiLayout / UiCanvas) and game adapter layer\nlang/           Localization files (zh_CN / en_US)\nconfig/         Default configuration for first installation\nsamples/        Example shader pack (ExamplePack)\n```\n\n## Third-Party References\n\n### Design and Compatibility References\n\n- [Iris](https://github.com/IrisShaders/Iris): reference for the shader parameter UI, parameter\n  categories, slider interaction, and click sound behavior.\n- [OptiFine](https://optifine.net/): reference for `shaders.properties` parameter expressions and\n  the `shaderpacks` directory convention.\n- [BetterRenderDragon](https://github.com/QYCottage/BetterRenderDragon): reference for the material\n  hot reload approach.\n- [Lamium](https://github.com/amatouhake/Lamium): **this mod's UI is based on its implementation**,\n  including the custom-drawn screen and input handling.\n\nNo third-party binaries or resources from these projects are distributed with this repository.\nThey are listed only as design and implementation references.\n\n### Build Toolchain and Bundled Components\n\n- [Lazurite](https://github.com/veka0/lazurite): LGPL-3.0. Used as the shader-project build entry.\n- [lazurite-albite-compat](https://github.com/bambosan/lazurite-albite-compat): LGPL-3.0. The\n  albite-compatible Lazurite source tree under `toolchain/lazurite-albite-compat/`.\n- [Albite](https://github.com/bambosan/albite): MIT License. Optional material compiler backend.\n\n- License: this project is licensed under LGPL-3.0. See [`LICENSE`](LICENSE).\n- Third-party projects, dependencies, and distribution notes are listed in\n  [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).\n"}],"gallery":[],"versions":[{"version":"0.2.1","prerelease":false,"released":"2026-10-21T08:53:55Z","releaseUrl":"https://github.com/honeymirror/RenderDragonShaderLoader/releases/tag/v0.2.1","manifestUrl":"https://github.com/honeymirror/RenderDragonShaderLoader/blob/v0.2.1/tooth.json","info":{"name":"RenderDragonShaderLoader","description":"Shader pack manager & custom shader settings UI for Minecraft Bedrock (RenderDragon) on LeviLamina","tags":["platform:levilamina","type:mod"]},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.*"}}]}},{"version":"0.2.0-beta","prerelease":true,"released":"2026-10-20T07:29:02Z","releaseUrl":"https://github.com/honeymirror/RenderDragonShaderLoader/releases/tag/v0.2.0-beta","manifestUrl":"https://github.com/honeymirror/RenderDragonShaderLoader/blob/v0.2.0-beta/tooth.json","info":{"name":"RenderDragonShaderLoader","description":"Shader pack manager & custom shader settings UI for Minecraft Bedrock (RenderDragon) on LeviLamina","tags":["platform:levilamina","type:mod"]},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.*"}}]}},{"version":"0.1.1-beta","prerelease":true,"released":"2026-10-20T08:52:48Z","releaseUrl":"https://github.com/honeymirror/RenderDragonShaderLoader/releases/tag/v0.1.1-beta","manifestUrl":"https://github.com/honeymirror/RenderDragonShaderLoader/blob/v0.1.1-beta/tooth.json","info":{"name":"RenderDragonShaderLoader","description":"Shader pack manager & custom shader settings UI for Minecraft Bedrock (RenderDragon) on LeviLamina","tags":["platform:levilamina","type:mod"]},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.40.*"}}]}},{"version":"0.1.0-beta","prerelease":true,"released":"2026-10-20T08:52:54Z","releaseUrl":"https://github.com/honeymirror/RenderDragonShaderLoader/releases/tag/v0.1.0-beta","manifestUrl":"https://github.com/honeymirror/RenderDragonShaderLoader/blob/v0.1.0-beta/tooth.json","info":{"name":"RenderDragonShaderLoader","description":"Shader pack manager & custom shader settings UI for Minecraft Bedrock (RenderDragon) on LeviLamina","tags":["platform:levilamina","type:mod"]},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.40.*"}}]}}],"dependencies":{"github.com/liteldev/levilamina":{"id":"github.com/LiteLDev/LeviLamina","name":"LeviLamina","owner":"LiteLDev","url":"https://levimc.org/mods/github.com/LiteLDev/LeviLamina/"}},"requiredBy":[]}