简介：面向Blender用户的暗影引擎模型处理插件包，专为游戏模组制作者设计，用于解决.e模型文件导入与.bin/.cal文件导出的问题。插件核心支持导入Telliamed的.e文件，并能借助BSP.exe与MeshBld.exe将对象和AI网格分别导出为.bin及.cal文件；其中bin导出代码改编自Elendir的Dark Exporter 2插件，导入过程中会自动转换图像格式以适配Blender，同时保留将纹理复制至txt16目录的可选条件设置，方便灵活控制资源路径。该工具包共包含19个文件，压缩包大小约1.82MB，其中以3个Python脚本作为插件主体，另含12张展示安装步骤、导出选项与界面配置的JPG截图，以及转换辅助程序、使用说明文档和许可证文件，使用者可对照截图快速完成安装并调整参数。目前已有308人在CSDN学习下载，特别适合需要频繁处理暗影引擎模型资源的进阶用户，能够显著提升模型资产在Blender与游戏引擎之间的转换效率，减少手工修改和重复操作。
1. NewDark 模型管线的三处断点：Blender Toolkit 补到了哪里
做 NewDark 模型的人基本都卡过同一条暗线：Blender 里模型建得再漂亮，导不进引擎就是白干。这套 Toolkit 把断点补得很明确——用 Blender 直接处理 .e 格式的中间模型文件，导入时顺手把引擎贴图转成 Blender 能认的格式，导出 .bin 时通过外部 BSP.exe 完成编译。也就是说，你不用再手动去凑 .e 文件，也不用担心贴图在 Blender 里一片黑。它适合给 NewDark 做静态物件、场景部件和武器模型的开发者；动画相关的东西它特意没碰，要去原版运动工具里做。下面我把安装、导入、导出的完整链路和踩过的坑拆开讲。
2. 安装与前置配置：BSP.exe 路径设置的三种常见翻车姿势
2.1 插件安装与 Python 环境确认
这套插件是标准的 Blender addon，安装方式跟大多数插件一致：把整个工具包目录拷到 Blender 的 addons 目录下，然后在偏好设置里启用。不过它依赖 Blender 内置 Python 环境，版本不匹配会出现一种很迷惑的现象——插件列表里能看到名字，勾选却报错。
我先说目录确认：
# Windows 下确认 addons 目录（Blender 版本不同，路径里的 x.x 会变） dir "%APPDATA%\Blender Foundation\Blender\3.6\scripts\addons" # Linux 下通常在： ls ~/.config/blender/3.6/scripts/addons/逻辑说明：Blender 的插件机制只从当前版本的 addons 目录加载，你把文件放错版本目录，它不会提示，而是直接不显示。我一般会先跑一下bpy.utils.script_paths()来确认实际加载路径。
参数说明：Blender 3.x 和 2.8x 的目录结构有差别，老插件经常因为 API 变更不能用，所以装完后首先看顶部菜单有没有新增的入口，而不是看偏好设置里的勾选状态。Python 版本方面，Blender 内置的是它自己带的那一套，跟系统 Python 没有关系，不需要额外 pip 安装什么，但如果插件用了第三方库，你会在启用时报 ModuleNotFoundError——这版本插件把图像转换限定在导入阶段，用到的图像库并不复杂，相对省心。
2.2 BSP.exe 路径的三种配置方式
导出 .bin 时必须调用 BSP.exe，这是 NewDark 的模型编译器。插件本身不直接写二进制，它生成中间 .e 文件，再把编译工作交给这个外部程序。路径配置直接决定你导出时是成功还是卡在“找不到文件”。
常见做法是在插件的偏好面板里填绝对路径，但不同人拿到的 SDK 包结构不一样，至少有三类配置方式：
# 形式一：插件 UI 面板里直接填 bsp_path = D:\NewDarkSDK\BSP.exe # 形式二：写在 config 文件里，插件启动时读取 [newdark] bsp_path = D:/NewDarkSDK/BSP.exe tex_dir = D:/NewDarkSDK/tex # 形式三：设置环境变量，插件运行时从环境取 # set NEWDARK_BSP=D:\NewDarkSDK\BSP.exe逻辑说明：插件导出前会校验这个路径，校验失败一般会弹一个“BSP path not valid”之类的提示。注意等号后面填的是 exe 文件本身，不是它所在的目录，这个最容易搞混。
参数说明：路径里最好别带空格和括号，BSP.exe 是从很老的命令行工具沿袭下来的，对路径解析比较敏感。我的习惯是，不管 UI 面板有没有提供“浏览”按钮，都手填一遍标准绝对路径，然后用正斜杠而不是反斜杠，避免转义符在配置读写时被吃掉。
2.3 装完先做一个五分钟导入测试
真正开始干活之前，先不要急着导自己的模型。找个现有的 .e 文件，走一遍“导入 → 看材质 → 看 UV → 删除”，确认环境没问题，再进入正式流程。
# 用 Blender 自带的 Python 控制台做环境自检 import bpy, os # 检查插件注册的导入器是否存在 importer = "import_newdark_e" print("importer registered:", importer in dir(bpy.ops)) # 检查 BSP.exe 路径是否有值 prefs = bpy.context.preferences.addons[__package__].preferences print("BSP path:", prefs.bsp_path)逻辑说明：dir(bpy.ops)能列出所有已注册的算子，如果导入器没注册，问题多半出在启用阶段而不是路径配置。prefs的字段名不同版本可能不一样，这里只是示意，你可以在插件源码里搜bsp_path确认。
参数说明：环境自检不通过时先看控制台完整报错，大多数问题在导入阶段就会暴露。这个测试花不了五分钟，能替你节省后面排查导出问题的时间。
3. 导入 .e 与图像转换：为什么只在导入期做一次转换
3.1 .e 文件的真实结构
.e 是这套工具链的中间模型格式，内容上相当于一个文本化的 3D 模型描述：顶点坐标、多边形面、UV 集、材质引用，以及可选的骨骼节点。旧版工具链处理的是另一种私有格式，这版本更新后把支持重心移到了 Telliamed 维护的那套 .e 文件上，等于统一了上游格式。
导入器读 .e 的时候会把每个材质引用映射成 Blender 的材质槽，同时把顶点数据填进 mesh。如果 .e 里带了骨骼，这版插件不会主动处理——它默认你只导静态模型，动画内容留给原版运动工具。所以一个带完整骨骼的 .e 文件导进来，你会看到网格正常，但骨架是空的或缺失的，这是正常现象，不是导入坏了。
贴图引用这块有讲究：.e 文件里的纹理字段通常是文件名而非完整路径，导入器需要自己去贴图目录里找同名文件。找不到时，Blender 里材质球是空的，模型显示成灰色或白色。
3.2 只在导入时转换，到底省了什么
引擎原生贴图是 .pcx / .gif 这类老格式，而且有的是带 mipmap 的变体，Blender 直接加载会出现颜色不对、打不开、或者拖进来变成黑块。这版本把转换逻辑限定在导入阶段——你在导入 .e 时，插件自动把引用到的贴图转成 PNG 并存到指定目录，同时建好 Blender 的 image 节点。
导出 .bin 时不再做图像转换，这是个刻意的设计：BSP.exe 编译时自己能按原始贴图路径去找 .pcx / .gif，不需要 Blender 把图片重新编码一遍。只转一次的好处是导入更快、工程文件更干净，也避免每次导出都重复转图浪费时间。
# 这是导入逻辑的简化示意，帮助理解转换时机 import bpy, os from PIL import Image def convert_texture_for_import(tex_path): ext = os.path.splitext(tex_path)[-1].lower() if ext in (".pcx", ".gif"): png_path = os.path.splitext(tex_path)[0] + ".png" # 只在目标 PNG 不存在时才转换 if not os.path.exists(png_path): Image.open(tex_path).save(png_path) return png_path return tex_path逻辑说明：关键词是“只在不存在时转换”。如果导入器每次都强制覆盖，你改过一遍贴图就会被打回原形。这里判断os.path.exists就是为了让第一次导入生成 PNG，之后 Blender 直接引用。
参数说明：转换后的 PNG 放在源贴图同目录，文件名保持一致，只换扩展名。这样材质球上的引用路径不会乱。如果你希望转换结果集中到一个目录，可以在插件偏好里找类似 texture_output_dir 的选项，但多数情况下同目录更省事，因为 .e 里的相对路径好维护。
3.3 材质槽和 UV 的对应规则
导入后你会看到 Blender 里建了和 .e 材质数一致的材质槽。一个常见的翻车点是：引擎贴图里有一部分是法线贴图和光照贴图，它们不是用来直接显示颜色，而是传给 BSP.exe 做特殊用途的。这种图如果导入时被当成 sRGB，颜色会亮得离谱。
我一般会手动把这类贴图的色彩空间改成 Non-Color，并确保 UV 层只有一个。多 UV 的模型要确认 .e 文件里写的 UV 集编号和 Blender 里选的 UV 层编号一致，否则导出后纹理位置全部错位。
材质命名最好保持 ASCII，不要带中文或特殊符号。.e 是文本格式，材质名会被直接写进中间文件，BSP.exe 对非 ASCII 字符串的处理常常会翻车，具体表现是编译成功但贴图错乱或模型崩溃。
4. 导出 .bin：社区导出插件代码改编后的执行链路与参数拆解
4.1 导出代码的血缘和它带来的兼容性特征
这版本的 .bin 导出代码是从社区早期一款 Dark 导出插件 2 改编来的。这段血缘关系决定了它的行为模式：遍历当前场景的 mesh 对象，收集顶点、面、UV、材质引用，再通过外部 BSP.exe 编译。
因为是改编代码，它保留了原插件的若干处理习惯，比如它会把 Blender 的 mesh 数据直接映射到 .e 的顶点缓冲，而不是走一遍 JSON 或别的中转格式。这意味着你在 Blender 里的三角面还是四边面会直接影响导出结果——BSP.exe 一般要求三角面，你最好在导出前把模型转成三角面，否则编译时它可能自己帮你切，但切出来的顶点顺序有时不对，导致法线方向莫名其妙地反转。
四边面转三角面这个操作，我建议在 Blender 里显式做一次，而不是靠 BSP.exe 隐式处理。你可以选中模型后在编辑器里按快捷键转，也可以在导出脚本里强制调用triangulate修改器。
# 导出前强制三角化的脚本片段 import bpy obj = bpy.context.active_object mod = obj.modifiers.new(name="TempTri", type="TRIANGULATE") mod.quad_method = "FIXED" mod.ngon_method = "CALC" # 让修改器生效 bpy.context.view_layer.update() # 导出完成后删除这个修改器 obj.modifiers.remove(mod)逻辑说明：quad_method控制四边形拆成两个三角形的方式，FIXED是固定对角线，结果稳定但可能不贴合 UV；CALC会按 UV 走向计算分割线，贴图更自然。静态物件我推荐CALC，因为 NewDark 场景里贴图对缝比多边形数更敏感。
参数说明：如果你在导出脚本里不想临时挂修改器，也可以在网格数据上用bmesh.ops.triangulate，效果一样但处理范围更可控。注意要在导出前更新 view_layer，否则修改器数据可能还没计算到位。
4.2 导出执行的完整序列
一次完整导出不是瞬时完成的，它的执行链路是：收集场景数据 → 写出临时 .e 文件 → 找到 BSP.exe → 调用它把 .e 编译成 .bin → 读回日志确认结果。
# 导出器内部执行链路的简化示意 import subprocess, os, tempfile def export_bin_from_blender(obj, out_dir): # 1. 在临时目录写出 .e tmp_e = os.path.join(tempfile.gettempdir(), obj.name + ".e") write_e_file(obj, tmp_e) # 2. 定位 BSP.exe bsp = get_pref("bsp_path") if not os.path.isfile(bsp): raise RuntimeError("BSP.exe not found, check path pref") # 3. 调用外部编译器，输入 .e，期望得到同名 .bin cmd = [bsp] cmd += ["-input", tmp_e] cmd += ["-output", os.path.join(out_dir, obj.name + ".bin")] proc = subprocess.run(cmd, capture_output=True, text=True) if proc.returncode != 0: raise RuntimeError(proc.stderr)逻辑说明：这个代码把流程拆成四个显式步骤，我在工程里看过不少导出失败案例，最后定位都是因为“BSP.exe 路径没配好”或“.e 写入失败”而不是编译本身。write_e_file是导入器的逆过程，正常情况下不会报错，除非你的模型里有非三角面或空材质槽。
参数说明：-input和-output这两个参数名在不同 SDK 版本里叫法可能不一样，有的版本直接用位置参数BSP.exe input.e output.bin。我写的是常见形态，你拿到手的 BSP.exe 如果不认识这两个参数，打开命令行无参数运行一次，看它打印的 usage 就知道真实写法。这里强烈建议第一次运行时保持控制台日志可见，不要静默调用，能看到真实错误输出。
4.3 BSP.exe 编译日志怎么看
BSP.exe 是黑匣子型工具，编译日志通常很短，成功时只输出个完成信息，失败时也经常只有一行。我整理了几个高频日志特征：
# 日志特征一：文件未找到 Could not open texture file: xxx.gif # 说明 .e 里引用的贴图路径不对，不是模型本身的问题 # 日志特征二：顶点数据异常 Error: Vertices count mismatch # 说明建模时有重叠顶点或非流形面，BSP.exe 算不出来 # 日志特征三：成功但无输出 Build finished with 0 errors # 如果这时 .bin 文件不存在，多半是输出路径没写对逻辑说明：大部分编译失败的根因不在编译期，而在数据准备期。我看到“Vertices count mismatch”这类错误时，第一反应是回 Blender 做merge by distance，把焊接点合并，再看看模型有没有内部面。
参数说明：如果日志提示贴图缺失，去 .e 文件所在目录找同名贴图，而不是去 Blender 的纹理节点里找。因为 BSP.exe 读的是 .e 里的相对路径，跟 Blender 材质的引用路径是两套体系。
5. 排查与避坑：五次翻车记录和对应日志特征
5.1 环境和路径类：三次路径相关的翻车
翻车记录一：BSP.exe 路径填成目录。
现象：导出时点击按钮完全没有反应，控制台不报错，或弹一个很笼统的 Path not valid。 原因：插件校验路径时用了os.path.isfile，你填的D:\NewDarkSDK是文件夹，校验直接返回 False。 解决：把路径补全到D:\NewDarkSDK\BSP.exe，确保末尾带 exe 文件名。路径里不要带引号，也不要带分号。
翻车记录二：路径里带空格导致编译静默失败。
现象：BSP.exe 能启动，但导出的 .bin 文件大小为 0 字节，或者根本没生成。 原因：这是老命令行工具的经典毛病，参数解析到空格处就断了，输入文件路径被截断，它去读了一个不存在的文件。 解决：把工具链整体放到一个纯 ASCII 且无空格的路径下，比如D:\NDTools\，不要放在Program Files下面，这是血泪经验。
翻车记录三：贴图路径里有中文。
现象：编译成功，引擎里模型加载正常，但贴图全部错乱或模型透明。 原因：.e 文件里写的中文路径在 BSP.exe 的旧文件 I/O 中解码不一致，贴图引用实际没找到，它用了默认白色贴图顶上。 解决：所有模型文件和贴图文件名统一用英文 + 数字，目录层级不要太深，最好不超过两级。
5.2 模型和材质类：两次数据准备相关的翻车
翻车记录四：模型外部更新了贴图，Blender 里导入的却是旧图。
现象：你在 Photoshop 里改了贴图存盘，切回 Blender 发现模型上的贴图没变，重新导入 .e 还是一样。 原因：这版本只在导入时做图像转换，转换后的 PNG 已经存在于磁盘，导入器看到目标文件存在就不覆盖，Blender 用的还是旧 PNG。 解决：把同目录下对应的 PNG 删掉，再重新导入 .e，让它重新转换一次。或者用 Blender 的 Image 节点手动重新加载文件。
翻车记录五：带骨骼的模型导出时报错。
现象：模型的网格导出成功，但引擎里加载时模型扭曲，或者直接崩溃。 原因：这版导出代码不处理骨骼数据，但 .e 文件里写了骨骼引用，BSP.exe 编译时找不到对应动画绑定。 解决：静态模型导出前把骨架对象删掉或隐藏，确保只导出纯网格。如果你确实需要带动画的模型，要去用原版运动工具，这个 Toolkit 管不了 .cal 运动数据。
6. 收尾验证：把 .bin 塞进引擎前要过的最后四道检查
导出 .bin 成功不代表真正做完，还需要四道检查。第一，确认 .bin 文件大小不是 0 字节，时间戳是最新的，这能排除路径截断导致的悬空写入。第二，检查 .bin 旁边的贴图引用是否正确——打开引擎的模型加载日志，看有没有 missing texture 字样。第三，单位制检查，在 Blender 里确认 1 个 Blender Unit 等于 1 个 NewDark Unit，否则模型进引擎后可能大得像一栋楼，这是最常见的静默问题。第四，三角面确认，选中模型打开属性面板看三角面计数，如果还有四边面残留，BSP.exe 虽然会隐式处理但结果不可控。
我最后会跑一个快速回归流程：导出一版 → 丢进引擎测试地图 → 绕模型走一圈看贴图方向 → 切回 Blender 改 UV → 再导出。这套流程看起来很机械，但能一次性把大部分问题兜住。
# 做一个简单的导出产物自检 # 检查 .bin 大小非零 ls -l props/statue.bin | awk '{print $5}' # 检查同目录贴图引用都存在 for f in statue.gif statue.pcx; do test -f tex/$f && echo "$f ok" || echo "$f missing"; done参数说明：awk '{print $5}'在 Linux 下打印文件大小字段，Windows 下直接用dir看就行。这个自检脚本不复杂，但它能在你快速迭代时省掉反复进引擎的等待时间。
说句实在话，我第一次用这套工具时也跳过中间自检，直接把 .bin 扔进引擎，结果模型加载出来是一堆错乱面片，花了一整天才定位到是三角化阶段的问题。从那以后我每次导出都强制走一遍上面的四道检查，再也没出过那种让人想删工程的怪问题。希望帮到你——把流程固定下来，NewDark 模型这条链路其实没有那么多玄学。
本文还有配套的精品资源，点击获取
