# Morphing和变形动画插件

## 概述

Morphing和变形动画插件为EG项目提供了一个完整且功能丰富的顶点变形、morphing目标和网格变形解决方案。该插件支持模型的顶点级动画控制，包括Morph目标创建、动画状态管理、物理集成、性能优化和网络同步等高级功能。

## 功能特性

### 核心功能
1. **模型注册与管理** - 支持注册3D模型以进行morphing操作
2. **Morph目标创建** - 创建和管理Morph目标，包括顶点、法线和切线偏移
3. **权重控制** - 精确控制每个Morph目标的权重
4. **顶点变形** - 支持直接顶点位置变形动画
5. **程序化变形** - 支持自定义变形函数

### 高级功能
1. **动画状态机** - 管理复杂的动画状态转换和混合
2. **动画曲线编辑器** - 支持对动画属性进行曲线编辑和自定义
3. **物理动画集成** - 将物理模拟与顶点变形结合

### 性能优化
1. **动画压缩** - 支持多种压缩算法减少动画数据大小
2. **LOD系统** - 根据距离和性能自动调整动画质量
3. **智能缓存** - 提供高效的动画数据缓存机制

### 网络功能
1. **动画状态同步** - 支持多人环境中动画状态的同步
2. **分布式动画管理** - 管理网络环境中的动画同步
3. **状态序列化** - 支持动画状态的序列化和反序列化

## 系统架构

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

1. **MorphingCore** - 核心变形管理器，负责模型和Morph目标的管理
2. **AnimationStateMachine** - 动画状态机，管理复杂的动画状态转换
3. **AnimationCurveEditor** - 动画曲线编辑器，支持动画属性的曲线控制
4. **PhysicsAnimationIntegration** - 物理动画集成系统，结合物理模拟与变形
5. **AnimationCompressor** - 动画压缩系统，减少动画数据大小
6. **AnimationLODSystem** - 动画LOD系统，根据条件调整动画质量
7. **AnimationCacheManager** - 动画缓存管理器，提高动画加载性能
8. **AnimationNetworkSync** - 网络同步系统，处理网络环境中的动画同步

## 安装和启用

### 启用插件

在主程序中启用插件:

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

# 启用Morphing动画插件
world.plugin_manager.enable_plugin('morphing_animation')
```

## 使用方法

### 基本使用

```python
# 获取插件实例
plugin = world.plugin_manager.get_plugin('morphing_animation')
core_system = plugin.get_core_system()

# 注册模型
model_id = core_system.register_model(model_node, 'my_model')

# 创建Morph目标
vertex_offsets = [(0.1, 0.0, 0.0)] * vertex_count  # 顶点偏移数据
core_system.create_morph_target(model_id, 'smile', vertex_offsets)

# 设置Morph目标权重
core_system.set_morph_target_weight(model_id, 'smile', 0.5)
```

### 高级使用

```python
# 使用状态机
state_machine = plugin.get_state_machine_system(model_id)
state_machine.add_state('idle', {'neutral': 1.0}, loop=True)
state_machine.add_state('happy', {'smile': 1.0}, duration=2.0)
state_machine.set_transition('idle', 'happy')
state_machine.enter_state('idle')
state_machine.start_updating()

# 使用曲线编辑器
curve_editor = plugin.get_curve_editor_system()
control_points = [(0.0, 0.0), (0.5, 1.0), (1.0, 0.0)]
curve_editor.create_curve('bounce', CurveType.BEZIER, control_points)
curve_editor.apply_curve_to_morph_target('bounce', model_id, 'smile', 0.5)

# 使用物理集成
physics_system = plugin.get_physics_integration_system()
physics_system.add_constraint(model_id, 'spring_smile', 'spring', 'smile', stiffness=2.0)
physics_system.start_updating()
```

### 性能优化

```python
# 使用压缩系统
compressor = plugin.get_compressor_system()
compressed_data = compressor.compress_morph_data(morph_data, CompressionMethod.KEYFRAME_REDUCTION)

# 使用LOD系统
lod_system = plugin.get_lod_system()
lod_system.set_camera(world.camera)
lod_system.update_lod_levels(models)

# 使用缓存管理
cache_manager = plugin.get_cache_manager_system()
cache_manager.put('key', data)
cached_data = cache_manager.get('key')
```

### 网络同步

```python
# 获取网络系统
network_system = plugin.get_network_system()

