简介这份资源是面向《神偷》系列关卡与模组制作者的 Blender 插件工具包基于 Telliamed 的 .e 文件工具更新而来主要解决旧版工具在模型导入导出与贴图兼容性上的问题。插件支持导入 .e 文件借助 BSP.exe 导出对象 .bin 文件并通过 MeshBld.exe 导出 AI 网格的 .bin 与 .cal 文件还可按条件将对象纹理复制到 txt16 文件夹并设置例外规则适合具备一定 Blender 操作基础、需要制作或修改 Dark Engine 游戏资产的开发者。压缩包共 19 个文件约 1.82MB以 jpg 界面截图、py 插件脚本为主另含 exe 转换程序、说明文档与许可证文件截图覆盖安装、导入导出选项、纹理复制等关键界面便于对照配置。目前已有 310 人学习下载可帮助读者快速理解插件功能边界与参数含义减少摸索成本。1. 从一份 .e 文件说起这个 Blender 插件到底解决什么问题如果你手里有一批老游戏的关卡资源格式是.e文件想丢进 Blender 里看结构、改布局、再导回去那基本绕不开一个现实Blender 原生不认识这种格式直接拖进去只会得到一个空场景。这个 Toolkit 干的事很具体——它把.e文件导入 Blender让你在视口里看到几何体和贴图改完之后再导出成.bin交给后续的 BSP 编译流程。它不是一个通用格式转换器而是围绕「导入编辑、导出编译」这条链路做的专用工具。适合谁一类是想复现老关卡、做地图重制的开发者另一类是拿它当参考研究 Blender 插件怎么写自定义导入导出器的人。技术栈上主体是 Python 写的 Blender 插件导出环节依赖外部BSP.exe做最终编译。标题里那句「现在仅在导入期间转换图像」是个关键设计取舍后面会展开讲它为什么省事也为什么埋坑。2. 环境准备与插件安装把 Python 插件塞进 Blender2.1 先确认 Blender 版本和 Python 环境这类老插件最常见的翻车点不是代码写错而是 Blender 版本对不上。插件用的是 Blender 的 Python APIbpy不同大版本之间 API 变动不小尤其是导入导出相关的操作符注册、图像对象属性。我的建议是先锁定一个能跑通的版本再动手别一上来就用最新版。判断方法很简单打开 Blender 的脚本控制台敲两行import bpy print(bpy.app.version_string) # 看 Blender 版本 print(bpy.app.binary_path_python) # 看内置 Python 解释器路径老版本才有新版 Blender 已经不再暴露binary_path_python直接用系统 Python 版本对应关系判断即可。插件里如果用了bpy.ops.import_scene这类老式注册方式在 4.x 上大概率要改。我一般会先在 3.x 系列上验证功能确认逻辑没问题再往新版本迁移。2.2 安装路径与启用方式Blender 插件的安装有两种一种是通过偏好设置里的「从磁盘安装」另一种是手动把插件目录丢进 scripts 目录。对于这种带多个模块文件的 Toolkit手动放更可控因为你能直接看到目录结构、改代码、看报错。# 以 Linux 为例插件目录一般在用户配置下 # 把整个插件文件夹复制到 addons 目录 cp -r blender_newdark_toolkit ~/.config/blender/3.6/scripts/addons/Windows 下对应的是%APPDATA%\Blender Foundation\Blender\3.6\scripts\addons\。放好之后打开 Blender进偏好设置 → 插件搜索插件名启用。启用时如果控制台报ImportError八成是插件内部相对导入写错了或者某个依赖模块没跟着放进去。提示启用插件后一定要打开系统控制台看输出。Blender 的报错在界面里只显示一行真正的堆栈在控制台里排查导入失败全靠它。2.3 配置 BSP.exe 路径导出.bin依赖外部BSP.exe这是整个流程里唯一一个非 Python 的环节。插件不会自带这个可执行文件你得自己准备然后在插件设置里填路径。常见做法是在插件偏好设置里加一个StringProperty存路径导出时用subprocess调用。import bpy import subprocess # 从插件偏好设置读取 BSP.exe 路径 prefs bpy.context.preferences.addons[__package__].preferences bsp_path prefs.bsp_exe_path # 调用外部编译器传入中间文件和输出参数 result subprocess.run( [bsp_path, input_file, -o, output_file], capture_outputTrue, textTrue ) if result.returncode ! 0: print(BSP 编译失败:, result.stderr)这里input_file是插件导出的中间文件output_file是最终.bin。capture_outputTrue是为了把编译器的输出抓回来失败时能打印原因不然你只会看到一个「导出失败」的弹窗完全不知道是路径错还是参数错。路径里如果有空格subprocess用列表传参是安全的别自己拼字符串。3. 导入链路拆解.e 文件怎么变成 Blender 里的网格3.1 解析 .e 文件的入口逻辑.e文件本质是一种结构化的关卡描述里面包含几何、材质引用、实体信息。导入器的第一件事是读文件头、校验格式然后按块解析。插件里通常有一个主解析函数负责把二进制流拆成几何数据和元数据两部分。def parse_e_file(filepath): with open(filepath, rb) as f: data f.read() # 读文件头确认是合法的 .e 格式 header data[:16] if not header.startswith(bELEM): raise ValueError(不是有效的 .e 文件) # 按块解析每块有类型标记和长度 offset 16 meshes [] while offset len(data): block_type data[offset:offset4] block_len int.from_bytes(data[offset4:offset8], little) block_data data[offset8:offset8block_len] if block_type bGEOM: meshes.append(parse_geometry(block_data)) offset 8 block_len return meshes这段是导入器的骨架。header校验防止用户误选别的文件block_type和block_len是典型的块式二进制布局按长度跳读比按固定偏移硬读更稳因为不同版本的.e块顺序可能变。parse_geometry负责把顶点、面索引转成 Blender 能吃的列表这一步的字节序little必须和文件实际一致搞反了顶点坐标会变成天文数字。3.2 图像转换为什么只在导入时做标题里明确写了「仅在导入期间转换图像」这是个有意的设计。.e引用的贴图格式往往不是 Blender 直接支持的比如某些索引色或自定义压缩导入时转成 Blender 能识别的图像对象后续编辑和预览都正常。但导出时不再反向转换意味着你改过的贴图不会自动转回原格式得靠外部流程处理。def convert_texture(raw_bytes, name): # 把原始贴图字节转成 Blender 图像 img bpy.data.images.new(name, width0, height0) img.pixels decode_pixels(raw_bytes) # 解码成 RGBA 浮点数组 img.pack() # 打包进 .blend避免路径丢失 return imgdecode_pixels是格式相关的解码逻辑img.pack()很关键——不打包的话贴图只存路径换台机器打开就全丢。这个取舍的好处是导入链路简单、编辑体验好代价是导出时图像不做逆转换如果你在 Blender 里换了贴图得自己保证导出流程能处理。3.3 把网格挂到场景里解析完数据最后一步是创建 Blender 对象并链接到当前集合。这里容易忽略的是坐标系转换——老游戏的坐标系和 Blender 的 Z-up 往往不一致需要旋转或交换轴。def build_mesh_object(mesh_data, name): mesh bpy.data.meshes.new(name) mesh.from_pydata(mesh_data[verts], [], mesh_data[faces]) mesh.update() obj bpy.data.objects.new(name, mesh) bpy.context.collection.objects.link(obj) # 坐标系修正老格式多为 Y-up转到 Blender 的 Z-up obj.rotation_euler[0] 1.5708 # 绕 X 轴 90 度 return objfrom_pydata接受顶点列表和面索引列表面用顶点索引的元组表示。mesh.update()必须调用否则法线和包围盒不刷新视口里可能显示异常。旋转那行是经验值具体角度取决于源格式导入后如果模型躺倒或镜像先查这里。4. 导出链路与 BSP 编译从场景到 .bin 的完整流程4.1 导出器的数据收集导出是导入的逆过程但多了编译这一步。插件先从当前场景收集网格、材质、实体序列化成中间格式再交给BSP.exe。收集阶段要注意只导出选中的对象还是全场景这个策略直接影响结果。def collect_export_data(context): export_objs [o for o in context.scene.objects if o.type MESH] # 如果用户勾选了「仅导出选中」则过滤 if context.scene.newdark_export_selected_only: export_objs [o for o in export_objs if o.select_get()] data [] for obj in export_objs: mesh obj.data data.append({ name: obj.name, verts: [tuple(obj.matrix_world v.co) for v in mesh.vertices], faces: [tuple(p.vertices) for p in mesh.polygons], }) return datamatrix_world v.co把局部坐标转成世界坐标这一步不能省否则对象一旦移动过导出的位置就是错的。polygons的vertices是面索引直接拿来序列化。导出前建议先bpy.ops.object.transform_apply应用变换避免旋转缩放残留导致坐标偏差。4.2 调用 BSP.exe 的封装导出器把中间文件写到临时目录然后调BSP.exe。封装这层要做三件事拼参数、抓输出、清理临时文件。import tempfile, os def run_bsp_compile(bsp_path, export_data): tmp_dir tempfile.mkdtemp() mid_file os.path.join(tmp_dir, level.map) out_file os.path.join(tmp_dir, level.bin) write_intermediate(mid_file, export_data) # 写中间格式 proc subprocess.run( [bsp_path, mid_file, -o, out_file], capture_outputTrue, textTrue ) if proc.returncode ! 0: raise RuntimeError(fBSP 编译失败: {proc.stderr}) # 把结果复制到用户指定位置 shutil.copy(out_file, bpy.context.scene.newdark_output_path) shutil.rmtree(tmp_dir) # 清理临时目录tempfile.mkdtemp()保证每次导出用干净目录避免上次残留文件干扰。returncode判断是必须的BSP.exe失败时不一定抛异常只看有没有输出文件会误判。shutil.rmtree放最后失败时临时文件还在方便你进去看中间产物。4.3 导出参数与常见配置项参数作用常见取值BSP.exe 路径指定编译器位置绝对路径避免相对路径歧义仅导出选中控制导出范围大场景建议开启减少编译时间输出目录最终 .bin 落点独立目录别和源文件混放中间文件保留调试用排查编译错误时临时开启这张表里的「中间文件保留」是我自己调试时加的开关默认关掉。BSP.exe报错信息有时很含糊留着中间文件能直接看它到底收到了什么比猜快得多。5. 避坑与排查导入导出链路上的五个真实坑5.1 导入后模型全黑或贴图丢失现象模型进来了但材质是黑的或者贴图显示为粉色。原因通常是图像没打包或者材质节点没连上。解决检查img.pack()是否执行以及材质里Image Texture节点的image是否指向转换后的图像对象。粉色是 Blender 找不到图像文件的标志说明路径失效。5.2 导出 .bin 时 BSP.exe 直接退出现象点导出弹窗报失败控制台里BSP.exe没有任何输出。原因多半是路径含空格或中文或者BSP.exe依赖的运行库缺失。解决把BSP.exe放到纯英文短路径下用列表传参而不是拼字符串在命令行手动跑一次同样的参数看它自己报什么错。5.3 坐标系错乱导致模型躺倒或镜像现象导入后模型朝向不对导出回去位置也偏。原因源格式和 Blender 的 up 轴不一致且导出时没做逆变换。解决导入时统一做一次轴转换导出前用transform_apply固化变换保证来回一致。我一般会在导入后立刻检查包围盒尺寸尺寸对但朝向错就是轴的问题。5.4 插件启用时报 ImportError现象偏好设置里勾选插件控制台报No module named xxx。原因插件目录结构不对或者内部用了相对导入但没按包的方式放。解决确认插件文件夹里有__init__.py且整个文件夹是直接放在addons下不是多套了一层目录。5.5 大场景导出卡死或内存爆掉现象导出几十万个面的场景时 Blender 无响应。原因一次性把所有顶点转成 Python 列表再序列化内存翻倍。解决分块导出或者用foreach_get批量取顶点坐标比逐顶点循环快一个数量级。这个坑在中小场景不明显一到大图就暴露。6. 二次开发改造把导入器改成你自己的格式适配层这个 Toolkit 的价值不只在能用更在于它的结构清晰——解析、转换、构建、导出四段分离改起来有明确的切入点。如果你要接一种新的关卡格式最省事的做法不是重写而是把parse_e_file换掉保留后面的build_mesh_object和导出链路。具体改造思路先定义一套中间数据结构顶点、面、材质引用、实体让你的新解析器输出这个结构后面的构建和导出完全不用动。这样格式适配和 Blender 交互解耦测试也方便——解析器可以脱离 Blender 单独跑单元测试。# 中间数据结构约定新格式解析器只需产出这个 level_data { meshes: [ {name: wall, verts: [...], faces: [...], material: brick} ], entities: [{classname: info_player_start, origin: (0, 0, 32)}], }验证方法很直接拿一个已知能正常导入的.e文件用新解析器跑一遍对比顶点数和包围盒数值一致再进 Blender 看效果。导出侧同理先保证中间文件能被BSP.exe接受再调几何细节。一个具体技巧把BSP.exe的调用封装成可替换的「编译器后端」接口默认实现调外部 exe测试时换成 mock这样导出逻辑的单元测试不用真的跑编译。我当初没这么做每次改导出参数都得手动点一遍 Blender来回几十次才定位到一个参数拼错血泪经验。从那以后我每次接新格式都先把解析器单独跑通、和原工具的输出做数值比对再往 Blender 里塞。希望帮到你。本文还有配套的精品资源点击获取