Flesh out overview documentation

This commit is contained in:
Neale Pickett 2016-07-15 17:00:15 -06:00
parent 1727383fec
commit c6b287f7b6
1 changed files with 91 additions and 5 deletions

View File

@ -1,5 +1,89 @@
How Everything Works Overview of MOTH
==================== ================
Monarch Of The Hill (MOTH) is a framework for running puzzle-based events for teams.
Each team is assigned a token which they use to identify themselves.
Teams are presented with a number of *categories*,
each containing a sequence of *puzzles* of increasing point value.
When the event starts, only the lowest-point puzzle in each category is available.
As soon as any team enters the correct solution to the puzzle,
the next puzzle is opened up for all teams.
A scoreboard tracks team rankings,
indicating score within each category,
and overall ranking.
How Scores are Calculated
-------------------------
The per-category score for team `t` is computed as:
* Let `m` be the sum of all points in currently-visible puzzles in this category
* Let `s` be the sum of all points team `t` has won in this category
* Team `t`'s score is `s`/`m`
Therefore, the maximum number of points a team can have in a category is 1.0.
Put another way, a team's per-category score is the percentage of points they've made so far in that category.
The total score for team `t` is the sum of all per-category points.
Therefore, the maximum number of points a team can have in a 7-category event is 7.0.
This point system has proven both easy to explain (if not immediately obvious),
and acceptable by participants.
Because we don't award extra points for quick responses,
teams always feel like they have the possibility to catch up if they are skilled enough.
Requirements
-------------
MOTH was written to run on a wide range of Linux systems.
We are very careful not to require exotic extensions:
you can run MOTH equally well on OpenWRT and Ubuntu Server.
It might even run on BSD: if you've tried this, please email us!
Its architecture also limits permissions,
to make it easier to lock things down very tight.
Since it writes to the filesystem slowly and atomically,
it can be run from a USB flash drive formatted with VFAT.
On the server, it requires:
* Bourne shell (POSIX 1003.2: BASH is okay but not required)
* Awk (POSIX 1003.2: gawk is okay but not required)
* Lua 5.1
On the client, it requires:
* A modern web browser with JavaScript
* Categories might add other requirements (like domain-specific tools to solve the puzzles)
Filesystem Layout
=================
The system is set up to make it simple to run one or more contests on a single machine.
I like to use `/srv/moth` as the base directory for all instances.
So if I were running an instance called "hack",
the instance directory would be `/srv/moth/hack`.
There are five entries in each instance directory, described in detail below:
/srv/moth/hack # (r-x) Instance directory
/srv/moth/hack/assigned.txt # (r--) List of assigned team tokens
/srv/moth/hack/bin/ # (r-x) Per-instance binaries
/srv/moth/hack/categories/ # (r-x) Installed categories
/srv/moth/hack/state/ # (rwx) Contest state
/srv/moth/hack/www/ # (r-x) Web server documentroot
`assigned.txt` `assigned.txt`
---------------- ----------------
@ -12,7 +96,7 @@ and tell kids to use any number they want: it makes it quicker to start.
For more advanced events, For more advanced events,
this doesn't work as well because people start guessing other teams' numbers to confuse each other. this doesn't work as well because people start guessing other teams' numbers to confuse each other.
So I use hex representations of random 32-bit ints. So I use hex representations of random 32-bit ints.
But you could use anything you want in here (with some restrictions, detailed in the registration CGI). But you could use anything you want in here (for specifics on allowed characters, read the registration CGI).
The registration CGI checks this list to see if a token has already assigned to a team name. The registration CGI checks this list to see if a token has already assigned to a team name.
Teams enter points by token, Teams enter points by token,
@ -21,10 +105,11 @@ Since we don't read their team name anywhere else than the registration and scor
it allows some assumptions about what kind of strings tokens can be, it allows some assumptions about what kind of strings tokens can be,
resulting in simpler code. resulting in simpler code.
`packages/`
`categories/`
-------------- --------------
`packages/` contains read-only package archives. `categories/` contains read-only category packages.
Within each subdirectory there is: Within each subdirectory there is:
* `map.txt` mapping point values to directory names * `map.txt` mapping point values to directory names
@ -33,6 +118,7 @@ Within each subdirectory there is:
* `summary.txt` a compliation of `00summary.txt` files for puzzles, to give you a quick reference point when someone says "I need help on js 40". * `summary.txt` a compliation of `00summary.txt` files for puzzles, to give you a quick reference point when someone says "I need help on js 40".
* `puzzles` is all the HTML that needs to be served up for the category * `puzzles` is all the HTML that needs to be served up for the category
`bin/` `bin/`
------ ------