# API Reference - HTML Chess Game
## Table of Contents
1. [Core Classes](#core-classes)
2. [Piece Classes](#piece-classes)
3. [Move System](#move-system)
4. [UI Components](#ui-components)
5. [Utilities](#utilities)
6. [Events](#events)
7. [Data Structures](#data-structures)
---
## Core Classes
### ChessGame
Main game controller that orchestrates all game logic.
#### Constructor
```javascript
new ChessGame(config?: GameConfig)
```
**Parameters:**
- `config` (optional): Configuration object
- `autoSave`: boolean - Enable automatic saving (default: true)
- `enableTimer`: boolean - Enable move timer (default: false)
- `timeControl`: number - Time in milliseconds per player
**Example:**
```javascript
const game = new ChessGame({
autoSave: true,
enableTimer: false
});
```
#### Properties
| Property | Type | Description |
|----------|------|-------------|
| `board` | Board | The game board instance |
| `currentTurn` | 'white' \| 'black' | Current player's turn |
| `gameState` | GameState | Game state manager |
| `status` | GameStatus | Current game status |
| `winner` | 'white' \| 'black' \| null | Winner if game ended |
#### Methods
##### makeMove()
Execute a chess move.
```javascript
makeMove(fromRow: number, fromCol: number, toRow: number, toCol: number): MoveResult
```
**Parameters:**
- `fromRow`: Source row (0-7)
- `fromCol`: Source column (0-7)
- `toRow`: Destination row (0-7)
- `toCol`: Destination column (0-7)
**Returns:** `MoveResult`
```javascript
{
success: boolean,
move?: Move,
error?: string,
gameStatus?: GameStatus
}
```
**Example:**
```javascript
const result = game.makeMove(6, 4, 4, 4); // e2 to e4
if (result.success) {
console.log('Move executed:', result.move.notation);
console.log('Game status:', result.gameStatus);
} else {
console.error('Invalid move:', result.error);
}
```
##### getLegalMoves()
Get all legal moves for a piece.
```javascript
getLegalMoves(piece: Piece): Position[]
```
**Parameters:**
- `piece`: The piece to get moves for
**Returns:** Array of legal positions
```javascript
[
{row: 4, col: 4},
{row: 5, col: 4}
]
```
##### isInCheck()
Check if a player is in check.
```javascript
isInCheck(color: Color): boolean
```
**Parameters:**
- `color`: 'white' or 'black'
**Returns:** `true` if in check, `false` otherwise
##### newGame()
Start a new game.
```javascript
newGame(): void
```
Resets the board and game state to initial position.
##### undo()
Undo the last move.
```javascript
undo(): boolean
```
**Returns:** `true` if undo successful, `false` if no moves to undo
##### redo()
Redo a previously undone move.
```javascript
redo(): boolean
```
**Returns:** `true` if redo successful, `false` if no moves to redo
##### resign()
Current player resigns.
```javascript
resign(): void
```
Sets game status to ended with opponent as winner.
##### offerDraw()
Offer a draw to opponent.
```javascript
offerDraw(): void
```
##### acceptDraw()
Accept a draw offer.
```javascript
acceptDraw(): void
```
Sets game status to draw.
---
### Board
Manages the chess board state and piece positions.
#### Constructor
```javascript
new Board()
```
#### Properties
| Property | Type | Description |
|----------|------|-------------|
| `grid` | (Piece \| null)[][] | 8x8 grid of pieces |
#### Methods
##### getPiece()
Get piece at position.
```javascript
getPiece(row: number, col: number): Piece | null
```
##### setPiece()
Place piece at position.
```javascript
setPiece(row: number, col: number, piece: Piece | null): void
```
##### movePiece()
Move piece from one position to another.
```javascript
movePiece(fromRow: number, fromCol: number, toRow: number, toCol: number): Piece | null
```
**Returns:** Captured piece if any
##### clone()
Create deep copy of board.
```javascript
clone(): Board
```
**Returns:** New board instance with copied state
##### setupInitialPosition()
Set up standard chess starting position.
```javascript
setupInitialPosition(): void
```
##### clear()
Remove all pieces from board.
```javascript
clear(): void
```
##### toFEN()
Export board to FEN notation.
```javascript
toFEN(): string
```
**Returns:** FEN string representing board state
**Example:**
```javascript
const fen = board.toFEN();
// "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"
```
##### fromFEN()
Import board from FEN notation.
```javascript
fromFEN(fen: string): void
```
**Parameters:**
- `fen`: FEN notation string
---
### GameState
Manages game state, move history, and metadata.
#### Constructor
```javascript
new GameState()
```
#### Properties
| Property | Type | Description |
|----------|------|-------------|
| `moveHistory` | Move[] | Array of all moves |
| `currentMove` | number | Current position in history |
| `capturedPieces` | CapturedPieces | Captured pieces by color |
| `status` | GameStatus | Current game status |
| `enPassantTarget` | Position \| null | Available en passant target |
| `halfMoveClock` | number | Moves since capture/pawn move |
| `fullMoveNumber` | number | Full move counter |
#### Methods
##### recordMove()
Record a move in history.
```javascript
recordMove(move: Move): void
```
##### getLastMove()
Get the most recent move.
```javascript
getLastMove(): Move | null
```
##### undo()
Undo to previous state.
```javascript
undo(): Move | null
```
**Returns:** Undone move or null
##### redo()
Redo to next state.
```javascript
redo(): Move | null
```
**Returns:** Redone move or null
##### toFEN()
Export full game state to FEN.
```javascript
toFEN(board: Board, currentTurn: Color): string
```
**Returns:** Complete FEN string
##### toPGN()
Export game to PGN notation.
```javascript
toPGN(metadata?: PGNMetadata): string
```
**Parameters:**
- `metadata` (optional): Game metadata
- `event`: string
- `site`: string
- `date`: string
- `white`: string
- `black`: string
- `result`: string
**Returns:** PGN formatted string
**Example:**
```javascript
const pgn = gameState.toPGN({
event: "Casual Game",
white: "Player 1",
black: "Player 2",
date: "2025.01.22"
});
```
---
## Piece Classes
### Piece (Abstract Base Class)
Base class for all chess pieces.
#### Constructor
```javascript
new Piece(color: Color, position: Position)
```
**Parameters:**
- `color`: 'white' or 'black'
- `position`: {row: number, col: number}
#### Properties
| Property | Type | Description |
|----------|------|-------------|
| `color` | 'white' \| 'black' | Piece color |
| `position` | Position | Current position |
| `type` | PieceType | Type of piece |
| `hasMoved` | boolean | Has piece moved |
#### Methods
##### getValidMoves()
Get all valid moves (without check validation).
```javascript
getValidMoves(board: Board): Position[]
```
**Returns:** Array of valid positions
##### isValidMove()
Check if move to position is valid.
```javascript
isValidMove(board: Board, toRow: number, toCol: number): boolean
```
##### clone()
Create copy of piece.
```javascript
clone(): Piece
```
##### getSymbol()
Get Unicode symbol for piece.
```javascript
getSymbol(): string
```
**Returns:** Unicode chess symbol (♔, ♕, ♖, etc.)
---
### Pawn
Implements pawn-specific movement and rules.
#### Methods
##### getValidMoves()
```javascript
getValidMoves(board: Board): Position[]
```
**Special behavior:**
- Forward 1 or 2 squares from starting position
- Diagonal captures
- En passant (handled separately)
- Promotion at last rank
**Example:**
```javascript
const pawn = new Pawn('white', {row: 6, col: 4});
const moves = pawn.getValidMoves(board);
// [{row: 5, col: 4}, {row: 4, col: 4}] if starting position
```
---
### Knight
Implements knight movement (L-shaped).
#### Methods
##### getValidMoves()
```javascript
getValidMoves(board: Board): Position[]
```
**Movement pattern:** 2 squares in one direction, 1 square perpendicular
---
### Bishop
Implements bishop movement (diagonals).
#### Methods
##### getValidMoves()
```javascript
getValidMoves(board: Board): Position[]
```
**Movement pattern:** Any number of squares diagonally
---
### Rook
Implements rook movement (straight lines).
#### Methods
##### getValidMoves()
```javascript
getValidMoves(board: Board): Position[]
```
**Movement pattern:** Any number of squares horizontally or vertically
---
### Queen
Implements queen movement (rook + bishop).
#### Methods
##### getValidMoves()
```javascript
getValidMoves(board: Board): Position[]
```
**Movement pattern:** Combination of rook and bishop
---
### King
Implements king movement and castling.
#### Methods
##### getValidMoves()
```javascript
getValidMoves(board: Board): Position[]
```
**Movement pattern:** One square in any direction
##### canCastle()
Check if castling is possible.
```javascript
canCastle(board: Board, side: 'kingside' | 'queenside'): boolean
```
---
## Move System
### MoveValidator
Static methods for move validation.
#### Methods
##### isMoveLegal()
Validate if move is legal (including check).
```javascript
static isMoveLegal(
board: Board,
piece: Piece,
toRow: number,
toCol: number,
gameState: GameState
): boolean
```
##### isKingInCheck()
Check if king is under attack.
```javascript
static isKingInCheck(board: Board, color: Color): boolean
```
##### isCheckmate()
Check if position is checkmate.
```javascript
static isCheckmate(board: Board, color: Color): boolean
```
##### isStalemate()
Check if position is stalemate.
```javascript
static isStalemate(board: Board, color: Color): boolean
```
##### hasAnyLegalMove()
Check if player has any legal moves.
```javascript
static hasAnyLegalMove(board: Board, color: Color): boolean
```
---
### SpecialMoves
Handles special chess moves.
#### Methods
##### canCastle()
Check if castling is legal.
```javascript
static canCastle(
board: Board,
king: King,
rook: Rook,
side: 'kingside' | 'queenside'
): boolean
```
##### executeCastle()
Execute castling move.
```javascript
static executeCastle(
board: Board,
king: King,
rook: Rook,
side: 'kingside' | 'queenside'
): void
```
##### canEnPassant()
Check if en passant is legal.
```javascript
static canEnPassant(
board: Board,
pawn: Pawn,
targetCol: number,
gameState: GameState
): boolean
```
##### executeEnPassant()
Execute en passant capture.
```javascript
static executeEnPassant(
board: Board,
pawn: Pawn,
targetRow: number,
targetCol: number
): Piece
```
**Returns:** Captured pawn
##### canPromote()
Check if pawn can be promoted.
```javascript
static canPromote(pawn: Pawn): boolean
```
##### executePiece promotion()
Promote pawn to another piece.
```javascript
static promote(
board: Board,
pawn: Pawn,
pieceType: 'queen' | 'rook' | 'bishop' | 'knight'
): Piece
```
**Returns:** New promoted piece
---
## UI Components
### BoardRenderer
Renders the chess board to DOM.
#### Constructor
```javascript
new BoardRenderer(boardElement: HTMLElement, config?: RendererConfig)
```
**Parameters:**
- `boardElement`: DOM element to render board into
- `config` (optional):
- `showCoordinates`: boolean - Show rank/file labels
- `pieceStyle`: 'symbols' | 'images' - Piece rendering style
- `highlightLastMove`: boolean - Highlight last move
#### Methods
##### renderBoard()
Render complete board state.
```javascript
renderBoard(board: Board, gameState: GameState): void
```
##### highlightMoves()
Highlight legal moves for a piece.
```javascript
highlightMoves(moves: Position[]): void
```
##### clearHighlights()
Remove all move highlights.
```javascript
clearHighlights(): void
```
##### selectSquare()
Select a square.
```javascript
selectSquare(row: number, col: number): void
```
##### deselectSquare()
Deselect current square.
```javascript
deselectSquare(): void
```
##### updateSquare()
Update a single square.
```javascript
updateSquare(row: number, col: number, piece: Piece | null): void
```
---
### DragDropHandler
Handles drag-and-drop interactions.
#### Constructor
```javascript
new DragDropHandler(game: ChessGame, renderer: BoardRenderer)
```
#### Methods
##### enable()
Enable drag-and-drop.
```javascript
enable(): void
```
##### disable()
Disable drag-and-drop.
```javascript
disable(): void
```
#### Events
Emits custom events on board element:
- `piece-drag-start`: Piece drag started
- `piece-drag-over`: Piece dragged over square
- `piece-drop`: Piece dropped
- `piece-drag-end`: Drag ended
---
### UIController
Manages all UI state and interactions.
#### Constructor
```javascript
new UIController(game: ChessGame)
```
#### Methods
##### init()
Initialize UI components.
```javascript
init(): void
```
##### updateGameStatus()
Update game status display.
```javascript
updateGameStatus(status: GameStatus, message?: string): void
```
##### showPromotionDialog()
Show pawn promotion piece selection.
```javascript
showPromotionDialog(callback: (pieceType: PieceType) => void): void
```
##### updateMoveHistory()
Update move history display.
```javascript
updateMoveHistory(moves: Move[]): void
```
##### updateCapturedPieces()
Update captured pieces display.
```javascript
updateCapturedPieces(captured: CapturedPieces): void
```
---
## Utilities
### Notation
Chess notation utilities.
#### Methods
##### positionToAlgebraic()
Convert position to algebraic notation.
```javascript
static positionToAlgebraic(row: number, col: number): string
```
**Example:**
```javascript
positionToAlgebraic(7, 4); // "e1"
positionToAlgebraic(0, 0); // "a8"
```
##### algebraicToPosition()
Convert algebraic notation to position.
```javascript
static algebraicToPosition(notation: string): Position
```
**Example:**
```javascript
algebraicToPosition("e4"); // {row: 4, col: 4}
```
##### moveToNotation()
Convert move to standard notation.
```javascript
static moveToNotation(move: Move, board: Board): string
```
**Example:**
```javascript
moveToNotation(move, board); // "Nf3", "Qxe5+", "O-O", etc.
```
---
### Storage
LocalStorage wrapper for game persistence.
#### Methods
##### save()
Save game state.
```javascript
static save(game: ChessGame, slotName: string = 'auto'): void
```
##### load()
Load game state.
```javascript
static load(slotName: string = 'auto'): SavedGame | null
```
**Returns:**
```javascript
{
fen: string,
pgn: string,
timestamp: number
}
```
##### list()
List all saved games.
```javascript
static list(): string[]
```
**Returns:** Array of save slot names
##### delete()
Delete saved game.
```javascript
static delete(slotName: string): void
```
---
## Events
### Game Events
The ChessGame instance emits events via EventTarget interface.
#### Available Events
##### move
Fired when a move is made.
```javascript
game.addEventListener('move', (event) => {
console.log('Move:', event.detail.move);
console.log('Result:', event.detail.result);
});
```
**Event Detail:**
```javascript
{
move: Move,
result: MoveResult
}
```
##### check
Fired when a king is in check.
```javascript
game.addEventListener('check', (event) => {
console.log('King in check:', event.detail.color);
});
```
##### checkmate
Fired when checkmate occurs.
```javascript
game.addEventListener('checkmate', (event) => {
console.log('Winner:', event.detail.winner);
});
```
##### stalemate
Fired when stalemate occurs.
```javascript
game.addEventListener('stalemate', () => {
console.log('Game ended in stalemate');
});
```
##### promotion
Fired when pawn promotion is available.
```javascript
game.addEventListener('promotion', (event) => {
// Show promotion dialog
showPromotionDialog(event.detail.pawn);
});
```
---
## Data Structures
### Types
```javascript
type Color = 'white' | 'black';
type PieceType = 'pawn' | 'knight' | 'bishop' | 'rook' | 'queen' | 'king';
type GameStatus = 'active' | 'check' | 'checkmate' | 'stalemate' | 'draw' | 'resigned';
interface Position {
row: number; // 0-7
col: number; // 0-7
}
interface Move {
from: Position;
to: Position;
piece: Piece;
captured?: Piece;
notation: string;
special?: 'castle-kingside' | 'castle-queenside' | 'en-passant' | 'promotion';
promotedTo?: PieceType;
timestamp: number;
}
interface MoveResult {
success: boolean;
move?: Move;
error?: string;
gameStatus?: GameStatus;
}
interface CapturedPieces {
white: Piece[];
black: Piece[];
}
interface GameConfig {
autoSave?: boolean;
enableTimer?: boolean;
timeControl?: number;
}
interface RendererConfig {
showCoordinates?: boolean;
pieceStyle?: 'symbols' | 'images';
highlightLastMove?: boolean;
}
interface PGNMetadata {
event?: string;
site?: string;
date?: string;
white?: string;
black?: string;
result?: string;
}
interface SavedGame {
fen: string;
pgn: string;
timestamp: number;
}
```
---
## Usage Examples
### Basic Game Setup
```javascript
import { ChessGame } from './js/game/ChessGame.js';
import { UIController } from './js/ui/UIController.js';
// Create game instance
const game = new ChessGame({
autoSave: true
});
// Initialize UI
const ui = new UIController(game);
ui.init();
// Listen for game events
game.addEventListener('move', (e) => {
console.log('Move made:', e.detail.move.notation);
});
game.addEventListener('checkmate', (e) => {
alert(`Checkmate! ${e.detail.winner} wins!`);
});
```
### Making Moves Programmatically
```javascript
// Make a move
const result = game.makeMove(6, 4, 4, 4); // e2 to e4
if (result.success) {
console.log('Move successful');
if (result.gameStatus === 'check') {
console.log('Check!');
}
} else {
console.error('Invalid move:', result.error);
}
```
### Save and Load
```javascript
// Save game
GameStorage.save(game.gameState, game.board);
// Load game
const saved = GameStorage.load();
if (saved) {
game.gameState.fromFEN(saved.fen);
}
```
### Custom Event Handling
```javascript
// Handle piece promotion
game.addEventListener('promotion', (event) => {
const pawn = event.detail.pawn;
// Show UI dialog
ui.showPromotionDialog((pieceType) => {
SpecialMoves.promote(game.board, pawn, pieceType);
});
});
```
---
## Error Handling
All methods that can fail return result objects or throw descriptive errors:
```javascript
try {
const result = game.makeMove(6, 4, 4, 4);
if (!result.success) {
console.error('Move failed:', result.error);
// Possible errors:
// - "No piece at source position"
// - "Not your turn"
// - "Invalid move for this piece"
// - "Move would leave king in check"
}
} catch (error) {
console.error('Unexpected error:', error);
}
```
---
## Performance Considerations
- **Move Validation**: Cached when possible, invalidated on board changes
- **Board Cloning**: Deep copy only when necessary (undo/check simulation)
- **DOM Updates**: Batched and debounced to minimize reflows
- **Event Handling**: Use event delegation for board squares
---
## Browser Compatibility
Minimum requirements:
- ES6+ support
- Drag and Drop API
- LocalStorage API
- CSS Grid
Supported browsers:
- Chrome 60+
- Firefox 54+
- Safari 10.1+
- Edge 79+
---
**For implementation examples, see [IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md)**