kards-env/README.md

# KARDS 战斗系统

一个基于Python的KARDS二战卡牌游戏战斗系统复刻，采用可扩展的架构设计。

## 📋 最新更新 (2025-09-04) - v0.3.0

**🎴 卡牌系统重大升级**:
- **模板继承系统**: 卡牌定义支持模板继承，大幅减少代码重复
- **参数化卡牌**: 完整的卡牌参数系统，支持部署位置选择等交互
- **多国卡牌支持**: 德国、意大利、美国、日本卡牌全面实现
- **YAML加载器**: 强化的YAML加载器支持模板合并和验证

**🔧 模板系统特性**:
- `unit_card` 模板提供标准的 `deploy_position` 参数
- 卡牌只需 `template: "unit_card"` 而无需重复配置
- 模板参数继承和合并机制
- 所有单位卡自动支持部署到己方支援线的可选位置选择

**📚 项目文档完善**:
- 完整的卡牌系统架构文档
- 模板继承系统使用指南
- 参数系统开发者文档
- 代码示例和最佳实践

**🏗️ 项目重构完成** (v0.2.0):
- 完整的pytest测试套件（19个测试，100%通过）
- 玩家API优化：使用整数ID (0/1) 替代字符串
- 代码结构优化：封存旧版本，清理项目结构
- uv环境管理：标准化依赖和虚拟环境

## 🎯 项目目标

- 复刻KARDS游戏的核心战斗机制
- 为AI Agent提供完整的游戏环境
- 可扩展的单位、能力和效果系统

## ✨ 核心特性

### 🏗️ 战场系统
- **三线战场**: 玩家1支援线 - 共用前线 - 玩家2支援线
- **HQ系统**: 总部作为支援线上的目标，20点防御值，摧毁敌方HQ获胜
- **紧凑排列**: 单位自动紧凑排列，无空隙
- **前线控制权**: 当前线被单一玩家控制时获得控制权
- **目标限制**: 每条战线最多5个目标（包括单位和HQ）

### 🚗 单位类型
| 类型 | 英文名 | 攻击规则 | 特殊能力 |
|------|--------|----------|----------|
| 步兵 | INFANTRY | 只能攻击相邻战线 | 基础作战单位 |
| 坦克 | TANK | 只能攻击相邻战线 | 可同回合移动+攻击 |
| 火炮 | ARTILLERY | **无视攻击距离**，**无视守护** | **不受反击** |
| 战斗机 | FIGHTER | **无视攻击距离** | 保护同战线免受轰炸机攻击 |
| 轰炸机 | BOMBER | **无视攻击距离**，**无视守护** | **不受反击**（战斗机除外），但会被战斗机阻挡 |

### 🎯 关键词系统
- **BLITZ** (闪击): 部署回合可立即行动
- **GUARD** (守护): 相邻单位只能被轰炸机/火炮攻击
- **SMOKESCREEN** (烟幕): 不能被攻击，行动后失效
- **HEAVY_ARMOR_X** (重甲): 受到伤害减少X点
- **AMBUSH** (伏击): 首次被攻击时先造成伤害
- **FURY** (奋战): 每回合可攻击两次
- **MOBILIZE** (动员): 回合开始+1/+1，受伤后失效
- **PINNED** (压制): 无法移动或攻击

### 🎪 能力系统
- **部署能力** (Deploy): 进场时触发
- **触发能力** (Triggered): 特定条件下触发
- **静态能力** (Static): 持续生效的光环效果
- **激活能力** (Activated): 主动使用的能力
- **死亡能力** (Death): 被摧毁时触发

## 🎴 卡牌系统

### ✨ 核心特性
- **模板继承系统**: 减少重复定义，提高维护性
- **参数化交互**: 卡牌支持复杂的参数化操作
- **多国卡牌**: 完整支持德国、意大利、美国、日本等国家
- **YAML驱动**: 所有卡牌定义通过YAML文件管理
- **类型安全**: 完整的参数验证和类型检查

### 🏗️ 模板继承系统

卡牌模板系统允许卡牌继承通用配置，避免重复定义：

