TreeCodeTyper/dsh-blender-mc

dsh-blender-mc

把 Minecraft 存档变成 Blender 封面和动画。 你只需要提供存档和 Blender，其余全自动 —— 而且渲完会自己检查对不对。

快速开始 · 使用教程 · 工作原理 · 常见问题 · 参与贡献

先看结果

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

机位、布光、材质、渲完的自动审图全部自动。

0.2.1 → 0.3.1

之前 · 现在 · 平光、无投影、剑穿过胸口 · AgX + 黄金时刻 + 接触阴影 + 景深，3/4 侧脸持剑

10 秒动画

它做了什么

存档 .mca  →  自动找机位  →  导出几何  →  Blender 搭场景（MCprep 材质 + BPS 骨架 + 三点布光）
           →  渲染  →  ★ OpenCV 审图  →  不合格自动调参重渲  →  出图 / 出片

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

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:/出图" }

传地图：设置 → 背景地图 → 把存档或整合包压成的 .zip 拖进去，自动解压识别， 之后 mc_shoot({ "map": "名字" }) 就能点名出图（map 会自动补存档路径和搜索范围）。

没有 DSH？也能当纯命令行工具用

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

为什么不只是"跑个脚本"

因为手工调试渲染最耗时的不是渲染，是渲完看不出问题。

这个项目在开发过程中真实踩过的坑：

现象 · 实际原因 · 人眼发现耗时 "视角好像不对" · 角色背对镜头（yaw 差 180°） · 反复调相机 → 才想到是角色朝向 "人咋是悬浮的" · 脚离地 0.019，MC 方块边缘锐利，一点缝就显眼 · 三轮排查 + 三次数值测量 "背景咋回事，也没有光源" · 「标准」视图转换无高光压缩，物理天空削顶成白，动态范围被占满 · 两组对比实验 "钻石剑好像没正确握在手上" · 抓握点用错（骨骼尾端 vs 手臂网格底部） · 逐部件测量

这四类问题的共同点：都能被 CV 判出来，但人眼在缩略图上看不出来。

所以渲染之后加了一道 OpenCV 审图：

检查项 · 判据 · 不合格自动怎么改 朝向 · 头部区域的皮肤色占比（正面 ~30% / 背面 ~9%） · yaw +180° 接地 · 脚底下方 vs 旁边地面的色差 · 加大下沉量 曝光 · 死白/死黑像素比、动态范围 · 降天空强度 布光 · 角色周围地面的灰阶方差（太均匀 = 平光） · 抬灯光倍率 构图 · 主体占画面高度、水平位置、头顶留白 · 调整相机距离

实测效果

故意给一个错的朝向（--yaw -125，背影），看它自己怎么办：

[4/5] 第 1 次渲染（yaw-125.0°）
[5/5] 审图: WARN 62 分
      ⚠️  [1] 看到的是【背面】（头部皮肤占比仅 8.9%）
      🔧 角色朝向 -125.0° → 55.0°（转正面）
[4/5] 第 2 次渲染（yaw55.0°）
[5/5] 审图: PASS 92 分
      ✅ 达标（92 ≥ 85），停止迭代

它自己发现并修正了。 这正是手工调试时最花时间的那一步。

快速开始

第 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 --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 只记路径不复制（96 MB 的系统工具没必要再放一份）

第 4 步：出图

python py/cli.py shoot "D:/saves/我的世界" --area -2100,-1600,-1400,-900 --out ./出图

--area 是允许搜索的矩形范围（x0,x1,z0,z1）。不给机位它会自己找。

第 5 步（可选）：把你的地图传进 DSH

DSH → 设置 → 背景地图 → 拖入存档 .zip（或点「选择文件」）。

• 单个 zip 上限 2 GB，解压后上限 6 GB —— 原版整合包地图（几百 MB 到 1 GB）够用
• zip 里套一层文件夹也能认（比如 方可梦世界/新的世界/level.dat）
• 一次上传里如果有多个存档，会让你点选要哪一个
• 传完会出现在列表里，带缩略图（能读到 icon.png 就用它）、MC 版本、坐标范围；

三个按钮：设为默认 / 重命名 / 删除（删除是软删，文件进回收目录，可找回）

传完就不用记路径了，出图时用 map 参数点名：

// mc_shoot
{ "map": "方可梦世界", "out": "E:/出图/方可梦封面" }        // 名字可以写部分前缀
{ "map": "m_542656d4d9e4", "out": "..." }                  // 也可以写 map id

map 省掉两个必填参数：save（自动指向解压出来的存档目录）和 area （自动按存档包围盒推荐机位搜索范围）。想自己指定范围，照旧写 area 覆盖它。

命令行等价写法（不经过 DSH 面板）：

# 导入一个 zip（--root 默认 %USERPROFILE%\.dsh\blender-mc\maps）
python py/cli.py map import --zip D:/整合包/方可梦世界.zip --name 方可梦世界
python py/cli.py map list
python py/cli.py map resolve --name 方可梦        # 打印 savePath / area / 版本

数据都在 %USERPROFILE%.dsh\blender-mc\maps 下，一个地图一个目录，删插件不删地图。

使用教程

第一次用请看 → 手把手使用教程 （从找存档目录开始，到出封面、出动画、调参，每步都有截图级说明）

命令速查

# 检查运行条件（缺什么会给出完整安装指引）
python py/cli.py doctor

# 装配外部资产
python py/cli.py setup [资源目录...] [--dry-run]

# 提取你自己资源包里的模型（Bedrock 几何 → OBJ，插件不带任何素材）
python py/cli.py extract <资源目录> --out <目录> [--list] [--filter 关键词]

# 在存档里找机位（按「开阔度」排序）
python py/cli.py scan <存档> --area x0,x1,z0,z1

# 出封面（含审图闭环）
python py/cli.py shoot <存档> --area x0,x1,z0,z1 --out <目录>

# 出动画（默认 10 秒杀戮光环）
python py/cli.py anim <封面工程.blend> --out <目录> [--preview 1,60,120]
python py/cli.py anim <封面工程.blend> --preset yujian --out <目录>   # 御剑飞天
python py/cli.py anim <封面工程.blend> --preset <配方名> --out <目录>  # 自己写的配方

# 分镜成片：一份分镜表 → 多镜头渲染 → 按顺序剪成一支 MP4（同时写 分镜表.md）
python py/cli.py film --plan 分镜.json --out <目录> [--animatic]

# 只审图，不跑 Blender
python py/cli.py check <图...> [--json]

# 地图库：把存档 zip 收进来（DSH 面板做的是同一件事）
python py/cli.py map import --zip <存档.zip> [--name 名字]
python py/cli.py map list | resolve --name <名字> | rename | delete | default | doctor

一句话出片：分镜成片（0.4.0）

mc_anim 出来的是一条 240 帧的长镜头。真实片子是"分镜表定几个镜头，每镜单独渲， 最后剪起来"——这就是 mc_film 干的事，你只要说一句话：

把刚才的御剑飞天剪成 10 秒：先中景看符阵亮、再低机位仰拍冲天、最后大远景飞进云里

模型会写一份分镜表交给 mc_film，它依次做：逐镜建工程（同一套动作、不同机位）→ 按帧区间渲 → 重编号 → ffmpeg 拼接 → 写 分镜表.md。