# KARDS 卡牌YAML格式规范
# 
# 本文件定义了KARDS游戏中卡牌的YAML格式规范
# 包含单位卡、指令卡、反制卡的完整定义格式

# ==================== 卡牌基础属性 ====================
# 所有卡牌共有的基础属性：
# - id: 卡牌唯一标识符
# - name: 卡牌名称（中文）
# - type: 卡牌类型（unit/order/countermeasure）
# - cost: 费用（Kredits）
# - nation: 所属国家
# - rarity: 稀有度（1-4级，对应游戏中的星级）
# - description: 卡牌描述

# ==================== 卡牌模板系统 ====================
# 定义可继承的卡牌模板，减少重复配置
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)"

# ==================== 单位卡格式 ====================
unit_cards:
  - id: "ger_infantry_grenadier_card"
    name: "German Grenadier"
    type: "unit"
    cost: 2
    nation: "germany"
    rarity: 2
    description: "Experienced German infantry equipped with grenades"
    
    # 单位卡特有属性
    unit_definition_id: "ger_infantry_grenadier"  # 对应units.yaml中的单位定义
    
    # 可选属性
    exile_nations: ["italy", "romania"]  # 流亡国家（小国专用）
    deploy_to: ["support"]  # 可部署位置：support/frontline/hq
    
    # 卡牌参数（新增）
    params:
      - name: "position"
        type: "slot"
        range: [0, 4]
        required: false
        description: "Deploy position"
    
    # 卡牌效果（可选）
    card_effects:
      - type: "deploy"
        description: "Heal 1 HP on deploy"
        effect:
          target: "self"
          action: "heal"
          value: 1
      
      - type: "passive" 
        description: "Gain +1 attack at turn start"
        effect:
          trigger: "turn_start"
          target: "self"
          action: "buff_attack"
          value: 1

  # 更多单位卡示例
  - id: "ger_tank_panzer_iv_card"
    name: "四号坦克D型"
    type: "unit"
    cost: 4
    nation: "germany"
    rarity: 3
    description: "德军主力中型坦克"
    unit_definition_id: "ger_tank_panzer_iv"
    deploy_to: ["support", "frontline"]

# ==================== 指令卡格式 ====================  
order_cards:
  - id: "blitzkrieg_assault"
    name: "Blitzkrieg Assault"
    type: "order"
    cost: 2
    nation: "germany"
    rarity: 3
    description: "Select a friendly unit, gain +2 attack and first strike this turn"
    
    # 指令卡参数
    params:
      - name: "target"
        type: "unit_target"
        valid_zones: ["O", "F"]
        filter: "friendly"
        required: true
        description: "Select friendly unit to buff"
    
    # 指令效果
    order_effects:
      - target: "selected_unit"
        action: "buff_attack"
        value: 2
        duration: "this_turn"
      - target: "selected_unit" 
        action: "add_keyword"
        value: "first_strike"
        duration: "this_turn"

  - id: "precision_strike"
    name: "Precision Strike"
    type: "order"
    cost: 3
    nation: "usa"
    rarity: 3
    description: "Destroy target enemy unit"
    
    params:
      - name: "target"
        type: "unit_target"
        valid_zones: ["E", "F"]
        filter: "enemy"
        required: true
        description: "Select enemy unit to destroy"
    
    order_effects:
      - target: "selected_unit"
        action: "destroy"

  - id: "area_bombardment"
    name: "Area Bombardment"
    type: "order"
    cost: 4
    nation: "usa"
    rarity: 4
    description: "Deal 2 damage to up to 3 enemy units"
    
    params:
      - name: "targets"
        type: "multi_unit_target"
        valid_zones: ["E", "F"]
        filter: "enemy"
        min_count: 1
        max_count: 3
        required: true
        description: "Select up to 3 enemy units"
    
    order_effects:
      - target: "selected_units"
        action: "damage"
        value: 2

  - id: "tactical_redeployment"
    name: "Tactical Redeployment"
    type: "order"
    cost: 2
    nation: "germany"
    rarity: 2
    description: "Move friendly unit to new position"
    
    params:
      - name: "unit"
        type: "unit_target"
        valid_zones: ["O", "F"]
        filter: "friendly"
        required: true
        description: "Select unit to move"
      - name: "destination"
        type: "position"
        valid_zones: ["O", "F"]
        must_be_empty: true
        required: true
        description: "Select destination"
    
    order_effects:
      - target: "selected_unit"
        action: "move"
        destination: "selected_position"

  - id: "supply_drop"
    name: "Supply Drop"
    type: "order"
    cost: 1
    nation: "usa"
    rarity: 1
    description: "Gain +2 Kredits this turn"
    
    params: []  # 无参数，直接生效
    
    order_effects:
      - target: "current_player"
        action: "add_kredits"
        value: 2

