A guide to the autoumpire

This guide was compiled by Michael Cripps (aka Scotsman aka mac57).

The Assassins' Guild AutoUmpire program was written by Ed Nokes. It consists of a web-front end to multiple cgi scripts. For the most part, the game can be run entirely from the web - however, in the course of the game there are almost certainly going to be problems, and a knowledge of the command-line programs and their options will be extremely useful. Also, the majority of people who know how to run the programs are leaving Cambridge in the next couple of years, so a guide seems a good plan. There are also ideas afoot to recode the AutoUmpire in Java/Perl/PHP or any other language - it depends on who you ask. There are so many vagaries that a rewrite may be useful, the problem is simply finding time to do it in.

Files

/societies/assassins/AutoUmpBin/YYYY-?/flock
/societies/assassins/AutoUmpBin/YYYY-?/genmail
/societies/assassins/AutoUmpBin/YYYY-?/genstats
/societies/assassins/AutoUmpBin/YYYY-?/mknews
/societies/assassins/AutoUmpBin/YYYY-?/prep
/societies/assassins/AutoUmpBin/YYYY-?/scoring
/societies/assassins/AutoUmpBin/YYYY-?/verify
/societies/assassins/AutoUmpBin/YYYY-?/wootime

/societies/assassins/cgi-bin/YYYY-?/event.cgi
/societies/assassins/cgi-bin/YYYY-?/front.cgi
/societies/assassins/cgi-bin/YYYY-?/pled.cgi
/societies/assassins/cgi-bin/YYYY-?/plinfo.cgi
/societies/assassins/cgi-bin/YYYY-?/stats.cgi

/societies/assassins/AutoUmpData/YYYY-?/eventsheader
/societies/assassins/AutoUmpData/YYYY-?/uinfoheader

Generating Targetting

Once the player list has been compiled into a Tab-Separated file, take a copy of it. This is important. Now run the following Script:

#!/bin/bash
prep <file>
cat uinfoheader testuinfo > uinfo.txt
cat eventsheader testevents > events.txt
scoring +e000000
verify

Retargetting

To send out targetting emails and to update the system, execute the following script:

#!/bin/bash
/societies/assassins/AutoUmpBin/YYYY-?/scoring +e
/societies/assassins/AutoUmpBin/YYYY-?/genmail ?tn '!s' '!d' '!p' >foo
/usr/sbin/sendmail -bS <foo
/societies/assassins/AutoUmpBin/YYYY-?/scoring +u

Ensuring you are in the directory containing the file email.txt [example], which should be ready to send out. If you are paranoid (and you ought to be) you can ignore the sendmail line and check the file by hand, to ensure no mistakes have been made. Then simply type in "/usr/sbin/sendmail -bS < foo" to send the emails. You can incorporate various types of directives into the file which will be executed by genmail. Directives:

{from} - from email address.
{date} - today's date.
{n} - User name.
{e} - User e-mail address.
{a} - User address.
{c} - User college.
{m} - User details.
{p} - User current pseudonym.
{b} - User's incompetence deadline
{?t_} - If the user has foo targets...

