zanewalker/termdoku
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

(Fix): Rewrote Readme because why not ( gemini made a very weird readme.md )

Browse Source
This commit is contained in:
Zane Walker
2025-11-25 21:20:08 +00:00
parent fb7efc9434
commit 625262d789
1 changed files with 117 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

314
README.md
View File

@@ -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
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.