Cheery Chimp

The first version of this game was hexagons. It was built, it worked, and it was wrong, and finding that out cost a day.

Word Grid is a six-by-six field of letters. You trace a path through adjacent cells — horizontally, vertically or diagonally — and if the letters along it spell a word, you have found it. The path highlights green while what you have spelled so far is a word and red while it is not, so the board tells you the answer before you commit.

None of that was the plan.

The honeycomb that had to go

The original design was a hexagonal field: hex cells packed without gaps, the whole board shaped as one large hexagon, with a smooth hexagonal border drawn around it to tidy up the stepped edge. It looked good. Honeycomb is a pleasing shape and the border trick solved the ragged-edge problem neatly.

As a word game it did not work, and I think the reason is that you read a letter board in lines.

A square grid gives you rows, columns and diagonals — three families of straight lines that your eye has been trained on since you learned to read. You do not consciously search a word-search puzzle; you sweep it. A hex grid has none of those lines in any orientation you have a habit for. Every cell has six neighbours instead of eight, arranged at angles you have no instinct about, and the board resists being scanned. You end up examining it one cell at a time, which is not playing, it is auditing.

So the hexagons went in the bin and the grid became six by six squares. The rebuild took less time than the original and the game was immediately better, which is the usual and slightly humiliating outcome of throwing a first version away.

Every word that is in there

The second change was larger than the first, and it started as a question: is it reasonable to work out every word a given board contains?

It is. Thirty-six starting cells, a depth-first walk outward from each, no cell reused within a path, and paths that terminate naturally because the board is small. The thing that makes it fast rather than merely possible is prefix pruning: at every step you ask not "is this a word" but "does any word in the dictionary start with this", and the moment the answer is no you abandon that branch and everything below it. Most branches die after three or four letters. The search finishes before the board has finished animating in.

What that enables is the part that changed the game. Instead of a score, the board comes with a list of every word it holds, in alphabetical order, each one shown as a row of empty boxes — one box per letter. You cannot see the words. You can see how many there are, how long each is, and exactly how many you have not found yet. As you spell one, its boxes fill in.

That converts the game from an open-ended scoring exercise into something with a bottom. There is a finite, knowable set of words in this board, and you are working through it. "I got eleven" means nothing on its own; "I got eleven of forty-three, and there is a nine-letter one in here somewhere" is a reason to keep looking. Scoring by points was eventually dropped altogether, because next to a completion count it was measuring the wrong thing.

Finding a word also gives you a way to look it up. A word game that regularly hands you a real English word you have never seen — and a six-by-six board will — ought to be able to tell you what it means.

Two ways to select, fighting each other

You can tap cells one at a time and tap the last one again to submit, or you can press and drag through them and let go. Supporting both is obvious from the outside and was the single largest source of bugs in the build.

The first failure was that tapping stopped working entirely. Pressing down on a cell set the game into drag mode immediately, and since every tap begins with a press, every tap was being treated as the start of a drag that never went anywhere. The two modes were not fighting over which gesture was which; the drag mode was simply claiming all of them.

The fix is to make drag mode conditional on something a tap never does: pressing down only records which cell you pressed, and drag mode starts when the pointer reaches a different cell while still held. A tap never moves to a second cell, so it is never mistaken for a drag, and a drag always does, so it is never missed.

Then a subtler one, and a classic. The code that started drag mode set the flag and, a few lines later, checked the flag to decide whether to add the cell under the pointer. In React a state update is not a variable assignment — the new value does not appear until the next render — so that check read the old value, saw false, and returned early. The visible symptom was that a drag never highlighted its second cell: you pressed, moved, and nothing happened until the third one.

The fix was to stop asking. When drag mode starts, both cells — the one pressed and the one moved to — are added in the same single update, so nothing has to read a flag that has not landed yet. Any time you find yourself setting a piece of state and then consulting it in the same function, that is the bug, and no amount of reordering the lines will save you.

One more piece of that: dragging back over a cell you already have does not remove it, it truncates the path there. You are not toggling cells on and off, you are rewinding to a point in the route. Anything with an order wants that behaviour rather than a toggle, and a selection of letters is very much a thing with an order.

Silence on the phone

The sound effects worked on a desktop and were completely silent on a phone, which took a while, because nothing errored.

Mobile browsers will not let a page make noise unless the audio context was created or resumed inside a real user gesture — a deliberate defense against pages that start playing at you on load. The code was constructing a fresh audio context for every individual sound, which meant each one was born suspended, outside any gesture, and quietly refused to play.

The fix is two small things. Create one audio context and keep it, rather than one per sound. And on the very first touch or click anywhere on the page, resume it — synchronously, inside that handler, before anything else. After that it stays running and every later sound plays, including the ones fired mid-drag when no new gesture is starting.

It is worth knowing about because the failure is so quiet. There is no error, no warning, and on the machine you are developing on there is no symptom at all.

The word list has a header

A small thing that is worth doing properly. The dictionary is a plain text file fetched at load, and it opens with a header block separated from the words by a blank line — licence, provenance, the usual.

The lazy option is to strip the first few lines by count. The right one is to split on the blank line and take what follows, because then the header can grow or shrink and nothing downstream cares. The number of lines in a file's preamble is exactly the sort of constant that is correct when you write it and wrong two years later, by which point the symptom is three missing words at the start of the alphabet that nobody ever notices.

What I took from it

Two things, both about knowing when to stop defending a decision.

The hexagons were not a bad idea badly executed. They were a good-looking idea that turned out to be incompatible with how people actually read a grid of letters, and no amount of polish was going to fix that, because the problem was underneath the polish. The only way to find that out was to build it and play it.

And the points were not a bad scoring system. They were an answer to a question the game stopped asking once it could tell you how many words the board contained. Once there is a real denominator, a score is just a number next to a better number.