2 Tone Game: Source Code

These notes are not complete. They are just a sparse outline. But if you send me questions, I'll fill in more information.

Spoiler Warning

This is the source code for a game with puzzles. If you look through the source code, you will see the answers to those puzzles. If you wanted the joy of solving those puzzles, beware of spoilers in:

• logic.py This file contains answers, hints, and partial answers. It is full of spoil. Beware!
• s/ This directory contains the puzzles themselves. This is arguably spoiler-ish material if you wanted the joy of "unlocking" these puzzles in the game.

Where? Here

Overview

The 2-Tone Game is a baroque web server. It administers a "puzzlehunt" game. It runs on top of Google App Engine. It's written in the Python programming language (plus some Javascript). There's also plenty of static web content, the game's puzzles.

More about

• Python programming language
• App Engine

Lessons Learned

I'm sharing this code as an example; but in many places, it's a bad example. This was a learn-as-you-go project. Example code should be exemplary; this code is not. Sorry about that. If I were starting a new such project, perhaps peeking at this project's code, some things I'd keep in mind:

• Perhaps the most important thing this program does is keep track of which puzzles a player has unlocked and/or solved. However, it does this in an overly-complicated way. It uses an unordered list of strings, but doesn't access the data structure in a list-y way. Usually, you want to know either
  • the player's state on a particular puzzle (how long have they been working on the Crossword puzzle?); or
  • a list of puzzles in the game, along with the player's state on that puzzle, so that you can display some kind of overview to the player. E.g., "Example puzzle: solved! Anagram puzzle: unlocked. Braille puzzle: unlocked."

  In hindsight, a simple dict would have been simpler.

• There's a lot of code here to handle OpenID login and user sessions, grabbed from a couple of excellent open source projects. I've got code from those projects working together... tweaking code that I didn't really understand. Then, in May 2010, Google announced some new OpenID support "baked in" to App Engine itself. If I were starting over today, I'd use that "baked in" stuff instead.
• The code organization... uhm, this code grew out of my first "hello world" app engine program, and I didn't really know that was happening. A lot of my projects start out messy like that, then they grow to a size where I think OK, it's time to organize this crap. Unfortunately, this code started working before I got sick of wallowing in it, and thus never organized it.
• There's some complicated JS to draw the checkered decoration at the top web pages. There must be a better way to do this; this was the first thing I stumbled onto that worked in a variety of browsers, including my old Blackberry, whose browser doesn't even run Javascript. If I had it to do over again, I'd choose an easier-to-render decorative element.
• I'd keep an eye out for more ways to separate the "game logic" out from the other code. The game logic changed a lot. I'm glad I separated that stuff out as much as I did.
• The list of puzzles changed. Puzzles got added; puzzles got removed; puzzles' names changed. I'm glad I didn't assume a stable set of puzzles when I wrote this code.
• I'm glad I didn't "roll my own" login system, but instead used OpenID. I didn't want to store user passwords. As it is, my site doesn't have anything that evil hackers want. But if my site stored users' passwords, then hackers might want that: many users use the same password on all their sites. Hackers know this, know that if they can break into that goofy little puzzle site, they can get Amazon passwords. I wish that more goofy little sites like this one used OpenID.

Code "Organization": the Files

• about The Game's "about" pages. HTML
• app.yaml App Engine uses this to figure out which code to invoke when the user visits, say http://www.2tonegame.org/about/credits or whatever.
• ddjs/ Javascript for an administrator "dashboard", built on top of Google's Closure Library and Closure Tools.
• fetcher.py part of the openid sample implementation
• gaeu Copy of gaeutilities, a set of Google App Engine Utilities. I use the Sessions code from here. That is, this code sets a cookie on the user's browser that distinguishes the user as they move from page to page.
• index.yaml App Engine uses this file to figure out how to index its Datastore. Automagically generated.
• logic.py This is the "Game Logic". Here's where I keep information about the puzzles. This is also where I keep functions that implement game "rules" like choosing which puzzle to unlock.
• main.py A bunch of Python web server code.
• openid/ If I were a more conscientious person, I'd remember exactly where I got this Python OpenID code. Some lovely open-source-ish place that deserves credit for it. Maybe from the Debian package?
• player.py Data structures that represent a player, plus some handy functions for interacting with these data structures.
• README Spoiler warnings similar to what you see at the top of this page.
• robots.txt Asks polite web search crawlers to not index the puzzles.
• s/ Directory of static web content. This is where the puzzle files live.
• settings.py I think that the GAEU sessions code needs this?
• store.py part of the openid sample implementation

Questions

Back