```yaml
# 模板定义 (cards_spec.yaml)
card_templates:
  - id: "unit_card"
    type: "unit"
    params:
      - name: "deploy_position"
        type: "slot"
        range: [0, 4]
        required: false
        description: "Deploy position (0-4, default: rightmost available slot)"

# 使用模板的卡牌 (japan.yaml)
unit_cards:
  - id: "jpn_imperial_guard_card"
    template: "unit_card"  # 继承模板配置
    name: "Imperial Guard"
    cost: 3
    nation: "japan"
    rarity: 4
    description: "Elite Japanese Imperial Guard infantry"
    unit_definition_id: "jpn_infantry_imperial_guard"
```

**模板系统优势**:
- **减少90%+重复代码**: 单位卡无需重复定义部署参数
- **统一标准化**: 所有单位卡自动获得标准参数
- **易于维护**: 修改模板即可影响所有继承卡牌
- **灵活扩展**: 支持多层继承和参数合并

### 📋 参数系统

卡牌参数系统支持复杂的玩家交互：

```python
from kards_battle.cards.card_params import ParameterType, ParameterDefinition

# 部署位置参数
position_param = ParameterDefinition(
    name="deploy_position",
    param_type=ParameterType.SLOT,
    param_range=(0, 4),
    required=False,
    description="选择部署位置 (0-4)"
)
```

**支持的参数类型**:
- `SLOT`: 位置选择 (0-4)
- `UNIT_TARGET`: 单位目标选择
- `MULTI_TARGET`: 多目标选择
- `CHOICE`: 选项选择
- `BOOLEAN`: 布尔选择

### 🌍 多国卡牌支持

目前支持的国家及卡牌数量：

| 国家 | 卡牌文件 | 卡牌数量 | 特色单位 |
|------|---------|---------|----------|
| 🇩🇪 德国 | `germany.yaml` | 15+ | 豹式坦克、Bf 109战斗机 |
| 🇮🇹 意大利 | `italy.yaml` | 12+ | M13坦克、精英步兵 |
| 🇺🇸 美国 | `usa.yaml` | 18+ | 谢尔曼坦克、P-51野马 |
| 🇯🇵 日本 | `japan.yaml` | 23+ | 九七式坦克、零式战斗机 |

### 📖 卡牌加载器 API

```python
from kards_battle.cards.card_loader import CardLoader, load_nation_cards
from kards_battle.core.enums import Nation

# 创建加载器
loader = CardLoader()

# 加载指定国家卡牌
japan_cards = loader.load_nation_cards(Nation.JAPAN)
print(f"加载了 {len(japan_cards)} 张日本卡牌")

# 加载所有可用卡牌
all_cards = loader.load_all_available_cards()
for nation, cards in all_cards.items():
    print(f"{nation.name}: {len(cards)} 张卡牌")

# 便捷函数
cards = load_nation_cards(Nation.GERMANY)
```

### 🎯 卡牌定义格式

**单位卡完整格式**:
```yaml
unit_cards:
  - id: "unique_card_id"           # 必需：唯一标识符
    template: "unit_card"          # 可选：继承模板
    name: "Card Name"              # 必需：卡牌名称
    cost: 3                        # 必需：费用
    nation: "germany"              # 必需：国家
    rarity: 2                      # 必需：稀有度 (1-4)
    description: "Card description" # 可选：描述
    unit_definition_id: "unit_id"  # 必需：对应单位定义
    
    # 可选参数（如果不使用模板）
    params:
      - name: "deploy_position"
        type: "slot"
        range: [0, 4]
        required: false
```

## 📁 项目结构

