Tis the Season

I should add a category for lawsuit synonyms.

...to create knock-offs of popular games from media conglomerates.  Today, I want to chat about my experience creating a Connections clone.  Connections is a game that the New York Times recently released wherein the player attempts to match groups of 4 words into 4 categories related by a hidden theme.  The game is entertaining and also highly frustrating when you're unable to make the connections in 4 guesses.

I made the clone to help a friend with her annual Christmas pub crawl.  Ahead of every annual event, she assembles various games for the attendees to play and had mentioned putting together a paper-based version of Connections as one of the games.

Given that the pub crawl was a few weeks away and I felt I could deliver something workable in that time frame, I decided to take a stab at creating one on her behalf.  The rest of the post is about the technical decisions I made as well as some of the details while writing the game. 

In addition to helping a friend out, I also wanted to exercise my technical chops with a fixed time constraint in play.  I've read a few posts on LinkedIn by No Code proponents who bemoan the use of agencies that charge $50k for minimum viable product work.  Their counter-proposal advocates the use of No Code or Low Code tools to generate an MVP and spending no more than $10k with the expectation that, should the product prove viable, it will be thrown out and rewritten with more traditional programming methods to stabilize the product and make the code maintainable.  If the product doesn't work out, the amount of effort and treasure expended is relatively low, so, why not?

I find this to be a reasonable proposal, but I thought, given that I have a software development background, would I be able to craft a more durable MVP in a reasonable amount of time for what would be a reasonable cost?  This project, in conjunction with my work on the flight features of Travelectable that I'll be enabling soon, gave me a good chance to test my abilities.

I briefly entertained the idea of letting an AI agent take a stab at creating a version, but decided against it.  I've heard pretty glowing reviews for some of the agents - particularly Cursor and Replit, but my initial encounter with Replit's version left me wanting.  Granted this is one encounter, but I decided not to spend any time fighting headaches a robot generated for me.  Plus, it seems like the pricing for agents is quickly increasing to match the overall AI-hype level and, likely, to recoup the costs from running AI at steeply discounted prices to get everyone hooked.

I'd like to investigate the viability of agents as, at least, rudimentary code monkeys, but I'm not willing to spend more than a couple of dollars or use it for anything other than an exploratory project for fear of wasting time correcting mistakes for something that's not going to learn anyway.

Showing that I've still got the developer's flare for estimation, I guessed that the project would take me roughly 8-10 hours with another 6 to create admin functionality.  Giving myself the benefit of the doubt, I'll say that my estimate was 16 hours.  I was only off by a scant 50% at a total of 24 hours.

I've written at length about estimates and contend that it's pretty difficult to get them to match up without significant padding, even when the developer is experienced.  Luckily, this was well within any bounds I've established to make money off such a project.

As with Travelectable, I didn't really need to do much in the way of gathering and interpreting requirements, since this game is a clone.  Nor did I need to bother with game or interface design for the same reason.  These are key points to a good application and add significant time to the completion of the project, but all of that was already available to me.  My job here was simply to make a reasonable facsimile of the NY Times app.

At first, I considered making this a single-page app and using a Javascript frontend framework for the construction.  Had I done that, I would've used Svelte.  I've tinkered with it in the past and like its straightforwardness vs. frameworks like React, which though powerful, are also significantly more complex.  

Instead, I thought my progress would move faster using Python, and fell back on what's quickly becoming my common toolchain - Python, htmx, _hyperscript, and Tailwind CSS, or what I'll coin the Bill the Cat stack for its melodic acronym of Phht (make sure you stick your tongue out of your mouth and blow in order to effect the correct pronunciation).

I was happy with my choice of technologies for the project.  If you want to follow me along and jeer me, the code for the repository is here.  It comes in at a relatively tight 593 LOC (or .6 kLOC if you're counting by thousands of lines of code) spread across 7 HTML files, 1 app.py file, and 1 CSS file.

In my constantly evolving love-hate relationship with GenAI and code completion, we were mostly in love during this project.  Like a long-term lover, I've come to accept the quirks of my digital paramour and have recognized its tells when it's lying and comes home smelling like perfume and hallucinations.

It helped me out with one key visual effect that Tailwind couldn't assist with and just worked the first time out, which was a pleasant surprise:

Not a hard thing to put together if you're down with CSS, but it saved a back-end savage like me at least 10-15 minutes of searching and tinkering.

Though AI code completion was extremely useful this time out, the biggest productivity gain by far was my use of _hyperscript.  I've mentioned it before and dabbled with it here and there on parts of my Travelectable project, but this was my first time using it more than just in passing.  I even bothered to spend a couple of hours reading the docs (and another couple reading the docs for htmx).  I ultimately forgot most of what I read, but I liked that the documentation isn't overwhelming.

It's possible that seasoned front-end programmers may find the syntax off-putting, the functionality restricted, or the code difficult to maintain at a larger team scale, but I found it a pure joy.  Then again, Erlang is my favorite language, so take my recommendation for what it's worth.

Here's the code for the dynamic functionality of the 'Submit' button for the game:

(It's worth noting that you can place _hyperscript code in its own file to make it more modular and easier to maintain if you're working on larger projects.)

In (sorta) plain English, here's what the _hyperscript code does when clicked (or when one of the game tiles is clicked):

If the submit button isn't disabled, add animation code to make the selected tiles "jump" when the submit button is clicked.  The wait command acts synchronously, so the code acts in the sequence written without any actions mysteriously occurring before they're expected.  Once the animation code is complete, send a custom event checktiles which will be processed by the htmx trigger code in the button element.

If 1 of the game tiles is selected and fewer than 4 of them have been selected, move (or keep) the 'Submit' button into a disabled state and style it appropriately (in the game screenshot above, this default disabled state is displayed).  If 4 tiles are selected, then enable the button to submit the user's answer.

Most of the time I spent on the game was fighting through the quirks present in client-side JavaScript that _hyperscript is unable to hide.  Given that _hyperscript is still fairly new (pre-1.0) I also struggled with a few concepts that aren't described in detail in the documentation, but, by and large, I had a lot of fun using it for the app and was happy with its ease of use.

This app isn't complete by any means:  

• It's not scalable to the thousands of users that the NYT app likely handles.
• It's not built for multi-tenancy if several people want to use my instance to create their own personal versions of the game.
• It's easy to cheat and reset your chances if you know the cheat code (though it's easy to cheat in the NYT version by using incognito mode).  Indeed, it's easy to change the words and themes if you know where the admin panel is located.

But, it's still a working MVP, and at least according to 20 or so merry tipplers, it was a joy to use for their holiday pub crawl.

Ho.  Ho.  Ho.

Until next time, my human and robot friends.