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. **可扩展**：支持新功能无痛添加
|
||
|
||
这种设计确保了系统的可维护性、可测试性和可扩展性。 |