《移动游戏产品的架构·客户端与移动运行时》2.2 纯逻辑内核：把玩法从引擎里拆出来

// file: src/domain/match3.ts
// tier: L1
// verify: node --test test/domain/match3.test.ts

import type { Clock } from "../core/clock.ts";
import type { Random } from "../core/random.ts";
import { fail, ok, type Result } from "../core/result.ts";

export type Gem = number;
export type Cell = Gem | null;
export type Board = readonly (readonly Cell[])[];

export interface Coord { readonly row: number; readonly col: number; }

export interface Match3Config {
  readonly rows: number;
  readonly cols: number;
  readonly kinds: number;
  readonly minRun: number;
  readonly baseScore: number;
  readonly comboStep: number;
  readonly durationMs: number;
}

export const DEFAULT_MATCH3_CONFIG: Match3Config = {
  rows: 8, cols: 8, kinds: 6, minRun: 3, baseScore: 60, comboStep: 25, durationMs: 90_000,
};

export type Match3Error =
  "out-of-bounds" | "not-adjacent" | "same-cell" | "no-match" | "session-over";

export interface MatchGroup {
  readonly orientation: "row" | "col"; readonly gem: Gem; readonly cells: readonly Coord[];
}

export interface TurnResult {
  readonly board: Board; readonly score: number; readonly cleared: number;
  readonly cascades: number; readonly groups: readonly MatchGroup[];
}

function cellKey(cell: Coord): string {
  return `${cell.row}:${cell.col}`;
}

function inBounds(board: Board, cell: Coord): boolean {
  if (cell.row < 0 || cell.row >= board.length) {
    return false;
  }
  const line = board[cell.row];
  return line !== undefined && cell.col >= 0 && cell.col < line.length;
}

function sameCell(a: Coord, b: Coord): boolean {
  return a.row === b.row && a.col === b.col;
}

function adjacent(a: Coord, b: Coord): boolean {
  return Math.abs(a.row - b.row) + Math.abs(a.col - b.col) === 1;
}

function pickGem(kinds: number, banned: ReadonlySet<Gem>, random: Random): Gem {
  const allowed: Gem[] = [];
  for (let gem = 0; gem < kinds; gem += 1) {
    if (!banned.has(gem)) {
      allowed.push(gem);
    }
  }
  return allowed[random.nextInt(allowed.length)];
}

export function createBoard(config: Match3Config, random: Random): Board {
  if (config.rows < config.minRun || config.cols < config.minRun) {
    throw new RangeError("board is smaller than the minimum run");
  }
  const rows: Gem[][] = [];
  for (let row = 0; row < config.rows; row += 1) {
    const line: Gem[] = [];
    for (let col = 0; col < config.cols; col += 1) {
      const banned = new Set<Gem>();
      if (col >= 2 && line[col - 1] === line[col - 2]) {
        banned.add(line[col - 1] as Gem);
      }
      if (row >= 2 && rows[row - 1][col] === rows[row - 2][col]) {
        banned.add(rows[row - 1][col]);
      }
      line.push(pickGem(config.kinds, banned, random));
    }
    rows.push(line);
  }
  return rows;
}

export function swapCells(board: Board, a: Coord, b: Coord): Result<Board, Match3Error> {
  if (!inBounds(board, a) || !inBounds(board, b)) {
    return fail("out-of-bounds", `swap ${cellKey(a)} -> ${cellKey(b)} leaves the board`);
  }
  if (sameCell(a, b)) {
    return fail("same-cell", `swap ${cellKey(a)} -> ${cellKey(b)} does not move`);
  }
  if (!adjacent(a, b)) {
    return fail("not-adjacent", `swap ${cellKey(a)} -> ${cellKey(b)} is not adjacent`);
  }
  const next: Cell[][] = board.map((line) => line.slice());
  const held = next[a.row][a.col];
  next[a.row][a.col] = next[b.row][b.col];
  next[b.row][b.col] = held;
  return ok(next);
}

function pushRun(groups: MatchGroup[], orientation: "row" | "col", gem: Gem,
  start: number, end: number, fixed: number, minRun: number): void {
  if (end - start < minRun) {
    return;
  }
  const cells: Coord[] = [];
  for (let index = start; index < end; index += 1) {
    cells.push(orientation === "row" ? { row: fixed, col: index } : { row: index, col: fixed });
  }
  groups.push({ orientation, gem, cells });
}

