Finazile example puzzles and document how to use them

example-puzzles/example/10/puzzle.moth

@@ -0,0 +1,90 @@
+Author: neale
+Summary: Making excellent puzzles
+Answer: moo
+
+Making Excellent Puzzles
+====================
+
+We (the dirtbags) use some core principles.
+If you're writing puzzles for our events,
+we expect you to bear these in mind.
+
+If you're doing your own event,
+you might still be interested in these:
+it's the result of years of doing these events
+and thinking hard about how to make the best possible experience for participants.
+
+
+Respect The Player
+---------------------------
+
+Start with the assumption that the person playing your puzzle is intelligent,
+can learn,
+and can figure out whatever you ask of them.
+If you observe in trial runs that they can't figure it out,
+that indicates a problem on your end,
+not theirs.
+
+
+Expect Creative Mayhem
+------------------------------------
+
+This is a hacking contest.
+People are going to be on the lookout for "ways around" your puzzles.
+This is something we want them to do:
+as a defender, they need to be always searching for holes in the defense.
+
+Here are some examples of "ways around".
+All of these have happened at prior events:
+
+* Logging into your appliance and changing the access password
+* Flooding your service off the network
+* Brute-force attacking your 2-letter answer
+* Photographing your printed list of answers while a team-mate chats with you
+* Writing a script to create hundreds of new accounts faster than you can remove them
+
+It's important to remember that they are here precisely to cause mayhem.
+If you set up a playground where this sort of mayhem ruins the experience for other players,
+we (the people running the event) can't penalize participants for doing what we've asked them to.
+Instead, we have to devalue points in your category to the point where nobody wants to bother playing it any more.
+
+
+Make The Work Easier than Guessing The Answer
+--------------------------------------------------------
+
+An important corrolary to expecting creative mayhem is that people are going to
+work hard to come up with creative ways to get points without doing the work you ask.
+
+It's okay to make your work about the same level of difficulty as guessing the answer.
+For instance, we use a few 4-byte answers.
+It would take about four hours to try submitting every possible answer,
+and if people want to spend their time coding up a brute-force attack,
+that is a constructive use of their event time and we're okay with it.
+Typically people give up on this line of attack when they realize
+how much time it's going to take
+(figuring this out is also a productive use of time),
+but once in a while people will go ahead.
+
+This means your answers need to be resistant to guessing and brute force attacks.
+True/false questions are, needless to say, going to result in us laughing at you.
+
+
+There's More Than One Way To Do It
+----------------------------------------------------
+
+Don't make puzzles that require a specific solution strategy.
+For instance,
+we're not going to allow puzzles that require a certain technology
+(such as "what is the third item in the File menu on product X's interface?").
+
+Rather, if your goal is to highlight a technology,
+you should create puzzles that show off how great the product is for this application,
+compared to alternatives.
+Something like "mount this file system from 1982 and paste the contents of the file named `foo`"
+might be trivial in a certain product and take hours by other means.
+That's fine.
+That's what we want to see.
+
+----
+
+The answer for this page is `moo`

example-puzzles/example/100/puzzle.py

@@ -0,0 +1,25 @@
+#!/usr/bin/python3
+
+import io
+
+def make(puzzle):
+    puzzle.author = 'neale'
+    puzzle.summary = 'crazy stuff you can do with puzzle generation'
+
+    puzzle.body.write("## Crazy Things You Can Do With Puzzle Generation\n")
+    puzzle.body.write("\n")
+    puzzle.body.write("The source to this puzzle has some advanced examples of stuff you can do in Python.\n")
+    puzzle.body.write("\n")
+
+    # You can use any file-like object; even your own class that generates output.
+    f = io.BytesIO("This is some text! Isn't that fantastic?".encode('utf-8'))
+    puzzle.add_stream(f)
+
+    # We have debug logging
+    puzzle.log("You don't have to disable puzzle.log calls to move to production; the debug log is just ignored at build-time.")
+    puzzle.log("HTML is <i>escaped</i>, so you don't have to worry about that!")
+
+    puzzle.answers.append('coffee')
+    answer = puzzle.make_answer()        # Generates a random answer, appending it to puzzle.answers too
+    puzzle.log("Answers: {}".format(puzzle.answers))
+