react-docs-game-lib

A TypeScript library for calculating optimal moves in Tic-Tac-Toe using the Minimax algorithm. This library provides an unbeatable AI that can play perfect Tic-Tac-Toe.

🎯 Features

- ✅ Optimal move calculation using Minimax algorithm
- ✅ TypeScript support with full type definitions
- ✅ Zero dependencies - pure algorithm implementation
- ✅ Comprehensive tests with 100% coverage
- ✅ Fast performance - optimized for quick decisions
- ✅ Easy to use - simple, clean API

📦 Installation

``bash
npm install react-docs-game-lib
`

🚀 Quick Start

`typescript
import { getOptimalTurn, GameBoard } from 'react-docs-game-lib';

// Define the game board: -1 = empty, 0 = Player O, 1 = Player X
const board: GameBoard = [
1,
1,
-1, // X | X | -
-1,
0,
-1, // - | O | -
-1,
-1,
-1, // - | - | -
];

// Get optimal move for Player O (0)
const optimalMove = getOptimalTurn(board, 0);
console.log(optimalMove); // => 2 (blocks X's winning move)
`

📖 API Documentation

$3

#### CellValue

`typescript
type CellValue = -1 | 0 | 1;
`

- -1: Empty cell
- 0: Player O
- 1: Player X

#### GameBoard

`typescript
type GameBoard = [
CellValue,
CellValue,
CellValue,
CellValue,
CellValue,
CellValue,
CellValue,
CellValue,
CellValue
];
`

Array of 9 cells representing the board:

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

#### Player

`typescript
type Player = 0 | 1;
`

- 0: Player O
- 1: Player X

$3

#### getOptimalTurn(gameField, player)

Returns the optimal move position for the given player.

Parameters:

- gameField: GameBoard - Current state of the game board
- player: Player - Current player (0 or 1)

Returns: number - Index (0-8) of the optimal move, or -1 if no moves available

Example:

`typescript
const board: GameBoard = [-1, -1, -1, -1, -1, -1, -1, -1, -1];
const move = getOptimalTurn(board, 0);
console.log(move); // => 0 (corner is optimal on empty board)
`

Throws:

- Error if board is not exactly 9 elements
- Error if player is not 0 or 1

#### getOptimalTurnWithScore(gameField, player)

Returns the optimal move with its evaluation score.

Parameters:

- gameField: GameBoard - Current state of the game board
- player: Player - Current player (0 or 1)

Returns: OptimalMoveResult

`typescript
{
position: number; // Index of optimal move (0-8), or -1 if none
score: number; // Evaluation score (positive = winning, negative = losing, 0 = draw)
}
`

Example:

`typescript
const board: GameBoard = [0, 0, -1, 1, 1, -1, -1, -1, -1];
const result = getOptimalTurnWithScore(board, 0);
console.log(result); // => { position: 2, score: 9 } (winning move)
`

#### checkGameOver(board)

Checks if the game is over and returns the result.

Parameters:

- board: GameBoard - Current state of the game board

Returns:

`typescript
{
isOver: boolean; // true if game is finished
winner: Player | null; // winning player (0 or 1), or null
isDraw: boolean; // true if game ended in draw
}
`

Example:

`typescript
const board: GameBoard = [0, 0, 0, 1, 1, -1, -1, -1, -1];
const result = checkGameOver(board);
console.log(result); // => { isOver: true, winner: 0, isDraw: false }
`

💡 Usage Examples

$3

`typescript
import { getOptimalTurn, checkGameOver, GameBoard } from 'react-docs-game-lib';

function playGame() {
let board: GameBoard = [-1, -1, -1, -1, -1, -1, -1, -1, -1];
let currentPlayer = 0;

while (true) {
// Get AI move
const move = getOptimalTurn(board, currentPlayer);

if (move === -1) break; // No moves available

// Make the move
board[move] = currentPlayer;

// Check if game is over
const gameState = checkGameOver(board);
if (gameState.isOver) {
if (gameState.isDraw) {
console.log("It's a draw!");
} else {
console.log(Player ${gameState.winner} wins!);
}
break;
}

// Switch players
currentPlayer = currentPlayer === 0 ? 1 : 0;
}
}
`

$3

`typescript
import { useState } from 'react';
import { getOptimalTurn, checkGameOver, GameBoard } from 'react-docs-game-lib';

function TicTacToe() {
const [board, setBoard] = useState([
-1, -1, -1, -1, -1, -1, -1, -1, -1,
]);

const handlePlayerMove = (position: number) => {
if (board[position] !== -1) return;

// Player move
const newBoard = [...board] as GameBoard;
newBoard[position] = 0;
setBoard(newBoard);

// Check game over
const gameState = checkGameOver(newBoard);
if (gameState.isOver) return;

// AI move
const aiMove = getOptimalTurn(newBoard, 1);
if (aiMove !== -1) {
newBoard[aiMove] = 1;
setBoard(newBoard);
}
};

// ... render board
}
``

🔍 How It Works

This library uses the Minimax algorithm, a decision-making algorithm used in game theory. The algorithm:

1. Explores all possible future game states recursively
2. Evaluates each terminal state (win/loss/draw)
3. Assumes both players play optimally
4. Chooses the move that leads to the best guaranteed outcome

The algorithm ensures the AI never loses - it will always win or draw when playing optimally.

📝 License

MIT © UV