GIMI 故障排查指南：从安装、Blender 导入导出到游戏内渲染的 3DMigoto 模型问题系统化解决方案

本篇指南以 GI-Model-Importer（GIMI）仓库的 Troubleshooting 文档 为主体，面向所有使用 3DMigoto GIMI 工具链向游戏导入自定义模型的玩家与制作者，系统梳理从加载器安装、Blender 插件导入导出，到游戏内最终渲染效果这一完整链路中最常见的问题与解决方案。读完本文，你将掌握一套可对照执行的排查清单：包括 d3dx.ini 配置检查、ModelData/Mod 目录区分、导出前 7 项校验、顶点组与顶点色（COLOR）修复、轮廓厚度脚本化调整，以及如何借助仓库内脚本与源码定位根因。

排查前的第一原则：确保全部组件为最新版本

在尝试本页面任何修复手段之前，请先确认三样东西都是最新的：3dmigoto 插件、角色数据文件、辅助程序。绝大多数用户遇到的问题都源自旧版本工具，例如本指南「模型导出问题」中提到的"旧版本插件 bug"、"旧插件只支持 Blender 2.80-2.92"等错误，都是版本过期的典型表现。

• 3dmigoto 加载器与 Blender 插件（blender_3dmigoto_gimi.py，仓库 Tools 目录提供）需要配套更新；
• 角色原始模型数据来自独立的数据仓库，需与 GIMI 版本匹配；
• 各辅助脚本（Tools 目录下的 genshin_*.py）同样以仓库内最新版本为准。

注意：本仓库 README 同时声明，独立的 GIMI 已弃用，官方推荐改用 XXMI loader 自动加载所需文件与库；仓库内指南与脚本虽部分过时，但其中包含的排查思路与数据结构信息仍然有效。此外，GIMI 是专为兼容目标游戏而修改的 3DMigoto 版本，强烈建议仅在私服上使用模组工具，在官方服务器上使用存在封号风险。

安装问题（Installation Issues）

安装阶段最常见的问题集中在三个点上，逐一核对即可覆盖大部分场景：

1. d3dx.ini 中游戏 .exe 路径是否正确。Genshin 安装目录下有两个 .exe，一个是启动器（launcher），一个是游戏本体，你需要指向后者（通常位于 "Genshin Impact Game" 文件夹内）。v7 及以上版本的 GIMI 会自动处理该步骤，可以跳过。若手动填写路径不生效，可尝试改用 target = GenshinImpact.exe。
2. 绿色文字不显示。绿色 overlay 文本是开发版专有功能，仓库 README.md 明确说明：仓库提供两个版本 —— "3dmigoto-GIMI-for-development.zip"（开发版，全部功能开启，含屏幕顶部/底部的绿色文本，速度较慢）与 "3dmigoto-GIMI-for-playing-mods.zip"（游玩版，关闭开发功能，无绿色文本，速度更快）。如果用的是游玩版，没有绿色文本是正常现象，不代表注入失败。
3. 加载器与游戏是否以管理员身份运行。请同时以管理员权限运行 3DMigoto Loader 和游戏本体。

两个容易误判的"正常现象"

• loader 控制台窗口在游戏加载后关闭：这是预期行为，无需担心。
• 出现 "Unable to verify if 3dmigoto successfully loaded" 提示：这不意味着注入失败，只是加载器无法确认注入状态。如果游戏内表现正常（绿色文本与 mod 均生效），可以直接关闭该窗口——事实上应当关闭，因为这个窗口一直开着会导致电脑变慢。

与其他工具共存与偶发注入失败

3dmigoto 可以与其他类型的游戏修改工具或加载器同时运行，唯一要求是先启动 3dmigoto loader，再启动其他程序。另外，偶尔即使一切配置正确，3dmigoto 也会注入失败——此时重新尝试注入即可解决。

模型导入问题（Model Importing Issues）

