About PuzzleMaze

PuzzleMaze Version: 2.04; Last Updated: 27-Feb-2016

Overview

PuzzleMaze is a general framework for hosting puzzle hunts. You solve puzzles on a web page or outdoors, and when doing so, enter an answer to unlock further pages with more puzzles, and so on. Pretty simple concept.

Games

The main unit on PuzzleMaze is a "game". A game has a start page and an end page. If you or your team get to the end page, you have "solved" the game, get its avatar as a trophy, and get listed as a solver on PuzzleMaze. Woohoo!

Some games may have outdoor treasures or other features to find (such as letterboxes, silver coins, or monuments), either as required objectives, or side goals. I suppose that all depends on how much time and creativity the puzzlemaster has.

It may or may not be necessary to solve all the puzzles in a game to get to the end of it. It all depends on how the puzzlemaster sets it up, either as a single linear path thru the game, multiple paths with or without deadends, and so on. Hopefully, if they have any talent, it will be interesting.

Solving and unlocking in a game can be pretty arbitrary and flexible. Obviously, in its simplest form, you solve a puzzle, and unlock the follow-on page. But, it may be set up to require the solving of 3 puzzles on a page, or X of Y, or whatever. Maybe 12 random puzzles various places in the game need to be unlocked to open a 13th page somewhere else. Who knows? Perhaps random writings on pages are clues to other puzzles. The framework is flexible, but content and puzzlemaster creativity, as always, are king.

The Sample Game on the Games page gives a general idea of how things can work. Nothing fancy really, but slightly cooler than static puzzle pages, I suppose.

Game Icons

