puzzletea

command module
v1.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 8, 2026 License: MIT Imports: 2 Imported by: 0

README

PuzzleTea

A terminal-based puzzle game collection built with Bubble Tea.

Twelve puzzle types, multiple difficulty modes, daily and weekly deterministic challenges, XP progression, 365 color themes, and an explicit game catalog for adding new games.

PuzzleTea menu

Features

  • 12 puzzle games -- Fillomino, Nonogram, Nurikabe, Ripple Effect, Sudoku, Shikaku, Word Search, Hashiwokakero, Hitori, Lights Out, Takuzu, Takuzu+
  • Daily puzzles -- A unique puzzle generated each day using deterministic seeding. Same date, same puzzle for everyone. Streak tracking rewards consecutive daily completions.
  • Weekly gauntlet -- Each ISO calendar week has a shared 99-puzzle ladder. The current week unlocks sequentially from #01 to #99; past weeks can be reviewed from completed saves only.
  • XP and leveling -- Per-category levels based on victories. Harder modes yield more XP. Daily puzzles grant 2x XP, and weekly puzzles add slot-based bonus XP.
  • Stats dashboard -- Profile level, daily streak status, weekly completion progress, victory counts, and XP progress bars per category.
  • 365 color themes -- Live-preview theme picker with WCAG-compliant contrast enforcement. Dark and light themes included.
  • Mouse support -- Click and drag in Nonogram, Nurikabe, Shikaku, and Word Search. Lights Out supports click-to-toggle.
  • Seeded puzzles -- Share a seed string to generate identical puzzles across sessions and machines.
  • Save/load persistence -- Games auto-save to SQLite. Resume any in-progress game by name.

Games

Game Description Modes
Fillomino Grow numbered regions to their exact sizes Mini 5x5 through Expert 12x12
Nonogram Fill cells to match row and column hints Easy/Medium/Hard across 5x5, 10x10, 15x15, 20x20
Nurikabe Build islands while keeping one connected sea 5 modes from 5x5 to 12x12
Ripple Effect Place digits in cages without violating ripple distance Mini 5x5 through Expert 9x9
Shikaku Divide grid into rectangles matching cell counts 5 modes from 7x7 to 11x11
Sudoku Classic 9x9 grid Beginner, Easy, Medium, Hard, Expert, Diabolical
Word Search Find hidden words in a letter grid Easy, Medium, Hard (3-8 directions)
Hashiwokakero Connect islands with bridges 12 modes across 7x7 to 13x13 grids
Hitori Shade cells to eliminate duplicates 6 modes from 5x5 to 12x12
Lights Out Toggle lights to turn all off Easy (3x3) to Extreme (9x9)
Takuzu Fill grid with two symbols 7 modes from 6x6 to 14x14
Takuzu+ Fill grid with symbols plus = and x relation clues 7 modes from 6x6 to 14x14

Install

Homebrew (macOS / Linux)
brew install FelineStateMachine/homebrew-tap/puzzletea
AUR (Arch Linux)
yay -S puzzletea
WinGet (Windows)
winget install FelineStateMachine.puzzletea
From release binaries

Download the latest binary for your platform from the Releases page.

From source

Requires Go 1.24+.

go install github.com/FelineStateMachine/puzzletea@latest

Or clone and build:

git clone https://github.com/FelineStateMachine/puzzletea.git
cd puzzletea
just        # or: go build -o puzzletea

Usage

Launch the interactive menu:

puzzletea

The Play menu includes:

  • Create for a new puzzle by category and mode
  • Continue for saved games
  • Daily for the shared deterministic daily puzzle
  • Weekly for the current or historical weekly gauntlet
  • Seeded for a custom deterministic seed

Weekly gauntlets use the ISO week-year format shown in the menu, for example Week 10-2026 # 7. The # value is the currently active weekly challenge for that week. Current-week puzzles unlock one at a time; older weeks are review-only.

Start a new game directly:

puzzletea new nonogram medium
puzzletea new fillomino "Hard 10x10"
puzzletea new ripple-effect "Medium 7x7"
puzzletea new sudoku hard
puzzletea new lights-out
puzzletea new hashi easy

