369 lines
8.7 KiB
Markdown
369 lines
8.7 KiB
Markdown
# 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接口，确保了接口的一致性和可用性。* |