```
项目根目录/
├── run_tests.sh              # 测试运行脚本
├── README.md                 # 项目文档
├── demo/                     # 演示文件目录
│   ├── demo_new_features.py  # 最新功能专项演示
│   ├── demo_card_system.py   # 卡牌系统演示
│   ├── demo_parameterized_cards.py # 参数化卡牌演示
│   ├── main.py               # 主入口文件
│   └── DEMOS.md              # 演示文件说明
│
├── examples/                 # 完整示例目录 🆕
│   └── card_system/          # 卡牌系统示例
│       ├── demo_card_system.py      # 卡牌加载和使用示例
│       └── demo_parameterized_cards.py # 参数化卡牌示例
│
├── assets/                   # 游戏资源文件 🆕
│   ├── cards/                # 卡牌定义文件
│   │   ├── cards_spec.yaml   # 卡牌格式规范和模板定义
│   │   ├── germany.yaml      # 德国卡牌 (15+ 张)
│   │   ├── italy.yaml        # 意大利卡牌 (12+ 张)
│   │   ├── usa.yaml          # 美国卡牌 (18+ 张)
│   │   ├── japan.yaml        # 日本卡牌 (23+ 张) 🆕
│   │   └── example_orders.yaml # 示例指令卡
│   └── units/                # 单位定义文件
│       ├── units_spec.yaml   # 单位格式规范
│       ├── germany.yaml      # 德国单位
│       ├── usa.yaml          # 美国单位
│       └── japan.yaml        # 日本单位 🆕
│
├── kards_battle/             # 核心战斗系统包
│   ├── core/                 # 核心引擎和逻辑
│   │   ├── battle_engine.py  # 新战斗引擎
│   │   ├── enums.py         # 枚举定义 (单位类型、战线等)
│   │   └── unit_combat_rules.py # 单位战斗规则
│   ├── cards/               # 卡牌系统 🆕
│   │   ├── card.py          # 卡牌基类和单位卡实现
│   │   ├── card_loader.py   # YAML卡牌加载器 (支持模板继承)
│   │   ├── card_params.py   # 卡牌参数系统
│   │   ├── card_manager.py  # 卡牌管理器
│   │   ├── deck.py          # 卡组管理
│   │   └── placeholder_cards.py # 占位卡牌定义
│   ├── units/               # 单位系统
│   │   ├── unit.py          # 单位基类和实现
│   │   └── unit_loader.py   # 单位加载器
│   ├── game/                # 游戏引擎和状态管理
│   │   ├── game_engine.py   # 高级游戏引擎
│   │   ├── game_state.py    # 游戏状态管理
│   │   └── nation_config.py # 国家配置
│   ├── battlefield/         # 战场管理
│   │   └── battlefield.py   # 基础战场系统
│   ├── abilities/           # 能力和关键词系统
│   │   ├── abilities.py     # 能力基类和接口
│   │   └── keywords.py      # 关键词效果实现
│   ├── effects/            # 效果系统
│   │   ├── effects.py      # 游戏效果实现
│   │   └── target_selectors.py # 目标选择逻辑
│   ├── events/             # 事件系统
│   │   ├── event_system.py # 事件分发器
│   │   └── managers/       # 事件管理器
│   └── examples/           # 示例单位和演示
│       └── sample_units.py # 15个示例单位定义
│
├── interactive/             # 交互式功能 
│   ├── battle_visualizer.py # 战场可视化器
│   ├── command_parser.py    # 命令解析器  
│   ├── interactive_test.py  # 交互测试
│   └── test_scenarios.py   # 测试场景
│
├── docs/                   # 项目文档
│   ├── KARDS_GAME_RULES.md # 游戏规则说明
│   ├── TESTING.md         # 测试说明
│   └── architecture/      # 架构文档
│       └── SYSTEM_DESIGN.md # 系统设计文档
│
└── tests/                  # 完整测试套件
    ├── test_card_loader.py      # 卡牌加载器测试 🆕
    ├── test_card_params.py      # 卡牌参数系统测试 🆕
    ├── test_card_system.py      # 卡牌系统集成测试 🆕
    ├── unit/                    # 单元测试
    ├── integration/             # 集成测试
    ├── examples/               # 示例和用法测试
    └── README.md              # 测试说明文档
```

## 🚀 快速开始

### 真实的KARDS操作体验

