/**
 * left_right_parkour.aigameplay — reducer 接口模板
 *
 * Agent 生成实际 reducer 时，必须导出以下函数。
 * 此文件是接口约束模板，不是可执行代码。
 *
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
 *
 * dispatch() 是一体化接口，内部执行完整的选择+效果应用+状态检测后只返回最终状态，
 * 中间过程（门板穿越动画、属性浮动文字、生命值变化特效）全部丢失。
 *
 * 渲染层需要在每个步骤间播放相应动画，因此必须使用下方「分步函数」。
 *
 * dispatch() 的用途：无头测试、AI 模拟、关卡预演分析。
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 */

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

export type GateEffect = {
  /** 得分变化（正=加分，负=扣分） */
  score: number;
  /** 生命值变化（正=加命，负=扣命） */
  lives: number;
  /** 速度倍率变化（正=提速，负=减速，如 +0.1） */
  speed: number;
  /** 获得的道具（null 表示无道具） */
  item: string | null;
};

export type GateOption = {
  /** 门板显示文字（如 '+100分'、'-1命'） */
  label: string;
  /** 选择此选项的效果 */
  effect: GateEffect;
};

export type Gate = {
  /** 门板唯一索引 */
  id: number;
  /** 左门选项 */
  left_option: GateOption;
  /** 右门选项 */
  right_option: GateOption;
};

export type ParkourConfig = {
  /** 关卡中的门板列表（按顺序排列） */
  gates: Gate[];
  /** 初始生命值，默认 3 */
  initialLives: number;
  /** 初始得分，默认 0 */
  initialScore: number;
  /** 初始速度倍率，默认 1.0 */
  initialSpeed: number;
  /** 胜利时的分数加成（可选，如距离奖励） */
  finishBonusScore?: number;
};

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

export type ParkourAction =
  | { type: 'choose'; direction: 'left' | 'right' }
  | { type: 'reset' };

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

export type Runner = {
  /** 已通过的门板数量（当前所在位置） */
  position: number;
  /** 当前累计得分 */
  score: number;
  /** 当前剩余生命值 */
  lives: number;
  /** 当前速度倍率 */
  speed: number;
  /** 已收集的道具列表 */
  items: string[];
};

export type GamePhase = 'running' | 'game_over' | 'win';

export type ParkourState = {
  /** 跑酷角色状态 */
  runner: Runner;
  /** 所有门板配置 */
  gates: Gate[];
  /** 当前待通过的门板索引 */
  currentGateIndex: number;
  /** 游戏阶段 */
  gameState: GamePhase;
  /** 最终得分（游戏结束后计算，运行中为 null） */
  finalScore: number | null;
};

// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────

/** applyGateChoice 返回值（含效果详情，供渲染层播放动画） */
export type GateChoiceResult = {
  /** 更新后的游戏状态 */
  state: ParkourState;
  /** 本次选择应用的效果 */
  appliedEffect: GateEffect;
  /** 选择方向 */
  direction: 'left' | 'right';
  /** 是否因此导致生命值归零（触发 game over 动画） */
  causedGameOver: boolean;
};

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

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

/**
 * init：根据配置初始化游戏状态
 */
export declare function init(config: ParkourConfig): ParkourState;

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

/**
 * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
 * - choose：选择当前门板的左/右选项，应用效果，检测生命值和完成条件
 * - reset：重置到初始状态
 *
 * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
 */
export declare function dispatch(state: ParkourState, action: ParkourAction): ParkourState;

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

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

/**
 * applyGateChoice：应用指定门板的选择效果，更新 runner 属性。
 *
 * 场景层在玩家点击左/右门板后调用：
 * - 更新 runner.score / runner.lives / runner.speed / runner.items
 * - 若 lives <= 0，设置 gameState = 'game_over'
 * - 返回 GateChoiceResult 包含效果详情（供渲染层播放浮动文字动画）
 *
 * @param state       当前游戏状态（不可变）
 * @param gateIndex   目标门板索引（通常为 currentGateIndex）
 * @param direction   选择方向：'left' 或 'right'
 * @returns           选择结果（含更新后状态和效果详情）
 */
export declare function applyGateChoice(
  state: ParkourState,
  gateIndex: number,
  direction: 'left' | 'right',
): GateChoiceResult;

/**
 * advanceToNextGate：前进到下一个门板。
 *
 * 场景层在门板穿越动画播放完毕后调用：
 * - currentGateIndex + 1
 * - runner.position 更新
 * - 若 currentGateIndex >= gates.length，设置 gameState = 'win'
 *
 * @param state   当前游戏状态（不可变）
 * @returns       更新后的游戏状态
 */
export declare function advanceToNextGate(state: ParkourState): ParkourState;

/**
 * checkGameOver：检测游戏是否已结束（生命归零）。
 *
 * 场景层在 applyGateChoice 动画播放完毕后调用，判断是否触发 Game Over 演出。
 *
 * @param state   当前游戏状态
 * @returns       true 表示游戏已结束（lives <= 0）
 */
export declare function checkGameOver(state: ParkourState): boolean;

/**
 * calculateFinalScore：计算最终得分（含通关加成）。
 *
 * 场景层在胜利或游戏结束时调用，用于显示结算面板。
 * 若 gameState === 'win'，在基础 score 上叠加 finishBonusScore。
 * 若 gameState === 'game_over'，返回当前 score（无加成）。
 *
 * @param state   当前游戏状态（gameState 应为 'win' 或 'game_over'）
 * @returns       最终分数
 */
export declare function calculateFinalScore(state: ParkourState): number;