# ==================== 反制卡格式 ====================
countermeasure_cards:
  - id: "anti_aircraft_fire"
    name: "Anti-Aircraft Fire"
    type: "countermeasure"
    cost: 1
    nation: "germany"
    rarity: 2
    description: "When enemy air unit attacks, deal 1 damage to it"
    
    # 反制卡触发条件
    trigger_conditions:
      - type: "unit_attacks"
        filter: "air_unit"
        source: "enemy"
    
    # 反制卡可选参数（触发时可选择目标）
    params:
      - name: "intercept_with"
        type: "unit_target"
        valid_zones: ["O"]
        filter: "friendly"
        unit_type_filter: ["fighter"]
        required: false
        description: "Optional: Select fighter to intercept with"
    
    # 反制效果
    counter_effects:
      - target: "attacking_unit"
        action: "damage"
        value: 1
        timing: "before_combat"

  - id: "fortified_position"
    name: "Fortified Position"
    type: "countermeasure" 
    cost: 2
    nation: "soviet"
    rarity: 3
    description: "When friendly unit is attacked, give it +1 defense"
    
    trigger_conditions:
      - type: "unit_attacked"
        filter: "friendly_unit"
    
    params: []  # 无参数，自动对被攻击单位生效
    
    counter_effects:
      - target: "defending_unit"
        action: "buff_defense"
        value: 1
        timing: "during_combat"

  - id: "strategic_reserves"
    name: "Strategic Reserves"
    type: "countermeasure"
    cost: 3
    nation: "uk"
    rarity: 3
    description: "When frontline is breached, deploy unit from hand"
    
    trigger_conditions:
      - type: "frontline_breached"
    
    params:
      - name: "unit_to_deploy"
        type: "choice"
        choices: []  # 动态生成可部署单位选项
        required: true
        description: "Select unit from hand to deploy"
      - name: "deploy_position"
        type: "position"
        valid_zones: ["O"]
        must_be_empty: true
        required: true
        description: "Select deployment position"
    
    counter_effects:
      - target: "selected_unit"
        action: "deploy_from_hand"
        position: "selected_position"

# ==================== 特殊属性说明 ====================
# 
# nation 国家代码:
# - germany, italy, romania, hungary, finland, japan
# - usa, uk, soviet, france, poland, norway, belgium, netherlands
# 
# rarity 稀有度:
# - 1: 普通 (白色)
# - 2: 常见 (绿色) 
# - 3: 稀有 (蓝色)
# - 4: 史诗 (紫色)
#
# deploy_to 部署位置:
# - support: 支援线
# - frontline: 前线
# - hq: 总部
#
# target_type 目标类型:
# - friendly_unit: 友军单位
# - enemy_unit: 敌军单位
# - any_unit: 任意单位
# - friendly_hq: 友方总部
# - enemy_hq: 敌方总部
# - battlefield: 整个战场
#
# action 效果动作:
# - damage: 造成伤害
# - heal: 恢复生命
# - buff_attack: 增加攻击力
# - buff_defense: 增加防御力
# - add_keyword: 添加关键词
# - remove_keyword: 移除关键词
# - move: 移动单位
# - destroy: 摧毁单位
# 
# timing 时机:
# - before_combat: 战斗前
# - during_combat: 战斗中
# - after_combat: 战斗后
# - deploy: 部署时
# - turn_start: 回合开始
# - turn_end: 回合结束

# ==================== 卡组构建规则 ====================
# 1. 每个卡组包含39张卡牌
# 2. 每张相同卡牌最多4张（根据稀有度限制）
# 3. 主国卡牌：27张（69%）
# 4. 盟国卡牌：12张（31%）
# 5. 流亡卡牌：小国卡牌可以在特定主国卡组中使用
# 6. 费用分布建议：
#    - 1费：8-12张
#    - 2费：12-16张  
#    - 3费：8-12张
#    - 4费+：4-8张