# 掼蛋卡牌游戏 (Guandan Card Game)

基于 Godot 4.x 开发的掼蛋卡牌游戏。目前处于训练模式开发阶段。

## 环境要求

- **Godot 4.x** (开发使用 4.6.3)
- 安装方式: `winget install GodotEngine.GodotEngine`
- 或从 [godotengine.org](https://godotengine.org/download) 下载

## 项目结构

```
game-cards/
├── src/
│   ├── core/          # 业务逻辑层（纯 GDScript，零依赖）
│   ├── ai/            # AI 模块（L1 基础 / L2 规则 / L3 策略）
│   ├── game/          # 游戏控制器（训练/对战/回放）
│   ├── network/       # 联机层（后期）
│   ├── ui/            # UI 场景和组件
│   │   ├── scenes/    # 主菜单、训练室、牌桌、大厅、观战
│   │   └── components/ # 卡牌、手牌区、出牌区等组件
│   └── autoload/      # 全局单例（配置、事件总线、音频）
├── tests/             # GUT 单元测试
├── docs/              # 设计文档和实施计划
└── assets/            # 卡牌图片、UI 素材、音频、字体
```

## 运行

### 1. 打开项目

用 Godot 编辑器打开项目根目录 `game-cards/`。

### 2. 配置 Autoload（首次运行）

进入 **项目 → 项目设置 → 自动加载 (Autoload)**，依次添加：

| 名称 | 路径 |
|------|------|
| Config | `res://src/autoload/config.gd` |
| EventBus | `res://src/autoload/event_bus.gd` |
| AudioManager | `res://src/autoload/audio_manager.gd` |

### 3. 设置主场景

**项目 → 项目设置 → 运行 → 主场景** 设为 `res://src/ui/scenes/main_menu.tscn`

### 4. 启动

按 **F5** 或点击右上角 **运行项目**。

## 运行测试

### 通过 GUT 运行（推荐）

1. 在 Godot AssetLib 中安装 **GUT** 插件并启用
2. 点击 GUT 面板 → 设置测试目录为 `res://tests`
3. 点击 **Run**

### 通过命令行

```bash
godot --headless -s addons/gut/gut_cmdln.gd -gdir=res://tests
```

## 开发计划

| 阶段 | 内容 | 状态 |
|------|------|------|
| 训练模式 | 核心逻辑 + L1/L2 AI + 牌型提示 | 进行中 |
| 单机对战 | 完整四人局 + L3 AI | 待开发 |
| 联机 | Action 同步 + 匹配 + 房间 | 待开发 |
| 观战 | Action 流回放 | 待开发 |

## 设计文档

- [设计规格](./docs/superpowers/specs/2026-05-28-guandan-card-game-design.md)
- [实施计划](./docs/superpowers/plans/2026-05-28-guandan-training-mode.md)