[工具发布]MMD/VRC模型 → 怪物猎人荒野全自动模型转换工具 v2.2

怪物猎人荒野MOD圈人物mod 工具整合便捷功能二次元

MMD / VRChat / VRM to Monster Hunter Wilds 模型转换工具 v2.2

概述

这是一套用于将 MMD / VRChat / VRM 模型转换为怪物猎人荒野 MOD 的增强自动化工具。

v2.2 新增（VRC/VRM 支持）

· 新源格式：.vrm（VRM 0/1.0）、.fbx（Unity humanoid / VRChat / Mixamo）、.glb/.gltf

· 新增 Operator：侧栏 → "Import VRC / VRM" 按钮，自动检测扩展名走对应导入器

· 完整 Unity Humanoid 骨骼字典（mmd_to_wilds/data/humanoid.py）：Hips/Spine/Chest/UpperChest/Neck/Head/LeftEye/Jaw、4 段手指 LeftThumbProximal/Intermediate/Distal、腿 LeftUpperLeg/LowerLeg/Foot/Toes 等 55+ 条

· 完整 VRM 1.0 camelCase 骨骼字典：hips/leftUpperArm/leftThumbMetacarpal/...

· Mixamo 兼容：mixamorig:Hips/Spine/Spine1/Spine2/...，VRoid 导出的混血骨架直接可用

· VRChat 15 viseme：sil/pp/ff/th/dd/kk/ch/ss/nn/rr/aa/e/i/o/u 自动 → Wilds BS_Mouth_*

· VRM 0 大写表情预设：NEUTRAL/JOY/FUN/ANGRY/SORROW/SURPRISED/BLINK_L/BLINK_R/LOOKUP/LOOKDOWN/...

· VRM 1.0 camelCase 表情：aa/ih/ou/ee/oh/blink/blinkLeft/happy/sad/angry/...

· EyesLookUp/Down/Left/Right → BS_Eye_LookUp/Down/Left/Right（Wilds 眼神朝向）

借鉴的开源资源

资源；用途

vrm-c/vrm-specification（https://github.com/vrm-c/vrm-specification） — VRMC_vrm-1.0 humanoid.md；VRM 1.0 标准骨骼名

VRChat creators docs（https://creators.vrchat.com/avatars/rig-requirements/）；Unity Humanoid 骨骼规范

VRChat Wiki — Visemes（https://wiki.vrchat.com/wiki/Visemes）；15 viseme 顺序和命名

hazre/VRC2NeosBones-blender-plugin（https://github.com/hazre/VRC2NeosBones-blender-plugin）；VRC 骨骼别名兼容（UpperLeg_L 等）

BStemplefix（https://github.com/...） joints.lua；真实 Wilds 205 个 joint 名

BStemplefix（https://github.com/...） expression.lua；BlendShape 按 index 而非 name 匹配的关键发现

saturday06/VRM-Addon-for-Blender（https://github.com/saturday06/VRM-Addon-for-Blender）；VRM 导入依赖（运行时）

CATS Blender Plugin（https://github.com/absolute-quantum/cats-blender-plugin）；MMD 导入 + apply_as_rest 工具链

推荐工作流（VRChat → Wilds）

1. 拿到 .vrm 或 .fbx 文件

2. Blender 装好 VRM-Addon（如果是 .vrm）

3. 点 "Import VRC / VRM" → 自动检测格式，导入完日志会列出 humanoid 状态 / shape key 分类 / 物理候选骨骼

4. 点 "Rename Bones" — humanoid 骨骼自动 → Wilds joint 名

5. 点 "Map Shape Keys" — VRC viseme + VRM 表情自动 → BS_*

6. 后续步骤（缩放/T-Pose/物理/MDF）和 MMD 路线一致

⚠️ 关键校准（v2.1 必读）

v2.1 的 Wilds 骨骼字典和物理参数已经按真实游戏数据重写，数据源：

· BStemplefix（https://github.com/...）的 joints.lua（V.A.L.I.S. 反向工程的 205 个 Wilds joint 名）

