Configuring tsh

How to set up tsh for your particular tournament.

Updated 2018-04-10T11:00:00+05 for tsh 3.340.

After you’ve installed tsh, you need to set up a subfolder (directory) of your tsh folder containing a configuration file (“config.tsh”, formerly known as “tsh.config”) describing your tournament, and one (“.t”) data file for each division. You can run as many tournaments as you like with one installation of tsh, but each one should have its own folder.

About The “config.tsh” file

You need to have a text file called “config.tsh” in your tournament folder/directory. You can ask me (John Chew, poslfit@gmail.com) to create one for you if you give me a few weeks’ notice. There are also a few sample tournaments that come with the tsh distribution, and you can try modifying one of their configuration files to make your own.

Your configuration file consists of a sequence of lines. The order of the lines sometimes matters: you may run into trouble if you try to specify the properties of a division before you declare its existence. The first word on a line determines its type, of which there are currently eight:

Note that the lines that appear in a configuration file are not regular tsh commands. Here is a very short sample “config.tsh” file.

# This is a comment because it starts with a '#'.
# The next line that you will store the data for Division a in file a.t.
division a a.t
# The next line says that the division has 3 prize classes
classes a 3
# The next line says that you want to keep track of 1sts/2nds (starts/replies)
config track_firsts = 1
# The next line says that Division A will play a simple round robin
autopair a 0 1 rr a
# The next line says that 1st place in Division A wins $25,000.
prize rank 1 A $25000
# The next line demonstrates the 'perl' command
perl print "Hello, world\n";

The following subsections discuss each type of line in detail.

Comments

Comments begin with a ‘#’.

You may add as many comments as you like to your configuration file, and it’s a good idea to be verbose so that the next person who runs your tournament for you will know what you were thinking.

Division Declarations

Your configuration file must contain at least one division declaration, beginning with the word ‘division’, then followed by a space, a case-insensitive division name, another space, and a filename. Division declarations must come before any other reference to a division in a configuration line. Filenames may or may not be case-sensitive depending on your operating system. You may have as many divisions as you like, but each one has to have its own division name and file name. All divisions should play the same number of rounds at roughly the same schedule; if not, you should set up separate directories and configuration files for differently scheduled divisions, and run separate copies of tsh.

In a multi-division event, you should keep the division name short, as it will appear beside player numbers and you will need to type it to specify divisions. If you want a longer version of the name for display purposes, use the “config division_label” configuration option.

If you have only one division in your tournament, it does not matter what you name it, and you won’t ever have to type its name. Except: if you give your only division a name that could also be a player number, some commands may get confused if you don't type the division name, so use alphabetical division names where possible. If you have more than one division, you should keep your division names short as you will be typing them frequently.

Class Declarations

Your configuration file may contain one or more class declarations, beginning with the word ‘classes’, then followed by a space, a case-insensitive division name, another space, and an integer greater than 1. Classes are typically used to award prizes to deserving lower-ranked players in a division.

If you specify how many classes a division has, then players will be assigned to equal-sized classes according to their pretournament ranking. Classes are named ‘A’, ‘B’, ‘C’... and are listed in the ratings and standings reports. This assignment takes place each time you run tsh: if you change player ratings, it may change player classes.

You can instead manually assign players to classes in the “.t” file using the “class” extension field, which you might want to do if labelling players in a particular group for use with the gibson_class configuration option to restrict opponents of Gibsonized players to members of one class.

Configuration Options

