524 lines
14 KiB
Markdown
524 lines
14 KiB
Markdown
# 高级骨骼动画系统插件
|
||
|
||
## 概述
|
||
|
||
高级骨骼动画系统插件为EG项目提供了一个完整且功能丰富的骨骼动画解决方案。该插件基于Panda3D的Actor系统，提供了从基础动画播放到高级动画控制的全套功能，包括动画状态机、逆向运动学、物理集成、动画压缩、网络同步和性能优化等。
|
||
|
||
## 功能特性
|
||
|
||
### 核心功能
|
||
1. **Actor模型加载** - 支持加载带有骨骼动画的3D模型
|
||
2. **动画播放控制** - 播放、停止、暂停、恢复动画
|
||
3. **速度调节** - 可调节动画播放速度
|
||
4. **动画混合** - 支持多个动画之间的平滑混合
|
||
5. **序列播放** - 支持动画序列的连续播放
|
||
6. **事件驱动** - 通过事件系统控制动画播放
|
||
|
||
### 高级功能
|
||
1. **动画状态机** - 管理复杂的动画状态转换和混合
|
||
2. **逆向运动学系统** - 实现骨骼的IK控制
|
||
3. **动画曲线编辑器** - 支持对动画属性进行曲线编辑和自定义
|
||
4. **物理动画集成** - 将物理模拟与骨骼动画结合
|
||
|
||
### 性能优化
|
||
1. **动画压缩** - 支持关键帧压缩、量化等多种压缩算法
|
||
2. **LOD系统** - 根据距离和性能自动调整动画质量
|
||
3. **智能缓存** - 提供高效的动画数据缓存机制
|
||
|
||
### 网络功能
|
||
1. **动画状态同步** - 支持多人环境中动画状态的同步
|
||
2. **分布式动画管理** - 管理网络环境中的动画同步
|
||
3. **状态序列化** - 支持动画状态的序列化和反序列化
|
||
|
||
### 工具系统
|
||
1. **动画分析器** - 提供动画性能、质量和内存使用分析
|
||
2. **动画编辑器** - 支持关键帧编辑、曲线编辑等功能
|
||
3. **调试可视化工具** - 提供骨骼、边界框等可视化功能
|
||
4. **性能分析器** - 提供详细的性能分析和优化建议
|
||
|
||
## 系统架构
|
||
|
||
插件采用模块化设计，包含以下核心组件：
|
||
|
||
1. **SkeletalAnimationCore** - 核心动画管理器，负责Actor和动画的管理
|
||
2. **AnimationNetworkSync** - 网络同步系统，处理网络环境中的动画同步
|
||
3. **AnimationStateMachine** - 动画状态机，管理复杂的动画状态转换
|
||
4. **AnimationCurveEditor** - 动画曲线编辑器，支持动画属性的曲线控制
|
||
5. **PhysicsAnimationIntegration** - 物理动画集成系统，结合物理模拟与动画
|
||
6. **AnimationCompressor** - 动画压缩系统，减少动画数据大小
|
||
7. **AnimationLODSystem** - 动画LOD系统，根据条件调整动画质量
|
||
8. **AnimationCacheManager** - 动画缓存管理器，提高动画加载性能
|
||
9. **AnimationAnalyzer** - 动画分析器，分析动画性能和质量
|
||
10. **AnimationEditor** - 动画编辑器，提供关键帧编辑功能
|
||
11. **DebugVisualizer** - 调试可视化工具，提供可视化调试功能
|
||
12. **AnimationProfiler** - 性能分析器，分析动画系统性能
|
||
|
||
## 安装和启用
|
||
|
||
### 启用插件
|
||
|
||
在主程序中启用插件:
|
||
|
||
```python
|
||
# 启用插件系统
|
||
world.plugin_manager.enable_plugin_system()
|
||
|
||
# 启用高级骨骼动画插件
|
||
world.plugin_manager.enable_plugin("advanced_skeletal_animation")
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 基本使用
|
||
|
||
```python
|
||
# 获取插件实例
|
||
plugin = world.plugin_manager.get_plugin("advanced_skeletal_animation")
|
||
core_system = plugin.get_core_system()
|
||
|
||
# 加载Actor模型
|
||
actor, actor_id = core_system.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:
|
||
core_system.play_animation(actor_id, "walk", loop=True)
|
||
```
|
||
|
||
### 高级使用
|
||
|
||
```python
|
||
# 动画混合
|
||
core_system.blend_animations(
|
||
actor_id,
|
||
"walk",
|
||
"run",
|
||
blend_time=2.0
|
||
)
|
||
|
||
# 获取动画信息
|
||
anim_info = core_system.get_animation_info(actor_id, "walk")
|
||
actor_info = core_system.get_actor_info(actor_id)
|
||
```
|
||
|
||
### 状态机使用
|
||
|
||
```python
|
||
from plugins.user.advanced_skeletal_animation.advanced import AnimationStateMachine
|
||
|
||
# 创建状态机
|
||
state_machine = AnimationStateMachine(actor)
|
||
|
||
# 添加状态
|
||
state_machine.add_state("idle", "idle_anim", loop=True)
|
||
state_machine.add_state("walk", "walk_anim", loop=True)
|
||
state_machine.add_state("run", "run_anim", loop=True)
|
||
|
||
# 设置状态转换
|
||
state_machine.set_transition("idle", "walk")
|
||
state_machine.set_transition("walk", "run")
|
||
state_machine.set_transition("run", "idle")
|
||
|
||
# 进入初始状态
|
||
state_machine.enter_state("idle")
|
||
|
||
# 在更新循环中更新状态机
|
||
def state_machine_update(task):
|
||
dt = globalClock.getDt()
|
||
state_machine.update(dt)
|
||
return task.cont
|
||
|
||
world.taskMgr.add(state_machine_update, "state_machine_update")
|
||
```
|
||
|
||
### 网络同步使用
|
||
|
||
```python
|
||
# 获取网络系统
|
||
network_system = plugin.get_network_system()
|
||
|
||
# 设置网络模式
|
||
from plugins.user.advanced_skeletal_animation.network import NetworkMode, SyncMode
|
||
network_system.set_network_mode(NetworkMode.SERVER)
|
||
network_system.set_sync_mode(SyncMode.STATE_SYNC)
|
||
|
||
# 注册Actor进行网络同步
|
||
network_id = network_system.register_actor_for_sync(actor_id)
|
||
```
|
||
|
||
### 工具系统使用
|
||
|
||
```python
|
||
# 获取分析器
|
||
analyzer = plugin.get_analyzer()
|
||
analyzer.start_analysis()
|
||
|
||
# 分析动画
|
||
analysis_result = analyzer.analyze_animation(actor_id, "walk", AnimationAnalysisType.PERFORMANCE)
|
||
|
||
# 获取编辑器
|
||
editor = plugin.get_editor()
|
||
editor.start_editing(actor_id, "walk")
|
||
|
||
# 获取可视化工具
|
||
visualizer = plugin.get_visualizer()
|
||
visualizer.enable_visualization(True)
|
||
visualizer.set_mode(DebugVisualizationMode.SKELETON)
|
||
|
||
# 获取性能分析器
|
||
profiler = plugin.get_profiler()
|
||
profiler.start_profiling()
|
||
```
|
||
|
||
## API参考
|
||
|
||
### SkeletalAnimationCore 类
|
||
|
||
#### 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, blend_mode='linear')
|
||
混合两个动画
|
||
|
||
**参数:**
|
||
- `actor_id` (str): Actor标识符
|
||
- `from_anim` (str): 起始动画名称
|
||
- `to_anim` (str): 目标动画名称
|
||
- `blend_time` (float): 混合时间
|
||
- `blend_mode` (str): 混合模式 ('linear', 'ease_in', 'ease_out', 'ease_in_out')
|
||
|
||
#### 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信息字典
|
||
|
||
### AnimationStateMachine 类
|
||
|
||
#### add_state(state_name, animations, loop=True, play_rate=1.0, blend_time=0.3)
|
||
添加动画状态
|
||
|
||
**参数:**
|
||
- `state_name` (str): 状态名称
|
||
- `animations` (str or list): 动画名称或列表
|
||
- `loop` (bool): 是否循环
|
||
- `play_rate` (float): 播放速度
|
||
- `blend_time` (float): 状态切换混合时间
|
||
|
||
#### set_transition(from_state, to_state, transition_type='smooth', condition=None, transition_time=0.3)
|
||
设置状态转换
|
||
|
||
**参数:**
|
||
- `from_state` (str): 起始状态
|
||
- `to_state` (str): 目标状态
|
||
- `transition_type` (str): 转换类型 ('immediate', 'smooth', 'blend', 'conditional')
|
||
- `condition` (function): 转换条件函数
|
||
- `transition_time` (float): 转换时间
|
||
|
||
#### enter_state(state_name)
|
||
进入指定状态
|
||
|
||
**参数:**
|
||
- `state_name` (str): 状态名称
|
||
|
||
### AnimationNetworkSync 类
|
||
|
||
#### set_network_mode(mode)
|
||
设置网络模式
|
||
|
||
**参数:**
|
||
- `mode` (NetworkMode): 网络模式 (DISABLED, SERVER, CLIENT, PEER_TO_PEER)
|
||
|
||
#### set_sync_mode(mode)
|
||
设置同步模式
|
||
|
||
**参数:**
|
||
- `mode` (SyncMode): 同步模式 (STATE_SYNC, INPUT_SYNC, INTERPOLATION)
|
||
|
||
#### register_actor_for_sync(actor_id, network_id=None)
|
||
注册Actor以进行网络同步
|
||
|
||
**参数:**
|
||
- `actor_id` (str): Actor ID
|
||
- `network_id` (str): 网络ID，如果为None则自动生成
|
||
|
||
**返回:**
|
||
- 网络ID
|
||
|
||
### AnimationCompressor 类
|
||
|
||
#### compress_animation(actor, anim_name, method='keyframe_reduction')
|
||
压缩指定动画
|
||
|
||
**参数:**
|
||
- `actor` (Actor): Actor对象
|
||
- `anim_name` (str): 动画名称
|
||
- `method` (str): 压缩方法 ('keyframe_reduction', 'quantization', 'delta_compression', 'rle')
|
||
|
||
**返回:**
|
||
- 压缩后的动画数据
|
||
|
||
### AnimationAnalyzer 类
|
||
|
||
#### analyze_animation(actor_id, anim_name, analysis_type=AnimationAnalysisType.PERFORMANCE)
|
||
分析指定动画
|
||
|
||
**参数:**
|
||
- `actor_id` (str): Actor ID
|
||
- `anim_name` (str): 动画名称
|
||
- `analysis_type` (AnimationAnalysisType): 分析类型 (PERFORMANCE, QUALITY, MEMORY, COMPRESSION)
|
||
|
||
**返回:**
|
||
- 分析结果
|
||
|
||
### AnimationEditor 类
|
||
|
||
#### start_editing(actor_id, anim_name)
|
||
开始编辑动画
|
||
|
||
**参数:**
|
||
- `actor_id` (str): Actor ID
|
||
- `anim_name` (str): 动画名称
|
||
|
||
**返回:**
|
||
- 是否成功开始编辑
|
||
|
||
#### add_keyframe(actor_id, anim_name, bone_name, frame, position=None, rotation=None, scale=None)
|
||
添加关键帧
|
||
|
||
**参数:**
|
||
- `actor_id` (str): Actor ID
|
||
- `anim_name` (str): 动画名称
|
||
- `bone_name` (str): 骨骼名称
|
||
- `frame` (int): 帧号
|
||
- `position` (tuple): 位置
|
||
- `rotation` (tuple): 旋转
|
||
- `scale` (tuple): 缩放
|
||
|
||
### DebugVisualizer 类
|
||
|
||
#### set_mode(mode)
|
||
设置可视化模式
|
||
|
||
**参数:**
|
||
- `mode` (DebugVisualizationMode): 模式 (SKELETON, BOUNDS, NORMALS, WIREFRAME, COLLISION)
|
||
|
||
#### enable_visualization(enabled=True)
|
||
启用/禁用可视化
|
||
|
||
**参数:**
|
||
- `enabled` (bool): 是否启用
|
||
|
||
### AnimationProfiler 类
|
||
|
||
#### start_profiling()
|
||
开始性能分析
|
||
|
||
#### stop_profiling()
|
||
停止性能分析
|
||
|
||
#### get_performance_report()
|
||
获取性能报告
|
||
|
||
**返回:**
|
||
- 性能报告字典
|
||
|
||
## 支持的文件格式
|
||
|
||
- 模型格式: .egg, .bam, .fbx, .gltf, .glb等Panda3D支持的格式
|
||
- 动画格式: .egg, .bam等包含动画数据的格式
|
||
|
||
## 配置选项
|
||
|
||
插件支持以下配置选项（config.json）:
|
||
|
||
```json
|
||
{
|
||
"modules": {
|
||
"core": {
|
||
"enabled": true,
|
||
"max_actors": 1000,
|
||
"default_play_rate": 1.0,
|
||
"default_loop": false,
|
||
"blend_time": 0.3
|
||
},
|
||
"network": {
|
||
"enabled": true,
|
||
"sync_interval": 0.1,
|
||
"interpolation_mode": "linear",
|
||
"enable_compression": true
|
||
},
|
||
"advanced": {
|
||
"state_machine": true,
|
||
"curve_editor": true,
|
||
"physics_integration": true
|
||
},
|
||
"optimization": {
|
||
"compression": true,
|
||
"lod": true,
|
||
"cache": true,
|
||
"cache_size": 500
|
||
},
|
||
"tools": {
|
||
"analyzer": true,
|
||
"editor": true,
|
||
"visualizer": true,
|
||
"profiler": true
|
||
}
|
||
},
|
||
"performance": {
|
||
"target_fps": 60,
|
||
"lod_threshold": 30,
|
||
"max_buffer_size": 100
|
||
}
|
||
}
|
||
```
|
||
|
||
## 性能优化建议
|
||
|
||
1. **使用LOD系统** - 根据Actor距离摄像机的远近自动调整动画质量
|
||
2. **启用动画压缩** - 减少内存占用，提高加载速度
|
||
3. **合理使用缓存** - 避免重复加载相同动画数据
|
||
4. **优化网络同步** - 根据网络状况调整同步频率
|
||
5. **及时释放资源** - 不需要的Actor及时调用unload_actor释放
|
||
6. **使用工具系统** - 通过分析器和性能分析器找出性能瓶颈
|
||
|
||
## 故障排除
|
||
|
||
常见问题及解决方案:
|
||
|
||
1. **模型加载失败**: 检查文件路径和格式支持
|
||
2. **动画无法播放**: 确认动画名称正确且与模型匹配
|
||
3. **性能问题**: 减少同时播放的动画数量，及时卸载不需要的Actor
|
||
4. **网络同步问题**: 确认网络模式设置正确，检查防火墙设置
|
||
5. **状态机问题**: 检查状态和转换定义是否正确
|
||
6. **工具系统问题**: 确认工具模块已正确初始化
|
||
|
||
## 扩展开发
|
||
|
||
插件采用模块化设计，可以轻松扩展:
|
||
|
||
1. 继承现有类添加新功能
|
||
2. 实现自定义的压缩算法
|
||
3. 添加新的动画控制方式
|
||
4. 扩展网络同步协议
|
||
5. 集成其他物理引擎
|
||
6. 开发新的工具模块
|
||
|
||
## 示例代码
|
||
|
||
查看 `examples.py` 文件获取详细的使用示例。
|
||
|
||
每个模块都有完整的使用示例，可以直接运行测试。
|
||
|
||
## 技术支持
|
||
|
||
如遇到问题，请查看以下资源：
|
||
|
||
1. 官方文档和API参考
|
||
2. 示例代码和使用说明
|
||
3. 社区论坛和技术支持
|
||
4. GitHub Issues页面
|
||
|
||
## 版本历史
|
||
|
||
### v1.0.0 (当前版本)
|
||
- 初始版本发布
|
||
- 实现完整的骨骼动画系统
|
||
- 包含所有核心功能和高级特性
|
||
- 提供完整的文档和示例
|
||
- 添加工具系统支持
|
||
|
||
## 许可证
|
||
|
||
本插件遵循EG项目的许可证条款。
|
||
|
||
## 联系方式
|
||
|
||
如有任何问题或建议，请联系开发团队。 |