简介这款Blender插件专门用于导入导出OGRE引擎中广泛使用的.mesh格式模型文件解决Blender默认不支持该格式、网上现有方案多为老旧失效链接的痛点适合游戏美术、资源转换人员以及需要处理Kenshi等以.mesh存储模型的开发者。插件包共7个文件其中5个Python脚本构成Blender端导入导出核心逻辑另有1个OgreXMLConverter.exe负责格式转换、1个OgreMain.dll提供运行依赖整体压缩包仅2.29MB轻量且便于部署。已有4157人学习下载。安装并激活插件后Blender即可直接读取和写出.mesh模型在导入的同时保留网格基础结构配合附带转换工具可应对常见OGRE资源减少手工转换和时间成本尤其适合在DCC工具链中快速打通旧模型资产。1. Blender 导入导出 .mesh 格式文件为什么值得自己把流程走通你手头有一个 Blender 文件角色绑好了骨骼材质也贴好了引擎那边只要.mesh格式文件。Blender 的默认导入导出列表里没有它网上教程各讲一半有的只给 XML 版本、有的只讲导入不讲导出、有的导出以后顶点散成一片。我按「Blender 导入导出 .mesh 格式文件」这条链路反复调过几轮把从拆包二进制、重建网格到带骨骼导出的一整套流程整理成了下面的脚本思路亲测好用。写这篇东西不是为了让你去下载某个黑匣子插件而是把格式拆开给你看让新手能照着一行行敲出来让熟手能直接拿去接进自己的管线。适合技术美术、独立开发者和正在接引擎管线的同学照着做一遍能省下至少两天的查错时间。这套格式的麻烦点在于它不是通用容器而是某个开源引擎定义的网格交换格式。导入导出的难点从来不是 Blender 侧的操作而是坐标轴、单位、索引分段、骨骼权重上限这些「两边约定不一致」的地方。只要把这几处约定对齐整条链路就稳了。2. 先搞懂 .mesh 里存了什么按数据块拆包而不是按行读文件.mesh文件的核心结构是 Header 加一串 chunk每个 chunk 前 8 字节是 ID 和长度后面跟着数据。很多人拿十六进制工具打开文件就晕就是没意识到「这不是文本是块状协议」。导入脚本的第一步永远不是读顶点而是先把 chunk 边界找对否则后面全是乱码。2.1 一个 .mesh 文件由哪些数据块拼成数据块存放内容典型布局Header魔数、版本号、格式标记一段 ASCII 头或固定字节Geometry顶点位置、法线、UV 集、骨骼权重每顶点定长 float 数组IndexBuffer三角形索引uint16 或 uint32按 submesh 划分区间Submesh材质名、索引起点/数量、几何类型字符串 数值区间SkeletonLink绑定的骨骼文件名、蒙皮矩阵字符串 16 个 float 矩阵Bounds模型 AABB 包围盒6 个 float这里面最容易踩坑的是 Geometry 块。位置、法线、UV、权重通常会凑在同一个顶点缓冲里引擎靠 stride步长和 offset 定位每段数据。不同版本的引擎字段顺序可能完全不同有的是位置、法线、UV有的是位置、UV、法线。你在文本编辑器里看到一整排浮点数却分不清哪个是哪个原因就在这。解析时必须先拿到底层声明的顶点布局再按偏移量切片不能按「第几个 float 是 x」这种猜法写。2.2 选二进制变体而不是 XML三个现实理由引擎在导出.mesh时有的版本会同时生成一份.mesh.xml用于编辑器预览。我的建议是正式流程只解析二进制二进制文件小一个数量级加载快引擎侧不会卡顿XML 的字段顺序在不同版本间差异大解析代码容易被版本牵着走现有工具链基本都走二进制写出来的脚本换到别的项目也能复用XML 也别扔留作排错参考。某块解析对不上时把 XML 打开对比字段顺序能省不少时间——这属于典型的「别人踩过但你还没踩」的坑。2.3 插件骨架怎么搭一个 IO 脚本 两个 Operator 入口常见做法是把插件拆成三个文件导入和导出逻辑分开避免一个.py文件里又处理读取又处理写入几百行之后自己都找不到函数在哪。bmesh_io/ __init__.py # 注册入口 import_mesh.py # 导入逻辑 export_mesh.py # 导出逻辑__init__.py只做一件事注册两个 Operator并把它们挂到 Blender 的导入导出菜单。先看注册部分import bpy class MESH_OT_import(bpy.types.Operator): bl_idname import_mesh.file bl_label Import .mesh filepath: bpy.props.StringProperty(subtypeFILE_PATH) def execute(self, context): load_mesh(context, self.filepath) return {FINISHED} def menu_import(self, context): self.layout.operator(MESH_OT_import.bl_idname, textImport .mesh) def register(): bpy.utils.register_class(MESH_OT_import) bpy.types.TOPBAR_MT_file_import.append(menu_import) def unregister(): bpy.types.TOPBAR_MT_file_import.remove(menu_import) bpy.utils.unregister_class(MESH_OT_import) if __name__ __main__: register()为什么导入和导出要分开两个 Operator因为导入没有context.object处理逻辑和撤销栈都不一样分开注册还能在 File 菜单里各自挂一个入口功能边界清晰。注意load_mesh别写死在execute里拆成独立函数后面命令行批处理和回读验证都要直接调它。这段骨架看起来简单但它决定了后面所有代码能不能被复用。我见过太多插件把解析逻辑全塞在 Operator 里结果想跑自动化测试的时候连 context 都 mock 不出来只能卸了插件手动点菜单。3. 导入 .mesh拆出顶点、索引、材质一口气建出网格导入前先准备一个最小的.mesh文件随便建一个立方体用引擎自带的工具导出来。然后用hexdump -C file.mesh | head -n 8看前 64 字节确认魔数和块头格式这一步能帮你少走很多弯路——不同引擎分支的魔数不一样网上抄来的脚本不匹配第一行就报错。3.1 魔数与 chunk 主循环三种写法里挑最稳的读取 chunk 有三种常见写法按struct.Struct定长解包、按类型映射字典、整块读进内存再切片。我一般用第一种逻辑直接、性能也够。核心循环长这样import struct def read_chunks(fp, end_offset): 读取后续所有 chunk每个 chunk 由 块ID(4B) 长度(4B) 数据 组成 chunks [] while fp.tell() end_offset: chunk_id, size struct.unpack(II, fp.read(8)) payload fp.read(size) chunks.append((chunk_id, payload)) return chunksII的意思是小端序、两个无符号 32 位整数。前一个I是块 ID后一个I是数据长度。这里有个细节长度是「后面跟随的数据字节数」不含这 8 字节头。有些旧版本引擎会写「含头长度」一旦按错整条流就歪掉了这种现象常被误判成「文件损坏」。注释里的end_offset一般是文件总大小减去 Header 长度。如果解析到某个 chunk 后fp.tell()跳过了end_offset先别急着改读取逻辑回去查长度字段是不是含头。我在这上面吃过一次亏整整花了半天排查。3.2 顶点缓冲怎么变成 Blender 网格拿到 chunk 之后把 Geometry 块里的顶点按 stride 切片IndexBuffer 里的数字按 submesh 分段然后一次性交还给 Blenderimport bpy def build_object(context, name, verts, tris, mat_names): mesh bpy.data.meshes.new(name) mesh.from_pydata(verts, [], tris) mesh.update() for m in mat_names: mat bpy.data.materials.get(m) if mat is None: mat bpy.data.materials.new(m) mesh.materials.append(mat) obj bpy.data.objects.new(name, mesh) context.scene.collection.objects.link(obj) return obj逻辑说明from_pydata接收三个参数——顶点坐标列表、边列表留空、面列表。这里的tris必须是每个三角形三个角顶点的索引而且顺序要和引擎侧 IndexBuffer 一致。mesh.update()在填充数据后调用作用是重建内部拓扑结构不加它的话后面的 UV 赋值可能报「mesh has no valid loops」。UV 也别漏赋值要按 loop 而不是按 vertexdef assign_uv(mesh, uv_data): if not uv_data: return uv_layer mesh.uv_layers.new(nameUVMap) for loop_idx, uv in enumerate(uv_data): uv_layer.data[loop_idx].uv (uv[0], 1.0 - uv[1])注意1.0 - uv[1]这一句Blender 的 V 方向向下很多引擎是 V 向上不翻转的话贴图会上下颠倒。这是导入导出两端最容易错位的地方后面避坑章节会再展开。材质名映射也要处理引擎侧的材质名可能和 Blender 里的名字不一致常见做法是「有同名材质就用没有就新建」。很多模型从第三方工具导出来材质名里带空格、斜杠、中文引擎侧解析器不一定全都支持导入脚本里可以先做个清洗把非法字符替换成下划线。3.3 导入后三件必做的事第一法线。如果引擎在 Geometry 块里存了法线直接覆盖mesh.normals并调用calc_normals_split()没存就让 Blender 按平滑组重算。注意calc_normals_split在 Blender 3.x 之后的行为有过变化用之前先查一下当前版本的 API 签名。第二双 UV。很多模型带第二套 UV 用于光照贴图导入时若只建一套 UV材质球一烘焙就会错位。我一般会在导入参数里加一个uv_names列表支持按名称批量建 UV 层。第三骨骼。如果文件里带 SkeletonLink 块导入后要建一个空的 Armature 对象把骨骼文件名和绑定矩阵挂到对象的rotation_euler/location上。这一步不做后面刷权重或做动画展示时模型会摆不对姿势。4. 导出 .mesh从 Object 到二进制包四个参数设一次就过导出比导入看起来简单——数据都在 Blender 里直接读出来写文件就行。但实际上Blender 里的网格形态和引擎侧期望的数据之间隔着一层「翻译」修改器、三角化、索引偏移、权重上限每一项都可能导致导出文件在引擎里渲染成另一副样子。4.1 第一步先拿一份干净的 mesh 快照导出前别直接读obj.data那个是基础网格没算修改器。美术在 Blender 里看的是细分、镜像、实体化之后的形态引擎要的也是这个最终结果。正确做法是拿依赖图求值后的临时网格def snap_mesh(obj, apply_modifiers): deps bpy.context.evaluated_depsgraph_get() if apply_modifiers: eval_obj obj.evaluated_get(deps) mesh eval_obj.to_mesh() else: mesh obj.data.copy() return mesh参数apply_modifiers默认为True。什么时候设成False导出低模碰撞体或者烘焙用的代理模型时要的是原始拓扑这时候开修改器反而帮倒忙。还要注意eval_obj.to_mesh()拿到的网格是临时对象用完要记得eval_obj.to_mesh_clear()否则内存会一直涨批处理导几十个文件时 Blender 直接崩掉。拿完快照后先三角化再去重mesh.calc_loop_triangles()如果不调用calc_loop_triangles()mesh.loop_triangles就是空的导出文件里一个三角形都没有。另外直接用mesh.loops的顶点索引拼三角形会发现同一个顶点被重复写了好几次——因为每个 loop 对应一个「顶点在某条边上的使用」而不是顶点本身。导出前要按「位置 法线 UV」建一个去重映射把重复顶点合并否则文件体积膨胀三倍引擎加载还变慢。4.2 顶点打包与索引分段二进制写入的核心单顶点打包这块常见引擎的布局是固定 48 字节位置 12 字节、法线 12 字节、UV 8 字节、骨骼索引与权重 16 字节。写成代码就是import struct def pack_vertex(position, normal, uv, bone_index, bone_weight): 默认顶点布局pos(12B) normal(12B) uv(8B) 4骨骼索引(8B) 4权重(16B) fmt 3f3f2f4H4f return struct.pack(fmt, *position, *normal, *uv, *bone_index, *bone_weight)3f是 xyz第二个3f是法线 xyz2f是 uv 的 u 和 v4H是四个无符号短整数骨骼索引最后的4f是四个 float 权重。如果引擎用的是另一种布局比如法线在最后只需要调整fmt字符串和参数顺序函数的骨架不用动。索引写入要特别注意 submesh 偏移def pack_submesh(sm, index_bits): fmt H if index_bits 16 else I indices [i sm.base_vertex for i in sm.indices] return struct.pack( fmt * len(indices), *indices)每个 submesh 的索引是相对自身起点的写入文件时必须加上base_vertex偏移否则第二个材质块的所有三角形都会错误地引用顶点缓冲的开头几个点渲染出来就是一堆三角形互相乱穿。这个base_vertex的值怎么拿常见做法是写入第一个 submesh 前记下已写入顶点数下一个 submesh 就从那里开始加。4.3 带骨骼的角色权重要截断到引擎上限Blender 允许一个顶点绑很多个顶点组但引擎一般只认 4 个骨骼影响。导出前做两步截断到前 4 个再归一化。def top4_weights(obj, vert_index): groups obj.data.vertices[vert_index].groups pairs [(obj.vertex_groups[g.group].name, g.weight) for g in groups] pairs.sort(keylambda x: x[1], reverseTrue) # 按权重降序保最重要的骨骼 pairs pairs[:4] total sum(w for _, w in pairs) or 1.0 # 避免除零 return [(name, w / total) for name, w in pairs]注意排序这行——顶点组的顺序在groups列表里是按添加顺序排的不是按权重排的。不排序直接取前 4 个很可能把权重 0.6 的主骨骼丢掉留下三个 0.1 的次要骨骼动画时模型局部塌陷。另外归一化把剩余权重重新按比例分配保证四个权重之和等于 1否则总和只有 0.7骨骼收不住力。骨骼索引的映射也在这里做把顶点组名转成引擎侧骨骼 ID。这步一般要从SkeletonLink里读一份骨骼名称到索引的对照表名称对不上直接报错比静默错位好至少能定位是导出端还是引擎端的问题。4.4 四个必调参数速查参数推荐值改它的场景unit_scale1.0或0.01引擎单位是厘米时开0.01单位不对模型会整体偏大或偏小flip_axisZ_UP转Y_UP引擎坐标系和 Blender 不一致时用不要手动改分量符号index_bits32顶点数可能超 65535 时用旧引擎只支持 16 位时改回 16 并拆 submeshapply_modifiersTrue导出低模代理时设False核对顶点数时设Falseflip_axis这里多说一句坐标轴转换不要自己在循环里对 x 或 y 取负那样很容易把左右手系搞反模型变成镜像。常见做法是用mathutils.Matrix.Rotation(math.radians(-90), 4, X)整体作用于网格或者走bpy_extras.io_utils.axis_conversion。矩阵乘一次所有顶点都正确比逐个分量手改可靠得多。材质名的处理也放进导出流程优先取obj.active_material.name做一个清洗函数去掉空格、斜杠、中文标点。引擎侧很多解析器遇到非 ASCII 字符直接跳过材质块表现就是模型灰模。5. 避坑这些场景我亲测时都翻过车每条都有后悔药这一章整理的是我从「导一次成功」到「连续导几十个文件」过程中踩得最深的五类问题按「现象 → 原因 → 解决」写。排查顺序也很关键先确认数据合法性再查坐标再查 UV 与权重最后才怀疑插件版本和 API 问题。5.1 导入后网格全是烂面现象顶点洒了一地三角形像蜘蛛网一样乱穿渲染出来全是破面。原因破面基本不是浮点精度问题而是 submesh 索引区间没加base_vertex偏移。第二个子网格的 0 号索引直接引用了整个顶点缓冲最开头的三个顶点三角形自然就飞到天边去了。解决按 submesh 遍历索引时每个数字加上sm.base_vertex后再写入。如果引擎侧导出的索引本身就是全局索引有些烘焙工具会把偏移提前处理好就按二进制惯例让base_vertex 0但每个 submesh 的索引数量要单独记录。拿 hexdump 对照 XML 里的索引范围能快速确认是哪一种约定。5.2 导出的模型在引擎里横躺现象同场景里其他模型朝向正常只有刚导出的角色歪在那里旋转 90 度才能立起来。原因Blender 是 Z-up很多引擎是 Y-up就算都是 Z-up向前轴也可能差一个方向。这种坐标手性差异靠目测改分量符号治标不治本。解决导出时用一个统一的 4x4 矩阵做坐标变换不要碰单个坐标分量。我一般是在导出函数开头判断flip_axis默认场景写死Matrix.Rotation(radians(-90), 4, X)导入时反过来再乘一次。矩阵写在开头全流程只有一个地方控制轴向排查时打开一个立方体就能验证对错。5.3 UV 铺满整个模型而不是按图集格子走现象贴图颜色对得上但花纹斜拉或者整个模型只显示贴图左下角的一小块。原因三层问题叠在一起——Blender 的 UV V 方向向下引擎常用 V 向上第二套 UV 没导引擎把第一套当光照贴图用导出时 UV 精度被压成半精度浮点图集上的小格子直接糊掉。解决导出时uv.y 1.0 - uv.y导入时反过来。如果贴图在引擎里上下颠倒先别怀疑贴图资源查这个翻转有没有做。双 UV 的场景要给每套 UV 单独指定数据源不要让引擎猜。存储精度保持 float32别贪省那 4 字节图集 UV 的代价不值得。5.4 权重导完角色一动画就局部塌陷现象大臂一抬手腕像断了一样弯折或者一整片袖子僵在原处不动。原因Blender 刷好的权重可能超过 4 个骨骼影响导出脚本只顺序取了前 4 个把真正的主导骨骼切掉了切掉后剩余权重没重新归一化总和只有 0.7骨骼收不住力。解决提取顶点组权重后按值降序排序截断到 4再把剩余权重全部除以总和。同时在 Blender 里刷完权重后用「权重 → 归一化」兜底一次让数据源本身是干净的。这两步都做了蒙皮动画才算真正稳定。5.5 插件在 Blender 4.x 是灰色或报弃用警告现象菜单里能看到导入项点击后没反应控制台报AttributeError: Mesh object has no attribute calc_tessface。原因Blender 4.x 移除了旧的三角化 API老插件里凡是用calc_tessface的地方全部失效。另一个常见来源是bpy.props里某些属性的默认参数写法变了旧插件直接装不上。解决封装一层兼容判断if hasattr(mesh, calc_loop_triangles): mesh.calc_loop_triangles() else: mesh.calc_tessface()安装第三方插件前先看它声明兼容的 Blender 版本不要直接解压进 addons 目录。控制台里的 deprecation 警告别忽略每条都记下 API 名封装到自己的工具函数里下次升级版本时只改一个文件。6. 进阶写一个回读校验脚本把「导一次」变成「随手能导」导入导出调通只是第一步。文件交给引擎之前我建议先在 Blender 里回读验证把刚导出的.mesh用同一套脚本再导进来比对顶点数和三角形数差异超过一个阈值就停下来。这样能把索引偏移、坐标翻转、单位换算的问题瞬间暴露出来。def verify_roundtrip(obj, filepath): v0, t0 len(obj.data.vertices), len(obj.data.loop_triangles) tmp import_mesh_into_scene(filepath, verify_mesh) v1, t1 len(tmp.data.vertices), len(tmp.data.loop_triangles) if (v0, t0) ! (v1, t1): raise RuntimeError(f回读不一致: {v0}/{t0} vs {v1}/{t1}) bpy.data.objects.remove(tmp)import_mesh_into_scene就是前面build_object的封装返回挂载到场景里的对象。比对通过后立刻删除不留垃圾数据。这套逻辑加上脚本跑一次只要几秒钟比在引擎里加载半天再发现模型爆炸要快得多。批处理多个文件时不要手动一个个点导出用命令行后台跑blender -b shot.blend -P export_all.py -- --outdir /tmp/out --index 32export_all.py里解析--后面的自定义参数遍历场景里所有带_LOD后缀的对象逐个调用导出函数并写日志。这样整个场景几十个模型一次就能导完中途哪个文件失败日志里直接能看到原因不用守在 Blender 前盯着看。我的习惯是每改完一次绑定或材质先导出一版跑一遍回读再扔给引擎。流程固定成改模型 → 导出 → 回读 diff → 确认 OK → 批量烘焙。导出脚本里的默认值写死只调参数不碰逻辑。以前有一次我把轴向翻转写成了手动翻转 X 分量符号导出的十几个模型在场景里全是镜像最后才发现是坐标系问题而不是模型问题。自那以后轴翻转、单位、索引位数这些全部收进参数表每次只改参数。这个习惯帮我省掉的不是我一个人的时间——所有接手这个脚本的人都不会再犯同样的错。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/16 9:40:42 · 阅读 1.2k Blender导入导出.mesh格式：解析二进制网格与骨骼权重全流程
简介这款Blender插件专门用于导入导出OGRE引擎中广泛使用的.mesh格式模型文件解决Blender默认不支持该格式、网上现有方案多为老旧失效链接的痛点适合游戏美术、资源转换人员以及需要处理Kenshi等以.mesh存储模型的开发者。插件包共7个文件其中5个Python脚本构成Blender端导入导出核心逻辑另有1个OgreXMLConverter.exe负责格式转换、1个OgreMain.dll提供运行依赖整体压缩包仅2.29MB轻量且便于部署。已有4157人学习下载。安装并激活插件后Blender即可直接读取和写出.mesh模型在导入的同时保留网格基础结构配合附带转换工具可应对常见OGRE资源减少手工转换和时间成本尤其适合在DCC工具链中快速打通旧模型资产。1. Blender 导入导出 .mesh 格式文件为什么值得自己把流程走通你手头有一个 Blender 文件角色绑好了骨骼材质也贴好了引擎那边只要.mesh格式文件。Blender 的默认导入导出列表里没有它网上教程各讲一半有的只给 XML 版本、有的只讲导入不讲导出、有的导出以后顶点散成一片。我按「Blender 导入导出 .mesh 格式文件」这条链路反复调过几轮把从拆包二进制、重建网格到带骨骼导出的一整套流程整理成了下面的脚本思路亲测好用。写这篇东西不是为了让你去下载某个黑匣子插件而是把格式拆开给你看让新手能照着一行行敲出来让熟手能直接拿去接进自己的管线。适合技术美术、独立开发者和正在接引擎管线的同学照着做一遍能省下至少两天的查错时间。这套格式的麻烦点在于它不是通用容器而是某个开源引擎定义的网格交换格式。导入导出的难点从来不是 Blender 侧的操作而是坐标轴、单位、索引分段、骨骼权重上限这些「两边约定不一致」的地方。只要把这几处约定对齐整条链路就稳了。2. 先搞懂 .mesh 里存了什么按数据块拆包而不是按行读文件.mesh文件的核心结构是 Header 加一串 chunk每个 chunk 前 8 字节是 ID 和长度后面跟着数据。很多人拿十六进制工具打开文件就晕就是没意识到「这不是文本是块状协议」。导入脚本的第一步永远不是读顶点而是先把 chunk 边界找对否则后面全是乱码。2.1 一个 .mesh 文件由哪些数据块拼成数据块存放内容典型布局Header魔数、版本号、格式标记一段 ASCII 头或固定字节Geometry顶点位置、法线、UV 集、骨骼权重每顶点定长 float 数组IndexBuffer三角形索引uint16 或 uint32按 submesh 划分区间Submesh材质名、索引起点/数量、几何类型字符串 数值区间SkeletonLink绑定的骨骼文件名、蒙皮矩阵字符串 16 个 float 矩阵Bounds模型 AABB 包围盒6 个 float这里面最容易踩坑的是 Geometry 块。位置、法线、UV、权重通常会凑在同一个顶点缓冲里引擎靠 stride步长和 offset 定位每段数据。不同版本的引擎字段顺序可能完全不同有的是位置、法线、UV有的是位置、UV、法线。你在文本编辑器里看到一整排浮点数却分不清哪个是哪个原因就在这。解析时必须先拿到底层声明的顶点布局再按偏移量切片不能按「第几个 float 是 x」这种猜法写。2.2 选二进制变体而不是 XML三个现实理由引擎在导出.mesh时有的版本会同时生成一份.mesh.xml用于编辑器预览。我的建议是正式流程只解析二进制二进制文件小一个数量级加载快引擎侧不会卡顿XML 的字段顺序在不同版本间差异大解析代码容易被版本牵着走现有工具链基本都走二进制写出来的脚本换到别的项目也能复用XML 也别扔留作排错参考。某块解析对不上时把 XML 打开对比字段顺序能省不少时间——这属于典型的「别人踩过但你还没踩」的坑。2.3 插件骨架怎么搭一个 IO 脚本 两个 Operator 入口常见做法是把插件拆成三个文件导入和导出逻辑分开避免一个.py文件里又处理读取又处理写入几百行之后自己都找不到函数在哪。bmesh_io/ __init__.py # 注册入口 import_mesh.py # 导入逻辑 export_mesh.py # 导出逻辑__init__.py只做一件事注册两个 Operator并把它们挂到 Blender 的导入导出菜单。先看注册部分import bpy class MESH_OT_import(bpy.types.Operator): bl_idname import_mesh.file bl_label Import .mesh filepath: bpy.props.StringProperty(subtypeFILE_PATH) def execute(self, context): load_mesh(context, self.filepath) return {FINISHED} def menu_import(self, context): self.layout.operator(MESH_OT_import.bl_idname, textImport .mesh) def register(): bpy.utils.register_class(MESH_OT_import) bpy.types.TOPBAR_MT_file_import.append(menu_import) def unregister(): bpy.types.TOPBAR_MT_file_import.remove(menu_import) bpy.utils.unregister_class(MESH_OT_import) if __name__ __main__: register()为什么导入和导出要分开两个 Operator因为导入没有context.object处理逻辑和撤销栈都不一样分开注册还能在 File 菜单里各自挂一个入口功能边界清晰。注意load_mesh别写死在execute里拆成独立函数后面命令行批处理和回读验证都要直接调它。这段骨架看起来简单但它决定了后面所有代码能不能被复用。我见过太多插件把解析逻辑全塞在 Operator 里结果想跑自动化测试的时候连 context 都 mock 不出来只能卸了插件手动点菜单。3. 导入 .mesh拆出顶点、索引、材质一口气建出网格导入前先准备一个最小的.mesh文件随便建一个立方体用引擎自带的工具导出来。然后用hexdump -C file.mesh | head -n 8看前 64 字节确认魔数和块头格式这一步能帮你少走很多弯路——不同引擎分支的魔数不一样网上抄来的脚本不匹配第一行就报错。3.1 魔数与 chunk 主循环三种写法里挑最稳的读取 chunk 有三种常见写法按struct.Struct定长解包、按类型映射字典、整块读进内存再切片。我一般用第一种逻辑直接、性能也够。核心循环长这样import struct def read_chunks(fp, end_offset): 读取后续所有 chunk每个 chunk 由 块ID(4B) 长度(4B) 数据 组成 chunks [] while fp.tell() end_offset: chunk_id, size struct.unpack(II, fp.read(8)) payload fp.read(size) chunks.append((chunk_id, payload)) return chunksII的意思是小端序、两个无符号 32 位整数。前一个I是块 ID后一个I是数据长度。这里有个细节长度是「后面跟随的数据字节数」不含这 8 字节头。有些旧版本引擎会写「含头长度」一旦按错整条流就歪掉了这种现象常被误判成「文件损坏」。注释里的end_offset一般是文件总大小减去 Header 长度。如果解析到某个 chunk 后fp.tell()跳过了end_offset先别急着改读取逻辑回去查长度字段是不是含头。我在这上面吃过一次亏整整花了半天排查。3.2 顶点缓冲怎么变成 Blender 网格拿到 chunk 之后把 Geometry 块里的顶点按 stride 切片IndexBuffer 里的数字按 submesh 分段然后一次性交还给 Blenderimport bpy def build_object(context, name, verts, tris, mat_names): mesh bpy.data.meshes.new(name) mesh.from_pydata(verts, [], tris) mesh.update() for m in mat_names: mat bpy.data.materials.get(m) if mat is None: mat bpy.data.materials.new(m) mesh.materials.append(mat) obj bpy.data.objects.new(name, mesh) context.scene.collection.objects.link(obj) return obj逻辑说明from_pydata接收三个参数——顶点坐标列表、边列表留空、面列表。这里的tris必须是每个三角形三个角顶点的索引而且顺序要和引擎侧 IndexBuffer 一致。mesh.update()在填充数据后调用作用是重建内部拓扑结构不加它的话后面的 UV 赋值可能报「mesh has no valid loops」。UV 也别漏赋值要按 loop 而不是按 vertexdef assign_uv(mesh, uv_data): if not uv_data: return uv_layer mesh.uv_layers.new(nameUVMap) for loop_idx, uv in enumerate(uv_data): uv_layer.data[loop_idx].uv (uv[0], 1.0 - uv[1])注意1.0 - uv[1]这一句Blender 的 V 方向向下很多引擎是 V 向上不翻转的话贴图会上下颠倒。这是导入导出两端最容易错位的地方后面避坑章节会再展开。材质名映射也要处理引擎侧的材质名可能和 Blender 里的名字不一致常见做法是「有同名材质就用没有就新建」。很多模型从第三方工具导出来材质名里带空格、斜杠、中文引擎侧解析器不一定全都支持导入脚本里可以先做个清洗把非法字符替换成下划线。3.3 导入后三件必做的事第一法线。如果引擎在 Geometry 块里存了法线直接覆盖mesh.normals并调用calc_normals_split()没存就让 Blender 按平滑组重算。注意calc_normals_split在 Blender 3.x 之后的行为有过变化用之前先查一下当前版本的 API 签名。第二双 UV。很多模型带第二套 UV 用于光照贴图导入时若只建一套 UV材质球一烘焙就会错位。我一般会在导入参数里加一个uv_names列表支持按名称批量建 UV 层。第三骨骼。如果文件里带 SkeletonLink 块导入后要建一个空的 Armature 对象把骨骼文件名和绑定矩阵挂到对象的rotation_euler/location上。这一步不做后面刷权重或做动画展示时模型会摆不对姿势。4. 导出 .mesh从 Object 到二进制包四个参数设一次就过导出比导入看起来简单——数据都在 Blender 里直接读出来写文件就行。但实际上Blender 里的网格形态和引擎侧期望的数据之间隔着一层「翻译」修改器、三角化、索引偏移、权重上限每一项都可能导致导出文件在引擎里渲染成另一副样子。4.1 第一步先拿一份干净的 mesh 快照导出前别直接读obj.data那个是基础网格没算修改器。美术在 Blender 里看的是细分、镜像、实体化之后的形态引擎要的也是这个最终结果。正确做法是拿依赖图求值后的临时网格def snap_mesh(obj, apply_modifiers): deps bpy.context.evaluated_depsgraph_get() if apply_modifiers: eval_obj obj.evaluated_get(deps) mesh eval_obj.to_mesh() else: mesh obj.data.copy() return mesh参数apply_modifiers默认为True。什么时候设成False导出低模碰撞体或者烘焙用的代理模型时要的是原始拓扑这时候开修改器反而帮倒忙。还要注意eval_obj.to_mesh()拿到的网格是临时对象用完要记得eval_obj.to_mesh_clear()否则内存会一直涨批处理导几十个文件时 Blender 直接崩掉。拿完快照后先三角化再去重mesh.calc_loop_triangles()如果不调用calc_loop_triangles()mesh.loop_triangles就是空的导出文件里一个三角形都没有。另外直接用mesh.loops的顶点索引拼三角形会发现同一个顶点被重复写了好几次——因为每个 loop 对应一个「顶点在某条边上的使用」而不是顶点本身。导出前要按「位置 法线 UV」建一个去重映射把重复顶点合并否则文件体积膨胀三倍引擎加载还变慢。4.2 顶点打包与索引分段二进制写入的核心单顶点打包这块常见引擎的布局是固定 48 字节位置 12 字节、法线 12 字节、UV 8 字节、骨骼索引与权重 16 字节。写成代码就是import struct def pack_vertex(position, normal, uv, bone_index, bone_weight): 默认顶点布局pos(12B) normal(12B) uv(8B) 4骨骼索引(8B) 4权重(16B) fmt 3f3f2f4H4f return struct.pack(fmt, *position, *normal, *uv, *bone_index, *bone_weight)3f是 xyz第二个3f是法线 xyz2f是 uv 的 u 和 v4H是四个无符号短整数骨骼索引最后的4f是四个 float 权重。如果引擎用的是另一种布局比如法线在最后只需要调整fmt字符串和参数顺序函数的骨架不用动。索引写入要特别注意 submesh 偏移def pack_submesh(sm, index_bits): fmt H if index_bits 16 else I indices [i sm.base_vertex for i in sm.indices] return struct.pack( fmt * len(indices), *indices)每个 submesh 的索引是相对自身起点的写入文件时必须加上base_vertex偏移否则第二个材质块的所有三角形都会错误地引用顶点缓冲的开头几个点渲染出来就是一堆三角形互相乱穿。这个base_vertex的值怎么拿常见做法是写入第一个 submesh 前记下已写入顶点数下一个 submesh 就从那里开始加。4.3 带骨骼的角色权重要截断到引擎上限Blender 允许一个顶点绑很多个顶点组但引擎一般只认 4 个骨骼影响。导出前做两步截断到前 4 个再归一化。def top4_weights(obj, vert_index): groups obj.data.vertices[vert_index].groups pairs [(obj.vertex_groups[g.group].name, g.weight) for g in groups] pairs.sort(keylambda x: x[1], reverseTrue) # 按权重降序保最重要的骨骼 pairs pairs[:4] total sum(w for _, w in pairs) or 1.0 # 避免除零 return [(name, w / total) for name, w in pairs]注意排序这行——顶点组的顺序在groups列表里是按添加顺序排的不是按权重排的。不排序直接取前 4 个很可能把权重 0.6 的主骨骼丢掉留下三个 0.1 的次要骨骼动画时模型局部塌陷。另外归一化把剩余权重重新按比例分配保证四个权重之和等于 1否则总和只有 0.7骨骼收不住力。骨骼索引的映射也在这里做把顶点组名转成引擎侧骨骼 ID。这步一般要从SkeletonLink里读一份骨骼名称到索引的对照表名称对不上直接报错比静默错位好至少能定位是导出端还是引擎端的问题。4.4 四个必调参数速查参数推荐值改它的场景unit_scale1.0或0.01引擎单位是厘米时开0.01单位不对模型会整体偏大或偏小flip_axisZ_UP转Y_UP引擎坐标系和 Blender 不一致时用不要手动改分量符号index_bits32顶点数可能超 65535 时用旧引擎只支持 16 位时改回 16 并拆 submeshapply_modifiersTrue导出低模代理时设False核对顶点数时设Falseflip_axis这里多说一句坐标轴转换不要自己在循环里对 x 或 y 取负那样很容易把左右手系搞反模型变成镜像。常见做法是用mathutils.Matrix.Rotation(math.radians(-90), 4, X)整体作用于网格或者走bpy_extras.io_utils.axis_conversion。矩阵乘一次所有顶点都正确比逐个分量手改可靠得多。材质名的处理也放进导出流程优先取obj.active_material.name做一个清洗函数去掉空格、斜杠、中文标点。引擎侧很多解析器遇到非 ASCII 字符直接跳过材质块表现就是模型灰模。5. 避坑这些场景我亲测时都翻过车每条都有后悔药这一章整理的是我从「导一次成功」到「连续导几十个文件」过程中踩得最深的五类问题按「现象 → 原因 → 解决」写。排查顺序也很关键先确认数据合法性再查坐标再查 UV 与权重最后才怀疑插件版本和 API 问题。5.1 导入后网格全是烂面现象顶点洒了一地三角形像蜘蛛网一样乱穿渲染出来全是破面。原因破面基本不是浮点精度问题而是 submesh 索引区间没加base_vertex偏移。第二个子网格的 0 号索引直接引用了整个顶点缓冲最开头的三个顶点三角形自然就飞到天边去了。解决按 submesh 遍历索引时每个数字加上sm.base_vertex后再写入。如果引擎侧导出的索引本身就是全局索引有些烘焙工具会把偏移提前处理好就按二进制惯例让base_vertex 0但每个 submesh 的索引数量要单独记录。拿 hexdump 对照 XML 里的索引范围能快速确认是哪一种约定。5.2 导出的模型在引擎里横躺现象同场景里其他模型朝向正常只有刚导出的角色歪在那里旋转 90 度才能立起来。原因Blender 是 Z-up很多引擎是 Y-up就算都是 Z-up向前轴也可能差一个方向。这种坐标手性差异靠目测改分量符号治标不治本。解决导出时用一个统一的 4x4 矩阵做坐标变换不要碰单个坐标分量。我一般是在导出函数开头判断flip_axis默认场景写死Matrix.Rotation(radians(-90), 4, X)导入时反过来再乘一次。矩阵写在开头全流程只有一个地方控制轴向排查时打开一个立方体就能验证对错。5.3 UV 铺满整个模型而不是按图集格子走现象贴图颜色对得上但花纹斜拉或者整个模型只显示贴图左下角的一小块。原因三层问题叠在一起——Blender 的 UV V 方向向下引擎常用 V 向上第二套 UV 没导引擎把第一套当光照贴图用导出时 UV 精度被压成半精度浮点图集上的小格子直接糊掉。解决导出时uv.y 1.0 - uv.y导入时反过来。如果贴图在引擎里上下颠倒先别怀疑贴图资源查这个翻转有没有做。双 UV 的场景要给每套 UV 单独指定数据源不要让引擎猜。存储精度保持 float32别贪省那 4 字节图集 UV 的代价不值得。5.4 权重导完角色一动画就局部塌陷现象大臂一抬手腕像断了一样弯折或者一整片袖子僵在原处不动。原因Blender 刷好的权重可能超过 4 个骨骼影响导出脚本只顺序取了前 4 个把真正的主导骨骼切掉了切掉后剩余权重没重新归一化总和只有 0.7骨骼收不住力。解决提取顶点组权重后按值降序排序截断到 4再把剩余权重全部除以总和。同时在 Blender 里刷完权重后用「权重 → 归一化」兜底一次让数据源本身是干净的。这两步都做了蒙皮动画才算真正稳定。5.5 插件在 Blender 4.x 是灰色或报弃用警告现象菜单里能看到导入项点击后没反应控制台报AttributeError: Mesh object has no attribute calc_tessface。原因Blender 4.x 移除了旧的三角化 API老插件里凡是用calc_tessface的地方全部失效。另一个常见来源是bpy.props里某些属性的默认参数写法变了旧插件直接装不上。解决封装一层兼容判断if hasattr(mesh, calc_loop_triangles): mesh.calc_loop_triangles() else: mesh.calc_tessface()安装第三方插件前先看它声明兼容的 Blender 版本不要直接解压进 addons 目录。控制台里的 deprecation 警告别忽略每条都记下 API 名封装到自己的工具函数里下次升级版本时只改一个文件。6. 进阶写一个回读校验脚本把「导一次」变成「随手能导」导入导出调通只是第一步。文件交给引擎之前我建议先在 Blender 里回读验证把刚导出的.mesh用同一套脚本再导进来比对顶点数和三角形数差异超过一个阈值就停下来。这样能把索引偏移、坐标翻转、单位换算的问题瞬间暴露出来。def verify_roundtrip(obj, filepath): v0, t0 len(obj.data.vertices), len(obj.data.loop_triangles) tmp import_mesh_into_scene(filepath, verify_mesh) v1, t1 len(tmp.data.vertices), len(tmp.data.loop_triangles) if (v0, t0) ! (v1, t1): raise RuntimeError(f回读不一致: {v0}/{t0} vs {v1}/{t1}) bpy.data.objects.remove(tmp)import_mesh_into_scene就是前面build_object的封装返回挂载到场景里的对象。比对通过后立刻删除不留垃圾数据。这套逻辑加上脚本跑一次只要几秒钟比在引擎里加载半天再发现模型爆炸要快得多。批处理多个文件时不要手动一个个点导出用命令行后台跑blender -b shot.blend -P export_all.py -- --outdir /tmp/out --index 32export_all.py里解析--后面的自定义参数遍历场景里所有带_LOD后缀的对象逐个调用导出函数并写日志。这样整个场景几十个模型一次就能导完中途哪个文件失败日志里直接能看到原因不用守在 Blender 前盯着看。我的习惯是每改完一次绑定或材质先导出一版跑一遍回读再扔给引擎。流程固定成改模型 → 导出 → 回读 diff → 确认 OK → 批量烘焙。导出脚本里的默认值写死只调参数不碰逻辑。以前有一次我把轴向翻转写成了手动翻转 X 分量符号导出的十几个模型在场景里全是镜像最后才发现是坐标系问题而不是模型问题。自那以后轴翻转、单位、索引位数这些全部收进参数表每次只改参数。这个习惯帮我省掉的不是我一个人的时间——所有接手这个脚本的人都不会再犯同样的错。希望帮到你。本文还有配套的精品资源点击获取