/**
 * tower_defence.aigameplay — reducer 接口模板
 *
 * Agent 生成实际 reducer 时，必须导出以下函数。
 * 此文件是接口约束模板，不是可执行代码。
 *
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
 *
 * 塔防游戏的核心是固定帧率的游戏循环（tickGameLoop），
 * 渲染层必须每帧（或每 tickRateMs）调用 tickGameLoop，
 * 然后根据返回的 lastAttackEvents/lastDeathEvents/lastEscapeEvents
 * 播放对应的视觉效果（攻击特效、死亡动画、逃跑动画）。
 *
 * 不要在每帧全量重建所有精灵——只更新有变化的对象。
 *
 * dispatch() 的用途：无头测试、AI 模拟、关卡预演等场景。
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 */

// ─── 配置类型 ─────────────────────────────────────────────────────────────────

export type TowerDefenceConfig = {
  /** 初始生命值，默认 20 */
  initialLives: number;
  /** 初始金币，默认 150 */
  initialGold: number;
  /** 游戏逻辑帧率（毫秒/帧），默认 100 */
  tickRateMs: number;
  /** 地图格子数组（宽×高） */
  gridWidth: number;
  gridHeight: number;
  /** 敌人路径坐标序列 */
  path: Vector2[];
  /** 波次定义列表 */
  waves: WaveDefinition[];
};

// ─── 核心类型 ─────────────────────────────────────────────────────────────────

export type Vector2 = { x: number; y: number };
export type CellType = 'path' | 'buildable' | 'occupied' | 'empty';

export type TowerType = 'arrow' | 'cannon' | 'magic';
export type EnemyType = 'basic' | 'fast' | 'armored' | 'boss';

export type TowerStats = {
  damage: number;
  range: number;        // 攻击范围（格子数）
  attackSpeed: number;  // 攻击间隔（毫秒）
  cost: number;
  upgradeCost: number;
  sellValue: number;
  splashRadius: number; // 范围伤害半径（仅 cannon > 0）
  slowFactor: number;   // 减速因子（仅 magic < 1.0，其他为 1.0）
  slowDurationMs: number;
};

export type Tower = {
  id: string;
  type: TowerType;
  position: Vector2;
  level: 1 | 2 | 3;
  stats: TowerStats;
  lastAttackMs: number;  // 上次攻击的游戏时间戳
};

export type Enemy = {
  id: string;
  type: EnemyType;
  hp: number;
  maxHp: number;
  speed: number;       // 格子/秒
  pathIndex: number;   // 当前目标路径点索引
  progress: number;    // 到下一路径点的进度 [0, 1)
  position: Vector2;   // 当前插值位置（用于渲染）
  reward: number;      // 击杀奖励金币
  armor: number;       // 装甲减伤百分比 [0, 1)
  slowUntilMs: number; // 减速效果结束时间戳
  alive: boolean;
};

export type WaveDefinition = {
  enemies: Array<{ type: EnemyType; count: number }>;
  spawnIntervalMs: number;  // 每个敌人之间的生成间隔
};

// ─── 动作类型 ─────────────────────────────────────────────────────────────────

export type TowerDefenceAction =
  | { type: 'place_tower'; position: Vector2; towerType: TowerType }
  | { type: 'upgrade_tower'; towerId: string }
  | { type: 'sell_tower'; towerId: string }
  | { type: 'tick'; deltaMs: number }   // 游戏循环帧
  | { type: 'start_wave' }              // 开始下一波次
  | { type: 'reset' };

// ─── 状态类型 ─────────────────────────────────────────────────────────────────

