From 625262d7896c400e11dcfb52a51c3ce684d17f1f Mon Sep 17 00:00:00 2001 From: bereck-work Date: Tue, 25 Nov 2025 21:20:08 +0000 Subject: [PATCH] (Fix): Rewrote Readme because why not ( gemini made a very weird readme.md ) --- README.md | 314 ++++++++++++++++++++---------------------------------- 1 file changed, 117 insertions(+), 197 deletions(-) diff --git a/README.md b/README.md index 427c8c3..6470758 100644 --- a/README.md +++ b/README.md @@ -1,254 +1,174 @@ -# 🎮 Termdoku +# Termdoku -**A beautiful, feature-rich terminal-based Sudoku game.** +A sleek, terminal-based Sudoku game built with Go. Play Sudoku right in your terminal with a beautiful interface, multiple difficulty levels, and full theme customization. -![License](https://img.shields.io/badge/license-MIT-blue.svg) -![Go Version](https://img.shields.io/badge/go-%3E%3D1.21-00ADD8.svg) +## Features -## ✨ Features +- **Multiple Difficulty Levels**: Easy, Normal, Hard, and Lunatic modes to challenge players of all skill levels +- **Daily Puzzles**: Get a new puzzle every day to keep your mind sharp +- **Smart Gameplay**: Auto-check for conflicts, timer support, and intuitive controls +- **Beautiful Themes**: Ships with Solarized Light and Dracula themes, plus support for custom themes +- **Profile System**: Track your stats, achievements, and compete on the leaderboard +- **Persistent Progress**: Save and resume your games anytime +- **Cross-Platform**: Works on Linux, macOS, Windows, and FreeBSD -### 🎯 Core Gameplay +## Installation -- **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 +### Pre-built Binaries -### 🧩 Advanced Puzzle Generation +Download the latest release for your platform from the `dist/` directory: -- **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 +```bash +# Linux (amd64) +./dist/termdoku-linux-amd64 -### 📊 Statistics & Progress +# macOS (Apple Silicon) +./dist/termdoku-darwin-arm64 -- **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 +# Windows +./dist/termdoku-windows-amd64.exe +``` ### Build from Source +Make sure you have Go 1.24+ installed: + ```bash # Clone the repository git clone https://gitlab.com/bereckobrian/termdoku.git cd termdoku +# Build for your current platform make build -# Run -./termdoku +# Or build for all platforms +make build-all + +# Install to your system +make install ``` -### Using Go Install +## Usage + +Simply run the binary to start the game: ```bash -go install github.com/bereckobrian/termdoku/cmd/termdoku@latest +termdoku ``` -## 🎮 How to Play - ### Controls -#### Menu Navigation +- **Arrow Keys / hjkl**: Navigate the grid +- **1-9**: Enter numbers +- **Backspace / 0**: Clear cell +- **?**: Show help +- **q**: Quit game +- **m**: Return to main menu -- `↑/↓` 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 +Navigate through the main menu to: -#### In-Game +- Start a new game with your preferred difficulty +- Resume saved games +- View your profile (stats, achievements, leaderboard) +- Access the database of completed puzzles -- `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 +## Configuration -### Game Modes +Termdoku stores its configuration in `~/.termdoku/config.yaml`. You can customize: -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 +```yaml +theme: "dark" # Options: "light", "dark", "auto", or custom theme name +autoCheck: true # Automatically highlight conflicts +timerEnabled: true # Show game timer +bindings: {} # Custom key bindings (optional) ``` -## 🔧 Advanced Features +## Custom Themes -### Puzzle Generation API +One of the coolest features of Termdoku is the ability to create your own themes using TOML files. -The generator package provides advanced puzzle generation capabilities: +### Creating a Custom Theme -```go -import "termdoku/internal/generator" +1. On first run, Termdoku creates an example theme at `~/.termdoku/themes/example.toml` +2. Create a new `.toml` file in `~/.termdoku/themes/` with your theme name (e.g., `mytheme.toml`) +3. Define your color palette: -// Generate a puzzle with specific difficulty -puzzle, err := generator.Generate(generator.Hard, "seed") +```toml +Name = "mytheme" -// 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) +[Palette] +Background = "#1a1b26" +Foreground = "#c0caf5" +GridLine = "#414868" +CellBaseBG = "" +CellBaseFG = "#c0caf5" +CellFixedFG = "#565f89" +CellFixedBG = "" +CellSelectedBG = "#283457" +CellSelectedFG = "#7dcfff" +CellDuplicateBG = "#2e2a2d" +CellConflictBG = "#3b2e3a" +Accent = "#7aa2f7" ``` -### Puzzle Analysis +4. Update your config to use the theme: -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 - -```go -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) +```yaml +theme: "mytheme" ``` -## 📊 Data Storage +### Color Fields Explained -Termdoku stores data in `~/.termdoku/`: +- **Background/Foreground**: Main terminal colors +- **GridLine**: Color of the Sudoku grid lines +- **CellBaseBG/FG**: Colors for empty cells you can edit +- **CellFixedBG/FG**: Colors for pre-filled cells (the puzzle clues) +- **CellSelectedBG/FG**: Colors for the currently selected cell +- **CellDuplicateBG**: Highlight color when you have duplicate numbers +- **CellConflictBG**: Highlight color for invalid placements +- **Accent**: Accent color used throughout the UI -- `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 +All colors should be in hex format (e.g., `#ff5555`). Leave fields empty (`""`) to use the terminal default. -## 🎨 Themes +## Data Storage -Create custom themes in `~/.termdoku/themes/`: +Termdoku stores all its data in `~/.termdoku/`: -```json -{ - "name": "My Theme", - "palette": { - "background": "#1a1b26", - "foreground": "#c0caf5", - "accent": "#7aa2f7", - "error": "#f7768e", - "success": "#9ece6a", - "warning": "#e0af68" - } -} +```bash +~/.termdoku/ +├── config.yaml # Your configuration +├── termdoku.db # SQLite database (stats, achievements, games) +└── themes/ # Custom theme files + ├── example.toml + └── mytheme.toml ``` -## 🤝 Contributing +## Development -Contributions are welcome! Please feel free to submit a Pull Request. +```bash -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 +# Format code +make fmt -## 📝 License +# Run linter +make lint -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +# Build for all platforms +make build-all +``` -## 🙏 Acknowledgments +## License -- Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) - A powerful TUI framework -- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Style definitions for nice terminal layouts \ No newline at end of file +MIT License - see [LICENSE](LICENSE) for details. + +## Credits + +Built with: + +- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - Terminal UI framework +- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Style definitions +- [SQLite](https://modernc.org/sqlite) - Database + +--- + +Enjoy playing Sudoku in your terminal! If you create a cool theme, feel free to share it.