Editing Match Management System

{{DesignDocument}}

==Overview==
The goal is to replace the existing '''/countdown''' and '''/gameover''' commands with a more unified matching system.

==Current Weaknesses==
The current system suffers from a number of weaknesses, including;
* Requiring everyone to leave the server to reset after a match.
* Little to no user control over who can and can not play.
* No method of reporting matches to the server owner or other authority.
* Inconstancy in command names.
* Has no support for non CTF leagues.

== /match command==
The core concept is to remove the /countdown and /gameover commands and replace them with a new single "/match" command. The match command will handle all the match related features. All match related permissions will be folded into a single "MATCH" permission.

The /match command will take the following options.

* Start <duration>: Begins a timed match. If the optional duration is specified it will be used instead of the default.
* End <reason>: Ends a timed match, broadcasting the reason if specified. Triggers a log entry in the server reports file with the match results and the reason.
* Pause <duration>: If the game is not paused, pauses the match. If the duration is specified the pause will automatically resume after the specified time unless manually resumed. If the game is paused the command will resume the match. If a duration is specified then the match will resume after the specified time. When games are paused, players will not be able to move or shoot.
* Substitute <playerA> <playerB>: Swaps observer player A for player B. If the command is given by a playing player, playerB is inferred. If the command is given by an admin both players must be specified. The score of playerB is applied to playerA. PlayerB must also be ether dead, paused, or NR.
* No Option: If no options are specified then the command will report the current status of the match.

===Reporting===
The match command will automatically report results to the report channel. If the server is setup to log these to a file they will be logged with it.

==API hooks==
API hooks will be added for each of the events, including the report event. This can allow for plug-ins to be made to report to websites or other reporting systems.

==Match Sample Flow==
An example of how a match may go would be;

* User calls /match start.
* Server announces that a timed match will begin in '''_matchPregameTime''' and does a countdown.
* Server waits for '''_matchPregameTime''', then clears all scores, despawns all players, and resets all flags. 
* Server announces that the match is starting, and spawns all players. If the game is a CTF game, all players will spawn on base.
* Match game plays out. If '''_matchDisallowJoins''' is true then new joining players will forced to observer.
* When match time reaches '''_matchEndCountdown''' from the end duration the server will begin an end countdown.
* When match reaches its duration the server will print out a notification, and report the results to everyone and the report channel.
* All players will be prevented from moving or shooting for '''_matchResetTime'''.
* When '''_matchResetTime''' has passed, all scores will be reset if '''_matchResetScoreOnEnd''' is true, and all players are despawned, and can respawn as desired. Again if the game is CTF all players will spawn at base.

This breaks the game up into 3 major sections. Pregame, Game, and Postgame. The match can only be paused during the Game section. It can be ended early during the Pregame and Game sections. A new game can only be started during the Postgame section.

== BZDB variables==
The following are the various BZDB vars that are used to configure the match system, as well as the default value.
* ''_matchPregameTime'' ('''60''') number of seconds after a /match start command that the match will start in.
* ''_matchDisallowJoins'' ('''FALSE''') controls whether or not players that join after the match has started will be allowed to join a real team. If this is true, new players will be shunted to the observer team.
* ''_matchDuration'' ('''1800''') the default duration of a match in seconds, -1 means the match will run until ended manually, or by a plug-in.
* ''_matchEndCountdown'' ('''30''') the number of seconds before the match end that the server will start a match end countdown.
* ''_matchResetTime'' ('''120''') the number of seconds for the postGame wrap up.
* ''_matchResetScoreOnEnd'' ('''TRUE''') controls whether or not the scores are reset after the post game time.
* ''_matchReportMatches'' ('''TRUE''') controls whether or not the system will send match results to the /report channel.