简介：基于GNUGo库实现的Unity围棋游戏完整工程包，包含离线AI对战与在线对战两种模式，面向需要完成毕业设计、课程设计、工程实训或学科竞赛的高校学生与开发者。工程经过严格测试，答辩评审平均分达96分，可实现复现复刻，适合在此基础上扩展新功能或借鉴设计报告。包内共625个文件，主要包含Unity场景与预制体、C#业务脚本、GNUGo引擎的C/C++源码及头文件，搭配Shader材质、棋子贴图、音频与DLL动态库等资源，压缩包约83.92MB，整体目录结构清晰，便于定位代码与资源。当前已有39人学习下载。该项目将经典围棋博弈与Unity游戏开发相结合，既可直接启动运行体验AI对弈，也可在源码基础上研究GNUGo命令行对弈、GTP协议通信及在线联机逻辑，对理解AI算法和网络同步均有参考价值。
1. 用GNUGo做Unity围棋游戏：离线AI和在线对战两条线，一次把题做完
毕设或者课设里，“基于GNUGo的Unity围棋游戏，包括离线AI对战和在线对战”是出现频率极高的组合。很多人拿到题目就先去画棋盘、摆棋子，等把UI磨得差不多了，才发现AI和网络两个大头还没动，工期已经烧掉一半。这篇文章想做的事很直接：把GNUGo这颗开源围棋引擎当成一个外部进程接进Unity，让离线AI的棋力全部由引擎负责，自己只写通信和状态管理；在线对战则用一份最小的权威服务器模型，让两台设备的棋盘始终对得上。适合手里正捏着这个题目、或者想在Unity里快速接入一个能跑完整对弈的围棋引擎的开发者，照着做，至少不会再输在起跑线。
2. 先让Unity和GNUGo对话：GTP协议、坐标映射与最小封装
2.1 认识GTP协议：一次一问、按行回话的黑匣子
GNUGo本质上是一个命令行围棋引擎，它不提供Unity可以直接调用的动态链接库，而是通过标准的Game Text Protocol（GTP）协议和人对话。GTP的交互方式非常简单：Unity往引擎的标准输入写一行命令，引擎思考完，往标准输出回一行结果。比如你要让AI走黑棋，发一条genmove black，引擎可能回= E17，也可能回= pass或者= resign。
这种“外部进程+文本协议”的方案对Unity集成非常友好：AI的计算全部发生在另一个进程里，GNUGo即使思考好几秒，Unity主线程也不会被计算占满。反过来，你得接受它是一只黑匣子——你只能通过文本输入输出判断它活没活着，一旦路径、编码、管道缓冲出问题，进程起来后可能什么回应都没有，排查起来特别像在修一台没有指示灯的机器。
GTP协议里，每条命令的回复以=开头表示成功，以?开头表示命令出错。对围棋对弈来说，核心命令也就这么几条：
| 命令 | 作用 | 典型回复 |
|---|---|---|
boardsize 19 | 设置棋盘路数 | = |
clear_board | 清空棋盘 | = |
komi 7.5 | 设置贴目 | = |
play black D4 | 直接落一子 | =或? illegal move |
genmove white | 让AI替白方思考一手 | = Q16或= pass |
showboard | 打印当前棋盘ASCII图 | 多行棋盘文本 |
quit | 退出引擎 | 无 |
理解这张表，后面的封装就有了底。需要注意的是，GTP的回复理论上以空行结尾，但GNUGo对play、genmove这类命令通常只回一行，所以实际开发里读取第一行就够。你要是较真去等空行，很容易把读取逻辑卡在缓冲区边界上，这是新手最常见的第一个坑。
2.2 GTP坐标与Unity棋盘数组的映射规则
围棋棋盘19×19，GTP坐标由列字母和行数字组成，比如K10。列字母从A到T，中间跳过I，因为大写的I和数字1太像；数字从1开始，从上往下增长。Unity侧最常用的棋盘存储是int[19,19]二维数组，0表示空，1表示黑，2表示白。所以整个项目第一步要解决的，就是GTP坐标和数组下标的双向换算。
// GTP坐标 -> Unity棋盘数组索引，非法返回(-1,-1) public static Vector2Int GtpToBoard(string gtp) { string s = gtp.Trim().ToUpperInvariant(); if (s.Length < 2 || s == "PASS" || s == "RESIGN") return new Vector2Int(-1, -1); char file = s[0]; // 第一个字符是列字母 int col = file - 'A' + 1; // A=1, B=2, 依次类推 if (file > 'I') col--; // 跳过I列，否则列号会整体右偏 int row = int.Parse(s.Substring(1)); // 第二个段是行号，1在最上方 if (col < 1 || col > 19 || row < 1 || row > 19) return new Vector2Int(-1, -1); return new Vector2Int(col - 1, row - 1); }这里最关键的只有col--这一行。字母K在ASCII码里的位置是75，减去字母A的65再加1，直接算出来是11，可实际K是第10列，因为I被跳过了，所以要向左修正一位。忘了这个修正，棋子会统一往右偏一格，最后一列直接出界。
方向问题也一样容易翻车。GTP行号从上往下增长，Unity的数组索引如果从下往上排，就要做19 - row的反转。为了避免两套规则混在一起，我习惯让数组索引0对应棋盘最上方，和GTP方向保持一致。反向转换就简单了：
// Unity棋盘数组索引 -> GTP坐标 public static string BoardToGtp(int x, int y) { int col = x + 1; char file = (char)('A' + col - 1); if (file >= 'I') file++; // 反向补回被跳过的I return $"{file}{y + 1}"; }如果要做悔棋或者在线对弈复盘功能，双向映射都要写对。光靠手工在纸上推一遍不够，我通常人肉测三个锚点：棋盘左上角A1、右下角T19、正中间的K10，三个点都能对上，映射基本就没问题。
2.3 最小C#进程封装：启动一局19路棋
要在Unity里启动GNUGo，绕不开System.Diagnostics.Process。封装思路就三步：设好进程参数、重定向标准输入输出、启动后做一次握手确认。下面这个类是我每次做原型都会先写一遍的版本，去掉了业务逻辑，只保留和官方GNUGo进程对话的能力。
using System.Diagnostics; using System.IO; using UnityEngine; public class GnuGoProcess { private Process _proc; private StreamWriter _stdin; private StreamReader _stdout; private StreamReader _stderr; public bool Start(string gnugoPath, int boardSize = 19) { string dir = Path.GetDirectoryName(gnugoPath); _proc = new Process(); _proc.StartInfo.FileName = gnugoPath; _proc.StartInfo.Arguments = $"--mode=gtp --boardsize={boardSize}"; _proc.StartInfo.WorkingDirectory = string.IsNullOrEmpty(dir) ? "." : dir; _proc.StartInfo.UseShellExecute = false; _proc.StartInfo.CreateNoWindow = true; _proc.StartInfo.RedirectStandardInput = true; _proc.StartInfo.RedirectStandardOutput = true; _proc.StartInfo.RedirectStandardError = true; _proc.Start(); _stdin = _proc.StandardInput; _stdout = _proc.StandardOutput; _stderr = _proc.StandardError; return IsReady(); } private bool IsReady() { try { _stdin.WriteLine("name"); string line = _stdout.ReadLine(); return line != null && line.StartsWith("="); } catch { return false; } } }UseShellExecute = false是这里的大前提：只有关掉Shell执行，三个重定向才能真正接管进程的输入输出，否则你写进去的命令进程根本收不到。WorkingDirectory必须显式设置为可执行文件所在的目录，GNUGo启动时需要读自己的配置文件，工作目录不对它会直接闪退。CreateNoWindow = true是让GNUGo不在Unity运行时代弹出一个控制台窗口，这在开发机上尤其重要。
IsReady() 里发一条最轻量的name命令做握手，引擎能回一行= GNU Go ...，说明进程启动和管道通信都正常。如果在这里失败，后面所有逻辑都没必要继续。
最后补一个退出方法，防止编辑器重跑时残留一堆孤儿进程：
public void Quit() { if (_proc == null) return; try { _stdin.WriteLine("quit"); _proc.WaitForExit(2000); } catch { } if (!_proc.HasExited) _proc.Kill(); }GNUGo在收到quit后一般会自己退出，但为了保险，两秒没退就直接Kill。Unity里跑AI进程最忌只杀进程不杀子进程，一旦残留，下一次启动又会因为端口或临时文件冲突出问题。
3. 离线AI对战落地：从命令序列到解析AI落子
3.1 完整对局动作：开局、落子、让AI动手
进程能跑通之后，要按GTP协议组织一场完整的对局。顺序必须固定：先设置棋盘大小，再清空棋盘，再设置贴目，之后才是你和AI交替落子。顺序错了，很多引擎版本会回复? boardsize not set之类的错误。
// 开启19路新对局，黑棋玩家先行，默认中国规则贴7.5目 public void NewGame(int size = 19, float komi = 7.5f) { _stdin.WriteLine($"boardsize {size}"); _stdout.ReadLine(); // 读取 "= " _stdin.WriteLine("clear_board"); _stdout.ReadLine(); _stdin.WriteLine($"komi {komi:0.0}"); _stdout.ReadLine(); }每条命令后面必须读掉一行响应，哪怕这行内容只有=两个字符。因为GTP是行协议，你不读走，下一行的play或genmove答案就会和上一条命令的响应混在一起，解析出来的落子永远是乱的。这个动作叫“消费响应”，新手最容易漏。
玩家落子时，用play告诉引擎棋盘上发生了什么：
// 把玩家点击的Unity坐标转成GTP坐标并发给引擎 public bool PlayMove(char color, int x, int y) { string gtp = BoardToGtp(x, y); _stdin.WriteLine($"play {color} {gtp}"); string resp = _stdout.ReadLine(); return !resp.StartsWith("?"); // "? illegal move" 表示非法落子 }这里返回值的含义要区分清楚：play成功只代表这手棋符合围棋落子规则，不代表对局策略上合理。如果要做成“禁着点提示”，直接看这个返回值就够；如果你还想让引擎替你判断贴目胜负，那得走到终局数子阶段，GNUGo里对应的是final_score命令。
3.2 解析genmove返回：= E17与pass、resign三个分支
AI落子的核心命令是genmove。发一条genmove black，引擎会自己根据当前棋盘状态算一手棋，然后返回结果。
public string GenMove(char color, float timeout = 10f) { _stdin.WriteLine($"genmove {color}"); return _stdout.ReadLine(); }注意这里timeout我留了参数但没真正用上。因为ReadLine()是阻塞式的，引擎思考多久，这行代码就堵多久。在原型阶段这个写法没问题，但做真实项目时你必须把它挪到异步逻辑里，否则Unity会卡死，这个坑在第5章会细说。
返回的字符串大概是= E17、= PASS或= RESIGN，也可能以?开头表示引擎内部出错。解析时要对这三种结果分别处理：
public enum AiMoveType { Move, Pass, Resign, Error } public AiMoveType TryParseGenmove(string resp, out Vector2Int pos) { pos = new Vector2Int(-1, -1); if (string.IsNullOrEmpty(resp) || resp[0] == '?') return AiMoveType.Error; string payload = resp.Length > 2 ? resp.Substring(2).Trim() : ""; if (payload.ToLower() == "pass") return AiMoveType.Pass; if (payload.ToLower() == "resign") return AiMoveType.Resign; pos = GtpToBoard(payload); if (pos.x < 0) return AiMoveType.Error; return AiMoveType.Move; }resp.Substring(2)是把前面的=两个字符切掉，剩下的才是真正的落子坐标。pass要格外留意：它表示引擎认为当前局面已经没有好的着法，常见于终局阶段或双方地盘已定。如果游戏里没有处理pass，AI一认输或者一过手，整个UI就会卡在等待状态。
resign则代表引擎判断差距悬殊直接认输。教学演示场景里，跟玩家说“AI认输了”要比默默让游戏结束体面得多。所以这三个分支都应该在UI层有对应反馈。
3.3 调AI强弱的三组参数：level、思考时间和随机种子
GNUGo的棋力不是写死的，启动时可以通过参数调。实操里我用得最多的是下面这几个：
| 启动参数 | 作用 | 课设推荐范围 |
|---|---|---|
--level | 搜索强度，1到10，越高越强 | 3到5，答辩演示可选8 |
--timelimit | 每手思考时间上限，单位秒 | 5到15 |
--seed | 随机种子，固定后可复现对局 | 任意整数，比如2024 |
--chinese-rules | 使用中国规则贴目7.5 | 默认开启即可 |
核心参数是level。它控制着引擎的搜索深度和广度，level 3 和 level 10 的棋力差异非常明显。但不要一上来就设10，level 10加上复杂的开局，单手思考时间可能超过十几秒，放在答辩现场就是一场即兴发呆表演。我一般建议课设默认level 5，配一个10秒的timelimit，棋力足够让非专业玩家感受到压力，又不会把节奏拖死。
想做出“AI有弱有强”的难度选择界面，最简单的方式是给每个难度档位映射一组启动参数：
// 简单/中等/困难三档，实际值可按演示效果微调 public string GetLevelArguments(int difficulty) { switch (difficulty) { case 0: return "--level=3 --timelimit=5"; case 1: return "--level=5 --timelimit=10"; case 2: return "--level=8 --timelimit=15"; default: return "--level=5 --timelimit=10"; } }如果你还想要一个“复盘功能”，就把随机种子固定下来。同样的棋局、同样的种子，AI会走出完全一样的应对策略，这对调试很有用，也是演示时展示项目规范性的加分项。
4. 在线对战落地：一台权威服务器与走棋消息同步
4.1 选型：课设阶段为什么我推荐Mirror而不是手写Socket
在线对战的本质是让两个客户端的棋盘保持一致。Unity里能选的路子大致有三种：Mirror这类网络库、Photon这类云服务SDK、以及自己手写UDP/TCP Socket。
对课设和毕设，我强烈建议用Mirror。它最大的优势是保留了Unity旧版本里[Command]/[ClientRpc]的编程习惯，写RPC像写普通方法一样自然，而且支持Host模式——一台机器既可以当服务器又当客户端，答辩时没有第二台电脑也能自己和自己对战演示。自己在Unity里手写Socket不是不行，但你要自己解决消息序列化、帧同步、掉线重连、NAT穿透这些问题，任何一个都比写围棋规则本身更难缠。Photon这类服务更稳定，但需要注册账号、申请AppId，课设阶段往往卡在审核流程上，不如Mirror下载导入就能跑。
4.2 最小走棋消息协议：从客户端发指令到全端广播
在线对战里最容易犯的错误，是让每个客户端自己维护整盘棋的规则判断。正确的做法是设置一个权威服务器：所有落子指令先发给服务器，由服务器校验合法性，再把结果广播给所有人。用Mirror实现，核心代码其实很短。
using Mirror; using UnityEngine; public class GoGameNetwork : NetworkBehaviour { [SyncVar(hook = nameof(OnLatestMove))] public string latestMoveGtp; [Command(requiresAuthority = false)] public void CmdSendMove(string gtp) { // 服务器收到客户端请求，校验通过后才广播 if (!ServerValidateMove(gtp)) return; latestMoveGtp = gtp; // SyncVar会自动同步到所有客户端 } private void OnLatestMove(string oldValue, string newValue) { if (string.IsNullOrEmpty(newValue)) return; BoardUI.PlaceStoneFromGtp(newValue); } }[Command(requiresAuthority = false)]表示任何客户端都可以调用这个方法，但真正的执行权在服务器上。所谓“权威”，就是哪怕某个客户端伪造了一手棋，只要服务器不认，这步棋就不会进棋盘。上边代码里ServerValidateMove就是服务器端的校验入口，我把GNUGo引擎的play命令直接当作裁判：
// 服务器端校验：用GNUGo的play命令验证整手棋 private bool ServerValidateMove(string gtp) { bool ok = _gnuGo.PlayMove(_currentTurnColor, gtp); if (!ok) return false; _currentTurnColor = _currentTurnColor == "black" ? "white" : "black"; return true; }这里把两次验证放到了一起：GNUGo返回的? illegal move既能拦住禁区落子，也能通过返回真值判断当前是不是轮到该方。服务器维护着_currentTurnColor，客户端即使连发两次，服务器也会因为轮次不匹配而拒绝。
4.3 断线/AI托管：对战中掉线如何让对局不崩
在线对战还有一个课设里躲不掉的需求：玩家掉线了怎么办。Mirror里可以通过NetworkServer的玩家断开回调来做托管逻辑，把掉线玩家的落子权交给GNUGo，也就是用引擎顶上，继续把棋下完，而不用判负或者卡住。
public void OnPlayerDisconnected(NetworkConnectionToClient conn) { if (!_gameInProgress) return; // 掉线一方由GNUGo接管，生成一手棋并广播 string resp = _gnuGo.GenMove(_currentTurnColor); if (resp.StartsWith("= ")) { latestMoveGtp = resp.Substring(2).Trim(); _currentTurnColor = _currentTurnColor == "black" ? "white" : "black"; } }这样断线的一方不会给局面留下一只“死棋子”，游戏体验不会被破坏。唯一的副作用是，AI接管后棋力可能比原玩家强，相当于对面突然被换了一个高手代打，但这在课设演示里反而能作为一种“AI托管对战”的功能亮点来展示。
5. Unity围棋项目避坑与排查：从GNUGo黑匣子到同步偏差
5.1 进程启动后无响应的黑匣子
现象：Unity编辑器运行后，GNUGo进程被拉起了，但ReadLine()一直阻塞，日志里什么都打不出来，感觉像引擎死了一样。
原因：九成是进程启动参数不对。最常见的是WorkingDirectory没设或设错，GNUGo在自己的可执行文件同目录下找不到配置数据，启动完直接退出；还有一种典型错误是UseShellExecute的值没设成false，导致标准输入输出根本没法重定向，你写进去的命令全丢进了黑洞。
解决：启动参数固定在Start方法里逐一排查，最稳妥的写法是WorkingDirectory显式取可执行文件所在目录，并把三个Redirect选项全部打开。
_proc.StartInfo.UseShellExecute = false; _proc.StartInfo.CreateNoWindow = true; _proc.StartInfo.WorkingDirectory = Path.GetDirectoryName(Path.GetFullPath(gnugoPath));改完后再用name命令做握手，如果握手通了，说明GNUGo确实活着，问题在别处。
5.2 落子差一格：GTP坐标里没有I
现象：你明明点击棋盘落了一子，棋子却落在右边一个交叉点上，或者在靠边的地方直接越界消失。
原因：坐标映射时没考虑GTP字母跳过了I。字母K通过'K' - 'A' + 1算出来是11，但真实棋盘里K是第10列，因为I不存在。新手在第一次写棋盘坐标转换时基本都会踩这个坑，属于这个方向最经典的血泪经验。
解决：在GtpToBoard里补上if (file > 'I') col--;，反向转换时补if (file >= 'I') file++;。验证方法很简单，强制让引擎通过play black A1、play white T19各下一手，再看棋盘上棋子的渲染位置在不在角落，用角落锚点来定位比人肉数格子高效得多。
5.3 在线对战不同步：主机权威与重放裁决
现象：两个客户端各自能正常落子，但几分钟后提子数量不一样了。A端显示黑棋提了对方五子，B端棋盘上还有两颗白子顽固地留着。
原因：客户端各自跑了一套围棋规则判断，落子顺序不同、提子时机也不一致。本质上不是网络问题，是设计问题——每个客户端都在自己脑子里画棋盘，那必然有画岔的一天。
解决：服务器统一裁决。所有非法落子、提子、轮次判断全部收归服务器端逻辑，客户端只负责两件事：把自己的落子坐标发上去，再把服务器广播下来的棋盘状态画出来。如果你用GNUGo做裁判，服务器就是唯一的真棋盘，客户端只是显示终端。加一个对局序号也能排查迟到的旧消息，但根源还是“权威体”没有立住。
5.4 Windows中文路径与控制台编码翻车
现象：GNUGo放在带中文或者空格的目录下，进程启动后一闪而过；偶尔能从标准输出读出怪字符，导致坐标解析全乱。
原因：GNUGo是年头很长的C程序，对非ASCII路径的兼容性很差，中文目录尤其容易导致它找不到内部文件直接退出。控制台输出的编码在Windows下也可能和Unity默认解析不一致，产生乱码。
解决：把GNUGo的可执行文件放到Unity项目Assets下的StreamingAssets子目录，路径全部用英文、不要带空格，运行时通过Path.Combine(Application.streamingAssetsPath, "gnugo.exe")来拼接完整路径。遇到读出的字符串首字符是奇怪符号，可以强制给StandardInput和StandardOutput设置ASCII编码：
_stdin.OutputEncoding = System.Text.Encoding.ASCII;这一行虽然简单，但往往能干掉一半编码类玄学问题。
5.5 主线程卡死：别在Update里同步读进程
现象：AI思考超过两秒，Unity窗口就变白，拖动窗口弹回“未响应”，等引擎出结果才恢复。
原因：ReadLine()是阻塞调用，放在Update里就是直接堵住Unity主线程。GNUGo算得越久，你的UI就卡得越久，这在演示现场是灾难。
解决：把GNUGo的读取工作挪到后台线程或者异步任务里，主线程只检查队列里有没有新落子。
private ConcurrentQueue<string> _responses = new ConcurrentQueue<string>(); // 后台线程读取引擎输出 void ReadLoop() { while (!_proc.HasExited) { string line = _stdout.ReadLine(); if (line != null) _responses.Enqueue(line); } } // Unity主线程里消费 void Update() { if (_responses.TryDequeue(out var line)) HandleAiResponse(line); }这样即使引擎想十秒，Unity界面依然能转动镜头、响应菜单。注意后台线程里读出来的字符串不能直接拿来改UI，要通过队列交回主线程后再做渲染处理。这个写法在答辩时也能说明白一个加分项：主线程不阻塞。
6. 验收技巧：给AI对战写一个GTP回放测试，再做一盘自动对弈
课设做完，最难回答的一个问题往往是“你怎么证明它没问题”。我现在的做法是，在开发初期就写一个编辑模式下的自动化测试，让两个GNUGo进程自对弈二十几手，用固定种子保证每盘结果可复现。这样每次改完代码跑一遍测试，就能知道协议层有没有被改坏。
using NUnit.Framework; public class GnuGoAutoPlayTest { [Test] public void GnuGo_AutoPlay_StaysAlive() { using var engine = new GnuGoProcess(); Assert.IsTrue(engine.Start("gnugo.exe")); for (int i = 0; i < 25; i++) { string black = engine.GenMove('B'); Assert.IsTrue(black.StartsWith("= ")); string white = engine.GenMove('W'); Assert.IsTrue(white.StartsWith("= ")); } } }这个测试看起来粗糙，但它实实在在保住了三层东西：进程能启动、命令能被解析、引擎不会在中途崩溃退出。每次迭代棋盘UI或网络代码后，跑一遍这个用例，比你手动下一整盘棋高效得多。我还习惯给它加一个超时保护，防止某天引擎卡死，让测试任务永远挂在那里。
除了自动化测试，验收阶段值得再补一个“能讲给老师听”的进阶点：在游戏里做一个对局信息面板，实时显示当前落子颜色、手数、AI思考耗时和最后一手棋的GTP坐标。这个面板成本很低，但它能直观地让人看到Unity和GNUGo之间确实在持续交换数据，而不是一个写死的动画。很多人做在线对战觉得难，是因为没有把服务器权威模型立起来；一旦立起来了，后面加悔棋、加保存棋谱、加AI托管，都只是在这个信任模型上继续堆功能。
我现在的个人习惯是，拿到“围棋+Unity+AI”这类题，第一件事不是画界面，而是先写一个能连接GNUGo进程并自动跑完二十手的测试脚本。脚本能稳定通过，才轮得到往场景里摆棋盘。这套顺序让我在后面踩进程和同步的坑时，总有个不能骗人的基线兜底。希望帮到你。
本文还有配套的精品资源，点击获取
