443 lines
12 KiB
Markdown
443 lines
12 KiB
Markdown
# 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项目的许可证条款。
|
||
|
||
## 联系方式
|
||
|
||
如有任何问题或建议，请联系开发团队。 |