跳至主要內容

8. 棋牌游戏通用框架

EVOCOSMOS2026/4/14大约 6 分钟

棋牌游戏通用框架

棋牌游戏看似种类繁多，但底层架构高度相似：都有规则引擎、回合管理、玩家操作验证和结果判定。本章设计一套可复用的棋牌游戏通用框架。

8.1 框架整体架构

GameController（游戏控制器）
    ├── RuleEngine（规则引擎）     ← 纯逻辑，无 UI
    ├── TurnManager（回合管理器）
    ├── PlayerManager（玩家管理器）
    │   ├── HumanPlayer（人类玩家）
    │   └── AIPlayer（AI 玩家）
    ├── NetworkManager（网络管理器）← 可选
    └── SpectatorSystem（观战系统）← 可选

8.2 规则引擎

规则引擎是框架的核心，负责验证操作合法性、计算结果、判断游戏结束条件。它是纯逻辑代码，不依赖任何 UI 或网络，便于单独测试。

C#
using Godot;
using System.Collections.Generic;

// 游戏操作的基类（玩家的每一步操作）
public abstract class GameAction
{
    public int PlayerId;
    public long Timestamp;
}

// 游戏状态基类（棋盘/牌局的完整状态快照）
public abstract class GameState
{
    public int CurrentPlayer;
    public int TurnNumber;
    public bool IsGameOver;
    public int Winner = -1; // -1 表示无胜者（平局或未结束）

    public abstract GameState Clone(); // 深拷贝，用于 AI 模拟
}

// 规则引擎接口
public interface IRuleEngine<TState, TAction>
    where TState : GameState
    where TAction : GameAction
{
    // 验证操作是否合法
    bool IsValidAction(TState state, TAction action);

    // 执行操作，返回新状态（不修改原状态）
    TState ApplyAction(TState state, TAction action);

    // 获取当前玩家所有合法操作
    List<TAction> GetLegalActions(TState state, int playerId);

    // 判断游戏是否结束，并设置胜者
    bool CheckGameOver(TState state);
}

// 五子棋规则引擎示例
public class GomokuRuleEngine : IRuleEngine<GomokuState, GomokuAction>
{
    private const int BOARD_SIZE = 15;
    private const int WIN_COUNT = 5;

    public bool IsValidAction(GomokuState state, GomokuAction action)
    {
        if (state.IsGameOver) return false;
        if (action.PlayerId != state.CurrentPlayer) return false;
        if (action.Row < 0 || action.Row >= BOARD_SIZE) return false;
        if (action.Col < 0 || action.Col >= BOARD_SIZE) return false;
        return state.Board[action.Row, action.Col] == 0; // 该位置必须为空
    }

    public GomokuState ApplyAction(GomokuState state, GomokuAction action)
    {
        var newState = (GomokuState)state.Clone();
        newState.Board[action.Row, action.Col] = action.PlayerId;
        newState.TurnNumber++;
        newState.CurrentPlayer = 3 - state.CurrentPlayer; // 1→2, 2→1 切换
        CheckGameOver(newState);
        return newState;
    }

    public List<GomokuAction> GetLegalActions(GomokuState state, int playerId)
    {
        var actions = new List<GomokuAction>();
        for (int r = 0; r < BOARD_SIZE; r++)
            for (int c = 0; c < BOARD_SIZE; c++)
                if (state.Board[r, c] == 0)
                    actions.Add(new GomokuAction { PlayerId = playerId, Row = r, Col = c });
        return actions;
    }

    public bool CheckGameOver(GomokuState state)
    {
        // 检查最后一次落子是否形成五连
        for (int r = 0; r < BOARD_SIZE; r++)
        {
            for (int c = 0; c < BOARD_SIZE; c++)
            {
                int player = state.Board[r, c];
                if (player == 0) continue;
                if (CheckLine(state.Board, r, c, 1, 0, player) ||  // 横
                    CheckLine(state.Board, r, c, 0, 1, player) ||  // 竖
                    CheckLine(state.Board, r, c, 1, 1, player) ||  // 斜
                    CheckLine(state.Board, r, c, 1, -1, player))   // 反斜
                {
                    state.IsGameOver = true;
                    state.Winner = player;
                    return true;
                }
            }
        }
        return false;
    }

    private bool CheckLine(int[,] board, int startR, int startC, int dr, int dc, int player)
    {
        int count = 0;
        for (int i = 0; i < WIN_COUNT; i++)
        {
            int r = startR + i * dr;
            int c = startC + i * dc;
            if (r < 0 || r >= BOARD_SIZE || c < 0 || c >= BOARD_SIZE) break;
            if (board[r, c] == player) count++;
            else break;
        }
        return count == WIN_COUNT;
    }
}

public class GomokuState : GameState
{
    public int[,] Board = new int[15, 15];

    public override GameState Clone()
    {
        var clone = new GomokuState
        {
            CurrentPlayer = CurrentPlayer,
            TurnNumber = TurnNumber,
            IsGameOver = IsGameOver,
            Winner = Winner,
        };
        System.Array.Copy(Board, clone.Board, Board.Length);
        return clone;
    }
}

public class GomokuAction : GameAction
{
    public int Row, Col;
}