# 设置网络模式
network_system.set_network_mode(NetworkMode.SERVER)
network_system.set_sync_mode(SyncMode.STATE_SYNC)

# 注册模型进行网络同步
network_id = network_system.register_model_for_sync(model_id)

# 启动同步任务
network_system.start_sync_task()
```

## API参考

### MorphingCore 类

#### register_model(model_node, model_id=None)
注册模型以支持morphing

**参数:**
- `model_node` (NodePath): 模型节点
- `model_id` (str): 模型ID，如果为None则自动生成

**返回:**
- 模型ID

#### unregister_model(model_id)
注销模型

**参数:**
- `model_id` (str): 模型ID

#### create_morph_target(model_id, target_name, vertex_offsets, normal_offsets=None, tangent_offsets=None)
创建Morph目标

**参数:**
- `model_id` (str): 模型ID
- `target_name` (str): 目标名称
- `vertex_offsets` (list): 顶点偏移列表
- `normal_offsets` (list): 法线偏移列表（可选）
- `tangent_offsets` (list): 切线偏移列表（可选）

#### set_morph_target_weight(model_id, target_name, weight)
设置Morph目标权重

**参数:**
- `model_id` (str): 模型ID
- `target_name` (str): 目标名称
- `weight` (float): 权重值 (0.0-1.0)

#### create_morphing_animation(model_id, anim_name, target_weights, duration, interpolation=InterpolationMode.LINEAR, loop=False)
创建Morphing动画

**参数:**
- `model_id` (str): 模型ID
- `anim_name` (str): 动画名称
- `target_weights` (dict): 目标权重字典 {target_name: weight}
- `duration` (float): 持续时间
- `interpolation` (InterpolationMode): 插值模式
- `loop` (bool): 是否循环

#### play_morphing_animation(model_id, anim_name)
播放Morphing动画

**参数:**
- `model_id` (str): 模型ID
- `anim_name` (str): 动画名称

### AnimationStateMachine 类

#### add_state(state_name, morph_targets, duration=0.0, loop=False, play_rate=1.0)
添加动画状态

**参数:**
- `state_name` (str): 状态名称
- `morph_targets` (dict): Morph目标权重字典 {target_name: weight}
- `duration` (float): 持续时间
- `loop` (bool): 是否循环
- `play_rate` (float): 播放速度

#### set_transition(from_state, to_state, transition_type=TransitionType.SMOOTH, condition=None, transition_time=0.3, blend_mode=InterpolationMode.LINEAR)
设置状态转换

**参数:**
- `from_state` (str): 起始状态
- `to_state` (str): 目标状态
- `transition_type` (TransitionType): 转换类型
- `condition` (function): 转换条件函数
- `transition_time` (float): 转换时间
- `blend_mode` (InterpolationMode): 混合模式

#### enter_state(state_name)
进入指定状态

**参数:**
- `state_name` (str): 状态名称

### AnimationCurveEditor 类

#### create_curve(curve_name, curve_type, control_points, interpolation=InterpolationMode.LINEAR)
创建动画曲线

**参数:**
- `curve_name` (str): 曲线名称
- `curve_type` (CurveType): 曲线类型
- `control_points` (list): 控制点列表 [(time, value)]
- `interpolation` (InterpolationMode): 插值模式

#### apply_curve_to_morph_target(curve_name, model_id, target_name, time, base_weight=1.0)
将曲线应用到Morph目标

**参数:**
- `curve_name` (str): 曲线名称
- `model_id` (str): 模型ID
- `target_name` (str): Morph目标名称
- `time` (float): 时间
- `base_weight` (float): 基础权重

### PhysicsAnimationIntegration 类

#### add_constraint(model_id, constraint_name, constraint_type, target_bone, stiffness=1.0, damping=0.1, rest_value=0.0)
添加物理约束

**参数:**
- `model_id` (str): 模型ID
- `constraint_name` (str): 约束名称
- `constraint_type` (str): 约束类型 ('spring', 'distance', 'angle')
- `target_bone` (str): 目标骨骼
- `stiffness` (float): 刚度
- `damping` (float): 阻尼
- `rest_value` (float): 静止值

### AnimationCompressor 类

#### compress_morph_data(morph_data, method=CompressionMethod.KEYFRAME_REDUCTION)
压缩Morph数据

**参数:**
- `morph_data` (list): Morph数据列表
- `method` (CompressionMethod): 压缩方法

**返回:**
- CompressedMorphData对象

### AnimationLODSystem 类

#### set_lod_strategy(strategy)
设置LOD策略

**参数:**
- `strategy` (LODStrategy): LOD策略

#### set_distance_thresholds(thresholds)
设置距离阈值

**参数:**
- `thresholds` (list): 距离阈值列表

#### update_lod_levels(models)
更新LOD级别

**参数:**
- `models` (dict): 模型字典 {model_id: model_data}

### AnimationCacheManager 类

#### get(key)
获取缓存项

**参数:**
- `key` (str): 缓存键

**返回:**
- 缓存数据

#### put(key, data, size=1)
放入缓存项

**参数:**
- `key` (str): 缓存键
- `data` (any): 缓存数据
- `size` (int): 数据大小

### AnimationNetworkSync 类

#### set_network_mode(mode)
设置网络模式

**参数:**
- `mode` (NetworkMode): 网络模式

#### set_sync_mode(mode)
设置同步模式

**参数:**
- `mode` (SyncMode): 同步模式

#### register_model_for_sync(model_id, network_id=None)
注册模型以进行网络同步

**参数:**
- `model_id` (str): 本地模型ID
- `network_id` (str): 网络ID，如果为None则自动生成

**返回:**
- 网络ID

## 支持的文件格式

- 模型格式: .egg, .bam 等Panda3D支持的格式
- Morph数据可以以多种格式存储和加载

## 配置选项

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

```json
{
    "modules": {
        "core": {
            "enabled": true,
            "max_morph_targets": 100,
            "default_interpolation": "linear",
            "update_rate": 60,
            "cache_size": 200
        },
        "advanced": {
            "state_machine": true,
            "curve_editor": true,
            "physics_integration": true,
            "state_machine_update_rate": 30,
            "curve_editor_points": 100,
            "physics_update_rate": 60
        },
        "optimization": {
            "compression": true,
            "lod": true,
            "cache": true,
            "compression_threshold": 0.001,
            "cache_size": 500,
            "lod_distance_thresholds": [10.0, 25.0, 50.0],
            "lod_frame_rates": [1.0, 0.5, 0.25, 0.1]
        },
        "network": {
            "enabled": true,
            "sync_interval": 0.1,
            "interpolation_mode": "linear",
            "enable_compression": true,
            "max_buffer_size": 100
        }
    },
    "performance": {
        "target_fps": 60,
        "lod_threshold": 30,
        "max_buffer_size": 100
    }
}
```

## 性能优化建议

1. **使用LOD系统** - 根据模型距离摄像机的远近自动调整变形质量
2. **启用动画压缩** - 减少内存占用，提高加载速度
3. **合理使用缓存** - 避免重复计算相同变形
4. **优化网络同步** - 根据网络状况调整同步频率
5. **及时注销模型** - 不需要的模型及时调用unregister_model释放
6. **使用状态机** - 管理复杂动画状态，避免手动控制的复杂性

## 故障排除

常见问题及解决方案:

1. **模型注册失败**: 检查模型节点是否有效
2. **Morph目标创建失败**: 确认顶点偏移数据与模型顶点数量匹配
3. **变形效果不明显**: 检查权重值是否正确设置
4. **性能问题**: 减少同时变形的模型数量，启用LOD和压缩
5. **网络同步问题**: 确认网络模式设置正确，检查防火墙设置
6. **状态机问题**: 检查状态和转换定义是否正确

## 扩展开发

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

1. 继承现有类添加新功能
2. 实现自定义的压缩算法
3. 添加新的变形控制方式
4. 扩展网络同步协议
5. 集成其他物理引擎
6. 开发新的工具模块

## 示例代码

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

每个模块都有完整的使用示例，可以直接运行测试。

## 技术支持

如遇到问题，请查看以下资源：

1. 官方文档和API参考
2. 示例代码和使用说明
3. 社区论坛和技术支持
4. GitHub Issues页面

## 版本历史

### v1.0.0 (当前版本)
- 初始版本发布
- 实现完整的Morphing和变形动画系统
- 包含所有核心功能和高级特性
- 提供完整的文档和示例

## 许可证

本插件遵循EG项目的许可证条款。

## 联系方式

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