FFXIV TexTools 模型导入自救手册：一张五步排查清单，专治发黑、反光乱闪和细节消失

FFXIV TexTools 模型导入自救手册：一张五步排查清单，专治发黑、反光乱闪和细节消失

【免费下载链接】FFXIV_TexTools_UI项目地址: https://gitcode.com/gh_mirrors/ff/FFXIV_TexTools_UI

如果你正在用 FFXIV TexTools 往游戏里塞自定义模型，大概率撞上过这类邪门事：模型明明导进去了，预览里却黑成一团；转个视角，金属高光像霓虹灯一样乱跳；明明烘了高模细节，进游戏却完全看不出来。这三件事看起来毫无关联，其实九成都是同一条数据链——法线（描述物体表面朝向的向量）——在某个环节断了。这篇文章给你一张"五步排查清单"，照着勾，从现象到根因挨个排除，配合两三条能直接复制的命令行，让你 20 分钟内从"看着黑"到"查明白、修得掉"。

开场：你导入的模型为什么会"物理性变黑"

先说个有点反常识的事实：FFXIV TexTools 导入的模型发黑，很多时候根本不是模型文件坏了，而是引擎拿到了一组"方向全反"或"全是零"的法线数据。法线这东西，通俗讲就是引擎判断"这个表面该朝哪个方向反光"的依据。数据一旦归零或者翻转，光照计算就会把表面当成"照不到光"来处理，于是整个模型就成了一块纯黑的剪影——你看着像坏档，其实只是方向信息出了问题。

另一层麻烦在于，FFXIV 用的是左手坐标系（DirectX 体系），和你在 Blender 里默认的那套习惯正好是镜像关系。你辛辛苦苦烘好的法线图，导进来时 Y 轴（上下方向）可能整个反了，游戏里看就是高光位置全错位。接下来这张清单，就是把这类问题一次性拆干净。

先背下这张五步排查清单，再动手改东西

下面的流程图是整篇文章的主线：遇到任何光照异常，先别急着重导，按顺序过五项检查，命中哪项就修哪项。

划重点：清单的顺序不是随机的——前两项解决"黑和暗"，第三项解决"闪"，第四项解决"糊"，第五项解决"进不去"。从前往后过，绝大多数问题在第 2、3 步就被拦下了。

清单第一项：法线贴图本身是不是已经"空"了

症状：模型整体一片死黑，任何角度、任何光源下都毫无反应，仿佛一块黑板。

快速诊断：把法线贴图从游戏包里导出来，用下面这段代码扫一遍，统计"空像素"占比。这里把贴图按 RGBA 四个通道逐像素读出来，如果某像素的 RGB 三个通道全是 0，就意味着这条法线压根不存在。

// 诊断代码：统计法线贴图里的"死像素" using var img = Image.LoadPixelData<Rgba32>(rawBytes, width, height); int dead = 0, total = 0; foreach (var p in img.Frames[0].Pixels) { total++; // 正常法线的 RGB 不会同时为 0；同时为 0 说明该点无朝向信息 if (p.R == 0 && p.G == 0 && p.B == 0) dead++; } // 死像素超过 1%，基本可以判定贴图本身废了 Console.WriteLine($"dead ratio: {(double)dead / total:P2}");

根治方案：

1. 在 TexTools 里用"导出原始纹理"把法线图存成 TGA（32 位无损格式，别存 JPG）。
2. 回 3D 软件里重新烘焙一张法线图，务必在烘焙设置里勾选"翻转绿色通道 / Flip Green"。
3. 重新导入，导入类型明确选"法线贴图"，不要选成普通彩色贴图。

这里最容易翻车：把法线图当成 RGB 普通贴图保存过一次，再去转格式。压缩是有损的，一旦在"RGB 贴图"的语义下走过一轮，方向信息就再也救不回来了，只能重新烘。

清单第二项：Y轴到底翻没翻，决定了你是发黑还是发亮

症状：模型有高光，但高光位置全错——该亮的地方黑，该黑的地方亮，整体像"负片"。

快速诊断：对着法线贴图看 B 通道（蓝色通道）。用任意通道查看器把 B 通道单独拎出来，如果大面积是黑而不是灰白，说明 Z 轴（里外方向）数据异常；再检查 G 通道，若高光区域在 G 通道上明暗分布"明显不对称"，基本就是 Y 轴反了。

根治方案：FFXIV 是 DirectX 体系，法线图必须满足"绿通道向下"的约定。修正代码如下，保留 R、B、A，只对 G 做 255 取反：

// 修复代码：反转法线图的 G 通道（Y 轴） var fixedPixel = new Rgba32( src.R, // R 通道管左右方向（X 轴），原样保留 (byte)(255 - src.G), // G 通道管上下方向（Y 轴），DX 体系下要取反 src.B, // B 通道管里外方向（Z 轴），原样保留 src.A // Alpha 通道，通常用不到，跟着走即可 );