导入是指把游戏原始模型数据从磁盘载入 Blender 进行编辑的阶段。

文件夹为空：选错数据源

如果在 Blender 导入面板中看不到任何内容，请确认你从 ModelData 文件夹加载数据，而不是 Mod 文件夹（当前不支持从 Mod 文件夹加载）。正确数据源文件夹中应包含 .vb 与 .ib 的 .txt 文件——这正是收集脚本处理帧转储后产出的格式（见 genshin_3dmigoto_collect.py，其 output_results 函数会按 名称-组件-vb0=哈希.txt、名称-组件-ib=哈希.txt 的命名写出文件）。

加载报错：插件版本过旧

如果加载模型时报错，说明插件过时——旧版插件只支持 Blender 2.80–2.92。请更新到 blender_3dmigoto_gimi.py 对应的最新插件版本。

其他加载错误：绝大多数源于模型数据本身

除了插件版本问题，几乎所有的加载错误都源于模型数据异常，最常见的是 4D 法线（4D normals）。其成因是收集脚本在转储时把模型的某个分量误标为法线。这一点在源码中有直接对应：在 genshin_3dmigoto_collect.py 的 collect_buffer_data 函数中，当检测到语义名为 NORMAL 的顶点分量长度为 4 且第 4 个值不为 0 时，会输出 ERROR: Incorrect NORMAL identified 并提示"程序误将其他分量识别为 NORMAL"，推荐的解决方案是使用 --force 参数强制脚本在正确的 draw id 上运行；也可以选择 y 继续导出（但需要在 Blender 中重算法线，且重新导入时可能遇到问题）。

模型导出问题（Model Exporting Issues）

导出是把编辑后的模型从 Blender 写回游戏可读取格式的阶段。排查之前，请先对照以下导出前检查清单逐项确认：

• 对象命名：场景中待导出的对象必须命名为 ObjectHead、ObjectBody、ObjectDress、ObjectExtra，且每个名称只允许存在一个（数量取决于原始模型实际拥有的部件数）；
• 导出目录与文件名：必须导出回原始模型来源的 ObjectData 文件夹（不是 Mod 文件夹），文件名为 Object.vb；并确认目标文件夹中存在 hash.json（该文件由收集脚本生成，见 genshin_3dmigoto_collect.py 中写出 hash.json 的代码；生成脚本 genshin_3dmigoto_generate.py 也会通过 load_hashes 读取它来完成后续拆分）；
• 部件数量一致：导出的部件数量必须与被替换的原始模型一致；
• 不允许完全空对象：场景中所有导出对象至少保留一个面（可以缩到极小来隐藏），否则 UV 无法正常导出；
• 3dmigoto 自定义属性：所有对象必须具备 3dmigoto 自定义属性，方式有二——与最初用插件导入的对象合并，或运行自定义属性转移脚本 blender_custom_property_transfer_script.txt（该脚本通过 Blender 的 bpy.data.objects[original][k] 把源对象的属性键值复制到目标对象，默认用法是先点击接收方、再 Ctrl+点击源对象，并确保源对象最后被选中；若报错，请确认已按脚本内说明替换对象名称）；
• UV 命名：UV 贴图必须命名为 TEXCOORD.xy、TEXCOORD1.xy、TEXCOORD2.xy… 直到覆盖原始模型拥有的贴图数量；
• 顶点色：模型必须有顶点色，且颜色分量命名为 COLOR。

借助控制台窗口定位导出错误

Blender 导出过程中会输出详细信息，打开控制台窗口（如 Blender 的系统控制台）能获得比插件面板更具体的报错内容，这是定位导出问题最直接的手段。

常见导出错误一览

