pupate

writing-dynamic-puzzles.md

 1How to write dynamic puzzles
 2===============================
 3
 4The primary reason we use dynamic puzzles is so that the answers can change. People can publish all the answers, or save them for the next event. With dynamic puzzles, they'll have to do the actual work again to get the points.
 5
 6This document will guide you through writing dynamic puzzles using a JSON-generating script (e.g., mkpuzzles) to define the puzzle content.
 7
 8
 9What is a dynamic puzzle?
10-------------------------------
11
12Dynamic puzzles are a type of puzzle where the content is generated programmatically, often with some element of randomness. The puzzle script generates a JSON description of the puzzle, which the contest system uses to present the challenge to contestants.
13
14Dynamic puzzles include several key elements:
15
16Randomized answers: 
17Answers can vary between runs, ensuring that each instance of the puzzle is unique.
18
19Customizable hints and debug information: 
20Contestants can be provided with dynamically generated hints to guide them toward the solution.
21
22Attachments and other assets: 
23Static files like images can be included, but the puzzle content itself is dynamically created.
24
25The generator program is always named mkpuzzles.  It can either be mkpuzzles.py or mkpuzzles.sh. On Unix, any extension will be recognized, but on Windows, it only supports .py and .sh.
26
27
28Structure of the puzzle generator (mkpuzzles)
29------------------------------
30
31The mkpuzzles generator script contains three main functionalities:
32
33Puzzle generation (puzzle command):
34This command outputs the dynamically-generated puzzle as JSON. The JSON includes elements like:
35    Puzzle description (Body field).
36    Correct answer (Answers field).
37    Debug information (hints, logs, etc.).
38    Any attached files (images, documents, etc.).
39    File retrieval (file command):
40    This command allows access to attachments such as images or other media referenced in the puzzle JSON.
41
42Answer checking (answer command):
43This command accepts a user's answer, compares it with the dynamically-generated correct answer, and returns whether the answer was correct.
44
45
46 Setting up a dynamic puzzle
47------------------------------------
48Follow these steps to create your dynamic puzzle:
49
50Create your puzzle directory:
51Start by setting up a directory dedicated to your puzzle. For example:
52    $ mkdir dynamic-puzzle
53
54Write the mkpuzzles script:
55Place the mkpuzzles.py script in the puzzle directory. Write your generator program to create dynamic puzzle content, including random elements for your questions and answers.
56
57Include attachments:
58If your puzzle requires attachments (e.g., static images or other files), ensure that they are placed in the same directory as the mkpuzzles.py script and referenced correctly in the JSON.
59
60Test your puzzle:
61Execute the three commands to verify each functionality:
62Generate the puzzle:
63    $ python3 mkpuzzles.py puzzle > puzzle.json
64Verify that the puzzle.json output matches your expectations
65Retrieve an attachment:
66    $ python3 mkpuzzles.py file salad.jpg > salad-output.jph
67Ensure attachments are correctly retrieved
68Check an answer:
69    $ python3 mkpuzzles.py answer "apple pear peach tangerine"
70Confirm that the answer validation works as intended
71
72Package your puzzle:
73When submitting your puzzle, include all required files, including the mkpuzzles generator and any attachments.
74
75