mirror of https://github.com/dirtbags/moth.git
Flesh out overview documentation
This commit is contained in:
Neale Pickett
parent
06cf79d2ef
commit
21babe3947
|
|
@ -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`
|
||||
----------------
|
||||
|
|
@ -12,7 +96,7 @@ and tell kids to use any number they want: it makes it quicker to start.
|
|||
For more advanced events,
|
||||
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.
|
||||
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.
|
||||
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,
|
||||
resulting in simpler code.
|
||||
|
||||
`packages/`
|
||||
|
||||
`categories/`
|
||||
--------------
|
||||
|
||||
`packages/` contains read-only package archives.
|
||||
`categories/` contains read-only category packages.
|
||||
Within each subdirectory there is:
|
||||
|
||||
* `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".
|
||||
* `puzzles` is all the HTML that needs to be served up for the category
|
||||
|
||||
|
||||
`bin/`
|
||||
------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue