简介：面向Blender动画师与技术美术人员，这款anim-exporter-addon是用Python开发的动画导出器插件，能将Blender动画场景导出为.anim格式，解决游戏引擎或自定义渲染工具导入动画数据时的格式转换问题。.anim格式采用类似Wavefront OBJ的层次化命令结构，支持fps定义每秒帧速率、start/end设定全局循环起止帧，并通过对象名与轨道标签分别关联网格及位置、旋转、缩放变换，便于后续程序化解析和复用。

资源包共2个文件，含插件主程序py和说明文档md，压缩包仅3KB，十分轻量。md文档详细介绍了格式语法与各命令含义，读者可据此快速理解格式并迁移到自己项目中；py脚本可直接放入Blender插件目录启用。目前已有587人学习或下载，适合需要精确控制动画导出细节、或研究自定义动画格式的Blender中高级用户快速上手。

1. 一个动画导出器要处理的，远不止“把关键帧抄进文件”

在 Blender 里检查角色动画时眼神确认没问题，一进引擎就出现“脚滑、转身时膝盖反向、整体腾空”这类玄学故障。这不是动画本身做坏了，而是 Blender 的右手系 Z-Up 坐标、骨骼姿态的求值链、以及运行时引擎的帧回放约定之间，存在三层容易被忽略的换算。动画导出器插件的本质，就是在这个边界上做一次有损但可控的翻译：把 Blender 的 F-Curve、Action、NLA 这些编辑态数据，转成游戏运行时能直接消费的姿态序列。

我建议把这类导出器定位成“引擎侧数据管线的起点”，而不是“文件转换脚本”。它需要负责三件事：坐标参考系换算、时间采样策略、姿态数据的冗余裁剪。适合谁用？如果你在做自研引擎、把 Blender 动画导入 Unity/UE 之外的其他运行环境，或需要把一批动画批量化导出成自定义 JSON 格式，这个方向值得投入。反之，如果只是偶尔导一两个动作并且能用 FBX 搞定，就不必造这个轮子。

2. 透视 Blender 动画数据结构：F-Curve、Action、NLA 到底是谁在说话

2.1 从 F-Curve 到 PoseBone：动画数据的四层组织

写导出器之前，先要弄清楚一个事实：Blender 给动画的最终呈现，是由多层数据叠加求值出来的，而不是“一个关键帧文件”里直挺挺躺着数组。从底层往上数大致有四层：

第一层是 F-Curve，它是单条属性通道的曲线数据，记录关键帧点的坐标、左右句柄、插值类型。一条典型的 F-Curve 的 data_path 可能是pose.bones["Bone.001"].location，配合.x、.y、.z这样的数组索引来标识具体通道。第二层是 Action，一堆 F-Curve 聚合在一个 Action 里，DOPESHEET 里看到的一条条可命名的“动作”，本质就是这些 F-Curve 的集合。第三层是 NLA，NLA Track 把多个 Action 片段按时间轴堆叠起来，还支持缩放、重复、静音等控制。第四层才是 PoseBone，它是骨架求值后的结果，pose_bone.matrix是经过 Action、NLA、约束、骨骼父子关系一条龙计算后得到的最终姿态矩阵。

这里会有一个新手常犯的理解偏差：直接去抄 F-Curve 上的关键帧数值，导出来的动画大概率是“散装”的。因为你跳过了约束求值和 NLA 的叠加效果。F-Curve 只是动画的“素材”，不是动画的“成品”。导出器如果在 F-Curve 层读取，你得到的只是某个属性通道的裸露数值流；如果在 PoseBone 层读取，你得到的是这个角色这一帧真正长什么样。

四层数据各自适合不同的导出策略。F-Curve 适合做关键帧保留型的精确导出；PoseBone 逐帧采样适合做烘焙型的通用导出。实际项目里，优先考虑 PoseBone 采样，因为它在约束、驱动、NLA 叠加这些复杂求值链下依然能稳定输出正确姿态。

2.2 导出插件应有的四个模块，别一上来就写导出函数

很多人在 Blender 里写导出插件，习惯把所有逻辑堆在一个 Operator 的 execute 方法里：拿当前 Action、循环帧、算矩阵、写文件。这个套路在 demo 阶段跑得通，一旦面对多角色、多动画、多目标格式的需求，就变成一团乱麻。

