lsamc
/
kards-env
1
0
Fork 0
Code Pull Requests Releases Activity
kards-env/docs/architecture/SYSTEM_DESIGN.md

5.9 KiB
Raw Permalink Blame History

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：

# 单位操作
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（单位系统）

组件化设计：

class Unit:
    stats: UnitStats           # 攻防血量
    keywords: Set[str]         # 关键词集合
    abilities: List[Ability]   # 能力列表
    activation_cost: int       # 激活费用

单位类型：

  • INFANTRY：基础作战单位
  • TANK：可同回合移动+攻击
  • ARTILLERY：无视距离和守护，不受反击
  • FIGHTER：无视距离，保护免受轰炸
  • BOMBER：无视距离和守护，不受反击（战斗机除外）

4. 资源系统

双层Kredits设计：

# 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

集中管理所有战斗规则：

@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. 可扩展：支持新功能无痛添加

这种设计确保了系统的可维护性、可测试性和可扩展性。