根治方案（另一条路）：如果不想动贴图，也可以在建模软件里处理——Blender 导出 FBX 时勾选"翻转 Y 轴"，Maya 则把坐标轴预设切成"3ds Max"风格再导。两条路二选一，别都做，否则负负得正又错回去。

记住这三步：先确认坐标系是 DirectX → 再确认绿通道方向 → 最后才动文件。

清单第三项：切线数据是"自己算的"还是"文件自带的"

症状：模型表面光泽随视角剧烈跳动，一会儿亮得刺眼，一会儿糊成一片，像表面涂了层液态金属。

快速诊断：把视角贴近模型边缘缓慢旋转。如果高光在某个临界角度突然"啪"地翻转，十有八九是切线空间（法线贴图依赖的局部坐标框架）算错了——要么是文件自带的数据不对，要么是工具重算时的焊接方式跟你模型拓扑不匹配。

根治方案：TexTools 的模型导入面板里有一个开关叫Use Imported Tangents（使用导入的切线），位置在导入模型视图的选项行中，对应的界面文件是 ImportModelView.xaml，逻辑在 ImportModelViewModel.cs 里。它决定一件事：法线贴图依赖的切线、副切线是用文件自带数据，还是由 TexTools 重算。

• 如果模型是从 Blender/Maya 烘焙后原样导出的，勾选它，尊重原始数据。
• 如果模型是从游戏里改装的、拓扑被改过，取消勾选，让工具基于 UV 重算。

命令行场景下，项目自带的 ConsoleTools/Program.cs 提供了等价开关：

# 使用 ConsoleTools 包装模型为游戏格式 # /tangents 等价于勾选"使用导入的切线"，让工具尊重文件自带的切线数据 TexTools.Console.exe /wrap model.fbx out.mdl "chara/human/c0101/model/c0101_top.mdl" /tangents

这里最容易翻车：改过拓扑却不取消勾选，或者反过来，原封不动的模型却勾了重算。记住一句话——"谁动过模型谁负责切线"，拓扑没动就用原数据，动过就让工具算。

清单第四项：UV和纹理有没有被悄悄移位

症状：纹理本身没问题，但贴图上的人物花纹、纹路在模型上横着长、斜着歪，法线细节完全对不上位置。

快速诊断：把模型切到"线框/UV 叠加"预览，对照 UV 展开图看贴图布局。如果发现 UV 整体偏了半格，或者第二套 UV（通常用于特效/次表面散射）跟第一套对不上，就是这里的问题。

根治方案：导入时把 UV 相关的选项盯紧。ConsoleTools 里两个相关开关值得记住：/shiftuvs（关闭 UV 移位自动校正）和/cloneuv2（把 UV1 克隆成 UV2，适合那些引擎需要第二套 UV 的装备）。

# 关闭 UV 自动移位 + 克隆第二套 UV TexTools.Console.exe /wrap body.fbx out.mdl "chara/human/c0101/model/c0101_body.mdl" /shiftuvs /cloneuv2

避坑提示：很多新人以为"保留原始 UV"一定对，其实 TexTools 的 UV 自动移位是为了对齐引擎内部的分区约定。你判断不了时，先按默认导入，进预览看贴图对齐度，不对再关掉重导——多一次导入，成本远低于对着错位贴图瞎猜。

清单第五项：Modpack是不是还活在旧版本

症状：导入不报错，模组也显示安装成功，但进游戏没效果，或者某些部位直接变回默认外观。

快速诊断：看模组包的格式后缀——.ttmp是旧格式，.ttmp2是新格式。大版本更新（比如 7.0 黎明之路）后，旧包进游戏常出现"装了等于没装"。

根治方案：用 ConsoleTools 的升级命令把旧包批量翻新：

# 把旧版 modpack 升级到新版本格式 TexTools.Console.exe /upgrade old_pack.ttmp old_pack_new.ttmp2

升级后再重新安装，走一遍游戏内验证。相关实现可参考 ModpackUpgraderWrapper.cs。

避坑提示：升级不是万能的。如果包里的模型本身是坏的法线数据，升级只改包装不改内容，照样翻车。所以第五项永远放在前四项之后查。

把这五项串起来：一次完整的自查流程

把故障现象对号入座后，用这张速查表做最后定位。它和前面的流程图互相印证，适合打印出来贴在显示器边上：

原理小课堂①：法线图的 RGB 为什么能当方向用

理解这件事，前面的修复逻辑就全通了。法线图本质是给每个像素发一张小纸条，纸条上用 R、G、B 三个数字记着"这个表面朝哪边"。但这三个数字存的不是 -1 到 +1 的真实方向，而是被压缩成 0 到 255 的整数刻度。着色器里那句BiasX2（定义在 Common.hlsl）干的事，就是把刻度从"0~1"换算回"-1~+1"的真实朝向。这就像量体温，温度计上刻的是 0~100，你得知道刻度和真实摄氏度的换算关系，否则 37 会被读成 3.7。

