Puzzlescript: A Dev’s Guide to an HTML5 Puzzle Game Engine

Enterprise software normally falls into one of four types of application: publishing, search, fulfillment and conversation. Fortunately, the web excels at doing all of these. The same four elements are also needed to manage services or platforms you wish to maintain yourself or within your organization. This post is about one particular exemplar, an “open source HTML5 puzzle game engine” that we can easily explore and then extract these principles from. And at the same time, learn how to make cool little puzzle games.

“Increpare” (better known as Stephen Lavelle) wrote Puzzlescript sometime ago. It describes both a script and a platform that specializes in game rules for Sokoban-style tile games. Sokoban? You know, the game where you can only push crates about. This original set of puzzles is actually quite frustrating but is a good examination of your planning and execution skills. As you can see from the Puzzlescript gallery, there are many interesting variations of these small games.

Defining the Game Rules, Levels and Blocks

Let’s take a look at the Puzzlescript platform from the viewpoint of a creator; that is, a would-be publisher. All games are split into levels, traversed by the player character who moves with the arrow keys, or “W”, ”A”, ”S” and “Z”. Any level is composed of (poorly) drawn block objects arranged in such a way as to progressively prevent you from getting to the win condition. Completing a level moves you to the next level. Of course, the best way to absorb all this quickly is just to play any game. The only objects in the original Sokoban were walls, crates and floors with dots on.

So your job is to define your game rules, design the puzzle levels, and to draw the blocks.

To write your own game rules, you use Puzzlescript script. So for example the following rule deems that it if a player moves toward a crate, the crate should itself move in the same direction:

This represents the standard push interaction in Sokoban. Read it as “replace the pattern on the left-hand side (player moves into a square with a stationary crate) with the right-hand side (player moves into square, crate moves into next square)”. So it is effectively a translation. You need to think about how the game engine checks all the activities about to happen, interprets each translation, then redraws the game. If you are a regular puzzle gamer, this will be familiar from modern hits like “Baba is You”.

Let’s look at the code of one particular Puzzlescript game called Manic Ammo (the author tells me he is ok about this). It appears to be a fanciful tale of someone stuck in a munitions bunker. Now hit the “hack” link at the bottom and you can see the screen is split into three windows.

The right-hand top window allows you to run the game as it is currently compiled. So if you click on it and press space, the game plays in the window. But our interest is in the left-hand side source code window. You can see the title “objects” and indeed there seems to be a long list of formatted data. You will quickly discern that these are a visual representation of the game’s 5×5 blocks, with a numeric code for their basic colors. For example, the “Player” is made of a black and pink head, with a yellow stomach. What a splendid little person.

The rest of the listing is clearly broken into titled sections, including “Rules”. There you will see some familiar Puzzlescript:

So you can see that a player can push a shell just like a crate in our initial example.

The purpose of all this quick access is to enable potential creators to start their journey by fiddling with existing games. For example, you could joyfully make the game unplayable by adding this code line under the Rules. Rebuild the game and try it from the start:

Can you see what it does before you run it? “Winconditions” is the single rule that needs to be satisfied to complete a level. That is the reason the hack above is so disruptive.

This playful method of getting directly involved with the app works very well. Just uploading some app code to GitHub and requiring people to clone it and run it locally is actually a poor use of the web by comparison. Allowing low friction methods of engagement (like adding a code line and seeing what transpires on the same page) helps turn experimenters into creators.

The Puzzlescript Platform

Writing small games using puzzlescript is certainly as good a test of development and design skills as any code dojo. However, this post is about the platform overall.

When you develop and support an app or tool within a company, you need to think in terms of a Community of Practice. A tool or app will only thrive once it has dedicated users, and users must themselves become advocates. This means you need to run a forum, and at least guide it. Despite the age of Puzzlescript, you can probably see entries in the forum from the current month. Stephen updates the platform, hopefully without breaking older games. There are plenty of additions since I used it last.

How does this platform work for search and fulfillment? The gallery page is searchable visibly, by puzzle name or by author — maybe some tag metadata would not have gone amiss. Because each game can be represented as a link, other sites can curate the games as they wish. Having a single URL to edit or play is very effective. This site categorizes puzzlescript games by size and challenge. Indeed the current list of games seems to be held in a json file, so deriving your own index is trivial. Games are also hosted on itch.io.

But let’s appreciate how the platform emulates all those enterprise targets. First, it acts as way for you to discover what Puzzlescript is, what a basic Sokoban puzzle is, and introduces what defining the rules can achieve. It then allows the user to create their own puzzle, and it also archives existing puzzles. And there is a forum to allow players to swap hints and recommendations — as well as a place for formal communication from the author.

So the platform covers in a fairly direct way content creators, designers, hackers, players, maintainers and curators. Can you say that other platforms that support your tools, apps or services have delivered all the facets in such an efficient way?

Of course, the site itself is on Github, as it is open source. So why not design a nice small puzzle game, while appreciating how a good full stack platform works in the wild.

David has been a London-based professional software developer with Oracle Corp. and British Telecom, and a consultant helping teams work in a more agile fashion. He wrote a book on UI design and has been writing technical articles ever since....

Read more from David Eastman