You may or may not see one or more of the following icons on the Games page. If you do (and even if you don't), this is what they mean --

  Game is completely online
  Game requires finding location(s) outdoors
  Game is under development
  Game is private, password required
  Game is pay to play, but there is hidden treasure to be found

Teams

The framework is team-centric. That means if a team joins a game, all players on that team are automatically joined to that game. More importantly, if one player on a team solves a puzzle or visits an unlocked page, it is considered solved/unlocked for everyone on the team (simply unlocking a page isn't sufficient; a visit is required, as it is possible that the problem of knowing it is unlocked or finding it in the game has not been solved).

However, since some players may still want to solve all puzzles for themselves, even if a teammate has, such solves are not automatic, but are given to the player as an option to auto-unlock when the time comes. Thus, some players may sponge on the success of their teammates, while others may still solve all the puzzles they encounter if they choose to.

If you don't have a team, you may still join a game as a Lone Wolf. You just don't get the benefits of shared team progress. Don't create a team just to join a game, just join as a Lone Wolf, its easier.

Note that you always own your progress thru a game. If you join a game as a Lone Wolf, and then join a team, your team inherits your progress. If you leave the team, you remain on the game with your progress to date as a Lone Wolf. If you join a game as a Lone Wolf, and a team your are on later joins the game, you and your progress are sucked into the team.

Confused yet? Don't worry about it. It should all work out reasonably behind the scenes. Join a game as a Lone Wolf and start hacking, and if and when your team captain sets up a team and joins a game, it will all just work out.

Finally, you may not be on a game via more than one team, for obvious reasons. You may get a error message to that effect if you try it, assuming the code isn't too buggy.

Leaving a Game

In certain circumstances, you may leave a game. There is generally no reason to, unless you wish to join a different team. When you leave a game, all progress you have made in that game is deleted.

Registration

Registration is simple. You have to provide a username and password, so other people know who you are and PuzzleMaze can track your progress thru a game. PuzzleMaze doesn't care about your e-mail address, (no offense), which is nice, but the downside to that approach is that the team joining process is a password mechanism rather than an invite mechanism. Oh well, it is what it is.

You may optionally also provide a small avatar, or have one randomly generated for you. The generated ones are kinda cool, if not on the campy side.

You may also join as a Guest if you don't want to provide a username and password. Guests get randomly assigned usernames and avatars, and may not join or create teams. Their accounts, and all game progress, are also automatically deleted after a month or so, tho they still remain in the solved Hall of Fame.

Tracking (PuzzleMaze Widget)

This is because, when in a game, PuzzleMaze gives you a window of bookmarks to all the pages that you have visited. Just click "Your Links" using the PuzzleMaze widget at the bottom left of every game page.

Since PuzzleMaze is tracking you, it is tracking other players/ teams as well. In addition to "Your Solves" under the PuzzleMaze widget, you can see rival's solves, as well as a list of puzzles that have been solved, with the player/teams that have solved them. Just choose the appropriate option under the PuzzleMaze widget.

(Note that "Your Links" may be different than "Your Solves", as pages and solves, technically, are different things (the architecture, in fact, is link-based and not page-based at all, FWIW). You don't have to worry about any of this, but the short answer is that some pages may be cruft or clues, without an actual puzzle to solve).

(Note that some options to see rivals and puzzles solved may not be available. This is a game by game option, and the puzzlemaster may set up various levels of opacity to restrict this information. For example, you can set it up to see how many puzzles rivals have solved, but not disclose which ones, and so forth. Me, I prefer to see this stuff, so I would tend to set games up with minimal opacity).

Once you've solved a puzzle, you don't have to answer it again. If the stock PuzzleMaze buttons are being used, the "Answer" button will be replaced by a "Proceed" button. If traditional links or artwork is being used for the Answer popup, then you can silently click thru if you have previously solved. However, you may want to answer a question again anyway (so see later about this).

Options (PuzzleMaze Widget)

There are a few options under the PuzzleMaze widget. Hopefully "Show Avatars" is obvious. If not, if set, avatars will be shown. (Note this this also applies to the main PuzzleMaze pages, but is buried in the in-game PuzzleMaze widget. Go figure).

"Auto Resume" means that when you log off, you will be resumed to where you left off upon re logging in (discussed previously, but here is where you can turn that off).

"Skip Answered" is prolly the only sometimes useful one. If set, the normal behavior of skipping previously answered puzzles occurs. However, there may be times when you wish to answer a puzzle again; if so, you need to toggle this. Remember to toggle it back, as it can get annoying and confusing to see a "Proceed" button, and then an Answer dialog popup in your face.

Scoring

Scoring is another one of those random and arbitrary things. You can score points for solving puzzles, clicking links, visiting pages, kicking field goals, and so much more. IMHO, scoring is silly; the only score is 1 or 0 (did I solve the game?). Or, did I solve some puzzles and have fun, or beat team X to a treasure?

But its there. Why did you do it? Cause it was easy. Just like the final line of The Stepford Wives -- "Why did you do it?     Because we could."

(Note that you can score negative points, depending on how the game is set up. Since I haven't decided whether negative points should count towards "maximum points" (and prolly never will, since I don't care about scoring so much), I think it is possible to score more than the maximum by avoiding negative events. I'm pretty certain that it is like this in the sample game)).

Answering

When solving a puzzle, you click on the "Answer" button or some sort of link. Duh. The Answer widget has some smarts, but it is only as smart as how the puzzlemaster set it up.

Architecturally, all answers are case insensitive, so that can't be changed too easily (well, its actually just one line of code, but out of the puzzlemaster's control. Should it be?). However, if the answer is "60 days", it can be set up to take "60", "60 days", "sixty", "sixty days", "LX", and so forth. Additionally, if the answer is "Abraham Lincoln", "Lincoln", "Abe Lincoln", and "Abraham Lincoln" all will prolly work, but "Honest Abe" may be more of a long shot. As a general rule, don't spell numbers; less is more; go with the shortest possible answer that makes sense, and spell things correctly. So in these cases, "60" and "Lincoln" are the best guesses. Obviously, for "password" style puzzles, none of this blather matters, except the case insensitive thing.

A game can be set up to have "guess limits" -- either a number at the game level that applies to all puzzles, or one that overrides the game level limit at the puzzle level. This is to mitigate endless guessing and mindless scripts. I have mixed feelings about this, and what the numbers should be set at, but as this is a puzzle hunt framework, having this configurable is obviously a required feature. If you see a guess limit message, you will have to wait 'til tomorrow to hack at it some more.

The most important thing to know about the Answer widget is to be aware that it can do different things based on different answers. It can be configured to send you to a different page based on your answer. It can be configured to not tell you that you are wrong, even when you are. The best defense against eevil puzzlemasters who do this without warning is to make sure you solve the puzzle correctly and type in the correct answer. Note that there can be multiple "correct" answers that do different things (e.g. a text adventure style maze).

Teammate skip is another feature of the Answer widget to be aware of. As discussed above, if a teammate has solved a puzzle, when you click that puzzle's Answer button, you can either solve the puzzle yourself, or type in "~Skip" to sponge on your teammate's work. A message to this effect will appear on the Answer widget when it applies. It is up to team policy and individual pride to decide how to proceed when this situation arises.

Finally, PuzzleMaze doesn't like weird characters in answers. If you accidentally or intentionally type them in, you will be taken to a weird place. I may add client-side processing to fix this someday, but since the server-side processing for this is needed anyway, I doubt I'll bother. Just don't use weird characters. If you do, and visit a weird place, just hit the "Back" button (I could do this on the server for you; I just don't want to). A list of such characters appears on the widget.

Technology and Browser Support

PuzzleMaze was developed using Firefox, and that is the only browser that is officially supported. IE 11 and Chrome are de facto supported, as they more or less work, outside a stupid bug font bug in Chrome, introduced in version 37. While this bug has been acknowledged, it does not appear that it will be fixed, but we'll see. It is not catastrophic; it just makes certain elements look silly. I was surprised that IE 11 passed all the compatibility tests I did, while Chrome did not. Of course, I didn't do too much compatibility testing at all; more bugs will be found.

IE versions before 11 and other browsers are not supported. Life is too short to care about this, as, at least to me, it is not an interesting puzzle or problem. Those that find such problems interesting are more than welcome to send me updates to the html or css if they want to. The only other browser that it has been tested in is IE 9, and that did not go so well. I imagine other webkit browsers, such as Safari, have a decent chance of working somewhat. I have nothing against other browsers or their old versions, but this is just a hobby, and I don't have the time.

Just think of it like this: finding a browser where PuzzleMaze works is actually part of the puzzle :)

