Keith Smith
8005a53b48
- PyInstaller spec file for cross-platform builds - Build scripts for Linux/macOS (build.sh) and Windows (build.bat) - requirements.txt with all dependencies - Updated README with build and installation instructions - Support for creating standalone executables for all platforms 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
156 lines
3.8 KiB
Markdown
156 lines
3.8 KiB
Markdown
# Word Search Generator & Player
|
|
|
|
A Python GUI application for generating and playing interactive word search puzzles with PDF export capability.
|
|
|
|
## Features
|
|
|
|
- **Interactive Puzzle Generation**: Create custom word search puzzles with configurable grid dimensions (5-25 x 5-25)
|
|
- **Drag-to-Select Gameplay**: Click and drag across letters to find words
|
|
- **Visual Feedback**:
|
|
- Blue highlighting for selected letters
|
|
- Green highlighting for found words
|
|
- Strikethrough on found words in the word list
|
|
- **PDF Export**: Export puzzles to PDF format for printing
|
|
- **Smart Word Placement**:
|
|
- 8-directional word placement (horizontal, vertical, and diagonal in all directions)
|
|
- Words can appear forwards or backwards
|
|
- Duplicate word prevention
|
|
- **Auto-Resizing Window**: Automatically adjusts to fit the generated puzzle
|
|
- **Clean PDF Output**: Grid lines removed for a professional appearance
|
|
|
|
## Requirements
|
|
|
|
- Python 3.x
|
|
- tkinter (usually included with Python)
|
|
- reportlab
|
|
|
|
## Installation
|
|
|
|
### Option 1: Download Pre-built Application (Recommended)
|
|
|
|
Download the pre-built application for your platform from the releases page:
|
|
- **Windows**: `WordSearch.exe`
|
|
- **macOS**: `WordSearch.app`
|
|
- **Linux**: `WordSearch` (executable)
|
|
|
|
No installation required - just download and run!
|
|
|
|
### Option 2: Run from Source
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://git.firebugit.com/ksmith/WordSearch.git
|
|
cd WordSearch
|
|
```
|
|
|
|
2. Install required dependencies:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Running the Application
|
|
|
|
**From pre-built executable:**
|
|
- **Windows**: Double-click `WordSearch.exe`
|
|
- **macOS**: Double-click `WordSearch.app` or run `open WordSearch.app`
|
|
- **Linux**: Run `./WordSearch` from terminal
|
|
|
|
**From source:**
|
|
```bash
|
|
python word_search_generator.py
|
|
```
|
|
|
|
### Creating a Puzzle
|
|
|
|
1. Enter the desired grid dimensions (Width and Height)
|
|
2. Enter words to include in the puzzle (one per line)
|
|
3. Click "Generate & Play" to create the puzzle
|
|
|
|
### Playing the Game
|
|
|
|
1. Click and drag across letters to select a word
|
|
2. Release to check if the selection matches a word
|
|
3. Found words turn green and are crossed off the list
|
|
4. Use "Clear Selection" to reset your current selection
|
|
|
|
### Exporting to PDF
|
|
|
|
1. Generate a puzzle
|
|
2. Click "Export to PDF"
|
|
3. Choose a location to save the file
|
|
|
|
## How Words Are Placed
|
|
|
|
- Words can appear in 8 directions:
|
|
- Horizontal (left-to-right or right-to-left)
|
|
- Vertical (top-to-bottom or bottom-to-top)
|
|
- Diagonal (all 4 diagonal directions)
|
|
- Words are placed randomly without duplicates
|
|
- Empty cells are filled with random letters
|
|
|
|
## Default Settings
|
|
|
|
- Default grid size: 12x12
|
|
- Default words: PYTHON, GUI, WORDSEARCH, GAME, PUZZLE, FUN
|
|
- Cell size: 30 pixels
|
|
- Grid dimensions: 5-25 (minimum-maximum)
|
|
|
|
## Technical Details
|
|
|
|
- Built with Python tkinter for the GUI
|
|
- Canvas-based interactive grid for responsive drag selection
|
|
- ReportLab for PDF generation
|
|
- Event-driven architecture for mouse interactions
|
|
|
|
## Building from Source
|
|
|
|
To create standalone executables for distribution:
|
|
|
|
### Prerequisites
|
|
|
|
Install build dependencies:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Building
|
|
|
|
**Linux/macOS:**
|
|
```bash
|
|
./build.sh
|
|
```
|
|
|
|
**Windows:**
|
|
```cmd
|
|
build.bat
|
|
```
|
|
|
|
The built application will be in the `dist/` directory:
|
|
- **Linux**: `dist/WordSearch`
|
|
- **macOS**: `dist/WordSearch.app`
|
|
- **Windows**: `dist/WordSearch.exe`
|
|
|
|
### Manual Build
|
|
|
|
You can also build manually using PyInstaller:
|
|
```bash
|
|
pyinstaller word_search.spec
|
|
```
|
|
|
|
### Cross-Platform Notes
|
|
|
|
- PyInstaller creates platform-specific executables
|
|
- Build on the target platform (Windows build requires Windows, etc.)
|
|
- macOS builds create an `.app` bundle
|
|
- Linux/Windows builds create a single executable file
|
|
|
|
## License
|
|
|
|
Created by Keith Smith
|
|
|
|
## Contributing
|
|
|
|
This is a personal project. For issues or suggestions, please contact the repository owner.
|