export type TowerDefenceState = {
  grid: CellType[][];        // grid[x][y]
  path: Vector2[];
  towers: Tower[];
  enemies: Enemy[];
  resources: { gold: number; lives: number };
  waves: {
    waveIndex: number;
    totalWaves: number;
    waveInProgress: boolean;
    spawnQueue: Array<{ type: EnemyType; count: number }>;
    lastSpawnMs: number;
    spawnIntervalMs: number;
  };
  currentTimeMs: number;   // 游戏逻辑时间（累计毫秒）
  gameOver: boolean;
  win: boolean;
  /** 本帧攻击事件（渲染层播放特效） */
  lastAttackEvents: AttackEvent[];
  /** 本帧死亡事件（渲染层播放死亡动画） */
  lastDeathEvents: DeathEvent[];
  /** 本帧逃跑事件（渲染层扣血UI） */
  lastEscapeEvents: EscapeEvent[];
};

// ─── 事件类型（渲染层驱动） ──────────────────────────────────────────────────

export type AttackEvent = {
  towerId: string;
  towerType: TowerType;
  targetEnemyId: string;
  damage: number;
  isSplash: boolean;
  splashTargets?: string[];  // cannon 范围伤害的其他目标 id
  appliedSlow: boolean;      // magic 是否施加了减速
};

export type DeathEvent = {
  enemyId: string;
  enemyType: EnemyType;
  position: Vector2;
  reward: number;
};

export type EscapeEvent = {
  enemyId: string;
  livesAfter: number;
};

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// 必须导出的函数
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

// ─── 初始化 ──────────────────────────────────────────────────────────────────

/**
 * init：根据关卡配置初始化游戏状态
 */
export declare function init(config: TowerDefenceConfig): TowerDefenceState;

// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────

/**
 * dispatch：接收动作，返回新状态（纯函数）
 * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
 */
export declare function dispatch(state: TowerDefenceState, action: TowerDefenceAction): TowerDefenceState;

/**
 * getState：返回当前状态快照
 */
export declare function getState(state: TowerDefenceState): TowerDefenceState;

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// 分步函数（渲染层/场景层必须使用这些函数）
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

/**
 * placeTower：在指定格子放置防御塔
 * 验证：格子为 buildable、金币充足
 * 若不合法则返回原 state（不抛出异常）
 *
 * 渲染层在玩家点击放塔时调用，若 state 发生变化则创建新塔精灵
 */
export declare function placeTower(
  state: TowerDefenceState,
  position: Vector2,
  towerType: TowerType,
): TowerDefenceState;

/**
 * upgradeTower：升级指定防御塔
 * 验证：塔存在、level < 3、金币充足
 * 升级后 damage × 1.5，range += 0.5
 *
 * 渲染层调用后更新塔精灵的视觉
 */
export declare function upgradeTower(
  state: TowerDefenceState,
  towerId: string,
): TowerDefenceState;

/**
 * tickGameLoop：执行一个完整的游戏逻辑帧
 * 按顺序执行：波次生成 → 敌人移动 → 逃跑检测 → 塔攻击 → 死亡结算 → 胜负检测
 * 返回含 lastAttackEvents/lastDeathEvents/lastEscapeEvents 的新状态
 *
 * 渲染层每帧调用（或按 tickRateMs 节流调用）
 */
export declare function tickGameLoop(
  state: TowerDefenceState,
  deltaMs: number,
): TowerDefenceState;

/**
 * processAttacks：仅执行塔的攻击阶段（不移动敌人，不生成波次）
 * 渲染层可用于精细控制各步骤的执行顺序
 */
export declare function processAttacks(
  state: TowerDefenceState,
): TowerDefenceState;

/**
 * moveEnemies：仅执行敌人移动阶段
 * - 敌人按速度（含减速）沿路径推进
 * - 到达出口的敌人触发逃跑事件
 * - 更新所有敌人的插值位置（供渲染层同步精灵）
 */
export declare function moveEnemies(
  state: TowerDefenceState,
  deltaMs: number,
): TowerDefenceState;

/**
 * spawnNextWave：手动触发下一波次生成（若上一波已结束）
 * 更新 waves.waveIndex，初始化 spawnQueue
 */
export declare function spawnNextWave(
  state: TowerDefenceState,
): TowerDefenceState;