kards-env/docs/ENGINE_API_REFERENCE.md

# KARDS 战斗引擎API接口文档

## 1. 核心引擎类 - BattleEngine

### 1.1 初始化
```python
class BattleEngine:
    def __init__(self, player1_name: str, player2_name: str, debug_mode: bool = False)
```
**参数**:
- `player1_name`: 玩家1名称
- `player2_name`: 玩家2名称  
- `debug_mode`: 调试模式开关

**返回**: BattleEngine实例

---

## 2. 单位部署接口

### 2.1 部署单位到支援线
```python
def deploy_unit_to_support(self, unit: Unit, player_id: int, position: Optional[int] = None) -> Dict[str, Any]
```
**参数**:
- `unit`: 要部署的单位对象
- `player_id`: 玩家ID (0或1)
- `position`: 可选的部署位置，None则自动添加到末尾

**返回**: 
```python
{
    "success": bool,
    "action": "deploy_to_support",
    "unit_id": UUID,
    "player": int,
    "position": int,
    "reason": str  # 失败时提供原因
}
```

**规则验证**:
- 检查玩家ID有效性
- 检查支援线是否已满
- 自动设置单位所有者
- 单位默认`deployed_this_turn = True`

---

## 3. 单位操作接口

### 3.1 移动单位
```python
def move_unit(self, unit_id: UUID, target_position: tuple, player_id: int) -> Dict[str, Any]
```
**参数**:
- `unit_id`: 单位的唯一标识符
- `target_position`: 目标位置 (line_type, index)
- `player_id`: 执行操作的玩家ID

**返回**:
```python
{
    "success": bool,
    "action": "move",
    "unit_id": UUID,
    "from": tuple,
    "to": tuple,
    "reason": str  # 失败时提供原因
}
```

**限制检查**:
- 回合验证: `player_id == active_player`
- 所有权验证: `unit.owner == player_names[player_id]`
- 移动能力: `unit.can_move()`
- 费用检查: `spend_kredits(player_id, unit.stats.operation_cost)`
- 成功后: `unit.perform_move()`

### 3.2 攻击目标
```python
def attack_target(self, attacker_id: UUID, target_id: Union[UUID, str], player_id: int) -> Dict[str, Any]
```
**参数**:
- `attacker_id`: 攻击者单位ID
- `target_id`: 目标单位ID或HQ标识符
- `player_id`: 执行操作的玩家ID

**返回**:
```python
{
    "success": bool,
    "action": "attack",
    "attacker_id": UUID,
    "target_id": Union[UUID, str],
    "combat_resolved": bool,
    "damage_dealt": int,
    "counter_damage": int,
    "target_destroyed": bool,
    "attacker_destroyed": bool,
    "reason": str  # 失败时提供原因
}
```

**限制检查**:
- 回合验证和所有权验证同移动
- 攻击能力: `unit.can_attack()`
- 费用检查: `spend_kredits(player_id, unit.stats.operation_cost)`
- 攻击规则: `UnitCombatRules.can_attack_target()`
- 成功后: `unit.perform_attack()`

---

## 4. 回合管理接口

### 4.1 结束回合
```python
def end_turn(self) -> Dict[str, Any]
```
**返回**:
```python
{
    "success": bool,
    "action": "end_turn",
    "previous_player": int,
    "new_active_player": int,
    "new_turn": int,
    "new_phase": int
}
```

**执行流程**:
1. 切换`active_player`: `(self.active_player + 1) % 2`
2. 更新`turn_phase`: `(self.turn_phase + 1) % 2`
3. 如果`turn_phase == 0`: `current_turn += 1`
4. 调用`_start_player_turn()`更新资源
5. 重置所有单位状态: `unit.start_new_turn()`

---

## 5. 资源管理接口

### 5.1 获取Kredits
```python
def get_kredits(self, player_id: int) -> int
def get_kredits_slot(self, player_id: int) -> int
```

### 5.2 消耗Kredits
```python
def spend_kredits(self, player_id: int, amount: int) -> bool
```
**规则**:
- 检查`current_kredits >= amount`
- 成功则减少相应数量
- 失败则不消耗，返回False

### 5.3 Kredits系统规则
- **Kredits Slot**: 每回合自然增长+1，上限12
- **Kredits**: 每回合重置为当前Slot数
- **激活费用**: 移动和攻击消耗`unit.stats.operation_cost`

---

## 6. 游戏状态接口

### 6.1 获取完整游戏状态
```python
def get_game_state(self) -> Dict[str, Any]
```
**返回**:
```python
{
    "turn": int,
    "turn_phase": int,
    "active_player": int,
    "kredits": {
        "player1": int,
        "player2": int,
        "active_player": int
    },
    "kredits_slots": {
        "player1": int,
        "player2": int,
        "active_player": int
    },
    "battlefield": str,
    "player1_hq": int,
    "player2_hq": int,
    "front_line_controller": str,
    "units_count": {
        "player1_total": int,
        "player2_total": int,
        "front_line": int
    },
    "debug_mode": bool
}
```

