DIR : /home/kozerus/public_html/dgs/dgs/specs/tournaments.txt

/home/kozerus/public_html/dgs/dgs/specs

# Topic: Tournaments
# Description: Managing tournaments on DGS
#
# URL: http://www.dragongoserver.net/forum/read.php?forum=5&thread=9423#9423
#      http://www.dragongoserver.net/forum/read.php?forum=6&thread=25718#25735
# Author: Jens-Uwe Gaspar, DGS 'juga'

## /*
## Dragon Go Server
## Copyright (C) 2001-  Erik Ouchterlony, Jens-Uwe Gaspar
##
## This program is free software: you can redistribute it and/or modify
## it under the terms of the GNU Affero General Public License as
## published by the Free Software Foundation, either version 3 of the
## License, or (at your option) any later version.
##
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU Affero General Public License for more details.
##
## You should have received a copy of the GNU Affero General Public License
## along with this program.  If not, see <http://www.gnu.org/licenses/>.
## */

Legend:
- T = Tournament
- TD = Tournament director
- TP = Tournament participant/player
- TV = Viewer of tournament
- Opp = opponent
- TL = tournament-ladder
- TRR = tournament-round-robin

Topics:

   1. Introduction
   X. Design, Classes and Files (implementation details)

   * Tournament = tourney = T : what it is, what it not is
   * types of tournaments : Ladders, Round Robin, Matrix (=TRR with 1 pool & 1 round)
   * scope of Ts: Dragon, Public, Private
   * tournament-process + status: ADM,NEW,REG,PAIR,PLAY,CLOSED,DEL
   * tournament-editing: locks
   * tables -> ddl-description
   * roles of T: T-Adm, Owner, TD, TP, TV

   * GUI for T-Adm, Owner, TD, TP, TV
      * page T-wizard: How to create new T (setting defaults)
      * page T-list
      * page T-info
      * page T-Manager
         -> common managing: info-section (T-info, owner, last-changed, changedby, my-role, flags, status)
         -> common managing: edit-locks, change-status, edit-T, news/bulletins, add TDs, edit-reg-props, edit-game-rules
         -> specifics for tournament-ladders.txt : edit-ladder-props
         -> specifics for tournament-round_robin.txt : change-round-status, edit-rounds
         -> common managing: edit-TPs
         -> specifics for tournament-ladders.txt : adm-ladder, edit-ladder, view-ladder
         -> specifics for tournament-round_robin.txt : def-pools, create-pools, edit-pools, edit-game-pairings
         -> common managing: admin-TG
         -> specifics for tournament-round_robin.txt : edit-ranks
         -> common managing: show tournament-log
      * page T-game-list
      * page TP-list
      * page TP-reg, TD-edit-reg
      * T-cron

   * ladder: "What happens with running games on user-removal ?"
      * use-cases for user-removal:
         (1) user removed by TD/T-Adm
         (2) user withdrew from ladder
         (3) user removed by T-system (game-end ladder-config)
         (4) user removed by T-system (long-absence ladder-config)
      * user is removed from tournament-ladder (other users move up one rank)
      * users tournament user registration is removed
      * running games are "detached" (continued as normal games)
         * Games.Flags-detach set
         * TG.Flags-detach set, TG.Status=SCORE to be processed and challengesIn/Out corrected (time-delayed by cron)
         * "detached" can be seen on game-page, gameinfo-page, game-list for T
      * if user re-joins challengesIn/Out are corrected from ACTIVE (PLAY|SCORE) games
      * notify sent to user (except for (1))
      * notify sent to opponents of running games

   * Requirements / Backlog / Ideas:
      * see below 'Wanted features'

   * Consistency script


#-------- (1) Introduction ----------------------------------------------------

#-------- (2) Users Guide -----------------------------------------------------

#-------- (2a) Setup MP-game --------------------------------------------------

#-------- (3) Design, Classes and Files ---------------------------------------

* Table-Design:

* Classes / Files:



#-------- Design Thoughts --------------------------------------

T-process:
   - T-creation
   - T-registration
   - T-confirmation (opt)
   - prepare T-round + T-games (auto/manually)
   - T-start: auto-start all games
   - (TPs playing games), TPs-game-end: gather results, end round, next round (prep)
   - T-close: report T-winners

T-use-cases / pages:
   - create new T
   - list Ts
   - view T

#--------------
# checks on TP-count:

T-types: TL | TRR
T-status: REG | PAIR | PLAY
StartRound: 1 | 2 (= >1)
Use-Cases:
   - U1. user-reg-new      (TP-status ->REG)
   - U2. user-edit-reg     (meaning TP-status is not changed from APPLY/INV <-> REG)
   - U3. user-ack-invite   (TP-status INV->REG)
   - U4. user-new-apply    (TP-status ->APP)
   - D1. td-invite         (TP-status *->INV)
   - D2. td-ack-apply      (TP-status APP->REG)
   - D3. td-edit-tp        (meaning TP-status is not changed from APPLY/INV <-> REG)
   - C1. T-stat-chg REG->PAIR
   - C2. T-stat-chg PAIR->PLAY
   - C3. T-stat-chg PLAY->PAIR (next-round);    (only for admin?)
   - C4. TRR next-round-change                  (implicit C3)

