/**
 * car_parking.aigameplay — reducer 接口模板
 *
 * Agent 生成实际 reducer 时，必须导出以下函数。
 * 此文件是接口约束模板，不是可执行代码。
 *
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
 *
 * dispatch() 是一体化接口，内部执行完整的移动+胜利检测后只返回最终状态。
 * 渲染层需要知道具体哪辆车移动了多少格才能播放位移动画，
 * 因此必须使用下方的「分步函数」逐步驱动。
 *
 * dispatch() 的用途：无头测试、AI 模拟、快速验证关卡可解性。
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 */

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

export type CarParkingConfig = {
  /** 棋盘列数，默认 6 */
  cols: number;
  /** 棋盘行数，默认 6 */
  rows: number;
  /** 初始车辆配置 */
  cars: CarConfig[];
  /** 出口位置 */
  exit: { col: number; row: number };
};

export type CarConfig = {
  /** 车辆唯一标识 */
  id: string;
  /** 朝向：H=水平，V=垂直 */
  orientation: 'H' | 'V';
  /** 初始占据格子坐标 */
  cells: Array<{ col: number; row: number }>;
  /** 车辆颜色/显示类型 */
  color: string;
  /** 是否为目标车（需移至出口） */
  isTarget: boolean;
};

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

export type CarParkingAction =
  | { type: 'move_car'; carId: string; steps: number }
  | { type: 'reset' };

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

export type Car = {
  id: string;
  orientation: 'H' | 'V';
  /** 当前占据格子坐标（按朝向排序，从小到大） */
  cells: Array<{ col: number; row: number }>;
  color: string;
  isTarget: boolean;
};

export type CarParkingState = {
  /** 棋盘尺寸 */
  cols: number;
  rows: number;
  /** 所有车辆当前状态 */
  cars: Car[];
  /** 出口位置 */
  exit: { col: number; row: number };
  /** 游戏是否结束 */
  gameOver: boolean;
  /** 是否胜利 */
  win: boolean;
  /** 已执行的移动步数（用于评分） */
  moveCount: number;
};

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

/** getCarMoveRange 返回值：该车可移动的范围（负=向左/上，正=向右/下） */
export type MoveRange = {
  /** 可向负方向（左/上）移动的最大格数（负数，如 -2 表示最多向左2格） */
  minSteps: number;
  /** 可向正方向（右/下）移动的最大格数（正数，如 3 表示最多向右3格） */
  maxSteps: number;
};

/** isBlocked 检测方向 */
export type BlockDirection = 'positive' | 'negative';

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

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

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

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

/**
 * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
 * - move_car：移动指定车辆指定步数，检测胜利条件
 * - reset：重置到初始状态
 *
 * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
 */
export declare function dispatch(state: CarParkingState, action: CarParkingAction): CarParkingState;

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

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

/**
 * getCarMoveRange：查询指定车辆在当前状态下可移动的步数范围。
 *
 * 场景层在玩家按下/拖动某辆车时调用，用于限制拖动范围。
 * minSteps <= 0 <= maxSteps，均值为0时表示该车完全被阻挡（四面无路）。
 *
 * @param state   当前游戏状态
 * @param carId   目标车辆 ID
 * @returns       可移动范围 { minSteps（负=向左/上）, maxSteps（正=向右/下）}
 */
export declare function getCarMoveRange(state: CarParkingState, carId: string): MoveRange;

/**
 * moveCar：执行车辆移动，返回新状态。
 *
 * 场景层在确认移动格数后调用（应先经过 getCarMoveRange 验证 steps 在合法范围内）。
 * 返回的新状态中 cars 已更新，win 字段已反映胜利检测结果。
 *
 * @param state   当前游戏状态（不可变）
 * @param carId   目标车辆 ID
 * @param steps   移动步数（正=向右/下，负=向左/上）
 * @returns       更新后的游戏状态
 */
export declare function moveCar(state: CarParkingState, carId: string, steps: number): CarParkingState;

/**
 * checkWin：检测目标车是否已到达出口。
 *
 * 场景层在每次 moveCar 动画播放完毕后调用，判断是否触发胜利演出。
 *
 * @param state   当前游戏状态
 * @returns       true 表示目标车已到达出口
 */
export declare function checkWin(state: CarParkingState): boolean;

/**
 * isBlocked：检测指定车辆在给定方向上是否被阻挡（无法移动）。
 *
 * 场景层可用于显示"该车无法移动"的视觉反馈（如抖动动画）。
 *
 * @param state      当前游戏状态
 * @param carId      目标车辆 ID
 * @param direction  检测方向：'positive'（右/下）或 'negative'（左/上）
 * @returns          true 表示该方向完全被阻挡
 */
export declare function isBlocked(state: CarParkingState, carId: string, direction: BlockDirection): boolean;