原理小课堂②：切线空间就是"贴纸怎么贴"的说明书

为什么"闪"要查切线而不是查法线？因为法线贴图里的方向是相对局部的，它只告诉你"这个小面片朝哪偏"，不告诉你"面片本身朝哪"。真正把局部方向和模型全局方向对接起来的，是切线、副切线这套框架，行话叫切线空间。你可以把模型想象成一张贴纸：UV 负责"把贴纸撕下来摊平画图案"，切线负责"这张贴纸在模型上是横着贴还是竖着贴"。横竖搞反了，图案（法线细节）自然就长倒了。游戏引擎里那套t1 / t2 / n的组合，见 psCustomMeshBlinnPhong.hlsl 的calcNormal函数，就是在运行时把这三者拼起来算最终光照方向。

原理小课堂③：BCn 压缩为什么能"毁掉"法线

第三个原理帮你理解"为什么不能乱转格式"。游戏内部法线数据用 BCn 系压缩存储（一种把颜色块近似量化的 GPU 纹理压缩），类似把一首歌压成 MP3：码率够高时听着还行，但原始相位信息一旦录反，整首歌就像从门缝里漏出来。法线图的每个通道只有 8 位整数，任何一次"RGB 语义"下的有损转换，都可能把方向信息彻底抹掉。所以前面反复强调：法线图永远走无损的 TGA 通道，别碰 JPG，别碰 RGB 语义。

源头预防：三个养成习惯，比修 bug 值钱

1. 给文件起"能说话"的名字。推荐格式：种族_性别_部位_版本_用途.fbx，例如Midlander_F_Top_v1.2_NormFix.fbx。修过法线的文件，一定要在名字里留痕，否则一周后你自己都分不清哪个是修过的。
2. 每次改动只动一个变量。要么只反转 G 通道，要么只改切线选项，要么只动 UV，不要三件事一起做。否则出了问题，你根本不知道是哪一步修的。
3. 保留"出厂数据"。原始 FBX、原始法线贴图、第一次导入前的备份，单独放一个目录不动。所有修复都基于副本操作。

当模型预览阶段就显示"无图"占位，往往是贴图引用或格式问题的第一个信号，别急着往下查

上自动化：把检查写成脚本，一劳永逸

手动排查总有漏网之鱼。把下面的往返测试脚本挂到 CI 或定时任务里，每提交一批模型就跑一遍——任何一步报错，都会在日志里留下文件名。脚本里的命令来自 ConsoleTools/Program.cs，支持wrap（包装）与unwrap（拆包）两个动作，正好可以做"包装→拆包"的完整性往返校验。

# 批量往返测试：包装再拆包，任何一步报错都会暴露问题文件 for f in ./models/*.fbx; do TexTools.Console.exe /wrap "$f" "./out/$(basename "$f" .fbx).mdl" "chara/human/c0101/model/c0101_top.mdl" /tangents \ && echo "OK $f" \ || echo "FAIL $f" done

跑批处理时界面会进入排队状态，看到加载动画转起来属于正常现象，耐心等它跑完即可：

批处理期间工具会进入加载态，脚本跑完会在终端逐行打印 OK/FAIL 清单

如果想在本地跑这些命令，需要先拿到源码。克隆仓库地址如下，命令行批处理项目在ConsoleTools目录，编译后即可使用：

git clone https://gitcode.com/gh_mirrors/ff/FFXIV_TexTools_UI

接下来往哪走

• 下一步行动：把本文的五步清单存成你自己的"导入前检查卡"，从下一个模型开始强制走流程；同时把那段往返测试脚本加到你的文件提交流程里。
• 延伸学习方向：往深处可以研究两件事——一是psCustomMeshBlinnPhong.hlsl里的光照模型，弄懂它你就明白高光为什么对法线如此敏感；二是 FFXIV 的模型文件.mdl格式本身，理解顶点、切线、副切线的存储布局，很多玄学问题会瞬间变透明。

版本与使用须知

本文方案基于 FFXIV TexTools 2.x 系列及当前 DawnTrail（7.x）时代验证，早期 1.x 版本的选项位置和命令参数可能存在差异。命令行工具的参数以你本地ConsoleTools /?输出的帮助为准。另外提醒一句：修改游戏文件属于灰色地带操作，请遵守 SE 的用户协议，做出来的东西自己用或小圈子分享就好，别拿去碰官方服务。本文引用的界面、源码路径均指向项目内真实文件，如 ImportModelView.xaml、ConsoleTools/Program.cs，动手前可先翻一翻源码确认当前版本的准确行为。

【免费下载链接】FFXIV_TexTools_UI项目地址: https://gitcode.com/gh_mirrors/ff/FFXIV_TexTools_UI