175 lines
4.3 KiB
Markdown
175 lines
4.3 KiB
Markdown
# Termdoku
|
|
|
|
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
|
|
|
|
- **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
|
|
|
|
## Installation
|
|
|
|
### Pre-built Binaries
|
|
|
|
Download the latest release for your platform from the `dist/` directory:
|
|
|
|
```bash
|
|
# Linux (amd64)
|
|
./dist/termdoku-linux-amd64
|
|
|
|
# macOS (Apple Silicon)
|
|
./dist/termdoku-darwin-arm64
|
|
|
|
# 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
|
|
|
|
# Or build for all platforms
|
|
make build-all
|
|
|
|
# Install to your system
|
|
make install
|
|
```
|
|
|
|
## Usage
|
|
|
|
Simply run the binary to start the game:
|
|
|
|
```bash
|
|
termdoku
|
|
```
|
|
|
|
### Controls
|
|
|
|
- **Arrow Keys / hjkl**: Navigate the grid
|
|
- **1-9**: Enter numbers
|
|
- **Backspace / 0**: Clear cell
|
|
- **?**: Show help
|
|
- **q**: Quit game
|
|
- **m**: Return to main menu
|
|
|
|
Navigate through the main menu to:
|
|
|
|
- Start a new game with your preferred difficulty
|
|
- Resume saved games
|
|
- View your profile (stats, achievements, leaderboard)
|
|
- Access the database of completed puzzles
|
|
|
|
## Configuration
|
|
|
|
Termdoku stores its configuration in `~/.termdoku/config.yaml`. You can customize:
|
|
|
|
```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)
|
|
```
|
|
|
|
## Custom Themes
|
|
|
|
One of the coolest features of Termdoku is the ability to create your own themes using TOML files.
|
|
|
|
### Creating a Custom Theme
|
|
|
|
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:
|
|
|
|
```toml
|
|
Name = "mytheme"
|
|
|
|
[Palette]
|
|
Background = "#1a1b26"
|
|
Foreground = "#c0caf5"
|
|
GridLine = "#414868"
|
|
CellBaseBG = ""
|
|
CellBaseFG = "#c0caf5"
|
|
CellFixedFG = "#565f89"
|
|
CellFixedBG = ""
|
|
CellSelectedBG = "#283457"
|
|
CellSelectedFG = "#7dcfff"
|
|
CellDuplicateBG = "#2e2a2d"
|
|
CellConflictBG = "#3b2e3a"
|
|
Accent = "#7aa2f7"
|
|
```
|
|
|
|
4. Update your config to use the theme:
|
|
|
|
```yaml
|
|
theme: "mytheme"
|
|
```
|
|
|
|
### Color Fields Explained
|
|
|
|
- **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
|
|
|
|
All colors should be in hex format (e.g., `#ff5555`). Leave fields empty (`""`) to use the terminal default.
|
|
|
|
## Data Storage
|
|
|
|
Termdoku stores all its data in `~/.termdoku/`:
|
|
|
|
```bash
|
|
~/.termdoku/
|
|
├── config.yaml # Your configuration
|
|
├── termdoku.db # SQLite database (stats, achievements, games)
|
|
└── themes/ # Custom theme files
|
|
├── example.toml
|
|
└── mytheme.toml
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
|
|
# Format code
|
|
make fmt
|
|
|
|
# Run linter
|
|
make lint
|
|
|
|
# Build for all platforms
|
|
make build-all
|
|
```
|
|
|
|
## License
|
|
|
|
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.
|