# 刚体动力学插件使用文档 ## 简介 刚体动力学插件是一个完整的物理模拟系统，基于Bullet物理引擎，提供了丰富的物理功能，包括刚体动力学、约束系统、车辆模拟、粒子系统等。 ## 功能特性 ### 1. 物理世界管理 - 重力设置和控制 - 时间步长和子步长模拟 - 性能监控和优化 - 多线程支持 - 空间分区优化 ### 2. 刚体系统 - 静态、动态、运动学刚体 - 多种碰撞形状（盒体、球体、胶囊体、圆锥体、圆柱体、凸包、网格、复合形状） - 质量、摩擦、弹性等物理属性 - 连续碰撞检测(CCD) - 力和扭矩应用 - 速度和加速度控制 - 能量计算（动能、势能） - 碰撞历史记录 ### 3. 材质系统 - 预定义常用材质（混凝土、木材、金属、橡胶、冰、沙、水、玻璃、肉体等） - 自定义材质属性 - 基础物理属性（摩擦、弹性、密度等） - 热力学属性（热导率、比热容等） - 电学属性（电导率、介电常数等） - 流体属性（粘度、表面张力等） - 视觉属性（颜色、粗糙度等） - 环境属性（耐候性、腐蚀率等） - 特殊属性（易燃性、毒性、放射性） - 高级材质功能 - 热膨胀和相变模拟 - 环境老化效应（雨水、紫外线、风力等） - 疲劳累积和损伤分析 - 化学反应和腐蚀模拟 - 流体动力学效应（阻力、升力、浮力） - 能量吸收和耗散 - 失效准则和结构完整性评估 - 动态摩擦和恢复系数计算 - 材质交互矩阵 - 材质状态管理（温度、湿度、磨损、疲劳、污染等） - 材质历史记录和统计分析 - 材质保存和加载 ### 4. 约束和关节 - 点对点约束 - 铰链约束 - 滑动约束 - 锥形扭转约束 - 6自由度约束 - 6自由度弹簧约束 - 齿轮约束 - 固定约束 - 约束组和标签管理 - 约束马达和弹簧控制 - 约束限制设置 - 约束状态监控 ### 5. 车辆系统 - 底盘和车轮物理 - 悬挂系统 - 引擎和刹车控制 - 转向系统 - 差速器类型支持 - 齿轮系统 - 发动机扭矩曲线 - 防抱死刹车(ABS) - 牵引力控制(TC) - 车身稳定控制(ESP) - 空气动力学效应 - 防倾杆系统 - 车辆损伤系统 - 燃料系统 - 性能统计 ### 6. 粒子系统 - 大量粒子模拟 - 多种粒子类型（烟雾、火焰、水、碎片、爆炸、火花、气泡、叶子、雪、雨等） - 发射器控制 - 粒子生命周期管理 - 环境影响（风力、温度等） - 特殊效果（涡流等） - 粒子子发射器 - 粒子轨迹和淡出效果 - 粒子碰撞和死亡回调 - 爆炸和火焰特效 ### 7. 调试和可视化 - 碰撞体可视化 - 约束可视化 - 接触点可视化 - 法线可视化 - 速度和力可视化 - 坐标轴可视化 - 质心可视化 - 休眠状态可视化 - 粒子轨迹可视化 - 性能监控面板 - 调试文本显示 - 可视化选项控制 ### 8. 实用工具 - 物理计算工具（质量计算、冲量应用、扭矩计算等） - 配置管理器 - 碰撞组定义 - 物理常量库 ## 安装和配置 ### 目录结构 ``` rigid_body_physics/ ├── __init__.py ├── plugin_manager.py ├── README.md ├── core/ │ ├── physics_world.py │ ├── rigid_body.py │ └── material.py ├── constraints/ │ └── constraint_manager.py ├── vehicles/ │ └── vehicle_system.py ├── particles/ │ └── particle_system.py ├── debug/ │ └── debug_tools.py ├── utils/ │ └── physics_utils.py └── config/ └── physics_config.json ``` ## 快速开始 ### 1. 初始化插件 ```python from plugins.user.rigid_body_physics.plugin_manager import RigidBodyPhysicsPlugin # 创建物理插件实例 physics_plugin = RigidBodyPhysicsPlugin(world_node=render) ``` ### 2. 创建刚体 ```python # 创建一个盒子形状的动态刚体 box_body = physics_plugin.create_rigid_body( node_path=box_node, shape_type='box', mass=1.0, body_type=RigidBody.DYNAMIC ) # 设置物理属性 box_body.set_friction(0.5) box_body.set_restitution(0.3) # 应用力和扭矩 box_body.apply_force(Vec3(0, 0, 100)) # 向上施加力 box_body.apply_torque(Vec3(0, 10, 0)) # 绕Y轴施加扭矩 ``` ### 3. 创建约束 ```python # 创建铰链约束 hinge_constraint = physics_plugin.create_constraint( constraint_type='hinge', body_a=body_a, body_b=body_b, pivot_a=Point3(0, 0, 0), pivot_b=Point3(0, 0, 0), axis_a=Vec3(0, 0, 1), axis_b=Vec3(0, 0, 1) ) ``` ### 4. 创建车辆 ```python # 定义车轮配置 wheel_configs = [ { 'connection_point': Point3(-1, 1, 0), 'wheel_direction': Vec3(0, 0, -1), 'wheel_axle': Vec3(1, 0, 0), 'wheel_radius': 0.3 }, # ... 其他车轮配置 ] # 创建车辆 vehicle = physics_plugin.create_vehicle(chassis_body, wheel_configs) # 控制车辆 vehicle.set_steering(0.5) # 转向 vehicle.set_engine_force(1.0) # 加油 vehicle.set_brake_force(0.3) # 刹车 ``` ### 5. 创建粒子系统 ```python # 创建粒子系统 particle_system = physics_plugin.create_particle_system(max_particles=500) # 设置发射器属性 particle_system.set_emitter_properties( position=Point3(0, 0, 5), velocity=Vec3(0, 0, 10), spread=0.5 ) # 创建爆炸效果 particle_system.create_explosion( position=Point3(0, 0, 0), particle_count=100, explosion_force=50.0 ) ``` ### 6. 主循环更新 ```python def update(task): dt = globalClock.getDt() physics_plugin.update(dt) # 更新车辆 for vehicle in physics_plugin.vehicles: vehicle.update(dt) return task.cont taskMgr.add(update, "physics_update") ``` ## 高级功能 ### 材质系统 ```python # 使用预定义材质 concrete_material = physics_plugin.get_predefined_material('concrete') # 创建自定义材质 custom_material = physics_plugin.create_custom_material( 'my_material', { 'friction': 0.8, 'restitution': 0.2, 'density': 2000.0, 'thermal_conductivity': 2.0, 'color': Vec4(0.8, 0.6, 0.4, 1.0) } ) # 设置材质交互 custom_material.set_interaction_coefficient('metal', 1.2) # 更新材质状态 custom_material.update_state( temperature=50.0, wear=0.1, stress=100.0 ) ``` ### 调试可视化 ```python # 启用调试可视化 physics_plugin.enable_debug_visualization(True) # 设置调试选项 physics_plugin.set_debug_options( show_constraints=True, show_aabbs=True, show_velocities=True, show_forces=True ) # 性能分析 profiler = physics_plugin.profiler performance_report = profiler.get_performance_report() print(f"平均FPS: {performance_report['average_fps']}") ``` ### 性能监控 ```python # 获取性能统计 stats = physics_plugin.get_performance_stats() print(f"平均更新时间: {stats['avg_update_time']}") print(f"刚体数量: {stats['objects']['rigid_bodies']}") # 获取详细性能分析 analysis = physics_plugin.profiler.get_performance_analysis() print(f"性能等级: {analysis['performance_grade']}") print(f"瓶颈: {analysis['bottlenecks']}") print(f"建议: {analysis['recommendations']}") ``` ## 配置文件 插件支持通过JSON配置文件进行配置： ```json { "physics": { "gravity": [0, 0, -9.81], "time_step": 0.016667, "solver_iterations": 10, "solver_tolerance": 0.001 }, "materials": { "concrete": { "friction": 0.7, "restitution": 0.1, "density": 2400.0 } }, "vehicle": { "max_engine_force": 3000.0, "max_brake_force": 100.0, "max_steering": 0.7854 } } ``` ## API参考 ### RigidBodyPhysicsPlugin类 #### 构造函数 ```python RigidBodyPhysicsPlugin(world_node=None, config_file=None) ``` #### 主要方法 - `create_rigid_body(node_path, shape_type, mass, body_type, material)`: 创建刚体 - `create_constraint(constraint_type, body_a, body_b, **kwargs)`: 创建约束 - `create_vehicle(chassis_body, wheel_configurations)`: 创建车辆 - `create_particle_system(max_particles)`: 创建粒子系统 - `update(dt)`: 更新物理系统 - `ray_test(from_pos, to_pos)`: 射线检测 - `get_performance_stats()`: 获取性能统计 - `enable_debug_visualization(enabled)`: 启用调试可视化 - `set_debug_options(**kwargs)`: 设置调试选项 - `get_predefined_material(material_name)`: 获取预定义材质 - `create_custom_material(name, properties)`: 创建自定义材质 - `set_gravity(gravity)`: 设置重力 - `set_time_step(time_step, max_substeps)`: 设置时间步长 - `get_collision_groups()`: 获取碰撞组工具 - `save_config(config_file)`: 保存配置 - `load_config(config_file)`: 加载配置 - `clear_all()`: 清除所有物理对象 - `destroy()`: 销毁物理插件 ### RigidBody类 #### 主要方法 - `set_friction(friction, static_friction, dynamic_friction)`: 设置摩擦系数 - `set_restitution(restitution)`: 设置恢复系数 - `set_damping(linear_damping, angular_damping)`: 设置阻尼 - `set_factors(linear_factor, angular_factor)`: 设置线性和角因子 - `set_activation_state(active, always_active)`: 设置激活状态 - `set_sleeping_thresholds(linear_threshold, angular_threshold)`: 设置休眠阈值 - `set_ccd_parameters(motion_threshold, swept_sphere_radius)`: 设置CCD参数 - `apply_force(force, position, duration)`: 应用力 - `apply_torque(torque, duration)`: 应用扭矩 - `apply_impulse(impulse, position, duration)`: 应用冲量 - `apply_torque_impulse(torque_impulse)`: 应用扭矩冲量 - `get_linear_velocity()`: 获取线性速度 - `set_linear_velocity(velocity)`: 设置线性速度 - `get_angular_velocity()`: 获取角速度 - `set_angular_velocity(velocity)`: 设置角速度 - `get_position()`: 获取位置 - `set_position(position)`: 设置位置 - `get_rotation()`: 获取旋转 - `set_rotation(rotation)`: 设置旋转 - `sync_visual_node()`: 同步物理节点和可视化节点 - `get_mass()`: 获取质量 - `set_mass(mass)`: 设置质量 - `get_kinetic_energy()`: 计算动能 - `get_potential_energy(gravity)`: 计算势能 - `get_total_energy(gravity)`: 计算总能量 - `set_custom_data(key, value)`: 设置自定义数据 - `get_custom_data(key, default)`: 获取自定义数据 - `destroy()`: 销毁刚体 ### PhysicsMaterial类 #### 主要方法 - `set_property(property_name, value)`: 设置材质属性 - `get_property(property_name)`: 获取材质属性 - `set_friction(friction, static_friction, dynamic_friction)`: 设置摩擦系数 - `set_restitution(restitution)`: 设置恢复系数 - `set_density(density)`: 设置密度 - `set_color(color)`: 设置颜色 - `set_thermal_properties(conductivity, specific_heat, expansion)`: 设置热力学属性 - `set_electrical_properties(conductivity, dielectric, permeability)`: 设置电学属性 - `set_fluid_properties(viscosity, surface_tension, compressibility)`: 设置流体属性 - `set_visual_properties(roughness, metallic, specular, emissive)`: 设置视觉属性 - `set_environmental_properties(weather_resistance, corrosion_rate, aging_rate)`: 设置环境属性 - `set_special_properties(flammability, toxicity, radioactivity)`: 设置特殊属性 - `update_state(temperature, humidity, wear, contamination, stress, fatigue)`: 更新材质状态 - `get_effective_friction(other_material, velocity)`: 获取有效摩擦系数 - `get_effective_restitution(other_material, impact_velocity)`: 获取有效恢复系数 - `set_interaction_coefficient(other_material_name, coefficient)`: 设置交互系数 - `apply_to_rigid_body(rigid_body)`: 应用到刚体 - `to_dict()`: 转换为字典 - `from_dict(data)`: 从字典创建 - `save_to_file(filepath)`: 保存到文件 - `load_from_file(filepath)`: 从文件加载 ### ConstraintManager类 #### 支持的约束类型 - `CONSTRAINT_POINT2POINT`: 点对点约束 - `CONSTRAINT_HINGE`: 铰链约束 - `CONSTRAINT_SLIDER`: 滑动约束 - `CONSTRAINT_CONETWIST`: 锥形扭转约束 - `CONSTRAINT_6DOF`: 6自由度约束 - `CONSTRAINT_6DOF_SPRING`: 6自由度弹簧约束 - `CONSTRAINT_GEAR`: 齿轮约束 - `CONSTRAINT_FIXED`: 固定约束 #### 主要方法 - `create_point2point_constraint(body_a, body_b, pivot_a, pivot_b, ...)`: 创建点对点约束 - `create_hinge_constraint(body_a, body_b, pivot_a, pivot_b, axis_a, axis_b, ...)`: 创建铰链约束 - `create_slider_constraint(body_a, body_b, frame_a, frame_b, ...)`: 创建滑动约束 - `create_cone_twist_constraint(body_a, body_b, frame_a, frame_b, ...)`: 创建锥形扭转约束 - `create_6dof_constraint(body_a, body_b, frame_a, frame_b, ...)`: 创建6自由度约束 - `create_6dof_spring_constraint(body_a, body_b, frame_a, frame_b, ...)`: 创建6自由度弹簧约束 - `create_gear_constraint(body_a, body_b, axis_a, axis_b, ratio)`: 创建齿轮约束 - `create_fixed_constraint(body_a, body_b, frame_a, frame_b, ...)`: 创建固定约束 - `set_motor(constraint, axis, target_velocity, max_impulse)`: 设置马达 - `disable_motor(constraint)`: 禁用马达 - `set_spring(constraint, axis, stiffness, damping, equilibrium)`: 设置弹簧 - `disable_spring(constraint, axis)`: 禁用弹簧 - `set_limit(constraint, axis, lower_limit, upper_limit)`: 设置限制 - `add_constraint_to_group(constraint, group_name)`: 添加到组 - `remove_constraint_from_group(constraint, group_name)`: 从组移除 - `add_constraint_tag(constraint, tag)`: 添加标签 - `remove_constraint_tag(constraint, tag)`: 移除标签 - `get_constraints_by_tag(tag)`: 根据标签获取约束 - `get_constraints_by_group(group_name)`: 根据组获取约束 - `get_constraint_state(constraint)`: 获取约束状态 - `get_constraint_statistics()`: 获取约束统计 ### VehicleSystem类 #### 主要方法 - `add_wheel(...)`: 添加车轮 - `set_steering(steering)`: 设置转向 - `set_engine_force(force)`: 设置引擎力 - `set_brake_force(force)`: 设置刹车力 - `set_handbrake_force(force)`: 设置手刹力 - `shift_up()`: 升档 - `shift_down()`: 降档 - `set_gear(gear)`: 设置档位 - `update(dt)`: 更新车辆 - `get_current_speed_km_hour()`: 获取当前速度(km/h) - `get_wheel_info(wheel_index)`: 获取车轮信息 - `get_vehicle_state()`: 获取车辆状态 - `get_engine_torque()`: 获取发动机扭矩 - `get_engine_power()`: 获取发动机功率 - `apply_damage(component, amount)`: 应用损伤 - `repair_component(component, amount)`: 修复组件 - `refuel(amount)`: 加油 - `get_performance_stats()`: 获取性能统计 - `enable_anti_lock_brake(enabled)`: 启用ABS - `enable_traction_control(enabled)`: 启用牵引力控制 - `enable_stability_control(enabled)`: 启用车身稳定控制 - `destroy()`: 销毁车辆 ### ParticleSystem类 #### 主要方法 - `set_emitter_properties(...)`: 设置发射器属性 - `set_particle_properties(...)`: 设置粒子属性 - `set_physics_properties(...)`: 设置物理属性 - `set_collision_properties(...)`: 设置碰撞属性 - `set_environmental_effects(...)`: 设置环境影响 - `set_special_effects(...)`: 设置特殊效果 - `set_lifetime_behaviors(...)`: 设置生命周期行为 - `set_sub_emitter(...)`: 设置子发射器 - `set_performance_options(...)`: 设置性能选项 - `set_emission_rate(rate)`: 设置发射速率 - `set_emission_burst(count, interval)`: 设置爆发发射 - `emit_particle(position, velocity, lifetime, color)`: 发射粒子 - `update(dt)`: 更新粒子系统 - `get_particle_count()`: 获取粒子数量 - `get_statistics()`: 获取统计信息 - `clear_particles()`: 清除粒子 - `pause(paused)`: 暂停/恢复 - `set_time_scale(scale)`: 设置时间缩放 - `create_explosion(position, particle_count, explosion_force, ...)`: 创建爆炸 - `create_fire_effect(position, particle_count, rise_speed, ...)`: 创建火焰 - `destroy()`: 销毁粒子系统 ### PhysicsWorld类 #### 主要方法 - `set_gravity(gravity)`: 设置重力 - `set_time_step(time_step, max_substeps)`: 设置时间步长 - `set_solver_parameters(iterations, tolerance)`: 设置求解器参数 - `set_split_impulse(enable, penetration_threshold)`: 设置分离冲量 - `set_ccd_parameters(threshold, radius)`: 设置CCD参数 - `enable_multithreading(enable, thread_count)`: 启用多线程 - `setup_spatial_partitioning(partition_size)`: 设置空间分区 - `update(dt)`: 更新物理世界 - `add_rigid_body(rigid_body)`: 添加刚体 - `remove_rigid_body(rigid_body)`: 移除刚体 - `add_constraint(constraint)`: 添加约束 - `remove_constraint(constraint)`: 移除约束 - `add_vehicle(vehicle)`: 添加车辆 - `remove_vehicle(vehicle)`: 移除车辆 - `add_particle_system(particle_system)`: 添加粒子系统 - `remove_particle_system(particle_system)`: 移除粒子系统 - `ray_test(from_pos, to_pos)`: 射线检测 - `ray_test_all(from_pos, to_pos)`: 射线检测(所有结果) - `get_performance_stats()`: 获取性能统计 - `pause(paused)`: 暂停/恢复 - `set_time_scale(scale)`: 设置时间缩放 - `clear()`: 清除所有对象 - `reset()`: 重置物理世界 ### PhysicsDebug类 #### 主要方法 - `enable_debug(enabled)`: 启用/禁用调试 - `set_debug_options(...)`: 设置调试选项 - `update_debug_visualization()`: 更新调试可视化 - `add_contact_point(position, normal, impulse)`: 添加接触点 - `add_collision_event(body_a, body_b, contact_points)`: 添加碰撞事件 - `set_line_thickness(thickness)`: 设置线条粗细 - `set_axis_length(length)`: 设置坐标轴长度 - `set_velocity_scale(scale)`: 设置速度缩放 - `set_force_scale(scale)`: 设置力缩放 - `set_contact_point_size(size)`: 设置接触点大小 - `set_normal_scale(scale)`: 设置法线缩放 - `enable_debug_text(enabled)`: 启用/禁用调试文本 - `enable_stats_display(enabled)`: 启用/禁用统计显示 - `set_debug_update_frequency(frequency)`: 设置调试更新频率 - `hide_debug_visualization()`: 隐藏调试可视化 - `show_debug_visualization()`: 显示调试可视化 - `destroy()`: 销毁调试工具 ### PhysicsProfiler类 #### 主要方法 - `record_frame()`: 记录帧数据 - `get_average_update_time()`: 获取平均更新时间 - `get_max_update_time()`: 获取最大更新时间 - `get_min_update_time()`: 获取最小更新时间 - `get_average_fps()`: 获取平均FPS - `get_object_counts()`: 获取对象数量 - `get_average_object_counts()`: 获取平均对象数量 - `get_performance_report()`: 获取性能报告 - `get_performance_analysis()`: 获取性能分析 - `reset_statistics()`: 重置统计 - `export_statistics(filepath)`: 导出统计 - `destroy()`: 销毁分析器 ## 性能优化建议 1. **合理设置时间步长**: 过小的时间步长会影响性能，建议在1/60秒左右 2. **控制刚体数量**: 过多的刚体会影响性能，考虑使用休眠机制和剔除 3. **使用适当的碰撞形状**: 复杂形状比简单形状消耗更多资源，优先使用基本形状 4. **启用休眠机制**: 让静止的物体进入休眠状态以节省计算资源 5. **使用连续碰撞检测**: 对于高速运动的物体启用CCD以避免穿透 6. **合理设置求解器参数**: 迭代次数和容差影响精度和性能的平衡 7. **启用调试可视化仅在开发时**: 调试可视化会消耗额外资源 8. **及时销毁不需要的对象**: 避免内存泄漏 9. **使用对象池**: 对于频繁创建销毁的对象使用对象池 10. **空间分区**: 对于大型场景使用空间分区优化碰撞检测 ## 故障排除 ### 常见问题 1. **刚体穿透**: - 检查时间步长是否过小，增加求解器迭代次数 - 对高速物体启用连续碰撞检测(CCD) - 调整碰撞形状边界 2. **性能问题**: - 减少刚体和约束数量 - 优化碰撞形状复杂度 - 启用休眠机制 - 使用空间分区 - 调整求解器参数 3. **约束不稳定**: - 检查约束参数，适当调整限制范围 - 增加求解器迭代次数 - 调整约束的破裂阈值 4. **车辆控制不自然**: - 调整悬挂参数 - 调整轮胎摩擦系数 - 调整发动机扭矩曲线 - 启用或调整ABS、TC等辅助系统 5. **粒子效果不理想**: - 调整发射器参数 - 调整粒子生命周期参数 - 调整物理属性（重力、阻力等） - 调整环境影响参数 ### 联系支持 如有问题，请联系插件开发者或查看相关文档。