philshem / open-spelling-bee

🐝 Terminal-based python clone of New York Times' puzzle game "Spelling Bee"

Open Spelling Bee (OSB)

🐝

Open source port of New York Times' puzzle game Spelling Bee for the command line.

Requires Python 3.x and nothing but standard Python libraries.

to play

To download the game:

git clone https://github.com/philshem/open-spelling-bee.git
cd open-spelling-bee

To play a random game:

python3 play_puzzle.py

To play a non-random game:

python3 play_puzzle.py RDGHNOU

where R is the center letter that must be used at least once in each word. If the puzzle RDGHNOU does not exist, it will be created and saved to data/RDGHNOU.json (the file names are the first letter and the alphabetically sorted remaining letters).

The word list used is from SCOWL. The default setting contains 40,000 words, which seems comparable to the New York Times dictionary. (See below on changing the size parameter to include more erudite words.)

To reach "genius" level, you'll need to solve 50% of the words.

To solve a game (aka cheat-mode):

python3 solve_puzzles.py RDGHNOU

If the game does not exist, it will be created and saved to the data/ folder.

For a list of the previous NY Times letter selections, see William Shunn's page.

to generate new puzzles

Set custom parameters in the params.py file, for example how many puzzles you want to create. Then generate by running:

python3 generate_puzzles.py

Or to save the word stats:

python3 generate_puzzles.py > stats.csv

Runtime depends on your parameters. For the default parameter settings, the code takes approximately 8 hours to generate 100 7-letter puzzles that meet the criteria (total points, total words, pangram count).

To generate a certain letter combination, use:

python3 generate_puzzles.py AGFEDCB

which will then be saved to data/ABCDEFG.json.

to change the size of the wordlist

If you find the game overly facile or wish your recondite words were accepted, you can change the wordlist size. Change size=35 to a larger number in word_lists/mkscowl and then run mkscowl to create a new wordlist. You must run generate_puzzles.py (as detailed above) whenever the wordlist changes.

Description	Scowl size	Num words	Sample word
Small	size=35	40,198	abacus
Medium	size=50	63,375	abeyance
Large	size=70	115,332	abecedarian
Huge	size=80	251,064	abapical
Insane	size=95	435,726	abigailship

---

Game Play

To play, build words with a minimum of 4 letters, using the letters provided.

Each word must include the center letter at least once.

Letters may be used as many times as you'd like.

Scoring: 1 point for a 4 letter word, and 1 more point for each additional letter.

Each puzzle has 1 "pangram" that uses each of the 7 letters at least once. The pangram is worth 7 extra points.

example play

(based on game found by playing python3 play_puzzle.py RDGHNOU)

Type !help or !h for help
Playing puzzle index: 1
Your letters are: 
            _____
           /     \
          /       \
    ,----(    N    )----.
   /      \       /      \
  /        \_____/        \
  \   H    /     \    U   /
   \      /       \      /
    )----(    R'   )----(
   /      \       /      \
  /        \_____/        \
  \   G    /     \    D   /
   \      /       \      /
    `----(    O    )----'
          \       /
           \_____/

Max score: 88
Total words: 37
Your guess: GROUND
✓ GROUND              word score = 3        words found = 1/37    total score = 3/88    

Use the following commands for more details:

!i : instructions
!g : show letters
!f : shuffle letters
!s : player stats
!h : help
!q : quit

---

interesting puzzles

• Q as center letter: QAHILSU, QBEISTU

• X as center letter: XACESTV, XEFIOST, XAENSTU, XADEIRS, XAEINOT, XCENOST, XEFIPRS, XAERSTY, XDELOPS, XBELOST, XCDELSU

• Z as center letter: ZORIBTE, ZRBEOSU, ZCEILST,ZAEMNST,ZADELRS, ZADENRS, ZAEIKLS, ZACENOS, ZGILNOS, ZABDELR, ZBEGINO, ZABGINS, ZEILNOR, ZABDELS, ZAELOST

open-spelling-bee's Issues

syntax error

python3 play_puzzle.py RDGHNOU
Traceback (most recent call last):
File "play_puzzle.py", line 6, in
import utils
File "open-spelling-bee/utils.py", line 6, in
import generate_puzzles
File "open-spelling-bee/generate_puzzles.py", line 182
print (f'unique {params.TOTAL_LETTER_COUNT}-letter pool: '+str(len(pool)))
^
SyntaxError: invalid syntax

Documentation: highlighting interesting puzzles

In the README.md, it'd be cool to have a list of interesting puzzles that users can choose to play, rather than a random puzzle

python3 play_puzzle.py ABCDEFG

For example, including less-frequently used letters like X,Z,Q, or finding 7-letter pangrams, etc...

(also consider scraping previous NYTimes letters: https://www.shunn.net/bee/?past=1 )

Consider compressing data directory

If multiple word lists are to be added, as mentioned in #8, it would make sense to compress the data directory in some way. As a test, tar -acf data.tar.gz data shrinks the data directory from over 20 MB to less than 1. (Of course, implementing this using plain Python would be preferable to an external command like tar.)

Create checkpoints for returning to saved game

not needed, but interesting before turning into a GUI (see issue)

create solver/cheater code

Would run like this

python3 cheat.py ABCDEFG

• if it exists, the answers to that puzzle would be printed (with stats).

• if it doesn't exist, that puzzle would be generated (and saved locally) and the answers printed

Create tests

Would be helpful to have some testing code, especially before releasing to PyPi (see issue).

It's slightly complicated because play_puzzle.py has lots of user input, but some good solutions here.

Create web-app GUI

New word lists

The current word list is from Scrabble (TWL06) and contains 180k words. It's too many, and the NYTimes is also using a smaller word list with obscure words removed.

It'd be great to

• get a simpler word list

• create a simple download tool for users to use their own, which would then be multi-language support

---

BUT, rather than shorten the word list, it would be cool to make a puzzle difficulty rating. this way, a user could ask for easy and get one with many words with high-frequencies. Same for the pangrams, since some users play a puzzle just to find the pangram.

Release on PyPi for easy pip installation

Would be a good learning exercise to release as a PyPi package.

Allow users to "upload" puzzles

Using travis-ci, it's possible that a file could be added to the repository via Pull Request.

For example, adding a file named ABCDEFG to a repository folder would trigger a build and create a puzzle with those letters.

(also consider scraping previous NYTimes letters: https://www.shunn.net/bee/?past=1 )

Improving performance of puzzle generator

It's quite slow, at about 100 puzzles in 12 hours on my MacBook Pro (2015), although the filters for quality games are relatively narrow.

The code generate_puzzles.py and function make_puzzles() has multi-threading over the word_list (see code), instead of multiple arrays of letter combinations. Since the word_list is always constant, it's probably better to create chunks of letter arrays and do multi-threading over them.