export function findMatches(board: Board, minRun = 3): readonly MatchGroup[] {
  const groups: MatchGroup[] = [];
  for (let row = 0; row < board.length; row += 1) {
    const line = board[row];
    let start = 0;
    for (let col = 1; col <= line.length; col += 1) {
      const previous = line[col - 1];
      const current = col < line.length ? line[col] : undefined;
      if (current !== previous) {
        if (previous !== null && previous !== undefined) {
          pushRun(groups, "row", previous, start, col, row, minRun);
        }
        start = col;
      }
    }
  }
  const cols = board[0]?.length ?? 0;
  for (let col = 0; col < cols; col += 1) {
    let start = 0;
    for (let row = 1; row <= board.length; row += 1) {
      const previous = board[row - 1][col];
      const current = row < board.length ? board[row][col] : undefined;
      if (current !== previous) {
        if (previous !== null && previous !== undefined) {
          pushRun(groups, "col", previous, start, row, col, minRun);
        }
        start = row;
      }
    }
  }
  return groups;
}

function collapseAndRefill(grid: Cell[][], config: Match3Config, random: Random): Board {
  for (let col = 0; col < config.cols; col += 1) {
    const kept: Gem[] = [];
    for (let row = config.rows - 1; row >= 0; row -= 1) {
      const cell = grid[row][col];
      if (cell !== null) {
        kept.push(cell);
      }
    }
    let index = 0;
    for (let row = config.rows - 1; row >= 0; row -= 1) {
      grid[row][col] = index < kept.length ? kept[index] : random.nextInt(config.kinds);
      index += 1;
    }
  }
  return grid;
}

const MAX_CASCADES = 32;

export function playTurn(board: Board, a: Coord, b: Coord, config: Match3Config, random: Random): Result<TurnResult, Match3Error> {
  const swapped = swapCells(board, a, b);
  if (!swapped.ok) {
    return swapped;
  }
  if (findMatches(swapped.value, config.minRun).length === 0) {
    return fail("no-match", `swap ${cellKey(a)} -> ${cellKey(b)} creates no run`);
  }

  let current: Board = swapped.value;
  let cascades = 0;
  let cleared = 0;
  let score = 0;
  const groups: MatchGroup[] = [];

  while (cascades < MAX_CASCADES) {
    const matches = findMatches(current, config.minRun);
    if (matches.length === 0) {
      break;
    }
    cascades += 1;
    groups.push(...matches);
    const marked = new Set<string>();
    for (const group of matches) {
      for (const cell of group.cells) {
        marked.add(cellKey(cell));
      }
    }
    cleared += marked.size;
    score += marked.size * config.baseScore + (cascades - 1) * config.comboStep * matches.length;
    const grid: Cell[][] = current.map((line) => line.slice());
    for (const key of marked) {
      const [row, col] = key.split(":").map(Number);
      grid[row][col] = null;
    }
    current = collapseAndRefill(grid, config, random);
  }

  return ok({ board: current, score, cleared, cascades, groups });
}

export class Match3Session {
  #clock: Clock;
  #random: Random;
  #config: Match3Config;
  #board: Board;
  #startedAtMs: number;
  #score = 0;
  #turns = 0;
  #lastTurnAtMs: number | null = null;

  constructor(
    clock: Clock,
    random: Random,
    config: Match3Config = DEFAULT_MATCH3_CONFIG,
    initialBoard?: Board,
  ) {
    this.#clock = clock;
    this.#random = random;
    this.#config = config;
    this.#board = initialBoard ?? createBoard(config, random);
    this.#startedAtMs = clock.nowMs();
  }

  get board(): Board { return this.#board; }
  get score(): number { return this.#score; }
  get turns(): number { return this.#turns; }
  get lastTurnAtMs(): number | null { return this.#lastTurnAtMs; }

  elapsedMs(): number { return this.#clock.nowMs() - this.#startedAtMs; }
  remainingMs(): number { return Math.max(0, this.#config.durationMs - this.elapsedMs()); }
  isExpired(): boolean { return this.remainingMs() === 0; }

  swap(a: Coord, b: Coord): Result<TurnResult, Match3Error> {
    if (this.isExpired()) {
      return fail("session-over", `session ended after ${this.#config.durationMs}ms`);
    }
    const result = playTurn(this.#board, a, b, this.#config, this.#random);
    if (!result.ok) {
      return result;
    }
    this.#board = result.value.board;
    this.#score += result.value.score;
    this.#turns += 1;
    this.#lastTurnAtMs = this.#clock.nowMs();
    return result;
  }
}