# 高级骨骼动画系统插件

## 概述

高级骨骼动画系统插件为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项目的许可证条款。

## 联系方式

如有任何问题或建议，请联系开发团队。