TD_USER_GUIDE

Tournament Director's User Guide
--------------------------------

Before You Start
----------------

You're going to need an account on a site running the software.
The site operator needs to give you the appropriate permissions.
Throughout this document, we'll assume the site is https://example.com/.

Concepts
--------

Most of this should be fairly familiar, but there are some subtleties.
Things will be more obvious if you have a good understanding of these concepts.

A Player is a person who plays Diplomacy.
A Tournament is an event where people play Diplomacy competitively.
A Tournament consists of a number of Rounds, each of which has a number of Games.
A Round may optionally be divided into two Pools, one with a set number of Games
(for example, a beginner pool or a top board pool).
Each Game is played with a GameSet (e.g. the Avalon Hill edition).
Tournaments may be part of a Series, for example an annual tournament or an
event like DipCon that is hosted by different tournaments in different years.
A Tournament hands out Awards to deserving Players based on various criteria.
By default, these are just seven "Best Country" awards.
A Team is a group of players whose scores in certain Round(s) are added to give
the team score.

When Players register to play in a Tournament, this is represented by a
TournamentPlayer. When Players are present at roll call for a particular Round,
this is represented by a RoundPlayer. A Player playing a particular Game is
represented by a GamePlayer (note that the system doesn't currently support
replacement players - each Great Power in a Game has exactly one GamePlayer).

Games are scored using some GameScoringSystem (the system has support for all
the systems commonly used in North America). There are two possible mechanisms
for combining game scores into tournament scores - a 2-step and a 3-step process.
In the 3-step process, scores for Games in a Round are combined into scores for
each Round using a RoundScoringSystem. This only matters if you have players
playing multiple Games in a Round - you may want all games played by a player to
contribute to their score or just the best result. Similarly, Round scores get
combined using a TournamentScoringSystem. The system currently support "best 2
rounds", "best 3 rounds", and "best 4 rounds". This allows you to have a "drop
round" or to include all round scores.
In the 2-step process, the RoundScoringSystem should be set to "None", and the
TournamentScoringSystem should be set to one of the "Sum best N games" options.
In this case, the actual rounds are ignored and all game scores are considered.
In both processes, you can also give points to players who volunteer to sit out
a round to make the numbers work. In the 3-step process, this simply gives the
player a score for the round despite having no games in that round. In the 2-step
process, the score for sitting out a Round is treated like an additional score
for a Game.

The system also knows about SupplyCentres, CentreCounts, and DrawProposals, all
of which should be fairly self-explanatory.

The final concept is a SeederBias. This is used to guide the game seeding algorithm.
Essentially it tells the system to do its best not to have those players play a
game against each other. It is intended for use when you have family members
that you would prefer not to end up at the same board.

Finally, it reads background information from the World Diplomacy Database and/or
World Diplomacy Reference and stores it as PlayerAwards, PlayerGameResults,
PlayerRankings, and PlayerTournamentRankings, but you shouldn't need to worry about
those at all.

Creating Your Tournament
------------------------

Start out at https://example.com/admin/tournament/tournament/add.
Give the tournament a name (the year will automatically be appended), format (FTF
or vFTF), location, dates, and pick a TournamentScoringSystem and RoundScoringSystem.
If you want to include a team round, specify the size of the teams (number of
players).
You can specify any bonus points for sitting out a Round and whether those
bonus points can be awarded more then once or not. You can also specify whether
the Tournament uses handicaps, which are additional points that are assigned by
the TD but kept secret until all Games have finished.
The system can either show the scores as they were after the last round ended,
or "if all games ended now", so choose which of those you prefer.
Decide whether you want the system to seed the games or not, how Great Powers
will be assigned, what you're going to tell players about failed DrawProposals,
and whether best countries are determined by score or centre count.

If there's a Discord channel for the tournament, you can create a webhook to that
channel on Discord and add it to the tournament. This will allow the system to
post board calls directly to that Discord channel.

Next come some items to control how the site will treat the Tournament. Make
yourself a Manager (you can add others too if you like), and decide whether to
publish the Tournament on the site. Unpublished Tournaments will only be visible
to users with accounts on the site, so it's a good idea to keep it unpublished
while you're getting everything set up. You might not want to publish it at all,
or only to publish it after the Tournament is over. Keep the Tournament Editable
until it's over and all the data has been entered. Check the "no email"
checkbox if you're going to be doing any experimenting (e.g. trying out game
seeding) or if you don't want the system to send email to the players at all.
You may also want to check "Delay publishing game URL" if you are going to have
games taking place on Backstabbr or recorded in Backstabbr sandboxes. By default
in these case, the system will link to Backstabbr.