我一般把导出器拆成四个独立模块：插件入口（注册、面板、属性定义）负责和 Blender UI 交互；数据提取器负责从 Action 或场景里拿数据；变换层负责坐标系、手性、单位的换算；序列化层负责输出 JSON 或自定义二进制格式。这个结构的好处是，当你要从 JSON 切换到二进制，只动序列化层；当你要从 Blender 切换到其他 DCC，只重写数据提取器即可。

模块之间用数据结构隔离，不需要互相了解实现。以这个导出器为例，数据提取器输出的是一个“帧数组”，帧内的骨骼姿态统一是 4×4 矩阵数组；变换层消费的是矩阵，输出标准化后的 T/R/S 数组；序列化层拿到的永远是 T/R/S。这样换格式、换坐标约定，改动范围都被锁死在一个文件内部。

3. 手写最小动画导出器：一个能跑通的“采样+写文件”管道

3.1 插件骨架：注册、属性、面板

做一个最小可跑的插件，先要把 Blender 插件的注册骨架立起来。下面这段代码涵盖了bl_info、属性组、导出按钮操作符和面板四件套：

import bpy from bpy.props import FloatProperty, BoolProperty, StringProperty bl_info = { "name": "Anim Exporter Addon", "author": "Your Name", "version": (1, 0, 0), "blender": (3, 6, 0), "category": "Animation", } class AnimExporterProps(bpy.types.PropertyGroup): target_fps: FloatProperty(name="Target FPS", default=30.0, min=1.0, max=240.0) flip_left_hand: BoolProperty(name="Flip To Left-Hand", default=False) output_path: StringProperty(name="Output Path", subtype="FILE_PATH") class ANIMEXPORTER_OT_export(bpy.types.Operator): bl_idname = "animexporter.export" bl_label = "Export Animations" def execute(self, context): props = context.scene.anim_exporter_props # 此处调用数据提取与序列化逻辑 self.report({"INFO"}, "Export done") return {"FINISHED"} class ANIMEXPORTER_PT_panel(bpy.types.Panel): bl_label = "Anim Exporter" bl_space_type = "VIEW_3D" bl_region_type = "UI" bl_category = "Anim" def draw(self, context): layout = self.layout props = context.scene.anim_exporter_props layout.prop(props, "target_fps") layout.prop(props, "flip_left_hand") layout.prop(props, "output_path") layout.operator("animexporter.export", text="Export") def register(): bpy.utils.register_class(AnimExporterProps) bpy.utils.register_class(ANIMEXPORTER_OT_export) bpy.utils.register_class(ANIMEXPORTER_PT_panel) bpy.types.Scene.anim_exporter_props = bpy.props.PointerProperty(type=AnimExporterProps) def unregister(): del bpy.types.Scene.anim_exporter_props bpy.utils.unregister_class(ANIMEXPORTER_PT_panel) bpy.utils.unregister_class(ANIMEXPORTER_OT_export) bpy.utils.unregister_class(AnimExporterProps) if __name__ == "__main__": register()

这里把导出参数抽成了 PropertyGroup，而不是直接用 hard code 写在代码里。target_fps用来控制采样率，flip_left_hand是手性切换开关，output_path决定保存位置。面板把这些参数暴露在侧边栏里，免去每次改代码的麻烦。

属性注册顺序有讲究：先注册属性组，再注册操作符，然后是面板，最后把属性组挂到 Scene 上。反过来注册，面板里的context.scene.anim_exporter_props会报找不到属性。这是一个很隐蔽的报错点，尤其在插件重载时容易出现。

3.2 按照帧烘焙骨骼姿态：采样循环的核心逻辑

插件骨架搭好后，导出器的核心是数据提取环节。最稳的方案是逐帧调用frame_set，让 Blender 自己完成所有求值，然后读取pose_bone.matrix。

