---

这是什么

一个 DSH 插件（也可以脱离 DSH 当命令行工具用）。

给它一个 Minecraft 存档目录，它就能：

存档 .mca  →  自动找好看的机位  →  导出几何  →  调 Blender 搭场景
           →  渲染  →  ★ OpenCV 自动审图  →  不合格自动调参重渲  →  出图 / 出片

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

出来的封面

真实存档草原 + 海平线，角色 3/4 侧脸持钻石剑。机位、布光、材质全自动。

渲完自己审图

每张图渲完都会用 OpenCV 检查 朝向 / 接地 / 曝光 / 布光 / 构图， 左上角是结论分数，绿框是识别到的角色位置。不合格会自动调参重渲。

10 秒动画

挥剑两刀 + 环绕的发光能量环 + 斩击弧光。

---

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

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

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

现象	实际原因	人眼发现耗时
"视角好像不对"	角色背对镜头（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：从源码装

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

第 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）。不给机位它会自己找。

---

使用教程

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

命令速查

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

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

# 在存档里找机位（按「开阔度」排序）
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]

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

在 DSH 里直接用

装好插件后开新会话，直接用自然语言：

用 E:\存档\我的世界 出一张封面，背景要开阔点的

先 doctor 看看环境齐不齐

把出好的封面做成 10 秒动画

模型会自己判断该调哪个工具（mc_doctor / mc_scan / mc_shoot / mc_anim / mc_check）。

常用参数

参数	默认	说明
--yaw	25	角色朝向（度）。相机在 -Y，25° 是 3/4 侧脸面向镜头
--cam-az	200	视线方位角（MC 角度）
--dist	11.2	相机距离
--sky	0.03	天空强度。用「标准」视图转换时必须 ≤0.05，否则削顶成白
--sink	0.06	脚陷入地面的深度。防止"看起来悬浮"
--view-transform	Standard	Standard / Filmic / AgX
--attempts	3	审图不达标时自动重渲几轮
--target	85	目标分，达到就停

---

工作原理

① scan     读 .mca → 每列最高方块 → 找成片同高度平地 → 排除视线遮挡 → 推荐机位
② export   机位周围导出 OBJ（材质名 = MC 贴图名，供 MCprep 识别）
③ build    调 Blender：导入世界 → mcprep.prep_materials（含生物群系染色）
           → 追加角色集合 → 手持物品挂 Hand.R → 物理天空 → 三点布光 → 相机
④ render   EEVEE 渲染
⑤ check    OpenCV 审图 → 不合格回 ③ 改参数（最多 N 轮）
⑥ anim     （可选）骨骼关键帧 + 旋转光环 + 斩击弧光
⑦ convert  ffmpeg 转 MP4 / GIF

目录结构

dsh-blender-mc/
├── lib/index.js              DSH 插件外壳：注册 6 个工具，调 Python
├── py/
│   ├── cli.py                命令行入口
│   ├── pipeline.py           ★ 编排 + 审图闭环 + auto_adjust
│   ├── vision_check.py       ★ OpenCV 审图
│   ├── requirements.py       运行条件检查 + 安装指引
│   ├── setup_assets.py       外部资产装配
│   ├── scan.py               找机位
│   ├── anvil.py              读 .mca（纯标准库，不需要 Blender）
│   └── blender/
│       ├── _compat.py        ★ Blender 版本兼容层
│       ├── export_obj.py     存档 → OBJ
│       ├── build_cover.py    搭场景 + 渲染
│       └── animate_aura.py   杀戮光环动画
├── docs/                     使用教程 / 架构 / 发布指南
└── vendor/                   ← 装配出来的第三方资产（.gitignore 排除）

设计取舍

JS 侧只做「工具注册 + 参数校验 + 调 Python + 汇报」，真正的活全在 py/ 里。 这样用户能在命令行直接跑同一套逻辑，不必依赖 DSH 才能用。

每个非直觉的判断在代码里都标了 ⚠️ 坑 N，写明报什么错、为什么错、正确判据是什么。 比如：

