# swoole-game

**Repository Path**: yhwflash/swoole-game

## Basic Information

- **Project Name**: swoole-game
- **Description**: 实现了一个基于 Swoole WebSocket 的猜数字游戏服务器，具有：玩家连接、认证、游戏逻辑、聊天等功能。
- **Primary Language**: PHP
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-29
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 猜数字游戏服务器

基于 Swoole WebSocket 的多人在线猜数字游戏服务端，支持用户系统、房间机制、实时聊天、排行榜等功能。  
体验地址：https://php-game.xfcode.top

## 功能特性

### 核心游戏
- 多房间并行游戏
- 1-100 随机数字猜测
- 实时反馈猜大/猜小
- 游戏状态实时同步
- 自动开始新对局

### 用户系统
- 注册/登录/登出
- Token 认证机制
- 个人资料查看
- 游戏数据统计

### 社交功能
- 房间内实时聊天
- 游客/用户身份标识
- 聊天内容安全过滤

### 数据统计
- 个人战绩统计
- 全局排行榜
- 胜率/最佳成绩/平均猜测次数

### 调试功能
- 内置调试命令系统
- 实时查看服务器状态
- 内存/连接/房间监控
- 调试 SQL 执行
- 强制获胜等测试功能

## 快速开始

### 环境要求

- PHP 8.1+
- Swoole 5.0+
- Redis 6.0+
- MySQL 5.7+
- 必要扩展: `swoole`, `pdo_mysql`, `redis`

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd guess-number-game-server
```

2. **配置数据库**

创建 MySQL 数据库，执行以下 SQL：

```sql
CREATE DATABASE guess_number_game CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

USE guess_number_game;

-- 用户表
CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    nickname VARCHAR(50),
    avatar VARCHAR(255),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_username (username)
);

