Word Search Puzzle Generator

A Go-based word search puzzle generator with support for hidden answer strings and concurrent generation attempts.

Features

• ✨ Generate word search puzzles with customizable grid sizes
• 🔤 Place words in 8 directions (horizontal, vertical, diagonal - forward and backward)
• 🎯 Hide answer strings in unused grid cells
• ⚡ Concurrent puzzle generation for better success rates
• 🎨 Interactive TUI with progress tracking (using Bubbletea)
• 📝 Support for word lists from files or manual entry
• ✅ Comprehensive test coverage (96%+)

Installation

go build -o wordsearch main.go

Usage

Interactive Usage

Run the TUI and fill in the fields:

./wordsearch

Command-Line Options

If you provide --file on the command line, the app skips the menu and starts generating immediately.

./wordsearch --file words.txt --rows 12 --cols 12 --attempts 500 --answer "SECRET"

Options:

• --file, -f - Path to file containing words (one per line)
• --rows, -r - Number of rows in the grid (default: 12)
• --cols, -c - Number of columns in the grid (default: 12)
• --answer, -a - Answer string to hide in the puzzle
• --attempts, -t - Number of attempts to run (default: 1000)

Navigation:

• Tab / Shift+Tab to move between fields
• Enter to advance to the next field
• Ctrl+S to start generation
• q to quit

Fields

• Words file - Path to file containing words (one per line)
• Rows - Number of rows in the grid (default: 12)
• Cols - Number of columns in the grid (default: 12)
• Answer (optional) - Answer string to hide in the puzzle
• Attempts - Number of attempts to run (default: 1000)

How It Works

Answer String Algorithm

The generator uses a unique pre-allocation strategy for answer strings:

1. Pre-allocate: Before placing words, the answer string letters are distributed evenly across the grid
2. Mark cells: Answer cells are marked as reserved
3. Place words: Words are placed while avoiding conflicts with answer cells
4. Fill remaining: Empty cells are filled with random letters
5. Result: Reading answer cells left-to-right, top-to-bottom spells the answer string

Concurrency

The generator launches multiple goroutines that attempt puzzle generation in parallel. The best successful puzzle (most words placed) is chosen.

Project Structure

wordsearch/
├── main.go                  # CLI entry point
├── internal/
│   ├── puzzle/             # Core generation logic
│   │   ├── direction.go    # 8 directions enum
│   │   ├── grid.go         # Grid and Cell structures
│   │   ├── puzzle.go       # Puzzle type
│   │   ├── answer.go       # Answer string pre-allocation
│   │   ├── placer.go       # Word placement algorithm
│   │   ├── generator.go    # Main generation orchestrator
│   ├── generate/           # Concurrent generation
│   │   ├── run.go          # Goroutine-based runner
│   │   └── result.go       # Result types
│   └── tui/                # Bubbletea UI
│       ├── model.go        # TUI model
│       ├── update.go       # Update logic
│       └── messages.go     # Message types
└── words.txt               # Example word list

Testing

Run all tests:

go test ./...

Run with coverage:

go test ./... -cover

Run specific tests:

go test -run TestGenerator_Generate ./internal/puzzle

Example Output

Puzzle (10x10)
Words: HELLO, WORLD, CODE
Answer: SECRET

S S E M G I S C D F
I J V E K I E O Y S
M X B M Y E W D Z I
O I E C T K X E W H
A K W Q Q X O O A K
R C F F I L R Q A G
G Q G O L L E P D G
E J G E D S G N C C
K T H T W G Z T O K
Z M D R V U I L R U

Placements:
  HELLO at (8, 2) UpRight
  WORLD at (3, 8) DownLeft
  CODE at (0, 7) Down

License

MIT License