Resume and manage saved games:

puzzletea list                     # show saved games
puzzletea list --all               # include abandoned games
puzzletea continue amber-falcon    # resume by name

Use seeds for deterministic puzzle generation:

# Deterministically selects game, mode, and puzzle from one seed.
puzzletea new --set-seed myseed

# Deterministically generates a puzzle within a chosen game/mode.
puzzletea new nonogram epic --with-seed myseed

Export printable puzzle sets to JSONL:

# Stream JSONL to stdout (redirect if desired)
puzzletea new nonogram mini --export 2 > nonogram-mini-set.jsonl

# Single mode export
puzzletea new nonogram mini -e 6 -o nonogram-mini-set.jsonl

# Mixed modes within a category (deterministic with --with-seed)
puzzletea new sudoku --export 10 -o sudoku-mixed.jsonl --with-seed zine-issue-01

Render one or more JSONL packs into a half-letter print PDF:

puzzletea export-pdf nonogram-mini-set.jsonl -o issue-01.pdf --shuffle-seed issue-01 --volume 1 --title "Catacombs & Pines"

--title sets the pack subtitle (title page, and cover pages when enabled), and --volume sets the volume number. By default, covers are not included. Use --cover-color to include front/back cover pages. Page count is always auto-padded to a multiple of 4 for half-letter booklet printing.

Font license note (Atkinson Hyperlegible Next):

  • Follow the SIL OFL 1.1 requirements in pdfexport/fonts/OFL.txt.
  • Do not sell the font files by themselves.
  • If redistributing fonts with software, include the copyright notice and OFL text.
  • Modified font versions must keep OFL terms, and modified names must respect Reserved Font Name rules.

Lights Out is currently excluded from export because it does not translate cleanly to paper workflows.

Override the color theme:

puzzletea --theme "Catppuccin Mocha"

Flag aliases on the root command also work:

puzzletea --new nonogram:medium
puzzletea --continue amber-falcon
CLI Aliases

Several shorthand names are accepted for games: polyomino/regions for Fillomino, hashi/bridges for Hashiwokakero, lights for Lights Out, islands/sea for Nurikabe, ripple for Ripple Effect, binairo/binary for Takuzu, binario+ for Takuzu+, words/ws for Word Search, rectangles for Shikaku.

Controls

Global
Key Action
Enter Select
Escape Return to the menu or go back
Ctrl+R Reset puzzle
Ctrl+H Toggle full help
Ctrl+E Toggle debug overlay
Ctrl+C Quit
Navigation

Arrow keys, WASD, and Vim bindings (hjkl) are supported for grid movement across all games.

Mouse

Nonogram, Nurikabe, Shikaku, and Word Search support click and drag. Lights Out supports click to toggle. See each game's help for details.

Game Persistence

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.

Daily and current-week weekly puzzles keep a single deterministic save per seed/week slot. Completed weekly puzzles from prior weeks reopen in review mode and are not modified when viewed again.

Previews

Fillomino

Grow numbered regions so each connected region reaches its exact size.

Fillomino

Game details and controls

Ripple Effect

Place digits in cages while keeping matching values outside each other’s ripple distance.

Ripple Effect

Game details and controls

Nonogram

Fill cells to match row and column hints.

Nonogram

Game details and controls

Nurikabe

Build islands from clues while keeping one connected sea.

Nurikabe

Game details and controls

Shikaku

Divide the grid into rectangles, where each rectangle contains exactly the number of cells shown in its clue.

Shikaku

Game details and controls

Sudoku

Classic 9x9 number placement puzzle.

Sudoku

Game details and controls

Find hidden words in a letter grid.

Word Search

Game details and controls

Hashiwokakero

Connect islands with bridges.

Hashiwokakero

Game details and controls

Hitori

Shade cells to eliminate duplicate numbers.

Hitori

Game details and controls

Lights Out

Toggle lights to turn all off.

Lights Out

Game details and controls

Takuzu

