簡介這是一份面向C與Qt初學(xué)者的黑白棋完整項目源碼適合想通過小游戲?qū)嵺`GUI開發(fā)、鞏固算法與數(shù)據(jù)結(jié)構(gòu)的學(xué)習(xí)者。壓縮包共28個文件約1.12MB以cpp源文件、h頭文件、o目標(biāo)文件為主另含pro工程文件、ui界面文件、Makefile及可執(zhí)行程序覆蓋從工程配置到編譯產(chǎn)物的完整鏈路。已有364人學(xué)習(xí)下載。代碼圍繞8×8棋盤展開包含合法落子判斷、橫豎斜方向棋子翻轉(zhuǎn)與連鎖反應(yīng)處理、游戲結(jié)束判定等核心邏輯并借助QGraphicsView等類實現(xiàn)鼠標(biāo)點擊交互與界面信息展示還涉及存檔加載的序列化思路和基于最小-最大搜索加Alpha-Beta剪枝的AI設(shè)計。讀者可據(jù)此理解Qt信號槽與事件響應(yīng)機(jī)制掌握棋盤狀態(tài)更新與界面刷新配合方式并參考工程結(jié)構(gòu)自行擴(kuò)展動畫、計分或單人模式是銜接C語法與桌面應(yīng)用開發(fā)的實踐素材。1. 一個棋盤類項目為什么值得拿來練手很多人第一次接觸 Qt 是從計算器、記事本這類界面 Demo 開始的控件擺一擺、信號槽連一連跑起來就完事了。但真到要寫一個能玩、能判斷勝負(fù)、還要有 AI 對手的完整小游戲時問題就全冒出來了棋盤狀態(tài)怎么存、落子合法性怎么判、翻轉(zhuǎn)邏輯寫在哪一層、界面和規(guī)則怎么解耦。黑白棋Reversi恰好是個體量剛好的靶子——規(guī)則不復(fù)雜但足夠把「數(shù)據(jù)模型 規(guī)則引擎 界面渲染 搜索算法」這條鏈路完整走一遍。這份 C Qt 的黑白棋工程適合兩類人一類是剛學(xué)完 C 語法、想找個能跑起來的完整項目練手的另一類是寫過界面但沒系統(tǒng)做過游戲狀態(tài)管理的想看看別人怎么把棋盤邏輯和 Qt 控件拆開。下面我按「能干什么 → 怎么跑 → 代碼怎么組織 → 怎么改」的順序把這個工程拆開講。2. 環(huán)境準(zhǔn)備與首次編譯從零把工程跑起來2.1 工具鏈選型與版本對齊這個工程是標(biāo)準(zhǔn)的 Qt Widgets 項目核心依賴只有 Qt 本身沒有引入第三方庫所以環(huán)境準(zhǔn)備的重點是「Qt 版本 編譯器」這一對組合別錯配。常見做法是用 Qt 5.15 或 Qt 6.x 的 LTS 版本配套 MinGWWindows或系統(tǒng)自帶的 GCC/ClangLinux、macOS。Qt 6 之后部分 API 有調(diào)整比如QString的一些隱式轉(zhuǎn)換被收緊如果工程是按 Qt 5 寫的直接拿 Qt 6 編譯可能會在字符串拼接處報錯這時候要么降版本要么按報錯逐處補(bǔ)QStringLiteral。工程文件一般是.pro形式用 qmake 構(gòu)建。打開后先確認(rèn)QT 那一行有沒有把widgets帶上純界面項目漏了這行會在鏈接階段報一堆找不到QWidget的符號。我一般習(xí)慣先不急著改代碼原樣編譯一次看能不能出可執(zhí)行文件能出再談改造出不來就先解決環(huán)境。# 用 qmake 生成 Makefile 并編譯Linux/macOS 下 qmake Reversi.pro make -j4 # Windows MinGW 環(huán)境下通常是 qmake Reversi.pro mingw32-make -j4上面命令里-j4是并行編譯的核數(shù)機(jī)器好可以開到 8。qmake負(fù)責(zé)讀.pro生成平臺相關(guān)的構(gòu)建腳本make才是真正編譯。如果qmake這一步就報「找不到 Qt 安裝」說明 Qt 的 bin 目錄沒進(jìn) PATH或者該用 Qt 自帶的命令行終端Qt Creator 里那個「Qt 5.x MinGW Terminal」來執(zhí)行。2.2 用 Qt Creator 打開與運行配置不想折騰命令行的話直接用 Qt Creator 打開.pro文件最省事。打開后左側(cè)「項目」面板會讓你選 Kit這里要選和你安裝的 Qt 版本一致的那個 Kit選錯了會出現(xiàn)「編譯通過但運行閃退」或者「找不到平臺插件」的經(jīng)典問題。選好 Kit 后按 CtrlR 運行第一次運行如果彈窗提示缺少Q(mào)t5Core.dll之類是因為動態(tài)庫沒在可執(zhí)行文件旁邊Qt Creator 運行時會自動處理但你要是把 exe 單獨拷出去雙擊就得用windeployqt把依賴拷齊。# 把 exe 拷到空目錄后用 windeployqt 補(bǔ)齊運行依賴 windeployqt Reversi.exewindeployqt會掃描 exe 的導(dǎo)入表把需要的 Qt DLL、平臺插件platforms/qwindows.dll一并復(fù)制過來。這一步是 Windows 下分發(fā) Qt 程序的標(biāo)配漏了平臺插件程序啟動會直接報「This application failed to start because no Qt platform plugin could be initialized」。2.3 首次運行該看到什么編譯成功后運行正常應(yīng)該出現(xiàn)一個固定大小的棋盤窗口8×8 的格子初始四顆棋子擺在中央呈交叉狀黑棋先行。鼠標(biāo)懸?；螯c擊空格子時如果該位置合法應(yīng)該有落子反饋不合法則無反應(yīng)或提示。如果窗口出來了但棋盤是空白多半是paintEvent里沒觸發(fā)重繪或者棋盤數(shù)據(jù)初始化沒跑如果點擊沒反應(yīng)先查信號槽有沒有連上再查落子合法性判斷是不是把所有位置都判成了非法。這兩類問題在下面排查章節(jié)會展開。3. 工程結(jié)構(gòu)拆解棋盤數(shù)據(jù)、規(guī)則引擎與界面如何分層3.1 目錄與類的職責(zé)劃分這類 Qt 小游戲工程結(jié)構(gòu)上通常分三塊界面層主窗口、棋盤控件、規(guī)則層棋盤狀態(tài)、落子與翻轉(zhuǎn)計算、AI 層搜索與評估。目錄大致長這樣Reversi/ ├── Reversi.pro # qmake 工程文件 ├── main.cpp # 程序入口創(chuàng)建 QApplication 和主窗口 ├── mainwindow.h/.cpp # 主窗口菜單、狀態(tài)欄、棋盤控件容器 ├── boardwidget.h/.cpp # 棋盤控件繪制、鼠標(biāo)事件、坐標(biāo)換算 ├── board.h/.cpp # 棋盤數(shù)據(jù)模型8x8 狀態(tài)、落子、翻轉(zhuǎn)、勝負(fù)判斷 └── aiplayer.h/.cpp # AI 對手合法走法枚舉、極小化極大搜索、評估函數(shù)職責(zé)上Board是純邏輯類不依賴任何 Qt 界面頭文件只用一個二維數(shù)組或std::arraystd::arrayint,8,8存狀態(tài)0 表示空、1 表示黑、2 表示白。BoardWidget繼承QWidget負(fù)責(zé)把Board的狀態(tài)畫出來并把鼠標(biāo)點擊換算成行列坐標(biāo)交給Board處理。MainWindow負(fù)責(zé)把兩者拼起來管回合切換和狀態(tài)欄文字。這種「邏輯不碰界面」的分層是這類項目最值得學(xué)的地方后面加 AI、加悔棋、加存檔都靠它。3.2 棋盤狀態(tài)的數(shù)據(jù)結(jié)構(gòu)棋盤狀態(tài)用定長二維數(shù)組最直接8×8 一共 64 格不需要動態(tài)擴(kuò)容。用int存每格狀態(tài)比用enum class在數(shù)組下標(biāo)訪問時少一層轉(zhuǎn)換寫起來順手。關(guān)鍵是要把「當(dāng)前輪到誰」也作為狀態(tài)的一部分否則每次判斷都得從外部傳進(jìn)來容易漏。// board.h #pragma once #include array class Board { public: static constexpr int SIZE 8; enum Cell { Empty 0, Black 1, White 2 }; Board(); void reset(); // 重置為初始四子局面 bool isValidMove(int row, int col, int player) const; bool applyMove(int row, int col, int player); // 落子并翻轉(zhuǎn)非法返回 false int countPieces(int player) const; // 統(tǒng)計某方棋子數(shù) bool hasAnyValidMove(int player) const; // 是否還有合法走法 int cellAt(int row, int col) const { return grid_[row][col]; } private: std::arraystd::arrayint, SIZE, SIZE grid_{}; int flipCount(int row, int col, int player, int dr, int dc) const; };grid_用std::array而不是裸數(shù)組好處是能直接值拷貝、能拿到size()調(diào)試時也更好看。Cell枚舉定義在類內(nèi)外部用Board::Black引用避免全局命名污染。flipCount是私有輔助函數(shù)給定方向和起點數(shù)一數(shù)這個方向能翻幾顆落子合法性判斷和實際翻轉(zhuǎn)都復(fù)用它避免兩處邏輯寫岔。3.3 落子合法性判斷與八方向翻轉(zhuǎn)黑白棋的核心規(guī)則就一條落子后從落子點出發(fā)沿八個方向只要某一方向上出現(xiàn)「連續(xù)對方棋子 己方棋子」的結(jié)構(gòu)中間那些對方棋子全部翻成己方。合法性判斷就是「至少有一個方向能翻」。這段邏輯寫錯整個游戲就沒法玩所以值得逐行看。// board.cpp節(jié)選 int Board::flipCount(int row, int col, int player, int dr, int dc) const { int opponent (player Black) ? White : Black; int r row dr, c col dc, count 0; while (r 0 r SIZE c 0 c SIZE grid_[r][c] opponent) { count; r dr; c dc; } // 必須越過對方棋子后落在己方棋子上才算有效 if (count 0 r 0 r SIZE c 0 c SIZE grid_[r][c] player) return count; return 0; } bool Board::isValidMove(int row, int col, int player) const { if (row 0 || row SIZE || col 0 || col SIZE) return false; if (grid_[row][col] ! Empty) return false; static const int dirs[8][2] {{-1,-1},{-1,0},{-1,1},{0,-1},{0,1},{1,-1},{1,0},{1,1}}; for (auto d : dirs) if (flipCount(row, col, player, d[0], d[1]) 0) return true; return false; }flipCount的循環(huán)條件是「在界內(nèi)且是對方棋子」一旦碰到空或己方就停。停下來的位置如果正好是己方棋子且中間至少翻了一顆count 0這個方向才有效。注意邊界判斷要寫在循環(huán)條件里不能等越界了再補(bǔ)否則數(shù)組下標(biāo)會越界讀。dirs數(shù)組把八個方向一次性列出來比寫八段重復(fù)代碼清爽得多這也是這類棋盤游戲最常見的寫法。applyMove在確認(rèn)合法后對每個有效方向再走一遍翻轉(zhuǎn)把中間棋子改色。這里有個容易翻車的點翻轉(zhuǎn)必須基于「落子前」的狀態(tài)判斷方向有效性不能邊翻邊判否則剛翻過去的棋子會影響后續(xù)方向判斷。穩(wěn)妥做法是先收集所有要翻的坐標(biāo)最后統(tǒng)一改。3.4 界面繪制與鼠標(biāo)坐標(biāo)換算BoardWidget的paintEvent負(fù)責(zé)畫格子和棋子mousePressEvent負(fù)責(zé)把像素坐標(biāo)換算成行列。棋盤一般畫成正方形格子邊長 控件寬度 / 8坐標(biāo)換算就是整除。// boardwidget.cpp節(jié)選 void BoardWidget::paintEvent(QPaintEvent*) { QPainter p(this); int cell qMin(width(), height()) / Board::SIZE; for (int r 0; r Board::SIZE; r) for (int c 0; c Board::SIZE; c) { QRect rect(c * cell, r * cell, cell, cell); p.fillRect(rect, QColor(34, 139, 34)); // 棋盤綠底 p.setPen(Qt::black); p.drawRect(rect); int v board_-cellAt(r, c); if (v ! Board::Empty) { p.setBrush(v Board::Black ? Qt::black : Qt::white); p.drawEllipse(rect.adjusted(4, 4, -4, -4)); // 留邊距畫圓 } } } void BoardWidget::mousePressEvent(QMouseEvent* e) { int cell qMin(width(), height()) / Board::SIZE; int c e-pos().x() / cell; int r e-pos().y() / cell; emit cellClicked(r, c); // 交給主窗口處理回合與合法性 }rect.adjusted(4,4,-4,-4)是給棋子留邊距不然圓會貼著格子邊視覺上很擠。cellClicked用信號拋出去而不是在控件里直接改棋盤這樣控件只負(fù)責(zé)「報告點了哪」回合切換、AI 響應(yīng)都放在主窗口職責(zé)清晰。qMin(width(), height())保證控件被拉成非正方形時棋盤仍然按短邊算不會畫歪。4. AI 對手與搜索讓機(jī)器會下棋的那幾十行4.1 合法走法枚舉與評估函數(shù)AI 的第一步是把當(dāng)前局面下所有合法走法列出來這一步直接復(fù)用Board::isValidMove遍歷 64 格即可。第二步是給每個走法打分最樸素的是「棋子數(shù)差」但黑白棋里棋子多不一定是好事角位價值極高、邊位次之、靠近角的星位是陷阱。常見做法是給每個格子一個權(quán)重落子得分 權(quán)重 翻轉(zhuǎn)收益。// aiplayer.cpp節(jié)選 static const int WEIGHT[8][8] { { 100, -20, 10, 5, 5, 10, -20, 100}, { -20, -50, -2, -2, -2, -2, -50, -20}, { 10, -2, 1, 1, 1, 1, -2, 10}, { 5, -2, 1, 1, 1, 1, -2, 5}, { 5, -2, 1, 1, 1, 1, -2, 5}, { 10, -2, 1, 1, 1, 1, -2, 10}, { -20, -50, -2, -2, -2, -2, -50, -20}, { 100, -20, 10, 5, 5, 10, -20, 100} }; int AI::evaluate(const Board b, int player) const { int score 0; for (int r 0; r Board::SIZE; r) for (int c 0; c Board::SIZE; c) { int v b.cellAt(r, c); if (v player) score WEIGHT[r][c]; else if (v ! Board::Empty) score - WEIGHT[r][c]; } return score; }權(quán)重表里四個角是 100因為角一旦占住就翻不掉角旁邊的格子是 -20 到 -50因為占了角旁等于把角送給對方。這張表是黑白棋 AI 的經(jīng)典起點數(shù)值可以調(diào)但結(jié)構(gòu)基本就這樣。evaluate返回的是「站在 player 視角的凈分」搜索時要在極大極小之間取反符號別搞混。4.2 極小化極大搜索與深度控制有了評估函數(shù)就可以做極小化極大搜索AI 走一步假設(shè)對手也走最優(yōu)往下推若干層取對自己最有利的分。層數(shù)越深越強(qiáng)但耗時指數(shù)增長8×8 棋盤分支因子在開局能有十幾深度 4 到 5 是性能和棋力的平衡點。// aiplayer.cpp節(jié)選 int AI::minimax(Board board, int depth, int player, bool maximizing, int aiColor) { if (depth 0 || !board.hasAnyValidMove(Board::Black) !board.hasAnyValidMove(Board::White)) return evaluate(board, aiColor); int best maximizing ? INT_MIN : INT_MAX; for (int r 0; r Board::SIZE; r) for (int c 0; c Board::SIZE; c) { if (!board.isValidMove(r, c, player)) continue; Board next board; // 值拷貝避免污染當(dāng)前層 next.applyMove(r, c, player); int val minimax(next, depth - 1, 3 - player, !maximizing, aiColor); best maximizing ? qMax(best, val) : qMin(best, val); } return best; }Board next board這里用值拷貝是關(guān)鍵std::array讓拷貝成本可控64 個 int比手動回溯翻轉(zhuǎn)狀態(tài)安全得多。3 - player是黑白互換的小技巧1 和 2 相加為 3。maximizing標(biāo)志表示當(dāng)前層是 AI 還是對手AI 層取最大、對手層取最小。深度設(shè)太大在開局會明顯卡頓實際工程里一般配合 alpha-beta 剪枝把明顯劣勢的分支提前砍掉這里為了講清主干先不展開。4.3 把 AI 接進(jìn)回合流程AI 算完后要落子落子后要觸發(fā)界面重繪和回合切換。常見做法是在主窗口里判斷「當(dāng)前回合是白方且白方是 AI」就調(diào) AI 算一步拿到坐標(biāo)后走和人類玩家一樣的落子路徑保證邏輯只有一份。// mainwindow.cpp節(jié)選 void MainWindow::onCellClicked(int r, int c) { if (gameOver_ || current_ ! Board::Black) return; // 人類固定執(zhí)黑 if (!board_.applyMove(r, c, Board::Black)) return; boardWidget_-update(); switchTurn(); if (!gameOver_) QTimer::singleShot(300, this, MainWindow::aiMove); } void MainWindow::aiMove() { QPoint move ai_.chooseMove(board_, Board::White); if (move.x() 0) { board_.applyMove(move.x(), move.y(), Board::White); boardWidget_-update(); } switchTurn(); }QTimer::singleShot(300, ...)是給 AI 一個 300 毫秒的延遲不然 AI 瞬間落子人眼反應(yīng)不過來體驗很差。chooseMove返回QPoint(-1,-1)表示無棋可走這時要跳過該方回合而不是判負(fù)。switchTurn里還要處理「一方無子可下則對方繼續(xù)」的規(guī)則這塊漏了會出現(xiàn)雙方都卡住不動的情況。5. 避坑與排查編譯能過但玩起來不對的幾種情況5.1 點擊格子沒反應(yīng)現(xiàn)象是窗口正常、棋盤正常但鼠標(biāo)點下去毫無反饋。原因通常有兩個一是mousePressEvent里坐標(biāo)換算用了控件全寬而不是棋盤實際邊長導(dǎo)致算出的行列越界被isValidMove直接拒掉二是信號cellClicked沒連到主窗口的槽或者連了但槽里第一行就return了。解決方式是先在mousePressEvent里打印r、c確認(rèn)坐標(biāo)落在 0 到 7 之間再檢查connect那行有沒有拼錯信號名。Qt 5 之后推薦用函數(shù)指針形式的connect拼錯會在編譯期報錯比字符串形式安全。5.2 落子后棋子翻轉(zhuǎn)方向不對現(xiàn)象是能落子但翻的棋子位置和預(yù)期不符或者該翻的沒翻。原因多半是flipCount和實際翻轉(zhuǎn)用了兩套方向判斷或者翻轉(zhuǎn)時基于「已修改」的棋盤繼續(xù)判斷。血淚經(jīng)驗是先把所有要翻的坐標(biāo)收集到一個std::vectorQPoint全部收集完再統(tǒng)一改色中間不要動grid_。另外八個方向的dr、dc別寫反{-1,0}是向上、{0,-1}是向左寫反了翻轉(zhuǎn)會跑到對稱位置去。5.3 AI 一步要算好幾秒甚至卡死現(xiàn)象是輪到 AI 時界面凍結(jié)鼠標(biāo)點不動。原因是極小化極大在開局分支多、深度又設(shè)得大純遞歸沒有剪枝耗時爆炸。解決分兩步先把深度降到 3 到 4 驗證功能再加 alpha-beta 剪枝如果還慢就在搜索前先按權(quán)重給走法排序優(yōu)先搜高分走法剪枝效率會高很多。另外搜索函數(shù)里傳Board用值拷貝是安全的但別在循環(huán)里反復(fù)構(gòu)造大對象std::array的拷貝成本可以接受換成std::vector動態(tài)分配就會明顯拖慢。5.4 一方無棋可走時游戲卡住現(xiàn)象是某一方明明還有空格但輪到它時沒有任何合法走法程序既不跳過也不結(jié)束界面就停在那。原因是回合切換邏輯只做了「黑變白、白變黑」沒處理「對方無合法走法則繼續(xù)本方」的規(guī)則。正確做法是切換回合后檢查新回合方hasAnyValidMove沒有就再切一次如果雙方都沒有才判游戲結(jié)束并按棋子數(shù)定勝負(fù)。這個判斷要放在每次落子之后統(tǒng)一做別散落在各個分支里。5.5 換臺機(jī)器運行報缺少平臺插件現(xiàn)象是在自己機(jī)器上跑得好好的拷到別人電腦雙擊就彈「no Qt platform plugin could be initialized」。原因是只拷了 exe沒拷platforms/qwindows.dll和 Qt 核心 DLL。解決是用windeployqt處理一遍或者手動把 Qt 安裝目錄下plugins/platforms整個文件夾和幾個核心 DLL 放到 exe 同級目錄。注意platforms文件夾名不能改Qt 是按固定路徑找插件的。6. 二次開發(fā)從能玩到好玩我一般改這幾處拿到這個工程后最值得先動的是 AI 的棋力因為它決定了這個項目是「玩具」還是「能跟人下幾盤」的東西。我的習(xí)慣是先加 alpha-beta 剪枝改動集中在minimax函數(shù)多傳兩個參數(shù)alpha、beta在最大化層更新alpha、最小化層更新beta一旦alpha beta直接返回。這一步通常能把同樣深度下的節(jié)點數(shù)砍掉一大半深度從 4 提到 6 也不至于卡死。int AI::minimax(Board board, int depth, int player, bool maximizing, int aiColor, int alpha, int beta) { if (depth 0) return evaluate(board, aiColor); int best maximizing ? INT_MIN : INT_MAX; for (int r 0; r Board::SIZE; r) for (int c 0; c Board::SIZE; c) { if (!board.isValidMove(r, c, player)) continue; Board next board; next.applyMove(r, c, player); int val minimax(next, depth - 1, 3 - player, !maximizing, aiColor, alpha, beta); if (maximizing) { best qMax(best, val); alpha qMax(alpha, best); } else { best qMin(best, val); beta qMin(beta, best); } if (beta alpha) return best; // 剪枝 } return best; }剪枝的收益在開局最明顯因為開局分支多、很多走法一眼就差。加完之后建議做個簡單驗證固定一個開局局面分別用剪枝前后跑深度 4對比返回的最佳走法是否一致、耗時差多少。如果走法變了但棋力沒降說明剪枝寫對了如果走法變得很離譜多半是alpha、beta的更新方向搞反了。第二處值得改的是悔棋。因為Board是值類型悔棋最簡單的實現(xiàn)是在主窗口維護(hù)一個std::vectorBoard棧每次落子前把當(dāng)前局面壓?；谄鍟r彈棧覆蓋。這比記錄每一步的翻轉(zhuǎn)坐標(biāo)再逆操作要省心得多代價是每步多存 64 個 int對這個體量完全無所謂。第三處是存檔把grid_和當(dāng)前回合序列化成一個文本文件讀檔時反序列化回來格式用「8 行每行 8 個數(shù)字 一行回合」就夠不用上 JSON 庫。改 AI 這塊我踩過最深的坑是評估函數(shù)的符號。有一版我把對手棋子的權(quán)重也按正分累加結(jié)果 AI 瘋狂送子因為它的評估里「對方棋子多」反而成了好事。從那以后我每次改評估函數(shù)都強(qiáng)制拿一個已知局面的手算分?jǐn)?shù)對一遍確認(rèn) AI 視角和對手視角的符號沒反再往下調(diào)權(quán)重。希望這些能幫到你少走幾段彎路。本文還有配套的精品資源點擊獲取