There are also fields to enter the Tournament's id in the World Diplomacy Database
and World Diplomacy Reference, but you won't be able to enter these until after the
results have been uploaded to those sites.

Pick which awards you are going to hand out. If needed, you can add additional awards
by clicking the "Awards" link in the left-hand panel.

Next you can add Rounds. For each one, you need to specify the start and end times and dates,
and the scoring system used for games in that Round (most Tournaments will use the
same scoring system for every round, but the system supports deviations from that).
You also need to decide whether Draws in the Round include all survivors (DIAS). If
you have teams, specify which round(s) will count towards team scores.
If you want, you can specify that a Round ends after a particular game year or
between specified times.

Scroll all the way to the bottom to find the "Save" button.

Now your Tournament has its own page on the site. Let's assume it's
https://example.com/tournaments/42/.

If any of your Rounds need to sub-divided into Pools, create those Pools now by going
to https://example.com/admin/tournament/pool/add/ Note that only Rounds with exactly
two Pools (one with a fixed board count) are currently supported, so create both Pools
now. Most likely your fixed-size Pool will have one board.
For each Pool, you can specify a game score multiplier (for example if the top board
scores double a regular game), you can override the Tournament's power assignment method
(for example to not have the system assign powers for your top board), and you can
specify that the Pool determines a number of overall Tournament positions (e.g. that
the three highest-scoring players on the top board will get first, second, and third
place in the tournament, even if someone who didn't play the top board got a higher
tournament score).

Registering Players
-------------------

The tournament page will list the number of players currently registered near the
top of the page. This is a link to the Tournament Players page at
https://example.com/tournaments/42/players/, where you will see them listed and
you can add and remove them.

Unregistering a player is as simple as clicking the button by their name. Note, though,
that the system will get very confused if you unregister a player who has already
played any games. Once the Tournament is underway, you're probably best just leaving
anyone who didn't show up, just to be safe.

Registering a player is very easy as long as the system knows about them - just
select their name from the dropdown list and click "Submit". You can currently add
up to 4 players at a time, and you'll end up back at the same page.

If the Player you want to add doesn't appear in the dropdown list, follow the link to
https://example.com/admin/tournament/player/add/ where you can add them. Please
do check before adding them - de-duplicating players who are in the system twice has
to be done by hand and is quite tricky! Note that email address, if provided, will
be used to send board calls to, and also to send a link to enter power preferences
if that's how Great Powers are assigned in your Tournament. The "WDD id" is used to
provide background information about the Player. The "picture" is for future use.
Any "Backstabbr username" will be displayed in board calls for vFTF Tournaments.
"Backstabbr profile URL" is still a work-in-progress.
"Location" and "Nationalities" are displayed in the list of registered players.
The "User" field is to match-up Players who are also TDs who use the system (by
default, Players who play in a Tournament that they help manage will be "Unranked"
- they won't be eligible for Best Country awards and their score will be noted
separately to everyone else.

On this page is a link to a separate page where you can track who has paid to
attend, if desired.

If your Tournament uses handicaps, there will be a link to a separate page where
you can enter the handicap for each registered Player. This will be added to their
score after all Games have ended.

This is also a good time to add any SeederBias that you might need. Your Tournament
page has a link to https://example.com/admin/tournament/seederbias/add/ where you
can specify the pairs of TournamentPlayers to keep apart.

Great Power Preferences
-----------------------

If you're using preference lists to assign Great Powers, hopefully most players will
provide you with an email address. In that case, when you register them, the system
will send them an email (unless you checked that "no email" flag for the Tournament)
with a unique URL where they can enter their preferences for the Tournament. You can
see which have been sent out from the tournament player page, and you can also re-send
them from here if needed.

For players who don't provide an email, you can enter their preferences by hand at
https://example.com/tournaments/42/prefs. Preferences are entered as a string of
characters, for example "FGIRT" meaning "France, then Germany, then Italy, then
Russia, then Turkey, with England and Austria joint last".

Roll Call, Pool Population, and Game Seeding
--------------------------

Note: the software has the concept of "the current round", which is determined
by which rounds have RoundPlayers (i.e. roll call has been done) and Games that
haven't yet finished. One effect of this is that you shouldn't enter roll call
information until you're actually about to start the round (in practice, you
don't know for sure who's going to show up until then anyway).

