# 触觉反馈系统插件

## 简介

触觉反馈系统插件为EG引擎提供全面的触觉反馈支持，包括设备管理、效果处理、物理集成、音频同步等功能。该插件支持多种触觉设备，如游戏手柄、VR控制器、触觉手套、震动背心等，并提供丰富的API供开发者集成到自己的应用中。

## 功能特性

### 1. 设备管理
- 自动发现和管理多种触觉设备
- 支持USB、蓝牙、无线等多种连接方式
- 实时监控设备状态和电池电量
- 支持热插拔设备检测

### 2. 效果系统
- 预定义多种触觉效果（脉冲、震动、爆炸等）
- 支持自定义效果创建和编辑
- 效果混合和层叠播放
- 实时效果参数调整

### 3. 物理引擎集成
- 碰撞反馈：根据碰撞冲量生成触觉效果
- 力反馈：实时力反馈模拟
- 摩擦反馈：基于表面材质的纹理反馈
- 材质系统：不同材质对应不同触觉反馈

### 4. 音频同步
- 音频特征分析和触觉映射
- 节拍检测和同步反馈
- 频谱分析和多频段反馈
- 音量驱动的动态触觉效果

### 5. 事件系统
- 游戏事件到触觉效果的映射
- 事件优先级和抑制机制
- 事件组合和复合反馈
- 可自定义的事件映射规则

### 6. 配置管理
- 全局配置和用户偏好设置
- 多种预设配置文件
- 实时配置更新和保存
- 配置验证和错误处理

### 7. 编辑器支持
- 可视化设备管理界面
- 效果编辑和实时预览
- 配置文件管理
- 实时监控和调试工具

## 目录结构

```
haptic_feedback_system/
├── plugin.py                 # 插件主文件
├── core/
│   └── haptic_manager.py     # 触觉管理器
├── effects/
│   └── effect_processor.py   # 效果处理器
├── devices/
│   └── device_manager.py     # 设备管理器
├── physics/
│   └── physics_integration.py# 物理引擎集成
├── audio/
│   └── audio_haptics.py      # 音频触觉反馈
├── events/
│   └── event_handler.py      # 事件处理器
├── config/
│   └── config_manager.py     # 配置管理器
├── editor/
│   └── haptic_editor.py      # 触觉编辑器
└── utils/
    └── haptic_utils.py       # 工具类
```

## 核心模块

### 触觉管理器 (HapticManager)
负责管理触觉效果的播放和设备控制，提供效果播放、停止、暂停、恢复等功能。

### 效果处理器 (EffectProcessor)
处理各种触觉效果，包括预定义效果和自定义效果，支持效果混合和参数调整。

### 设备管理器 (HapticDeviceManager)
管理各种触觉设备，包括设备发现、连接、状态监控和控制。

### 物理引擎集成 (PhysicsIntegration)
将物理引擎中的碰撞、力和摩擦转换为触觉反馈。

### 音频触觉反馈 (AudioHaptics)
将音频特征转换为触觉效果，支持节拍检测和频谱分析。

### 事件处理器 (HapticEventHandler)
处理游戏事件并触发相应的触觉反馈。

### 配置管理器 (HapticConfigManager)
管理插件配置和用户偏好设置。

### 触觉编辑器 (HapticEditor)
提供可视化界面用于配置和测试触觉反馈效果。

### 工具类 (HapticUtils)
提供实用工具函数，包括性能监控、日志记录、数据转换等。

## 使用示例

```python
# 初始化插件
plugin = HapticFeedbackSystemPlugin(engine)
plugin.initialize()
plugin.enable()

# 播放简单触觉效果
plugin.haptic_manager.play_effect(
    effect_type='click',
    intensity=0.8,
    duration=0.1,
    frequency=50.0
)

# 处理碰撞事件
collision_data = {
    'impulse': 5.0,
    'contact_point': (0, 0, 0),
    'object_a': 'player',
    'object_b': 'wall',
    'material_a': 'flesh',
    'material_b': 'stone'
}
plugin.physics_integration.process_collision(collision_data)

# 处理游戏事件
plugin.event_handler.handle_event('player_take_damage', {'intensity': 0.9})

# 应用配置预设
plugin.config_manager.apply_profile('gaming')
```

## API参考

详细的API文档请参考各模块的源代码注释。

## 配置说明

插件配置文件位于 `config/haptic_config.json`，支持以下配置项：

- 全局设置：启用状态、强度缩放、频率缩放等
- 设备设置：默认强度、最大并发效果数等
- 效果设置：预处理、后处理、最大持续时间等
- 物理设置：碰撞反馈、力反馈、摩擦反馈等
- 音频设置：音频触觉反馈、节拍检测等
- 事件设置：事件处理、事件抑制等

## 支持的设备

- Xbox/PlayStation 游戏手柄
- Oculus Touch/Valve Index VR控制器
- 触觉反馈手套
- 震动背心和座椅
- 力反馈方向盘

## 性能优化

- 使用对象池减少内存分配
- 多线程处理避免阻塞主线程
- 智能设备检测减少CPU占用
- 效果缓存和复用机制

## 扩展开发

插件采用模块化设计，易于扩展新功能：

1. 添加新的效果类型
2. 支持新的设备类型
3. 扩展物理反馈类型
4. 添加新的音频映射算法

## 许可证

本插件遵循EG引擎许可证协议。

## 支持与反馈

如有问题或建议，请联系开发团队或提交GitHub issue。