---

## 7. 调试接口

### 7.1 设置单位属性
```python
def debug_set_unit_stats(self, unit_id: UUID, attack: Optional[int] = None, 
                        defense: Optional[int] = None, current_defense: Optional[int] = None) -> Dict[str, Any]
```

### 7.2 设置Kredits
```python
def debug_set_kredits(self, player_id: int, kredits: Optional[int] = None, 
                     slot: Optional[int] = None) -> Dict[str, Any]
```

### 7.3 设置HQ防御
```python
def debug_set_hq_defense(self, player_id: int, defense: int) -> Dict[str, Any]
```

**注意**: 调试接口不执行规则验证，仅用于测试环境

---

## 8. 战斗规则接口 - UnitCombatRules

### 8.1 攻击目标验证
```python
@staticmethod
def can_attack_target(attacker: Unit, target: Union[Unit, HQ], battlefield: Battlefield) -> bool
```

### 8.2 反击检查
```python
@staticmethod
def can_counter_attack(defender: Unit, attacker: Unit) -> bool
```

### 8.3 守护保护检查
```python
@staticmethod
def is_protected_by_guard(target: Union[Unit, HQ], battlefield: Battlefield) -> bool

@staticmethod
def can_ignore_guard(attacker: Unit) -> bool
```

### 8.4 获取有效攻击目标
```python
@staticmethod
def get_valid_targets(attacker: Unit, battlefield: Battlefield) -> List[Union[Unit, HQ]]
```

**规则实现**:
- 步兵/坦克: 相邻阵线攻击规则
- 火炮: 无视距离和守护
- 战斗机: 无视距离
- 轰炸机: 无视距离和守护，受战斗机保护限制

---

## 9. 单位状态接口 - Unit

### 9.1 行动能力检查
```python
def can_move(self) -> bool
def can_attack(self) -> bool
```

**检查逻辑**:
```python
# 部署限制
if self.deployed_this_turn and not self.can_operate_immediately:
    return False

# 移动检查
if self.has_moved_this_turn:
    return False (for move)

# 攻击检查  
if self.attacks_this_turn >= self.max_attacks_per_turn:
    return False (for attack)

# 移动攻击互斥
if self.has_moved_this_turn and not self.can_move_and_attack:
    return False (for attack)
if self.has_attacked_this_turn and not self.can_move_and_attack:
    return False (for move)
```

### 9.2 行动执行
```python
def perform_move(self) -> None
def perform_attack(self) -> None
def start_new_turn(self) -> None
```

### 9.3 关键词应用
```python
def apply_keyword_abilities(self) -> None
```
**实现映射**:
- `BLITZ` → `can_operate_immediately = True`
- `TANK` → `can_move_and_attack = True`
- `FURY` → `max_attacks_per_turn = 2`

---

## 10. 交互式命令接口 - CommandParser

### 10.1 命令映射
```python
commands = {
    # 显示命令
    'show': cmd_show,        # 显示战场状态
    'list': cmd_list,        # 列出可用单位
    'info': cmd_info,        # 查看单位详情
    
    # 单位操作
    'deploy': cmd_deploy,    # 部署单位
    'move': cmd_move,        # 移动单位
    'attack': cmd_attack,    # 攻击目标
    
    # 游戏控制
    'endturn': cmd_endturn,  # 结束回合
    'reset': cmd_reset,      # 重置战场
    'switch': cmd_switch,    # 切换活动玩家
    
    # 资源管理
    'kredits': cmd_kredits,  # 查看资源
    'setk': cmd_set_kredits, # 设置Kredits
    'sets': cmd_set_slot,    # 设置Slot
}
```

### 10.2 简化语法支持
- **移动命令**: `move <from_pos> <to_pos>`
- **攻击命令**: `attack <from> <to>` 支持 `F0 S1` 简化格式
- **位置解析**: 自动转换 `F0` → `(LineType.FRONT, 0)`

---

## 11. API一致性约定

### 11.1 返回值格式
所有操作API都返回包含以下字段的字典:
- `success: bool` - 操作是否成功
- `action: str` - 操作类型标识
- `reason: str` - 失败时的原因描述（可选）

### 11.2 错误处理
- **参数验证**: 无效参数返回 `{"success": False, "reason": "详细错误信息"}`
- **权限检查**: 非当前玩家操作返回权限错误
- **状态验证**: 不符合游戏规则的操作返回规则错误
- **费用检查**: Kredits不足返回资源不足错误

### 11.3 ID系统
- **单位ID**: 使用UUID系统，全局唯一
- **玩家ID**: 使用整数0/1表示，对应player1/player2
- **位置系统**: 使用 `(LineType, int)` 元组表示位置

### 11.4 状态管理
- **原子操作**: 所有API操作都是原子性的，失败时不改变游戏状态
- **状态一致性**: 操作成功后立即更新相关状态
- **事件触发**: 重要操作会触发相应的游戏事件

---

*此文档涵盖了KARDS战斗引擎的所有主要API接口，确保了接口的一致性和可用性。*