diff --git a/README.md b/README.md index 28ea1ee..37c294e 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,28 @@ -Dirtbags King Of The Hill Server +Dirtbags Monarch Of The Hill Server ===================== -This is a set of thingies to run our KOTH-style contest. -Contests we've run in the past have been called -"Tracer FIRE" and "Project 2". +This is a set of thingies to run our Monarch-Of-The-Hill contest, +which in the past has been called +"Tracer FIRE", +"Project 2", +"HACK", +"Queen Of The Hill", +and "Cyber FIRE". -It serves up puzzles in a manner similar to Jeopardy. +Information about these events is at +http://dirtbags.net/contest/ + +This software serves up puzzles in a manner similar to Jeopardy. It also track scores, and comes with a JavaScript-based scoreboard to display team rankings. -How Everything Works ----------------------------- - -### `assigned.txt` - -This is just a list of tokens that have been assigned. -One token per line, and tokens can be anything you want. - -For my middle school events, I make tokens all possible 4-digit numbers, -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). - -The registration CGI checks this list to see if a token has already assigned to a team name. -Teams enter points by token, -which lets them use any text they want for a team name. -Since we don't read their team name anywhere else than the registration and scoreboard generator, -it allows some assumptions about what kind of strings tokens can be, -resulting in simpler code. - -### `packages/` - -`packages/` contains read-only package archives. -Within each subdirectory there is: - -* `map.txt` mapping point values to directory names -* `answers.txt` a list of answers for each point value -* `salt` used to generate directory names (so people can't guess them to skip ahead) -* `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/` - -Contains all the binaries you'll need to run an event. -These are probably just copies from the `base` package (where this README lives). -They're copied over in case you need to hack on them during an event. - -`bin/once` is of particular interest: -it gets run periodically to do everything, including: - -* Gather points from `points.new` and append them to the points log. -* Generate a new `puzzles.html` listing all open puzzles. -* Generate a new `points.json` for the scoreboard - -#### Pausing `once` - -You can pause everything `bin/once` does by touching a file in the root directory -called `disabled`. -This doesn't stop the game: -it just stops points collection and generation of the files listed above. - -This is extremely helpful when, inevitably, -you need to hack the points log, -or do other maintenance tasks. -Most times you don't even need to announce that you're doing anything: -people can keep playing the game and their points keep collecting, -ready to be appended to the log when you're done and you re-enable `once`. - - -### `www/` - -HTML root for an event. -It is possible to make this read-only, -after you've set up your packages. -You will need to symlink a few things into the `state` directory, though. - - -### `state/` - -Where all game state is stored. -This is the only part of the contest directory setup that needs to be writable, -and tarring it up preserves exactly the entire contest. - -Notable, it contains the mapping from team hash to name, -and the points log. - -`points.log` is replayed by the scoreboard generator to calculate the current score for each team. - -New points are written to `points.new`, and picked up by `bin/once` to append to `points.log`. -When `once` is disabled (by touching a file called `disabled` at the top level for a game), -the various points-awarding things can keep writing files into `points.new`, -with no need for locking or "bringing down the game for maintenance". +How everything works +--------------------------- +This section wound up being pretty long. +Please check out [the overview](doc/overview.md) +for details. How to set it up diff --git a/doc/overview.md b/doc/overview.md new file mode 100644 index 0000000..d96ec9e --- /dev/null +++ b/doc/overview.md @@ -0,0 +1,89 @@ +How Everything Works +==================== + +`assigned.txt` +---------------- + +This is just a list of tokens that have been assigned. +One token per line, and tokens can be anything you want. + +For my middle school events, I make tokens all possible 4-digit numbers, +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). + +The registration CGI checks this list to see if a token has already assigned to a team name. +Teams enter points by token, +which lets them use any text they want for a team name. +Since we don't read their team name anywhere else than the registration and scoreboard generator, +it allows some assumptions about what kind of strings tokens can be, +resulting in simpler code. + +`packages/` +-------------- + +`packages/` contains read-only package archives. +Within each subdirectory there is: + +* `map.txt` mapping point values to directory names +* `answers.txt` a list of answers for each point value +* `salt` used to generate directory names (so people can't guess them to skip ahead) +* `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/` +------ + +Contains all the binaries you'll need to run an event. +These are probably just copies from the `base` package (where this README lives). +They're copied over in case you need to hack on them during an event. + +`bin/once` is of particular interest: +it gets run periodically to do everything, including: + +* Gather points from `points.new` and append them to the points log. +* Generate a new `puzzles.html` listing all open puzzles. +* Generate a new `points.json` for the scoreboard + +### Pausing `once` + +You can pause everything `bin/once` does by touching a file in the root directory +called `disabled`. +This doesn't stop the game: +it just stops points collection and generation of the files listed above. + +This is extremely helpful when, inevitably, +you need to hack the points log, +or do other maintenance tasks. +Most times you don't even need to announce that you're doing anything: +people can keep playing the game and their points keep collecting, +ready to be appended to the log when you're done and you re-enable `once`. + + +`www/` +----------- + +HTML root for an event. +It is possible to make this read-only, +after you've set up your packages. +You will need to symlink a few things into the `state` directory, though. + + +`state/` +--------- + +Where all game state is stored. +This is the only part of the contest directory setup that needs to be writable, +and tarring it up preserves exactly the entire contest. + +Notable, it contains the mapping from team hash to name, +and the points log. + +`points.log` is replayed by the scoreboard generator to calculate the current score for each team. + +New points are written to `points.new`, and picked up by `bin/once` to append to `points.log`. +When `once` is disabled (by touching a file called `disabled` at the top level for a game), +the various points-awarding things can keep writing files into `points.new`, +with no need for locking or "bringing down the game for maintenance".