v0.4.6 地图/皮肤上传全线修复，支持 Minecraft 26.x

0.4.2 – 0.4.6 一起发布（此前 npm 上的 latest 一直停在 0.4.1）。

• 支持 Minecraft 26.x：dimensions/<命名空间>/<维度>/region 世界布局 + 新版方块调色板
• 主世界 region 改为按布局判断，不再按文件数猜（整合包的数据包维度不会顶掉主世界）
• 浏览器 chunked 上传不再被 411 拒绝
• 认不出存档时直接说明 zip 里到底有什么；地图卡片显示版本 / region 数 / 源文件名 / 存档内名
• 新上传的皮肤自动设为默认；修 mc map doctor 崩溃

完整记录见 CHANGELOG。

v0.3.0

装它

在 DSH 里：插件市场搜 dsh-blender-mc，或命令行 dsh bundle add dsh-blender-mc@0.3.0。
装完先跑 mc_doctor 看环境，mc_setup 装配 BPS 骨架 / 物品库。

这版两个大件

① 设置页直接传背景地图 —— 不用再翻存档路径。
设置 → 背景地图，把整合包 zip 拖进去，插件自己解压、识别 level.dat、索引、出缩略图；
之后 mc_shoot({ "map": "方可梦世界" }) 就能点名出图（map 自动补 save 和搜索范围 area）。
单包 2 GiB / 解压 6 GiB 上限，zip 里套一层文件夹也认，多存档会让你点选。

② 渲染整链重做 —— 从「平光站桩」到「有光有雾有景深」。
根因是色彩管理停在 Standard，没有高光压缩，天空只能压到 0.03，环境光≈0，只剩三盏世界坐标硬光。
现在：AgX + Punchy → 太阳 8° 黄金时刻 → 三灯改相机基向量（换机位不会跑到角色背后）→
开 raytracing/fast GI 出接触阴影 → 有限体积盒做雾（EEVEE 5.2 的 world volume 必黑）→
相机 50mm/8.2 格 + DOF 对焦头部。主体占画高 0.431 → 0.55，脚底终于有影子。

审图从 5 项扩到 9 项，并修掉了「把接触阴影判成悬空」的误判。

另外加了

• 人物皮肤上传：设置 → 背景地图页下方，拖 64×64 经典皮肤 PNG；出图时 skin: "名字"。
• 姿势预设：hero / guard / raise / legacy（DSH_POSE）。
• 10 秒动画重做：mc_anim 现在有 preset，默认「双剑陀螺升空」。

修掉的 bug

--res abc / --samples 0 / --area 起止写反 会静默出废图或甩 traceback；
坏 zip 会导致退出码 0；map 的索引会跟着插件重装丢素材；
重装插件后 vendor/ 被清空导致「没装 BPS 骨架」；天空判据里「没高光」和「过曝」互为死锁。

完整逐条见 CHANGELOG.md。

0.1.0 - 2026-10-XX

首个可用版本。

新增

核心流水线

• mc_scan —— 在存档里找适合拍摄的机位。要求成片同高度平地，并排除视线遮挡。
  扫描范围外的格子按「有遮挡」处理，避免选出被建筑包围的假阳性机位
• mc_shoot —— 从存档出封面。自动找机位 → 导出几何 → 搭 Blender 场景 → 渲染
• mc_anim —— 出 10 秒「杀戮光环」动画（挥剑两刀 + 旋转能量环 + 斩击弧光）
• mc_check —— 只审图，不跑 Blender
• mc_doctor —— 检查运行条件，缺什么就给出完整安装指引
• mc_setup —— 从本地资源目录装配第三方资产

★ OpenCV 审图闭环

• 渲完自动检查：朝向（正面/背面）、接地、曝光、布光、构图
• 不合格按问题类型自动调参重渲，最多 N 轮
• 输出标注图（框出识别到的角色 + 结论分数）

Blender 侧

