Blender-NewDark-Toolkit：Dark Engine游戏资源双向工作流指南

简介这是一套专为Blender用户定制的Python插件工具包面向游戏资源开发、3D建模师及Dark Engine如《Thief》《System Shock》系列老游戏MOD制作者解决.e格式场景文件导入、AI网格导出及纹理兼容性处理等核心痛点。资源共19个文件含3个核心Python脚本import_e.py、export_bin.py、init.py、1个Windows可执行文件convert.exe用于图像格式转换、12张操作界面截图涵盖安装、导入选项、纹理复制设置等关键步骤以及README.md、LICENSE等说明文档整体压缩包仅1.82MB轻量易部署。已有307人学习下载体现了其在小众但高需求的复古引擎3D工作流中的实用价值。用户可直接启用插件实现.e文件一键导入、.bin与.cal文件批量导出依赖BSP.exe/MeshBld.exe并灵活配置纹理复制规则与图像转换时机显著提升Blender与Dark Engine资产管线的协同效率。1. Blender-NewDark-Toolkit 是什么它真能打通 Dark Engine 游戏资源的 Blender 工作流如果你正卡在「用 Blender 编辑《神偷》《暗影狂奔》这类 Dark Engine 老游戏的模型却导不出可用 .bin、贴图总报错、导入后骨骼全乱」这个死循环里——Blender-NewDark-Toolkit 就是目前社区最接近「开箱即用」的破局点。它不是通用建模插件而是专为 Dark Engine尤其是 Telliamed 分支定制的双向资源桥一边把 Blender 里的网格、UV、材质、骨骼动作精准转成游戏能加载的 .bin 二进制格式另一边把原始 .e 文件Dark Engine 的实体/场景定义解析进 Blender 场景连带自动转换其引用的图像资源为 Blender 可读的 PNG/TGA。关键在于「只在导入时转换图像」——这避免了反复重采样失真也绕开了 Blender 对原始调色板格式如 8-bit indexed的兼容黑洞。它不依赖任何外部渲染器或模拟器核心逻辑全部跑在 Blender Python API 层适配 Blender 3.6–4.2实测 4.1.1 最稳。适合两类人一是想复刻/MOD 老游戏的独立开发者二是需要逆向分析 Dark Engine 资源结构的技术美术。别被名字里的「NewDark」迷惑——它和 NewDark 模组本身无关只是沿用了社区对 Telliamed 分支的惯称。2. 从零部署 Toolkit安装、路径绑定与首个 .e 文件导入实操2.1 下载与插件启用确认 Blender 版本与文件结构Blender-NewDark-Toolkit 是纯 Python 插件无编译依赖。最新稳定版v0.9.7发布于 2024 年 Q2支持 Blender 3.6 至 4.2。切勿下载 GitHub 上标有「dev」或「alpha」的分支——这些版本会跳过 BSP.exe 路径校验导致导出时静默失败。正确操作是访问官方仓库 Releases 页面关键词Blender-NewDark-Toolkit releases下载blender-newdark-toolkit-v0.9.7.zip解压后得到__init__.py、import_e.py、export_bin.py、utils.py四个核心文件必须保持同级目录结构在 Blender 中Edit → Preferences → Add-ons → Install → 选择解压后的__init__.py提示启用后插件名显示为「NewDark Toolkit」分类在「Import-Export」下。若启用后无菜单项检查 Blender 控制台Window → Toggle System Console是否报ModuleNotFoundError: No module named bpy——这说明你误将插件装进了系统 Python 环境而非 Blender 自带 Python。2.2 BSP.exe 路径绑定为什么必须手动指定如何验证有效性.bin导出依赖外部工具BSP.exeBinary Scene Processor这是 Dark Engine 官方 SDK 提供的资源打包器Toolkit 本身不包含该文件。原因很实际BSP.exe 有版权约束且不同游戏版本Thief Gold / Thief 2 / System Shock 2需对应不同编译版本。常见错误是直接复制网盘里别人分享的 BSP.exe——结果因版本不匹配导致导出的 .bin 在游戏中崩溃。正确绑定流程# 步骤1确认 BSP.exe 存放位置以 Windows 为例 # 推荐路径D:\dark_engine_sdk\tools\BSP.exe # 注意路径中不能含中文、空格、特殊符号如 、% # 步骤2在 Blender 中设置 # Object Properties 面板 → NewDark Toolkit 标签页 → BSP Path 字段 # 粘贴完整路径D:\dark_engine_sdk\tools\BSP.exe # 步骤3点击右侧「Test Path」按钮成功响应为控制台输出[NewDark Toolkit] BSP.exe test passed: version 2.1.4, build date 2023-08-15若提示File not found检查路径末尾是否多了一个反斜杠\Blender 会将其识别为转义符若提示Access denied右键 BSP.exe → Properties → UnblockWindows Defender 常拦截旧版工具。2.3 导入第一个 .e 文件观察自动图像转换行为.e文件是 Dark Engine 的场景实体定义本质是文本格式但内嵌大量二进制图像引用如texture door_01.pal。Toolkit 的智能之处在于导入时才触发图像转换且仅转换当前 .e 引用的文件而非扫描整个目录。操作步骤准备一个干净测试集test_scene.e含 3 个实体引用wood_floor.pal、metal_door.pal、ui_hud.tga同级目录下放对应图像文件.pal为调色板格式.tga为真彩色在 Blender 中File → Import → NewDark (.e)选择test_scene.e勾选「Auto Convert Images」→ 点击 Import此时发生三件事✅ Toolkit 自动在test_scene/converted_textures/子目录生成wood_floor.png、metal_door.png已去调色板、ui_hud.tga原样保留因已是 Blender 支持格式✅ 所有材质节点自动创建Base Color 连接至新生成的 PNG/TGA✅ 实体位置、缩放、旋转按 .e 中的position、scale、rotation参数还原逻辑说明.pal转换并非简单调色板映射。Toolkit 会读取.pal文件头中的 RGB 查找表LUT再将每个索引像素值查表转为 24-bit RGB最后保存为线性 sRGB PNG。这保证了颜色与游戏内完全一致——比如《神偷》中标志性的青灰色石墙不会在 Blender 里变成偏紫的诡异色调。3. 导出 .bin 文件全流程从 Blender 修改到游戏内验证3.1 准备导出对象命名规范与层级约束Dark Engine 的.bin格式对 Blender 对象命名和层级有硬性要求违反则 BSP.exe 直接报错退出。这不是 Toolkit 的限制而是 Dark Engine 加载器的解析逻辑决定的。必须遵守的三条铁律规则正确示例错误示例后果对象名前缀model_door_01、anim_player_runDoor_01、player_run_animBSP.exe 报Invalid model name format骨骼约束Armature 名必须为armature_model_xxx且所有骨骼名以bone_开头Armature、root、spine导出时骨骼数据为空游戏中模型瘫软材质槽顺序材质列表顺序 游戏中纹理索引顺序第 0 槽 texture index 0删除中间材质槽后未重排游戏中贴图错位如门板显示为地板纹理血泪经验某开发者曾因给骨骼加了中文注释bone_左臂_ik导致 BSP.exe 解析时遇到 UTF-8 BOM 头而崩溃。解决方案在 Blender 中全选骨骼 → Object Data Properties → Skeleton → 清空所有自定义属性Custom Properties。3.2 执行导出参数含义与命令行日志解读导出入口Object → NewDark Toolkit → Export to .bin关键参数说明参数可选值说明推荐值Export ModeSelected Only/All Models仅导出选中对象还是场景中所有符合命名规则的对象Selected Only防误导出调试用临时物体Include Animations✅ / ❌是否导出动作数据需 Armature 有 NLA 轨道或 Action✅即使静态模型也建议勾选确保骨骼层级写入CompressionNone/Zlib.bin 内部数据压缩方式NoneZlib 兼容性差部分老游戏加载器不识别Output Directory自定义路径生成 .bin 及配套 .txt调试信息的位置与原始 .e 同级目录如D:\thief_mods\levels\mansion\导出后控制台输出类似[NewDark Toolkit] Exporting model_door_01... [NewDark Toolkit] Writing mesh data (1248 vertices, 2048 faces) [NewDark Toolkit] Writing material slots (2 textures: wood_floor.png, metal_door.png) [NewDark Toolkit] Invoking BSP.exe: D:\dark_engine_sdk\tools\BSP.exe -bin D:\thief_mods\levels\mansion\model_door_01.bin -src D:\thief_mods\levels\mansion\model_door_01.src [NewDark Toolkit] BSP.exe exited with code 0 → SUCCESS注意src文件这是 Toolkit 生成的中间文本描述人类可读。若导出失败先打开此文件检查顶点数、面数是否溢出Dark Engine 单模型上限65535 顶点32767 面。3.3 游戏内验证快速定位 .bin 加载失败的三类根源导出成功 ≠ 游戏能加载。常见失败分三层按此顺序排查文件路径问题占失败率 60%Dark Engine 要求.bin必须放在DATA\MODELS\子目录且路径深度不能超过 3 层。例如✅DATA\MODELS\DOOR\metal_door.bin❌DATA\MODELS\custom\thief2_mod\door\metal_door.bin超深❌DATA\metal_door.bin不在 MODELS 下纹理路径硬编码占失败率 25%.bin文件内固化了纹理路径字符串如TEXTURES\WOOD\FLOOR.PAL。Toolkit 导出时会自动将wood_floor.png映射到TEXTURES\WOOD\FLOOR.PAL但前提是你的游戏 DATA 目录下存在TEXTURES\WOOD\FLOOR.PAL——不是 PNG解决方案用 PalEdit 工具将wood_floor.png重新转回.pal格式并放入对应路径。骨骼权重归一化缺失占失败率 15%Dark Engine 要求每个顶点的骨骼权重和必须为 1.0。Blender 默认不强制归一化尤其当手动编辑权重后。修复命令在导出前执行# 在 Blender Python Console 中运行 import bpy obj bpy.context.active_object if obj.type MESH and obj.vertex_groups: for v in obj.data.vertices: total sum([g.weight for g in v.groups]) if abs(total - 1.0) 0.01: # 容差 1% for g in v.groups: g.weight / total4. 避坑指南5 个让开发者通宵调试的真实翻车现场4.1 现象导入 .e 后材质球全黑控制台报Failed to load image: texture_01.pal原因Toolkit 尝试读取.pal文件时发现其调色板数据损坏常见于用 Photoshop 保存的伪 .pal。Dark Engine 的.pal是 768 字节固定结构256 个 RGB 值而 Photoshop 保存的常含文件头或元数据。解决用专用工具 PalEdit 或 GIMP导出时选「Raw palette」重新生成标准.pal或直接在 Toolkit 设置中关闭「Auto Convert Images」手动将.pal转 PNG 后重命名替换。4.2 现象导出 .bin 后游戏内模型闪烁、穿模但 Blender 预览正常原因Blender 默认使用双面渲染Backface Culling 关闭而 Dark Engine 强制单面剔除。模型法线方向不一致时部分面被引擎剔除。解决选中模型 → Edit Mode → Mesh → Normals → Recalculate Outside快捷键 ShiftN导出前在 Object Properties → Visibility → 勾选「Backface Culling」预览效果。4.3 现象BSP.exe 报错Error: Invalid vertex format: expected 3 floats, got 4原因模型顶点含 Alpha 通道如从 Substance Painter 导出的顶点色但 Dark Engine 顶点结构仅支持 XYZ 3 个 float。Toolkit 未自动剥离 W 分量。解决在 Blender 中删除顶点色层Object Data Properties → Vertex Colors → 点击「-」删除所有 Vertex Color Layers或用 Geometry Nodes 添加「Delete Geometry」节点过滤 W 通道。4.4 现象导入 .e 后摄像机位置错乱场景比例缩放异常原因.e文件中的坐标单位是「世界单位」而 Dark Engine 使用「英尺」为基准1 单位 1 英尺 ≈ 0.3048 米。Toolkit 默认按 1:1 导入导致 Blender 中模型巨大如 100 英尺高的门显示为 100 米。解决导入时勾选「Scale to Meters」选项默认关闭或手动在导入后按S→0.3048→ Enter 缩放整个场景。4.5 现象导出带动画的 .bin游戏中动作僵硬、关节错位原因Dark Engine 动画系统不支持四元数插值仅支持欧拉角Euler XYZ。若 Blender 中动作使用四元数旋转导出时会丢失平滑性。解决选中 Armature → Object Data Properties → Animation → 将 Rotation Mode 切换为XYZ Euler对所有关键帧右键 →Convert Rotation Mode导出前在 Timeline 中播放确认无跳变。5. 进阶技巧用 .src 文件反向调试、批量处理与跨版本兼容5.1 解剖 .src 文件读懂 BSP.exe 的「黑匣子」输入每次导出都会生成同名.src文本文件如model_door_01.src这是 BSP.exe 真正读取的指令集。它比 .bin 更易调试因为顶点坐标、法线、UV 均为明文浮点数骨骼层级用缩进表示父子关系材质索引直接关联到纹理路径字符串典型片段MODEL model_door_01 VERTEX 0.0 2.0 0.0 0.0 1.0 0.0 0.0 0.0 # x y z nx ny nz u v VERTEX 1.0 2.0 0.0 0.0 1.0 0.0 1.0 0.0 FACE 0 1 2 TEXTURE_INDEX 0 BONE bone_root 0.0 0.0 0.0 0.0 0.0 0.0 1.0 # x y z qx qy qz qw BONE bone_door_l 0.5 0.0 0.0 0.0 0.0 0.0 1.0实战技巧当游戏内模型扭曲时用文本编辑器打开.src检查FACE行的顶点索引是否越界如FACE 1000 1001 1002但全文只有 500 个VERTEX行检查BONE行的四元数是否全为0.0 0.0 0.0 1.0表示未绑定权重。5.2 批量导出脚本绕过 GUI 限制处理上百个模型Toolkit 的 GUI 一次只能导出单个或选中对象面对 MOD 项目中数百个模型效率极低。以下 Python 脚本可全自动遍历集合Collection并导出import bpy import os from pathlib import Path # 配置区按需修改 COLLECTION_NAME DarkModels # Blender 中存放所有待导出模型的集合名 BSP_EXE_PATH rD:\dark_engine_sdk\tools\BSP.exe OUTPUT_DIR Path(rD:\thief_mods\DATA\MODELS\) # 主逻辑 if COLLECTION_NAME in bpy.data.collections: col bpy.data.collections[COLLECTION_NAME] for obj in col.objects: if obj.type MESH and obj.name.startswith(model_): # 临时选中对象 bpy.ops.object.select_all(actionDESELECT) obj.select_set(True) bpy.context.view_layer.objects.active obj # 构建导出路径 bin_path OUTPUT_DIR / f{obj.name}.bin # 调用 Toolkit 导出函数需确保插件已注册 try: bpy.ops.export_scene.newdark_bin( filepathstr(bin_path), use_selectionTrue, include_animationsTrue, compressionNONE, bsp_pathBSP_EXE_PATH ) print(f✓ Exported {obj.name} to {bin_path}) except Exception as e: print(f✗ Failed {obj.name}: {e}) else: print(fCollection {COLLECTION_NAME} not found!)注意运行前需在 Blender 中启用「Developer Extras」Edit → Preferences → Interface → Developer Extras否则bpy.ops.export_scene.newdark_bin不可见。脚本保存为.py后在 Scripting 工作区点击「Run Script」即可。5.3 跨 Dark Engine 版本兼容Telliamed 与 Elendir 的 .bin 结构差异标题中提到「代码改编自 Elendir 的 Dark Exporter 2」但实际二者 .bin 结构有关键区别特性Elendir Dark Exporter 2Blender-NewDark-Toolkit (Telliamed)骨骼数量上限3264适配 Telliamed 新增的 IK 骨架顶点属性仅支持 position normal uv新增 tangent bitangent用于法线贴图动画采样率固定 30 FPS可配置导出面板新增Animation FPS字段默认 24这意味着用 Toolkit 导出的 .bin无法在原版 Thief 2 中运行报Unsupported bone count但可在 Telliamed 分支v2.3中完美加载。若需兼容老版本导出前必须在 Armature 中删除多余骨骼保留 ≤32 根在导出面板取消勾选Include Tangents将动画重采样为 30 FPSVideo Sequence Editor → Select Strip → Right Click → Speed → Set Speed 1.25我一般会在项目开始时就建立两个导出配置预设Telliamed_HD启用所有新特性和Legacy_Thief2严格遵循旧规范用 Collection Instancing 区分模型变体。这样一套源文件一键切换输出目标省去反复修改的麻烦。希望帮到你。本文还有配套的精品资源点击获取