- commit
- 15527784f1d2e15c9ecf2b4e4da1c001fff67a66
- parent
- 9f8ce4e43bc508ffe3eb381b7b3c48c89af1e69f
- author
- Dami <dami@Damis-MacBook-Air.local>
| A | README.md | 127 | ++++++++++++++++++++++++++++++ |
@@ -0,0 +1,127 @@
1+# PuzzleTea2+3+A terminal-based puzzle game collection built with [Bubble Tea](https://github.com/charmbracelet/bubbletea).4+5+Five puzzle types, multiple difficulty modes, save/load persistence, and a plugin architecture for adding new games.6+7+## Games8+9+| Game | Description | Modes |10+|------|-------------|-------|11+| **Nonogram** | Fill cells to match row and column hints | Easy (5x5), Medium (10x10), Hard (15x15), Extra (5x10) |12+| **Sudoku** | Classic 9x9 grid | Beginner, Easy, Medium, Hard, Expert, Diabolical |13+| **Word Search** | Find hidden words in a letter grid | Easy, Medium, Hard (3-8 directions) |14+| **Hashiwokakero** | Connect islands with bridges | 12 modes across 7x7 to 13x13 grids |15+| **Lights Out** | Toggle lights to turn all off | Easy (3x3) to Extreme (9x9) |16+17+## Install18+19+### From release binaries20+21+Download the latest binary for your platform from the [Releases](https://github.com/FelineStateMachine/puzzletea/releases) page.22+23+### From source24+25+Requires Go 1.24+.26+27+```bash28+go install github.com/FelineStateMachine/puzzletea@latest29+```30+31+Or clone and build:32+33+```bash34+git clone https://github.com/FelineStateMachine/puzzletea.git35+cd puzzletea36+just # or: go build -o puzzletea37+```38+39+## Usage40+41+Launch the interactive menu:42+43+```44+puzzletea45+```46+47+Or jump straight into a game:48+49+```bash50+puzzletea new nonogram medium51+puzzletea new sudoku hard52+puzzletea new lights-out53+puzzletea new hashi easy54+```55+56+Manage saved games:57+58+```bash59+puzzletea list # show saved games60+puzzletea continue amber-falcon # resume by name61+```62+63+Flag aliases also work:64+65+```bash66+puzzletea --new nonogram:medium67+puzzletea --continue amber-falcon68+```69+70+## Controls71+72+### Global73+74+| Key | Action |75+|-----|--------|76+| `Enter` | Select |77+| `Escape` | Go back |78+| `Ctrl+N` | Return to main menu |79+| `Ctrl+C` | Quit |80+| `Ctrl+E` | Toggle debug overlay |81+| `Ctrl+H` | Toggle full help |82+83+### Navigation84+85+Arrow keys, WASD, and Vim bindings (hjkl) are supported for grid movement across all games.86+87+## Game Persistence88+89+Games are automatically saved to `~/.puzzletea/history.db` (SQLite). Navigating away saves progress; quitting with `Ctrl+C` marks the game as abandoned. Completed games are preserved and can be revisited.90+91+## Building92+93+[just](https://github.com/casey/just) is used as the command runner:94+95+```bash96+just # build97+just run # build and run98+just test # run tests99+just lint # run golangci-lint100+just fmt # format with gofumpt101+just install # install to $GOPATH/bin102+just clean # remove build artifacts103+```104+105+## Adding a New Puzzle106+107+PuzzleTea uses a plugin architecture. To add a new puzzle type:108+109+1. Create a package (e.g., `mypuzzle/`)110+2. Implement the `game.Gamer` interface on a Model struct111+3. Define modes embedding `game.BaseMode` that implement `game.Spawner`112+4. Register an import function in `init()` for save/load support113+5. Add the category to `GameCategories` in `model.go`114+115+See any existing game package (e.g., `nonogram/`) for the full pattern.116+117+## License118+119+See [LICENSE](LICENSE) for details.120+121+## Built With122+123+- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework124+- [Lip Gloss](https://github.com/charmbracelet/lipgloss) - Terminal styling125+- [Bubbles](https://github.com/charmbracelet/bubbles) - TUI components126+- [Cobra](https://github.com/spf13/cobra) - CLI framework127+- [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite) - Pure-Go SQLite