npm package: @richiewinters/react-docs-game-lib
Description: Optimal move calculator for React Docs Game
Author: UV
Latest version: 1.0.2

# 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

### Types

#### `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

### Functions

#### `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

### Basic AI Opponent

```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;
  }
}
```

### React Integration

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

function TicTacToe() {
  const [board, setBoard] = useState<GameBoard>([
    -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