There are a large number of configuration options that you can set using lines beginning with the “config” keyword. All configuration options are at least theoretically optional, because they either have reasonable default values (which may depend on your configuration realm, or not required by all commands (a notable counterexample is the “max_rounds” option, which tells tsh how many rounds long your tournament is, and which is therefore required for the proper functioning of several pairing commands.

Here are all currently available configuration options:

OptionExampleDescription
account_for_h2h_sraccount_for_h2h_sr = 1If set and firsts are being assigned, players' head-to-head record of firsts and seconds will be considered after their overall record and before the length of any runs of firsts or seconds.
addscore_promptaddscore_prompt = 'games'Addscore” will prompt with number of games remaining (rather than scores).
allow_gapsallow_gaps = 1tsh usually assumes that each player plays their games in chronological order, round by round. If this is not the case, you can specify this option, but be warned that this will cause most pairing and report commands to fail.
alpha_pair_first_page_breakalpha_pair_first_page_break = 14tsh will force a page break after this many rows (defaulting to the value of “config alpha_pair_page_break”) are shown on the first page of two-column alpha pairings.
alpha_pair_page_breakalpha_pair_page_break = 15tsh will force a page break after this many rows (defaulting to 10) are shown in two-column alpha pairings. If you choose a value that is too small, then some rows may be split across pages and hard to read.
alpha_pair_single_columnalpha_pair_single_column = 1If set, will always show alphabetic pairings in a single column, even when there are a large number of them.
assign_firstsassign_firsts = 1Have tsh randomly determine who goes first when players would otherwise have to draw. Sets the “config track_firsts” option if it is not already set.
autopair Set using the autopair instruction. It’s not a good idea to mess with this directly.
auto_koth_repeatsauto_koth_repeats = 2If set, then KOTH pairings induced by “config force_koth” have the specified number of maximum repeats, rather than an unlimited number.
avoid_sr_runsavoid_sr_runs = 1If set, try to avoid assigning a player too many consecutive starts (1sts) or replies (2nds) when pairing a win group. Does not currently work with round robin pairings, which are carefully arranged to make players balance in the end.
backup_directorybackup_directory = './notold/'Override the default “./old/” as a place to keep journalled “.t” files. Must end with a “/” or other locally appropriate path separator.
board_stabilityboard_stability = 1If set to 1, try to keep one of the two players in each game at the same board in the next round during sessions (if you do not specify “config session_breaks” the entire tournament is treated as a single session). If not set, boards will be reassigned each round to place high-ranked players at low-numbered boards.
bracket_capbracket_cap = 16If specified, bracket_pairings will apply only to that number of top players.
bracket_nonconbracket_order = 'nasc'If set to nasc, players who do not advance in bracket_pairings will be paired by NASC algorithm; if none, they are left unpaired.
bracket_orderbracket_order = 'id'If set to id, bracket_pairings will be seeded by player number; if rating, by pretournament rating.
bracket_prelimsbracket_prelims = 3Specifies a number of rounds of “InitFontes” pairings to precede any bracket pairings.
bracket_repeatsbracket_repeats = 3Specifies the number of times each pairing will repeat within a stage of bracket_pairings.
bye_firstsbye_firsts = 'ignore'If set to “'alternate'”, the default value, use the rule the NSA adopted on 2008-07-24 to assign alternating firsts and seconds to players who have forfeit losses. If set to “'ignore'”, ignore assign firsts and seconds when necessary by comparing firsts, then comparing seconds, and ignoring byes and forfeits.
bye_methodbye_method = 'top_down'If set to “'always_bottom'”, byes will always be assigned to the bottom-ranked player; if “'bottom_up'” (the default), byes will be assigned from the bottom of the field upward; if “'top_down'”, byes will be assigned from the top of the field downward.
bye_spreadbye_spread = 75Sets the number of points of spread awarded to a player who is assigned a bye. You should probably adjust the value of “realm” rather than change this directly; contact John Chew if this is not possible. As a special case, if you set this to zero, byes count neither as wins nor losses.
check_by_winnercheck_by_winner = 1Instructs the “CheckRoundScores” command to sort rows by winning player rather than starting player.
chew_no_swiss_allchew_no_swiss_all = 1Instructs the “ChewPair” command not to pair everyone Swiss when all as yet unpaired players are still contenders.
colourcolour = 'no'Enables use of ANSI colour escape sequences to highlight text in the tsh session.
colour = 'yes'
commentary_directorycommentary_directory = '/Library/WebServer/Documents/myevent/tsh/comm'Designate a target directory for the “COMMentary command.
count_good_wordscount_good_words = 1If specified, the LOOK command will report how many good words were challenged, for penalty calculation purposes.
cross_tables_idcross_tables_id = 12345Identifies the cross-tables.com ID for this tournament.
csv_encodingcsv_encoding = 'utf8'Specifies a file encoding for CSV files manipulated using the “LoadplayersCsV”, “MergeplayersCsV” and “SaveplayersCsV” commands.
currency_symbolcurrency_symbol = '£'Specifies the currency symbol to be used with monetary values. Defaults to the dollar sign.
custom_stylesheetcustom_stylesheet = 'local.css'Specifies a custom stylesheet to be loaded after the default CSS stylesheet.
de_alternatede_alternate = 3Used to designate the alternate player for “double elimination pairings&rquo;.
director_emaildirector_email = "poslfit@gmail.com"Used to identify the tournament director.
director_iddirector_id = "CM000003"Used to identify a NASPA tournament director when submitting ratings data.
director_namedirector_name = "John Chew"Used to identify the tournament director.
director_passworddirector_password = "friend"(Deprecated) Specifies director’s password for use with “SUBMIT” command.
division_labeldivision_label{'A'} = 'Expert'Override a division’s default name given in its division declaration.
division_rating_listdivision_rating_list{'C'} = 'naspa-csw'Overrides “rating_list” on a per-division basis.
division_rating_systemdivision_rating_system{'C'} = 'none'Overrides “rating_system” on a per-division basis.
entryentry = "spread"Used to specify data entry mode. Default value is “'scores'”, where you enter scores; other common permitted values are “'spread'” (enter only the difference between scores) and “'both'” (enter both scores and spread). Less common values are “'board'”, “'sudoku'”, and “'tagged'”.
entry_pairingentry_pairing = 1If specified, changes the behaviour of the “Addscore” command so that when presented with scores for unpaired players, it assumes that they played each other. Use with caution, as it prevents TSH from doing an important part of its normal data entry validation.
entry_tagsentry_tags = {'c'=>'csw', 'csw'=>'csw', 't'=>'twl', 'twl'=>'twl'}Specifies accepted tags and synonyms for tagged data entry with the “Addscore” command.
esb_geometryesb_geometry{'A'} = [[5,6,0],[5,4,30]]Specifies a series of default geometry values for a given division’s enhanced scoreboard. Each triple specifies one scoreboard; within each triple the first number is the number of columns, the second the number of rows, the third the offset from top rank.
esb_liteesb_lite = 1If specified, suppresses certain elements in the ESB to save on pixels.
event_dateevent_date = "September 30, 2005"Used to specify the event date, particularly when submitting ratings data.
event_nameevent_name = "Toronto 2005"Used to identify the event, particularly when submitting ratings data.
exagonyexagony = 1If used, prevents players from the same team from facing each other. See also the list of commands compatible with this option and the “team” extension field.
exagony = [1,2,3]If used, prevents players from the same team from facing each other in specified rounds. See also the list of commands compatible with this option and the “team” extension field.
external_pathexternal_path = ['./bin','../bin']Used to specify where external commands can be found. Default value is ['./bin'].
fat_tweetsfat_tweets = 1If enabled, the “TWEET” command sends more detailed social media reports not restricted to 140 characters. Use this if posting say to Facebook rather than to Twitter.
final_drawfinal_draw = 1If used, players will be instructed to draw to see who starts (plays first) in the final round if their start/reply records are equal, even if firsts and seconds are otherwise being assigned.
flight_capflight_cap = 'TSH::PairingCommand::FlightCapNSC'Lets you override the default algorithm for capping the number of players who can be considered in contention when using the Chew pairing algorithm. Talk to John Chew if you need to adjust this. The example given is suitable for a tournament which is used to select two finalists. This parameter is also used in estimating pairings flights when choosing an opponent for a Gibsonized player.
flight_cap = [12,12,8,4]Lets you override the default algorithm for capping the number of players who can be considered in contention when using the Chew pairing algorithm. Talk to John Chew if you need to adjust this. The example given is suitable for a tournament which is used to select two finalists. This parameter is also used in estimating pairings flights when choosing an opponent for a Gibsonized player.
force_kothforce_koth = 1When using default pairings (not autopair), makes the last round be KOTH with unlimited repeats (unless overridden by “config auto_koth_repeats”), rather than Chew pairings. If a number of rounds greater than 1 is specified, then that number of round of KOTH pairings are used.
ftp_hostftp_host = 'www.poslfit.com'Required when using the “mirror-ftp” utility command, and specifies the FTP server to which events should be uploaded.
ftp_passwordftp_username = 'jamie'Formerly required when using the “mirror-ftp” utility command, specifies the password with which to log onto the FTP server; now deprecated in favour of entering this information from the command line.
ftp_pathftp_path = 'www/myevents'Required when using the “mirror-ftp” utility command, and specifies the path on the FTP server to which events should be uploaded. An event subdirectory will be created within the designated directory.
ftp_usernameftp_username = 'john'Formerly required when using the “mirror-ftp” utility command, specifies the username with which to log onto the FTP server; now deprecated in favour of entering this information from the command line.
gibsongibson = 1Enable automatic detection of Gibson situations. When using default or Chew pairings, tsh always looks for possible Gibson situations. When using automatic pairings, tsh does or does not check depending on the value of this option.
gibsongibson = 'strict'Behaves as per “config gibson = 1” and in addition pairs Gibson with the highest-ranked player out of contention, regardless of repeats.
gibson_classgibson_class = 'A'Requires that opponents of Gibsonized players must belong to the named class. Use this option at events where some players may be competing for a special prize, such as qualification to another event, and should not be paired with Gibsonized players.
gibson_groupsgibson_groups{'A'} = [[1,2]]Indicates final ranks that are to be considered equivalent when testing for Gibsonization. Works only with Chew pairings. If not specified, each final rank is considered to be of different value to a player. The example given should be used where the current event is a preliminary to qualify players for a two-player final match and it doesn’t matter whether a player finishes first or second. In the unlikely event that you wanted to have players ranked 3 through 6 compete in a separate final match, you could specify the value “[[1,2],[3,4,5,6]]”.
gibson_spreadgibson_spread = [250,175,150]Overrides the default spread thresholds for Gibsonization. The nth value from the end gives the maximum spread by which a player may win a game in the nth last round; for earlier rounds, the maximum spread is given by the first value.
gui_portgui_port = 1234Overrides the default port (7779) for the “FIX” command.
hook_addscore_flushhook_addscore_flush = 'sb a;sb b;sb c;sb d'Gives one or more semicolon-separated commands to be executed whenever the “Addscore” command updates score data.
hook_addscore_flush = 'json a;json b;json c;json d'
hook_autopairhook_autopair = 'sb a;sb b;sb c;sb d'Gives one or more semicolon-separated commands to be executed whenever pairings are automatically computed.
hook_autopair = 'json a;json b;json c;json d'
hook_division_completehook_division_complete{'A'} = 'tweet a 1 2'Gives one or more semicolon-separated commands to be executed whenever the last scores have been entered for a division in a round. In the command text, the strings ‘$d’ and ‘$r’ are replaced respectively by the division and round number that have just completed.
hook_division_updatehook_division_update = 'tweet a 1 2'Gives one or more semicolon-separated commands to be executed whenever a division data file is updated.
html_directoryhtml_directory = '/Library/WebServer/Documents/myevent/tsh/'Override the default “./html/” as a place to keep round-by-round “.html” reports. Must end with a “/” or other locally appropriate path separator. The example given places reports on the local machine’s public web server under OS/X.
html_in_event_directoryhtml_in_event_directory = 1Stores an extra copy of printable HTML reports directly in the event directory, where they may be easy to find, but may cause clutter. Note that player photos will not be correctly linked in event directory web pages unless you manually copy the photo directory into the event directory as well.
html_bottomhtml_bottom = '<p align=center><a href="event url"><img src="event logo"></a></p>'If defined, appears at the bottom of each HTML page.
html_index_bottomhtml_index_bottom = '<p align=center><a href="event url"><img src="event logo"></a></p>'If defined, appears at the bottom of the event HTML index, overriding the value of “config html_bottom”, if any.
html_index_recent_firsthtml_index_recent_first = 1If set, the event HTML index lists recent (later) rounds higher on the page, for easier viewing of large indexes on small screens.
html_index_tophtml_index_top = '<p align=center><a href="event url"><img src="event logo"></a></p>'If defined, appears between the body and h1 tags at the top of the event HTML index, overriding the value of “config html_top”, if any.
html_page_break_tophtml_index_top = '<p align=center><a href="event url"><img src="event logo"></a></p>'If defined, appears after a page break and before table headings in HTML reports.
html_suffixhtml_suffix = '.shtml'Overrides the default “.html” suffix (filename extension) appended to generated filenames.
html_tophtml_top = '<p align=center><a href="event url"><img src="event logo"></a></p>'If defined, appears between the body and h1 tags at the top of each HTML page.
index_top_extrasindex_top_extras = { 'Live Coverage' => 'http://wherever.com'If used, specifies additional entries to appear in the top section of the web coverage index.
initial_exagonyinitial_exagony = 1If used, prevents players from the same team from facing each other in first-round random pairings. See also the “team” extension field.
initial_randominitial_random = 1When using Chew pairings either explicitly or as the default pairing algorithm, specifies one initial round of random pairings, as required at the WSC.
initial_scheduleinitial_schedule = 3When using Chew pairings either explicitly or as the default pairing algorithm, it is often useful to start with a semirandomized fixed schedule generated by the InitFontes command. This parameter (which defaults to zero) specifies the number of rounds that that schedule should run.
initial_snakedinitial_snaked = 1If set, the “InitFontes” command assigns players to pairings groups in boustrophedonic order rather than randomly.
interleave_rrinterleave_rr = 1If set, the “RoundRobin” pairing command will add all rounds of a round robin before beginning the next round robin, rather than adding all of a player’s games with a given opponent before moving on to the next opponent.
localelocale = 'no_NO'Specify a standard locale code to be used by internationalization code in the Perl interpreter or the operating system.
localise_nameslocalise_names = 1If set, apply standard player name localisations, such as omitting Thai family names.
manual_pairingsmanual_pairings = 1Use neither auto-pairings even if configured, nor Chew pairings in the absence of auto-pairings. Deprecated in favour of “pairing_system = 'manual'”.
max_div_roundsmax_div_rounds{'A'} = 12Like “config max_rounds” but applies only to one division. If you only specify the maximum number of rounds in some divisions, the largest value you give is assumed for the rest.
max_roundsmax_rounds = 12Specify the last round in the tournament. Used in Gibson detection, and to check for illegal round numbers in commands.
max_scoremax_score = 800Specify the largest score that will be accepted in data entry.
message_encodingmessage_encoding = 'utf8'Specify a character encoding for ‘.t’ files other than the default ‘isolatin1’.
message_filemessage_file = 'lib/messages/deu.txt'Specify an alternate file containing the text messages displayed by tsh. Normally this is determined based on your realm.
mirror_directoriesmirror_directories = [qw(c:\dir\subdir /tmp/copy)]If specified, instructs tsh to keep a copy of all data and report files in the given locations.
minimum_team_sizeminimum_team_size = 3If specified, instructs tsh to ignore teams of fewer than this many players in determining team prizes.
next_round_stylenext_round_style = 'brief'Changes the style of the next-round pairing data shown at the end of ratings reports from the default 'nextrat' to one of: 'normal', 'half', 'balanced', 'brief' or 'nextrat'.
no_aupair_bye_tiesno_aupair_bye_ties = 1Omit byes and forfeits in AUPAIR rating data reports, rather than using standard notation. Not required with modern rating software.
no_boardsno_boards = 1Do not show board numbers anywhere. If set to 0, show board numbers even where they would not normally be shown; e.g., where table numbers have already been shown.
nohistorynohistory = 1Used internally to prevent commands triggered by hooks from affecting the page to be displayed by “BrowseLast”.
no_index_tally_slipsno_index_tally_slips = 1The “ShowPairings” command will generate tally slips as usual, but they will not appear in the web index.
no_initial_rrno_initial_rr = 1Do not start default pairings with a round robin, even if there is room to do so.
no_randomno_random = 1If set, do not use random tie-breaks for players tied in standings, use pre-tournament rating or player number instead.
no_ranked_pairingsno_ranked_pairings = 1Do not show ranked pairings in “ShowPairings”, only alphabetical ones.
no_show_lastno_show_last = 1Do not show information about the last round’s results in “RoundRATings” or “RATings”. Use if you find the information too cluttered or hard to understand.
no_text_filesno_text_files = 1Do not create text versions of reports. Useful if you only want HTML files, and don’t want your directories cluttered with text files.
numeric_pairing_displaynumeric_pairing_display = 1Sort players in numeric order by ID rather than alphabetically in STandings” or “RoundRATings” commands will show pairing bars for a specific round. An integer indicates the number of times players have been paired against each other prior to the round for which pairings are displayed. One or more asterisks indicates the number of times players have been paired back-to-back. This feature should be considered experimental, contact vince@wgvc.com directly with any issues.
pairing_system pairing_system = 'auto' You do not need to explicitly specify the use of automatic pairings; they are selected if you include an “autopair” instruction in your configuration file.
pairing_system = 'basd' BASD pairings pair players in a byzantine format developed by Ira Freehof for his Big Apple Showdown.
pairing_system = 'bracket' Bracket pairings pair players in single-elimination format, optionally restricting to the top “bracket_cap”, seeded initially according to the value of the “bracket_order” configuration option and repeating each pairing a number of times specified by “bracket_repeats” configuration option, preceded optionally by a number of rounds of “InitFontes” pairings specified by the “bracket_prelims” configuration option. Players who do not advance may optionally be paired according to the “bracket_noncon_pairings” configuration option.
pairing_system = 'chew' You do not need to explicitly specify the use of Chew pairings; they are selected by default.
pairing_system = 'green' Green pairings are used by John Green in Florida to pair groups of six to eight players using a fixed five-round schedule followed by a KOTH.
pairing_system = 'guelph' Guelph pairings are used by Andy Saunders in Guelph, ON, CAN to pair six, eight or ten players in a six-round schedule.
pairing_system = 'manual' You should explicitly specify the use of manual pairings if you do not want tsh to provide default pairings.
pairing_system = 'nast' You should use NAST pairings if you are directing a satellite event of the North American Scrabble Tour, which has specific requirements for the pairings of such events. The exact system depends on the number of players in the tournament, and consists of either four rounds of fixed pairings and one round of Swiss pairings or five rounds of fixed pairings, followed by one round of KOTH pairings.
pairing_system = 'none' Although tsh began as a program for generating pairings and reports, it can also be used at events like crossword or Sudoku tournaments, where players compete separately to attain individual scores. No pairings are generated or displayed, but standings reports and web features are available.
pair_page_breakpair_page_break = 15If this option is specified, tsh will force a page break after this many rows are shown in rank-ordered (not alpha) pairings. If this option is not used, player names may be split across page breaks.
pairings_refreshpairings_refresh = 10If specified, HTML pairings reports will refresh themselves in web browsers at intervals of this many seconds.
photo_databasephoto_database = 'nsa'Choose a photo database. Currently available databases are: ‘nsa’, ‘centrestar’, ‘deu’, ‘ken’ and ‘pak’.
player_id_firstplayer_id_first = 1If enabled, display player IDs ahead of names.
player_nicknamesplayer_nicknames = "albany.txt"Inidcates the name of a file in lib containing pipe-delimited mappings of canonical player names to their preferred scoreboard representation, in the format Name, Canonical|Nickname. To use nicknames in HTML and text reports, enable pname_from_sbname.
player_number_formatplayer_number_format = "#%s"Specify sprintf(3) formatting of player numbers. By default, a ‘#’ is prepended to the number for clarity if there is only one division.
player_photo_aspect_ratioplayer_photo_aspect_ratio = 0.75Gives the ratio of player photo widths to heights (all photos must use the same value).
player_photosplayer_photos = 1If specified, display photos of opponents in alpha pairings reports.
pname_from_sbnamepname_from_sbname = 1If this is set to a nonzero value, the pname .t file keyword will inherit its value from sbname and this value will be used in cases where use_pname would be effective. If the use_pname config value is also set and a player's pname is defined then this value will not be overriden by their sbname.
portport = 7777If this is set to a nonzero value, tsh will use its web interface instead of its command-line interface. Still in early development and incomplete but feel free to see what is there so far.
prize_bandsprize_bands{'A'} = [2,3,4,5]Specifies which final ranks are to be considered equivalent for pairings purposes: the numbers given mark the end of each band (range) of equivalent prizes (ranks). Only used in scoreboard displays and in Chew pairings, which try to pair players who are in contention for one prize band with each other. In the example, the top prize band goes from 1st place to 2nd place (presumably because the top two finalists qualify for a playoff); each of 3rd, 4th and 5th place is its own prize band (presumably awarding players cash prizes); and everything from 6th place on is the last prize band (presumably winning nothing). If this option is omitted when required, a warning is displayed and a default value is assigned which assumes prizes are assigned to the top quarter of the division. Note that Gibsonization won’t work with a value of “[1]”, because the “highest ranked player out of contention for prize money” that the Gibsonized player ought to play ends up being the second-ranked player.
prize_bands_from_prizesprize_bands_from_prizes = 1Indicates that the prize_bands for all divisions are to be derived from the rank prizes as specified by the prizes configuration, so that if you intend to set prize bands of the form [1,2,...N] you need only enter the number of prizes once.
prizes Set using the “prizes” instruction. It’s not a good idea to mess with this directly.
quiet_hooksquiet_hooks = 1If enabled, do not display the output of commands being triggered by hooks.
random_rr_orderrandom_rr_order = 1Arrange the rounds of a round robin in random order, rather than presenting the top seed with opponents of increasing strength.
rating_fieldsfields = [qw(rank newr name team)]If you need complete flexibility in configuring which fields are listed in the output of the “RATings” and “RoundRATings” commands, you can list them here. See the description of Standings and Ratings reports for a list of permitted fields.
rating_listrating_list = 'deu'If set to “deu”, the “UPDATERATINGS” command will fetch the German rating list and not the NSA one.
rating_systemrating_system = 'absp'Computes ABSP ratings wherever ratings are needed. This parameter must be set to this or one of the following values when using the “SUBMIT” command.
rating_system = 'aus'Computes Australian ratings wherever ratings are needed.
rating_system = 'elo'Computes Elo ratings without traditional NSA bugs wherever ratings are needed.
rating_system = 'none'Prevents ratings from being calculated or displayed.
rating_system = 'nsa'Computes oldstyle NSA ratings wherever ratings are needed.
rating_system = 'nsa lct'Computes oldstyle NSA ratings for a local club tournament wherever ratings are needed.
rating_system = 'naspa'Computes NASPA ratings wherever ratings are needed. This is the default value but may be implicitly overridden by a “realm”. Synonymous for historical reasons with the value “'nsa2008'”.
rating_system = 'naspa lct'Computes NASPA ratings for a local club tournament wherever ratings are needed. Synonymous for historical reasons with the value “'nsa2008 lct'
rating_system = 'wespa'Computes WESPA ratings wherever ratings are needed.
ratings_noteratings_note = "Please rate this after the early bird."Specifies a note to include when submitting ratings data.
realmrealm = 'nsa'Specifies default values for several parameters, as explained in the section on configuration realms.
reservedreserved{'P'}[13] = 4Permanently assigns player P13 to board 4. Typically used when you have a player with special needs.
rotofilerotofile = 'roto.txt'Specify the name of a rotisserie pool file to be used in producing U.S.-style rotisserie pool reports.
roster_orderroster_order = 'alpha'Specify the order in which players will be listed in the “ROSTERS” command: “'alpha'” (alphabetically), “'rank'” (by rank), “'team'” (by team), “'team-class'” (by team, then class).
round_robin_orderround_robin_order = [4,9,8,7,6,5,10,3,2]Specify the order of player 1’s round robin opponents, or the order in which players are assigned to the schedule by the “TeamRoundRobin” command.
save_intervalsave_interval = 10Specifies how often results should be saved to disk in “Addscore”. Defaults to every ten new entries.
sb_banner_heightsb_banner_height = 128Specify the height of a scoreboard banner.
sb_banner_urlsb_banner_url = "http://event.poslfit.com/2017/kingscup/banner.html"Specify the web address of a scoreboard banner.
scoreboard_teamsscoreboard_teams = 1Show team flags in the enhanced scoreboard.
scorecards_refreshscorecards_refresh = 15Specifies an integer interval in seconds at which scorecard webpages should refresh in the browser.
scoresscores = 'scrabble'If set to “'WL'”, spread is ignored, and only wins and losses count. If set to “'WLT'”, spread is ignored, and only wins, losses and ties count. With the default value of “'scrabble'”, game results are understood to be a pair of integer scores, with win/loss/tie outcome based on their difference. If set to “'sudoku”, game results are understood to be solitaire integer scores.
seatsseats = 1Enables display and tracking of seat numbers, for realms where seats are numbered instead of boards or tables.
session_breakssession_breaks = [3,6,8,11,12]Specifies after which rounds there is enough time in the schedule to wait for all results to come in before computing pairings. Used when the “ChewPair” is automatically invoked.
show_divnameshow_divname = 1Show division names in report headings even when you have only one division. Use this if you have to split a tournament into different tsh events because you have more than one computer for data entry, but you want to be able to tell which reports came from which division.
show_honourable_mentionshow_honourable_mention = 1If specified, the “PRiZes” command will list with honourable mention the additional prizes that a player would have won, were they eligible to earn more than one exclusive prize.
show_inactiveshow_inactive = 1Normally, inactive players are not displayed in reports. Select this option to include them, for example if you had a player leave early who should still be listed in the final standings.
show_last_player_nameshow_last_player_name = 1When displaying ratings reports, show the last player's name if known, and not just player number.
show_roster_classesshow_roster_classes = 1Show classes in player rosters.
show_roster_photosshow_roster_photos = 1Show photos in player rosters, overriding “player_photos”.
show_teamsshow_teams = 1Show team names with player names.
sort_by_first_namesort_by_first_name = 1Sort players by first name (when names are being presented in “given_names surnames” order).
spitfilespitfile{'A'} = 'spita.txt'Specify the name of a rotisserie pool file to be used in producing U.K. rotisserie pool reports for a given division.
split1split1 = 9Specifies after which round a long tournament should be split-rated when using Elo ratings. (This option is no longer needed, and is therefore deprecated.)
spread_capspread_cap = 350Specifies the maximum earnable spread in each round, for use in Thailand.
spread_cap = [350, 250, 100]Specifies different values for maximum earnable spread in each round.
squadssquads = 1If enabled, a team will earn a squad win/loss and spread shwn all of its opponents in a round belong to one opposing team.
standings_hotlinkstandings_hotlink = 1If enabled, player names in standings link to player scorecards.
standings_hotlink_targetstandings_hotlink_target = "-scorecard.html#%d"Specifies an alternate target for the standings_hotlink, if enabled. The player number will be interpolated as per printf. The division name is prepended to the format string.
standings_refreshstandings_refresh = 10If specified, HTML standings and ratings estimate reports will refresh themselves in web browsers at intervals of this many seconds.
standings_spread_capstandings_spread_cap = [100, 150, 250, 250, 250, 250]Specifies the maximum earnable spread in each round, for standings purposes but not pairings purposes, for use at the U.S. NSSC.
standings_with_ratingsstandings_with_ratings = 1If enabled, ratings are displayed even in standings reports.
start_timesstart_times = [qw(19:00 20:00 21:00 09:00 10:00)]Specifies the round start times to be used in the “TWeetPairings” command.
sum_before_spreadsum_before_spread = 1If specified, players should be ranked on W-L, then total points scored, then spread.
suppress_results_in_pairingssuppress_results_in_pairings = 1If set, the ESB Pairing Mode will not display results, to give your players another reason to leave the playing area between games.
surname_lastsurname_last = 1If specified, raw names of the form ‘surnames, given names’ in ‘.t’ files are translated to ‘given names surnames’ whenever displayed.
swiss_orderswiss_order = ['auto','koth','forced']Specifies how players are paired within Swiss-paired win groups in each round. If fewer values are specified than there are rounds, then the last value is repeated as necessary to fill out the event. Acceptable values are “'auto'” (do whatever TSH thinks is appropriate), “'forced'” (always pair the top half in order against the bottom half, disregarding things like firsts and seconds), and “'koth'” (minimize rank distance between opponents).
table_formattable_format = '%3s'sprintf(3) description of how table numbers are formatted.
table_methodtable_method = 'consecutive'If set to “consecutive”, assigns boards to table numbers consecutively across divisions. If left unset, or set to the default value of “none”, does not assign boards to tables automatically.
table_titletable_title = "Room"Specify what tables are called in titles. The default value is “Table”.
tablestables{'A'} = [1,1,2,2,3,3,4,4,5,5]List which board is at which table. Division name must be capitalized. If you don’t give information for enough boards, you’ll get cryptic error messages. You may use Perl expressions like “1..20” or “map { $_, $_ } 1..20” to save typing.
tally_slips_blankstally_slips_blanks = 1If specified, the tally slips generated as a side effect of the “ShowPairings” command will include an area for designating blanks.
tally_slips_challengestally_slips_challenges = 1If specified, the tally slips generated as a side effect of the “ShowPairings” command will include an area for listing challenged words.
tally_slips_no_spreadtally_slips_no_spread = 1If specified, the tally slips generated as a side effect of the “ShowPairings” command will not include a box for spread.
tally_slips_page_breaktally_slips_page_break = 15If this option is specified, tsh will force a page break after this many rows are shown in tally slips. If this option is not used, tally slips may be split across page breaks.
team_quotasteam_quotas = { 'AUS'=> 13, 'AUT'=> 2, 'BHR'=> 2, 'CAN'=> 9 }Specify parameters for WSC-style quotas for team standings
terminologyterminology = 'deu'Select the terminology that tsh uses in its reports and user interface. This feature is only partially implemented, in those areas of tsh where it has been requested. Currently supported terminology values are “absp”, “deu” and “nsa”. Contributions of additional terminology are welcome.
thai_pointsthai_points = 1If set, compute and display Thai points (2 for win, 1 for tie, 0 for loss, plus handicap) where appropriate.
tfile_encodingtfile_encoding = 'utf8'Specify a character encoding for ‘.t’ files other than the default ‘isolatin1’.
top_down_swisstop_down_swiss = 1If set, disable bidirectional optimization of Swiss pairings.
tournament_idtournament_id = 123Identifies the tournament for the purpose of submitting rating data.
track_firststrack_firsts = 1Make tsh care about who played first and second in each game. If this option is set and “assign_firsts” is not set, tsh will use the order in which scores are entered to determine who played first, and complain if the wrong player did. If this option is set and you use Chew pairings, the pairing algorithm will have a weak preference for pairing players due to go first with players due to go second.
twitter_commandtwitter_command = 'ttytter -ssl -silent -status="%s"'Specify the back-end command-line command to be used by the “TWEET” command.
twitter_commandtwitter_command = 'ttytter -ssl -silent -status="%s"'Specify the back-end command-line command to be used by the “TWEET” command.
twitter_dm_commandtwitter_dm_command = 'ttytter -ssl -script -runcommand="/dm %s %s"'Specifies the command to be used to send Twitter direct messages in the “TWeetPairings” command.
twitter_prefixtwitter_prefix = 'Live from DO:'Specify a prefix to be attached to each message sent by the “TWEET” command.
twitter_usernametwitter_username = 'whoever'(Deprecated) Specified the username to be used to authenticate each message sent by the old version of the “TWEET” command.
unfair_byesunfair_byes = 1If specified, byes will always be assigned solely on standing, not taking into account how many byes each player has had. Equivalent to “config bye_method = 'always_bottom'”.
wallchart_refreshwallchart_refresh = 30If specified, HTML wallcharts will refresh themselves in web browsers at intervals of this many seconds.
zero_byes_tiezero_byes_tie = 1Specify that a bye with zero spread is to be treated as a tie, rather than a nonevent.

Configuration Realms

Because tsh is used in many different countries with many different Scrabble traditions (and it’s even sometimes used for non-Scrabble events), tsh has a quick way of specifying common default values for configuration options that vary from country to country: the “realm” configuration option. The following table shows which default values are set according to the value of this option.

RealmDefault Values Specified for Configuration Options
config realm = 'nsa'
(This is the default realm.)
alpha_pair_page_break = 10
rating_list = 'nsa'
rating_system = 'nsa2008'
config realm = 'absp' alpha_pair_page_break = 10000
assign_firsts = 1
avoid_sr_runs = 1
bye_firsts = 'ignore'
bye_spread = 75
currency_symbol = '£'
html_in_event_directory = 1
no_index_tally_slips = 1
photo_database = 'centrestar'
rating_list = 'absp'
rating_system = 'absp'
surname_last = 1
table_method = 'consecutive'
terminology = 'absp'
track_firsts = 1
config realm = 'deu' bye_firsts = 'ignore'
currency_symbol = '€'
locale = 'de_DE'
message_file = 'lib/messages/deu.txt'
photo_database = 'deu'
rating_list = 'deu'
rating_system = 'deu'
terminology = 'deu'
use_windows_code_page = 1
config realm = 'go' assign_firsts = 1
bye_spread = 2
rating_system = 'nsa'
scores = 'WL'
track_firsts = 1
config realm = 'ken' currency_symbol = 'K'
photo_database = 'ken'
config realm = 'naspa' rating_list = 'nsa'
rating_system = 'nsa2008'
config realm = 'naspa-csw' rating_list = 'naspa-csw'
rating_system = 'naspa-csw'
config realm = 'naspa-lct' rating_list = 'nsa'
rating_system = 'nsa2008 lct'
config realm = 'nor' currency_symbol = '€'
locale = 'nb_NO'
message_file = 'lib/messages/nor.txt'
rating_list = 'nor'
rating_system = 'nor'
terminology = 'nor'
use_windows_code_page = 1
config realm = 'pak' bye_firsts = 'ignore'
photo_database = 'pak'
rating_list = 'pak'
rating_system = 'pak'
config realm = 'pol' all_byes_tie = 1
assign_firsts = 1
bye_spread = 300
locale = 'pl_PL'
message_encoding = 'utf8'
message_file = 'lib/messages/pol.txt'
rating_list = 'pol'
rating_system = 'nsa2008'
sum_before_spread = 1
tally_slips_no_spread = 1
terminology = 'pol'
tfile_encoding = 'utf8'
track_firsts = 1
config realm = 'sgp' bye_firsts = 'ignore'
rating_list = 'sgp'
rating_system = 'nsa'
surname_last = 1
config realm = 'sudoku' entry = 'sudoku'
pairing_system = 'none'
rating_list = 'sudoku'
rating_system = 'sudoku'
scores = 'sudoku'
terminology = 'sudoku'
tfile_game = 'sudoku'
config realm = 'thai' bye_spread = 100
console_encoding = 'cp874'
csv_encoding = 'windows-874'
member_separator = '-'
message_encoding = 'windows-874'
rating_list = 'thai'
rating_system = 'thai'
spread_cap = 350
terminology = 'thai'
tfile_encoding = 'windows-874'
config realm = 'wespa' bye_spread = 75
rating_list = 'wespa'
rating_system = 'wespa'

Configuring Pairings

tsh has a number of pairings commands, each of which adds one or more rounds of who-plays-whom information to the player data (“.t”) files. Pairing information must be entered before scoring information: the score entry command will not accept scores for players whose opponents are not yet known to the program. You should be familiar with the contents of the section on pairing theory and have decided on one or more of the pairing systems described in that section for your tournament before reading further.

There are four ways of telling tsh what kind of pairings to use: default, automatic, custom and manual pairings.

Default Pairings

With default pairings the only thing you need to tell tsh is how many rounds your tournament is:

# The following config.tsh line says that this tournament has 12 rounds.
config max_rounds = 12

After you enter the results for each round, ask tsh for the next round’s pairings using the “ShowPairings” command and it will compute Chew pairings. (If the number of rounds is large compared to the number of players, one or more round robins will be scheduled first.) The following configuration options can be set to control how these default pairings work. See the detailed description of configuration options for their syntax.

OptionEffectUtility
auto_koth_repeats If set, any final KOTH pairings induced by “config force_koth” will have the specified number of repeats, rather than an unlimited number. Sometimes used in South Africa for the sake of tradition.
avoid_sr_runs If set, minimise consecutive starts (1sts) or replies (2nds) when pairing a win group. You might use this, if your players are likely to complain about long runs of starts or replies, and you don't mind slowing down the pairings a little.
flight_cap If set, overrides the cap on the size of the top flight. Do not use, unless you are a pairings wizard.
gibson_class If set, restricts opponents of Gibsonized players to one named class. You might use this, some but not all of your players are competing in this tournament to qualify for something else, and should not be penalized in their qualification attempt by having to play a Gibsonized opponent.
gibson_groups Indicates final ranks that are to be considered equivalent when testing for Gibsonization. You should only use this if you are a pairings wizard.
gibson_spread Overrides default spread thresholds for Gibsonization. You should only use this in consultation with your governing rules body.
force_koth If set, the last round will be KOTH even when default pairings are being used. You might want to use this, if your (likely North American players) will rebel at the thought of a tournament that doesn’t end in a KOTH.
initial_snaked If set, and “InitFontes” is invoked to generate first-round pairings, players are assigned to pairings groups in boustrophedonic order rather than randomly. Use this if you mistakenly believe that is a good thing to allow players to engineer their first-round pairings in a high stakes tournament by sacrificing pretournament ratings points, or that ratings are sufficiently accurate for detailed seeding of players.
initial_schedule If set, specifies a number of initial rounds that will be paired in a fixed schedule. It’s not a bad idea to set this if you have the number of players is much larger than the number of rounds, or if you want to give yourself some breathing space early in your tournament.
interleave_rr If set, players in a multiple round robin play each opponent in turn, rather than each opponent repeatedly before moving on to the next. This option is not set by default, because tournaments run much faster when players don’t have to move from round to round. Some players get bored playing the same opponent repeatedly though, which is why we have this option.
max_rounds Specifies the length of the tournament in rounds. Required.
no_initial_rr If set, there will be no initial round robin phase, even if there are enough rounds to accommodate one. Used in large tournaments including players with widely ranging skill levels.
pairing_system Explicitly set to indicate which of 'auto', 'chew', 'manual' or 'nast' pairings you want. Required when using NAST pairings, optional otherwise.
prize_bands Should be set to indicate which final ranks are equivalent. If you do not set it, you will be warned that you have not set it each time pairings are calculated. Strongly advised.
random_rr_order If set, the top seed in a round robin is paired against randomly ordered opponents; if not set, the top seed faces opposition of increasing strength. Used in Ireland, and useful in reducing data input errors in multi-division events.
session_breaks If set, pairings may be calculated based Fontes-style on the second preceding round’s scores during sessions. If not set, pairings will only be calculated once the immediately preceding round’s scores have all been entered. Strongly advised.
top_down_swissIf set, disable bidirectional optimization of Swiss pairings.Use where strict Swiss pairings are required.

Automatic Pairings

If you prefer to have more control over your tournament’s pairings, or have advertised the use of a specific system that is not the tsh default, you should use automatic pairings. This involves pre-entering all the pairings commands that you expect to use into the configuration file, where they will be automatically triggered when the time is right.

Each auto-pairing configuration line consists of the command word “autopair”, a division name, the number of the round whose results must all be in before pairings can be calculated, the number of the round whose pairings will be calculated, and then a tsh command that generates the pairings.

For example, you can tell tsh that the first seven rounds of your two-division event is a round-robin, and the eighth round is a king-of-the-hill (KOTH):

# When Div. A has no scores and needs Rd. 1 pairings: RoundRobin A
autopair a 0 1 rr a
# When Div. B has no scores and needs Rd. 1 pairings: RoundRobin B
autopair b 0 1 rr b
# When Div. A has Rd. 7 scores and needs Rd. 8 pairings: 
# KOTH with one repeat allowed based on Rd. 7 standings, Division A
autopair a 7 8 koth 1 7 a
# When Div. B has Rd. 7 scores and needs Rd. 8 pairings: 
# KOTH with one repeat allowed based on Rd. 7 standings, Division B
autopair b 7 8 koth 1 7 b

When you ask for the first round’s pairings tsh will compute the round-robin, then later on when you have entered scores for the first seven rounds you can ask tsh for the eight round’s pairings and it will compute the KOTH. If you ask for Round 8 pairings before all results are in for Round 7, tsh will remind you that it can’t compute them yet.

Here’s a slightly more complicated example, for a six-round two-division tournament where the first three rounds are paired using the “InitFontes” command, the next two are paired Swiss based on Round 3 standings but with no repeats, and the last is a KOTH based on Round 5 standings with repeats permitted:

autopair a 0 1 if 3 a
autopair a 3 4 ns 0 3 a
autopair a 3 5 ns 0 3 a
autopair a 5 6 koth 1 5 a
autopair b 0 1 if 3 b
autopair b 3 4 ns 0 3 b
autopair b 3 5 ns 0 3 b
autopair b 5 6 koth 1 5 b

As explained in the section on manual pairings, you might still need to resort to manual pairings even when you have planned on using automatic pairings.

Custom Pairings

Some directors have developed regionally popular idiosyncratic pairing systems. For example, you might have a few rounds paired according to a fixed schedule, a few rounds of Swiss, and a few rounds of KOTH. You can select one of these by specifying a value for the “pairing_system” configuration option. The “ShowPairings” command will then generate pairings appropriate to the specified custom pairing system.

To add a new custom pairing system to tsh, please submit your request at least 1-2 months before its first planned use.

Manual Pairings

You should use manual pairings if you do not know in advance exactly how you will be pairing the tournament, such as when you haven’t decided when to start allowing repeats.

You might also find during your tournament that the automatic system you specified is impossible. For example, you might have asked for a round-robin followed by a KOTH with no repeats. You can quit tsh, edit the automatic pairing instructions and then try again, but if you’re under time pressure you’ll likely prefer to just enter the pairings commands directly and manually.

Prize Declarations

The “PRiZes” command lists all the prizes you are awarding, and if it can be automatically determined, who won them. If you want to use this command, you need to list your prizes in your configuration file using the “prize” instruction. You need one instruction in the file for each prize you are awarding. For example, if you are awarding a high game prize in each of four divisions, it will take four instructions to describe them. Unlike with most other lines in your configuration file, the order in which you enter prize instructions is important, as that is the order in which they will appear in the subsequent report.

Here are some examples of actual prize instructions from the 2008 US NSC:

prize note Place Prizes
prize rank 1 1 $25000
prize rank 2 1 $10000
prize separator
prize note Miscellaneous Automatically Calculated Prizes
prize tuffluck 1 1 $50
prize rank 1 1 $200 groupname='55+ Senior' members=[2,5,6,21,22,23,28,30,42,46,51,52,53,68,69,72,74,78,82,85,91,101,102]
prize brlh 1 1 $200 first=15 last=21 prizename='Division 1 Best Record Day 3 Lower Half'
prize highroundwin 1 1 $20 round=1
prize highroundloss 1 1 $20 round=28
prize lowwin 1 1 $20
prize separator
prize note Signup Prizes
prize signup 'Division 1 Biggest Comeback' 1 $75

Each line has several items, separated by one or more spaces. If an item has a space in it, such as “'Division 1 Biggest Comeback'”, enclose it in matching single or double quotes.

  1. The first item has to be the word “prize”, to identify the line as a prize declaration.
  2. The second item is the prize type: a complete list can be found below.
  3. The third item is the prize subtype: usually the rank a player has to attain in the category determined by the prize type in order to win the prize. In the example above, first place wins $25,000 and second place wins $10,000. Negative ranks count from the bottom of the field.
  4. The fourth item is the name of the division to which the player must belong in order to qualify for the prize. In the example above, all prizes are in Division 1.
  5. The fifth item is the amount of the prize. This may be a cash value, or a description of merchandise.

In addition to these five items, you may have extra items consisting of an item label, an equals sign, and an item value. A complete list of these can also be found below.

Here is a list of all currently defined prize types. If you want to compute a prize that is not listed below, please ask and it will be added.

Prize Type Description
brlh Computes the U.S. NSC's "Best Record Lower Half". Requires two extra items: “first” and “last”. Ranks players according to their record in the range of rounds that these specify, excluding any players who either did not play any games in that range, or began the range ranked in the upper half of the field.
highloss Ranks players according to the highest-scoring loss they recorded.
highratingchange Ranks players according to their rating changes.
highroundloss Requires one extra item: “round”. Ranks players according to the highest-scoring loss they recorded in the designated round (or hyphen-separated range of rounds).
highroundwin Requires one extra item: “round”. Ranks players according to the highest-scoring win they recorded in the designated round (or hyphen-separated range of rounds).
highwin Ranks players according to the highest-scoring win they recorded.
lowwin Ranks players according to the lowest-scoring win they recorded.
luckystiff Ranks players according to their lucky stiffness (smallest margin by which they won six games).
note Adds a note to the prize table.
overseed Ranks players according to how high they climbed from their original rating-based seed.
rank Ranks players according to their wins, losses and cumulative spread.
roundrecord Ranks players according to their wins, losses and cumulative spread over a range of rounds specified by “first” and “last”.
separator Leaves a blank line in the prize table; other arguments are ignored and may be omitted.
totalteam Ranks teams according to the average record of their members in all divisions. See “config minimum_prize_team
tuffluck Ranks players according to the sum of the spreads of their six closest losses.
upset Ranks players according to the difference between their rating and the rating of the highest stronger player whom they were able to defeat. Unlike the a UPSETs command, this version does not consider occasions when an unrated player defeats a higher-rated one.

Here is a table of extra items that may be added to any prize declaration to refine the way prizes are awarded. Each must be followed by an “=” and a value. There must not be spaces before or after the “=”. If the value includes spaces, the entire value must be enclosed in “'”.

Label Description
class The value assigned should be a class name. If this extra item is used, it restricts prize eligibility to players belonging to the designated class.
exclusive If a value is assigned to this item, it designates an exclusive prize category. A player may win at most one prize from any one exclusive prize category. If they are eligible for two prizes, they will be awarded the first one listed, and the second prize will go to the next contender. If you are using this to award class prizes, list your prizes in decreasing order of value, with class prizes ahead of place prizes of equal value. You may also wish to specify “config show_honourable_mention” to list the additional prizes that a player would have won had exclusivity not been in effect.
first Specifies the first in a range of rounds for the “brlh” and “roundrecord” prize types.
groupname If a value is assigned to this item, the default name for this prize will display it between the division name and the prize name.
last Specifies the last in a range of rounds for the “brlh” and “roundrecord” prize types.
memberfile The value assigned should be the name of a file which lists player names, exactly as they appear in data files. If this extra item is used, it restricts prize eligibility to the designated players, who might be of a particular age group or from a particular country.
members The value assigned should be a comma-separated list of player IDs, enclosed in [square brackets]. If this extra item is used, it restricts prize eligibility to the designated players, who might be of a particular age group or from a particular country.

Encoding Directives

If you need to have text in your configuration file that is not in the ISO 8859-1 (Latin) character encoding, use the “encoding” directive to specify an alternate encoding. The new encoding should be named in the directive following white space, and takes effect immediately. If you have no idea what this is about, be thankful.

Raw Perl Commands

Experienced thrill-seekers may also add lines to the “config.tsh” file which begin with the keyword “perl”. This is about as safe as using the tsh shell command “eval”, and does the same thing: it evaluates its argument as a string. There is currently no good reason for using this feature.

The “.t” Files

A “.t” file contains all the information for a division, and must be in the same subdirectory as your “config.tsh” file. It’s a text file that can be edited with a text editor if need be, and is usually created in the first place using a text editor. You may have received “.t” files for your tournament with your tsh distribution, but you should be familiar with the content of this section in case of no-shows and walk-ins.

There is an experimental script for importing data from TourneyMan files. It’s called “parsetm”, is found in the “util/” directory and can be invoked from the command-line to turn one “.ltm” file at a time into a “.t” file. It has been thoroughly tested on the version of TourneyMan to be used at the 2005 US NSC.

A “.t” file should contain one line per player. The line should look something like this:

Chew, John   1850 400 450 350; 10 4 3; p12 1 2 2; board 1 1 3

In this example, a player named John Chew entered the tournament with a rating of 1850. In round 1, he played player #10 and scored 400 points. In round 2, he played player #4 and scored 450 points. In round 3, he played player #3 and scored 350 points. He went first in round 1 and second in rounds 2 and 3. He played at board #1 in rounds 1 and 2, and at board #3 in round 3. Anywhere where there is a space on the line, tsh will tolerate as many spaces as you like, but please do not use tabs. Of course, adding spaces within a player’s name will make many reports look odd.

Scores and opponent numbers may have the special value “00”, indicating that the value has not yet been assigned. This should not be confused with the “0” that indicates a bye.

Players must be listed in order of player number, beginning with player number 1. Note that this means that players must be numbered within each division starting at 1. Unless you feel strongly otherwise, you should number players beginning with the highest-rated. If you want to number players in two divisions in one numbering system without restarting from 1 at the top of the second division, you must call the two divisions one division for data entry purposes.

When you first set up a tournament file, it will probably contain only player names and ratings. So your file will look something like:

Chew, John          1850 
Saint John, Sherrie 1300 
Chew, Kristen       1200 

Player names may include any characters other than semicolons, and must not end in a digit. If you will be submitting your tournament results to a rating system, then you should spell your player names exactly the way that they appear in official rating lists. If you really have to have a player name that ends in a digit (it has happened), put a comma after the final digit and the comma will be silently omitted in reports. Player names should be entered as shown above, with the surname (last name) first followed by a comma. If you do not do so, a few commands which need to know how to split names into given names (first names) and surnames will not function.

Not all files contain the same information for players. Some information only appears if some optional features are enabled. Each set of optional data is preceded by a semicolon and an identifying keyword. At present, the following extensions are in use:

KeywordData
board Lists at which board the player played in each round. This is typically set by the “ShowPairings” command the first time pairings for the round are shown, and not changed thereafter.
class If present, should be followed by a single-word class name: typically ‘A’, ‘B’.... Will be set automatically by the “classes” configuration command, overriding any previously set values. Is used by report generation commands to indicate which class a player belongs to.
cume Is present if the player’s cume must be set to a given value. It should be used with extreme caution, as it will override the regular calculation of cume in all rounds. This feature is not yet fully implemented.
cumeadj Is present if the player’s cume must be adjusted, typically to compensate for a misadjudication. It should be followed by one or two values, the first the amount of the adjustment, the second the round in which the adjustment should first be applied. This feature is not yet fully implemented.
initrec If set, specifies an initial record of wins, losses, spread, capped spread or score sum with which the player is understood to have begun the event.
lifeg If set, indicates the number of games that the player has played in his life, used for ratings computations. If not set, a value of 50 is assumed.
off Is present if the player is inactive for pairing purposes. It is followed by a single integer, indicating what spread ought to be awarded to them for each missed game. This feature is not yet fully implemented.
initrec If present, specifies a record (e.g. “5 2 1000 800” for a player who had 5 wins, 2 losses, +1000 spread and +800 capped spread) that a player is credited with at the start of the event.
p12 Lists whether the player went first (1) or second (2) in each round. Rounds where the player went neither first nor second are marked 0, rounds where the player is paired but has to randomly determine whether or not s/he goes first are marked 3, rounds where tsh is not sure who will go first or even whether a random determination will be required are marked 4.
pname Specifies how a player’s name should be displayed in reports, possibly using Unicode characters not available at the console. You may need to specify a tfile_encoding to use certain characters.
password Specifies a player’s password for self-service scoring.
sbname Specifies how a player’s name should be displayed by the “EnhancedScoreBoard” command. You may need to specify a tfile_encoding to use certain characters.
seat Specifies a player’s seat for realms where seats are numbered instead of boards.
tag Tags a game with a user-specific label, used by NASPA for identifying game lexicon in hybrid CSW-TWL events.
team Names the player’s team, for use in team tournaments. The value is a case-sensitive sequence of words; each instance of white space is collapsed to a single space.
twitter Gives the player’s Twitter handle, which will replace their name in tweets issued by the “TWEET” command.

If you have an Internet connection, you can update the tournament ratings in your player data files at any time using first the “UPDATERATINGS” command and then the “USERATINGS” command. This command is not available for all realms. If it doesn't work in yours, please ask for rating support to be added.

“.tsh” Archive Files

The “BUGreport” and “SUBMIT” commands generates (and depending on configuration may upload) an archive file which concatenates the configuration file with copies of each division data file wrapped between marker lines. Here’s a very simple example.

config event_name = "Sample Event"
config max_rounds = 2
division A a.t
division B b.t
#begin_file name=a.t
Chew, John    1800 2 2 ; 400 350
Chew, Kristen 1400 1 1 ; 350 400
#end_file name=a.t
#begin_file name=b.t
Chew, Jamie 1000 2 2 ; 400 350
Chew, Liam   500 1 1 ; 350 400
#end_file name=b.t

You may use this as an archive format for past events. tsh will accept an archive name as a command-line argument, but treats its data as read-only.

User Profile

If you find yourself running a lot of similarly configured events and want to save the common configuration instructions in one place, you can do so in your user profile using the “PROFILE” command. This command lets you manipulate a file called “lib/profile.tsh” that is currently identical in format to your “config.tsh” files, but is not intended to be edited directly.

A good value to store in your profile is configuration realm.

Dry Run

Once you have everything set up, preferably a few days before your tournament, you should try a dry run of your event. The easiest way to do this is to use the “DRYrun” command, which runs an entire tournament for one division on random data using the pairings you configured. After you’ve looked at all the reports it has generated, use the “RESETEVERYTHING” command to delete all the test data.

If you want finer control over the dry run, you can do what it does manually using the “ShowPairings” and “RANDomscores” commands.

There are also a number of unsupported scripts in the “util/” folder which do further analysis on dry runs, for the purposes of compiling statistics on pairing systems and predicting event winners.

Backups and Redundancy

Now is a good time to think about what to do if disaster strikes. You should always bring an extra computer, extra printer and extra ink cartridges. If you are running a multidivision tournament and have extra staff, then you can use the extra equipment to split the data entry task across two installations of tsh, combining the two if some of your hardware fails.

tsh journals a copy of every “.t” file after every change, which is useful for correcting errors, but not helpful if your hard disk crashes or your computer dies. Follow the standard rule for backups: make a copy of important files often enough that you don’t mind having to type in any changes since your last backup. For “.t” files, this should be somewhere between every round (to be safe) and every session (to live dangerously). Back up files to other computers, the net, and/or removable media.

If your computer fails and you do not have a spare computer, announce what has happened, gather scorecards and any qualified directors and do pairings by hand. Then write out “I will not run a tournament without a spare computer” enough times by hand that you learn your lesson.

If your printer fails or you run out of ink, in a small tournament you can probably write out or announce pairings aloud, especially if you just need to cover until you can find a replacement cartridge.