# gobang

**Repository Path**: davidfdw/gobang

## Basic Information

- **Project Name**: gobang
- **Description**: 微信小程序开发五子棋小游戏
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-08-19
- **Last Updated**: 2025-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 五子棋微信小程序

一个基于微信小程序开发的五子棋游戏，支持本地对战、在线对战和AI对战功能。项目采用模块化设计，具有完整的测试覆盖和错误处理机制。

## 本项目已有内测版本,感兴趣的微信扫下面二维码

![image](img1.png)


## 📋 目录

- [功能特性](#功能特性)
- [技术架构](#技术架构)
- [项目结构](#项目结构)
- [核心模块详解](#核心模块详解)
- [AI系统](#ai系统)
- [在线对战系统](#在线对战系统)
- [安装和部署](#安装和部署)
- [使用说明](#使用说明)
- [开发指南](#开发指南)
- [测试系统](#测试系统)
- [故障排除](#故障排除)
- [性能优化](#性能优化)
- [贡献指南](#贡献指南)

## 🎮 功能特性

### 核心游戏功能
- 🎯 **本地对战**: 支持双人本地对战，完整的游戏逻辑
- 🌐 **在线对战**: 基于微信云开发的实时对战功能
- 🤖 **AI对战**: 集成智能AI对战，支持三种难度等级
- 👥 **好友邀请**: 支持通过微信分享邀请好友加入游戏
- 🔄 **悔棋功能**: 每个玩家有3次悔棋机会
- 🎨 **现代UI**: 美观的游戏界面和流畅的动画效果

### 高级功能
- 📱 **响应式设计**: 适配不同屏幕尺寸和设备
- 🎵 **背景音乐**: 支持游戏背景音乐播放
- 🏆 **胜负判定**: 完整的获胜和平局判定机制
- 🔧 **错误处理**: 完善的错误处理和用户提示
- 📊 **性能监控**: 内置性能监控和调试工具

### 技术特性
- 🚀 **模块化架构**: 清晰的代码结构和模块分离
- 🧪 **测试覆盖**: 完整的测试套件和自动化测试
- 🔒 **安全机制**: 用户认证和数据验证
- 📈 **性能优化**: 内存管理和渲染优化

## 🏗️ 技术架构

### 前端技术栈
- **微信小程序**: 原生小程序开发框架
- **Canvas 2D**: 游戏渲染引擎，支持高性能图形绘制
- **ES6+**: 现代JavaScript语法和模块化开发
- **模块化设计**: 清晰的代码结构和依赖管理

### 后端服务
- **微信云开发**: 云数据库、云函数、云存储
- **实时通信**: 基于云数据库的轮询机制
- **用户认证**: OpenID获取和验证系统
- **简化架构**: 单一云函数处理所有房间操作

### 开发工具
- **微信开发者工具**: 官方开发环境
- **ESLint**: 代码质量检查
- **Git**: 版本控制系统

## 📁 项目结构

```
gobang/
├── 📄 配置文件
│   ├── app.js                 # 小程序入口文件
│   ├── app.json              # 小程序配置文件
│   ├── project.config.json   # 项目配置文件
│   ├── cloud-config.js       # 云开发配置
│   └── sitemap.json         # 站点地图配置
│
├── 🎮 游戏页面
│   ├── game.js              # 游戏页面逻辑
│   ├── game.json            # 游戏页面配置
│   └── game.wxml            # 游戏页面模板
│
├── ☁️ 云函数
│   ├── getOpenId/           # 获取用户OpenID
│   │   ├── index.js
│   │   └── package.json
│   └── roomManager/         # 房间管理云函数
│       ├── index.js         # 主要业务逻辑
│       └── package.json
│
├── 🎯 核心代码 (js/)
│   ├── main.js              # 主游戏逻辑
│   ├── databus.js           # 数据总线
│   ├── render.js            # 渲染引擎
│   │
│   ├── 🧠 AI模块
│   │   └── ai/
│   │       └── gameAI.js    # AI对战逻辑
│   │
│   ├── 🌐 网络模块
│   │   └── network/
│   │       ├── cloudManager.js      # 云开发管理
│   │       ├── networkManager.js    # 网络管理
│   │       └── simpleCloudManager.js # 简化云管理器
│   │
│   ├── 🎨 运行时组件
│   │   └── runtime/
│   │       ├── aiMenu.js           # AI菜单
│   │       ├── background.js       # 背景组件
│   │       ├── board.js           # 棋盘组件
│   │       ├── confirmDialog.js   # 确认对话框
│   │       ├── gameControlPanel.js # 游戏控制面板
│   │       ├── gameinfo.js        # 游戏信息显示
│   │       ├── mainMenu.js        # 主菜单
│   │       ├── music.js          # 音乐控制
│   │       └── onlineMenu.js     # 在线菜单
│   │
│   ├── 🛠️ 工具类
│   │   └── utils/
│   │       ├── deviceDetector.js   # 设备检测
│   │       ├── errorHandler.js     # 错误处理
│   │       ├── performanceMonitor.js # 性能监控
│   │       └── storage.js         # 存储工具
│   │
│   ├── 🧪 测试文件
│   │   └── test/
│   │       ├── aiTest.js          # AI测试
│   │       ├── drawConditionTest.js # 平局测试
│   │       ├── onlineRoomFixTest.js   # 在线房间测试
│   │       ├── roomJoinTest.js    # 房间加入测试
│   │       ├── runTests.js        # 测试运行器
│   │       └── ...               # 其他测试文件
│   │
│   ├── 📚 基础库
│   │   ├── base/
│   │   │   ├── animation.js       # 动画系统
│   │   │   ├── pool.js           # 对象池
│   │   │   └── sprite.js         # 精灵基类
│   │   └── libs/
│   │       └── tinyemitter.js    # 事件发射器
│   │
│   └── 🎮 游戏子包
│       ├── game-sub.js           # 游戏子包逻辑
│       └── game-sub-context.js   # 子包上下文
│
├── 🖼️ 资源文件
│   ├── images/
│   │   ├── bg.jpg               # 背景图片
│   │   └── share.jpg            # 分享图片
│   └── img.png                  # 项目图标
│
└── 📖 文档
    └── README.md               # 项目文档
```

## 🔧 核心模块详解

### 1. DataBus - 数据总线
**文件**: `js/databus.js`

数据总线是整个游戏的核心，负责管理所有游戏状态：

#### 主要功能
- **游戏状态管理**: 棋盘状态、当前玩家、游戏进度
- **胜负判定**: 检查获胜条件和平局条件
- **悔棋系统**: 管理悔棋次数和历史记录
- **模式切换**: 本地对战、在线对战、AI对战模式切换

#### 核心方法
```javascript
// 检查获胜条件
checkWin(row, col, player)

// 检查平局条件
checkDraw()

// 悔棋功能
undoLastMove()

// 切换玩家
switchPlayer()
```

### 2. Render - 渲染引擎
**文件**: `js/render.js`

负责游戏画面的渲染和Canvas管理：

#### 主要功能
- **Canvas管理**: 安全地获取和管理Canvas上下文
- **屏幕适配**: 适配不同屏幕尺寸
- **渲染优化**: 高性能的图形渲染

### 3. Main - 主游戏逻辑
**文件**: `js/main.js`

游戏的主要控制逻辑：

#### 主要功能
- **游戏循环**: 主游戏循环和状态更新
- **事件处理**: 触摸事件和用户交互
- **模式管理**: 不同游戏模式的切换
- **错误处理**: 全局错误处理和恢复

### 4. SimpleCloudManager - 云开发管理
**文件**: `js/network/simpleCloudManager.js`

简化的云开发管理器，处理在线对战：

#### 主要功能
- **房间管理**: 创建、加入、离开房间
- **实时同步**: 游戏状态的实时同步
- **错误处理**: 网络错误和重试机制
- **轮询机制**: 替代WebSocket的稳定轮询

### 4. SimpleCloudManager - 云开发管理
**文件**: `js/network/simpleCloudManager.js`

简化的云开发管理器，处理在线对战：

#### 主要功能
- **房间管理**: 创建、加入、离开房间
- **实时同步**: 游戏状态的实时同步
- **错误处理**: 网络错误和重试机制
- **轮询机制**: 替代WebSocket的稳定轮询

## 🤖 AI系统

### AI技术实现

#### 核心算法
- **极小化极大搜索 (Minimax Search)**: 模拟双方最优策略的博弈树搜索
- **Alpha-Beta剪枝 (Alpha-Beta Pruning)**: 在极小化极大搜索基础上剪除不必要分支
- **启发式评估函数 (Heuristic Evaluation)**: 识别连五、活四、冲四、活三、眠三等棋型

#### 评估函数评分
| 棋型 | 分数 | 说明 |
|------|------|------|
| 连五 | 100000 | 必胜棋型 |
| 活四 | 10000 | 必胜棋型 |
| 冲四 | 1000 | 威胁棋型 |
| 活三 | 1000 | 威胁棋型 |
| 眠三 | 100 | 潜在威胁 |
| 活二 | 100 | 基础棋型 |
| 眠二 | 10 | 基础棋型 |

### 难度设置

#### 简单模式 (Easy)
- **搜索深度**: 2层
- **特点**: 反应快速，适合初学者
- **技术**: 基础极小化极大搜索

#### 中等模式 (Medium)
- **搜索深度**: 3层
- **特点**: 具备一定棋力
- **技术**: Alpha-Beta剪枝 + 启发式评估

#### 困难模式 (Hard)
- **搜索深度**: 4层
- **特点**: 接近职业水平
- **技术**: 所有基础技术 + 候选走法剪枝

### AI性能特点

#### 优势
- **响应速度快**: 简化算法，思考时间短
- **内存占用低**: 无复杂缓存系统
- **代码简洁**: 易于理解和维护
- **稳定性高**: 减少复杂逻辑，降低出错概率

#### 技术实现
```javascript
// 极小化极大搜索
minimax(board, depth, alpha, beta, isMaximizing, role)

// 启发式评估
evaluate(board, role)

// 候选走法生成
getValuableMoves(board, role)
```

## 🌐 在线对战系统

### 简化架构设计

#### 核心改进
- **单一云函数**: 使用 `roomManager` 云函数处理所有房间操作
- **轮询机制**: 替代复杂的实时监听，使用简单的轮询获取房间状态
- **简化流程**: 减少中间步骤，直接调用云函数进行房间操作

#### 云函数功能
| 功能 | 描述 | 参数 |
|------|------|------|
| `create_room` | 创建房间 | roomId, playerName, openid |
| `join_room` | 加入房间 | roomId, playerName, openid |
| `make_move` | 下棋操作 | roomId, row, col, player, openid |
| `get_room_info` | 获取房间信息 | roomId |
| `leave_room` | 离开房间 | roomId, playerName, openid |

#### 优势
- **稳定性高**: 减少复杂的监听和重连逻辑
- **维护简单**: 单一云函数，易于调试和修改
- **性能优化**: 轮询机制比实时监听更稳定
- **错误处理**: 简化的错误处理流程

### 技术实现

#### 房间创建流程
```javascript
// 生成房间ID
const roomId = Math.random().toString(36).substr(2, 6).toUpperCase()

// 调用云函数创建房间
const result = await callCloudFunction('create_room', {
  roomId: roomId,
  playerName: '玩家1'
})
```

#### 房间加入流程
```javascript
// 用户输入房间号
const roomId = userInput

// 调用云函数加入房间
const result = await callCloudFunction('join_room', {
  roomId: roomId,
  playerName: '玩家2'
})
```

#### 状态轮询
```javascript
// 每秒轮询房间状态
setInterval(() => {
  pollRoomStatus()
}, 1000)
```

## 🚀 安装和部署

### 1. 环境准备

#### 必需工具
- **微信开发者工具**: 最新版本
- **微信小程序账号**: 已注册的小程序账号
- **云开发权限**: 已开通微信云开发

#### 系统要求
- **操作系统**: Windows 10+, macOS 10.14+, Linux
- **内存**: 4GB RAM (推荐8GB)
- **存储**: 1GB 可用空间

### 2. 项目配置

#### 克隆项目
```bash
# 克隆项目到本地
git clone [项目地址]
cd gobang
```

#### 导入项目
1. 打开微信开发者工具
2. 选择"导入项目"
3. 选择项目目录
4. 输入AppID (如果有)

### 3. 云开发配置

#### 开通云开发
1. 在微信开发者工具中点击"云开发"
2. 开通云开发服务
3. 创建云环境
4. 记录环境ID

#### 配置云环境
1. 修改 `cloud-config.js` 文件：
```javascript
export const CLOUD_CONFIG = {
  envId: 'your-env-id' // 替换为你的云环境ID
}
```

#### 创建数据库集合
1. 进入云开发控制台
2. 创建数据库集合 `rooms`
3. 设置集合权限为"所有用户可读，仅创建者可写"

### 4. 云函数部署

#### 部署getOpenId云函数
```bash
# 进入云函数目录
cd cloudfunctions/getOpenId

# 安装依赖
npm install

# 在微信开发者工具中右键云函数，选择"上传并部署"
```

#### 部署roomManager云函数
```bash
# 进入云函数目录
cd cloudfunctions/roomManager

# 安装依赖
npm install

# 在微信开发者工具中右键云函数，选择"上传并部署"
```

### 5. 权限配置

#### 小程序权限
在 `app.json` 中确保已配置必要的权限：
```json
{
  "permission": {
    "scope.userInfo": {
      "desc": "用于获取用户信息进行游戏对战"
    }
  }
}
```

#### 云开发权限
确保云函数有足够的权限访问数据库和云存储。

## 📖 使用说明

### 本地对战
1. 启动游戏
2. 选择"本地对战"
3. 开始游戏
4. 黑白双方轮流下棋
5. 先连成5子的一方获胜

### 在线对战
1. 选择"在线对战"
2. 创建房间或加入房间
3. 等待对手加入
4. 开始游戏
5. 实时同步游戏状态

### AI对战
1. 选择"人机对战"
2. 选择AI难度（简单/中等/困难）
3. 开始游戏
4. 与AI进行对战

### 好友邀请
1. 在在线对战页面点击"分享"
2. 选择分享方式（微信好友、朋友圈等）
3. 好友通过分享链接加入

### 游戏规则
- **获胜条件**: 任意一方在横向、纵向或斜向连成5子即获胜
- **平局条件**: 当棋盘所有位置都被占满且无人获胜时，游戏平局
- **悔棋功能**: 每个玩家有3次悔棋机会
- **AI模式**: 在AI模式下，只有玩家可以悔棋，AI不能悔棋

## 👨‍💻 开发指南

### 项目结构说明

#### 核心模块
- **DataBus**: 数据总线，管理游戏状态
- **Render**: 渲染引擎，负责游戏画面绘制
- **Main**: 主游戏逻辑，控制游戏流程
- **SimpleCloudManager**: 云开发管理，处理在线对战

#### 运行时组件
- **Board**: 棋盘组件，处理棋盘绘制和交互
- **GameControlPanel**: 游戏控制面板
- **MainMenu**: 主菜单界面
- **OnlineMenu**: 在线对战菜单
- **AIMenu**: AI对战菜单

#### 工具类
- **DeviceDetector**: 设备检测和适配
- **ErrorHandler**: 错误处理和日志记录
- **PerformanceMonitor**: 性能监控
- **Storage**: 本地存储管理

### 开发环境设置

#### 开发工具配置
1. **ESLint配置**: 确保代码质量
2. **Git配置**: 版本控制设置
3. **调试工具**: 微信开发者工具调试功能

#### 开发流程
1. **功能开发**: 在对应模块中开发新功能
2. **测试验证**: 使用测试套件验证功能
3. **代码审查**: 确保代码质量和规范
4. **部署测试**: 在测试环境验证功能

### 代码规范

#### JavaScript规范
- 使用ES6+语法
- 遵循模块化设计
- 添加必要的注释
- 使用有意义的变量名

#### 文件命名规范
- 使用小驼峰命名法
- 文件名使用英文
- 目录名使用小写字母

#### 注释规范
```javascript
/**
 * 函数说明
 * @param {string} param1 - 参数1说明
 * @param {number} param2 - 参数2说明
 * @returns {boolean} 返回值说明
 */
function exampleFunction(param1, param2) {
  // 实现代码
}
```

## 🧪 测试系统

### 测试架构

#### 测试文件结构
```
js/test/
├── aiTest.js              # AI功能测试
├── drawConditionTest.js   # 平局条件测试
├── onlineRoomFixTest.js   # 在线房间测试
├── roomJoinTest.js        # 房间加入测试
├── runTests.js           # 测试运行器
└── ...                   # 其他测试文件
```

#### 测试类型
- **单元测试**: 测试单个函数或模块
- **集成测试**: 测试模块间的交互
- **功能测试**: 测试完整功能流程
- **性能测试**: 测试系统性能指标

### 运行测试

#### 快速测试
```javascript
// 在微信开发者工具控制台中运行
window.testCurrentFix.quickDiagnosis()
```

#### 完整测试
```javascript
// 运行所有测试
window.testCurrentFix.runFullTest()
```

#### 单独测试
```javascript
// 测试OpenID获取
window.testCurrentFix.testOpenId()

// 测试房间创建
window.testCurrentFix.testRoomCreation('test_openid')
```

### 测试覆盖

#### 已测试功能
- ✅ AI基础功能测试
- ✅ 平局条件测试
- ✅ 在线房间测试
- ✅ 房间加入测试
- ✅ 悔棋功能测试
- ✅ 错误处理测试

#### 测试工具
- **控制台测试**: 在微信开发者工具控制台运行
- **自动化测试**: 使用测试脚本自动验证
- **性能监控**: 实时监控系统性能

## 🔧 故障排除

### 常见问题

#### 1. 云函数部署问题
**错误**: `Error: Cannot find module 'wx-server-sdk'`

**解决方案**:
1. 确保在云函数目录下运行 `npm install`
2. 检查 `package.json` 是否包含 `wx-server-sdk` 依赖
3. 重新部署云函数

#### 2. 房间更新验证失败
**错误**: `房间更新验证失败：player2未正确设置`

**解决方案**:
- 已实现轮询验证机制，最多尝试10次验证
- 如果问题持续，请检查网络连接和云数据库权限

#### 3. 游戏无法自动开始
**错误**: 双方连接后游戏未自动开始

**解决方案**:
- 已实现更频繁的状态检查（每1秒）
- 添加了强制更新机制
- 确保云环境正常初始化

### 当前修复状态

#### ✅ 已修复的问题
1. **云函数调用失败**: 临时跳过云函数，使用备选方案获取OpenID
2. **数据库更新验证**: 实现轮询验证机制，最多10次尝试
3. **游戏开始检测**: 改进创建者检测机制，更频繁的状态检查
4. **WebSocket连接问题**: 添加自动降级到轮询模式

#### 🔧 最新改进
1. **轮询验证机制**: 在 `joinRoom` 中实现更可靠的数据库更新验证
2. **创建者检测优化**: 改进 `checkRoomStatus` 方法，更主动地检测游戏开始条件
3. **错误处理增强**: 更好的错误日志和重试机制

### 调试技巧

#### 查看关键日志
在控制台中查找以下关键信息：
- `✅ 房间更新验证成功` - 表示数据库更新成功
- `创建者检测到player2已设置` - 表示创建者检测到加入者
- `游戏开始条件满足` - 表示游戏可以开始

#### 使用测试脚本
在微信开发者工具控制台中运行：
```javascript
// 快速诊断
window.testCurrentFix.quickDiagnosis()

// 完整测试
window.testCurrentFix.runFullTest()
```

#### 手动检查数据库
1. 打开微信开发者工具
2. 进入"云开发" -> "数据库"
3. 查看 `rooms` 集合中的房间数据
4. 确认 `player2` 字段是否正确设置

## ⚡ 性能优化

### 渲染优化

#### Canvas优化
- **批量绘制**: 减少Canvas API调用次数
- **脏矩形更新**: 只更新变化的区域
- **离屏Canvas**: 使用离屏Canvas进行预渲染

#### 内存管理
- **对象池**: 重用游戏对象，减少GC压力
- **及时清理**: 及时释放不需要的资源
- **内存监控**: 实时监控内存使用情况

### 网络优化

#### 轮询优化
- **智能轮询**: 根据游戏状态调整轮询频率
- **错误重试**: 实现指数退避重试机制
- **连接池**: 复用网络连接

#### 数据压缩
- **增量更新**: 只传输变化的数据
- **数据压缩**: 压缩传输数据大小
- **缓存机制**: 缓存常用数据

### AI性能优化

#### 搜索优化
- **Alpha-Beta剪枝**: 减少搜索分支
- **启发式排序**: 优先搜索最有希望的走法
- **时间控制**: 限制AI思考时间

#### 缓存优化
- **局面缓存**: 缓存已计算的局面
- **评估缓存**: 缓存评估函数结果
- **内存管理**: 及时清理缓存数据

## 🤝 贡献指南

### 贡献流程

#### 1. Fork项目
1. 在GitHub上Fork项目
2. 克隆你的Fork到本地
3. 创建功能分支

#### 2. 开发功能
1. 在功能分支上开发新功能
2. 遵循代码规范
3. 添加必要的测试
4. 更新文档

#### 3. 提交更改
1. 提交你的更改
2. 编写清晰的提交信息
3. 推送到你的Fork

#### 4. 发起Pull Request
1. 在GitHub上发起Pull Request
2. 描述你的更改
3. 等待代码审查

### 代码规范

#### 提交信息规范
```
类型(范围): 简短描述

详细描述（可选）

- 功能点1
- 功能点2
```

#### 类型说明
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具的变动

### 问题报告

#### Bug报告
请包含以下信息：
1. **环境信息**: 操作系统、微信版本、小程序版本
2. **复现步骤**: 详细的复现步骤
3. **期望行为**: 期望的正确行为
4. **实际行为**: 实际发生的错误行为
5. **错误日志**: 相关的错误日志

#### 功能请求
请包含以下信息：
1. **功能描述**: 详细的功能描述
2. **使用场景**: 功能的使用场景
3. **实现建议**: 可选的实现建议
4. **优先级**: 功能的优先级

## 📄 许可证

本项目采用 MIT License 许可证。

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- **GitHub Issues**: 提交Issue

## 🙏 致谢

- 感谢前端大牛-言川的AI算法教程提供的有力帮助
- 详细算法教程可查：https://gitee.com/mirrors_lihongxun945/gobang
![image](img.png)

---

**注意**: 本项目需要微信小程序开发环境和云开发权限。请确保在正确的环境中运行和测试。

**版本信息**: v1.4.4 
**最后更新**: 2025年8月7日
**维护者**: LvesDi005