• anvil.py —— 纯标准库读 .mca，不需要 Blender 也不需要 Mineways
• export_obj.py —— 存档 → OBJ，材质名用 MC 贴图名（供 MCprep 识别）
• build_cover.py —— 导入世界 + MCprep 材质染色 + 角色骨架 + 手持物品挂 Hand.R
  • 物理天空 + 三点布光 + 相机
• animate_aura.py —— 骨骼关键帧 + 旋转光环 + 斩击弧光
• _compat.py —— Blender 版本兼容层，把反复踩的版本坑集中到一处

工程化

• requirements.py —— 必需/可选分清楚，缺可选的降级继续跑而不是报错
• setup_assets.py —— 自动挑对版本（BPS 选 V4.0.9 避开会闪烁的 BETA1）、
  ffmpeg 只记路径不复制、跳过用不上的大件
• scripts/smoke.mjs —— 不启动 DSH 就能验证插件外壳
• GitHub Actions CI（外壳 + Python + 仓库卫生 + 文档链接）

说明

为什么不打包第三方资产：MCprep（GPL）、BPS Rig、MC 素材都属他人作品，
再分发不合适；而且大部分用不上（Mineways 251 MB、Cycles Rig 整包 551 MB，
实际只用其中 1 个 15.7 MB 文件）。改为从用户本地资源目录"装配"，
vendor/ 排除在版本库和 npm 包之外。

已知限制

• 只支持 Java 版存档（Anvil 格式），不支持基岩版
• 扫描偏向 +x 方向（范围边界外被当作有遮挡，靠左边界的点只有朝 +x 看才有足够数据）
• 「接地」检查是全图颜色统计，纯色超平坦地形下判据会失效
• 角色骨架和物品库需要自备
• 动画只有"杀戮光环"一种

---

坑注释清单

本项目的代码里标了 ⚠️ 坑 N，写明报什么错、为什么错、正确判据是什么。
这是本项目最有价值的产出之一 —— 这类知识最容易丢，不写下来半年后会原样再踩一遍。

坑	内容
17	Blender 4.4 起 Action 没有 .fcurves，改成 layers → strips → channelbags
35	Blender 5.2 把天空 NISHITA 改名 MULTIPLE_SCATTERING
53/57	「标准」视图转换无高光压缩 → 物理天空削顶成白、动态范围被占满、布光完全显不出来
55	判断"哪些网格算身体"错了四次，最终判据：有指向该骨架的 Armature 修改器 且未隐藏
58	扫描时范围外必须当作有东西，否则会选出被房子包围的假阳性机位
59	o.bound_box 不算修改器形变 → 拿它算落地角色会浮在半空；且迭代会发散（depsgraph 不刷新）
62	Windows 下 cv2.imread 不支持中文路径，必须走 imdecode + np.fromfile
63	审图找主体的判据：只有角色有皮肤色，海面和天空没有
64	审图判朝向只取顶部 22%（MC 角色头只占身高 25%），取 35% 会把手臂算进来
65	扫描的提前退出判据必须覆盖所有资产种类，否则漏掉后面的目录
66	Windows 控制台默认 GBK → 打印 ✅ ❌ ⚠️ 这类符号会 UnicodeEncodeError 崩掉。cli.py 启动时强制把 stdout/stderr 切到 UTF-8（用 errors='replace' 兜底），不要求用户记得设 PYTHONIOENCODING
67	package.json 的 files 白名单里，.npmignore 和 .gitignore 都排除不掉东西。 所以写裸目录名（"py"）会把 __pycache__/*.pyc 一起带进 npm 包（实测 13 个文件 95 KB）。必须写 glob（"py/**/*.py"）。加 .npmignore 反而更糟 —— 它的存在让 npm 不再参考 .gitignore，.pyc 从 4 个变成 13 个
68	npm 账号开了 2FA 时，Classic Token 的 "Publish" 类型不绕过 2FA，npm publish 报 403 Two-factor authentication ... required。只有 "Automation" 类型（或勾了 "Bypass 2FA" 的 Granular Token）能免验证码发布；否则每次都要 --otp=123456。注意 npm publish --dry-run 不会触发这个检查，所以它通过不代表真发布能过