OnlineRpg/编译与运行指南.md

# OnlineRpg 编译与运行指南

## 编译环境

- **操作系统**: WSL (Debian)
- **编译器**: GCC 14.2.0
- **C++标准**: C++17
- **构建工具**: CMake 3.15+
- **数据库**: SQLite3 (amalgamation 版本)

## 项目结构

```
OnlineRpg/
├── include/          # 头文件
│   ├── core/        # 核心模块 (多态、模板、链表)
│   ├── common/      # 通用模块 (网络、数据库)
│   ├── server/      # 服务器模块
│   └── client/      # 客户端模块
├── src/             # 源文件
├── lib/             # 第三方库 (SQLite3 amalgamation)
├── data/            # 数据目录 (数据库文件)
└── build/           # 构建目录
    └── bin/         # 可执行文件
        ├── server   # 服务器程序
        └── client   # 客户端程序
```

## 核心技术实现

### 1. 多态 (Polymorphism)
- **抽象基类**: `ICharacter`, `ISkill`
- **具体实现**: `Warrior`, `Mage`
- **技能系统**: 7种技能类 (NormalAttack, PowerStrike, etc.)

### 2. 模板 (Templates)
- **模板类**: `Node<T>`, `HistoryLog<T>`
- **用途**: 通用链表结构，用于战斗历史记录

### 3. 手写链表 (Linked List)
- **实现**: 基于 `Node<T>` 的单向链表
- **应用**: `HistoryLog<T>` 存储战斗日志

### 4. STL容器
- **std::map**: 客户端管理、战斗房间管理
- **std::vector**: 消息参数传递
- **std::shared_ptr**: 智能指针管理资源
- **std::thread**: 多线程客户端处理
- **std::mutex**: 线程同步
- **std::atomic**: 原子状态标志

### 5. 网络编程 (Networking)
- **跨平台Socket封装**: `SocketWrapper`
- **协议**: 管道分隔符的文本协议
- **架构**: TCP C/S模型，每客户端一线程

### 6. 数据库 (Database)
- **SQLite3**: 嵌入式数据库
- **表结构**: Users (用户表), Characters (角色表)
- **线程安全**: std::mutex 保护数据库操作

## 编译步骤

### 1. 清理构建目录
```bash
cd /mnt/e/50425/Documents/Github/OnlineRpg
rm -rf build
```

### 2. 配置 CMake
```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release
```

### 3. 编译项目
```bash
cmake --build build --config Release -j4
```

编译输出：
- `build/bin/server` - 服务器可执行文件 (约1.7MB，包含SQLite)
- `build/bin/client` - 客户端可执行文件 (约80KB)

## 运行服务器

### 1. 创建数据目录
```bash
mkdir -p data
```

### 2. 启动服务器
```bash
./build/bin/server
```

服务器配置：
- **默认端口**: 8888
- **数据库文件**: `data/game.db`

成功启动输出：
```
==================================
  OnlineRpg Server
==================================
Port: 8888
Database: data/game.db
==================================
Server started successfully
Listening on port: 8888
Database: Connected
Server accepting connections...
```

## 运行客户端

```bash
./build/bin/client
```

客户端功能：
- **注册**: 创建新账户
- **登录**: 登录现有账户
- **创建角色**: 选择职业 (Warrior/Mage)
- **大厅聊天**: 与其他玩家交流
- **战斗邀请**: 发起PvP战斗
- **回合制战斗**: 使用技能战斗

## 网络协议

### 消息格式
```
CMD|param1|param2|...\n
```

### 主要命令
- `REGISTER|username|password` - 注册
- `LOGIN|username|password` - 登录
- `CREATE_CHAR|class|name` - 创建角色
- `CHAT|message` - 聊天
- `INVITE|targetUsername` - 邀请战斗
- `BATTLE|action|target|skillIndex` - 战斗操作

## 数据库架构

### Users 表
```sql
CREATE TABLE Users (
    UserID INTEGER PRIMARY KEY AUTOINCREMENT,
    Username TEXT NOT NULL UNIQUE,
    PasswordHash TEXT NOT NULL,
    CreatedAt DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

### Characters 表
```sql
CREATE TABLE Characters (
    CharacterID INTEGER PRIMARY KEY AUTOINCREMENT,
    UserID INTEGER NOT NULL,
    CharacterClass TEXT NOT NULL,
    CharacterName TEXT NOT NULL,
    Level INTEGER DEFAULT 1,
    Health INTEGER DEFAULT 100,
    Attack INTEGER DEFAULT 10,
    Defense INTEGER DEFAULT 5,
    Magic INTEGER DEFAULT 0,
    CreatedAt DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

## 编译问题解决

### SQLite3 链接错误
**问题**: undefined reference to sqlite3_* functions

**解决方案**:
1. 在 CMakeLists.txt 中启用 C 语言支持:
   ```cmake
   project(OnlineRpg VERSION 1.0.0 LANGUAGES C CXX)
   ```

2. 确保 SQLite amalgamation 文件被包含:
   ```cmake
   set(COMMON_SOURCES
       src/common/SocketWrapper.cpp
       src/common/Protocol.cpp
       src/common/Database.cpp
       ${SQLITE_SRC}  # 包含 lib/sqlite3.c
   )
   ```

3. 链接服务器时包含 SQLite:
   ```cmake
   target_link_libraries(server core common ${SQLITE_LIBS} ${PLATFORM_LIBS})
   ```

### 前向声明错误
**问题**: invalid use of incomplete type 'class BattleRoomManager'

**解决方案**: 在 .cpp 文件中包含完整的头文件:
```cpp
#include "server/BattleRoomManager.h"  // 而不是前向声明
```

## 测试验证

### 功能测试
- [x] 服务器启动成功
- [x] 数据库自动创建和初始化
- [x] Socket监听端口8888
- [ ] 客户端连接测试
- [ ] 注册登录功能
- [ ] 角色创建功能
- [ ] 聊天系统
- [ ] 战斗系统

### 技术验证
- [x] 多态: ICharacter/ISkill 接口
- [x] 模板: HistoryLog<T> 类
- [x] 链表: Node<T> 手写链表
- [x] STL: map, vector, shared_ptr, thread, mutex
- [x] 网络: SocketWrapper 跨平台封装
- [x] 数据库: SQLite3 集成

## 下一步

1. **功能测试**: 测试完整的游戏流程
2. **集成测试**: 多客户端同时连接
3. **性能优化**: 优化数据库查询和网络通信
4. **错误处理**: 完善异常处理和错误恢复
5. **文档完善**: 添加API文档和用户手册

## 项目完成度

- ✅ 环境配置 (100%)
- ✅ 核心技术实现 (100%)
- ✅ 编译成功 (100%)
- ✅ 服务器运行 (100%)
- ⏳ 功能测试 (0%)
- ⏳ 验收标准 (待验证)