# 骨骼动画系统插件

## 概述

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

## 功能特性

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

## 系统架构

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

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

## 安装和启用

### 启用插件

在主程序中启用插件:

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

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

## 使用方法

### 基本使用

```python
# 获取插件实例
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)
```

### 高级使用

```python
# 动画混合
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` - 恢复动画

使用方法:

```python
# 通过事件加载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` 文件获取详细的使用示例。