dsh-blender-mc

dsh plugin --profile web add dsh-blender-mc

<div align="center">

<img src="icon.svg" width="112" alt="dsh-blender-mc">

dsh-blender-mc

把 Minecraft 存档变成能直接当封面的 Blender 图，或一支 10 秒片子。

你不用会 Blender：机位、布光、材质、后期、审图全自动 —— 而且渲完会自己挑毛病。






[快速开始](#快速开始) · [使用教程](docs/使用教程.md) · [工作原理](#工作原理) · [常见问题](#常见问题) · [参与贡献](CONTRIBUTING.md) · [交接文档（改代码前必读）](docs/交接.md)

</div>

---

先看结果

<img src="assets/cover-hero.jpg" alt="cover" width="100%">

存档是玩家自己在 设置 → 背景地图 里拖进去的 zip，皮肤也是自己传的 64×64 PNG。

剩下的机位、布光、材质、后期、审图全部自动。1280×720 / 192 采样约 16 秒（EEVEE）。

0.4.9 → 0.5.3：同一份存档，只换了插件版本

0.4.9 · 0.5.3

<img src="assets/before-0.4.9.jpg" width="430"> · <img src="assets/after-0.5.3.jpg" width="430">

视图转换 Standard、1.6:1 对打平光、没有后期、没有接触阴影；MCprep 装的是假成功、方块贴图根本没进 Blender，树林永远种不出来 · AgX + 三点布光（Key/Fill/Rim 按相机方向重摆）+ 合成器后期（bloom / 饱和度 / 暗角）+ 接触阴影 / 景深；贴图链路打通，自动挑机位会避开「正对土崖」的方位

一张图之外

<img src="assets/screenshot-3-anim.jpg" alt="animation" width="100%">

10 秒动画（mc_anim）、多镜头分镜成片（mc_film）、自己写的动作配方（py/blender/presets/*.json）走的是同一套场景搭建与审图。

它做了什么

存档 .mca  →  挑机位（地形仰角 / 天空占比 / 太阳方向）  →  导出几何  →  Blender 搭场景
           （MCprep 材质 + BPS 骨架 + 贴图 + 三点布光 + 合成器后期）
           →  渲染  →  ★ OpenCV 审图  →  不合格自动调参重渲  →  出图 / 出片

你不用会 Blender，不用会 Mineways，不用手动摆相机、调灯光、配材质、找贴图。

能力 · 说明

自动挑机位 · 在 .mca 里找成片平地 → 视线方位打分（地形仰角 > 8° 直接出局、被太阳直射惩罚、背后空旷加分）→ 相机按「角色左、右侧留白」摆

自动搭场景 · MCprep 染色材质（失败自动退回内置按面染色）、BPS v4 角色骨架、方块物品库、可选树林（自动避让角色与镜头路径）

像摄影师那样布光 · Key / Fill / Rim 按相机与太阳方向重摆（世界坐标固定灯在换机位后会全废），黄金时刻色温 + 物理天空 + 雾

电影感后期 · AgX 色彩管理 + 合成器：bloom（阈值按实际亮度调）/ 饱和度 / 暗角；后期可整体关掉

渲完自己挑毛病 · OpenCV 审 8 类：朝向、接地、曝光/动态范围、布光（地面灰阶方差）、景深、构图（主体占比/留白）、轮廓光、天空梯度

不合格就自己改 · yaw 翻转、下沉量、天空强度、灯倍率、相机距离 —— 五类可自动修，其余给建议分

一次出片 · 10 秒动画、分镜成片（一份分镜表 → 多机位渲染 → 按顺序剪成 MP4）、自定义动作配方

接自己的素材 · 设置页上传地图 zip 与皮肤；mc_extract_models 把资源包/模组里的 Bedrock 模型转 OBJ 摆进场景

30 秒上手

# ① 装（或在 DSH 插件市场里搜 dsh-blender-mc）
dsh plugin --profile desktop add dsh-blender-mc

# ② 体检 + 装配 Minecraft 素材（MCprep / BPS 骨架 / 物品库 / ffmpeg / 方块贴图）
mc_doctor
mc_setup

# ③ 出图（存档 zip 已经在「设置 → 背景地图」里传过）
mc_shoot { "map": "方可梦世界", "out": "E:/出图", "trees": 10 }

缺东西它会先说：装完之后插件会在后台跑一次体检（只读目录、不启动 Blender，

几十毫秒），结论缓存在 <DSH_HOME>/blender-mc/readiness.json。缺 MCprep / cv2 /

骨架这类必需项时，AI 会在你下一次开口时主动列出缺哪几项、每项一句怎么装；

装齐了就一个字都不说。想立刻看结论：跑一次 mc_doctor，或终端

python py/cli.py readiness。自检可以关：插件配置里 startupCheck: 'off'

（默认 'cache'，每次都深检用 'full'）。

传地图：设置 → 背景地图 → 把存档或整合包压成的 .zip 拖进去，自动解压识别，

之后 mc_shoot({ "map": "名字" }) 就能点名出图（map 会自动补存档路径和搜索范围）。

<details>

<summary>没有 DSH？也能当纯命令行工具用</summary>

pip install opencv-python numpy
python py/cli.py doctor
python py/cli.py setup
python py/cli.py shoot "D:/saves/新的世界" --area -2050,-1940,-1230,-980 --out ./out

</details>

---

快速开始

第 0 步：需要什么

· 必需 · 说明

✅ · Blender · 4.2 LTS 以上。下载

✅ · Python 3.10+ · 要能 pip install

✅ · Minecraft Java 版存档 · .mca 区域文件那层目录

⭕ · MCprep / BPS 骨架 / 物品库 / ffmpeg · 可选，缺了会明确告诉你少了什么功能

基岩版不支持 —— 基岩版用 LevelDB，本项目只读 Anvil 格式。

第 1 步：装依赖

pip install opencv-python numpy

第 2 步：装插件

方式 A：从插件市场装（推荐）

DSH → 设置 → 插件市场 → 搜索 dsh-blender-mc → 安装 → 开新会话

方式 B：命令行装（推荐给要配本机路径的人）

dsh plugin --profile desktop add dsh-blender-mc@0.2.1
python scripts/install_to_profile.py --profile desktop   # 写本机路径配置（可 --dry-run 预览）

为什么写成 @0.2.1：DSH 装包时有一层「新版本冷却期」（pnpm minimumReleaseAge），

刚发布几个小时的版本不会自动被选中 —— 不带版本号时可能装到旧的 0.1.2，而那个版本在

DSH 0.2.0-rc.2 上 7 个工具全都注册不上。写死版本号会绕过冷却期（DSH 会把它记进

minimumReleaseAgeExclude）。等冷却期过了，不带版本号也能装到最新的。

install_to_profile.py 会先备份、再改 profile 的 cordis.patch.yml，写前用 PyYAML 自查、

写后用 dsh <profile> --dump-config 让 DSH 自己组合一遍 —— 这是 0.2.1 修掉的重点，

细节见下面「⚠️ 装完 DSH 打不开怎么办」。

方式 C：从源码装

git clone https://github.com/TreeCodeTyper/dsh-blender-mc.git
cd dsh-blender-mc
python py/cli.py doctor        # 先看看缺什么

⚠️ 装完 DSH 打不开怎么办（0.2.1 之前的坑）

症状：双击 DSH 没反应 / 窗口一闪就没；命令行跑 dsh 报

failed to parse overlay ...\cordis.patch.yml: YAMLException: end of the stream or a document separator is expected

或 ... must be a top-level YAML array of loader patch entries。

原因：profile 的补丁层 cordis.patch.yml 必须恰好是一份一维 YAML 列表。

0.2.1 之前的 scripts/install_to_profile.py 会直接往文件末尾拼 - id: blender-mc 块，

而全新 profile 的模板里那行 [] 占位还在 —— [] 后面再跟块条目就是一份文档两个顶层元素，

YAML 解析失败 → 补丁层读不出来 → 应用起不来。重装 DSH 能让补丁层退回 [] 模板，

所以「只能重装」；但下次再装同一个坑还会踩。

不用重装的救法（在 DSH 打不开的状态下也能跑）：

python scripts/repair_profile.py            # 先体检，看哪个 profile 的补丁层坏了
python scripts/repair_profile.py --apply    # 修（写前自动备份 .bak-<时间戳>）

它只做行级修复：把和别人共存的 [] 占位注释成 # []、文件里一条条目都不剩时补回 []，

然后重启 DSH 即可。修不好也别硬改 —— 把报错贴到

issues。

手工改的话记住两条：① 一个文件里只能有一份顶层列表；② 没有条目时文件里必须留 []，

只剩注释会被解析成 null，同样起不来。

第 3 步：装配外部资产

第三方资产（MCprep、角色骨架、物品库）不随本项目分发，需要从你本地已有的资源目录装配：

python py/cli.py setup --dry-run    # 先看会搬什么，不动文件
python py/cli.py setup              # 实际装配

装配器会：

• ✅ 自动优先选 BPS Rig V4.0.9（4.0.10 BETA1 的头部网格是平的，会闪烁）
• ✅ 把 MCprep 解压安装到 Blender 的 addons 目录（路径是问 Blender 要的）
• ✅ 跳过用不上的大件（Mineways 251 MB、MCSkin3D —— 本项目直接用 Python 读 .mca）
• ✅ ffmpeg 只记路径不复制

…(truncated)