# 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.3-blue)
![Platform](https://img.shields.io/badge/platform-Windows-lightgrey)

> 🎯 **最新版本 v8.3** - 引入IUP图形库，优化项目结构，支持Makefile编译

## 📋 大版本更新

### v8.3 (2026-03-16) - 图形界面库迁移与架构优化

- 🔧 **IUP图形库** - 迁移至轻量级IUP库，无需复杂配置即可运行
- 📂 **目录重构** - 采用标准的 `bin/` (可执行文件) 和 `obj/` (中间文件) 目录结构
- ⚡ **Makefile支持** - 提供完整的Makefile，支持一键编译、清理和运行
- 🌐 **本地化资源** - 集成第三方库到 `libs/` 目录，开箱即用

## 目录

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

## 项目简介

这是一个使用C语言实现的现代化五子棋对战系统，支持人机对战、双人对战和网络对战三种模式。系统基于 Alpha-Beta 剪枝优化的 Minimax 算法，具备完整的配置管理、复盘分析、智能评分和网络通信功能。v8.3版本引入IUP图形化界面，提供简洁高效的可视化游戏体验。

## 功能特性

### 🎮 游戏模式

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

### ⚙️ 游戏设置

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

### 🎯 游戏功能

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

### 💻 用户体验

- **双界面支持** - 同时提供图形化界面和终端界面
- **IUP图形化界面** - 原生控件风格，轻量高效
- **鼠标操作支持** - 直观的点击落子操作
- **完备输入验证** - 确保所有用户输入的有效性和安全性
- **智能错误提示** - 详细的错误信息和操作指导
- **跨平台兼容** - 支持Windows系统，代码结构预留跨平台扩展

### 🔧 技术特性

- **模块化架构** - 清晰的代码结构，便于维护和扩展
- **IUP图形库集成** - 简单易用的跨平台图形库
- **Makefile构建系统** - 标准化的编译流程
- **目录结构规范** - 代码(src)、对象(obj)、执行文件(bin)分离
- **结构体定义集中化** - 所有数据结构统一在type.h中管理
- **配置参数统一管理** - 所有配置宏定义集中在config.h中
- **全局变量统一管理** - 所有全局变量集中在globals模块中管理
- **内存优化管理** - 高效的内存使用和资源管理
- **配置文件支持** - INI格式配置文件自动加载保存
- **UTF-8编码支持** - 完美支持中文显示
- **事件驱动架构** - 高效的图形界面事件处理机制
- **网络对战功能** - 完整的在线多人对战系统

## 快速开始

### 编译项目

#### 使用Makefile（推荐）

在项目根目录下打开终端（PowerShell 或 CMD），运行以下命令：

**编译所有版本：**

```bash
mingw32-make all
```

**仅编译控制台版本：**

```bash
mingw32-make console
```

**仅编译GUI版本：**

```bash
mingw32-make gui
```

**清理构建文件：**

```bash
mingw32-make clean
```

**注意：**

- 需要安装 MinGW-w64 并将 `bin` 目录添加到 PATH 环境变量。
- 编译生成的可执行文件位于 `bin/` 目录下。

### 运行游戏

#### 控制台版本

```bash
.\bin\gobang_console.exe
```

#### GUI版本

```bash
.\bin\gobang_gui.exe
```

或者使用Makefile指令直接运行：

```bash
mingw32-make run-gui
```

## 游戏玩法

### 🚀 快速开始

1. **启动游戏**：运行 `gobang_console.exe` 进入主菜单
2. **选择模式**：
   - `1` - **人机对战模式** - 与AI智能对手进行五子棋对战
   - `2` - **双人对战模式** - 两名玩家轮流对弈的本地对战
   - `3` - **网络对战模式** - 通过网络与远程玩家实时对战
   - `4` - **复盘模式** - 回放历史对局并查看详细分析
   - `5` - **配置管理** - 自定义游戏设置和参数调整
   - `6` - **游戏规则** - 查看五子棋游戏规则和操作说明
   - `7` - **关于游戏** - 查看项目版本和开发者信息
   - `8` - **图形化界面** - 启动GUI模式
   - `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)
- 构建工具: GNU Make (mingw32-make)
- 终端: 支持UTF-8编码的终端

## 常见问题

### 权限问题

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

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

### 乱码显示问题

如果在Windows终端中出现中文字符显示为乱码，请确保终端代码页为UTF-8 (65001)。程序会自动尝试设置，但如果失败，请手动执行：

```bash
chcp 65001
```

## AI 设计实现

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

### 核心算法

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

### 棋局评估函数

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

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

## 项目结构

### 📁 核心模块

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

### 🎮 功能模块  

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

### 📄 配置和文档

- **`Makefile`** - 项目构建脚本
- **`gobang_config.ini`** - 游戏配置文件
- **`records/`** - 对局记录目录
- **`include/`** - 头文件目录
- **`libs/`** - 第三方库目录 (包含IUP)
- **`bin/`** - 编译输出目录 (可执行文件)
- **`obj/`** - 中间文件目录
- **`installer/`** - 安装包制作目录
- **`MD/`** - 项目详细文档

### 🔧 开发工具

- **`.vscode/`** - VS Code 配置文件
- **`.idea/`** - IntelliJ IDEA 配置文件

## 许可证

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

## 欢迎贡献

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

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

## 未来计划

### ✅ 已完成功能

- [x] **IUP图形化界面** - 集成轻量级IUP库，实现跨平台图形界面
- [x] **构建系统优化** - 引入Makefile，规范化编译流程
- [x] **目录结构重构** - 分离源码、对象文件和可执行文件
- [x] **双版本架构** - 实现控制台版本和GUI版本并行支持
- [x] **安装包制作** - 提供Inno Setup和NSIS两种专业安装包方案
- [x] **模块化架构设计** - 完成代码重构，实现清晰的模块分离
- [x] **完整复盘功能** - 支持对局记录、回放和专业评分分析

### 🚀 开发路线图

#### 📱 用户体验提升

- [ ] **主题系统**：支持多种UI主题和棋盘样式
- [ ] **音效系统**：添加落子音效和背景音乐
- [ ] **多语言支持**：支持中英文界面切换

#### 🌐 网络功能

- [ ] **在线对战模式**：实现网络多人对战功能
- [ ] **排行榜系统**：在线玩家等级和排名系统

#### 🧠 AI增强

- [ ] **开局库系统**：集成专业开局棋谱数据库
- [ ] **神经网络AI**：基于深度学习的高级AI对手