简介：Blender插件blender-egg-importer面向Blender建模师与Panda3D游戏开发者，用于将Panda3D的.egg模型直接导入Blender，并与YABEE等导出器互操作，保留原始模型的层级结构和法线信息。资源包体积仅21KB，包含4个文件，其中3个Python脚本分别实现插件初始化、egg文件解析和导入逻辑，另有1个Markdown文档说明安装与用法，结构精简，适合快速集成到Blender 2.74及以上版本（已在2.80验证）。目前已有967人学习下载。插件还提供与bam2egg配合的可靠路径，可在Blender中直接导入由egg2bam生成的.bam文件，形成从建模到Panda3D引擎的完整链路；法线处理策略避免冗余自定义数据，确保模型表现准确。对于需要在Blender与Panda3D之间频繁转换资源的开发者，这是一套轻量实用的开源工具。
1. 为什么是egg导入器：从Panda3D到Blender的模型搬运难题
做过Panda3D开发的人大概率都有过这么一段经历：好不容易从旧项目或素材库里翻出一个EGG格式的模型，打开Blender想改贴图、调骨骼，结果拖进视口发现Blender根本不识别，导入菜单里也找不到对应选项。把后缀改成obj或者fbx更是白搭，打开就是一坨乱码。EGG是Panda3D引擎自己的模型描述格式，不是通用交换格式，外部工具默认不认。这时候，一个能用的Blender EGG导入插件就成了卡脖子的刚需。本文要聊的blender-egg-importer，正好解决从Panda3D资产到Blender工作流之间的这条断头路。它适合两类人：一类是把遗留Panda3D模型迁到新管线做二次开发的开发者，另一类是想在Blender里修模型、再回灌Panda3D工程的上手玩家。
2. EGG文件的构成与导入器解析思路：先搞懂格式再谈插件
很多人会把EGG当成又一个“顶点列表格式”，拿到文件直接丢给导入器，报错就一头雾水。实际上EGG的复杂度和OBJ不在一个量级，它把坐标、材质、纹理、骨骼、碰撞盒这些信息全塞在一个文本树里。导入器要做的不是简单读顶点，而是把Panda3D引擎能执行的节点描述翻译成Blender能理解的对象结构和数据属性。这一步理解透了，后面调参数、改报错才有方向。
2.1 EGG格式的核心语法：顶点池、多边形与材质绑定
一个典型的EGG文件是按缩进组织的中括号块结构。先看一个最简示例，删掉了无关标签：
<egg-file> { <CoordinateSystem> { Z-up } <Group> model_root { <VertexPool> pool_1 { <Vertex> 0 { <XYZ> { 0 0 0 } <UV> { 0 0 } } <Vertex> 1 { <XYZ> { 1 0 0 } <UV> { 1 0 } } <Vertex> 2 { <XYZ> { 0 1 0 } <UV> { 0 1 } } } <Material> mat_wood { <Diffuse> { 0.8 0.6 0.4 1 } } <Polygon> { <VertexRef> 0 1 2 { <Ref> { pool_1 } } <MaterialRef> { mat_wood } } } }这个片段虽然短，信息量却不小。最外层的<egg-file>是根节点，<CoordinateSystem>声明坐标系，这个值直接决定导入器要不要做坐标轴换算。<Group>对应一个场景层级节点，类似Blender里的空物体或父级容器；<VertexPool>是顶点池，池里每个<Vertex>用<XYZ>存位置、<UV>存第一套UV。<Material>定义材质，<Polygon>画一个三角面，<VertexRef>按顺序引用顶点池里的索引，<MaterialRef>把面和材质挂上钩。
实际工程里的EGG会比这个复杂得多：一个模型文件里可能有多个<VertexPool>、多套UV、顶点法线（<Normal>）、蒙皮权重，甚至带<Collide>碰撞盒。层级越深，导入器的递归解析就越关键。理解了结构之后你会发现，如果Console里报错提到某个顶点池或材质名称，打开EGG文本搜索对应名字，直接就能定位到出错的段落，比自己瞎猜快很多。
2.2 导入器内部的解析链路：从文本流到Blender对象
很多导入器的实现思路，是写一个递归下降解析器，按标签类型分派到不同处理函数。处理过程中维护一个栈，记录当前在哪个Group或VertexPool下，再分两条线推进：几何线处理顶点坐标、UV、面索引，属性线处理材质、纹理、骨骼层级。大致示意如下：
# 示意代码：表达核心解析路径，不完整 def build_mesh_from_egg(egg_lines): vertices = [] faces = [] materials = {} for line in egg_lines: if line.startswith("<Vertex>"): vertices.append(parse_vertex(line)) elif line.startswith("<VertexRef>"): faces.append(parse_ref(line)) elif line.startswith("<Material>"): materials[line.name] = parse_material(line) # 返回一个带材质名的网格对象 return create_blender_mesh(vertices, faces, materials)这段代码只做一件事：把EGG的树形结构线性化。parse_vertex负责读<XYZ>和<UV>，parse_ref读<VertexRef>里按空格分隔的顶点索引，parse_material解析漫反射颜色和贴图路径。create_blender_mesh再把收集到的数组转成Blender的Mesh对象，设置uv_layer后挂上Material。
这个阶段，坐标系换算和全局缩放也会被执行。比如EGG声明Z-up，而导入器检测到与Blender一致，就不做翻转；如果源文件是Y-up，就要在构建顶点时把坐标轴重新映射。参数面板里的scale影响顶点坐标的倍率，texture_root影响材质贴图路径的重映射。所以想在贴图路径上省事，应该在导入前就填好根目录，别等导入后手动去材质节点里补救。
2.3 为什么不能靠改后缀名硬导：格式差异的底层逻辑
这是新手最常见的误区。把.egg改成.obj，Blender还是会按OBJ语法解析，看到一堆标签和数字被误读，最后要么导入空场景，要么直接报错。原因是OBJ是纯粹的几何描述，顶点坐标、法线、UV全部平铺，没有层级、没有可执行指令；而EGG是带逻辑的模型描述，里面有<Group>层级、<MaterialRef>引用、<Transform>矩阵变换，还有一批引擎运行时才会读的指令标签。这些信息OBJ根本没有对应的数据结构。
更关键的是坐标约定。Panda3D默认Z-up右手坐标系，Blender也是Z-up，听起来一致，但某些老项目或人工导出工具会写成Y-up，加上模型导出时可能做了局部旋转，导入后就会看到模型躺倒或绕某个轴翻转。OBJ格式本身没有坐标系统声明，全靠导入器猜。EGG文件头部的<CoordinateSystem>是一个权威声明，但手动拆改过的文件这一行有可能被误删。遇到翻转90度这种问题，先用文本编辑器打开EGG，搜索CoordinateSystem，确认这行还在不在、写的什么，比盲目在Blender里旋转模型可靠得多。
3. 安装blender-egg-importer：从插件文件到导入菜单出现
安装本身不难，但版本匹配和目录选错会绕不少路。我一般会先确认Blender版本，再决定用哪种方式装，最后在导入菜单里做一次验证，确认插件被真正加载，而不是文件放到了某个没人读的目录。
3.1 两种安装方式的适用场景
第一种是界面安装，适合单个.py文件或打包好的.zip。在Blender里依次打开Edit→Preferences→Add-ons，点右上角的Install...，选中文件后勾选启用，最后保存用户设置。
第二种是手动放置，适合插件需要固定目录管理、或你希望多个Blender版本共用同一份插件源码的情况。先找到Blender真正读取的addons路径，最靠谱的方式是直接在Blender的脚本工作区里运行一段Python：
import addon_utils # 列出当前Blender实例实际检查的插件路径 for addon_path in addon_utils.paths(): print(addon_path)addon_utils.paths()返回的是当前Blender启动时实际扫描的目录列表，里面包含系统级和用户级两类路径。把插件文件放进列出的某个路径下的addons子目录，再回到偏好设置点刷新，或者直接重启Blender。两种方式的差异在于：界面安装会帮你把文件复制进当前版本的addons目录，手动放置则让你自己统一管理脚本仓库，升级Blender时只需把目录重新指一下，插件不用重复装。
3.2 启用插件并验证加载成功
安装之后，在偏好设置的搜索框里输入egg或panda，应该能看到插件条目。勾选它，然后保存用户设置，否则下次打开Blender又得重新勾。这时还不能说装好了，必须在导入菜单里验证：
- 重启Blender，确保插件真正完成初始化；
- 在
File菜单下找Import子菜单； - 确认列表里出现类似
Panda3D Egg (.egg)的条目； - 如果菜单里没有，回偏好设置看插件条目是否显示已启用。
有时候插件加载了，但导入菜单里找不到入口。这种情况往往是操作符注册成功、菜单项注册失败，新老Blender版本之间的UI接口差异比较容易引发这类问题。排查时先看Blender的Console窗口有没有红色报错，再决定是更新插件还是换回旧版Blender，而不是反复重装同一个文件。
3.3 首次配置的3个全局参数：坐标系、纹理根目录、缩放
插件装好不等于导入顺利。第一件要配置的是坐标系。EGG头部的CoordinateSystem如果是Z-up，基本不用动；如果是Y-up，记得在导入前把源坐标系改成Y-up，否则模型会翻转。不要指望导入器自动侦测一切，自动侦测只对规范文件有效，残缺文件照样翻车。
第二件是纹理根目录。EGG里的贴图路径通常是相对路径，比如textures/brick.jpg。你把模型放在model/目录、贴图放在model/textures/下，默认解析没问题；但模型文件一旦被单独拷走，贴图路径立刻失效。我通常会把texture_root填成整个资产包的顶层目录，让导入器自己去拼前缀，这样换机器、换工程都不怕。
第三件是缩放单位。Panda3D项目很少约定统一单位，有的场景以米为单位，有的以厘米为单位。导入器如果暴露了global_scale参数，先导入一个模型量一下bounding box，再反推缩放值。面板里没有这个参数也没关系，导入后手动缩放对象，记得Ctrl+A应用变换，否则导出回Panda3D时会带一个奇怪的缩放矩阵，后续又要解释半天。
4. 实操导入一个EGG模型：最小步骤、参数扫盲与检查清单
安装只是开始，真正跑通一个模型才是检验插件的关键。假设模型路径是D:/panda_assets/cartoon.egg，目录里还有个textures文件夹放贴图。整个过程耗时一分钟，但每一处参数选择都会影响最终结果。
4.1 最小导入操作：从File菜单到Outliner
导入一个简单模型建议保持参数默认，先建立一个基线再调。操作分五步：
- 点击
File→Import→Panda3D Egg (.egg)，弹出文件选择器； - 定位到
cartoon.egg，选中后准备右下角的导入按钮； - 在左侧导入面板里把
texture_root填成D:/panda_assets，其余参数先不动； - 点击
Import，等待左下角进度条消失； - 在Outliner面板里展开层级，确认模型名称和结构是否合理。
这五步里最容易漏的是第三步。EGG里的贴图路径是相对路径，texture_root没填对，导入的模型材质是有的，贴图却接不上，整个模型看起来灰灰的。先走一遍默认参数还有一个好处：可以先把坐标、缩放这类变量从问题池里排掉，专注确认贴图路径是不是主要障碍。导入完成后切到Solid模式看一眼形状，再切到Material Preview模式看材质，颜色明显不对就回导入面板重新填路径再导一次——多数时候不是模型数据坏了，只是路径没对上。
4.2 关键导入参数逐一过一遍：全局缩放、旋转、纹理路径
不同导入器参数命名有差异，但核心对象是这几个：
- 全局缩放（Global Scale）：这个数值直接乘到每个顶点的坐标上，只影响模型大小，不影响形状和拓扑。面板里没有就导入后手动缩放，但记得应用变换。
- 源坐标系（CoordinateSystem）：下拉框里常见
Z-up和Y-up。选错的结果是模型绕X轴翻转90度。要以EGG文件里的声明为准，不要靠肉眼判断面朝向。 - 旋转补偿（Rotation Offset）：部分导入器在坐标转换后会额外加一个补偿角度，默认是0。模型整体朝向不对时通过它微调，常见绕X轴转负90度。
- 纹理根目录（Texture Root）：填资产包顶层目录，让插件重新拼接贴图路径。
不同版本插件暴露的参数不一定一样。有的写成scale=1.0，有的写成import_scale=1.0，有的面板里根本不显示。遇到参数对不上，去源码里找操作符类暴露了哪些FloatProperty和StringProperty，比自己在面板里逐个试要快得多。
4.3 导入后检查清单：网格、材质、UV、动画
导入不是终点，检查让你知道这次导入值不值得继续往下做。每次导入完我至少过这几项：
第一是网格对象。选中Outliner里的模型，查看多边形数量不为0，三角形数量落在合理范围。EGG里<Polygon>自带材质引用，导入器通常把多个面合并到同一个网格对象里，层级多的模型会有多个网格对象，逐个确认。
第二是材质节点。切到Shader Editor，选中模型，看Principled BSDF的Base Color是纯色还是连着贴图节点。纯色但有贴图节点没接线，多半是导入时材质连点没对上，手动把贴图节点的Color输出接到Base Color即可。
第三是UV。进入Edit Mode，全选网格，打开UV Editor。UV岛重叠或超出0-1范围，回导入面板找类似keep_uv_as_is的开关，重新导入。最常见的问题不是UV丢失，而是模型用了第二套UV但只有第一套被导入。
第四是动画和骨骼。工程里包含骨骼动画时，导入后去Action Editor看有没有动作片段。没有的话再回导入面板确认有没有动画相关开关；根本没有开关，说明这个插件不处理动画数据，得另走转换管线。这四项检查顺序不要乱：先网格，再材质，再UV，最后动画。前面任何一项挂掉，动画就算导进来也没法验证。
5. 避坑指南：EGG导入最常见的5个问题与排查思路
这章不全是插件bug，更多是格式与Blender之间的语义差异。每个问题按现象、原因、解决的顺序写，方便直接对号入座。
5.1 纹理全部丢失，模型变成紫粉色
现象：导入后模型显示为粉色或紫色，材质节点里有一个贴图节点，但图像路径是空的。
原因：EGG里的纹理路径是相对路径，默认相对于EGG文件所在目录解析。模型文件被移动、贴图目录被改名，导入器就找不到贴图文件，贴图节点只能留下一个空路径。
解决：导入前把texture_root设成资产根目录，让插件重新拼接路径。已经导入完了就在Shader Editor里选中Image Texture节点，重新指定贴图文件路径，再连到Principled BSDF的Base Color上。改完如果还发粉，检查贴图文件本身的格式——部分老EGG工程里引用了rgb或rgba格式贴图，Blender默认不认，要先转成png或jpg。
5.2 模型整体翻转或躺倒
现象：导入后模型绕X轴翻转了90度，或者原本应该站着的模型变成躺着。
原因：EGG文件的<CoordinateSystem>声明和导入器默认值不一致，或者这行被手动删掉了。老项目文件里写Z-up，但实际导出工具用的是Y-up，这种不一致经常出现。
解决：先用文本编辑器搜索EGG文件里的CoordinateSystem标签确认实际值，再去导入面板把源坐标系改成对应选项。如果文件里没有这行，试验两种配置后选形状正确的那一个。导入后整体旋转也能救，但会留下一个非零旋转量，导出回Panda3D时要额外处理，不推荐。
5.3 材质对错，A物体的材质跑到B物体上
现象：多个组件的材质在导入后交换或丢失，甚至所有面都挂到同一个材质上。
原因：EGG里的<Material>标签作用域不一定全局，它可能定义在某个<Group>内部，而导出工具未必对同名材质做了去重。导入器只按名字映射时，同名不同属性的材质就会互相覆盖。
解决：先用文本编辑器扫描EGG文件里的全部<Material>标签，看有没有同名定义。有的话在Panda3D侧重新导出并做材质重命名，或直接手工改EGG文本，把重复名称改成唯一值。导入后发现材质错乱，逐个检查对象每个面的material_index是否等于预期值，不对就手动重新指定。别在Blender里靠拖拽材质球去补，面一多就漏。
5.4 骨骼或顶点组导入后消失，动画跟着没了
现象：模型带蒙皮动画，但导入后对象上没有顶点组，场景里也没有骨架对象，Action列表为空。
原因：EGG的骨骼数据大多写在<Skinned>或<Skeleton>区域，和普通<Group>不在同一棵解析树上。不少导入器为求稳定，会直接跳过骨架相关标签，只导入静态网格。
解决：先查插件源码或文档里有没有skeleton、armature、animation相关开关。有开关就打开重新导入。没有开关，就别硬磕，换一条路：用Panda3D自带工具把EGG转成BAM格式，再通过能读BAM的转换器转成glTF或FBX，绕一圈再进Blender。这条路损耗大，但保留骨骼数据的确定性比手动重新绑骨骼高出很多。
5.5 导入时直接报表错，插件在Blender 4.x下失灵
现象：导入过程中报AttributeError或TypeError，场景里留下半截对象，Console里是一串红色堆栈。
原因：Blender从2.80到4.x几次调整Python API，某些老插件调用的接口被改名或移除。比如旧代码习惯直接拿mesh.vertices[i]做索引访问收藏，在新版本里接口行为变成了别的对象，调用自然失败。
解决：先看报错堆栈定位到插件源码的具体行，再去查对应Blender版本的API变更。插件太久没维护的话，最省事的做法是装一个Blender 2.93 LTS版本跑它，别硬在新版里强行适配——用新API重写解析器的工作量，往往比降版本大多了。报错时把Blender版本、插件版本、报错堆栈三样东西打包发给维护者，别人才能帮你定位。单独丢一句“导入失败”出去，基本等不到有效回应。
6. 再进一步：用Python脚本批量导入EGG建立资产库
如果你打算长期和Panda3D项目打交道，手动一个文件一个文件导入肯定撑不住。Blender的导入插件启用后，会给bpy模块注册一个导入操作符，你可以把它当普通函数调用，写一个批处理脚本。
6.1 把整个目录的EGG逐个导入并重新导出
下面这个脚本负责把指定目录下的所有EGG文件导入，再存成glTF放到另一个目录。批量转换前建议先手动导入一个，确认导入参数和导出目录没毛病。
import bpy import os # 根据自己环境修改这两个路径 source_dir = r"D:/panda_assets" target_dir = r"D:/panda_assets_gltf" os.makedirs(target_dir, exist_ok=True) for file_name in os.listdir(source_dir): if not file_name.lower().endswith(".egg"): continue # 每个文件从空白场景开始，避免上一个模型的残留数据混入 bpy.ops.wm.read_factory_settings(use_empty=True) egg_path = os.path.join(source_dir, file_name) # 具体操作符名以插件源码里的注册ID为准 bpy.ops.import_scene.egg(filepath=egg_path, texture_root=source_dir) bpy.ops.export_scene.gltf( filepath=os.path.join(target_dir, file_name[:-4] + ".gltf"), export_format="GLTF_SEPARATE" ) print("processed:", file_name) print("done")三个关键点。bpy.ops.wm.read_factory_settings(use_empty=True)是重置场景，防止批量循环时上一个模型的网格和材质污染下一个。texture_root=source_dir是给导入器传纹理根目录，比手动弹面板填路径可靠。export_format="GLTF_SEPARATE"让glTF导出器把纹理作为独立文件输出，方便后续在别的工具里打开。脚本里的导入操作符名是我按常见命名写的示例，换成你自己插件实际的注册ID即可。
6.2 用网格统计快速揪出异常文件
批量导入不像手动导入能逐个查看形状，所以我会在脚本里加一个一致性检查：统计每个导入对象的顶点数和三角形数，和数据清单对比，快速找出明显异常的模型。
for obj in bpy.context.scene.objects: if obj.type != "MESH": continue verts = len(obj.data.vertices) tris = len(obj.data.polygons) if verts < 10 or tris < 5: print("suspicious object:", obj.name, "verts:", verts, "tris:", tris)顶点数小于10、三角形数小于5的对象基本可以判定导入失败，要回到对应的EGG文件本体去排查。这个脚本不会自动修好损坏的模型，但能帮你在几十个导入结果里把坏样本快速挑出来，不用挨个点开看。
我的习惯是新建一个专用Blender工程文件，把这个批处理脚本存成文本模块，每次换项目只用改路径。跑完批量导入后，再从Outliner里挑两个样本模型做上面说的四项检查，确认整体质量稳定，才算整批完成。这个方法帮我在迁移一个中型Panda3D资产库时省下了大半天时间，希望也能帮到你。
本文还有配套的精品资源，点击获取
