Quick Start Guide - RumenDamyanov/go-chess GitHub Wiki

Quick Start Guide

Get up and running with go-chess in just 5 minutes! This guide will help you install the library, create your first chess game, and make some moves.

Prerequisites

  • Go 1.21 or later
  • Basic knowledge of Go programming

Installation

Install the Library

go mod init my-chess-app
go get github.com/rumendamyanov/go-chess

Verify Installation

Create a simple test file to verify everything works:

// main.go
package main

import (
    "fmt"
    "github.com/rumendamyanov/go-chess/engine"
)

func main() {
    game := engine.NewGame()
    fmt.Println("Chess game created successfully!")
    fmt.Println(game.Board().String())
}

Run it:

go run main.go

You should see the initial chess board position!

Your First Chess Game

Let's create a simple interactive chess game:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/rumendamyanov/go-chess/ai"
    "github.com/rumendamyanov/go-chess/engine"
)

func main() {
    // Create a new chess game
    game := engine.NewGame()

    // Create an AI opponent
    aiPlayer := ai.NewRandomAI()
    aiPlayer.SetDifficulty(ai.DifficultyEasy)

    fmt.Println("Welcome to Go Chess!")
    fmt.Println("Starting position:")
    fmt.Println(game.Board().String())
    fmt.Println()

    // Make a player move
    fmt.Println("Making move: e2-e4")
    move, err := game.ParseMove("e2e4")
    if err != nil {
        log.Fatal("Invalid move:", err)
    }

    if err := game.MakeMove(move); err != nil {
        log.Fatal("Could not make move:", err)
    }

    fmt.Println("After player move:")
    fmt.Println(game.Board().String())
    fmt.Println()

    // Get AI response
    fmt.Println("AI is thinking...")
    ctx := context.Background()
    aiMove, err := aiPlayer.GetBestMove(ctx, game)
    if err != nil {
        log.Fatal("AI error:", err)
    }

    if err := game.MakeMove(aiMove); err != nil {
        log.Fatal("Could not make AI move:", err)
    }

    fmt.Printf("AI played: %s\n", aiMove.String())
    fmt.Println("Board after AI move:")
    fmt.Println(game.Board().String())
}

HTTP API Server

Want to create a chess API? Here's a minimal server:

package main

import (
    "log"

    "github.com/gin-gonic/gin"
    "github.com/rumendamyanov/go-chess/api"
    "github.com/rumendamyanov/go-chess/config"
)

func main() {
    // Create configuration
    cfg := config.Default()

    // Create API server
    server := api.NewServer(cfg)

    // Setup routes
    r := gin.Default()
    server.SetupRoutes(r)

    // Start server
    log.Println("Chess API server starting on :8080")
    if err := r.Run(":8080"); err != nil {
        log.Fatal("Failed to start server:", err)
    }
}

Test the API:

# Create a new game
curl -X POST http://localhost:8080/api/games

# Make a move
curl -X POST http://localhost:8080/api/games/1/moves \
  -H "Content-Type: application/json" \
  -d '{"from": "e2", "to": "e4"}'

# Get AI move
curl -X POST http://localhost:8080/api/games/1/ai-move \
  -H "Content-Type: application/json" \
  -d '{"difficulty": "easy"}'

LLM AI Integration (Optional)

To use advanced LLM AI opponents, you'll need API keys. Create a config file:

{
  "llm_ai": {
    "enabled": true,
    "default_provider": "openai",
    "providers": {
      "openai": {
        "api_key": "sk-your-openai-key",
        "model": "gpt-4o",
        "enabled": true
      }
    }
  }
}

Then use it in your code:

// Request LLM AI move
curl -X POST http://localhost:8080/api/games/1/ai-move \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "llm",
    "provider": "openai",
    "level": "medium"
  }'

// Chat with AI
curl -X POST http://localhost:8080/api/games/1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Good opening move!",
    "provider": "openai"
  }'

Next Steps

Now that you have the basics working:

  1. Learn More: Check out Basic Usage for detailed examples
  2. AI Features: Explore AI Integration for advanced AI opponents
  3. API Documentation: See API Reference for complete endpoint docs
  4. Advanced Features: Read Advanced Usage for production features

Common Issues

Import Errors

Make sure you have the correct module path:

go mod tidy

Port Already in Use

Change the port in your server configuration:

cfg.Server.Port = 8081

Invalid Moves

Use standard algebraic notation:

  • e2e4 (pawn to e4)
  • Nf3 (knight to f3)
  • O-O (kingside castling)

Need Help?

Happy chess coding! ♟️