moth

overview.md

  1Overview of MOTH
  2================
  3
  4Monarch Of The Hill (MOTH) is a framework for running puzzle-based events for teams.
  5Each team is assigned a token which they use to identify themselves.
  6
  7Teams are presented with a number of *categories*,
  8each containing a sequence of *puzzles* of increasing point value.
  9
 10When the event starts, only the lowest-point puzzle in each category is available.
 11As soon as any team enters the correct solution to the puzzle,
 12the next puzzle is opened up for all teams.
 13
 14A scoreboard tracks team rankings,
 15indicating score within each category,
 16and overall ranking.
 17
 18
 19State Directory
 20===============
 21
 22The state directory is written to by the server to preserve state.
 23At no point is anything only in memory:
 24if it's not on the filesystem,
 25mothd doesn't think it exists.
 26
 27The state directory is also used to communicate actions to mothd.
 28
 29
 30`initialized`
 31-------------
 32
 33Remove this file to reset the state. This will blow away team assignments and the points log.
 34
 35
 36`hours.txt`
 37-------
 38
 39A list of start and stop hours.
 40If all the hours are in the future, the event defaults to running.
 41"Stop" here just pertains to scoreboard updates and puzzle unlocking.
 42People can still submit answers and their awards are queued up for the next start.
 43
 44
 45`teamids.txt`
 46-------------
 47
 48A list of valid Team IDs, one per line.
 49It defaults to all 4-digit natural numbers,
 50but you can put whatever you want in here.
 51
 52
 53`points.log`
 54------------
 55
 56The log of awarded points:
 57
 58    EpochTime TeamId Category Points
 59
 60Do not write to this file, unless you have disabled the contest. You will lose points!
 61
 62
 63`points.tmp`
 64------------
 65
 66Drop points logs here.
 67Filenames can be anything.
 68
 69When the file is complete and written out,
 70move it into `points.new`,
 71where a non-disabled event's maintenance loop will eventually move it into the main log.
 72
 73`points.new`
 74------------
 75
 76Complete points logs should be atomically moved here.
 77This is to avoid needing locks.
 78[Read about Maildir](https://en.wikipedia.org/wiki/Maildir)
 79if you care about the technical reasons we do things this way.
 80
 81
 82Mothball Directory
 83==================
 84
 85Put a mothball in this directory to open that category.
 86Remove a mothball to disable that category.
 87
 88Overwriting a mothball with a newer version will be noticed by the server within one maintenance interval
 89(20 seconds by default).
 90Be sure to use the same compilation seed in the development server if you compile a new version!
 91
 92Removing a category does not remove points that have been scored in the category.
 93
 94
 95Resources Directory
 96===================
 97
 98
 99Making it look better
100-------------------
101
102`mothd` provides some built-in HTML for rendering a complete contest,
103but it's rather bland.
104You can override everything by dropping a new file into the `resources` directory:
105
106* `basic.css` is used by the default HTML to pretty things up
107* `index.html` is the landing page, which asks to register a team
108* `puzzle.html` renders a puzzle from JSON
109* `puzzle-list.html` renders the list of active puzzles from JSON
110* `scoreboard.html` renders the current scoreboard from JSON
111* Any other file in the `resources` directory will be served up, too.
112
113If you don't want to read through the source code, I don't blame you.
114Run a `mothd` server and pull the various static resources into your `resources` directory,
115and then you can start hacking away at them.
116
117
118Making it look totally different
119---------------------
120
121Every handler can serve its answers up in JSON format,
122just add `application/json` to the `Accept` header of your request.
123
124This means you could completely ignore the file structure in the previous section,
125and write something like a web app that only loads static resources at startup.
126
127
128Changing scoring
129--------------
130
131Scoring is determined client-side in the scoreboard,
132from the points log.
133You can hack in whatever algorithm you like,
134and provide your own scoreboard(s).
135
136If you do hack in a new algorithm,
137please be a dear and email it to us.
138We'd love to see it!
139
140
141
142How Scores are Calculated by Default
143------------------------------------
144
145The per-category score for team `t` is computed as:
146
147* Let `m` be the sum of all points in currently-visible puzzles in this category
148* Let `s` be the sum of all points team `t` has won in this category
149* Team `t`'s score is `s`/`m`
150
151Therefore, the maximum number of points a team can have in a category is 1.0.
152Put another way, a team's per-category score is the percentage of points they've made so far in that category.
153
154The total score for team `t` is the sum of all per-category points.
155
156Therefore, the maximum number of points a team can have in a 7-category event is 7.0.
157
158This point system has proven both easy to explain (if not immediately obvious),
159and acceptable by participants.
160Because we don't award extra points for quick responses,
161teams always feel like they have the possibility to catch up if they are skilled enough.
162
163