(Fix): Rewrote Readme because why not ( gemini made a very weird readme.md )
This commit is contained in:
314
README.md
314
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.
|
||||||
|
|
||||||
|
## 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
|
### Pre-built Binaries
|
||||||
- **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
|
Download the latest release for your platform from the `dist/` directory:
|
||||||
|
|
||||||
- **Unique Solution Guarantee**: All puzzles have exactly one solution
|
```bash
|
||||||
- **Symmetry Patterns**: Support for rotational, vertical, and horizontal symmetry
|
# Linux (amd64)
|
||||||
- **Puzzle Analysis**: Comprehensive difficulty rating and analysis
|
./dist/termdoku-linux-amd64
|
||||||
- **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
|
# macOS (Apple Silicon)
|
||||||
|
./dist/termdoku-darwin-arm64
|
||||||
|
|
||||||
- **Comprehensive Stats**: Track games played, win rate, streaks, and more
|
# Windows
|
||||||
- **Best Times**: Personal records for each difficulty level
|
./dist/termdoku-windows-amd64.exe
|
||||||
- **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
|
### Build from Source
|
||||||
|
|
||||||
|
Make sure you have Go 1.24+ installed:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone the repository
|
# Clone the repository
|
||||||
git clone https://gitlab.com/bereckobrian/termdoku.git
|
git clone https://gitlab.com/bereckobrian/termdoku.git
|
||||||
cd termdoku
|
cd termdoku
|
||||||
|
|
||||||
|
# Build for your current platform
|
||||||
make build
|
make build
|
||||||
|
|
||||||
# Run
|
# Or build for all platforms
|
||||||
./termdoku
|
make build-all
|
||||||
|
|
||||||
|
# Install to your system
|
||||||
|
make install
|
||||||
```
|
```
|
||||||
|
|
||||||
### Using Go Install
|
## Usage
|
||||||
|
|
||||||
|
Simply run the binary to start the game:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
go install github.com/bereckobrian/termdoku/cmd/termdoku@latest
|
termdoku
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🎮 How to Play
|
|
||||||
|
|
||||||
### Controls
|
### 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
|
Navigate through the main menu to:
|
||||||
- `←/→` or `h/l` - Navigate menu items (horizontal)
|
|
||||||
- `Enter` - Select menu item
|
|
||||||
- `a` - Toggle auto-check mode
|
|
||||||
- `t` - Toggle timer
|
|
||||||
- `q` - Quit
|
|
||||||
|
|
||||||
#### 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
|
## Configuration
|
||||||
- `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
|
Termdoku stores its configuration in `~/.termdoku/config.yaml`. You can customize:
|
||||||
|
|
||||||
1. **Easy** - 38 empty cells, perfect for beginners
|
```yaml
|
||||||
2. **Normal** - 46 empty cells, balanced difficulty
|
theme: "dark" # Options: "light", "dark", "auto", or custom theme name
|
||||||
3. **Hard** - 52 empty cells, challenging puzzles
|
autoCheck: true # Automatically highlight conflicts
|
||||||
4. **Expert** - 56 empty cells, very difficult
|
timerEnabled: true # Show game timer
|
||||||
5. **Lunatic** - 60 empty cells, extreme challenge
|
bindings: {} # Custom key bindings (optional)
|
||||||
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
|
## 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
|
1. On first run, Termdoku creates an example theme at `~/.termdoku/themes/example.toml`
|
||||||
import "termdoku/internal/generator"
|
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
|
```toml
|
||||||
puzzle, err := generator.Generate(generator.Hard, "seed")
|
Name = "mytheme"
|
||||||
|
|
||||||
// Generate with symmetry
|
[Palette]
|
||||||
puzzle, err := generator.GenerateWithSymmetry(
|
Background = "#1a1b26"
|
||||||
generator.Normal,
|
Foreground = "#c0caf5"
|
||||||
"seed",
|
GridLine = "#414868"
|
||||||
generator.SymmetryRotational180,
|
CellBaseBG = ""
|
||||||
)
|
CellBaseFG = "#c0caf5"
|
||||||
|
CellFixedFG = "#565f89"
|
||||||
// Generate with analysis
|
CellFixedBG = ""
|
||||||
result, err := generator.GenerateWithAnalysis(generator.Expert, "seed")
|
CellSelectedBG = "#283457"
|
||||||
fmt.Printf("Difficulty Rating: %d/100\n", generator.RatePuzzle(result.Puzzle))
|
CellSelectedFG = "#7dcfff"
|
||||||
|
CellDuplicateBG = "#2e2a2d"
|
||||||
// Analyze a puzzle
|
CellConflictBG = "#3b2e3a"
|
||||||
analysis := puzzle.Analyze()
|
Accent = "#7aa2f7"
|
||||||
fmt.Printf("Symmetry: %s\n", analysis.SymmetryType)
|
|
||||||
fmt.Printf("Techniques: %v\n", analysis.SolvingTechniques)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Puzzle Analysis
|
4. Update your config to use the theme:
|
||||||
|
|
||||||
Every puzzle can be analyzed for:
|
```yaml
|
||||||
|
theme: "mytheme"
|
||||||
- **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)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 📊 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)
|
All colors should be in hex format (e.g., `#ff5555`). Leave fields empty (`""`) to use the terminal default.
|
||||||
- `stats.json` - Statistics backup (JSON format)
|
|
||||||
- `achievements.json` - Achievements backup (JSON format)
|
|
||||||
- `config.json` - User configuration
|
|
||||||
- `themes/` - Custom theme files
|
|
||||||
|
|
||||||
## 🎨 Themes
|
## Data Storage
|
||||||
|
|
||||||
Create custom themes in `~/.termdoku/themes/`:
|
Termdoku stores all its data in `~/.termdoku/`:
|
||||||
|
|
||||||
```json
|
```bash
|
||||||
{
|
~/.termdoku/
|
||||||
"name": "My Theme",
|
├── config.yaml # Your configuration
|
||||||
"palette": {
|
├── termdoku.db # SQLite database (stats, achievements, games)
|
||||||
"background": "#1a1b26",
|
└── themes/ # Custom theme files
|
||||||
"foreground": "#c0caf5",
|
├── example.toml
|
||||||
"accent": "#7aa2f7",
|
└── mytheme.toml
|
||||||
"error": "#f7768e",
|
|
||||||
"success": "#9ece6a",
|
|
||||||
"warning": "#e0af68"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🤝 Contributing
|
## Development
|
||||||
|
|
||||||
Contributions are welcome! Please feel free to submit a Pull Request.
|
```bash
|
||||||
|
|
||||||
1. Fork the repository
|
# Format code
|
||||||
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
make fmt
|
||||||
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
|
# 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
|
MIT License - see [LICENSE](LICENSE) for details.
|
||||||
- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Style definitions for nice terminal layouts
|
|
||||||
|
## 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.
|
||||||
|
|||||||
Reference in New Issue
Block a user