EG/plugins/user/skeletal_animation_system

骨骼动画系统插件

概述

骨骼动画系统插件为EG项目提供完整的骨骼动画支持。该插件基于Panda3D的Actor系统，支持模型加载、动画播放、速度控制、动画混合等高级功能。

功能特性

1. Actor模型加载 - 支持加载带有骨骼动画的3D模型
2. 动画播放控制 - 播放、停止、暂停、恢复动画
3. 速度调节 - 可调节动画播放速度
4. 动画混合 - 支持多个动画之间的平滑混合
5. 序列播放 - 支持动画序列的连续播放
6. 事件驱动 - 通过事件系统控制动画播放
7. GUI控制面板 - 提供可视化控制界面
8. 多Actor管理 - 支持同时管理多个动画角色
9. 动画信息查询 - 提供详细的动画状态信息

系统架构

插件采用模块化设计，包含以下核心组件：

1. SkeletalAnimationManager - 核心动画管理器，负责Actor和动画的管理
2. AnimationEventManager - 事件管理器，处理事件驱动的动画控制
3. SkeletalAnimationGUI - GUI界面，提供可视化控制面板

安装和启用

启用插件

在主程序中启用插件:

# 启用插件系统
world.plugin_manager.enable_plugin_system()

# 启用骨骼动画插件
world.plugin_manager.enable_plugin("skeletal_animation_system")

使用方法

基本使用

# 获取插件实例
skeletal_plugin = world.plugin_manager.get_plugin("skeletal_animation_system")
animation_manager = skeletal_plugin.get_animation_manager()

# 加载Actor模型
actor, actor_id = animation_manager.load_actor(
    model_path="path/to/model.egg",
    anim_dict={
        "walk": "path/to/walk.egg",
        "run": "path/to/run.egg"
    },
    actor_id="my_hero",  # 可选，自动生成如果未提供
    position=(0, 0, 0),  # 可选
    scale=1.0            # 可选
)

# 播放动画
if actor:
    animation_manager.play_animation(actor_id, "walk", loop=True)

高级使用

# 动画混合
blend = animation_manager.blend_animations(
    actor_id, 
    "walk", 
    "run", 
    blend_time=2.0,
    loop=True
)

# 创建动画序列
sequence = animation_manager.create_animation_sequence(
    actor_id, 
    ["walk", "run", "jump"], 
    loop=True
)

# 获取动画信息
anim_info = animation_manager.get_animation_info(actor_id, "walk")
actor_info = animation_manager.get_actor_info(actor_id)

事件驱动控制

插件注册了以下事件:

• skeletal.load_actor - 加载Actor模型
• skeletal.play_animation - 播放动画
• skeletal.stop_animation - 停止动画
• skeletal.set_animation_speed - 设置动画速度
• skeletal.pause_animation - 暂停动画
• skeletal.resume_animation - 恢复动画

使用方法:

# 通过事件加载Actor
world.send("skeletal.load_actor", [
    "models/character.egg",
    {"walk": "anim/walk.egg"},
    "hero",
    (0, 0, 0),
    1.0
])

# 通过事件播放动画
world.send("skeletal.play_animation", ["hero", "walk", True, 1.0])

API参考

SkeletalAnimationManager 类

load_actor(model_path, anim_dict=None, actor_id=None, position=None, scale=None)

加载Actor模型

参数:

• model_path (str): 模型文件路径
• anim_dict (dict): 动画文件路径字典，格式 {'anim_name': 'anim_path'}
• actor_id (str): Actor标识符，如果为None则自动生成
• position (tuple): 位置坐标 (x, y, z)
• scale (float or tuple): 缩放比例

返回:

• Actor对象和actor_id

unload_actor(actor_id)

卸载Actor

参数:

• actor_id (str): 要卸载的Actor标识符

play_animation(actor_id, anim_name, loop=False, play_rate=1.0, start_frame=None, end_frame=None)

播放动画

参数:

• actor_id (str): Actor标识符
• anim_name (str): 动画名称
• loop (bool): 是否循环播放
• play_rate (float): 播放速度
• start_frame (int): 起始帧
• end_frame (int): 结束帧

stop_animation(actor_id, anim_name=None)

停止动画

参数:

• actor_id (str): Actor标识符
• anim_name (str): 动画名称，如果为None则停止所有动画

set_animation_speed(actor_id, anim_name, speed)

设置动画播放速度

参数:

• actor_id (str): Actor标识符
• anim_name (str): 动画名称
• speed (float): 播放速度

pause_animation(actor_id, anim_name=None)

暂停动画

参数:

• actor_id (str): Actor标识符
• anim_name (str): 动画名称，如果为None则暂停所有动画

resume_animation(actor_id, anim_name=None)

恢复动画播放

参数:

• actor_id (str): Actor标识符
• anim_name (str): 动画名称，如果为None则恢复所有动画

blend_animations(actor_id, from_anim, to_anim, blend_time=1.0, loop=True)

混合两个动画

参数:

• actor_id (str): Actor标识符
• from_anim (str): 起始动画名称
• to_anim (str): 目标动画名称
• blend_time (float): 混合时间
• loop (bool): 是否循环混合

create_animation_sequence(actor_id, anim_list, loop=False)

创建动画序列

参数:

• actor_id (str): Actor标识符
• anim_list (list): 动画名称列表
• loop (bool): 是否循环播放序列

get_actor_animations(actor_id)

获取Actor的所有动画名称

参数:

• actor_id (str): Actor标识符

返回:

• 动画名称列表

get_animation_info(actor_id, anim_name)

获取动画信息

参数:

• actor_id (str): Actor标识符
• anim_name (str): 动画名称

返回:

• 动画信息字典

get_actor_info(actor_id)

获取Actor详细信息

参数:

• actor_id (str): Actor标识符

返回:

• Actor信息字典

支持的文件格式

• 模型格式: .egg, .bam, .fbx, .gltf, .glb等Panda3D支持的格式
• 动画格式: .egg, .bam等包含动画数据的格式

配置选项

插件支持以下配置选项（config.json）:

• default_play_rate: 默认播放速度
• default_loop: 默认循环播放设置
• enable_gui: 是否启用GUI控制面板
• enable_events: 是否启用事件系统
• max_actors: 最大Actor数量
• animation_cache_size: 动画缓存大小
• blend_default_time: 默认混合时间
• debug_mode: 调试模式

注意事项

1. 确保模型文件包含正确的骨骼信息
2. 动画文件需要与模型骨骼结构匹配
3. 插件会在禁用时自动清理所有加载的Actor
4. 使用完毕后应调用unload_actor释放资源
5. 大量Actor可能影响性能，注意优化
6. 某些格式（如FBX）可能需要额外的转换处理

故障排除

常见问题及解决方案:

1. 模型加载失败: 检查文件路径和格式支持
2. 动画无法播放: 确认动画名称正确且与模型匹配
3. 性能问题: 减少同时播放的动画数量，及时卸载不需要的Actor
4. 事件无响应: 确认插件已正确启用且事件系统工作正常

扩展开发

插件采用模块化设计，可以轻松扩展:

1. 继承SkeletalAnimationManager添加新功能
2. 扩展AnimationEventManager处理自定义事件
3. 修改SkeletalAnimationGUI创建自定义界面
4. 添加新的动画控制算法

示例代码

查看 examples.py 文件获取详细的使用示例。