坑	内容
版本兼容	Blender 4.4 起 Action 没有 .fcurves；5.2 把天空 NISHITA 改名
Windows	cv2.imread 不支持中文路径，必须走 imdecode
求值	o.bound_box 不算修改器形变，拿它算落地角色会浮在半空
过滤	判断"哪些网格算身体"错了四次，最终判据是「有 Armature 修改器 且未隐藏」
扫描	扫描范围外的格子必须当作有东西，否则会选出被房子包围的假阳性机位

---

常见问题

缺东西怎么办？

跑 python py/cli.py doctor。缺任何东西都会给出完整安装指引，包含： 是什么 / 没它会怎样 / 去哪下载 / 怎么装 / 怎么验证。

必需项（Python 依赖、Blender、MCprep）缺了会拦住并停下； 可选项（角色骨架、物品库、贴图、ffmpeg）缺了只提示，会降级继续跑： 没有角色骨架就出风景空镜，没有 ffmpeg 就只出帧序列。

渲出来草地是灰白的？

MCprep 没装或没启用。草和树叶的贴图本身是灰度的，绿色是运行时按生物群系乘上去的 —— 这一步由 MCprep 完成。

动画渲了多少帧、怎么转视频？

mc_anim 出的是 PNG 序列帧。转 MP4：

ffmpeg -framerate 24 -i frame_%04d.png -c:v libx264 -crf 18 \
       -pix_fmt yuv420p -movflags +faststart 输出.mp4

sink 那类参数、以及为什么建议先 --preview 1,60,120 只渲几帧验证动作， 见使用教程。

支持基岩版吗？

不支持。基岩版用 LevelDB 存储，本项目只读 Java 版的 Anvil 格式（.mca）。

为什么外部资产不打包进来？

因为它们全是别人的作品（MCprep 是 GPL、BPS Rig 属 BlenderPlasticStudio、 MC 素材是 Mojang 的），各有各的许可，再分发不合适。

而且大部分用不上：Mineways 251 MB、Cycles Rig 整包 551 MB（实际只用其中 1 个 15.7 MB 的文件）。 本项目用纯 Python 直接读 .mca，不需要 Mineways 那套 GUI 导出流程。 所以改成从你本地已有的资源目录"装配"，vendor/ 也排除在版本库和 npm 包之外。

---

参与贡献

欢迎贡献，但请走 fork → PR → 审核 → 合并的流程。 直接推送到源仓库是不允许的。

完整流程见 CONTRIBUTING.md。简要版：

# 1. 先 fork，再克隆你自己的 fork
git clone https://github.com/<你的 GitHub 用户名>/dsh-blender-mc.git
cd dsh-blender-mc

# 2. 建分支（不要直接在 main 上改）
git checkout -b feat/你的功能名

# 3. 改完自测
python py/cli.py doctor
python py/cli.py check <几张你渲出来的图>
node scripts/smoke.mjs

# 4. 提交并推送
git commit -m "feat: 做了什么"
git push origin feat/你的功能名

# 5. 在 GitHub 上对源仓库开 Pull Request

所有 PR 都需要通过维护者审核后才能合并。

特别欢迎的贡献

• 🌍 英文文档 / 其他语言 —— 现在只有中文
• 🎬 更多动画预设 —— 现在只有"杀戮光环"一种
• 👁️ 更多审图判据 —— 比如"主体是否被前景遮挡"
• 🧱 更多方块 / 物品支持 —— 或者 MiBlend 的接入
• 🐛 你踩到的坑 —— 带上复现步骤和报错原文，非常有价值

提交前请确认

• python py/cli.py doctor 通过
• 新加的判据/参数在代码注释里写清了为什么（不只写"做了什么"）
• 没有把 vendor/ 或渲染产物提交进去
• 改了行为就更新 CHANGELOG.md

---

许可

MIT —— 覆盖本仓库自身的代码与文档。

运行时需要的第三方资产不由本项目分发，详见 THIRD_PARTY_NOTICES.md。

本项目与 Mojang Studios、Microsoft 无任何隶属或背书关系。 "Minecraft" 是 Mojang Studios 的商标。