-- 用户统计表
CREATE TABLE user_stats (
    user_id INT PRIMARY KEY,
    games_played INT DEFAULT 0,
    games_won INT DEFAULT 0,
    total_guesses INT DEFAULT 0,
    best_score INT,
    total_play_time INT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- 会话表
CREATE TABLE user_sessions (
    id INT PRIMARY KEY AUTO_INCREMENT,
    user_id INT NOT NULL,
    session_token VARCHAR(64) UNIQUE NOT NULL,
    fd INT,
    expires_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    INDEX idx_token (session_token),
    INDEX idx_fd (fd)
);

-- 游戏记录表
CREATE TABLE game_records (
    id INT PRIMARY KEY AUTO_INCREMENT,
    room_id VARCHAR(50) NOT NULL,
    target_number INT NOT NULL,
    winner_id INT,
    guess_count INT NOT NULL,
    players_count INT NOT NULL,
    game_duration INT NOT NULL,
    played_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (winner_id) REFERENCES users(id) ON DELETE SET NULL,
    INDEX idx_room (room_id),
    INDEX idx_winner (winner_id)
);
```

4. **修改config.php配置文件（内有详细注释）**

5. **启动服务器**
```bash
php server.php
```

## 📖 客户端 API

### 连接参数

WebSocket 连接 URL：
```
ws://server-ip:配置文件的端口?token={token}
```
- `token`: 可选，登录后获得的认证令牌

### 消息格式

所有消息均为 JSON 格式，必须包含 `action` 字段：

```json
{
    "action": "action_name",
    ... 其他参数
}
```

### 可用动作

| 动作          | 说明     | 必要参数                                 |
| ------------- | -------- | ---------------------------------------- |
| `register`    | 注册     | `username`, `password`, `nickname`(可选) |
| `login`       | 登录     | `username`, `password`                   |
| `logout`      | 登出     | -                                        |
| `profile`     | 个人资料 | -                                        |
| `join`        | 加入房间 | `room_id`(可选，默认为`default`)         |
| `guess`       | 猜测数字 | `number`                                 |
| `status`      | 游戏状态 | -                                        |
| `stats`       | 个人统计 | -                                        |
| `leaderboard` | 排行榜   | -                                        |
| `chat`        | 聊天     | `message`, `token`(登录用户可选)         |
| `leave`       | 离开房间 | -                                        |

### 调试命令

发送以特殊前缀开头的聊天消息执行调试命令：
```
_128f46a2-e20a-45b8-b715-f557c09550d2_ <command>
```

| 命令                  | 说明             |
| --------------------- | ---------------- |
| `TOKEN <token>`       | 检查 Token 状态  |
| `STATUS`              | 服务器状态       |
| `ROOMS`               | 所有房间信息     |
| `PLAYERS`             | 所有玩家信息     |
| `MEMORY`              | 内存使用信息     |
| `ONLINE`              | 在线用户列表     |
| `SQL <query>`         | 执行 SQL 查询    |
| `USER <user_id>`      | 用户详细信息     |
| `FORCE_WIN <room_id>` | 强制当前玩家获胜 |
| `FULL`                | 完整系统信息     |
| `HELP`                | 显示帮助         |

## 项目架构

### 目录结构

```
GuessNumberGame/
├── Core/
│   ├── GameCore.php           # 游戏核心逻辑
│   ├── Functions/
│   │   ├── ChatManager.php    # 聊天管理
│   │   ├── ConfigManager.php  # 配置管理
│   │   ├── DatabaseManager.php # 数据库管理
│   │   ├── DebugManager.php   # 调试管理
│   │   ├── StatsManager.php   # 统计管理
│   │   └── UserManager.php    # 用户管理
│   └── Traits/
│       ├── BroadcastTrait.php # 广播功能
│       ├── PlayerTrait.php    # 玩家功能
│       └── RoomTrait.php      # 房间功能
├── Enums/
│   ├── DebugCommand.php       # 调试命令枚举
│   ├── GameAction.php         # 游戏动作枚举
│   └── MessageType.php        # 消息类型枚举
├── Utils/
│   └── Logger.php             # 日志工具
└── server.php                 # 服务器入口
```

### 核心流程

1. **连接建立** - 客户端建立 WebSocket 连接，可选携带 Token 自动登录
2. **身份认证** - 验证 Token，绑定用户与连接
3. **加入房间** - 玩家加入指定房间，自动创建或等待游戏开始
4. **游戏进行** - 玩家猜测数字，获得实时反馈，其他玩家可见
5. **游戏结束** - 有人猜中数字，广播胜利信息，更新统计数据
6. **自动重置** - 3秒后开始新游戏

## 配置说明

### 日志级别

- `DEBUG`: 全部日志，包含调试信息
- `INFO`: 普通信息及更高级别
- `WARNING`: 警告及错误
- `ERROR`: 仅错误日志

### 性能优化建议

1. **生产环境**将日志级别设为 `INFO` 或 `WARNING`
2. **关闭调试 SQL**功能
3. **调整 Swoole 参数**根据实际连接数
4. **使用 Redis 持久化**配置
5. **定期清理**过期会话和旧游戏记录

## 数据结构

### 房间数据结构

```php
[
    'players' => [
        $fd => [
            'fd' => int,
            'user_id' => ?int,
            'user_info' => ?array,
            'guess_count' => int,
            'joined_at' => int
        ]
    ],
    'target_number' => int,  // 1-100
    'game_started' => bool,
    'winner' => ?int,
    'game_history' => array,
    'created_at' => int
]
```

### 玩家统计数据

```php
[
    'user_id' => ?int,
    'games_played' => int,
    'games_won' => int,
    'total_guesses' => int,
    'best_score' => ?int,
    'average_guesses' => float,
    'current_game_start' => ?int
]
```

## 错误处理

服务器会返回以下格式的错误消息：

```json
{
    "type": "error",
    "message": "错误描述"
}
```

常见错误：
- `Invalid message format` - 消息格式错误
- `Unknown action: xxx` - 未知的动作类型
- `请先加入房间` - 未加入房间执行游戏操作
- `请输入 1-100 之间的有效数字` - 猜测数字超出范围
- `用户名或密码错误` - 登录失败
- `用户名已存在` - 注册失败

## 开发计划

- [ ] 添加 WebSocket 心跳检测
- [ ] 实现断线重连机制
- [ ] 增加机器人玩家
- [ ] 支持自定义房间设置
- [ ] 添加游戏观战模式
- [ ] 实现排行榜缓存
- [ ] 增加 Web 管理后台
- [ ] 支持分布式部署

## 贡献指南

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 许可证

[Apache License](LICENSE)

## 联系方式

项目维护者 - [小枫_QWQ]

---

**注意**: 本服务端需要配合客户端使用，客户端可通过 WebSocket 连接进行交互。