Table of Contents

• Quick Start
• For Offline Play (vs Stockfish AI)
  • Easy Installation (Recommended)
  • Manual Installation
  • Verify Installation
• Command Line Options
• Creating Custom Themes
• NPM Scripts
• Server Configuration
• Troubleshooting
• Data Storage Location

Quick Start

# Install the game globally
npm install -g chess-arena

# Start playing
chess-arena

Alternative: If the chess-arena command isn't recognized, use npx chess-arena instead.

For Offline Play (vs Stockfish AI)

To play offline against the computer, you need to install the Stockfish chess engine.

Easy Installation (Recommended)

Chess Arena includes an installation helper:

# Run the built-in installer
install-stockfish

Manual Installation

If you prefer to install Stockfish manually, follow the official instructions at Stockfish Installation Guide.

Verify Installation

stockfish --version

Command Line Options

| Command | Description | | ------------------------------- | -------------------------------------------- | | chess-arena | Start the game with default settings | | chess-arena -l | List all available themes with descriptions | | chess-arena -p | Preview all themes with sample boards | | chess-arena -t <theme> | Set board theme | | chess-arena -s <url> | Set custom server URL (e.g., localhost:3000) | | chess-arena -h | Show comprehensive help message | | chess-arena -c | Show current saved configuration | | chess-arena -r | Reset all settings to defaults | | chess-arena --sound <on\|off> | Enable or disable sound effects | | install-stockfish | Install Stockfish for offline play |

Creating Custom Themes

Add new themes to themes/index.js:

newTheme: {
  name: "Theme Name",
  description: "Theme description",
  lightSquare: "#hex-color",
  darkSquare: "#hex-color",
  whitePieces: "#hex-color",
  blackPieces: "#hex-color",
  borderColor: "chalk-color",
  pieces: {
    white: { k: "♔", q: "♕", r: "♖", b: "♗", n: "♘", p: "♙" },
    black: { k: "♚", q: "♛", r: "♜", b: "♝", n: "♞", p: "♟" }
  }
}

NPM Scripts

npm start               # Start the game
npm run dev            # Start with file watching
npm run themes         # List available themes
npm run preview        # Preview all themes
npm run install-stockfish  # Install Stockfish engine
npm run server         # Start the multiplayer server
npm run server:dev     # Start server in development mode

Server Configuration

Chess Arena's online multiplayer is powered by a server hosted on Hack Club's Nest, connecting by default to http://chess.bilalkhan.hackclub.app:3456.

Switch to Local Server:

# Start local server
npm run server

# Configure client to use localhost
chess-arena -s http://localhost:3000

# Or for development mode
npm run server:dev
chess-arena -s http://localhost:3000

Switch Back to Deployed Server:

chess-arena -s http://chess.bilalkhan.hackclub.app:3456

Check Current Server:

chess-arena -c

Troubleshooting

Command Not Recognized

If you get the error 'chess-arena' is not recognized as an internal or external command (Windows) or command not found: chess-arena (Mac/Linux):

Quick Fix:

npx chess-arena

Why this happens: This is a PATH configuration issue. Your system isn't configured to find globally installed npm packages. This is more common on Windows but can occur on Mac/Linux too.

Permanent Fix (Optional):

1. Find npm's global directory:

   npm config get prefix

2. Add that path to your system PATH:
   • Windows: Environment Variables in System Properties
   • Mac/Linux: Add to ~/.bashrc, ~/.zshrc, or ~/.profile
3. Restart your terminal

Bottom line: npx chess-arena works perfectly and is a valid way to run the application!

Data Storage Location

Chess Arena stores all user data in a single directory:

• Linux/Mac: ~/.chess-arena/
• Windows: C:\Users\YourName\.chess-arena\

This includes:

• config.json - Settings and preferences
• saved_games/ - Automatically exported PGN files from completed games