Russell Beattie

There's a game that was launched a couple years ago on iOS called Seven Little Words which I was addicted to for a few weeks back then. The author did a great job coming up with a completely new game mechanic for a word puzzle which is simple, yet very compelling: There are seven word definitions listed at the top, and a grid of squares containing 2 or 3 letters listed randomly at the bottom, which you combine to make up the answers. When you first start, you may not be able to guess most of the words except for one or two, but as you successfully guess words, the number of squares left diminishes, reducing the number of possible letters for the more difficult words making them easier to guess. So what seems at the beginning like a set of impossible clues and a jumble of letters becomes, as you go along, much more manageable. Additionally, by listing the letters in chunks of 2 or 3, sometimes words will seem more difficult than they should be because of the way it has been divided - seeing a square with 'TH' and you immediately think the letters will be used as a digraph (as in the words 'think' or 'with'), whereas the word might actually be 'hothead', leading to a lot of 'ah-ha!' moments. It's really quite brilliant.

Anyways, back a couple years ago, I wanted more words (before they started selling word packs) so I decided to figure out how to make my own version of the game and whipped up a basic Javascript version. I changed some features it didn't have at the time like adding more clues, hints, shuffle and a timer. I didn't want to stomp on the developer's new game, so I didn't do anything else with the code. I ran across the project folder on my computer the other day and figured since it's been a couple years, I'd dust off the code and convert it into a pure HTML5 app and put the project and source online for fun.

If you want to play the game, go to Flip.io (I decided to use one of the various .io domains I've been hoarding since it was just sitting there), but I also put the source up on Github with an MIT license. Check it out and feel free to send me pull requests if there's something you'd like to change. :-) I posted about it on Twitter last week and already someone sent me a suggestion to add a 'sort' button, which I thought was a good idea and since it was relatively simple to do I added it in.

Here's some technical details: It's self-contained HTML5 web app - so there's no server-side script involved. I used JQuery, Lodash.js and Backbone.js as the main libraries to manipulate the UI, structure the code and manage the events and navigation. I'm not in love with backbone.js for this stuff (because it's a pain in the ass), but I'm using it on another project and didn't want to mess my mind by doing something different. It uses the HTML5 audio functionality to play 'ding' and 'sweep' sound files (in .wav and .mp3 versions to support the various devices/browsers) and HTML localStorage API to save completed puzzles (which doesn't work very well, honestly, so I may change this). In theory, I should be able to use a HTML5 manifest file to make the whole thing an 'offline app', but in practice that thing is a giant pain so I included it in the source, but don't actually use it. At one point I'll make the effort to create a 'real' Firefox or Chrome web app, but for now it's fine just hosted on a server.

If you do happen to dive into the code, note that I'll probably want to go back and refactor the reliance on JQuery and data-attributes that the GUI has. I just re-used the code I whipped up a couple years ago as I was figuring things out and it's pretty ugly/confusing in some spots. It'd be nice to separate out the display logic from the game management logic a bit more, as right now they're heavily mixed (like when trying to figure out if a square has been used or not: Is it visible? Then yes. If not, then no. This could be done better...). But for now it works ok.

The puzzle.js JSON file is generated by a Node.js batch.js script which pulls definitions from a words.txt file containing 30,000+ words imported from the Princeton WordNet dictionary (there's an import.js file as well which does this). The main intelligence of the app is actually in the puzzle generator. I need to add some better comments, but the general idea is that there are only a finite number of ways a set of words can be divided into a grid of squares containing 2 or 3 letters. The words are between 4 and 10 letters in length, and since they can only be split in a set number of ways - for example a word like 'bring' makes two squares containing either 'br' and 'ing', or 'bri' and 'ng' - it's possible to list out all the combinations and then randomly choose words to fill in the squares. The code itself puts the various possible combinations in a 'wordSquares' array, and then uses that to calculate out a random set of word lengths that could be divisible into a grid of squares, then it grabs random words from the words.txt dictionary file based on the lengths needed and then randomly divides them into letter squares accordingly. Because of the randomness at various levels (random chunk counts, random words to fit the chunks by total letters, random splitting of the words into squares) it can be hard to follow, but it works pretty well and can be used to make a puzzle of any number of words - I decided on 10.

The batch file could be set in a loop to create an unlimited number of random puzzles from the 30,000 words, but I've got it hard coded to create 999 puzzles as that's more than enough to keep me busy. Be warned though, because the dictionary definitions are random, sometimes the clues aren't the best - they could be *really* obscure, or many times include a word variation in the definition, giving it away. If you want quality, definitely go grab the original Seven Little Words as they edit each puzzle - my version of the game is definitely quantity over quality :-). Despite that, I actually enjoy playing the randomly generated puzzles quite a bit, and the hint feature is usually all I need to get by the more difficult/obscure definitions. I can honestly say it's been improving my vocabulary. Recent example: What's a seven letter word for "The phenomenon of forming chemical bonds?"

Final thoughts. It's just a simple HTML app, but I think the game could be used in lots of fun and useful ways. Swapping out the current words.txt dictionary for a list of your kid's vocabulary words would be a great way to help them study, or at the minimum making a grade-level appropriate word list would make a lot of fun for children (my son likes to help me when I'm working on a puzzle, but many of the words bewilder me, let alone a 5th grader). Swapping it for a dictionary in another language (Spanish, French, etc.) either straight, or with definitions in one language and the words in another, would be a great way to learn new vocabulary. The clues don't have to be straight definitions either - they could be details concerning today's news headlines for example, with the answers being the name of the city/person/place that was involved.

Anyways, even if it doesn't get used by anyone but myself ever, it still makes me happy to have it done. This is one of those pleasurable 'scratching an itch' projects which I can now use whenever I'm in the mood to play a puzzle game, which is exactly what I wanted. Hope you enjoy it.

-Russ