NOTES:
   - MaxTP may be 0 (=unlimited), then use db-MaxTP instead for checks
   - for NOW, edit-TP is ONLY allowed for REG/PLAY (TL) or REG (TRR), i.e. all TPs must be properly REGed for PAIR-status (no user can be removed if he wishes for TRR, for TL it's possible by withdrawal or remove-user) -> for TRR it would be special use-case to remove-TP (or edit-TP) after T already started !!

Features:
   - F1. T has MinTP/MaxTP-limits, but MaxTP can be unlimited (=0)
   - F2. T can have multiple rounds, also with some Max-TP-limits based on MaxTP
   - F3. TP should NOT be able to apply/register if MaxTP reached (not to overload TD with TPs to handle, and to allow first-come-first-serve)
   - F4. TP should be able to edit his application once he is on INVITE/APPLY-TP-status
   - F5. TD can not invite TPs exceeding the MaxTP-limit (first take care of APPLY/INVITE'd TPs -> REG or REMOVE)
   - F6. TD must sort it out to keep all TPs registered before T can start (precondition on T-stat changes)

General Check:
   - if StartRound > 1 and MaxTP = 0 -> use MaxTP = DB-max-allowed instead    [F1]
   - MaxTP for StartRound > 1 calc'ed by: ROUND( MaxTP / 2^(StartRound-1) )   [F2]
   - assure, that T-status REG ONLY possible with Round=1

What checks are needed on TPs:
   - TL: StartRound = 1 (always), MaxRounds = 1
      - U1-4/D1-3. error like (TRR.U1-4/D1-3)
      - C1. T-stat-chg REG->PAIR: like (TRR.C1)
      - C2. T-stat-chg PAIR->PLAY: like (TRR.C2)

   - TRR:
      - Round N:
         - T-stat REG: (only round 1)
            - U1. user-new-reg: error; reg not allowed if #TP[Status=ALL,StartRound=i] >= MaxTP/2^(i-1)
            - U2. user-edit-reg: error like (U1)
            - U3. user-ack-invite: error like (U1)
            - U4. user-new-apply: error; apply not allowed if #TP[Status=ALL,StartRound=i] >= MaxTP/2^(i-1)
            - D1. td-invite: error like (U4)
            - D2. td-ack-apply: error like (U3)
            - D3. td-edit-tp: error like (U2)
            - C1. T-stat-chg REG->PAIR: for round i=1..MaxRounds: #TP[Status=ALL,StartRound=i] <= MaxTP; #TP[Status=APPLY|INV] == 0; #TP[StartRound>1] <= MaxTP / 2^(i-1); do NOT check on TP.NextRound but StartRound!!
         - T-stat PAIR:
            - C2. T-stat-chg PAIR->PLAY: no TP-checks
         - T-stat PLAY:
            - C3. T-stat-chg PLAY->PAIR: like (C1)-checks
            - C4. #TP[Status=REG,StartRound=CurrentRound+1] + #PoolWinners[CurrentRound] >= 2

What can be expected for T-status:
   REG:  #TP[Status=ALL,StartRound=i] <= MaxTP / 2^(i-1)
   PAIR: #TP[Status=ALL,StartRound=i] <= MaxTP / 2^(i-1); and there are no TPs on Status = APPLY|INVITE
   PLAY: like PAIR for TRR; like REG for TL (allowed to join on PLAY-status for ladders)

#-------- Wanted features --------------------------------------

Tournament-types:
   - Ladder, King of the hill
   - Round-Robin (= Elimination)
      - Matrix = round-robin single or double with 1 round & 1 pool
   - League-T (pyramid-like structure), connection to next/prev Ts
   - Championship (ala IYT): http://www.itsyourturn.com/pp?tournmain
   - K.O. variations (rounded T):
      - Best of 2 (std), Best of N (N>1) + N-Best of M (N,M>1)
      - Double-KO
   - McMahon, Swiss
      - see diploma-thesis Christoph Gerlach: http://senseis.xmp.net/?McMahonPairing
      - upper / lower / no bar
   - Manual (?), flexible setup

Features / Processes:

* General:
   - define T process
   - T can handle more than one TD
   - TD can add time to game, TPs can't add time
      - add time for directors ? to users with time-cheating (timezone) ?
      - game-page: "add-time" not possible for tournaments(!)
   - setup: TP requirements (rating or by TD, min. finished/rated games, min. moves, min. active play)
   - setup: T min/max TP
   - handling of vacation: ignore-vacation
   - forbid delete-game
   - support-ticket to all TDs
   - bulletin board to all TDs/TPs -> may use T-forum, multi-receiver messages, maybe RSS-feed on forum
   - manage fee-paid, even if not paid over DGS (register-phase) (?)

* registration + removal / user-related:
   - T registration
   - TP unregister
   - Invite-tournaments: register only by inviting; manual invite to T by TD
   - REG: TD has full control of T-registration, T-games and T-results for "punishment" (unfair conduct, escapers, swindlers) or "adjudication"
   - TD can set TP in any round/pool
      - some players start in round >1 (e.g. winners from last tournament or dan-players) & more
      - setting players in later rounds (dan/prev-tournament) by director
   - handling late-entrance: TD can add TPs at any time (after T started)
   - handling of sandbagger, escaper, swindler by TD
   - handling tournament-escapers: TD can set/end/overwrite result of game
   - need tournament-rank for players, changeable from normal DGS-rank; use DGS-rank
      - TP can register with DGS rating, TD can overwrite it
   - (TRR) use start-rating or current rating in all rounds

* type-related / setup games / scoring:
   - T-types: round robin (pooled), 1-n rounds with pools of 1..m TPs
   - PAIR: Pairing algorithms (depends on T-type): slaughther, slide, adjacent, random; "bars"; TD has full (manual) control over "pairing"
   - pairing / rounds / pools
   - setup: winner-calculation (wins/tie-breaker/rounds)
   - (TRR) rules: tie-breaker, http://senseis.xmp.net/?TieBreaker
   - (TRR) rules: score of a "bye" (=forfeit) 0 or 0.5
   - (TRR) handling different participant-counts in pools towards points-rank
      - (TRR) handling tournament-escapers (odd <-> even TPs, pooling)
   - T-scoring / pairing: McMahon, Swiss, Round-Robin, Hahn-System (http://senseis.xmp.net/?HahnSystem)
   - T-scoring: http://senseis.xmp.net/?TournamentScoring
   - T-game: game rating is independent from tournament
      - T can have rated games but should not control if game is made unrated, though T-director can set T-game unrated as T-director set up T as rated

#-------- Tournament References --------------------------------

* General SL-links:
   - DGS-T-Features: http://senseis.xmp.net/?DragonGoServer%2FTournaments
   - http://senseis.xmp.net/?OrganizingATournament
   - http://senseis.xmp.net/?TournamentDirectingSoftware

* Former DGS-tournaments (managed on SL):
   - http://senseis.xmp.net/?DGSShogun (partly failed)
      - I Shogun: http://www.garyshomepage.btinternet.co.uk/Tourney/tourney_index_page.htm
   - http://senseis.xmp.net/?DragonTourney2005
      - http://www.dragongoserver.net/forum/read.php?forum=4&thread=7398
   - http://senseis.xmp.net/?DragonTourney2006
   - http://senseis.xmp.net/?DragonTourney2007
   - http://senseis.xmp.net/?DragonTourney2008
      - http://senseis.xmp.net/?DragonTourney2008%2FRegistration
   - http://senseis.xmp.net/?DragonTourney2009
   - http://senseis.xmp.net/?DragonTournament2010

   - http://senseis.xmp.net/?Ryzours DGS-tournament-director (-2009)
   - T-attempt: http://www.dragongoserver.net/forum/read.php?forum=4&thread=15858

* URL(TBGG - turn-based-go guild):
   - Erik was one guild-founder, "King of the Hill" and "Ladders"
   - http://senseis.xmp.net/?TurnBasedGoGuild
   - http://business.baylor.edu/steve_rich/go/rules.html (dead)

* Templates:
   - (TRR) google-tabs: http://spreadsheets.google.com/pub?key=p6wtm-AUn1NmziCSIU-oeGg
   - (TRR) google-tabs: http://spreadsheets.google.com/pub?key=p6wtm-AUn1NmURr6h4S45Kg
   - (TRR) LittleGolem (Tie-Breaker SODOS): http://www.edcollins.com/golem/#What%20is%20Son?
   - (TRR) LittleGolem: http://www.littlegolem.net/jsp/tournament/tournament.jsp?trnid=go9.ch.1.1.1
   - (TRR) Chess T-status/Pool-Matrix: http://www.yourturnmyturn.com/toernooi.php?toernooi=2814

* Other Go Servers:
   * http://senseis.xmp.net/?TurnBasedGoServers

   * FICGS: http://www.ficgs.com/tournaments.html#go_tournaments

   * IYT: http://www.itsyourturn.com/pp?tournmain

   * LittleGolem:
      - http://www.littlegolem.net/jsp/tournament/index.jsp
      - FAQ: http://www.edcollins.com/golem/#Could you explain the different types of tournaments available?

   * OGS: http://www.online-go.com/
      - Formats: http://senseis.xmp.net/?OGS%2FTournamentFormats
      - Example: http://www.online-go.com/faq/tournaments.php#q1b

* old incomplete tournaments on DGS (2004): see SCM-history (dead files):
   new_tournament.php
   list_tournaments.php
   show_tournament.php
   create_tournament.php
   include/tournament_round.php
   include/tournament.php
   include/tournamenttypes/macmahon.php
   include/tournamenttypes/index.php
   include/tournamenttypes/all_types.php
   specs/old-dgs-tournaments-2004.sql

#-------- Related features -------------------------------------