gobang.h

2026-05-10 02:19:46 +08:00 · 2025-06-23 20:37:24 +08:00
parent 19c4ddbf3e
commit 46048b25ce
1 changed files with 173 additions and 0 deletions
@@ -0,0 +1,173 @@
+/**
+ * @file gobang.h
+ * @author 刘航宇(3364451258@qq.com、15236416560@163.com、lhy3364451258@outlook.com)
+ * @brief 五子棋游戏头文件
+ * @version 1.0
+ * @date 2025-06-20
+ *
+ * @copyright Copyright (c) 2025
+ *
+ * @note 本文件为gobang.c的接口文件，提供游戏所需的所有函数声明
+ * @note 设计要点：
+ * 1. 支持5x5到25x25的可变棋盘尺寸
+ * 2. 使用极小极大算法实现AI决策
+ * 3. 提供完整的游戏过程复盘功能
+ * 4. 所有坐标采用0-base索引
+ * 5. 使用全局变量简化状态管理
+ */
+
+#ifndef GO_BANG_H
+#define GO_BANG_H
+
+#include <stdio.h>
+#include <math.h>
+#include <stdlib.h>
+#include <stdbool.h>
+#include <string.h>
+
+// 宏定义
+/**
+ * @brief 最大支持棋盘尺寸
+ * @note 25x25是性能与实用性的平衡点，更大的棋盘会显著降低AI响应速度
+ */
+#define MAX_BOARD_SIZE 25 // 最大支持棋盘尺寸(5x5到25x25)
+
+/**
+ * @brief 玩家标识符
+ * @note 使用1/2而非字符标识，便于扩展为多玩家游戏
+ */
+#define PLAYER 1 // 玩家棋子标识符
+#define AI 2     // AI棋子标识符
+
+/**
+ * @brief 空位置标识符
+ * @note 必须与PLAYER/AI的值不同
+ */
+#define EMPTY 0 // 空位置标识符
+
+/**
+ * @brief 最大步数限制
+ * @note 等于棋盘总格数，确保不会数组越界
+ */
+#define MAX_STEPS (MAX_BOARD_SIZE * MAX_BOARD_SIZE) // 最大步数（棋盘总格数）
+
+// 全局变量声明
+extern int BOARD_SIZE;                            // 实际使用的棋盘尺寸(默认15)
+extern int board[MAX_BOARD_SIZE][MAX_BOARD_SIZE]; // 棋盘状态存储数组
+extern int step_count;                            // 当前步数计数器
+
+/**
+ * @brief 落子步骤记录结构体
+ * @note 用于存储游戏历史记录和AI决策树
+ * @note 字段说明:
+ * - player: 标识落子方(PLAYER/AI)
+ * - x/y: 0-based坐标位置
+ */
+typedef struct
+{
+    int player; // 落子方标识
+    int x, y;   // 坐标位置
+} Step;
+
+extern Step steps[MAX_STEPS]; // 存储所有落子步骤的数组
+
+/**
+ * @brief 连子检测信息结构体
+ * @note 用于五子连珠判断和棋局评估
+ * @note 字段说明:
+ * - continuous_chess: 连续同色棋子数量
+ * - check_start: 序列起点方向是否有空位(可发展性)
+ * - check_end: 序列终点方向是否有空位(可发展性)
+ */
+typedef struct
+{
+    int continuous_chess; // 连续棋子数量
+    bool check_start;     // 序列起点方向是否开放（空位）
+    bool check_end;       // 序列终点方向是否开放（空位）
+} DirInfo;
+
+// 函数声明
+/**
+ * @brief 初始化棋盘为全空状态
+ */
+void empty_board();
+
+/**
+ * @brief 打印当前棋盘状态
+ */
+void print_board();
+
+/**
+ * @brief 检查指定位置是否为空且有效
+ * @param x 行坐标(0-base)
+ * @param y 列坐标(0-base)
+ * @return true 位置有效且为空
+ * @return false 位置无效或已被占用
+ */
+bool have_space(int x, int y);
+
+/**
+ * @brief 玩家落子操作
+ * @param x 行坐标(0-base)
+ * @param y 列坐标(0-base)
+ * @return true 落子成功
+ * @return false 落子失败(位置无效)
+ */
+bool player_move(int x, int y);
+
+/**
+ * @brief 计算特定方向上连续同色棋子数量
+ * @param x 起始行坐标
+ * @param y 起始列坐标
+ * @param dx 行方向增量(-1,0,1)
+ * @param dy 列方向增量(-1,0,1)
+ * @param player 玩家标识(PLAYER/AI)
+ * @return DirInfo 包含连续棋子数和方向开放状态的结构体
+ */
+DirInfo count_specific_direction(int x, int y, int dx, int dy, int player);
+
+/**
+ * @brief 检查特定位置落子后是否形成五连珠
+ * @param x 行坐标(0-base)
+ * @param y 列坐标(0-base)
+ * @param player 玩家标识(PLAYER/AI)
+ * @return true 形成五连珠
+ * @return false 未形成五连珠
+ */
+bool check_win(int x, int y, int player);
+
+/**
+ * @brief 评估特定位置对当前玩家的价值
+ * @param x 行坐标(0-base)
+ * @param y 列坐标(0-base)
+ * @param player 玩家标识(PLAYER/AI)
+ * @return int 位置评估分数(越高越好)
+ */
+int evaluate_pos(int x, int y, int player);
+
+/**
+ * @brief 带α-β剪枝的深度优先搜索(极小极大算法)
+ * @param x 当前行坐标
+ * @param y 当前列坐标
+ * @param player 当前玩家
+ * @param depth 搜索深度
+ * @param alpha α值(当前最大值)
+ * @param beta β值(当前最小值)
+ * @param is_maximizing 是否为极大化玩家
+ * @return int 最佳评估分数
+ */
+int dfs(int x, int y, int player, int depth, int alpha, int beta, bool is_maximizing);
+
+/**
+ * @brief AI落子决策函数
+ * 使用评估函数和搜索算法选择最佳落子位置
+ */
+void ai_move(int depth);
+
+/**
+ * @brief 复盘游戏过程
+ * 逐步重现游戏中的所有落子步骤
+ */
+void review_process();
+
+#endif // GO_BANG_H