from math import pi import bpy from mathutils import Matrix # 将 Blender 的 Z-Up 右手系旋转到 Y-Up 右手系 M_ZUP_TO_YUP = Matrix.Rotation(-pi / 2, 4, "X") def sample_action_to_frames(action_name, armature_obj): """逐帧采样指定 Action 的所有骨骼姿态""" if action_name not in bpy.data.actions: raise RuntimeError(f"Action not found: {action_name}") action = bpy.data.actions[action_name] scene = bpy.context.scene frame_start = int(action.frame_range[0]) frame_end = int(action.frame_range[1]) frames = [] for frame in range(frame_start, frame_end + 1): scene.frame_set(frame) bone_data = [] for pbone in armature_obj.pose.bones: # 取出该骨骼在骨架空间中的姿态矩阵 mat = M_ZUP_TO_YUP @ pbone.matrix loc, quat, scale = mat.decompose() bone_data.append({ "name": pbone.name, "t": [loc.x, loc.y, loc.z], # 统一用四元数，避免欧拉旋转次序带来的歧义 "q": [quat.x, quat.y, quat.z, quat.w], "s": [scale.x, scale.y, scale.z], }) frames.append({ "frame": frame, "bones": bone_data, }) return frames

这段代码的关键点是：用scene.frame_set(frame)驱动求值链，而不是手动遍历 fcurves。约束、驱动、NLA 对姿态的影响都会在这一步被正确计算进去。如果只遍历 fcurves，遇到带约束的骨骼就会翻车。

第二个关键点是使用了pbone.matrix，也就是骨骼在骨架空间中的姿态矩阵。这里有一个常见的疑点：要不要在乘上骨架对象自身的matrix_world？我的做法是导出骨架空间数据，因为运行时引擎通常会把骨架对象自身位移清零，用pbone.matrix就能和引擎的 bind pose 对齐。如果目标引擎要求世界坐标，再把armature_obj.matrix_world乘进去，但在导出器里必须二选一，不能混着来。

mat.decompose()返回位置、四元数、缩放三件套。位置和缩放适合[x, y, z]，旋转用四元数[x, y, z, w]。如果你选择欧拉角，需要明确旋转次序，否则相同的数值在不同引擎里解算出行完全不同，这是最容易制造“动作看着差不多但就是不对劲”的坑。

3.3 统一数据出口：把 T/R/S 结构序列化成 JSON

从矩阵分解出 T/R/S 之后，导出器的工作就变成了“把内存里的帧数组落盘”。JSON 适合作为第一版格式，结构直观、方便调试，跑通链路后再考虑二进制压缩。

import json def write_animation_json(output_path, meta, frames): """把帧数组和元信息写入 JSON 文件""" export_data = { "meta": meta, "frames": frames, } with open(output_path, "w", encoding="utf-8") as f: json.dump(export_data, f, indent=1, ensure_ascii=False)

meta 里至少要放这些信息：角色模型名、目标 FPS、骨骼数量、坐标系统说明、单位。特别是坐标系统说明，不写清楚的话，三个月后你自己都不知道这个文件是左手系还是右手系。

序列化层不做任何姿态数据的修改。它收到的 T/R/S 数组一定已经完成了坐标变换、手性翻转、单位换算。这样做的原因很实际：如果序列化层也参与变换，数据流会变成一团浆糊，排查问题时无法确定到底是哪一层改错了数据。

4. 导出方向的三个硬决策：坐标空间、采样率、插值保留策略

4.1 坐标空间：Blender 右手 Z-Up 到引擎左手 Y-Up，少一步就翻车

Blender 的默认世界坐标是 Z 轴朝上的右手系，绝大多数游戏引擎使用 Y 轴朝上的坐标系统，其中不少还是左手系。这意味着导出数据时，至少要经历一次旋转，如果目标引擎是左手系，还需要额外做一次手性翻转。

项目和选择方案，我整理成了下面这张表，按目标运行时分类：

表里说“翻转一个轴”，具体翻哪个轴取决于引擎的 X 轴朝向约定。常见的做法是翻转 X 轴，也就是对 X 坐标取反。需要强调的是，这个手性翻转必须同时作用于模型网格和动画数据，只翻转动画不翻转模型，导入后会出现左右交叉错位的现象。

在第 3 章的代码里，M_ZUP_TO_YUP已经把旋转做完了，手性翻转由面板上的flip_left_hand开关控制。实现上就是对取出的向量和四元数的 x 分量取反，不需要再做别的算术变换。

