/**
 * merge_core.aigameplay — reducer 接口模板
 *
 * Agent 生成实际 reducer 时，必须导出以下函数。
 * 此文件是接口约束模板，不是可执行代码。
 *
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
 *
 * dispatch() 是一体化接口，内部完成合并、升级、自动生成全流程后
 * 只返回最终状态，中间过程（哪两个物品合并了、升级动画坐标、
 * 新生成的物品位置）全部丢失。
 *
 * 渲染层需要分步动画（拖动飞向目标 → 合并升级光效 → 新物品弹出），
 * 因此必须使用下方的「分步函数」逐步驱动，每步之间插入 Tween 动画。
 *
 * dispatch() 的用途：无头测试、AI 模拟、自动求解等场景。
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 */

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

export type MergeConfig = {
  /** 棋盘列数，默认 5 */
  cols: number;
  /** 棋盘行数，默认 5 */
  rows: number;
  /** 最高等级（达到后胜利），默认 9 */
  maxTier: number;
  /** 是否在每次合并后自动生成新物品 */
  autoSpawn: boolean;
  /** 自动生成的物品等级，默认 1 */
  spawnTier: number;
  /** 相邻方式：正交（上下左右）或全方向（含斜角） */
  adjacency: 'orthogonal' | 'all';
  /** 目标分数（score_goal 模式），可选 */
  goalScore?: number;
};

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

export type MergeAction =
  | { type: 'merge'; from: { col: number; row: number }; to: { col: number; row: number } }
  | { type: 'reset' };

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

/** 棋盘格子：null 表示空，number 表示物品等级（1 ~ maxTier） */
export type GridCell = number | null;

export type MergeState = {
  /** 棋盘，board[col][row] */
  board: GridCell[][];
  /** 当前得分 */
  score: number;
  /** 已操作次数 */
  moves: number;
  /** 游戏是否结束 */
  gameOver: boolean;
  /** 是否胜利 */
  win: boolean;
  /** 上一次合并是否被拒绝 */
  lastMergeRejected: boolean;
};

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

/** 格子坐标 */
export type GridPos = { col: number; row: number };

/** 合并结果 */
export type MergeResult = {
  /** 被移除的源格子坐标 */
  removedFrom: GridPos;
  /** 升级后的目标格子坐标和新等级 */
  mergedItem: { pos: GridPos; tier: number };
  /** 新状态 */
  newState: MergeState;
};

/** 自动生成的物品 */
export type SpawnedItem = {
  pos: GridPos;
  tier: number;
} | null;

/** 可合并对 */
export type MergePair = {
  from: GridPos;
  to: GridPos;
  tier: number;
};

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

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

/**
 * init：根据配置初始化游戏状态
 * - 创建空棋盘
 * - 随机在部分空格生成 spawnTier 物品（初始填充约 1/3 棋盘）
 */
export declare function init(config: MergeConfig): MergeState;

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

/**
 * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
 * - merge：验证并执行合并，自动生成新物品，检测胜败
 * - reset：重置到初始状态
 *
 * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
 */
export declare function dispatch(state: MergeState, action: MergeAction): MergeState;

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

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

/**
 * canMerge：检测 from 格子的物品是否可以合并到 to 格子
 *
 * 合法条件：
 * 1. from 和 to 都有物品（非 null）
 * 2. from 和 to 的物品等级相同
 * 3. from 和 to 在配置允许的相邻范围内（正交或全方向）
 * 4. 合并后等级不超过 maxTier（或恰好 = maxTier 触发胜利）
 *
 * 场景层在拖拽过程中实时调用，用于高亮合法/非法目标格子。
 */
export declare function canMerge(
  state: MergeState,
  from: GridPos,
  to: GridPos,
  config: MergeConfig,
): boolean;

/**
 * mergeItems：执行合并（不做合法性验证，调用前请先确认 canMerge）
 *
 * 合并逻辑：移除 from 格子的物品，将 to 格子的物品等级 +1。
 * 场景层在拖拽释放后调用，播放飞入合并动画。
 */
export declare function mergeItems(
  state: MergeState,
  from: GridPos,
  to: GridPos,
  config: MergeConfig,
): MergeResult;

/**
 * spawnItem：在棋盘随机空格生成 spawnTier 等级的新物品
 *
 * 若棋盘没有空格，返回 null。
 * 场景层根据返回值在对应格子播放物品弹出缩放动画。
 */
export declare function spawnItem(
  state: MergeState,
  config: MergeConfig,
): SpawnedItem;

/**
 * findMergablePairs：返回当前棋盘上所有可合并的物品对
 *
 * 场景层用途：
 * - 空数组 + 棋盘满 → 触发游戏结束
 * - Hint 功能：高亮推荐的下一步合并对
 */
export declare function findMergablePairs(
  state: MergeState,
  config: MergeConfig,
): MergePair[];