202 lines
5.9 KiB
Markdown
202 lines
5.9 KiB
Markdown
|
# KARDS Battle System - 系统设计文档
|
|||
|
|
|
|||
|
|
## 🏗️ 架构概述
|
|||
|
|
|
|||
|
|
KARDS战斗系统采用模块化设计，专注于核心战斗机制，为AI训练提供完整的游戏环境。
|
|||
|
|
|
|||
|
|
## 📁 项目结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
kards/
|
|||
|
|
├── kards_battle/ # 核心战斗系统包
|
|||
|
|
│ ├── core/ # 核心引擎和逻辑
|
|||
|
|
│ │ ├── battle_engine.py # 主战斗引擎（当前使用）
|
|||
|
|
│ │ ├── enums.py # 枚举定义
|
|||
|
|
│ │ └── unit_combat_rules.py # 战斗规则
|
|||
|
|
│ ├── battlefield/ # 战场管理
|
|||
|
|
│ │ └── battlefield.py # 3线战场系统
|
|||
|
|
│ ├── units/ # 单位系统
|
|||
|
|
│ │ └── unit.py # 单位基类
|
|||
|
|
│ ├── abilities/ # 能力系统
|
|||
|
|
│ │ ├── abilities.py # 能力基类
|
|||
|
|
│ │ └── keywords.py # 关键词效果
|
|||
|
|
│ ├── effects/ # 效果系统
|
|||
|
|
│ │ ├── effects.py # 游戏效果
|
|||
|
|
│ │ └── target_selectors.py # 目标选择
|
|||
|
|
│ └── examples/ # 示例单位
|
|||
|
|
│ └── sample_units.py # 15个示例单位
|
|||
|
|
├── tests/ # 完整测试套件
|
|||
|
|
│ ├── test_comprehensive_movement.py # 移动系统测试
|
|||
|
|
│ ├── test_turn_and_resources.py # 回合资源测试
|
|||
|
|
│ ├── unit/ # 单元测试
|
|||
|
|
│ ├── integration/ # 集成测试
|
|||
|
|
│ └── examples/ # 示例测试
|
|||
|
|
├── demo/ # 演示文件
|
|||
|
|
│ ├── demo_new_features.py # 最新功能演示
|
|||
|
|
│ ├── main.py # 主程序入口
|
|||
|
|
│ └── DEMOS.md # 演示说明
|
|||
|
|
├── archive/ # 已封存的旧版本
|
|||
|
|
└── docs/ # 项目文档
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🎯 核心模块设计
|
|||
|
|
|
|||
|
|
### 1. BattleEngine（战斗引擎）
|
|||
|
|
|
|||
|
|
**主要职责：**
|
|||
|
|
- 管理游戏状态和回合流程
|
|||
|
|
- 处理单位部署、移动、攻击
|
|||
|
|
- 管理Kredits资源系统
|
|||
|
|
- 提供DEBUG功能
|
|||
|
|
|
|||
|
|
**关键API：**
|
|||
|
|
```python
|
|||
|
|
# 单位操作
|
|||
|
|
deploy_unit_to_support(unit: Unit, player_id: int, position: Optional[int]) -> Dict
|
|||
|
|
move_unit(unit_id: UUID, target_position: tuple, player_id: int) -> Dict
|
|||
|
|
attack_target(attacker_id: UUID, target_id: Union[UUID, str], player_id: int) -> Dict
|
|||
|
|
|
|||
|
|
# 回合管理
|
|||
|
|
end_turn() -> Dict
|
|||
|
|
|
|||
|
|
# 资源管理
|
|||
|
|
get_kredits(player_id: int) -> int
|
|||
|
|
spend_kredits(player_id: int, amount: int) -> bool
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. Battlefield（战场系统）
|
|||
|
|
|
|||
|
|
**3线布局设计：**
|
|||
|
|
```
|
|||
|
|
Player1_Support [HQ] [Unit1] [Unit2] ...
|
|||
|
|
Front_Line [Unit3] [Unit4] ... (共享前线)
|
|||
|
|
Player2_Support [HQ] [Unit5] [Unit6] ...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**特性：**
|
|||
|
|
- 自动紧凑排列（无空隙）
|
|||
|
|
- 前线控制权动态更新
|
|||
|
|
- HQ作为支援线上的目标
|
|||
|
|
- 每线最多5个目标
|
|||
|
|
|
|||
|
|
### 3. Unit（单位系统）
|
|||
|
|
|
|||
|
|
**组件化设计：**
|
|||
|
|
```python
|
|||
|
|
class Unit:
|
|||
|
|
stats: UnitStats # 攻防血量
|
|||
|
|
keywords: Set[str] # 关键词集合
|
|||
|
|
abilities: List[Ability] # 能力列表
|
|||
|
|
activation_cost: int # 激活费用
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**单位类型：**
|
|||
|
|
- INFANTRY：基础作战单位
|
|||
|
|
- TANK：可同回合移动+攻击
|
|||
|
|
- ARTILLERY：无视距离和守护，不受反击
|
|||
|
|
- FIGHTER：无视距离，保护免受轰炸
|
|||
|
|
- BOMBER：无视距离和守护，不受反击（战斗机除外）
|
|||
|
|
|
|||
|
|
### 4. 资源系统
|
|||
|
|
|
|||
|
|
**双层Kredits设计：**
|
|||
|
|
```python
|
|||
|
|
# Kredits Slot：指挥点容量
|
|||
|
|
kredits_slot: int # 每回合+1，上限12
|
|||
|
|
|
|||
|
|
# Kredits：当前可用指挥点
|
|||
|
|
kredits: int # 每回合重置为slot值，上限24
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🔄 游戏流程
|
|||
|
|
|
|||
|
|
### 回合系统
|
|||
|
|
```
|
|||
|
|
Turn 1: Phase 0 (Player0) → Phase 1 (Player1)
|
|||
|
|
Turn 2: Phase 0 (Player0) → Phase 1 (Player1)
|
|||
|
|
...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 操作流程
|
|||
|
|
```
|
|||
|
|
1. 部署单位到支援线 → deploy_unit_to_support()
|
|||
|
|
2. 移动单位到前线 → move_unit()
|
|||
|
|
3. 攻击敌方目标 → attack_target()
|
|||
|
|
4. 结束回合 → end_turn()
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🎮 玩家系统
|
|||
|
|
|
|||
|
|
**玩家标识：**
|
|||
|
|
- 内部使用整数ID：`0` (Player1), `1` (Player2)
|
|||
|
|
- 显示使用名称：`"Germany"`, `"USA"`
|
|||
|
|
- API统一使用整数ID，避免字符串浪费
|
|||
|
|
|
|||
|
|
**优势：**
|
|||
|
|
- 性能更好（整数比较）
|
|||
|
|
- 代码更简洁
|
|||
|
|
- 减少字符串错误
|
|||
|
|
|
|||
|
|
## 📊 战斗规则系统
|
|||
|
|
|
|||
|
|
### UnitCombatRules
|
|||
|
|
集中管理所有战斗规则：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
@staticmethod
|
|||
|
|
def can_attack_target(attacker: Unit, target: Union[Unit, HQ], battlefield: Battlefield) -> bool
|
|||
|
|
def can_counter_attack(defender: Unit, attacker: Unit) -> bool
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 攻击距离规则
|
|||
|
|
- 步兵/坦克：只能攻击相邻战线
|
|||
|
|
- 火炮/战斗机/轰炸机：无视攻击距离
|
|||
|
|
|
|||
|
|
### 特殊规则
|
|||
|
|
- 火炮：无视守护，不受反击
|
|||
|
|
- 轰炸机：无视守护，不受反击（战斗机除外）
|
|||
|
|
- 战斗机：可保护同战线免受轰炸机攻击
|
|||
|
|
|
|||
|
|
## 🧪 测试架构
|
|||
|
|
|
|||
|
|
### 测试分层
|
|||
|
|
```
|
|||
|
|
pytest测试套件 (19个测试)
|
|||
|
|
├── 移动系统测试 (10个)
|
|||
|
|
│ ├── 成功场景测试
|
|||
|
|
│ └── 失败场景测试
|
|||
|
|
└── 回合资源测试 (9个)
|
|||
|
|
├── 资源增长测试
|
|||
|
|
└── 限制验证测试
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 测试原则
|
|||
|
|
- 每个核心功能都有对应测试
|
|||
|
|
- 覆盖成功和失败场景
|
|||
|
|
- 验证边界条件和错误处理
|
|||
|
|
- 使用setup_method确保测试独立
|
|||
|
|
|
|||
|
|
## 🔧 可扩展性设计
|
|||
|
|
|
|||
|
|
### 插件化架构
|
|||
|
|
- **关键词系统**：新关键词可独立实现
|
|||
|
|
- **能力系统**：支持部署、触发、静态等多种能力
|
|||
|
|
- **效果系统**：可组合的游戏效果
|
|||
|
|
- **目标选择**：灵活的目标选择逻辑
|
|||
|
|
|
|||
|
|
### 未来扩展方向
|
|||
|
|
- AI对手实现
|
|||
|
|
- 完整的卡牌系统
|
|||
|
|
- 图形用户界面
|
|||
|
|
- 网络对战功能
|
|||
|
|
- 战斗回放系统
|
|||
|
|
|
|||
|
|
## 💡 设计原则
|
|||
|
|
|
|||
|
|
1. **单一职责**：每个模块职责明确
|
|||
|
|
2. **低耦合**：模块间依赖最小化
|
|||
|
|
3. **高内聚**：相关功能集中管理
|
|||
|
|
4. **可测试**：所有核心逻辑都可测试
|
|||
|
|
5. **可扩展**：支持新功能无痛添加
|
|||
|
|
|
|||
|
|
这种设计确保了系统的可维护性、可测试性和可扩展性。
|