4.2 采样率：FPS×1 还是 FPS×2，取决于目标方的回放方式

采样率决定了帧数组里到底有多少帧。很多导出器默认每个原始动画帧采一次，也就是 Blender 场景的 FPS 等于导出 FPS。这个策略在大多数情况下是对的，但有两个例外值得调整。

第一个例外是目标引擎对动画通道做线性插值。如果引擎在相邻采样帧之间使用线性插值还原动作，而 Blender 里用的是贝塞尔曲线，采样率偏低就会出现明显的卡顿感。这时把采样率提到原始 FPS 的两倍，会平滑很多，代价是文件体积翻倍。

第二个例外是目标引擎能接受插值类型描述。此时不需要高采样率，反而要在导出时保留关键帧的位置和插值类型，走“关键帧无损”路线，而不是“逐帧烘焙”。两种模式对应不同的数据提取方式：逐帧烘焙用frame_set；关键帧保留要读取 fcurve 的keyframe_points。

target_fps这个参数的正确理解方式是“最终文件里的时间密度”，不要盲目追求 60 甚至 120。常见动作文件在 30 FPS 采样下已经够用，升到 120 只会让 JSON 从几百 KB 膨胀到几 MB，而肉眼几乎看不出差别。

4.3 插值保留：贝塞尔关键帧导出后为什么缺了味道

Blender 里的动画默认用贝塞尔插值，关键帧之间是曲线过渡，不是直线。逐帧采样时，这个曲线特性已经被烘焙进球数据里了，引擎端只需要做线性插值即可还原得差不多。但如果你走关键帧保留路线，直接把贝塞尔手柄数值丢给引擎，多数引擎并不认贝塞尔手柄。

处理办法有两种：一是把贝塞尔关键帧重采样成若干中间帧，把曲线拆成一堆密集的线性片段；二是只保留关键帧本身，引擎端的插值算法负责过渡。前一种输出量大，后一种在快速转身动作上容易出现“甩鞭子”效果。

我的建议是：优先做逐帧烘焙，别在第一步就尝试保留插值类型。把导出器跑通、验证轨迹正确之后，再考虑精简关键帧的优化工作，这才能让优化有对比基准。

4.4 单位与名称规范化：别让命名问题变成绑定错乱

Blender 的单位默认是米，引擎如果需要厘米，得在序列化层统一乘以 100。这个小问题会在角色比例和物理碰撞上放大。

骨骼命名更值得重视。Blender 里复制骨骼时自动追加.001、.002后缀。如果引擎按名称匹配骨骼，把Bone.001原样导出去，绑定阶段就要出幺蛾子。常见做法是提供一张名称映射表，导出前把.001这类后缀清理掉，同时保留一个原始名到目标名的映射。

名称规范化还会碰到左右骨骼的问题。Blender 里常用.L/.R后缀区分左右，引擎可能期望_left/_right，或者根本不区分。这些工作如果不做，角色导入后会出现左手动画套在右手骨骼上的灾难。

5. 避坑手册：动画导出最常遇见的五类翻车现场

5.1 NLA 轨道动画导出为空

现象：在 Blender 里 NLA 编辑器中角色动画正常播放，导出后动作文件里只有第一帧，或者只有某个片段的动作。 原因：F-Curve 求值链受 NLA Track 的激活状态影响。NLA 里堆叠的 Action 片段并不会自动合并进 pose_bone.matrix，它们只有在对应的 NLA Track 被激活时才会求值。 解决：导出前把 NLA 动画烘焙到新的 Action。常见操作是选中骨架，使用 Bake Action 操作生成一个完整的关键帧 Action，导出器只认这个烘焙结果，不直接读取原始 NLA 片段。

5.2 动画中腿部突然反向扭曲

现象：角色走路动画在拐弯或抬腿瞬间，膝盖朝向突然反了 180 度，像“折腿”。 原因：目标引擎的旋转通道使用欧拉角，而 Blender 骨骼的原始旋转是四元数。欧拉角存在万向锁问题，在特定姿态下插值路径会绕远路。 解决：导出时统一输出四元数，引擎侧也按四元数处理插值。如果引擎只认欧拉角，至少固定旋转次序（比如 XYZ），并在旋转分量接近 180 度时做符号修正。这种故障排查起来非常费时，我在项目里通常直接禁止欧拉角导出。