Fill the grid with two symbols following three simple rules.

Takuzu

Game details and controls

Building and Testing

just is used as the command runner:

just              # build
just run          # build and run
just test         # run tests (go test ./...)
just test-short   # run tests, skipping slow generator tests
just lint         # run golangci-lint
just fmt          # format with gofumpt
just tidy         # go mod tidy
just install      # install to $GOPATH/bin
just clean        # remove build artifacts
just vhs          # generate all VHS GIF previews

Run a single package's tests:

go test ./nonogram/
go test ./sudoku/ -run TestGenerateGrid

All code must pass gofumpt and golangci-lint before committing. CI runs both on every PR.

Adding a New Puzzle

PuzzleTea uses an explicit game catalog. To add a new puzzle type:

1. Create the game package

Create a directory (e.g., mypuzzle/) with these files:

File Purpose
Gamemode.go Mode struct embedding game.BaseMode, Spawn(), Modes/DailyModes, and package-level Definition metadata
Model.go Model struct implementing game.Gamer
Export.go Save struct, GetSave(), ImportModel() for persistence
keys.go Game-specific KeyMap struct
style.go lipgloss styling and rendering helpers
generator.go Puzzle generation logic (if applicable)
grid.go Grid type and serialization (for grid-based games)
mypuzzle_test.go Tests (table-driven, save/load round-trip, generator validation)
README.md Game docs: rules, controls table, modes table, quick start examples
2. Wire it into the central catalog

Edit the central catalog once:

  • catalog/catalog.go: Import the package and add its exported Definition to All (maintain alphabetical order).

The game package's Definition owns:

  • canonical name
  • description
  • aliases
  • menu modes
  • daily-eligible modes
  • help content
  • save/import function
3. Add a VHS preview
  • Create vhs/<game>.tape following the format in existing tapes.
  • Add the tape to the vhs target in the justfile.
4. Verify
just fmt && just lint && just test

See any existing game package (e.g., nonogram/) for the full pattern, and AGENTS.md for detailed conventions.

License

MIT

Built With

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

View all Source files

Directories

Path Synopsis
Package app implements the root TUI model for PuzzleTea, including the Elm-architecture update/view loop, game spawning, and debug overlay.
 Package app implements the root TUI model for PuzzleTea, including the Elm-architecture update/view loop, game spawning, and debug overlay.
Package cmd defines the CLI commands for PuzzleTea using Cobra.
 Package cmd defines the CLI commands for PuzzleTea using Cobra.
Package config provides persistent application configuration for PuzzleTea.
 Package config provides persistent application configuration for PuzzleTea.
Package game defines the plugin interface for puzzle games.
 Package game defines the plugin interface for puzzle games.
Package hashiwokakero implements the bridge-connecting puzzle game.
 Package hashiwokakero implements the bridge-connecting puzzle game.
Package hitori implements the Hitori number puzzle game.
 Package hitori implements the Hitori number puzzle game.
Package lightsout implements the lights out toggle puzzle game.
 Package lightsout implements the lights out toggle puzzle game.
Package namegen generates random human-readable names for saved games.
 Package namegen generates random human-readable names for saved games.
Package nonogram implements the grid-based picture logic puzzle.
 Package nonogram implements the grid-based picture logic puzzle.
Package shikaku implements the Shikaku rectangle-partition puzzle game.
 Package shikaku implements the Shikaku rectangle-partition puzzle game.
Package store provides persistent storage for saved games.
 Package store provides persistent storage for saved games.
Package sudoku implements the classic number-placement puzzle.
 Package sudoku implements the classic number-placement puzzle.
Package takuzu implements the binary (Binairo) puzzle game.
 Package takuzu implements the binary (Binairo) puzzle game.
Package takuzuplus implements the Takuzu+ puzzle game.
 Package takuzuplus implements the Takuzu+ puzzle game.
Package theme provides color theming for PuzzleTea.
 Package theme provides color theming for PuzzleTea.
Package wordsearch implements the word-finding grid puzzle.
 Package wordsearch implements the word-finding grid puzzle.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.