{#_} - How many?
{<_} - Do this block #_ times.

{n_0} - Name of foo target.
{c_0} - College of foo target.
{a_0} - Address of foo target.
{m_0} - Comments on foo target.

{>_} - End of loop block.

{!t_} - If the user doesn't have foo targets...
{/t_} - EndIf

Fill in the _s with directives from the section for genmail - for example, replacing with 'n' gives new targets, with 's' gives same targets [ones carried over], with 'x' gives dead targets and so on.

Programs

flock

"Build an executable which can be run to grab a lock on the datafiles, for safe manual updates to the system. Lock is held until a keypress is received; often handy to send to background with ctrl-Z whilst working on datafiles."

Command-line options

None

genmail

"Generates textual output suitable for, eg. the targetting or password emails, from current game status. Can also generate lists of player information according to selection criteria."

Command-line options

[+|^|-|!|?|/][dpswicmle][t[atonsx]] scanned left-to-right.
For example: genmail ?tn '!s' '!d' '!p' > foo
Selects all players that have new targets that aren't special, aren't dead and aren't police. It defaults to using "email.txt" I believe. The 's are required otherwise things break.
sendmail -bS <foo
'!' inverts choice
Flag: 'd' = Players that are dead
Flag: 'p' = Players that are police
Flag: 's' = Players that are 'special'
Flag: 'w' = Players that are wanted
Flag: 'i' = Players that are incompetent
Flag: 'c' = Players that are inactive [may be a difference...]
Flag: 'm' = Players that are to be mailed
Flag: 'l' = Players that are listed
Flag: 'e' = Players that can be mailed
Flag: 't' = specify type of targets:

Flag: 'a' = Current assassins
Flag: 't' = Current targets
Flag: 'o' = Last-known targets
Flag: 'n' = New targets since last-known
Flag: 's' = Same targets as last known
Flag: 'x' = Ex-targets from last-known

Note that running "scoring +u" will update last-known.

genstats

"Generate TSV statistics tables from game data."

Command-line options

[+|^|-]<name>[=<value>] scanned left-to-right.
Flags: '+' to set, '^' to toggle, '-' to clear.
Only first char of <name> used to do matching.
Flag: <name> = 'a' to not omit annulled events.
Flag: <name> = 'd' to print debugging text.
Flag: <name> = 'n' to include np atts/kills
Use <name> = 'k' to print list of kills to file pathname <value> or stdout if <value> is empty.
Similarly, <name> = 'f' for list of attempts,
'bx' for bjoernstats mode (all 'x' every hour),
's' for scoring debugger (explains scoring),
'cx' for changelogs (all 'x' after changes).
Where <x> = 's' | 'k' | 'f' | 'd' | 'v' | 'i' | 'l' | 'n' for scores, kills, attempts, deaths, survivals, illegal np kills, legal np kills, np attempts.

mknews

Generates news pages, police, inco and wanted lists, as well as Headlines and Updates.

Command-line options

None

prep

"Prepare player target/assassin topology & files according to seeding system."

CAUTION! - There is a bug in this code that manifests rarely (seen once in three years) and results in invalid target assignments (inconsistent between assassin and target) --- be sure to run the verify program on the generated data to check for this ocurring.

Command-line options

<file> - the list of players to perform preparation on, in Tab-separated format. Column headings are: [Name] [E-mail] [College] [Address] [Pseudonym] [Water Weapon Status].

scoring

Set the game state to a given time. Default is current time.

Command-line options

[+|^|-]<name>[=<value>] scanned left-to-right.
'+' to set, '^' to toggle, '-' to clear.
Only first char of name used to do matching.
Flag: <name> = 'e' to evolve game state. +e evolves to current time, +e= evolves to start of game, +e=<time> evolve game state to time.
Flag: <name> = 'u' to inform the system that all players have been told about their new targets, so that no new emails will be produced. Use this command with care! You can seriously damage the game state.
Flag: <name> = 'a' - "all" mode. Do everything? Probably don't need to use this command!
Flag: <name> = 'x' - StrictTargets mode. Unknown option - probably don't need to use.
Flag: <name> = 'r' - mode reset. Clears some fields. Warning! This sounds dangerous! I don't know what it does...
Flag: <name> = 's' - print scores to stdout, I think. Maybe a filename can be given.
Flag: <name> = 'o' - print output. " It allows you to write the updated unifo data into a different file."
Flag: <name> = 'p' - print list of player IDs
Flag: <name> = 't' - print targetting list
Flag: <name> = 'y' - print out pseudonyms
Flag: <name> = 'b' - do bodge. "+b was a quick thingy to work out inactivity deadlines for a normal game where they were accidently entered wrongly by default. It just produces output suitable for a search and replace of the wrong date, followed by paste into events.txt"
Flag: <name> = 'c' - print crontab.
Flag: <name> = 'f' - flag change parameters. Can probably ignore this

verify

"Check consistency of the snapshot in uinfo.txt and in particular, the targetting given there."

Command-line options

None

wootime

Produces output for the current time, including "yearday" - useful for setting in a config file somewhere.

Command-line options

None

CGI Programs

event.cgi

"Build a CGI executable to deal with addition/editing/viewing of all events and reports, in particular assassinations/attempts. Note that for other types of event, the initial event submission form is generated by a different executable, but is actually acted upon by this one (possibly after some pre-processing)."

front.cgi

Frontend for using the system.

pled.cgi

"Builds a CGI executable to handle editing of user/player information and special events."

plinfo.cgi

Return information on a player, including all details, information about kills, attempts and so on.

stats.cgi

Long list of players, sortable by all sorts of details. Useful for working out which player has most kills, for example.