Shortly before the Round starts, go to the round page, which should be
https://example.com/tournaments/42/current_round/
There you will find a "Roll Call" link to https://example.com/tournaments/42/rounds/1/roll_call/
Here you simply check the "Present" box by each player who is present to play the round.
You can also flag players as "Standby" if they would prefer not to actually play
but are willing to play if needed, and as "Sandboxer" if they are willing to record their
game in Backstabbr as it progresses. "Rounds played" is for TD information, in case
you want to enforce that players don't play every round.
Once you have everyone entered, press "Submit".
If the Round has Pools, you will go to a page to specify which players are in the fixed-size
Pool. Select the appropriate players and click Submit.
This will take you to the "get seven" page. If you have an exact multiple of seven
players (possibly including standby players), you can just seed the games from here.
Otherwise, the system will prompt you to either have players sit out the round or to
have players play multiple games. Just select them from the dropdown lists and hit "Seed Games".
The system will go ahead and seed the boards. This page annotates players willing to
record their game with an asterisk so that you can ensure that every board has somebody
recording it if needed. Note that you can refresh this page to re-do the seeding if needed.
You can also make changes manually. For a vFTF tournament with games on Backstabbr or a
tournament with games captured in sandboxes, you can enter links to the games on backstabbr
on this page to make it easier to import centre-count information. Once you're happy, press
"Submit" and the Games will be created, including sending out emails to the players (unless
your Tournament has the "no email" option selected) and posting to the Discord webhook (if any).

Team Entry
----------

Before the first team round, you'll need to follow the link to "Add/edit teams" and enter
all the teams. Each team needs a name and a set of players (teams can have fewer than the
specified number of players).

Top Board Tie Breaks
--------------------

It is common to have some sort of tie break system for top boards. This is supported by setting
the "tie_break_rank" GamePlayer attribute for all top board players. This currently has to be
done through the admin. Each top board player should be given a unique number, with the system
resolving any ties by comparing these attributes. The player with the lower number will be ranked
above the one with the higher number. If this attribute is not set, the system will give tied
players equal rank.

Game Tracking
-------------

How much you do here really depends on what you want to achieve. The system is designed
to allow people to follow along with the tournament as it progresses, but that obviously
means more data entry on your part than just tracking the results of games.
Your options are:
Upload images for games as they progress. Ideally every season, but gaps are ok.
Enter SupplyCentre ownership data after each game year (in this case the system will
calculate CentreCounts).
Enter CentreCounts after each game year. (For a vFTF game, or if the Game has a
backstabbr URL, you can grab the current CentreCounts from Backstabbr by
just clicking the "Import SC Counts from Backstabbr" link on the Game page).
For DrawProposals, you can enter all of them or just the ones that pass, or just flag Games
as ended if the draw doesn't affect the scoring.

The bare minimum is the final year CentreCounts and any successful DrawProposals. These are
needed to calculate scores. For some scoring systems, you'll also need to enter elimination
years if you don't enter SC Counts for those years.

If you were to enter all the above data, people would be able to see timelapse-style
displays of the board state, charts of SC ownership and centre counts, graphs of
centre-counts over time, and textual highlights like "Austria dropped from 5 to 2, losing
Trieste to Italy, Greece to Turkey, and Budapest to Russia", as well as up-to-date "if all
games ended now" scores.

Remember that if you want people to be able to follow the Tournament, or even just see the
standings, you'll need to set it to "Published".

Results
-------

The system will calculate scores as games progress (it continually updates all the scores
on an "if all games ended now" basis), and will provide charts for best countries,
as well as a leaderboard.

If necessary, you can override the calculated scores.

The system will automatically determine every player's placement in the tournament as well
as who earned each "Best Country" award. You can record who earned any other awards and/or
change the "Best Country" recipients if needed on the "Awards" page for the Tournament.

Once the Tournament is over and all the data has been entered, please uncheck the "Editable"
checkbox for the Tournament (and Save it). This will help prevent inadvertant changes.

Upload to WDD
-------------

Once your Tournament is complete, the system can generate the two CSV files needed to
upload the results to the WDD. Once your Tournament is actually on the WDD, please take
a moment to set its "WDD Id" (and Save it) to help with cross-referencing.