5.3 骨骼名带.001导致绑定错位

现象：导出后角色模型四肢扭曲到不自然的位置，但动画本身没有破绽。 原因：Blender 复制骨骼后默认追加.001后缀，引擎按骨骼名称匹配 bind pose 时找不到对应骨骼，退而求其次匹配到了错误的骨骼。 解决：在导出器里内置一个名称清理函数，把骨骼名里的.001、.002去掉，并输出一份 mapping 表给引擎侧使用。注意改名不能破坏骨骼父子关系，只改字符串，不重建骨架。

5.4 采样帧范围覆盖了无关键帧的空段

现象：动画文件里出现一段莫名其妙的多余过渡动作，Blender 源文件里并没有这些帧。 原因：action.frame_range返回的是整个 Action 的时间跨度。如果某些通道只有前半段有关键帧、后半段为空，frame_set求值时会自动用线性插值填补空段，生成了 Blender 编辑界面里看不到的“假动作”。 解决：在采样前检查每个 fcurve 的实际关键帧范围，取所有通道范围的并集作为采样区间。空档处选择跳过，或者判定为“该通道保持上一帧值”。

5.5 左手系镜像后骨骼交叉

现象：导出到左手系引擎后，角色左手动作出现在右手上，或者双手在胸前交叉。 原因：手性翻转只作用在动画数据上，而模型顶点没有同步翻转，或者翻转轴选择与模型不一致。 解决：手性翻转必须同时作用于模型和动画数据。检查引擎的坐标轴向定义，确认翻转轴后，在导出器里用同一个矩阵处理 mesh 顶点和骨骼矩阵。最简单的方法是先在 Blender 里把模型和动画都按目标轴向摆好，再导出，把问题消灭在源头。

6. 进阶：验证导出结果的实用技巧与关键帧精简思路

6.1 用空物体加轨迹可视化，五分钟验证动作有没有丢

导出完不能直接丢给引擎，应该先在 Blender 里把导出的数据“回读”验证一遍。我常用空物体加轨迹功能做这个事。读取 JSON 中根骨骼的t数据，创建一个空物体，逐帧设置其位置，然后打开空物体的轨迹显示。如果轨迹连贯平滑，说明动画数据没有丢帧；如果轨迹出现折线或断点，说明采样率不够或空段处理有问题。

这个方法对全身动画同样适用，你可以对每个骨骼位置创建小立方体并显示轨迹，快速检查四肢末端在空间中的运动路径是否和源动作一致。端部轨迹是最敏感的检验点，比观察旋转数值更直观。

6.2 关键帧精简：用近似度换文件体积

逐帧烘焙输出的 JSON 虽然稳定，但体积往往冗余。如果目标引擎对插值支持较好，可以在导出后做一次关键帧精简，降低文件里的姿态帧数。一个简单的思路是对每个骨骼的位置通道单独做折线近似，设定误差阈值，能近似替代掉的中间帧直接丢弃。

具体做法是遍历当前骨骼的位移采样点序列，对每一段尝试用首尾两点连成的直线去拟合中间点，如果中间点到拟合直线的最大距离小于阈值，就认为这些中间点可以被安全丢弃。这个算法本质上是道格拉斯-普克抽稀算法的简化版，配合四元数通道单独计算误差。

实际测试时，阈值从很小开始调（比如模型单位下的 0.001），观察引擎端动作变化。注意精简只针对线性可替代的段做，剧烈旋转片段必须保留全部关键帧，否则动感会明显丢失。

我在某个跨平台项目里就吃过亏：当时图省事只导出了局部姿态通道，运行时再让引擎做插值，结果转身动画时脚跟离地。后来统一改成逐帧烘焙、根骨骼轨迹先行验证，问题再没出现过。动画导出器不是“写完就完”的类型，花半小时把验证流程搭好，能省下后面几天的调试时间。希望这篇笔记能帮你在自己的项目里少踩我踩过的这些坑。

本文还有配套的精品资源，点击获取