Gobang-Game/README.md

# C语言五子棋人机对战AI

![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
![License](https://img.shields.io/badge/license-MIT-blue)
![Version](https://img.shields.io/badge/version-v8.0-blue)
![Platform](https://img.shields.io/badge/platform-Windows-lightgrey)

> 🎯 **最新版本 v8.0** - GUI图形化界面更新，实现SDL3图形化界面、现代化用户体验、可视化棋盘操作等重大功能升级

## 📋 大版本更新

### v8.0 (2025-01-18) - GUI图形化界面更新
- 🖥️ **SDL3图形化界面** - 全新的现代化图形用户界面
- 🎮 **可视化棋盘操作** - 支持鼠标点击落子和直观的棋盘显示
- 🎨 **现代化UI设计** - 美观的界面布局和用户体验优化
- 📦 **安装包制作** - 提供Inno Setup和NSIS两种安装包方案
- 🔧 **双版本支持** - 同时支持控制台版本和GUI版本
- 🎯 **窗口管理优化** - 完善的窗口显示和事件处理机制
- 📱 **响应式界面** - 自适应窗口大小和分辨率
- 🚀 **性能优化** - 图形渲染和事件处理性能提升

## 目录
- [C语言五子棋人机对战AI](#c语言五子棋人机对战ai)
  - [📋 大版本更新](#-大版本更新)
    - [v8.0 (2025-01-18) - GUI图形化界面更新](#v80-2025-01-18---gui图形化界面更新)
  - [目录](#目录)
  - [项目简介](#项目简介)
  - [功能特性](#功能特性)
    - [🎮 游戏模式](#-游戏模式)
    - [⚙️ 游戏设置](#️-游戏设置)
    - [🎯 游戏功能](#-游戏功能)
    - [💻 用户体验](#-用户体验)
    - [🔧 技术特性](#-技术特性)
  - [快速开始](#快速开始)
    - [编译项目](#编译项目)
      - [控制台版本编译](#控制台版本编译)
      - [GUI版本编译（需要SDL3）](#gui版本编译需要sdl3)
    - [运行游戏](#运行游戏)
      - [控制台版本](#控制台版本)
      - [GUI版本](#gui版本)
  - [游戏玩法](#游戏玩法)
    - [🚀 快速开始](#-快速开始)
    - [🎯 对局操作](#-对局操作)
    - [⚙️ 配置管理](#️-配置管理)
    - [📊 复盘功能](#-复盘功能)
    - [🌐 网络对战功能](#-网络对战功能)
  - [环境要求](#环境要求)
  - [常见问题](#常见问题)
    - [权限问题](#权限问题)
    - [乱码显示问题](#乱码显示问题)
  - [AI 设计实现](#ai-设计实现)
    - [核心算法](#核心算法)
    - [棋局评估函数](#棋局评估函数)
  - [项目结构](#项目结构)
    - [📁 核心模块](#-核心模块)
    - [🎮 功能模块](#-功能模块)
    - [📄 配置和文档](#-配置和文档)
    - [🔧 开发工具](#-开发工具)
  - [许可证](#许可证)
  - [欢迎贡献](#欢迎贡献)
  - [未来计划](#未来计划)
    - [✅ 已完成功能](#-已完成功能)
    - [🚀 开发路线图](#-开发路线图)
      - [📱 用户体验提升](#-用户体验提升)
      - [🌐 网络功能](#-网络功能)
      - [🧠 AI增强](#-ai增强)
      - [🔧 技术优化](#-技术优化)

## 项目简介
这是一个使用C语言实现的现代化五子棋对战系统，支持人机对战、双人对战和网络对战三种模式。系统基于 Alpha-Beta 剪枝优化的 Minimax 算法，具备完整的配置管理、复盘分析、智能评分和网络通信功能。v8.0版本新增SDL3图形化界面，提供现代化的可视化游戏体验，同时保持控制台版本的完整功能。

## 功能特性

### 🎮 游戏模式
-  **人机对战模式** - 与智能AI进行对弈
-  **双人对战模式** - 支持本地双人游戏
-  **复盘模式** - 回顾和分析历史对局
-  **GUI图形化模式** - 现代化图形界面游戏体验
-  **控制台模式** - 传统终端界面游戏模式

### ⚙️ 游戏设置
-  **自定义棋盘尺寸** - 支持5x5至25x25可调节棋盘
-  **多级AI难度** - 1-5级智能难度可选
-  **配置管理系统** - 持久化保存游戏设置
-  **禁手规则支持** - 可选启用五子棋标准禁手规则
-  **回合计时器** - 可设置每回合思考时间限制

### 🎯 游戏功能
-  **实时对局控制** - 悔棋、认输、保存等操作
-  **自动游戏记录** - 完整保存对局过程到CSV文件
-  **智能评分系统** - 对每步棋进行专业评分和分析
-  **完整复盘功能** - 逐步回放对局并显示评分
-  **MVP评选系统** - 自动评选对局最佳表现者

### 💻 用户体验
-  **双界面支持** - 同时提供图形化界面和终端界面
-  **SDL3图形化界面** - 现代化的可视化游戏体验
-  **鼠标操作支持** - 直观的点击落子操作
-  **完备输入验证** - 确保所有用户输入的有效性和安全性
-  **智能错误提示** - 详细的错误信息和操作指导
-  **响应式设计** - 自适应窗口大小和分辨率
-  **跨平台兼容** - 支持Windows系统，预留跨平台扩展

### 🔧 技术特性
-  **模块化架构** - 清晰的代码结构，便于维护和扩展
-  **SDL3图形库集成** - 现代化的跨平台图形渲染支持
-  **双版本架构** - 控制台版本和GUI版本并行开发
-  **结构体定义集中化** - 所有数据结构统一在type.h中管理
-  **配置参数统一管理** - 所有配置宏定义集中在config.h中
-  **全局变量统一管理** - 所有全局变量集中在globals模块中管理
-  **内存优化管理** - 高效的内存使用和资源管理
-  **配置文件支持** - INI格式配置文件自动加载保存
-  **UTF-8编码支持** - 完美支持中文显示
-  **事件驱动架构** - 高效的图形界面事件处理机制
-  **安装包支持** - 提供专业的软件安装和分发方案
-  **网络对战功能** - 完整的在线多人对战系统

## 快速开始

### 编译项目

#### 控制台版本编译
```bash
gcc -std=c17 -o gobang.exe *.c -lws2_32
```

或者使用优化编译：
```bash
gcc -O2 -o gobang.exe main.c gobang.c game_mode.c ai.c record.c init_board.c ui.c config.c globals.c network.c -lws2_32
```

#### GUI版本编译（需要SDL3）
```bash
gcc -std=c17 -o gobang_gui.exe *.c -ID:\settings\SDL\SDL3-3.2.22\x86_64-w64-mingw32\include -LD:\settings\SDL\SDL3-3.2.22\x86_64-w64-mingw32\lib -lSDL3 -lws2_32
copy "D:\settings\SDL\SDL3-3.2.22\x86_64-w64-mingw32\bin\SDL3.dll" .
```

或者使用批处理文件：
```bash
.\compile_gui.bat
```

**注意：** 
- Windows系统需要添加 `-lws2_32` 链接库以支持网络功能
- GUI版本需要SDL3库支持，请确保SDL3路径正确
- 编译GUI版本后需要将SDL3.dll复制到可执行文件目录

### 运行游戏

#### 控制台版本
```bash
.\gobang.exe
```

#### GUI版本
```bash
.\gobang_gui.exe
```

## 游戏玩法

### 🚀 快速开始
1. **启动游戏**：运行 `gobang.exe` 进入主菜单
2. **选择模式**：
   - `1` - **人机对战模式** - 与AI智能对手进行五子棋对战
   - `2` - **双人对战模式** - 两名玩家轮流对弈的本地对战
   - `3` - **网络对战模式** - 通过网络与远程玩家实时对战
   - `4` - **复盘模式** - 回放历史对局并查看详细分析
   - `5` - **配置管理** - 自定义游戏设置和参数调整
   - `6` - **游戏规则** - 查看五子棋游戏规则和操作说明
   - `7` - **关于信息** - 查看项目版本和开发者信息
   - `0` - **退出游戏** - 安全退出程序

### 🎯 对局操作
- **落子**：输入坐标 (格式: `行 列`，如 `8 8`)
- **悔棋**：输入 `R` 或 `r` 撤销上一步
- **认输**：输入 `S` 或 `s` 主动认输
- **保存**：输入 `SAVE` 保存当前对局
- **退出**：输入 `EXIT` 退出当前对局

### ⚙️ 配置管理
- **棋盘大小**：5x5 至 25x25 可调 (默认15x15)
- **AI难度**：1-5级智能难度 (默认3级)
- **禁手规则**：可选启用标准五子棋禁手
- **计时器**：可设置每回合时间限制
- **配置保存**：所有设置自动保存到 `gobang_config.ini`

### 📊 复盘功能
- **自动记录**：每局游戏自动保存到 `records/` 目录
- **逐步回放**：按步骤重现整局对弈过程
- **评分分析**：显示每步棋的专业评分
- **MVP评选**：自动评选本局最佳表现者
- **胜负统计**：完整的对局结果记录

### 🌐 网络对战功能
- **服务器模式**：创建游戏房间等待其他玩家加入
- **客户端模式**：连接到指定服务器进行对战
- **实时同步**：棋盘状态和游戏进度实时同步
- **连接管理**：自动处理网络连接和断线重连
- **延迟显示**：实时显示网络延迟状态
- **安全验证**：基本的数据验证和防作弊检测

## 环境要求
- 操作系统: Windows (当前版本使用了Windows特有的 `_kbhit()` 和 `Sleep()` 函数，因此暂不跨平台)
- 编译器: GCC (MinGW-w64)
- 终端: 支持UTF-8编码的终端

> **跨平台兼容性说明:**
> 
> 为了未来在Linux或macOS等其他操作系统上运行，需要将平台特定的代码（如 `_kbhit()`）替换为跨平台的实现，或使用条件编译（`#ifdef _WIN32`）进行隔离。

## 常见问题

### 权限问题
如果在保存游戏记录时提示“无法创建文件”，这通常是由于程序缺少写入权限。请尝试以下解决方案：

1.  **以管理员身份运行**：右键点击 `gobang.exe` 并在管理员权限的终端中运行程序。
2.  **更改项目目录权限**：确保项目目录不在受系统保护的目录（如 `C:\Program Files`），建议将项目放在用户目录下，例如 `D:\Code`。
3.  **手动创建 `records` 目录**：如果 `records` 目录不存在，请在 `gobang.exe` 所在目录手动创建一个。

### 乱码显示问题
如果在Windows终端中出现中文字符显示为乱码，这是由于终端代码页不匹配导致的。请在程序运行前执行以下命令：

```bash
chcp 65001
```

这会把当前终端的代码页切换为UTF-8，从而正确显示中文字符。为了方便，你可以创建一个批处理文件 `.bat` 来自动执行此操作。

**start_game.bat**
```batch
@echo off
chcp 65001
.\gobang.exe
```

## AI 设计实现

项目的AI主要基于以下技术实现：

### 核心算法

-   **Minimax算法 (Minimax)**：作为博弈树的基础模型，为双人对弈的每一步选择最优解法。
-   **Alpha-Beta 剪枝 (Alpha-Beta Pruning)**：对Minimax算法的重大优化，通过剪掉那些不影响最终决策的树枝来提高AI的计算效率，使其能够在有限时间内达到更深的搜索深度。
-   **搜索深度**：AI的思考深度，默认为3层，可以根据难度等级进行调整。深度越大，AI预测能力越强，但计算耗时也越长。

### 棋局评估函数

为了对棋局进行价值评估，AI使用了一套复杂的评分系统，其主要依据包括：

-   **棋型识别 (Pattern Recognition)**：能够识别并评估游戏中的关键棋型，如“连五”、“活四”、“冲四”、“活三”等，并为每种棋型赋予不同权重。
-   **位置权重 (Positional Value)**：棋盘上不同位置的战略价值不同，中心位置通常比边缘位置更有优势。评估函数会为棋盘上的落子点附加位置分。
-   **威胁检测 (Threat Detection)**：评估那些能够直接形成制胜局面的落子点，如“四三”或“活三”，并对这些点给予极高的评价值，以抓住制胜机会。
-   **双向连通性**：在评估一个点时，会同时判断其是否拥有足够的空间形成有效棋型，避免在被封锁的位置下出无效棋。

## 项目结构

### 📁 核心模块
- **`main.c`** - 主程序入口，负责初始化与游戏模式选择
- **`gobang.c/h`** - 核心游戏逻辑，包括棋盘操作、胜负判断
- **`game_mode.c/h`** - 游戏模式实现 (人机对战、双人对战、复盘模式)
- **`ai.c/h`** - AI算法实现 (Minimax + Alpha-Beta剪枝)
- **`gui.c/h`** - SDL3图形化界面模块 (窗口管理、事件处理、图形渲染)

### 🎮 功能模块  
- **`ui.c/h`** - 用户界面模块，负责所有显示和交互
- **`record.c/h`** - 游戏记录系统 (保存、加载、复盘、评分)
- **`init_board.c/h`** - 棋盘初始化和游戏设置
- **`config.c/h`** - 配置管理系统 (参数设置、文件读写)
- **`globals.c/h`** - 全局变量统一管理模块
- **`network.c/h`** - 网络功能模块 (为未来网络对战预留)

### 📄 配置和文档
- **`gobang_config.ini`** - 游戏配置文件 (自动生成和保存)
- **`records/`** - 对局记录目录 (CSV格式存储)
- **`type.h`** - 数据结构和类型定义集中文件
- **`compile_gui.bat`** - GUI版本编译脚本
- **`installer/`** - 安装包制作目录
  - **`setup.iss`** - Inno Setup安装脚本
  - **`installer.nsi`** - NSIS安装脚本
- **`MD/README.md`** - 项目说明文档
- **`MD/README_GUI.md`** - GUI版本使用指南
- **`MD/AI_Enhancement_Guide.md`** - AI算法增强指南
- **`MD/NETWORK_README.md`** - 网络功能使用说明
- **`MD/Architecture_Refactoring_Guide.md`** - 代码架构重构详细指南

### 🔧 开发工具
- **`.vscode/`** - VS Code 配置文件
- **`.idea/`** - IntelliJ IDEA 配置文件
- **`.vs/`** - Visual Studio 配置文件

## 许可证

本项目采用 [MIT 许可证](https://opensource.org/licenses/MIT)授权。

这意味着你可以自由地使用、复制、修改、合并、出版、分发、再授权和/或销售本软件的副本，只需在所有副本或重要部分中包含原始的版权声明和本许可声明即可。

## 欢迎贡献

我们非常欢迎任何形式的反馈和贡献！如果你发现了Bug、有功能建议，或希望改进代码，请随时通过以下方式参与：

-   **提交 Issue**：对于问题反馈或新想法，请在 [GitHub Issues](https://github.com/LHY0125/Gobang-Game/issues) 页面提交详细描述。
-   **发起 Pull Request**：如果你对源码进行了改进，欢迎提交 Pull Request。请确保你的代码风格与项目保持一致，并提供清晰的改动说明。

你的每一次贡献都将使这个项目变得更好！

## 未来计划

### ✅ 已完成功能
- [x] **SDL3图形化界面** - 完成现代化GUI界面开发，支持可视化棋盘操作
- [x] **双版本架构** - 实现控制台版本和GUI版本并行支持
- [x] **安装包制作** - 提供Inno Setup和NSIS两种专业安装包方案
- [x] **鼠标交互支持** - 实现直观的点击落子和界面操作
- [x] **窗口管理优化** - 完善的窗口显示、居中和事件处理机制
- [x] **模块化架构设计** - 完成代码重构，实现清晰的模块分离
- [x] **全局变量统一管理** - 所有全局变量集中在globals模块中管理
- [x] **宏定义优化** - 消除重复定义，统一管理所有宏定义
- [x] **配置管理系统** - 实现INI配置文件的自动加载和保存
- [x] **完整复盘功能** - 支持对局记录、回放和专业评分分析
- [x] **用户界面优化** - 实现现代化的终端UI界面
- [x] **智能评分系统** - 完成每步棋的评分和MVP评选功能
- [x] **禁手规则支持** - 添加标准五子棋禁手规则选项
- [x] **网络模块预留** - 为未来网络对战功能预留完整接口

### 🚀 开发路线图

#### 📱 用户体验提升
-   [x] **图形用户界面 (GUI)**：使用 `SDL3` 开发现代化图形界面
-   [ ] **主题系统**：支持多种UI主题和棋盘样式
-   [ ] **音效系统**：添加落子音效和背景音乐
-   [ ] **动画效果**：添加落子动画和界面过渡效果
-   [ ] **多语言支持**：支持中英文界面切换

#### 🌐 网络功能
-   [ ] **在线对战模式**：实现网络多人对战功能
-   [ ] **排行榜系统**：在线玩家等级和排名系统
-   [ ] **观战功能**：支持观看其他玩家对局

#### 🧠 AI增强
-   [ ] **开局库系统**：集成专业开局棋谱数据库
-   [ ] **神经网络AI**：基于深度学习的高级AI对手
-   [ ] **AI训练模式**：允许AI通过对局学习和改进

#### 🔧 技术优化
-   [ ] **跨平台支持**：完整支持Linux和macOS系统
-   [ ] **性能优化**：多线程搜索和内存优化
-   [ ] **数据库支持**：使用SQLite存储对局历史和统计