EG/plugins/user/morphing_animation

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 - 网络同步系统，处理网络环境中的动画同步

安装和启用

启用插件

在主程序中启用插件:

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

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

使用方法

基本使用

# 获取插件实例
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)

高级使用

# 使用状态机
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()

性能优化

# 使用压缩系统
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')

网络同步

# 获取网络系统
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）:

{
    "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项目的许可证条款。

联系方式

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