274 lines
7.1 KiB
Markdown
274 lines
7.1 KiB
Markdown
# 骨骼动画系统插件
|
||
|
||
## 概述
|
||
|
||
骨骼动画系统插件为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` 文件获取详细的使用示例。 |