现象	根因	处理方式
导出后模型错乱/文件未被识别	没有导出回 ObjectData 文件夹，或文件名不是 Object.vb	检查导出目标目录与文件名
文件命名相关报错	命名不正确	确保文件名严格为 Object.vb
"某组件出现多次"报错	场景中存在重名对象（如 HuTaoBody 出现两次）	删除或重命名组件，直到该名称唯一
自定义属性转移脚本报错	未在 Blender 中替换脚本内的对象名称	按脚本注释将 transfer_to / transfer_from 替换为实际对象名
COLOR 相关报错	COLOR 分量缺失或命名错误	确认顶点色存在且命名为 COLOR
顶点数超限报错	模型顶点超过 64k	删除部分顶点，或使用 Decimate 减面
空对象相关报错	某个对象完全为空	至少保留一个面，确保 UV 可导出
莫名导出错误	旧版本插件的 bug	更新插件版本

游戏内模型问题（In-game Model Issues）

这是排查中最棘手的部分——从 Blender 导出成功到游戏内正确显示，中间还有大量变量。下面按问题类别逐一拆解。

模型完全不加载

依次确认：3dmigoto 确实在运行；mod 已放置到正确的 Mods 文件夹；在游戏内按 F10 重载已变更的 mod。若以上都无误仍不加载，尝试清空 ShaderCache 与 ShaderFixes 文件夹——这两个缓存目录有时会干扰 mod 加载。

模型加载了，但部分部件未被绘制

这类问题源于模型的顶点限制（vertex limit）。凡是带 blend weights / 顶点组的对象，都需要在 3dmigoto 的 dll 中提高顶点上限才能正常绘制；作者已为大多数角色调高，但仍有遗漏。在仓库生成脚本 genshin_3dmigoto_generate.py 中可以看到应对手段：它会为带 blend 数据的部件额外生成 [TextureOverride{name}VertexLimitRaise] 覆盖段（代码注释明确写到"These are custom commands GIMI implements, they do not need a corresponding command list"），这正是配合 dll 顶点上限机制的配套设置。

大量 mod 冲突警告

冲突警告（warning）源于游戏试图将多个文件加载到同一个 hash。常见原因：同时为同一角色启用了两个 mod；或旧版本工具存在 bug，导致共享的脸部组件在多个位置被覆盖。

修复方法：删除重复的 mod 文件夹；若确定已全部删除而警告仍在，则打开警告中提到的 .ini 文件，删除或注释掉对应行。

模型加载报错 / 游戏内不显示

与警告不同，error 通常意味着程序加载 mod 失败，常见原因有三：

1. 名称不正确：.ini 中的名称与文件夹内的实际文件名不一致（例如扩展名不同）；
2. 纹理格式错误：对照原始文件确认格式——通常为 .dds，且宽高必须是 2 的幂，并保持整数比例，如 1024x1024、2048x2048、1024x2048 等；
3. 顶点组缺失：原模型有顶点组，而新模型没有绘制/转移任何顶点组。此时应使用 Blender 的权重转移功能，或借助仓库脚本处理顶点组（见下文「顶点组修复脚本」小节）。

对象方向错误

这是因为 Blender 中由 3dmigoto 导入的对象与你要替换的新模型使用了不同的坐标系。即便两者在 Blender 中看起来对齐了，实际可能仍需要相对 3dmigoto 模型进行旋转与平移才能获得正确方向。最常见的做法：将角色模型旋转 90 度使其朝上，然后全选并 Apply All Transforms（应用全部变换）。原文档以"旧模型（枫原万叶 Kazuha）与新模型（诺艾尔 Noelle）方向正确对齐"作为示例场景。

模型完全错乱（FUBAR）

大概率是顶点组问题：顶点组的数量、顺序、位置必须在新旧模型间一一对应。检查要点：

• 新模型中所有顶点组都存在；
• 顺序正确——例如原顺序 4 6 7 8 5 应调整为 4 5 6 7 8；
• 无缺口——例如 4 7 8 9 应补全为 4 5 6 7 8 9。

模型轻微错乱（略微 FUBAR）