```python
from kards_battle.core.battle_engine import BattleEngine
from kards_battle.examples.sample_units import create_american_gi, create_german_infantry
from kards_battle.core.enums import LineType

# 创建战斗引擎 (专注战斗系统，不包含卡牌)
engine = BattleEngine("Germany", "USA", debug_mode=True)

# 创建单位并设置激活成本
german_infantry = create_german_infantry()
american_gi = create_american_gi()
german_infantry.activation_cost = 1
american_gi.activation_cost = 1

print(f"初始状态:")
print(f"德军 - Kredits: {engine.get_kredits('Germany')}, Slot: {engine.get_kredits_slot('Germany')}")
print(f"美军 - Kredits: {engine.get_kredits('USA')}, Slot: {engine.get_kredits_slot('USA')}")

# 第1回合 - 德军直接部署单位到支援线
result1 = engine.deploy_unit_to_support(german_infantry, "Germany")
print(f"德军步兵部署到支援线: {result1['success']}")

# 切换到美军回合 (Kredits Slot自动增长)
engine.end_turn()
print(f"美军回合 - Kredits: {engine.get_kredits('USA')}, Slot: {engine.get_kredits_slot('USA')}")

# 第2回合 - 美军部署并移动
result2 = engine.deploy_unit_to_support(american_gi, "USA")
print(f"美军GI部署到支援线: {result2['success']}")

# 美军移动GI到前线 (消耗1点Kredits激活费用)
move_result = engine.move_unit(american_gi.id, (LineType.FRONT, 0), "USA")
print(f"美军GI移动到前线: {move_result['success']}")
if move_result['success']:
    print(f"前线控制权: {move_result['front_line_controller']}")

print(f"美军剩余Kredits: {engine.get_kredits('USA')}")

# 第3回合 - 德军反击
engine.end_turn()
print(f"德军回合 - Kredits: {engine.get_kredits('Germany')}")

# 德军从支援线攻击前线的美军 (消耗1点Kredits激活费用)
attack_result = engine.attack_target(german_infantry.id, american_gi.id, "Germany")
print(f"德军攻击美军: {attack_result['success']}")
if attack_result['success']:
    print(f"造成伤害: {attack_result['damage_dealt']}, 反击伤害: {attack_result['counter_damage']}")

# 查看最终战场状态
print(f"\n最终战场:")
print(engine.battlefield)

# DEBUG功能演示 - 设置资源和属性
engine.debug_set_kredits("Germany", kredits=10)
engine.debug_set_unit_stats(german_infantry.id, attack=5, defense=8)
print(f"\nDEBUG: 德军Kredits设为10，步兵属性增强为 5/8")
```

### 运行演示

```bash
# 最新功能演示 (推荐先运行)
python3 demo/demo_new_features.py

# 主程序入口
python3 demo/main.py
```

### 运行测试

```bash
# 🧪 运行pytest测试套件（推荐）
./run_pytest.sh                                    # 运行所有pytest测试（19个）

# 或分别运行
uv run pytest tests/test_comprehensive_movement.py -v  # 移动系统测试（10个）
uv run pytest tests/test_turn_and_resources.py -v      # 回合资源测试（9个）

# 🔧 运行传统测试套件
./run_tests.sh                                     # 旧版测试运行器

# 特定测试类别
python3 tests/unit/test_battle_engine.py           # 新战斗引擎测试
python3 tests/unit/test_unit_type_rules.py         # 单位类型规则测试
python3 tests/integration/test_system.py          # 系统集成测试
```

**推荐使用pytest套件 - 覆盖所有核心功能的完整验证！**

## 🔧 扩展系统

### 创建自定义单位

```python
from kards_battle.units.unit import Unit
from kards_battle.core.enums import UnitType

# 创建基础单位
custom_unit = Unit(
    name="Custom Tank",
    unit_type=UnitType.TANK,
    attack=4,
    defense=5,
    operation_cost=4,
    keywords={"BLITZ", "HEAVY_ARMOR_1"}
)
```

### 创建自定义能力

```python
from kards_battle.abilities.abilities import DeployAbility

class CustomDeployAbility(DeployAbility):
    def get_valid_targets(self, owner, battlefield):
        # 实现目标选择逻辑
        return []
    
    def execute(self, owner, battlefield, target=None, context=None):
        # 实现能力效果
        return {"success": True}
```

### 创建自定义关键词

```python
from kards_battle.abilities.keywords import KeywordEffect, TriggerTiming

class CustomKeyword(KeywordEffect):
    def get_trigger_timing(self):
        return [TriggerTiming.ON_DEPLOY]
    
    def _execute_effect(self, owner, battlefield, timing, context):
        # 实现关键词效果
        pass
```

