EG/plugins/user/matchmaking_system/README.md

# 匹配系统插件

为EG引擎提供完整的玩家匹配功能，包括队列管理、算法匹配、房间分配、规则配置、实时监控和数据分析等核心功能。

## 功能特性

### 1. 匹配管理
- 智能匹配过程管理
- 多种匹配模式支持
- 匹配状态跟踪和控制
- 匹配结果处理和回调

### 2. 队列系统
- 玩家排队管理
- 队列优先级处理
- 超时自动清理
- 实时队列状态监控

### 3. 匹配算法
- 技能匹配算法
- 快速匹配算法
- 团队平衡算法
- 自定义算法支持
- 匹配质量评估

### 4. 房间分配
- 动态房间创建和销毁
- 玩家房间分配管理
- 房间状态跟踪
- 房间密码保护

### 5. 规则配置
- 灵活的匹配规则系统
- 游戏模式特定规则
- 自定义规则集支持
- 实时规则验证

### 6. 实时监控
- 性能指标收集
- 实时数据监控
- 警报系统
- 系统健康状态检查

### 7. 事件系统
- 事件驱动架构
- 异步事件处理
- 事件过滤和优先级
- 事件监听器系统

### 8. 配置管理
- 持久化配置存储
- 动态配置更新
- 配置变更监听
- 配置导入导出

### 9. 可视化编辑器
- 实时数据展示
- 配置参数调整
- 统计图表显示
- 数据导出功能

### 10. 数据统计
- 实时数据收集
- 历史数据分析
- 统计报告生成
- 数据导出支持

## 系统架构

```
匹配系统插件
├── 核心模块
│   └── 匹配管理器 (core/match_manager.py)
├── 队列系统
│   └── 队列管理器 (queue/queue_manager.py)
├── 算法系统
│   └── 算法管理器 (algorithms/algorithm_manager.py)
├── 房间系统
│   └── 房间分配器 (rooms/room_allocator.py)
├── 规则系统
│   └── 规则管理器 (rules/rule_manager.py)
├── 监控系统
│   └── 匹配监控器 (monitoring/match_monitor.py)
├── 事件系统
│   └── 事件处理器 (events/event_handler.py)
├── 配置系统
│   └── 配置管理器 (config/match_config.py)
├── 编辑器系统
│   └── 匹配编辑器 (editor/match_editor.py)
├── 统计系统
│   └── 统计管理器 (stats/stats_manager.py)
└── 插件主文件
    └── 插件入口 (plugin.py)
```

## 安装和使用

### 安装依赖

```bash
# 无特殊依赖，使用标准Python库
```

### 配置插件

插件配置文件位于 `config/matchmaking_config.json`，包含以下主要配置项：

```json
{
  "system": {
    "enable_matchmaking": true,
    "max_concurrent_matches": 1000,
    "default_match_timeout": 300.0
  },
  "queue": {
    "default_queue_timeout": 300.0,
    "queue_processing_interval": 2.0
  },
  "matching": {
    "default_algorithm": "skill_based",
    "skill_range": 100
  },
  "room": {
    "default_max_players": 8,
    "enable_room_passwords": true
  }
}
```

### 启动插件

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

# 插件会自动处理匹配过程
```

## API参考

### 匹配管理

```python
# 开始匹配
match_id = plugin.match_manager.start_matchmaking(player_ids, match_params)

# 取消匹配
plugin.match_manager.cancel_matchmaking(match_id)

# 获取匹配统计
stats = plugin.match_manager.get_match_stats()
```

### 队列管理

```python
# 添加玩家到队列
plugin.queue_manager.add_players_to_queue(player_ids, queue_params)

# 从队列移除玩家
plugin.queue_manager.remove_players_from_queue(player_ids=player_ids)

# 获取队列信息
queue_info = plugin.queue_manager.get_queue_info(queue_name)
```

### 算法管理

```python
# 设置活动算法
plugin.algorithm_manager.set_active_algorithm("skill_based")

# 运行匹配算法
result = plugin.algorithm_manager.run_matching_algorithm(players)

# 更新玩家技能
plugin.algorithm_manager.update_player_skill(player_id, skill_level)
```

### 房间分配

```python
# 创建房间
room_id = plugin.room_allocator.create_room(room_name, room_settings)

