/**
 * ball_sort.aigameplay — reducer 接口模板
 *
 * Agent 生成实际 reducer 时，必须导出以下函数。
 * 此文件是接口约束模板，不是可执行代码。
 *
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
 *
 * dispatch() 是一体化接口，内部完成移动逻辑后返回最终状态，
 * 中间过程（哪个球从哪根管移入哪根管）丢失。
 *
 * 渲染层需要分步驱动球的弧线移动动画，因此必须使用下方的
 * 「分步函数」逐步驱动，每步之间插入 Tween 动画。
 *
 * dispatch() 的用途：无头测试、AI 模拟、快速跳过动画等场景。
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 */

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

export type BallSortConfig = {
  /** 颜色数量（等于有色管子的数量），默认 6 */
  colorCount: number;
  /** 每根管子的容量（球的最大数量），默认 4 */
  tubeCapacity: number;
  /** 额外空管子数量（缓冲区），默认 2 */
  emptyTubeCount: number;
};

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

export type BallSortAction =
  | { type: 'move'; from: number; to: number }  // 将 from 管顶部的球移入 to 管
  | { type: 'reset' };

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

/** 球的颜色，0 ~ colorCount-1 */
export type BallColor = number;

/** 单根管子的状态，balls[0] 是底部，balls[length-1] 是顶部 */
export type Tube = BallColor[];

export type BallSortState = {
  /** 所有管子，tubes[i] 是第 i 根管 */
  tubes: Tube[];
  /** 总步数 */
  moves: number;
  /** 游戏是否结束（死锁或胜利） */
  gameOver: boolean;
  /** 是否胜利 */
  win: boolean;
  /** 上一次移动是否被拒绝 */
  lastMoveRejected: boolean;
};

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

/** 移动球的结果 */
export type MoveResult = {
  /** 被移动的球的颜色 */
  ball: BallColor;
  /** 源管子索引 */
  fromTube: number;
  /** 目标管子索引 */
  toTube: number;
  /** 移动后的新状态 */
  newState: BallSortState;
};

/** 合法移动描述 */
export type ValidMove = {
  from: number;
  to: number;
  ball: BallColor;
};

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

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

/**
 * init：根据配置生成随机初始状态
 * - 生成 colorCount 根有色管子（每管随机混色球，共 tubeCapacity 个）
 * - 再添加 emptyTubeCount 根空管
 * - 确保初始状态不是已胜利状态
 */
export declare function init(config: BallSortConfig): BallSortState;

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

/**
 * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
 * - move：尝试将 from 管顶部的球移入 to 管，验证合法性并执行
 * - reset：重置到初始状态
 *
 * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
 */
export declare function dispatch(state: BallSortState, action: BallSortAction): BallSortState;

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

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

/**
 * isValidMove：检测从 from 管将顶球移入 to 管是否合法
 *
 * 合法条件：
 * 1. from 管非空
 * 2. to 管未满
 * 3. to 管为空 OR to 管顶部颜色 === from 管顶部颜色
 *
 * 场景层在玩家点击目标管时调用，决定高亮效果与是否执行移动。
 */
export declare function isValidMove(
  state: BallSortState,
  from: number,
  to: number,
): boolean;

/**
 * moveBall：执行移动（不做合法性验证，调用前请先调用 isValidMove）
 *
 * 场景层在合法性确认后调用，播放球的弧线移动动画。
 * 返回被移动球的颜色和新状态，用于动画 + 状态同步。
 */
export declare function moveBall(
  state: BallSortState,
  from: number,
  to: number,
): MoveResult;

/**
 * checkWin：检测当前状态是否满足胜利条件
 *
 * 胜利条件：每根非空管子内的球颜色完全相同。
 * 场景层在每次 moveBall 后调用。
 */
export declare function checkWin(state: BallSortState): boolean;

/**
 * findValidMoves：返回当前状态下所有合法移动列表
 *
 * 场景层用途：
 * - 空列表 → 触发死锁提示
 * - 非空列表 → Hint 功能高亮推荐的下一步
 */
export declare function findValidMoves(state: BallSortState): ValidMove[];