仍然是顶点组问题：除复查上述顺序与缺口外，还需确认新模型在该区域的权重（weight）与原模型一致。

顶点组修复脚本（仓库配套工具）

针对顶点组顺序、缺口、映射问题，仓库 Tools 目录提供了四个 Blender 脚本（在 Blender 的 Scripting 工作区运行）：

• blender_fill_vg_gaps.txt：为当前选中对象补齐缺失的顶点组并排序——例如对象有组 0 1 4 5 7 2，它会补出 3、6 并排序为 0 1 2 3 4 5 6 7；可通过修改脚本中的 largest 变量强制生成到更大编号；
• blender_merge_vg.txt：把同前缀的顶点组合并为一个（多组批量版 Vertex Weight Mix），默认模式 3 合并全部组，也可改用模式 1（指定组名列表）或模式 2（编号区间）；合并后建议再跑一次 blender_fill_vg_gaps.txt 补缺口；
• blender_vg_remap.txt：把一个模型的顶点组重命名为与另一模型尽可能匹配并补齐缺口（实验性，只改名不改权重；使用前请先合并重复顶点）；它用 KDTree 做最近邻匹配，源码注释记录了实现思路；
• blender_remove_unused_vertex_groups_script.txt：删除未被顶点引用的空顶点组，用于清理。

另外，复杂外部模型（如 MMD 模型）导入游戏前往往需要简化骨骼结构，可使用 blender_bone_deletion_script.txt 把选中骨骼的权重转移到其最近的未选中父骨骼后删除该骨骼。

纹理不正确

纹理显示错误可能由多种原因造成，最常见的是：

1. UV 贴图未命名为 TEXCOORD.xy；
2. 法线反转（reversed normals）；
3. ObjectTexcoord.buf 损坏或不正确；
4. 忘记用新纹理替换，仍在加载原始模型的旧纹理。

纹理过亮 / 发光

这通常是因为使用的纹理图没有 alpha 通道。处理原则：在任何纹理文件顶部保留一个透明层——顶层用于控制自发光（emission）并决定亮度，底层用于绘制模型颜色与图案。更详细的纹理制作流程可参考仓库的 TextureModdingTutorial.md 与 EffectModdingTutorial.md。

轮廓过厚或颜色异常

根因是顶点 COLOR 值不正确。三种修复手段：

1. 复制正确轮廓数据：从原始模型轮廓正确的部件上复制 COLOR 数据到新模型对应位置；
2. 脚本调整轮廓厚度：使用 genshin_set_outlines.py。用法：把脚本放进 mod 文件夹，执行

   python genshin_set_outlines.py --thickness t
   

   其中 t 为 0–255 的整数：0 表示无轮廓，255 表示最大轮廓。多数游戏模型取值在 80–130 之间，但建议针对自己的模型实测调优。从源码看，该脚本会在当前目录查找唯一的 *Texcoord.buf 与唯一的 .ini 文件，从 ini 中解析出 stride，然后遍历 texcoord 缓冲区，把每个顶点的第 4 个字节（即 COLOR 的 alpha 通道）改写为指定厚度值——这也印证了轮廓厚度由顶点色 alpha 通道控制的底层机制；
3. 完全移除轮廓：可把 --thickness 设为 0 实现等效效果（原文档引用的独立 genshin_remove_outlines.py 在当前仓库中未提供，仓库内 genshin_set_outlines.py 的头注释也说明它"比移除轮廓脚本更强"）。

此外，仓库还提供 genshin_set_color.py 用于强制设置 texcoord 输出中 COLOR 分量的 RGBA 值，适用于角色边缘轮廓异常的场景，典型用法：

python genshin_set_color.py -n CharTexcoord.buf --stride X -a 0

其中 X 为 stride（多数情况为 12 或 20，可在 mod 文件夹 ini 的 texcoord 配置中核对），-a 0 表示将 alpha 置 0 以移除轮廓。源码中每个颜色通道都校验了 0–255 取值范围，输出写为 原文件名Modified.buf。