8.3 回合管理器

C#
using Godot;
using System.Collections.Generic;

public partial class TurnManager : Node
{
    [Signal] public delegate void TurnStartedEventHandler(int playerId);
    [Signal] public delegate void TurnEndedEventHandler(int playerId);
    [Signal] public delegate void GameOverEventHandler(int winner);

    private List<int> _playerOrder = new();
    private int _currentIndex = 0;
    private float _turnTimeLimit = 30f; // 每回合限时30秒
    private float _timeRemaining;
    private bool _isRunning = false;

    public int CurrentPlayer => _playerOrder.Count > 0 ? _playerOrder[_currentIndex] : -1;

    public void StartGame(List<int> playerIds)
    {
        _playerOrder = new List<int>(playerIds);
        _currentIndex = 0;
        _isRunning = true;
        StartNextTurn();
    }

    private void StartNextTurn()
    {
        _timeRemaining = _turnTimeLimit;
        EmitSignal(SignalName.TurnStarted, CurrentPlayer);
        GD.Print($"[Turn] Player {CurrentPlayer}'s turn, {_turnTimeLimit}s");
    }

    public override void _Process(double delta)
    {
        if (!_isRunning) return;
        _timeRemaining -= (float)delta;
        if (_timeRemaining <= 0)
        {
            // 超时，强制结束回合（可以自动出牌或跳过）
            GD.Print($"[Turn] Player {CurrentPlayer} timed out");
            EndTurn();
        }
    }

    // 结束当前回合，切换到下一玩家
    public void EndTurn()
    {
        EmitSignal(SignalName.TurnEnded, CurrentPlayer);
        _currentIndex = (_currentIndex + 1) % _playerOrder.Count;
        StartNextTurn();
    }

    public float GetTimeRemaining() => _timeRemaining;
    public float GetTimeProgress() => _timeRemaining / _turnTimeLimit;
}

8.4 观战系统

观战系统让非参赛玩家能实时观看对局。

C#
using Godot;
using System.Collections.Generic;

public partial class SpectatorSystem : Node
{
    private List<long> _spectators = new(); // 观战者的网络 ID
    private string _latestStateSnapshot = "";

    // 玩家申请加入观战
    [Rpc(MultiplayerApi.RpcMode.AnyPeer)]
    public void RequestSpectate()
    {
        if (!Multiplayer.IsServer()) return;
        long spectatorId = Multiplayer.GetRemoteSenderId();

        if (!_spectators.Contains(spectatorId))
        {
            _spectators.Add(spectatorId);
            GD.Print($"[Spectator] {spectatorId} joined as spectator");
        }

        // 发送当前游戏状态给新观战者
        if (!string.IsNullOrEmpty(_latestStateSnapshot))
            RpcId(spectatorId, nameof(ReceiveGameState), _latestStateSnapshot);
    }

    // 广播游戏状态给所有观战者
    public void BroadcastToSpectators(string stateJson)
    {
        _latestStateSnapshot = stateJson;
        foreach (long id in _spectators)
            RpcId(id, nameof(ReceiveGameState), stateJson);
    }

    // 观战者接收游戏状态并更新 UI
    [Rpc(MultiplayerApi.RpcMode.Authority)]
    public void ReceiveGameState(string stateJson)
    {
        GD.Print($"[Spectator] Received state update");
        // 更新观战界面（只读，无操作权限）
        UpdateSpectatorUI(stateJson);
    }

    private void UpdateSpectatorUI(string stateJson)
    {
        // 根据状态更新棋盘显示
    }
}

8.5 框架使用示例

以下展示如何用这套框架快速搭建一个五子棋游戏：

# game_controller.gd
extends Node

var rule_engine := GomokuRuleEngine.new()
var turn_manager := TurnManager.new()
var game_state: Dictionary

func _ready() -> void:
    add_child(turn_manager)
    turn_manager.turn_started.connect(_on_turn_started)

    # 初始化游戏状态
    game_state = {
        "board": [],
        "current_player": 1,
        "turn_number": 0,
        "is_game_over": false,
        "winner": -1,
    }
    for i in 15:
        game_state.board.append([])
        for j in 15:
            game_state.board[i].append(0)

    turn_manager.start_game([1, 2])

func player_place_piece(row: int, col: int) -> void:
    var action := { "player_id": game_state.current_player, "row": row, "col": col }
    if not rule_engine.is_valid_action(game_state, action):
        return
    game_state = rule_engine.apply_action(game_state, action)
    _update_board_display()
    if game_state.is_game_over:
        print("Player %d wins!" % game_state.winner)
    else:
        turn_manager.end_turn()

func _on_turn_started(player_id: int) -> void:
    print("Player %d's turn" % player_id)

框架扩展

这套框架可以轻松扩展到其他棋牌游戏：

  • 麻将：继承 RuleEngine，实现碰、杠、和牌等规则
  • 扑克：实现手牌管理、出牌顺序、组合比较等逻辑
  • 围棋：实现提子、气的计算、劫争判断等规则
最近更新:
贡献者: zefeng.peng,bobokaka
EVOCOSMOS
Copyright © 2026 EVOCOSMOS