· 实际 natives/STM/BoneSystem/*.fbxskel.7 文件解析

旧 v2 字典使用的 hip_HJ_00 / arm_L / thigh_L / head 等小写命名不是 Wilds 真实命名（可能是 RE Engine 早期版本或其他游戏的猜测）。Wilds 实际使用 Hip / L_UpperArm / L_Thigh / Head 等 PascalCase + L_/R_ 前缀 + _HJ_* 辅助关节后缀。

BStemplefix/expression.lua 每帧用循环 setBlendShapeWeight(i, weight) 把 Player_Face 的 BlendShape 权重原样复制到 body armor。这意味着：

· 防具 mesh 的 BlendShape 顺序必须和 Player_Face 槽位对齐

· 名字本身游戏不读（人眼用）

· 想让你的 MMD morph 在游戏里能被驱动，必须保证导出时 shape key 顺序与 Player_Face 一致

人家的 morph 映射依然有用——它让 Blender 里 shape key 名字可读，但导出前请手动 reorder shape keys到 Player_Face 顺序（或用 BStemplefix 的 debug_list_blendshapes 函数 dump 你目标角色的 BS 顺序后再对齐）。

主代码自动 try-import + numpy fallback

mmd_to_wilds/_native/__init__.py 顶层 try: from . import _accel 失败时自动用 numpy 实现继续跑，所以没有 .pyd 也能用——只是慢一点。

HAS_NATIVE 布尔可以告诉调用方加速器是否在线。

想自己编译别的平台 / 别的 Python 版本

cd mmd_to_wilds/_native

python setup.py build_ext --inplace

需要：

· C 编译器（Windows MSVC、Linux gcc、macOS clang）

· Cython >= 0.29

· numpy

编译完得到 _accel.<abi>.pyd (Win) / _accel.<abi>.so (Linux/macOS)，留在同目录即可被 loader 选中。

🟢 BlendShape 索引校准（.mesh 直接提取，无需进游戏！）

二刷资料后人家发现了真正的捷径喵～RE-Mesh-Editor 的 BlendShape 完整导入是关闭的（file_re_mesh.py:13 写着 IMPORT_BLEND_SHAPES = False（https://github.com/NSACloud/RE-Mesh-Editor），因为 vertex delta 解析在新版 RE Engine 上还坏着），但是 BS 的「名字+索引顺序」是另外一段数据，活得好好的！

人家照着 NSACloud 的 FileHeader 解析逻辑 + alphazolam 的 010 模板，写了一个纯 Python 的 .mesh BS 名提取器，不用进游戏、不用 REFramework、不用 RE-Mesh-Editor，直接读 ch00_001_0000.mesh.241111606 就能 dump 真实 Player_Face BlendShape 顺序。

三条获取路径（任选其一）

A) 直接从 .mesh 文件提取（推荐） ⭐

需要从主人自己的游戏目录提取 .mesh 文件（版权数据不可分发，所以人家不内置）：

文件；用途

Art/Model/Character/ch00/001/0000/ch00_001_0000.mesh.241111606；Player Head (Female) — 首选 BS 提取源

Art/Model/Character/ch00/000/0000/ch00_000_0000.mesh.241111606；Player Head (Male)

Art/Model/Character/ch00/500/0000/ch00_500_0000.mesh.241111606；Alma Head（NPC，对比参考）

Art/Model/Character/ch00/505/0000/ch00_505_0000.mesh.241111606；Gemma Head（NPC，对比参考）

提取工具二选一：

· RE Asset Library（https://www.nexusmods.com/monsterhunterwilds/mods/41） — Blender 插件，浏览 + 一键提取 (推荐)

· ree-pak-rs（https://github.com/zhxoshi/ree-pak-rs） — CLI .pak 解包器

Blender 侧栏 → Morph Preview 面板 → 展开 "How to get ch00 Face Mesh" 子面板有完整文件清单和提取步骤。

完整 path 索引内置在 mmd_to_wilds/data/wilds_mesh_paths.py（来源：NSACloud/RE-Asset-Library-Collection（https://github.com/NSACloud/RE-Asset-Library-Collection）的 catalog TSV，只含 path 字符串，不含 mesh 数据）。

CLI:

python -m mmd_to_wilds.tools.mesh_blendshapes ch00_001_0000.mesh.241111606 out.json

Blender 侧栏 → "Extract BS Names from .mesh" → 选 mesh 文件。提取成功后自动 reorder。

支持的版本：MHWilds (130, magic 241111606 / beta 240820143) + ONI2 transitional (127)。

B) 从游戏内 dump（备用）

1. 装 praydog/REFramework（https://github.com/praydog/REFramework） + BStemplefix

2. 进游戏，在 BStemplefix GUI 调用 Expression.debug_list_blendshapes()

3. 拿到 reframework/log.txt

4. Blender 侧栏 → "Load Player_Face BS Dump" → 选 log.txt

C) 手写 JSON

参照 schema mmd_to_wilds.blendshape_dump.v1：

{

"schema": "mmd_to_wilds.blendshape_dump.v1",

"player_face": [{"index": 0, "name": "BS_Eye_Close"}, ...]

}

校准状态

mmd_to_wilds/data/wilds_blendshapes.py 内置占位表，每条带 source 字段：

Source；含义

real；从游戏 dump / .mesh 提取确认 ✅

inferred；根据 RE Engine 命名规律推测 ⚠️

guess；纯靠猜，先占位 ❌

Morph Preview 面板顶部横幅显示当前状态（CALIBRATED / PLACEHOLDER + 数字 + 两个一键提取按钮）。

Reorder 算法

mmd_to_wilds/ops/reorder.py 的 reorder_to_wilds_index：

1. 按目标列表逐槽位 move Blender shape key 到 index 对应槽

2. 缺失的槽位补 0-offset 占位 shape key（保持 index 对齐）

3. 多余的 shape key 留在尾部（不删，主人手动决定）

为什么我们没写死真实表？

刨了 NSACloud/RE-Mesh-Editor（https://github.com/NSACloud/RE-Mesh-Editor）（mesh 导入器源码）和 kassent/mhwilds_data（https://github.com/kassent/mhwilds_data）之后确认：

· RE-Mesh-Editor 源码 file_re_mesh.py:1311 有 # TODO Blend shapes are different in wilds, fix — 连作者也还没完全反向工程出 Wilds 的 BS 结构变化

· 公开数据集里没有人放过完整 Player_Face dump

· 唯一可靠来源是用户自己在游戏里用 BStemplefix dump

人家诚实地标 PLACEHOLDER，而不是编一份伪数据给主人埋雷喵 ฅฅ

新增 fbxskel.7 导入

侧栏 → "Import fbxskel.7 (Hunter Ref)" 按钮，直接读取 natives/STM/BoneSystem/*.fbxskel.7 生成 Blender 参考骨架，免装 RE Mesh Editor 就能 Snap。

也可以从 CLI 使用：

python -m mmd_to_wilds.tools.fbxskel EO_Milltina.fbxskel.7

输出：EO_Milltina.json（BStemplefix 兼容格式）

v2.1 新功能（相对 v2）

· 表情自动映射 ⭐ — PMX morph (日文) → 标准英文 → RE Engine / ARKit / VRChat BlendShape 命名

· Shape Key 清理 — 自动删除空 morph、合并重复、跨 mesh 同步重命名

· 左右对称检测 — UI 中标记对称 morph 对（_L/_R、Left/Right、左/右）

· Morph 预览面板 — 按 brow / eye / mouth / other 分类的滑块面板，对称配对图标提示

· 骨骼对齐 Snap — 加载 Hunter 骨架后，把同名骨骼自动 snap 到 Hunter 的位置和朝向

· 权重清理 — 删零权重、限制每顶点 4 骨、normalize（RE Engine 上限）

· Mesh 命名规范化 — 按身体分组自动 ch03_<armor>_000_<group>_LOD0

· MDF 材质草稿 — 扫描所有材质，按推断类型（skin/hair/eye/cloth/metal/transparent）生成 JSON 草稿

· 辅助骨自动生成 — 裙子辅助骨自动绑在大腿下方

· 物理预设真正生效 — CHAIN_PRESETS 参数会写入 RE Chain 设置（v2 只是定义了字典但没应用）

· 跨 Operator 共享状态 — 不再每个按钮新建实例，所有操作共享 Scene 上的 state

· 配置 JSON 保存/加载 — 一次设好的参数可以复用

· Blender 日志面板 — 转换过程直接在侧栏可见

· 撤销点 — 每个步骤前 ed.undo_push，出错时可一键回退

v2 -> v2.1 修复的 bug

· T-Pose 调整无效（rotation_euler 写入 quaternion 模式被丢弃）— 现在显式切 XYZ 模式

· 缩放双倍（先对 armature apply scale 再对 mesh apply）— 现在一次性对所有目标 apply

· Twist 权重合并 O(顶点×组数) 每次 try/except —— 现在直接遍历 vertex.groups

· CHAIN_PRESETS / AUXILIARY_BONES 字典定义但从未使用 — 现在真正应用到 RE Chain 设置

· 手指 +5° 不区分左右 — 现在按 _R/right/右取反

继承自 v2 的功能

· 完整骨骼映射 - 基于CATS插件的数百种骨骼名称变体

· 自动姿态调整 - A-Pose自动转换为T-Pose

· 自动缩放匹配 - 根据目标身高自动缩放模型

· 物理骨骼检测 - 自动识别头发/裙子物理骨骼

· 物理链创建 - 集成RE Chain Editor V12自动创建Chain2物理

· 碰撞胶囊生成 - 自动为头部和腿部创建碰撞

基于教程

本工具基于以下教程和开源项目开发：

· 万字教程：从零开始的荒野MMD二次元MOD教程（https://www.caimogu.cc/post/2114547.html）

· CATS Blender Plugin（https://github.com/absolute-quantum/cats-blender-plugin） - 骨骼映射字典

· RE Mesh Editor（https://github.com/NSACloud/RE-Mesh-Editor） - 模型导入导出

· RE Chain Editor（https://github.com/NSACloud/RE-Chain-Editor） - 物理链创建

所需软件

必需

1. Blender 4.3.2+ - 下载地址（https://download.blender.org/release/Blender4.3/）

2. Python 3.10+ (如果单独运行贴图处理)

Blender 插件（必需）

插件；版本；用途

CATS Blender Plugin（https://github.com/absolute-quantum/cats-blender-plugin）；0.19.0+；MMD导入和修复

RE Mesh Editor（https://github.com/NSACloud/RE-Mesh-Editor）；V0.60+；RE Engine模型导出

RE Chain Editor（https://github.com/NSACloud/RE-Chain-Editor）；V12.1+；物理链创建 (支持Chain2)

批量插件 (诸葛不太亮)；-；骨骼吸附和贴图合并

其他工具

1. Photoshop + Intel DDS 插件 - 贴图处理

2. mdf-manager - MDF 材质编辑

3. ree-pak-rs - 游戏文件解包/封包

文件说明

Semiauto-MMD-to-Wilds-model-converter/

├── mmd_to_wilds/ # 主插件包 (v2.1，模块化)

│ ├── __init__.py # bl_info + register/unregister

│ ├── config.py # ConversionConfig + JSON 持久化

│ ├── state.py # Scene PropertyGroup (跨 operator 共享状态)

│ ├── logger.py # 路由到 Scene 集合的日志

│ ├── utils.py # blender + 文本工具

│ ├── data/ # 静态查表

│ │ ├── bones.py # MMD 日文 / 标准英文 / Wilds 三层骨骼映射

│ │ ├── morphs.py # MMD morph -> Standard EN -> ARKit/VRChat/RE Engine

│ │ ├── physics.py # CHAIN_PRESETS AUXILIARY_BONES / 碰撞胶囊

│ │ └── meshes.py # Wilds mesh 命名约定

│ ├── ops/ # 无 Blender Operator 包装的纯函数

│ │ ├── bones.py # 重命名 / Snap / Twist 合并 / Scale

│ │ ├── morphs.py # ⭐ shape key 重命名 / 清理 / 对称检测

│ │ ├── meshes.py # 权重清理 / 命名规范化

│ │ ├── pose.py # A-Pose -> T-Pose

│ │ ├── physics.py # 链 + 碰撞 + 辅助骨 + 预设应用

│ │ ├── material.py # ⭐ MDF 草稿 JSON

│ │ └── io.py # 导入导出

│ └── ui/

│ ├── operators.py # Blender Operator 类（一对一对应 ops/）

│ └── panels.py # 主面板 + Settings + Morph 预览 + 日志

├── mmd_to_wilds_v2.py # 兼容入口（转发到包，保留"打开脚本即运行"的用法）

├── texture_processor.py # 贴图处理工具 (独立 Python，CLI)

└── README.md # 本文档

安装

1. 安装 Blender 插件

方法一: 作为插件安装（推荐）

1. 把 mmd_to_wilds/ 整个文件夹打包成 zip

2. 编辑 → 偏好设置 → 插件 → 安装

3. 选择 zip，启用 MMD to Monster Hunter Wilds Converter

方法二: 直接加载脚本（向后兼容）

1. 打开 Blender，Scripting 工作区

2. 打开 mmd_to_wilds_v2.py（薄壳子）

3. 点击运行 — 会自动 import mmd_to_wilds 包并注册

2. 安装贴图处理依赖

pip install pillow numpy

使用方法

一键转换 (推荐)

1. 打开 Blender

2. 在 3D 视图右侧找到 "MMD2Wilds" 标签

3. 点击 "一键转换" 按钮

4. 选择 MMD 模型文件

分步操作

侧栏 "MMD2Wilds" 标签下分四个面板：

MMD -> Wilds（主面板）

· 导入 MMD / Hunter — 选 .pmx/.pmd 或 .mesh

· Fix Model — 删锁定 vgroup + 删 IK 骨 + 合并扭曲骨权重

· Rename Bones — MMD 日文/英文 → Wilds 命名

· Snap to Hunter — 同名骨吸附到 Hunter 骨架位置/朝向（先导入 Hunter）

· Auto Scale — 按目标身高缩放

· A-Pose -> T-Pose — 手臂展开+手指轻弯 (按左右镜像方向)

· Map Shape Keys ⭐ — PMX morph 按所选 Style 重命名

· Drop Empty Shape Keys — 删几乎为 0 的 morph

· Clean Weights — 限制每顶点 4 骨 + normalize + 删空组

· Normalize Mesh Names — 按身体部位分组的 Wilds 命名

· Detect Physics Bones — 识别 hair/skirt/cloth/accessory

· Create Skirt Aux Bones — 生成裙子辅助骨

· Create Physics + Collision — Chain2 + CLSP，自动套预设参数

· Generate MDF Draft — 扫描材质，输出 JSON

Settings

· Morph Style 切换：re_engine / arkit / vrchat / standard / keep_japanese

· 物理 / 缩放 / 姿态各项开关

· 每顶点最大权重数

· 保存/加载配置 JSON

Morph Preview ⭐

· 按 brow / eye / mouth / other 分类的滑块

· 对称对（_L/_R、Left/Right、左/右）旁边显示 ↔ 图标

· 一键 Reset 全部 morph 归零

Log

· 转换过程的实时日志（最近 30 条）

转换流程

自动化步骤

步骤；描述

导入 MMD 模型；使用 CATS 插件导入 .pmx/.pmd 文件

修复模型；删除锁定顶点组、分离网格

重命名骨骼；将 MMD 日文骨骼名转换为荒野骨骼名

贴图处理；生成 EMI 和 ATOS 贴图

需要手动操作

步骤；描述；原因

姿态调整；调整手臂为 T-Pose，手指并拢；每个模型姿态不同

缩放调整；将模型缩放到猎人大小；需要视觉对比

骨骼吸附；使用批量插件吸附骨骼；需要确认字典类型

贴图合并；将多个贴图合并为一张；需要判断部位划分

物理设置；创建物理链和碰撞胶囊；需要判断物理类型

MDF 配置；设置材质路径和参数；路径需要精确匹配

导出封包；导出模型并封包；需要检查设置

骨骼映射表

脚本包含 MMD 到荒野的骨骼映射：

MMD (日文)；Monster Hunter Wilds

全ての親；root

センター；hip_HJ_00

上半身；spine_01

頭；head

左腕；arm_L

右腕；arm_R

左足；thigh_L

右足；thigh_R

...；...

完整列表见 mmd_to_wilds/data/bones.py（mmd_to_wilds/data/bones.py）。

表情 (Morph) 映射表

PMX → Standard EN → 目标 Style 的两段式重命名。以 RE Engine 为例：

MMD (日文)；Standard EN；RE Engine BlendShape

あ；A；BS_Mouth_A

い；I；BS_Mouth_I

まばたき；Blink；BS_Eye_Close

ウインク左；WinkLeft；BS_Eye_Close_L

笑い；BlinkHappy；BS_Eye_Happy

にっこり；Smile；BS_Mouth_Smile

照れ；Blush；BS_Cheek_Blush

怒り眉；BrowAngry；BS_Brow_Angry

涙；Tears；BS_Tear

ぺろっ；TongueOut；BS_Tongue_Out

...；...；...

完整列表见 mmd_to_wilds/data/morphs.py（mmd_to_wilds/data/morphs.py）（约 100 个 MMD morph，覆盖眉/目/口/其他四个 panel）。

ARKit Style 把多 shape 组合（如 eyeBlink_L+eyeBlink_R）展开成第一个，因为一个 Blender shape key 只能对应一个目标名。

贴图处理说明

EMI 贴图 (自发光)

二次元材质使用自发光贴图，需要调整以避免过亮：

· 亮度: 降低到 70% (0.7)

· 对比度: 降低到 50% (0.5)

· 饱和度: 增加到 130% (1.3)

· 曝光: 降低 (-1.0)

ATOS 贴图 (透明)

用于半透明材质（黑丝、半透明眼镜等）：

· R 通道存储透明度信息

· 从原图的 Alpha 通道提取

常见问题

Q: 进游戏卡在喝茶界面黑屏

A: MDF 贴图路径错误。检查：

· 路径是否完全正确

· 是否有多余或缺少的字符

· 格式是否为 .tex

Q: 模型全黑

A: 缺少材质或 MDF 配置错误。

Q: 物理不工作

A: 检查：

· Chain Header 是否设置为 Chain2 格式

· 物理骨骼链是否至少有 2 根骨骼

· Settings 参数是否正确

Q: 裙子穿模

A: 考虑使用绑腿方法而非辅助骨方法，或调整碰撞胶囊。