其他罕见问题（"古神图"合集）

这些现象正常使用中很少出现，但值得了解其成因，均可在帧转储的 .ini / 缓冲区文件中核对：

• .ini 中 stride 不正确：stride 与缓冲区实际布局不匹配；
• IB 与 VB 不匹配：索引缓冲区与顶点缓冲区来自不同对象或版本错配；
• 在 VB 上覆盖而非 IB：覆盖目标选错缓冲区类型，导致数据绑定错误。

这些都与 3dmigoto 对 VB/IB 哈希与 draw call 的匹配机制直接相关，修复时需回到帧转储数据重新核对哈希与格式。

模型转储问题（Model Dumping Issues）

原文档明确说明该章节"即将到来"——模型转储脚本仍处于实验阶段。不过仓库已提供对应的核心脚本 genshin_3dmigoto_collect.py，其用途是：把 3dmigoto 帧转储（FrameAnalysis 文件夹）中分散在多个缓冲区（position/blend/texcoord、IB、diffuse/lightmap 纹理等）的角色数据收集、校验并组织成 Blender 插件可识别的 .vb0/ib 文本文件，同时生成 hash.json。该脚本源码中包含了与故障排查直接相关的设计：

• 通过 -vb 指定主绘制 VB 哈希，-vs 指定根 VS（默认 653c63ba4a73ca8b），-f 指定帧转储文件夹（缺省取最近一次）；
• --force / --force_object 可在自动匹配失败时强制指定 draw id 或对象，是解决"缓冲区尺寸不匹配""错误 NORMAL 识别"等问题的关键参数；
• --remove_sanity 可关闭 sanity check（作者在注释中自嘲"也是我调试了一整天后的感受"）；
• 当 position、blend、texcoord 三个缓冲长度不一致时会报错并提示使用 --force 指定 draw ids。

反向流程（把 Blender 导出拆分为游戏所需缓冲区并生成 .ini）由 genshin_3dmigoto_generate.py 完成，它读取 hash.json、生成 <角色名>Mod 文件夹与 Position.buf/Blend.buf/Texcoord.buf 及纹理资源，并写出完整的 [TextureOverride]/[Resource] 配置。若你在转储或生成阶段遇到问题，这两个脚本的命令行参数与源码注释是最直接的排查依据。

排查思路总结与脚本索引

当游戏内模型表现异常时，推荐按以下顺序收敛问题：

1. 版本核对 → 插件、角色数据、脚本全部为最新；
2. 加载链路核对 → 3dmigoto 运行中、mod 在正确 Mods 文件夹、已按 F10 重载、必要时清空 ShaderCache/ShaderFixes；
3. 导出数据核对 → 对照「导出前检查清单」逐项检查命名、目录、部件数、空对象、自定义属性、UV 命名、COLOR；
4. 数据结构核对 → 顶点组数量/顺序/缺口/权重、顶点数上限、纹理格式（dds、2 的幂尺寸）、stride 与 IB/VB 匹配；
5. 脚本工具介入 → 顶点组用 blender_fill_vg_gaps.txt / blender_merge_vg.txt / blender_vg_remap.txt 修复；轮廓用 genshin_set_outlines.py 或 genshin_set_color.py 调整；mod 合并用 genshin_merge_mods.py（可生成按键切换的合并 mod，注意冲突警告与 ini 去重）；透明度可用 genshin_set_transparency.py（-b/-hd/-d/-e 选择部件、-t R G B 调透明度）。

相关阅读：完整的工具使用流程见 UsageInstructions.md；逐步上手实例见 MonaWalkthrough.md（移除角色部件）与 BananaWeaponWalkthrough.md（自定义武器）；纹理与特效方向见 TextureModdingTutorial.md 与 EffectModdingTutorial.md。安装步骤与两个发行版（开发版/游玩版）的区别见 README.md。