EG/plugins/user/network_sync/README.md

# 网络同步插件

## 概述

网络同步插件为EG引擎提供了完整的网络同步功能，支持客户端-服务器架构、实时对象同步、时钟同步、预测与插值等高级功能。该插件采用模块化设计，具有高性能、可扩展和易配置的特点。

## 功能特性

### 1. 核心功能
- **网络通信**: 完整的TCP/IP网络通信实现
- **对象同步**: 实时游戏对象状态同步
- **协议处理**: 自定义网络协议支持
- **连接管理**: 客户端和服务器连接管理
- **数据序列化**: 高效的数据序列化和反序列化
- **时钟同步**: 精确的客户端-服务器时钟同步
- **预测管理**: 网络延迟下的对象状态预测
- **配置管理**: 灵活的配置系统
- **事件处理**: 完整的事件系统
- **加密支持**: 数据加密和安全传输
- **可视化编辑器**: 图形化配置和监控界面

### 2. 高级功能
- **插值与外推**: 平滑的对象运动效果
- **增量压缩**: 减少网络带宽使用
- **心跳检测**: 连接状态监控
- **断线重连**: 自动连接恢复
- **数据缓存**: 提高处理效率
- **性能监控**: 实时性能数据展示
- **错误处理**: 完善的异常处理机制

## 模块架构

```
network_sync/
├── plugin.py                 # 插件主入口
├── core/
│   └── sync_manager.py      # 同步管理器
├── network/
│   └── network_manager.py   # 网络管理器
├── protocol/
│   └── protocol_handler.py  # 协议处理器
├── sync/
│   └── object_sync.py       # 对象同步器
├── connection/
│   └── connection_manager.py # 连接管理器
├── serialization/
│   └── data_serializer.py   # 数据序列化器
├── clock/
│   └── clock_sync.py        # 时钟同步器
├── prediction/
│   └── prediction_manager.py # 预测管理器
├── config/
│   └── sync_config.py       # 配置管理器
├── editor/
│   └── sync_editor.py       # 可视化编辑器
├── events/
│   └── event_handler.py     # 事件处理器
├── encryption/
│   └── encryption_manager.py # 加密管理器
├── utils/
│   └── network_utils.py     # 网络工具类
└── README.md               # 说明文档
```

## 安装与配置

### 安装依赖

```bash
pip install cryptography psutil
```

### 基本配置

在插件配置文件中设置基本参数：

```python
# 网络配置
network_config = {
    "server_host": "localhost",
    "server_port": 7777,
    "max_connections": 32,
    "connection_timeout": 30.0
}

# 同步配置
sync_config = {
    "sync_rate": 20,  # 每秒20次同步
    "interpolation_rate": 60,
    "enable_delta_compression": True
}
```

## 使用方法

### 1. 初始化插件

```python
from plugins.user.network_sync.plugin import NetworkSyncPlugin

# 创建插件实例
plugin = NetworkSyncPlugin(engine)

# 初始化插件
if plugin.initialize():
    print("插件初始化成功")
    
# 启用插件
if plugin.enable():
    print("插件已启用")
```

### 2. 启动服务器

```python
# 启动服务器
if plugin.start_server(port=7777):
    print("服务器启动成功")
```

### 3. 连接服务器

```python
# 连接服务器
if plugin.connect_to_server("localhost", 7777):
    print("连接服务器成功")
```

### 4. 同步对象

```python
# 注册本地对象
object_data = {
    "position": [0.0, 0.0, 0.0],
    "rotation": [0.0, 0.0, 0.0],
    "scale": [1.0, 1.0, 1.0]
}

plugin.sync_manager.register_local_object("player_1", object_data)

# 同步对象状态
plugin.sync_object("player_1", object_data)
```

## API参考

### 主要类和方法

#### NetworkSyncPlugin
- `initialize()`: 初始化插件
- `enable()`: 启用插件
- `disable()`: 禁用插件
- `start_server(port)`: 启动服务器
- `connect_to_server(host, port)`: 连接服务器
- `sync_object(obj_id, obj_data)`: 同步对象

#### SyncManager
- `register_local_object(obj_id, obj_data)`: 注册本地对象
- `register_remote_object(obj_id, obj_data)`: 注册远程对象
- `update_object_data(obj_id, obj_data)`: 更新对象数据
- `get_object_data(obj_id)`: 获取对象数据

#### NetworkManager
- `send_sync_data(data, target_client_id)`: 发送同步数据
- `get_connection_state()`: 获取连接状态
- `get_network_stats()`: 获取网络统计

#### ObjectSync
- `sync_object(obj_id, obj_data)`: 同步对象
- `receive_sync_data(obj_id, obj_data)`: 接收同步数据
- `get_local_objects()`: 获取本地对象
- `get_remote_objects()`: 获取远程对象

## 性能优化

### 1. 带宽优化
- 启用增量压缩减少数据传输
- 使用数据缓存避免重复传输
- 实现智能同步频率调节

### 2. CPU优化
- 多线程处理网络通信
- 对象池减少内存分配
- 智能更新检测避免无用计算

### 3. 内存优化
- 及时清理过期数据
- 使用高效的数据结构
- 实现LRU缓存策略

## 安全特性

### 1. 数据加密
- 支持AES加密算法
- 会话密钥管理
- 密钥轮换机制

### 2. 身份验证
- 用户名/密码验证
- 令牌认证
- 连接授权

### 3. 数据完整性
- 消息认证码(MAC)
- 数据校验和
- 防篡改检测

## 故障排除

### 常见问题

1. **连接失败**
   - 检查服务器地址和端口
   - 确认防火墙设置
   - 查看网络连接状态

2. **同步延迟**
   - 检查网络带宽
   - 调整同步频率
   - 优化数据传输

3. **性能问题**
   - 监控CPU和内存使用
   - 减少同步对象数量
   - 调整插值参数

### 日志查看

```python
# 获取插件统计信息
stats = plugin.get_stats()
print(f"发送字节: {stats['bytes_sent']}")
print(f"接收字节: {stats['bytes_received']}")
```

## 扩展开发

### 添加新功能模块

1. 创建新的模块文件
2. 实现标准接口方法
3. 在主插件中注册模块
4. 添加配置选项

### 自定义协议

1. 扩展ProtocolHandler类
2. 添加新的消息类型
3. 实现消息处理器
4. 更新协议版本

## 许可证

本插件采用MIT许可证，详情请查看LICENSE文件。

## 联系方式

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