## 📊 示例单位

系统包含15个示例单位，展示各种能力组合：

**德军**:
- Panzer IV (闪击坦克)
- Panther Tank (重甲坦克)  
- Bf 109 (伏击战斗机)
- Ju 87 Stuka (轰炸机)
- German 88mm Gun (部署伤害火炮)

**美军**:
- M4 Sherman (闪击坦克)
- P-51 Mustang (奋战战斗机)
- B-17 Flying Fortress (重型轰炸机)
- Field Officer (增益光环)

**特殊单位**:
- Elite Sniper (烟幕+动员)

- Combat Medic (死亡治疗)
- Kamikaze Pilot (牺牲攻击)

## 🔄 游戏流程

1. **玩家回合**: 可自由进行以下操作
   - 直接部署单位到己方支援线（不需要卡牌）
   - 移动单位（支援线→前线，消耗Kredits激活费用）
   - 攻击敌方目标（消耗Kredits激活费用）
2. **回合结束**: 切换玩家，Kredits Slot自动增长，Kredits重置为Slot数值
3. **胜利条件**: 摧毁敌方HQ（20→0防御值）

### 💰 Kredits资源系统
- **Kredits Slot**: 每回合自增1（上限12），代表"钱包容量"
- **Kredits**: 每回合重置为Slot数值，当前可用"资源"  
- **激活费用**: 移动和攻击都需要消耗单位的activation_cost点Kredits

### 🎮 核心操作机制
- **直接部署**: `deploy_unit_to_support()` - 将单位部署到己方支援线
- **移动单位**: `move_unit()` - 从支援线移动到前线（包括挤位置）
- **攻击目标**: `attack_target()` - 攻击敌方单位或HQ
- **DEBUG功能**: 调试模式下可直接编辑单位属性和玩家资源

## 🧪 测试结果

系统通过了以下测试：

✅ **纯战斗系统**: 专注战斗机制，不包含卡牌系统 🆕  
✅ **Kredits资源系统**: Kredits Slot/Kredits双层资源管理 🆕  
✅ **直接单位部署**: 函数调用直接部署到支援线 🆕  
✅ **DEBUG功能系统**: 完整的调试和编辑功能 🆕  
✅ **真实的3条战线布局**  
✅ **HQ作为支援线上的目标**  
✅ **单位自动紧凑排列**  
✅ **前线控制权动态更新**  
✅ **前线内挤位置机制**  
✅ **跨线攻击规则**  
✅ **完整的单位类型战斗规则** 🆕  
✅ **火炮和轰炸机不受反击**  
✅ **轰炸机被战斗机保护机制**    
✅ **关键词效果触发** (伏击、重甲等)  
✅ **战斗伤害计算和反击**  
✅ **游戏状态管理**  

## 🎯 后续扩展方向

- [ ] AI对手实现
- [ ] 完整的卡牌系统
- [ ] 资源管理系统  
- [ ] 图形用户界面
- [ ] 网络对战功能
- [ ] 更多单位和能力
- [ ] 保存/加载游戏
- [ ] 战斗回放系统

## 🏆 设计亮点

### 真实战场还原
- **3条战线布局**: 完全符合KARDS真实游戏规则
- **紧凑排列机制**: 单位自动填补空隙，无碎片化
- **前线控制权**: 动态计算和更新控制权状态
- **HQ作为目标**: 总部正确放置在支援线上

### 可扩展架构
- **组件模式**: 单位通过组合关键词和能力构建
- **策略模式**: 不同能力实现为独立策略类  
- **事件驱动**: 所有游戏逻辑通过事件触发
- **工厂模式**: 关键词和效果可动态创建

### 高度模块化
- 核心系统与具体内容分离
- 每个模块职责单一，低耦合
- 便于单独测试和扩展

### 真实游戏机制
- 完整复现KARDS核心规则
- 准确的单位类型和特殊规则
- 详细的关键词效果实现

---

*基于KARDS: The WWII Card Game设计，用于学习和AI研究目的*