termdoku/README.md

🎮 Termdoku

A beautiful, feature-rich terminal-based Sudoku game.

✨ Features

🎯 Core Gameplay

• Multiple Difficulty Levels: Easy, Normal, Hard, Expert, and Lunatic
• Daily Puzzles: New puzzle every day with consistent seeds
• Smart Hint System: Intelligent hints using solving techniques (Naked Singles, Hidden Singles)
• Auto-Check Mode: Optional real-time validation of moves
• Timer: Track your solving time
• Undo/Redo: Full move history support

🧩 Advanced Puzzle Generation

• Unique Solution Guarantee: All puzzles have exactly one solution
• Symmetry Patterns: Support for rotational, vertical, and horizontal symmetry
• Puzzle Analysis: Comprehensive difficulty rating and analysis
• Custom Generation: Create puzzles with custom parameters
• Pattern Detection: Identifies required solving techniques
• Optimized Solver: Uses most-constrained-first heuristic for fast solving

📊 Statistics & Progress

• Comprehensive Stats: Track games played, win rate, streaks, and more
• Best Times: Personal records for each difficulty level
• Leaderboard: Top 5 fastest times per difficulty
• Daily History: Track your daily puzzle completions
• Recent Games: View your last 50 games

🏆 Achievement System

• 8 Unique Achievements: Unlock achievements as you play
• Progress Tracking: See your progress toward each achievement
• Visual Indicators: Beautiful UI showing locked/unlocked status
• Achievements Include:
  • 🏆 First Victory - Complete your first puzzle
  • ⚡ Speed Demon - Complete an Easy puzzle in under 3 minutes
  • 💎 Perfectionist - Complete a puzzle without using hints
  • 🔥 Streak Master - Achieve a 5-day streak
  • 💯 Century Club - Complete 100 puzzles
  • 🌙 Lunatic Legend - Complete 10 Lunatic puzzles
  • 📅 Daily Devotee - Complete 30 daily puzzles
  • ✨ Flawless - Complete a Hard puzzle without auto-check

🎨 Customization

• Theme Support: Customizable color themes
• Adaptive Colors: Dynamic color schemes for different UI elements
• Gradient Effects: Beautiful gradient text and borders
• Configurable Settings: Auto-check, timer, and more

💾 Data Persistence

• SQLite Database: Robust data storage for games and achievements
• JSON Stats: Human-readable statistics files
• Save Games: Resume puzzles later
• Cross-Session: All data persists between sessions

📦 Installation

Prerequisites

• Go 1.21 or higher

Build from Source

# Clone the repository
git clone https://gitlab.com/bereckobrian/termdoku.git
cd termdoku

make build

# Run
./termdoku

Using Go Install

go install github.com/bereckobrian/termdoku/cmd/termdoku@latest

🎮 How to Play

Controls

Menu Navigation

• ↑/↓ or k/j - Navigate menu items
• ←/→ or h/l - Navigate menu items (horizontal)
• Enter - Select menu item
• a - Toggle auto-check mode
• t - Toggle timer
• q - Quit

In-Game

• Arrow Keys or h/j/k/l - Move cursor
• 1-9 - Enter number
• 0 or Backspace - Clear cell
• n - Toggle notes mode
• u - Undo move
• r - Redo move
• ? or h - Get hint
• c - Check solution
• s - Solve puzzle
• m or Esc - Return to menu
• q - Quit game

Game Modes

1. Easy - 38 empty cells, perfect for beginners
2. Normal - 46 empty cells, balanced difficulty
3. Hard - 52 empty cells, challenging puzzles
4. Expert - 56 empty cells, very difficult
5. Lunatic - 60 empty cells, extreme challenge
6. Daily - One puzzle per day, same for everyone

🏗️ Project Structure

termdoku/
├── cmd/
│   └── termdoku/          # Main application entry point
├── internal/
│   ├── achievements/      # Achievement system
│   ├── config/           # Configuration management
│   ├── database/         # SQLite database layer
│   ├── game/             # Game board logic
│   ├── generator/        # Puzzle generation engine
│   │   ├── api.go       # Grid analysis & validation
│   │   ├── core.go      # Generation algorithms
│   │   ├── generator.go # Main generation interface
│   │   ├── benchmark.go # Performance benchmarking
│   │   └── utils.go     # Utility functions
│   ├── savegame/         # Save/load game state
│   ├── solver/           # Sudoku solver
│   ├── stats/            # Statistics tracking
│   ├── theme/            # Theme system
│   └── ui/               # Terminal UI (Bubble Tea)
├── go.mod
├── go.sum
├── LICENSE
├── Makefile
└── README.md

🔧 Advanced Features

Puzzle Generation API

The generator package provides advanced puzzle generation capabilities:

import "termdoku/internal/generator"

// Generate a puzzle with specific difficulty
puzzle, err := generator.Generate(generator.Hard, "seed")

// Generate with symmetry
puzzle, err := generator.GenerateWithSymmetry(
    generator.Normal, 
    "seed", 
    generator.SymmetryRotational180,
)

// Generate with analysis
result, err := generator.GenerateWithAnalysis(generator.Expert, "seed")
fmt.Printf("Difficulty Rating: %d/100\n", generator.RatePuzzle(result.Puzzle))

// Analyze a puzzle
analysis := puzzle.Analyze()
fmt.Printf("Symmetry: %s\n", analysis.SymmetryType)
fmt.Printf("Techniques: %v\n", analysis.SolvingTechniques)

Puzzle Analysis

Every puzzle can be analyzed for:

• Filled/Empty cells count
• Candidate distribution (min, max, average)
• Solution uniqueness
• Estimated difficulty
• Required solving techniques
• Symmetry pattern
• Complexity score

Benchmarking

import "termdoku/internal/generator"

// Benchmark generation performance
result := generator.BenchmarkGeneration(generator.Hard, 10)
fmt.Println(result.String())

// Compare generation methods
standard, symmetric := generator.CompareGenerationMethods(generator.Normal, 10)

📊 Data Storage

Termdoku stores data in ~/.termdoku/:

• termdoku.db - SQLite database (games, achievements, stats)
• stats.json - Statistics backup (JSON format)
• achievements.json - Achievements backup (JSON format)
• config.json - User configuration
• themes/ - Custom theme files

🎨 Themes

Create custom themes in ~/.termdoku/themes/:

{
  "name": "My Theme",
  "palette": {
    "background": "#1a1b26",
    "foreground": "#c0caf5",
    "accent": "#7aa2f7",
    "error": "#f7768e",
    "success": "#9ece6a",
    "warning": "#e0af68"
  }
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Bubble Tea - A powerful TUI framework
• Lipgloss - Style definitions for nice terminal layouts