/**
 * 2048_core.aigameplay — reducer 接口模板
 *
 * Agent 生成实际 reducer 时，必须导出以下函数。
 * 此文件是接口约束模板，不是可执行代码。
 *
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
 *
 * dispatch() 是一体化接口，内部完成滑动 + 合并 + 生成后只返回最终状态，
 * 中间过程（哪些方块移动了多远、哪些方块合并了、新方块在哪里生成）全部丢失。
 *
 * 渲染层需要分步动画（方块平移 → 合并弹跳 → 新方块弹出），
 * 因此必须使用下方的「分步函数」逐步驱动，每步之间插入 Tween 动画。
 *
 * dispatch() 的用途：无头测试、AI 模拟、快速跳过动画等场景。
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 */

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

export type SlideDirection = 'up' | 'down' | 'left' | 'right';

export type Game2048Config = {
  /** 棋盘尺寸，默认 4（4×4） */
  gridSize: number;
  /** 胜利目标值，默认 2048 */
  winValue: number;
  /** 生成方块的可选值，默认 [2, 4] */
  spawnValues: number[];
  /** 对应权重（0-1），默认 [0.9, 0.1] */
  spawnWeights: number[];
  /** 初始生成方块数量，默认 2 */
  initialTileCount: number;
  /** 胜利后是否继续，默认 false */
  continueAfterWin: boolean;
};

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

export type Game2048Action =
  | { type: 'slide'; direction: SlideDirection }
  | { type: 'reset' };

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

/**
 * 棋盘格子，null 表示空格
 * board[row][col]，row 0 为顶行，col 0 为左列
 */
export type TileCell = {
  value: number;
  /** 本次滑动中是否已参与合并（防止二次合并） */
  merged: boolean;
} | null;

export type Game2048State = {
  /** 4×4 棋盘，board[row][col] */
  board: TileCell[][];
  /** 当前得分 */
  score: number;
  /** 历史最高分 */
  bestScore: number;
  /** 游戏是否结束 */
  gameOver: boolean;
  /** 是否达到胜利值 */
  win: boolean;
  /** 上次滑动是否有效（棋盘发生变化） */
  lastSlideEffective: boolean;
};

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

/** 方块移动信息（用于驱动平移动画） */
export type TileMove = {
  /** 来源位置 */
  from: { row: number; col: number };
  /** 目标位置 */
  to: { row: number; col: number };
  /** 方块值 */
  value: number;
};

/** 合并信息（用于驱动合并动画） */
export type MergeResult = {
  /** 合并发生在目标位置 */
  position: { row: number; col: number };
  /** 合并前两个方块的值 */
  fromValue: number;
  /** 合并后的新值 */
  toValue: number;
  /** 本次合并的得分 */
  scoreGained: number;
};

/** 新生成方块信息 */
export type SpawnedTile = {
  row: number;
  col: number;
  value: number;
};

/** slideBoard 的完整返回 */
export type SlideResult = {
  /** 更新后的棋盘（已完成移动和合并，但尚未重置 merged 标志） */
  board: TileCell[][];
  /** 所有方块的移动信息 */
  moves: TileMove[];
  /** 所有合并信息 */
  merges: MergeResult[];
  /** 本次滑动是否有效（棋盘发生变化） */
  effective: boolean;
  /** 本次滑动新增得分 */
  scoreGained: number;
};

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

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

/**
 * init：根据配置初始化游戏状态，随机放置 initialTileCount 个方块
 */
export declare function init(config: Game2048Config): Game2048State;

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

/**
 * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
 * - slide：滑动棋盘，合并方块，生成新方块，检测胜败（一步到位）
 * - reset：重置到初始状态
 *
 * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
 */
export declare function dispatch(state: Game2048State, action: Game2048Action): Game2048State;

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

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

/**
 * slideBoard：执行一次滑动操作（移动 + 合并）
 * 返回包含移动信息、合并信息和更新后棋盘的完整结果
 *
 * 场景层调用顺序：
 * 1. slideBoard → 获取 moves / merges / board
 * 2. playTileMoveAnimation(moves) 并行平移动画
 * 3. playTileMergeAnimation(merges) 合并弹跳动画
 * 4. 若 effective，调用 spawnTile(board)
 *
 * 关键约束：合并后的方块其 merged = true，本次滑动不再参与二次合并
 */
export declare function slideBoard(board: TileCell[][], direction: SlideDirection): SlideResult;

/**
 * mergeTiles：仅执行合并逻辑（不含位移），用于需要独立控制合并步骤的场景
 * 通常直接使用 slideBoard 即可，此函数供高级定制使用
 */
export declare function mergeTiles(board: TileCell[][], direction: SlideDirection): MergeResult[];

/**
 * spawnTile：在棋盘随机空格生成新方块
 * 返回生成的方块信息（直接修改传入的 board 引用）
 *
 * 场景层根据 SpawnedTile 在对应位置创建精灵并播放 scale 0→1 弹出动画
 * 若无空格则返回 null（理论上 slideBoard effective 后必有空格）
 */
export declare function spawnTile(board: TileCell[][]): SpawnedTile | null;

/**
 * hasValidMoves：检查棋盘是否还有可用的合法滑动
 * - 有空格：true
 * - 无空格但有相邻同值方块：true
 * - 无空格且无相邻同值方块：false（游戏结束）
 */
export declare function hasValidMoves(board: TileCell[][]): boolean;

/**
 * calculateScore：计算一轮合并的总得分
 * 每次合并得分 = 合并后新方块的值
 */
export declare function calculateScore(merges: MergeResult[]): number;