As for mobile, since I don't own a mobile device, there's no chance. Sorry. If I did, I'd make it work, but PuzzleMaze doesn't really seem like the thing you would do on a phone anyway. Hopefully, if you have to type in a code from a letterbox or monument, it will work well enough to do that in the field, but it might not. When I get a phone, I'll work on it if I have the time, but I'd rather write puzzles, and the odds of me getting a phone are lower than it working on IE.

One of the goals of the PuzzleMaze project was to build a web site without any javascript, as I find javascript hideously annoying. (I'm sure many will find the CSS-based approach I used even more annoying).

But I couldn't do it. There are about 30 lines of javascript code in there, so you will need javascript enabled on your browser to make it work right.

You also need to have cookies enabled. See "Privacy" under "Terms of Use" if you care about what PuzzleMaze does with them, but it is the obvious, and nothing more.

Puzzlemaster Mode

On second thought, after banging this out all morning, I need a beer. I'll write puzzlemaster mode later, and I suppose it should only be on the puzzlemaster page anyway.

But its cool, you bang out a game in html, and the framework sucks it in, and sets up 90% of the game for you. That's the coolest part of the whole framework, but there is no reason to write about it here.

Revision History

PuzzleMaze Version 0 (first line of code); 20-Jul-2014
PuzzleMaze Version 1 (initial semi-working prototype); 04-Nov-2014
PuzzleMaze Version 2 (support for Maze of Doors); 09-Jan-2016

• Added support for objects
• Added new opacity levels
• Changed the way solved puzzles is sorted so opponent solve order can't be determined
• 100% percent of a game is now auto-generated from the html source
• Many secret features needed to support Maze of Doors
• Made team elsewhere unlock less restrictive in some cases
• Added a second level of auto-generation so the source maze can be specified in the database, and the source html auto-generated

• Made games visible to the cloud without requiring login
• Cosmetic changes on scoring windows
• Monkeyed with the wrong guess penalization algorithm

• Sort the Score window by points so it looks like a Leaderboard (this means solve order of each puzzle is now random, not time order); renamed Leaderboard
• Fix bug in the Leaderboard window when team names differ only by case
• Added Answer Log window for the PM

• Fix an information leak bug in the Leaderboard window
• Sort the Solved Puzzles window by time solved, both for the puzzle and the solver, so we just need to look at the top to see what was just cracked, and solvers get 'first solver' cred.

• Fix a bug in the Solved Puzzles window
• Sort the Games by inception date rather than gamename

PuzzleMaze: "Works as Coded" :)

Verified bugs since live: 3