This page describes the operation of the referee box. It is intended to serve as a reference for referees and referee box operators. It will hopefully also be helpful to teams, as it explains the sequence of events that take place in a game and describes the different commands and stages. For specific details on the protocol, see protocol; this page instead describes the commands at a high level and explains how they relate to each other and what sequences of commands occur during a game.
At the top of the window are the big four buttons: halt, stop, force start, and normal start. These are some of the most frequently used buttons in the referee box.
Below the big four buttons are two large indicators showing the number of goals scored by each team (excluding penalty shootout goals when in the penalty shootout game stage). Below each indicator is a coloured bar showing which team the number applies to; these bars are editable drop-down boxes in which the teams’ names should be selected or typed (these can only be changed in halt). The button labelled “<-->” swaps all attributes of the two teams (goals, names, timeouts, and cards), and is used in the rare case where a team wants to swap colour at half-time; this button is also available only in halt.
The left part of this section shows, from top to bottom, the current game stage, the time elapsed in the game stage, the time left in the game stage, and the current state of play. As the referee box operator, it is your responsibility to monitor the time left in the current game stage (whether play or half-time) and notify the referee when this reaches zero. For a play stage, the referee will likely allow the current play to end after the time expires, and may allocate some extra time if excessive time was wasted during play for some reason. Also, should play stop in a way that leads to a penalty kick, the penalty kick is always taken even if no time is left in the stage.
The middle part provides a few additional buttons. The goal buttons award goals to the specified team and are available in stop. Each goal button has an adjacent minus button which subtracts a goal, to be used if a goal is accidentally awarded to the wrong team or when it should not have been. The cancel card or timeout button is available immediately after issuing a yellow or red card or starting a timeout and reverts all effects of the action: for a red card (usable in stop), the card count is decremented; for a yellow card (also usable in stop), the card is deissued and the timers are updated appropriately; for a timeout (usable while inside the timeout), the number of timeouts remaining is incremented and the timeout clock is reset to the value it had when the timeout was started, and the game is moved to the stop state. Thus, this button should be used immediately after accidentally issuing a card or timeout inappropriately (for cards, the button remains available throughout state and even stage changes, but obviously the card should be cancelled as soon as possible to minimize impact on gameplay).
The right part provides buttons for moving between game stages:
At the top of each team’s control rectangle are the controls and indicators for the team’s timeouts. A team can enter timeout only from the stop state. The referee box records the amount of timeout time and the number of timeouts each team has left, but it does not prevent the operator from starting a timeout when that should be impossible—it is at the referee’s discretion to permit additional timeouts in exceptional circumstances, and the referee box allows this. Timeouts can be taken during normal play stages or during *_PRE stages, but not during breaks. Once a timeout is issued, the game clock stops, a timeout is subtracted from the team’s stock, and the team’s timeout clock starts counting down. There are three actions available within a timeout: the stop button finishes the timeout and resumes the game (the normal way to end a timeout), the halt button stops the timeout clock from counting (to be used if the referee needs to consult with teams without penalizing them for timeout time) and allows either resuming the timeout (with the timeout resume button) or ending it (with the stop button), and the cancel card or timeout button reverts the timeout as if it never happened, resetting the timeout count and clock to their original values.
Below the timeout controls is the goalie selector. This field, which can be adjusted in halt and stop, must be set to the SSL-Vision index of the team’s goalie. This value is sent to the teams and can be used to detect a second defender in the defence area. This value must be adjusted using the mouse buttons on the spinner arrows or the up and down arrow keys; direct numerical entry is disabled to avoid confusion between typing numbers and pressing command hotkeys.
Below the goalie selector are the four favourable restart buttons:
Finally, at the bottom of each team’s rectangle are the card buttons. The yellow card button issues a yellow card to the team and displays the time remaining on the card; additional cards will be represented by a count in brackets (e.g. “(+1)” means there are two yellow cards issued, the one whose time is shown plus one more) and will display their time once the first card expires. It is the responsibility of the referee box operator to watch the yellow card timer and inform the referee when it reaches zero, thus allowing a robot to be placed back on the field at the next stoppage of play. Red cards do not have timers, but a count of issued red cards is shown on the button. In both cases, the last issued card can be cancelled using the cancel card or timeout button.
The penalty shootout game stage changes the operation of the referee box quite a lot:
A typical game would begin with pre-game setup. Here, the referee box operator sets the names of the two teams in the name fields (immediately below the score indicators), and also sets the initial goalie indices for the two teams.
To start the game, the operator will first issue stop, noting that the referee box is already in the pre-game state. The robots will now start moving. The referee will call for a kickoff of the appropriate team, which must be entered. Finally, once the referee is satisfied the robots are in position, a normal start is issued and the first half begins. Normal gameplay proceeds as a series of stops followed by restarts (force starts, direct and indirect free kicks, and kickoffs and penalty kicks with normal starts), interleaved with occasional goals, cards, and timeouts.
When the game clock reaches zero, the referee box operator communicates this fact to the referee. Once the referee is ready to enter half-time, the referee box operator pushes the half time button. At the end of half time, the referee acknowledges the end of half time and the operator pushes the second half button. From here, play starts with a kickoff just as at the start of the game.
At the end of the second half, if the scores are different or if a round-robin game is being played, the operator pushes end game; otherwise, the operator pushes half time and a break occurs before the start of first overtime period. This break, the two overtime periods, and the break between them run just like normal time, the second overtime period again ending with either end game (if the scores are different) or half time (if they are the same and a penalty shootout is needed).
If a penalty shootout is taken, the penalty shootout button starts the stage, after which the shootout is executed as a series of stop, penalty, normal start sequences. Once the necessary goal difference is obtained, the operator pushes end game.
On every game stage change, every new command, every five seconds, and whenever the referee box is closed, the complete state of the referee box is written to disk in a file called “referee.sav” (the filename can be changed with the SAVE directive in referee.conf, in the “files” section). In case the referee box crashes, or even a power failure brings down the entire computer, the state can be reloaded by adding the “-r” flag on the referee box command line. This always leaves the referee box in the halt state, for safety reasons; in the case of a timeout, the timeout resume button is available. This is also the only way to recover from accidentally pressing the end game button: post-game states are never saved to the recovery file, so closing the referee box and running it with “-r” will return it to the state it was in before ending the game.
Be careful: only one file is used (“referee.sav”), so if you run the referee box without “-r”, the recovery data from the previous run is gone forever!
If you need to do something extremely unorthodox, or you get into a very bad state and need to get out of it, you can use the Config / Ignore Rules option. This enables every single button in the referee box no matter what game state and stage are active. Many of the buttons will still not do anything, and some of them may do unexpected things, but this may be useful as a last resort—for example, all the game stage buttons are enabled, allowing you to go backwards in the stage progression if necessary (even using the first half button to go back to pre-game). The ignore rules command should almost certainly not be used during an official game, at least not without consulting an expert first, but it may be convenient for testing. In any case, it should be turned off as soon as possible once the job is done. Inappropriate use of the ignore rules command may seriously confuse the referee box and/or teams’ AIs.
The referee box ships with a scoreboard suitable for showing to spectators on an overhead projector or large TV, in the “scoreboard” directory, which you can compile separately. The scoreboard should be run from that directory, with the command “./scoreboard”. If your network interface is not named “eth0”, you will need to specify it on the scoreboard commandline, e.g. “./scoreboard -i eth1”. The scoreboard can be run on the same computer as the referee box or on another computer; its only input is the referee box packets on the network.
By default the scoreboard will show the name of a team in plain text, but if you add files to the “flags” or “logos” directory (or both), the team’s logo and/or national flag will be shown instead—there is no mapping database between team names and files; rather, the name of the file must be exactly the name of the team from the referee box plus the extension “.png”.
The scoreboard can be made full-screen by pressing F on the keyboard.