# 添加玩家到房间
plugin.room_allocator.add_client_to_room(room_id, player_id)

# 从房间移除玩家
plugin.room_allocator.remove_client_from_room(room_id, player_id)
```

### 规则管理

```python
# 应用规则
is_valid = plugin.rule_manager.apply_rules(players, game_mode)

# 添加自定义规则集
plugin.rule_manager.add_custom_rule_set("custom_rules", rules)

# 设置活动规则集
plugin.rule_manager.set_active_rules("custom_rules")
```

### 监控系统

```python
# 获取性能指标
metrics = plugin.monitor.get_performance_metrics()

# 获取活动警报
alerts = plugin.monitor.get_active_alerts()

# 记录匹配队列时间
plugin.monitor.record_match_queue_time(queue_time)
```

### 事件系统

```python
# 发出事件
plugin.event_handler.emit_event("match_found", payload)

# 注册事件处理器
plugin.event_handler.register_event_handler("match_found", handler_func)

# 注册事件过滤器
plugin.event_handler.register_event_filter("match_found", filter_func)
```

### 配置管理

```python
# 获取配置
config_value = plugin.config_manager.get_config("section", "key", default_value)

# 设置配置
plugin.config_manager.set_config("section", "key", value)

# 保存配置
plugin.config_manager.save_config()

# 加载配置
plugin.config_manager.load_config()
```

### 编辑器系统

```python
# 显示编辑器
plugin.editor.show_editor()

# 隐藏编辑器
plugin.editor.hide_editor()

# 切换标签页
plugin.editor.switch_tab("overview")

# 更新配置
plugin.editor.update_config("section", "key", value)
```

### 统计系统

```python
# 获取实时统计数据
realtime_stats = plugin.stats_manager.get_realtime_stats()

# 生成报告
report = plugin.stats_manager.generate_report("summary", "24h")

# 导出统计数据
plugin.stats_manager.export_stats("stats.json")

# 重置统计数据
plugin.stats_manager.reset_stats()
```

## 匹配流程

### 1. 玩家加入队列
```
玩家 -> 队列管理器 -> 添加到匹配队列
```

### 2. 队列处理
```
队列管理器 -> 算法管理器 -> 运行匹配算法
```

### 3. 匹配创建
```
算法管理器 -> 房间分配器 -> 创建匹配房间
```

### 4. 玩家分配
```
房间分配器 -> 玩家 -> 加入匹配房间
```

### 5. 匹配完成
```
匹配管理器 -> 事件系统 -> 发出匹配完成事件
```

## 性能优化

1. **异步处理**：采用多线程和异步I/O提高并发性能
2. **智能队列**：高效的队列管理和玩家匹配算法
3. **内存优化**：及时清理无用数据和对象
4. **缓存机制**：对频繁访问的数据进行缓存
5. **批量处理**：批量处理队列和匹配操作

## 扩展开发

### 添加新的匹配算法

```python
# 在算法管理器中实现新的匹配算法
def _run_custom_matching(self, players):
    # 实现自定义匹配逻辑
    pass

# 注册算法
plugin.algorithm_manager.register_algorithm("custom", _run_custom_matching)
```

### 添加新的事件类型

```python
# 注册事件处理器
plugin.event_handler.register_event_handler("custom_event", custom_handler)

# 发出事件
plugin.event_handler.emit_event("custom_event", payload)
```

### 添加自定义规则

```python
# 添加自定义规则集
plugin.rule_manager.add_custom_rule_set("my_rules", {
    "min_players": 2,
    "max_players": 8,
    "custom_rule": True
})

# 应用规则
plugin.rule_manager.apply_rules(players, "my_rules")
```

## 故障排除

### 常见问题

1. **匹配失败**：检查匹配规则和算法配置
2. **队列超时**：调整队列超时时间和匹配参数
3. **性能问题**：检查系统资源使用情况，优化配置
4. **配置错误**：验证配置文件格式和参数

### 日志分析

查看日志文件以诊断问题：
```
logs/matchmaking_system.log
```

## 版本信息

- 版本：1.0.0
- 作者：EG Plugin System
- 许可证：MIT

## 贡献指南

欢迎提交Issue和Pull Request来改进这个插件。

## 支持

如需技术支持，请联系插件维护团队或查看相关文档。