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

8.7 KiB
Raw Permalink Blame History

KARDS 战斗引擎API接口文档

1. 核心引擎类 - BattleEngine

1.1 初始化

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 部署单位到支援线

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则自动添加到末尾

返回:

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

规则验证:

  • 检查玩家ID有效性
  • 检查支援线是否已满
  • 自动设置单位所有者
  • 单位默认deployed_this_turn = True

3. 单位操作接口

3.1 移动单位

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

返回:

{
    "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 攻击目标

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

返回:

{
    "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 结束回合

def end_turn(self) -> Dict[str, Any]

返回:

{
    "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

def get_kredits(self, player_id: int) -> int
def get_kredits_slot(self, player_id: int) -> int

5.2 消耗Kredits

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 获取完整游戏状态

def get_game_state(self) -> Dict[str, Any]

返回:

{
    "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 设置单位属性

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

def debug_set_kredits(self, player_id: int, kredits: Optional[int] = None, 
                     slot: Optional[int] = None) -> Dict[str, Any]

7.3 设置HQ防御

def debug_set_hq_defense(self, player_id: int, defense: int) -> Dict[str, Any]

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

8. 战斗规则接口 - UnitCombatRules

8.1 攻击目标验证

@staticmethod
def can_attack_target(attacker: Unit, target: Union[Unit, HQ], battlefield: Battlefield) -> bool

8.2 反击检查

@staticmethod
def can_counter_attack(defender: Unit, attacker: Unit) -> bool

8.3 守护保护检查

@staticmethod
def is_protected_by_guard(target: Union[Unit, HQ], battlefield: Battlefield) -> bool

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

8.4 获取有效攻击目标

@staticmethod
def get_valid_targets(attacker: Unit, battlefield: Battlefield) -> List[Union[Unit, HQ]]

规则实现:

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

9. 单位状态接口 - Unit

9.1 行动能力检查

def can_move(self) -> bool
def can_attack(self) -> bool

检查逻辑:

# 部署限制
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 行动执行

def perform_move(self) -> None
def perform_attack(self) -> None
def start_new_turn(self) -> None

9.3 关键词应用

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 命令映射

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接口，确保了接口的一致性和可用性。