📖 Документация для библиотеки ttt-ai-maxmoses

📦 Tic-Tac-Toe AI

Библиотека для поиска оптимального хода в игре "Крестики-нолики" (3×3) с использованием алгоритма Minimax.

🚀 Быстрый старт

Установка

npm install ttt-ai-maxmoses

Использование

import { getOptimalTurn } from 'ttt-ai-maxmoses';

// Поле представлено как массив из 9 элементов:
// -1 = пустая клетка
//  0 = игрок "O"
//  1 = игрок "X"

const field = [
  -1, -1, -1,
   1,  1, -1,
   0,  0, -1
];

// Получить оптимальный ход для игрока "O" (0)
const bestMove = getOptimalTurn(field, 0);

console.log(bestMove); // 5 (блокирует победу "X")

📖 API Reference

getOptimalTurn(gameField: number[], player: 0 | 1): number

Параметры:

• gameField (number[]) - игровое поле 3×3, представленное как одномерный массив из 9 элементов:

  • -1 - пустая клетка
  • 0 - игрок "O"
  • 1 - игрок "X"

• player (0 | 1) - игрок, для которого нужно найти оптимальный ход:

  • 0 - игрок "O"
  • 1 - игрок "X"

Возвращаемое значение:

• number - индекс (0-8) оптимального хода на поле

Исключения:

• Функция не проверяет корректность входных данных (используйте TypeScript для типизации)
• Если поле полностью заполнено, поведение не определено

📊 Примеры

Пример 1: Пустая доска

import { getOptimalTurn } from 'ttt-ai-maxmoses';

const emptyBoard = [
  -1, -1, -1,
  -1, -1, -1,
  -1, -1, -1
];

// Первый ход для "O"
const move = getOptimalTurn(emptyBoard, 0);
console.log(move); // 4 (центр)

Пример 2: Завершение победной линии

const board = [
   0,  0, -1,
  -1, -1, -1,
  -1, -1, -1
];

const move = getOptimalTurn(board, 0);
console.log(move); // 2 (завершает верхнюю линию)

Пример 3: Блокировка противника

const board = [
   1,  1, -1,
  -1, -1, -1,
  -1, -1, -1
];

const move = getOptimalTurn(board, 0);
console.log(move); // 2 (блокирует победу "X")

Пример 4: Из задания

const board = [
  -1, -1, -1,
   1,  1, -1,
   0,  0, -1
];

const move = getOptimalTurn(board, 0);
console.log(move); // 5

🎯 Особенности алгоритма

Библиотека использует алгоритм Minimax с альфа-бета отсечением, который гарантирует:

• Оптимальность: всегда выбирает лучший возможный ход
• Полноту: рассматривает все возможные варианты развития игры
• Стратегию: для равных по оценке ходов предпочитает центр, затем углы

Оценка позиций:

• Победа: +1000 (с учетом глубины для более быстрой победы)
• Поражение: -1000 (с учетом глубины для более позднего поражения)
• Ничья: 0

⚙️ Ограничения

1. Только поле 3×3: библиотека работает только со стандартным полем крестиков-нолики
2. Нет валидации: функция предполагает корректные входные данные
3. Синхронный вызов: алгоритм работает синхронно (но очень быстро для 3×3)
4. Типы TypeScript: рекомендуется использовать TypeScript для типизации

📁 Структура проекта

src/
├── minimax.ts     # Основная логика алгоритма
├── index.ts       # Точка входа (экспорт)
└── types.ts       # TypeScript типы

🧪 Тестирование

Библиотека включает юнит-тесты с покрытием ключевых сценариев:

# Запуск тестов
npm test

# Запуск тестов с покрытием
npm run test:coverage

Тесты проверяют:

• Ход в центр на пустой доске
• Завершение победной линии
• Блокировку противника
• Создание стратегических преимуществ
• Выбор из доступных ходов

🛠️ Разработка

Установка для разработки

git clone <repository-url>
cd ttt-ai-maxmoses
npm install

Сборка

# Сборка библиотеки
npm run build

# Проверка типов
npm run type-check

Форматы сборки

Библиотека собирается в трех форматах:

• ES Module (dist/ttt-ai-maxmoses.es.js)
• CommonJS (dist/ttt-ai-maxmoses.cjs)
• UMD (dist/ttt-ai-maxmoses.umd.js)

📄 Лицензия

MIT

🔗 Ссылки

• Исходный код
• NPM пакет
• Пример использования

💡 Советы по использованию

1. Для отладки: добавьте логирование в свой код, чтобы видеть выбранные ходы
2. Валидация: проверяйте входные данные перед вызовом функции
3. Интерфейс: индексы 0-8 соответствуют позициям на поле:

0 | 1 | 2
---------
3 | 4 | 5
---------
6 | 7 | 8

Готово к использованию! 🎮 Библиотека решает задачу поиска оптимального хода в крестики-нолики и готова к интеграции в ваш проект.

📝 Пример полного приложения

import { getOptimalTurn } from 'ttt-ai-maxmoses';

class TicTacToeGame {
  private field: number[] = Array(9).fill(-1);
  private currentPlayer: 0 | 1 = 0;

  makeAIMove(): void {
    const bestMove = getOptimalTurn(this.field, this.currentPlayer);
    this.field[bestMove] = this.currentPlayer;
    this.currentPlayer = this.currentPlayer === 0 ? 1 : 0;
  }

  printBoard(): void {
    const symbols = [' ', 'X', 'O'];
    for (let i = 0; i < 9; i += 3) {
      console.log(
        symbols[this.field[i] + 1] + ' | ' +
        symbols[this.field[i + 1] + 1] + ' | ' +
        symbols[this.field[i + 2] + 1]
      );
      if (i < 6) console.log('---------');
    }
  }
}

// Использование
const game = new TicTacToeGame();
game.makeAIMove();
game.printBoard();