Phil's Musings notes from a peripatetic programmer

Embeddable and Accessible PuzzleScript Games

I ❤️ Puzzle Games.

I want kids to play games that don’t talk down to them, encourage them to figure out game mechanics on their own, and I want non-sighted people to play video games.

Introducing: the puzzlescript package.

a couple levels of the game Pot Wash Panic

Many games have puzzles sprinkled in, but I like ones that are distilled into just solving puzzles.

I first realized how engrossing these were while playing The Witness with friends. One person would control the player but everyone would be solving the puzzle in their head just by watching. We played together for days.

Then, I tried it with kids. It turns out, a 6-year-old grasped the puzzle concepts in The Witness faster than her parents and was explaining to her parents how the puzzles worked.

Then, I started looking for more and stumbled upon increpare’s awesome PuzzleScript.

Unlike other video games that tend to teach kids to memorize facts (like “Carmen San Diego”, “Oregon Trail”, or “Math Blaster”), these encourage kids to think critically, and problem-solve in groups.

Specifically, PuzzleScript games are interesting because the whole game is a text file and the levels are typically pretty small. This means it’s easy for kids to explore but it also makes the games playable by people that can’t see. The reason is that all of the sprites have human-readable names. So we can read those out instead of just showing colored pixels.


Inspiration came from both the tons of easter-eggs found in software (Chrome Dino Game, various Microsoft ones and commandline tools) as well as a desire to get more people in general to play video games.


  • get kids in classrooms playing these games
  • get vision-impaired people playing these games
  • get 404 pages to have these games when something is broken (like the Chrome Dino Game). Example: this website’s 404 page
  • get people to play these instead of Sudoku to exercise their brains more

Try it out!

Games can run embedded in a webpage or in a commandline terminal. There are over 200 games to choose from!


All you need is node 4 or higher and then run the following:

npm install --global puzzlescript

See philschatz/puzzlescript for examples.

Embed in a Webpage

  <table id="the-game-ui"></table>
  <script src=""></script>
    const gameSourceString = '...' // Source code for the game
    const table = document.querySelector('#the-game-ui')
    const engine = new PuzzleScript.TableEngine(table)
    engine.setGame(gameSourceString, 0 /*startLevel*/)

Visit the demo page to play several games (there are over 200), or see this website’s 404 page for an example of using it in a 404 page.

For Next Time

I would like to go through more details on how the code is organized. But if something does not work or is not clear, create an issue.

More Examples

Mirror Isles (original)


More examples can be found in the README or see the demo page to play them in a browser.