cat / puzzletea
clone

fifteen puzzle games for the terminal, with daily puzzles, weekly ladders and xp, built on bubble tea

add vhs gif generation and pipeline

Dami committed ca6ce18
commit
ca6ce181d94f60bb860fadc6ef158a579d039542
parent
ff6f3b2af1c53ba561df91c1fe1820fdd2d32eba
author
Dami <dami.etoile@gmail.com>
15 files changed, +690 -0
A.github/workflows/vhs.yml63++++++++++++++++++++++++++++++
MREADME.md39+++++++++++++++++++
Ahashiwokakero/README.md63++++++++++++++++++++++++++++++
Mjustfile9++++
Alightsout/README.md38++++++++++++++++++
Anonogram/README.md53+++++++++++++++++++++++++
Asudoku/README.md42++++++++++++++++++++
Avhs/config.tape4++
Avhs/hashiwokakero.tape57+++++++++++++++++++++++++++
Avhs/lightsout.tape45+++++++++++++++++++++
Avhs/menu.tape62++++++++++++++++++++++++++++++
Avhs/nonogram.tape58++++++++++++++++++++++++++++
Avhs/sudoku.tape52+++++++++++++++++++++++++
Avhs/wordsearch.tape62++++++++++++++++++++++++++++++
Awordsearch/README.md43++++++++++++++++++++
A .github/workflows/vhs.yml +63 -0
@@ -0,0 +1,63 @@
1+name: VHS GIFs2+3+on:4+ release:5+ types: [published]6+ workflow_dispatch:7+ push:8+ branches: [main]9+ paths:10+ - "vhs/*.tape"11+12+permissions:13+ contents: write14+15+jobs:16+ generate-gifs:17+ name: Generate GIFs18+ runs-on: ubuntu-latest19+ steps:20+ - uses: actions/checkout@v421+22+ - uses: actions/setup-go@v523+ with:24+ go-version: "1.24"25+26+ - name: Build binary27+ run: go build -ldflags "-X main.version=${{ github.ref_name }}" -o puzzletea28+29+ - uses: charmbracelet/vhs-action@v230+ with:31+ path: "vhs/menu.tape"32+33+ - uses: charmbracelet/vhs-action@v234+ with:35+ path: "vhs/nonogram.tape"36+37+ - uses: charmbracelet/vhs-action@v238+ with:39+ path: "vhs/sudoku.tape"40+41+ - uses: charmbracelet/vhs-action@v242+ with:43+ path: "vhs/wordsearch.tape"44+45+ - uses: charmbracelet/vhs-action@v246+ with:47+ path: "vhs/hashiwokakero.tape"48+49+ - uses: charmbracelet/vhs-action@v250+ with:51+ path: "vhs/lightsout.tape"52+53+ - name: Commit updated GIFs54+ run: |55+ git config user.name "github-actions[bot]"56+ git config user.email "github-actions[bot]@users.noreply.github.com"57+ git add vhs/*.gif58+ if git diff --cached --quiet; then59+ echo "No GIF changes to commit"60+ else61+ git commit -m "chore: regenerate VHS GIFs"62+ git push63+ fi
M README.md +39 -0
@@ -4,6 +4,8 @@ A terminal-based puzzle game collection built with [Bubble Tea](https://github.c
44 55 Five puzzle types, multiple difficulty modes, save/load persistence, and a plugin architecture for adding new games.66 7+![PuzzleTea menu](vhs/menu.gif)8+79 ## Games810 911 | Game | Description | Modes |
@@ -14,6 +16,43 @@ Five puzzle types, multiple difficulty modes, save/load persistence, and a plugi
1416 | **Hashiwokakero** | Connect islands with bridges | 12 modes across 7x7 to 13x13 grids |1517 | **Lights Out** | Toggle lights to turn all off | Easy (3x3) to Extreme (9x9) |1618 19+## Previews20+21+### Nonogram22+Fill cells to match row and column hints.23+24+![Nonogram](vhs/nonogram.gif)25+26+[Game details and controls](nonogram/README.md)27+28+### Sudoku29+Classic 9x9 number placement puzzle.30+31+![Sudoku](vhs/sudoku.gif)32+33+[Game details and controls](sudoku/README.md)34+35+### Word Search36+Find hidden words in a letter grid.37+38+![Word Search](vhs/wordsearch.gif)39+40+[Game details and controls](wordsearch/README.md)41+42+### Hashiwokakero43+Connect islands with bridges.44+45+![Hashiwokakero](vhs/hashiwokakero.gif)46+47+[Game details and controls](hashiwokakero/README.md)48+49+### Lights Out50+Toggle lights to turn all off.51+52+![Lights Out](vhs/lightsout.gif)53+54+[Game details and controls](lightsout/README.md)55+1756 ## Install1857 1958 ### Homebrew (macOS / Linux)
A hashiwokakero/README.md +63 -0
@@ -0,0 +1,63 @@
1+# Hashiwokakero2+3+Connect islands with bridges to form a single connected group.4+5+![Hashiwokakero gameplay](../vhs/hashiwokakero.gif)6+7+## How to Play8+9+Islands are numbered circles on the grid. Each number indicates how many10+bridges must connect to that island. Bridges run horizontally or vertically11+between adjacent islands, may not cross, and can be single or double.12+The puzzle is solved when every island has exactly the required number of13+bridges and all islands are connected.14+15+1. Navigate to an island and press `Enter` or `Space` to select it.16+2. Press an arrow key toward an adjacent island to build a bridge.17+3. Press the same direction again to upgrade to a double bridge, or a18+ third time to remove the bridge.19+4. Press `Enter`, `Space`, or `Escape` to deselect.20+21+## Controls22+23+### Navigation Mode24+25+| Key | Action |26+|-----|--------|27+| Arrow keys / WASD / hjkl | Jump to nearest island |28+| `Enter` / `Space` | Select island for bridging |29+| `Ctrl+H` | Toggle full help |30+| `Ctrl+E` | Toggle debug overlay |31+| `Ctrl+N` | Return to main menu |32+33+### Bridge Mode (after selecting an island)34+35+| Key | Action |36+|-----|--------|37+| Arrow keys / WASD / hjkl | Build or cycle bridge in direction |38+| `Enter` / `Space` / `Escape` | Deselect island |39+40+## Modes41+42+| Mode | Grid | Islands | Description |43+|------|------|---------|-------------|44+| Easy 7x7 | 7x7 | 8-10 | Small grid, few islands |45+| Medium 7x7 | 7x7 | 12-15 | Moderate density |46+| Hard 7x7 | 7x7 | 17-20 | Dense island placement |47+| Easy 9x9 | 9x9 | 12-16 | Larger grid, spread out |48+| Medium 9x9 | 9x9 | 20-24 | Moderate density |49+| Hard 9x9 | 9x9 | 28-32 | Dense island placement |50+| Easy 11x11 | 11x11 | 18-24 | Large grid, spread out |51+| Medium 11x11 | 11x11 | 30-36 | Moderate density |52+| Hard 11x11 | 11x11 | 42-48 | Dense island placement |53+| Easy 13x13 | 13x13 | 25-34 | Largest grid, spread out |54+| Medium 13x13 | 13x13 | 42-51 | Moderate density |55+| Hard 13x13 | 13x13 | 59-68 | Dense island placement |56+57+## Quick Start58+59+```bash60+puzzletea new hashi easy-7x761+puzzletea new hashi medium-9x962+puzzletea new hashi hard-13x1363+```
M justfile +9 -0
@@ -33,3 +33,12 @@ install:
3333 clean:3434 rm -f puzzletea3535 rm -rf dist36+37+# Generate VHS GIFs (requires vhs: https://github.com/charmbracelet/vhs).38+vhs: build39+ vhs vhs/menu.tape40+ vhs vhs/nonogram.tape41+ vhs vhs/sudoku.tape42+ vhs vhs/wordsearch.tape43+ vhs vhs/hashiwokakero.tape44+ vhs vhs/lightsout.tape
A lightsout/README.md +38 -0
@@ -0,0 +1,38 @@
1+# Lights Out2+3+Toggle lights in a cross pattern to turn them all off.4+5+![Lights Out gameplay](../vhs/lightsout.gif)6+7+## How to Play8+9+The grid starts with some lights on and some off. Toggling a cell flips10+that cell and its four orthogonal neighbors (up, down, left, right). The11+goal is to turn every light off.12+13+## Controls14+15+| Key | Action |16+|-----|--------|17+| Arrow keys / WASD / hjkl | Move cursor |18+| `Enter` / `Space` | Toggle light |19+| `Ctrl+H` | Toggle full help |20+| `Ctrl+E` | Toggle debug overlay |21+| `Ctrl+N` | Return to main menu |22+23+## Modes24+25+| Mode | Grid | Description |26+|------|------|-------------|27+| Easy | 3x3 | Small grid |28+| Medium | 5x5 | Classic size |29+| Hard | 7x7 | Large grid |30+| Extreme | 9x9 | Maximum size |31+32+## Quick Start33+34+```bash35+puzzletea new lights-out easy36+puzzletea new lights-out medium37+puzzletea new lights-out extreme38+```
A nonogram/README.md +53 -0
@@ -0,0 +1,53 @@
1+# Nonogram2+3+Fill cells to match row and column hints, revealing a hidden pattern.4+5+![Nonogram gameplay](../vhs/nonogram.gif)6+7+## How to Play8+9+Navigate the grid and fill or mark cells based on the numeric hints along10+each row and column. The hints tell you how many consecutive filled cells11+appear in that line, in order. Hints turn green when a row or column is12+correctly satisfied.13+14+- **Filled** cells count toward hint satisfaction.15+- **Marked** cells are visual reminders that a cell should stay empty.16+- The puzzle is solved when every row and column matches its hints.17+18+## Controls19+20+| Key | Action |21+|-----|--------|22+| Arrow keys / WASD / hjkl | Move cursor |23+| `z` | Fill cell |24+| `x` | Mark cell |25+| `Backspace` | Clear cell |26+| `Ctrl+H` | Toggle full help |27+| `Ctrl+E` | Toggle debug overlay |28+| `Ctrl+N` | Return to main menu |29+30+## Modes31+32+| Mode | Grid | Density | Description |33+|------|------|---------|-------------|34+| Easy 5x5 | 5x5 | ~35% | Simple hints |35+| Medium 5x5 | 5x5 | ~50% | Balanced challenge |36+| Hard 5x5 | 5x5 | ~65% | Dense hints |37+| Easy 10x10 | 10x10 | ~35% | Simple hints |38+| Medium 10x10 | 10x10 | ~50% | Balanced challenge |39+| Hard 10x10 | 10x10 | ~65% | Dense hints |40+| Easy 15x15 | 15x15 | ~35% | Simple hints |41+| Medium 15x15 | 15x15 | ~50% | Balanced challenge |42+| Hard 15x15 | 15x15 | ~65% | Dense hints |43+| Easy 20x20 | 20x20 | ~35% | Simple hints |44+| Medium 20x20 | 20x20 | ~50% | Balanced challenge |45+| Hard 20x20 | 20x20 | ~65% | Dense hints |46+47+## Quick Start48+49+```bash50+puzzletea new nonogram easy-5x551+puzzletea new nonogram medium-10x1052+puzzletea new nonogram hard-20x2053+```
A sudoku/README.md +42 -0
@@ -0,0 +1,42 @@
1+# Sudoku2+3+Classic 9x9 number placement puzzle.4+5+![Sudoku gameplay](../vhs/sudoku.gif)6+7+## How to Play8+9+Fill every empty cell with a digit from 1 to 9 so that each row, each10+column, and each 3x3 box contains every digit exactly once. Pre-filled11+cells (shown in bold) cannot be changed. Conflicting cells are highlighted12+in red.13+14+## Controls15+16+| Key | Action |17+|-----|--------|18+| Arrow keys / WASD / hjkl | Move cursor |19+| `1`-`9` | Fill cell with digit |20+| `Backspace` | Clear cell |21+| `Ctrl+H` | Toggle full help |22+| `Ctrl+E` | Toggle debug overlay |23+| `Ctrl+N` | Return to main menu |24+25+## Modes26+27+| Mode | Clues | Description |28+|------|-------|-------------|29+| Beginner | 45 | Single Candidate / Scanning |30+| Easy | 38 | Naked Singles |31+| Medium | 32 | Hidden Pairs / Pointing |32+| Hard | 27 | Box-Line Reduction / Triples |33+| Expert | 22 | X-Wing / Y-Wing |34+| Diabolical | 17 | Swordfish / XY-Chains |35+36+## Quick Start37+38+```bash39+puzzletea new sudoku beginner40+puzzletea new sudoku medium41+puzzletea new sudoku diabolical42+```
A vhs/config.tape +4 -0
@@ -0,0 +1,4 @@
1+# Shared PuzzleTea VHS settings.2+# Source this file from every game tape for visual consistency.3+Set FontSize 324+Set Theme "Catppuccin Frappe"
A vhs/hashiwokakero.tape +57 -0
@@ -0,0 +1,57 @@
1+Output vhs/hashiwokakero.gif2+3+Set FontSize 134+Set Width 8545+Set Height 4806+Set Padding 407+8+Hide9+Type "go build -o puzzletea"10+Enter11+Sleep 2s12+Ctrl+L13+Show14+15+Type "./puzzletea new hashi easy-7x7"16+Sleep 500ms17+Enter18+Sleep 2s19+20+# Navigate between islands21+Right22+Sleep 400ms23+Right24+Sleep 400ms25+26+# Select island to enter bridge mode27+Enter28+Sleep 500ms29+30+# Build a bridge to the right31+Right32+Sleep 500ms33+34+# Deselect35+Enter36+Sleep 500ms37+38+# Navigate to another island39+Down40+Down41+Sleep 400ms42+43+# Select and build downward bridge44+Enter45+Sleep 500ms46+Down47+Sleep 500ms48+49+# Build double bridge (cycle 1 -> 2)50+Down51+Sleep 500ms52+53+# Deselect54+Escape55+Sleep 500ms56+57+Sleep 3s
A vhs/lightsout.tape +45 -0
@@ -0,0 +1,45 @@
1+Output vhs/lightsout.gif2+3+Set FontSize 134+Set Width 8545+Set Height 4806+Set Padding 407+8+Hide9+Type "go build -o puzzletea"10+Enter11+Sleep 2s12+Ctrl+L13+Show14+15+Type "./puzzletea new lights-out easy"16+Sleep 500ms17+Enter18+Sleep 2s19+20+# Toggle center cell -- shows cross pattern21+Enter22+Sleep 800ms23+24+# Move to top-left corner and toggle25+Up26+Sleep 300ms27+Left28+Sleep 300ms29+Enter30+Sleep 800ms31+32+# Move right and toggle33+Right34+Right35+Sleep 300ms36+Enter37+Sleep 800ms38+39+# Move down and toggle40+Down41+Sleep 300ms42+Enter43+Sleep 800ms44+45+Sleep 3s
A vhs/menu.tape +62 -0
@@ -0,0 +1,62 @@
1+Output vhs/menu.gif2+3+Set FontSize 134+Set Width 8545+Set Height 4806+Set Padding 407+8+Hide9+Type "go build -o puzzletea"10+Enter11+Sleep 2s12+Ctrl+L13+Show14+15+Type "./puzzletea"16+Sleep 500ms17+Enter18+Sleep 2s19+20+# Browse main menu21+Down22+Sleep 500ms23+Down24+Sleep 500ms25+Up26+Up27+Sleep 500ms28+29+# Select "Generate"30+Down31+Enter32+Sleep 1s33+34+# Browse game categories35+Down36+Sleep 400ms37+Down38+Sleep 400ms39+Down40+Sleep 400ms41+Down42+Sleep 400ms43+44+# Select Nonogram (third item)45+Up46+Up47+Enter48+Sleep 1s49+50+# Browse modes51+Down52+Sleep 400ms53+Down54+Sleep 400ms55+56+# Go back through menus57+Escape58+Sleep 500ms59+Escape60+Sleep 500ms61+62+Sleep 2s
A vhs/nonogram.tape +58 -0
@@ -0,0 +1,58 @@
1+Output vhs/nonogram.gif2+3+Set FontSize 134+Set Width 8545+Set Height 4806+Set Padding 407+8+Hide9+Type "go build -o puzzletea"10+Enter11+Sleep 2s12+Ctrl+L13+Show14+15+Type "./puzzletea new nonogram easy-5x5"16+Sleep 500ms17+Enter18+Sleep 2s19+20+# Fill a cell21+Type "z"22+Sleep 400ms23+24+# Move right and fill25+Right26+Type "z"27+Sleep 400ms28+29+# Move right and mark30+Right31+Type "x"32+Sleep 400ms33+34+# Move down and left, fill more cells35+Down36+Left37+Left38+Type "z"39+Sleep 400ms40+Down41+Type "z"42+Sleep 400ms43+Right44+Type "z"45+Sleep 400ms46+Right47+Type "z"48+Sleep 400ms49+50+# Demonstrate clearing a cell51+Backspace52+Sleep 400ms53+54+# Refill it55+Type "z"56+Sleep 400ms57+58+Sleep 3s
A vhs/sudoku.tape +52 -0
@@ -0,0 +1,52 @@
1+Output vhs/sudoku.gif2+3+Set FontSize 134+Set Width 8545+Set Height 4806+Set Padding 407+8+Hide9+Type "go build -o puzzletea"10+Enter11+Sleep 2s12+Ctrl+L13+Show14+15+Type "./puzzletea new sudoku beginner"16+Sleep 500ms17+Enter18+Sleep 2s19+20+# Navigate to find an empty cell21+Down22+Down23+Right24+Sleep 300ms25+26+# Fill with a number27+Type "5"28+Sleep 500ms29+30+# Move to another cell31+Right32+Right33+Sleep 300ms34+Type "3"35+Sleep 500ms36+37+# Demonstrate clearing and re-entering38+Backspace39+Sleep 500ms40+Type "8"41+Sleep 500ms42+43+# Navigate around to show highlighting44+Down45+Down46+Down47+Sleep 300ms48+Right49+Right50+Sleep 300ms51+52+Sleep 3s
A vhs/wordsearch.tape +62 -0
@@ -0,0 +1,62 @@
1+Output vhs/wordsearch.gif2+3+Set FontSize 134+Set Width 8545+Set Height 4806+Set Padding 407+8+Hide9+Type "go build -o puzzletea"10+Enter11+Sleep 2s12+Ctrl+L13+Show14+15+Type "./puzzletea new wordsearch easy-10x10"16+Sleep 500ms17+Enter18+Sleep 2s19+20+# Navigate through the grid21+Down22+Down23+Right24+Right25+Right26+Sleep 500ms27+28+# Select start of a word29+Enter30+Sleep 500ms31+32+# Extend selection to the right33+Right34+Right35+Right36+Sleep 500ms37+38+# Confirm end of selection39+Enter40+Sleep 500ms41+42+# Navigate elsewhere43+Down44+Down45+Sleep 300ms46+47+# Start another selection48+Enter49+Sleep 300ms50+51+# Extend diagonally52+Right53+Down54+Right55+Down56+Sleep 300ms57+58+# Cancel the selection59+Escape60+Sleep 500ms61+62+Sleep 3s
A wordsearch/README.md +43 -0
@@ -0,0 +1,43 @@
1+# Word Search2+3+Find hidden words in a letter grid.4+5+![Word Search gameplay](../vhs/wordsearch.gif)6+7+## How to Play8+9+Words are hidden in the grid horizontally, vertically, and diagonally.10+Select the first letter of a word, then navigate to the last letter and11+confirm. Found words are highlighted in green and crossed off the word list.12+The puzzle is solved when all words are found.13+14+1. Move the cursor to the start of a word and press `Enter` or `Space`.15+2. Navigate to the end of the word.16+3. Press `Enter` or `Space` to confirm, or `Escape` to cancel.17+18+## Controls19+20+| Key | Action |21+|-----|--------|22+| Arrow keys / WASD / hjkl | Move cursor |23+| `Enter` / `Space` | Select start or confirm end |24+| `Escape` | Cancel current selection |25+| `Ctrl+H` | Toggle full help |26+| `Ctrl+E` | Toggle debug overlay |27+| `Ctrl+N` | Return to main menu |28+29+## Modes30+31+| Mode | Grid | Words | Directions | Description |32+|------|------|-------|------------|-------------|33+| Easy | 10x10 | 6 | 3 | Right, Down, DownRight |34+| Medium | 15x15 | 10 | 6 | + DownLeft, Left, Up |35+| Hard | 20x20 | 15 | 8 | All 8 directions |36+37+## Quick Start38+39+```bash40+puzzletea new wordsearch easy-10x1041+puzzletea new wordsearch medium-15x1542+puzzletea new wordsearch hard-20x2043+```